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

Installation
IRImagerDirect SDK Overview
Migration Guide
Changelog
Easy API

Easy and Expert API comparision

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)	❌	✅

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

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

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.

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.

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.