libirimager
IR Imager Direct-SDK
IRImagerDirect 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.

piimagers.png
optris PI imager series

Thermal images can be acquired in raw format for further processing. In order to obtain a human-interpretable representation, the SDK supports several conversion functions. With different coloring palettes the user can get a false color representation of his data takes. Some examples are depicted below.

household.png
Thermal image samples from a household environment

firescenes.png
Thermal image samples taken at a fire service drill

Getting started

Installation
IRImagerDirect SDK Overview
Migration Guide
Changelog
Easy API

Video format

The PI 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:

PI 160 (FW 2026..2199)PI 400/450 (FW 2438..2599)PI 640 (FW 2600..2799)
videoFormatIndexRaw formatImage formatRaw formatImage formatRaw formatImage format
0160x122@120Hz160x120@120Hz 382x290@27Hz382x288@27Hz 642x480@32Hz640x480@32Hz
1-- 384x288@80Hz382x288@80Hz --
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
videoFormatIndexFWRaw formatImage formatMin. TempMax. Temp
02800..2818385x289@27Hz382x288@27Hz4501800
2818..2999382x290@27Hz382x288@27Hz4501800
12800..2999384x288@80Hz382x288@80Hz5001800
22800..2999766x480@32Hz764x480@32Hz5001800
32800..281773x224@250Hz72x56@1000Hz6001800
2818..281974x224@250Hz72x56@1000Hz6001800
2820..299974x224@250Hz72x56@1000Hz6001800
42800..2999768x32@250Hz764x8@1000Hz6001800

For a PI 08M device, the format maps as follows. Important notice: The chosen temperature range is related to these image formats:

PI 08M
videoFormatIndexRaw formatImage formatMin. TempMax. Temp
0385x289@27Hz382x288@27Hz5751900
1384x288@80Hz382x288@80Hz6251900
2766x480@32Hz764x480@32Hz6251900
373x224@250Hz72x56@1000Hz7501900
4768x32@250Hz764x8@1000Hz7501900

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.

Temperature data format

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)data[i] / 10.f - 100.f;
    ...
}

<enable_high_precision>1</enable_high_precision> data format

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)data[i] / divisor - 100.f;
    ...
}

Industrial Process Interface (PIF)

The Direct SDK supports the PIF of Optris imagers. See pif/IRPifExample.cpp for an example code.

PIF snapshot triggering

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);

PIF flag control

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);

Calibration/Configuration

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>

Creating configuration files

Please use the included generic configuration file generic.xml as a template. Parameter meanings are documented in the file itself.

Basic interface usage

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.

sequencediagram_libirimager_win.png
Typical usage of SDK on Windows platforms
A C-style example is also available. The main difference is the usage of callback functions, instead of callback class methods.

Troubleshooting

  • Executing the examples via the console, requires to add the location of the libraries to the PATH-Variable, e.g. set PATH=%PATH%;..\..\sdk\x64, before executing ir_imager_show.exe ..\..\generic.xml.
  • In order to see where the problem in starting an application is, increase the debug level, e.g.:
    IRLogger::setVerbosity(IRLOG_DEBUG, IRLOG_OFF);
    at the beginning of your application.
  • Try temporary activation of nodrop option in uvcvideo: $ sudo rmmod uvcvideo; sudo modprobe uvcvideo nodrop=1
    See Installation

Frequently Asked Questions (FAQ)

Q: Can I convert RAVI files recorded with PI-Connect with the Direct-SDK to different Formats?
A: No, RAVI files are only used by PI-Connect. PI-Connect can import *.raw data files recorded with the Direct-SDK, not vice versa.

Q: Can I import data from my Direct-SDK based application to PI-Connect?
A: Yes, the class IRFileWriter supports a raw data format, that can be read by PI-Connect. The example serializeRaw.cpp shows the usage of this class.