Thermal Camera SDK 10.0.1
SDK for Optris Thermal Cameras
Loading...
Searching...
No Matches
Basic Usage

Contents

First Steps

The best way to get started with the SDK is to try out the precompiled Simple View example. Attach your camera via USB to your computer and navigate to the start/desktop menu entry of the Simple View application. Make sure you have internet access because the SDK may download calibration files from Optris servers.

Note
Connecting to an Ethernet device is not yet a one click experience. You can either first connect to the device via USB to auto generate its configuration file or use the one in the Important Files chapter and save in one of the search locations of the SDK. Adjust its settings as described in the Device Connection section and start the example with the device serial number as command line argument.

Once you click on it, two windows will open.

Display Window

The first window displays a live stream of false color images generated from the thermal data received from the camera.

False color imager stream.

The red cross-hair denotes the spot with the hottest and the blue one the spot with the coldest temperature within the frame. The corresponding temperatures in degree Celsius are shown right next to the cross-hairs. The white cross-hair is fixed in the center of the frame and its value represents the mean temperature in a small area around the spot it is pointing to.

The legend in the upper right corner features two FPS values. The one for Display refers to frame rate with which the content of the window is rendered. The FPS for Src relates to the frequency with which data frames are received from the camera.

Terminal Window

The second window is a terminal displaying the logging output of the SDK.

Terminal with SDK logging output (Windows).

The logging output of the SDK is quite extensive in this case because it was the first time that the camera PI 640 with the serial number 18052027 was used. Let us break the logs down to get a first glimpse at how the SDK operates.

Startup Process

Locate a Device

Since it was not specified to which camera the SDK should connect to it queried the EnumerationManager for a suitable device attached to the computer. It chose the one with the smallest serial number, in this case 18052027, and started the connection process.

Note
The EnumerationManager can currently only detect devices attached to the USB port.

This step can be skipped by providing the SDK with the serial number of the camera you want to connect to.

Load The Configuration

As the next step, the SDK tries to locate a configuration file specifying how to operate the camera. It contains settings detailing, amongst other things,

  • how to connect to the camera (USB, Ethernet, ...),
  • what video format and temperature range to use and
  • what radiation parameters (emissivity, transmissivity and ambient temperature) to apply.

Because the SDK was unable to find an appropriate configuration file it scheduled the creation of a new one. This does not happen right away since the SDK first gathers more information about the camera, like its device type and its supported video formats. Once completed it saves the new configuration file named <Serial Number>.xml to

  • <User AppData>\Roaming\Imager\Configs on Windows or to
  • ~/.config/optris/Configs on Linux.

This step can be skipped by providing the SDK with an IRImagerConfig instance.

Establish The Device Connection

At this point the SDK establishes two communication channels with the camera. One is used to send control commands to the device and the other is utilized for streaming the thermal data from the camera to the SDK.

For more details refer to the Device Communication chapter.

Load The Calibration

In order to provide precise temperature measurements the SDK has to locate and load the files containing the camera calibration. The calibration can consist out of up to three different file types:

  • A configuration file named Cali-<Serial Number>.xml detailing for which optics, temperature ranges and video formats calibrations are available.
  • Files named Cali-<Serial Number>-<...>.dat containing the calibration.
  • Files named Kennlinie-<Serial Number>-<...>.prn containing additional characteristic curves.

Because a new camera was used the required calibration files were not present on the system. The SDK determined the missing files and tried copy them from another location on the filesystem. Since the required source directory was not specified the attempt failed and the SDK moved on to download the files from Optris servers.

Note
You can adjust how the SDK tries to acquire missing calibration files with the help of the Sdk class. There you can prioritize the different possible sources or even deactivate the automated acquisition all together.
The SDK only acquires the calibration files needed to operate the camera with the current type of connection (USB, Ethernet). Changing the connection type may result in additional acquisition attempts with some device like the Xi 1M.

Determine The Operation Mode

Once it is clear which calibrations are available for the camera the SDK deduces the possible operation modes. An operation mode is defined by a valid combination of the following configuration options:

  • Optics, defined by its field of view and an optional text
  • Temperature Range, defined by its lower and upper non-extended limits
  • Video Format, defined by its frame rate and an optional text

The values in the configuration file are matched against the resulting modes to ensure that the desired settings are correct.

With the newly connected camera the SDK automatically chooses the first available optics, the first available temperature range and the first available video format respectively.

Startup Calibration

Now everything is set and the connection is established. The SDK receives thermal data from the device and begins the startup calibration. During this process the SDK clients already receive thermal frames but the contained temperature measurements are unreliable. Therefore, clients should wait until this calibration is finished before further processing the data.

Note
During the startup calibration the flag state is set to Initializing. You can get the flag state for each thermal through the corresponding FrameMetadata instance. Test, if it is not equal to Initializing to ensure the thermal data is valid.

Device Configuration

The device settings that the SDK should use are defined in a XML based configuration file. Some these settings can also be changed at runtime. Please refer to the API documentation of the IRImager interface for more details.

The following two sections describe the two most important configuration options. For more information about all the other available settings please refer to the documentation of the configuration file.

Device Connection

The SDK supports both USB and Ethernet connections. The relevant settings can be found in the configuration file between the <connection> tags:

<connection>
<interface>usb</interface>
<ip_address>192.168.0.101</ip_address>
<port>50101</port>
<check_ip>true</check_ip>
<timeout>10</timeout>
</connection>

