 |
libirimager
IR Imager Direct-SDK
|
|
|
libirimager
IR Imager Direct-SDK
|
|
The PI imager library is available as Debian package or Windows SDK. It contains a C-style interface and an object-oriented C++-interface for acquiring data from the optris PI imager series.
| Function | Easy API | Expert API |
|---|---|---|
| Programming Style | Simple Function Calls | Object Orientated |
| Programming Language | C, C++, C#, Matlab, Labview, Python and every other with C-Library Support | C++ |
| Thermal Image | ✅ | ✅ |
| Palette Image | ✅ | ✅ |
| Change Palette Color | ✅ | ✅ |
| Change Palette Scale | ✅ | ✅ |
| Change Palette Temperature Range | ✅(since v8.0) | ✅ |
| Set Focus Motor Position | ✅ | ✅ |
| High Precision Mode (PI450) | ✅ | ✅ |
| Extended Temperatur Range | ✅ | ✅ |
| RAW Data Recording for PIX-Connect | ❌ | ✅ |
| Access to visible frame (PI230) | ❌ | ✅ |
| Multiple Cameras | ✅(since v8.0) | ✅ |
| PIF I/O Support | ❌ | ✅ |
| Detect Connection Loss | ❌ | ✅ |
| Flagcontrol during Runtime | ✅(since v8.0) | ✅ |
| Create Optris Tiff Files | ❌ | ✅ |
| Temperature referencing with external probe (BR 20AR) | ❌ | ✅ |
The PI and XI imagers provide different video formats. Depending on the camera model, the user can choose different resolutions and frame rates respectively by specifying the so called "videoFormatIndex" (see structure IRDeviceParams and section Generating configuration files). For instance, the parameter chooses specific formats for the following devices:
| XI 80 (FW 3400..3599) | XI 400 (FW 3400..3599) | XI 410 (FW 3800..3999) | ||||
|---|---|---|---|---|---|---|
| videoFormatIndex | Raw format | Image format | Raw format | Image format | Raw format | Image format |
| 0 | 80x82@8Hz | 80x@8Hz | 382x290@27Hz | 382x288@27Hz | 384x288@80Hz | 382x288@80Hz |
| 1 | - | - | - | - | - | - |
| 2 | - | - | - | - | - | - |
| 3 | - | - | - | - | - | - |
| 4 | - | - | - | - | - | - |
| PI 160 (FW 2026..2199) | PI 400/450 (FW 2438..2599) | PI 640 (FW 2600..2799) | ||||
|---|---|---|---|---|---|---|
| videoFormatIndex | Raw format | Image format | Raw format | Image format | Raw format | Image format |
| 0 | 160x122@120Hz | 160x120@120Hz | 382x290@27Hz | 382x288@27Hz | 642x480@32Hz | 640x480@32Hz |
| 1 | - | - | 384x288@80Hz | 382x288@80Hz | 642x120@125Hz | 640x120@125Hz |
| 2 | - | - | - | - | - | - |
| 3 | - | - | - | - | - | - |
| 4 | - | - | - | - | - | - |
For a PI 1M device, the format maps as follows. Important notice: The chosen temperature range is related to these image formats:
| PI 1M | |||||
|---|---|---|---|---|---|
| videoFormatIndex | FW | Raw format | Image format | Min. Temp | Max. Temp |
| 0 | 2800..2818 | 385x289@27Hz | 382x288@27Hz | 450 | 1800 |
| 2818..2999 | 382x290@27Hz | 382x288@27Hz | 450 | 1800 | |
| 1 | 2800..2999 | 384x288@80Hz | 382x288@80Hz | 500 | 1800 |
| 2 | 2800..2999 | 766x480@32Hz | 764x480@32Hz | 500 | 1800 |
| 3 | 2800..2817 | 73x224@250Hz | 72x56@1000Hz | 600 | 1800 |
| 2818..2819 | 74x224@250Hz | 72x56@1000Hz | 600 | 1800 | |
| 2820..2999 | 74x224@250Hz | 72x56@1000Hz | 600 | 1800 | |
| 4 | 2800..2999 | 768x32@250Hz | 764x8@1000Hz | 600 | 1800 |
For a PI 05M device, the format maps as follows. Important notice: The chosen temperature range is related to these image formats:
| PI 05M | ||||
|---|---|---|---|---|
| videoFormatIndex | Raw format | Image format | Min. Temp | Max. Temp |
| 0 | 385x289@27Hz | 382x288@27Hz | 900 | 2450 |
| 1 | 384x288@80Hz | 382x288@80Hz | 950 | 2450 |
| 2 | 766x480@32Hz | 764x480@32Hz | 950 | 2450 |
| 3 | 73x224@250Hz | 72x56@1000Hz | 1100 | 2450 |
| 4 | 768x32@250Hz | 764x8@1000Hz | 1100 | 2450 |
For a PI 08M device, the format maps as follows. Important notice: The chosen temperature range is related to these image formats:
| PI 08M | ||||
|---|---|---|---|---|
| videoFormatIndex | Raw format | Image format | Min. Temp | Max. Temp |
| 0 | 385x289@27Hz | 382x288@27Hz | 575 | 1900 |
| 1 | 384x288@80Hz | 382x288@80Hz | 625 | 1900 |
| 2 | 766x480@32Hz | 764x480@32Hz | 625 | 1900 |
| 3 | 73x224@250Hz | 72x56@1000Hz | 750 | 1900 |
| 4 | 768x32@250Hz | 764x8@1000Hz | 750 | 1900 |
The user should check available video formats with a standard camera application, e.g., guvcview and valid temperature parameters by examining the provide calibration files.
The callback methods are using an unsigned short data representation for temperatures. In order to get temperature values in floating point format, the following conversion needs to be applied:
void onThermalFrame(unsigned short* thermal, unsigned int w, unsigned int h, IRFrameMetadata meta, void* arg)
{
...
float t = (float)thermal[i] / 10.f - 100.f;
...
}
If high percision mode is activated (enable_high_precision=1 in config.xml), the data representation depends on the supported decimal places of the thermal camera. The supported decimal places can be retrieved by the evo::IRImager::getTemprangeDecimal() method of the IRImager.h.
void onThermalFrame(unsigned short* thermal, unsigned int w, unsigned int h, IRFrameMetadata meta, void* arg)
{
...
short decimalPlaces = _irImager.getTemprangeDecimal();
float divisor = std::pow(10, decimalPlaces);
float t = (float)thermal[i] / divisor - 100.f;
...
}
The Direct SDK supports the PIF of Optris imagers. See pif/IRPifExample.cpp for an example code.
In order to receive images at rising edge events of the PIF digital input, the user needs to register a callback function via the IRImager class instance:
void IRImager::setThermalFrameEventCallback(fptrIRThermalFrame callback)
for thermal images and
void IRImager::setVisibleFrameEventCallback(fptrIRVisibleFrame callback)
for RGB images of cameras supporting bispectral technology.
Alternatively, one can use the object oriented interface by deriving the class IRImagerClient. For more information see the provided examples.
The following code enables snapshot triggering:
//Get initialized pif config
IRPifConfig pifConfig = imager.getPifConfig();
if(pifConfig.ChannelsDI.size() > 0)
{
pifConfig.ChannelsDI[0].Mode = IRChannelInputMode::SnapshotOnEdge; //Trigger only on edge
pifConfig.ChannelsDI[0].IsLowActive = false; //Trigger on rising edge
}
//Set pif config for apply new configuration
imager.setPifConfig(pifConfig);
The automatic flag control can be deactivated (<autoflag> tag in the xml configuration file). Flag cycles can be triggered manually by the PIF input:
//Get initialized pif config
IRPifConfig pifConfig = imager.getPifConfig();
if(pifConfig.ChannelsDI.size() > 0)
{
pifConfig.ChannelsDI[0].IsLowActive = true; //Invert, to close flag on true
pifConfig.FlagOpenInputChannel = pifConfig.ChannelsDI[0]; //Set which channel controls flag
}
//Set pif config for apply new configuration
imager.setPifConfig(pifConfig);
To improve the specified camera accuracy of the PI 450i T010 camera a reference source with a high emissivity and a stable and known temperature must be positioned in the scene proximate to the subject to be scanned. The BR 20AR Ambient referencing source is equipped with a temperature probe with +/- 0.1 °C accuracy.
To access the temperature values of the BR 20AR the configuration parameter <use_external_probe> must be set to 1. The temperature value will then be written to the first pif analog input channel in °C.
See "externalProbe/IRExternalProbe.cpp" on linux or "examples\\directshow\\irExternalProbe.cpp" on windows for an example code.
It is mandatory that the formats file (Formats.def) and the calibration files for the specific device can be found by the library. The optris PI imagers are shipped with a data storage medium containing those files. Please copy them to the desired directory or import them by using the PI connect software. The default folder for the calibration files is C:\Users\<myname>\AppData\Roaming\Imager. formats.def is found in the PI Connect installation folder. A custom directory can be configured with the IRDeviceParams structure. The structure can also be populated with data through the IRDeviceParamsReader interface via an XML file. Add the following tags in the configuration XML file:
<calipath>C:\YOUR\SPECIFIC\PATH\TO\CALIBRATION\FILES</calipath>
<formatspath>C:\YOUR\SPECIFIC\PATH\TO\FORMATS\DEF</formatspath>
Please use the included generic configuration file generic.xml as a template. Parameter meanings are documented in the file itself.
Typically, a DirectShow graph is used to acquire raw data. The user can employ an own implementation or use the library-contained IRDeviceDS class. After calling the blocking run method, the class instance will call a callback function/method frequently as soon as data is available. This data is to be passed to the process method of an IRImager instance. It uses itself the callback functions/methods onThermalData, onVisibleFrame and onFlagStateChange to pass converted data to the user. The following sequence diagram documents this typical usage.
1.8.13