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.

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.

Thermal image samples from a household environment

Thermal image samples taken at a fire service drill

Getting started

IRImagerDirect SDK Overview
Migration Guide
Easy API

Easy and Expert API comparision

FunctionEasy APIExpert API
Programming StyleSimple Function CallsObject Orientated
Programming LanguageC, C++, C#, Matlab, Labview, Python
and every other with C-Library Support
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)

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 642x120@125Hz640x120@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:

videoFormatIndexFWRaw formatImage formatMin. TempMax. Temp

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

PI 05M
videoFormatIndexRaw formatImage formatMin. TempMax. Temp

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

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)thermal[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)thermal[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

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

External Probe (BR 20AR)

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:

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.

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.