First you have to define which connection interface to use: USB or Ethernet. Write your choice between the <interface> tags. The SDK ignores the case of the provided string. If you chose USB, you do not need to give any more details. In the case of Ethernet you have to specify at least the following additional settings:

  • The IP address of the device in dot notation in the <ip_address> tags.
  • The port number to which the device sends its data to in the <port> tags.
Attention
Make sure that the device IP address and the port number you set are the same that are configured on the device. You can either use the command line tool otc_configure_ethernet or the PixConnect to review and change this on-device configuration.

Furthermore, you can instruct the SDK to check whether the sender IP address of received data packages equals the one set in the <ip_address> tags. If the IP addresses do not match, the data package will be discarded. Set <check_ip> to true to active this check or to false to deactivate it.

Finally, you can specify a connection timeout in seconds in the <timeout> tags. If the SDK does not receive data packages for more than the set amount of time, it will trigger the onConnectionTimeout() callback of the IRImagerClient class.

Note
Connection timeouts are the only way to detect connection losses with Ethernet devices because the callback onConnectionLoss() is only available for USB connections.

For more insights into the communication of the SDK with the device please refer to the chapter Device Communication.

Optics, Temperature Ranges, Video Formats

The configuration settings for optics, temperature ranges and video formats are dependent on each other. There is only a limited number of valid combinations that are defined by

  • the calibration configuration that specifies for which combinations calibrations exist and
  • the chosen connection type (USB, Ethernet, ...) since it dictates which video formats are available.

Consult the Support Cameras section in the Features chapter to get a list of the available video formats and temperature ranges for each supported device type.

Optics

The currently used camera optics are specified by two data points: The <field_of_view> of the optics in degree and an optional <text> further defining the optics.

<optics>
<field_of_view>30</field_of_view>
<text></text>
</optics>

If you set <field_of_view> to 0 and leave the <text> blank, the SDK will automatically choose the first optics specified in the calibration configuration.

Temperature Ranges

The temperature range is defined by its non-extended <min> and <max> temperatures in degree Celsius.

<temperature_range>
<min>-20</min>
<max>100</max>
<extended>false</extended>
<enable_high_precision>true</enable_high_precision>
</temperature_range>

If <min> and <max> are set to 0, the SDK will automatically select the first available temperature range of the optics defined in the calibration configuration.

For some devices the temperature range can be extended by setting the option <extended> to true. This can be helpful to align the field of view of the camera when using temperature ranges with high lower limits.

Attention
Extended temperature ranges are intended to improve the handling of the camera and are not suitable for measurement tasks. They feature a poorer precision that lies outside of the specifications of the camera.

Some devices can make temperature measurements with a higher precision for selected temperature ranges. If you set <enable_high_precision> to true, this higher precision will be automatically used if it is available. Set it to false, if you just want to use the standard precision throughout.

Video Formats

The video format is specified by the frame dimensions <width> and <height> in pixels and by its <framerate> in Hz. Consult the Supported Cameras section in the Features chapter for exhaustive lists detailing what formats are available for each device type.

<video_format>
<width>382</width>
<height>288</height>
<framerate>27</framerate>
<subsampled_framerate></subsampled_framerate>
</video_format>

If <width>, <height> and <framerate> are all set to 0, the SDK will choose the first available video format.

Attention
The availability of the different video formats depends on the used connection type (USB, Ethernet).

You can instruct the SDK to reduce the framerate by setting a <subsample_framerate> that is equal or less than the device <framerate>. This setting adjusts the rate with which IRImagerClients receive thermal frame callbacks but does not alter the framerate of the device itself.

Attention
The <subsampled_framerate> setting does not affect the rate with which the device publishes frames as specified by <framerate>. In fact the SDK has no way to manipulate the device framerate besides choosing a different video format.

Command Line Tools

The SDK comes with a set of command line tools that allow you to configure the on-device Ethernet settings, find devices on the USB port and print SDK version and build information.

otc_configure_ethernet

This tool allows you to configure the on-device Ethernet settings of cameras that offer Ethernet connectivity. Attach your camera via USB to your computer and run the following command in the terminal (Linux) or in the PowerShell (Windows):

Windows

otc_configure_ethernet.exe

Linux

otc_configure_ethernet

You will be prompted for the serial number of the device whose Ethernet settings you want to change. After you hit Enter the tool connects to the camera and displays the current configuration.

Changing Ethernet on device settings.

If successful, you can now enter the new device IP address, the IP address and port to which the device should send its data (destination) to and the subnet mask of the network. Provide the IP addresses and the subnet mask in dot notation.

You can leave the tool at any time with the help of Ctrl + C.

Once you entered all the required information the tool applies the settings to the device. Then it fetches the settings again and displays them so that you can verify that everything was configured correctly.

otc_find_devices

This tool displays all devices that are currently connected to the computer via USB and allows you to monitor connection events.

Windows

otc_find_devices.exe

Linux

otc_find_devices

First all currently connected devices are displayed. Then you will be asked whether you want to monitor device connection events. Type y to do so or n to quit.

Finding devices.

You can leave the tool at any time with Ctrl + C.

otc_version

This tool just displays basic version and build information about the SDK.

Windows

otc_version.exe

Linux

otc_version
Version and build information.