Version 9.0.0
 
Loading...
Searching...
No Matches
Overview

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

Set <tchipmode> to avoide temperature drifting

This table provides the recommended settings for tchipmode by camera model. This can be configured in the .xml file. The tchipmode setting options are:

  • 0: Floating (default)
  • 1: Auto
  • 2: Fixed value
CameraRecommended tchipmode
Xi800
Xi4000
Xi4100
X410MT0
Xi1M1
Pi1600
Pi640i G71
Pi450i G71
Pi400i0
Pi450i0
Pi640i0
Pi1M1
Pi08M1
Pi05M1

Video format

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 3016..3199)XI 400 (FW 3400..3599)
videoFormatIndexRaw formatImage formatRaw formatImage format
080x82@50Hz80x80@50Hz 382x290@27Hz382x288@27Hz
180x82@8.33Hz80x80@8.33 382x288@80Hz382x288@80Hz



XI 410 USB (FW 3800..3999)XI 410 Ethernet (FW 3800..3999)
videoFormatIndexRaw formatImage formatRaw formatImage format
0384x242@4.1Hz384x240@4.1Hz384x242@25Hz384x240@25Hz
180x82@8.33Hz80x80@8.33 382x288@80Hz382x288@80Hz



XI 410MT USB (FW 3800..3999)XI 410MT Ethernet (FW 3800..3999)
videoFormatIndexRaw formatImage formatRaw formatImage format
0384x242@4.1Hz384x240@4.1Hz384x242@25Hz384x240@25Hz
180x82@8.33Hz80x80@8.33 382x288@80Hz382x288@80Hz



XI 1M USB (FW 4000..4199)XI 1M Ethernet (FW 4000..4199)
videoFormatIndexRaw formatImage formatRaw formatImage format
0132x102@20Hz132x100@20Hz396x302@20Hz396x300@20Hz



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

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 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
0385x289@27Hz382x288@27Hz9002450
1384x288@80Hz382x288@80Hz9502450
2766x480@32Hz764x480@32Hz9502450
373x224@250Hz72x56@1000Hz11002450
4768x32@250Hz764x8@1000Hz11002450

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.

Configuration File (XML)

<formatspath>/opt/piimager</formatspath> <– The Folder contains the Formats.def file (raw camera formats)
<imager xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<serial>YOURSERIAL</serial> <– Provide serial number, if you attach more than one camera
 <videoformatindex>0</videoformatindex> <– Index of the used video format(USB enpoint) – Link to the Video Formats
 <calipath>/usr/share/libirimager/cali</calipath> <– Contains the configuration file (.XML)
 <fov>33</fov> <– Field of View
 <temperature> <– Temperature range the camera is supposed to locate
  <min>-20</min>
  <max>100</max>
 </temperature>
 <optics_text></optics_text>
 <framerate>32.0</framerate> <– Framerate must be less or equal to the Camera framerate
 <outputmode>2</outputmode> <– 1=Energy, 2=Temperature
 <bispectral>0</bispectral> <– 0=only thermal sensor, 1=bispectral technology (only PI200/PI230)
 <autoflag>
  <enable>1</enable>
  <mininterval>15.0</mininterval>
  <maxinterval>0.0</maxinterval>
 </autoflag>
 <tchipmode>0</tchipmode> <– 0=Floating (default), 1=Auto, 2=Fixed value -->
 <tchipfixedvalue>40.0</tchipfixedvalue> <– Fixed value for tchipmode=2 -->
 <focus>-1</focus>
 <buffer_queue_size>5</buffer_queue_size> <– internal buffer queue size -->
 <enable_high_precision>0</enable_high_precision> <– 0=Off, 1=On; Enables temperatures with more than 1 decimal places. Depends on used camera(IRImager::getTemprangeDecimal()).-->
 <radial_distortion_correction>0</radial_distortion_correction>
 <use_external_probe>0</use_external_probe> <– 0=Off, 1=On; Temperatures values of external probe BR20AR are accessible on PIFs first analog input in °C-->
</imager>

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.

Library overview

A class diagram of the most important library classes is depicted below.

Library class overview
  • IRDeviceUVCr and IRDeviceDS are acquisition classes for raw data streams under Linux (UVC) and Windows (DS==DirectShow).
  • IRDeviceParamsReader is a helper class and parses a configuration file in order to create an IRDeviceParams structure instance. This structure can also be instantiated and populated with parameters manually.
  • SimpleXML is a lightweight XML parser and used by the IRDeviceParamsReader class internally. The user might also employ it for reading application specific XML files.
  • IRCalibrationManager may be used to download or copy calibration files with the user's own program. Currently, there is no full support for the Windows operation system.
  • IRImager is the main class and is used for processing raw data and controlling the PI imager device.
  • IRImagerClient is an abstract class that enables object oriented interfacing of PI imagers. The library uses callback methods to inform the user of the availability of thermal or RGB data. IRImager either accepts pointers to C-style callback functions or a pointer to an inherited class instance of IRImagerClient .
  • IRFrameMetadata is a meta data container delivered by the PI imager within its raw data stream. It contains timestamp and internal state parameters.
  • ImageBuilder can be used to convert temperature data to a displayable format.
  • FramerateCounter states a helper class for calculating the frame rate of a loop. In the examples it is used to calculate the loop rate of a grabbing thread and a display thread.

It is recommended to keep the callback functions/methods lightweight in order to guarantee a high framerate of process method calls. Some of the provided examples show how to copy data in a queue within the callback functions. A worker thread is subsequently informed to do further processing

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;
    ...
}

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.

<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;
    ...
}

Connect the Xi80/Xi410 through Ethernet

Enable Ethernet Connection
  • Enable the "Enable Ethernet" option under the "Devices" tab, in the PIX CONNECT.
  • Once done, the "Ethernet settings (TCP/IP)..." option will be available
    Configure ethernet settings
  • Connect the desired Camera via USB, to configure it, through the PIX CONNECT.
  • From the PIX CONNECT TCP/IP settings window, the values in the red frame need to be set in the config (.xml) file, too.
  • To use the ethernet connection instead of the usb connection, the <device_api> value needs to be set to 5 instead of 0.
  • In addition to the above, the following values need also to be set accordingly (in the .xml file) to the below example:


  <device_api>5</device_api>
  <ethernet_device>
   <device_ip_address>192.168.0.11</device_ip_address>
   <local_udp_port>50011</local_udp_port>
   <check_udp_sender_ip>1</check_udp_sender_ip>
  </ethernet_device>

Important:

  • Issues may arise if the connection is handled via DHCP. To solve this, configure the address of the local computer manually, changing it to the address which was set in the PIX-Connect in "Send to address (local computer)".
  • Even if the port, which the camera sends UDP packages to, is greenlighted by your Firewall, you still might encounter issues, if your OWN software is not greenlit. To solve this, also add an exception in your firewall, for your own software.

Library overview

A class diagram of the most important library classes is depicted below.

Library class overview
  • IRDeviceUVCr and IRDeviceDS are acquisition classes for raw data streams under Linux (UVC) and Windows (DS==DirectShow).
  • IRDeviceParamsReader is a helper class and parses a configuration file in order to create an IRDeviceParams structure instance. This structure can also be instantiated and populated with parameters manually.
  • SimpleXML is a lightweight XML parser and used by the IRDeviceParamsReader class internally. The user might also employ it for reading application specific XML files.
  • IRCalibrationManager may be used to download or copy calibration files with the user's own program. Currently, there is no full support for the Windows operation system.
  • IRImager is the main class and is used for processing raw data and controlling the PI imager device.
  • IRImagerClient is an abstract class that enables object oriented interfacing of PI imagers. The library uses callback methods to inform the user of the availability of thermal or RGB data. IRImager either accepts pointers to C-style callback functions or a pointer to an inherited class instance of IRImagerClient.
  • IRFrameMetadata is a meta data container delivered by the PI imager within its raw data stream. It contains timestamp and internal state parameters.
  • ImageBuilder can be used to convert temperature data to a displayable format.
  • FramerateCounter states a helper class for calculating the frame rate of a loop. In the examples it is used to calculate the loop rate of a grabbing thread and a display thread.

It is recommended to keep the callback functions/methods lightweight in order to guarantee a high framerate of process method calls. Some of the provided examples show how to copy data in a queue within the callback functions. A worker thread is subsequently informed to do further processing. Please see the next two sections about example applications to start your development.