Calibration File Acquisition

Contents

• Overview
• Sources
  • Device
  • Filesystem
  • Internet
• Configuration
  • Calibration File Sources
  • Calibration File Source Directory
• Runtime Behavior
  • Device
  • Filesystem
  • Internet

Overview

While connecting to a device the SDK tries to locate its calibration. As explained in the corresponding section in the important files chapter the calibration is comprised of a set of different files. They tell the SDK, amongst other things,

• for what optics and temperature ranges calibrations exists and
• how to convert the raw device data into proper readings

If the SDK fails to find the full set of calibration files in one of their usual storage locations, it will probe up to three different sources from which it could acquire them. Clients can configure which sources should be tried and in what order through the static Sdk class.

Note

Some calibrations are tied to specific video formats. The available video formats depend on the connection interface (USB, Ethernet). As a result, the SDK only acquires the calibrations for the video formats that are supported by the current connection interface.

If none of these sources yielded the full set, the SDK nonetheless concludes the connection process. In this case an IRImagerClient will be able to receive frame data via the onFrame() and onRawFrame()callbacks:

• The raw frame in the RawFrameEvent holds valid data but many data points in the metadata may be faulty. This especially applies to the internal probe temperatures for box, flag and chip and the read PIF input values.
• The thermal frame in the FrameEvent only holds invalid temperatures because the SDK can not convert the raw frame data into valid temperatures without the calibration. The metadata has the same restrictions as in onRawFrame().
• Configured measurement fields are ignored.

False color images for a PI 640I without a calibration.

Additionally, the deduction of available operations modes is affected. The resulting operation modes are only derived from the supported video formats and feature invalid values for the field of view (0) and the temperature range limits (-100).

Operation modes of a PI 640I without a calibration.

The behavior of the calibration file acquisition can be adjusted statically through the Sdk class for all IRImager instances of the current process or dynamically for a specific IRImager instance during the connection process via the IRImagerClient::onConnection() callback.

Sources

The SDK is able to probe the following three different sources in search of a full set of calibration files. This happens automatically during the connection process.

Device

Supported by Xi 80, Xi 320 MT and Xi 410

The devices listed above have their calibrations stored in their on-device memory. The SDK is able to download them to the user data directory for use by all local SDK clients.

Note

The calibration file download from Xi 320 MTs and Xi 410s may take a moment.

This source is automatically skipped for devices that do not support it.

Filesystem

The SDK is capable of recursively searching a directory on the filesystem for missing calibration files. To make this happen, clients first need to specify the path to be searched via the Sdk class. By default this path is empty and the SDK will skip this source because of it.

The SDK copies found calibration files to the user data directory for the subsequent use by all local SDK clients.

Internet

Lastly, the SDK can download the calibration files from Optris servers.

Note

Internet access is required for this to work. If access is not granted, the SDK will skip this source.

Before the actual calibration file download the SDK acquires a XML file from Optris.com that details all available download servers. It then probes all listed servers for the missing calibration files.

Configuration

The static Sdk class exposes three methods that can be used to configure the behavior of the automatic calibrations file acquisition for all IRImager instances of that process.

Calibration File Sources

With the Sdk::setCalibrationFileSources() method you can specify which source should be probed in what order. The sources are represented by the enum CalibrationFileSource. If you call this method in C++ like this

Sdk::setCalibrationFileSources(CalibrationFileSource::Empty, 
                               CalibrationFileSource::Device, 
                               CalibrationFileSource::Filesystem);

the SDK will try the sources from top to bottom in search of missing calibration files:

1. Empty - This enum value indicates that the slot with the highest priority is empty. The SDK ignores it and moves to the second source.

   Note

   Setting all three parameters to Empty will result in a SDKException.

2. Device - The SDK tries to download the calibration files from the on-device memory. If this fails or if this is not supported by the device, the SDK will move on to the last source.
3. Filesystem - The SDK searches the set calibration file source directory for the missing files. If this fails or if a calibration file source directory is not set, the overall acquisition will fail and the SDK will connect to the device without a calibration with the limitations described in the overview section.

Note

The default configuration defines the following priority of calibration files sources:

1. Device
2. Filesystem
3. Internet

Calibration File Source Directory

Via the Sdk::setCalibrationFileSourceDirectory() you can specify the directory in which the Filesystem source searches for missing calibration files.

Note

This should not be confused with the directories that the SDK searches for acquired calibration files as listed in the SDK Search Hierarchy. Only if the files were not found in those directories, the SDK starts probing the calibration files sources and potentially the set calibration file source directory.

In C++ you can set the directory as follows:

Sdk::setCalibrationFileSourceDirectory("~/calibrations");

When specifying the directory path the following symbols/variables are supported:

• ~, %USERPROFILE% refer to ~/ on Linux and <User Home>/ on Windows.
• %APPDATA% refers to ~/.config/ on Linux and <User AppData>/Roaming/ on Windows.

Relative paths are not supported. You can either use / as system independent directory separator or utilize system dependent ones like / for Linux and \ on Windows.

Note

The SDK requires permissions to access and to read this directory and its sub-directories.

If the specified path does not exist or if it is not a directory a SDKException is thrown.

A set calibration file source directory can be cleared via the Sdk::clearCalibrationFileDirectory() method.

Note

By default the calibration file directory is empty because the SDK can not guarantee its existence and the required access rights.

Runtime Behavior

When initiating a connection through one of the IRImager::connect() methods, the SDK will update registered IRImagerClients about the connection processes via the callback onConnection(). The state field in the provided ConnectionEvent indicates the current stage of this process.

Right after calling connect() the state Connecting is sent to the clients. At this stage the SDK gathers all necessary information to establish the device connection. This includes locating the required calibration files. If they are present, the SDK will proceed and ultimately send the state Connected on success or Failed on failure.

If it needs to acquire missing calibration files, it will probe the sources in the configured sequence. Depending on the currently tried source the SDK publishes different ConnectionStates:

Device

The state CaliDeviceDownload is sent to indicate that the SDK is trying to download the calibration files from the device. If successful, the state will transition to CaliAcquired. Otherwise, the state will either move to CaliMissing, if it is the last source to be probed or the SDK moves on to the next specified source.

Filesystem

Firstly, the state CaliCopy is published before the SDK searches the configured calibration file source directory. If this fails or if no directory is set, the SDK will send the state CaliCopySourceDirectory. In this case clients can now provide an alternative source directory to be searched by setting the sourceDirectory field of the ConnectionEvent. If an empty string (default) is provided, this step is skipped. On a successful acquisition the ConnectionState moves on to the CaliAcquired state. Otherwise, the state will either transition to CaliMissing, if it is the last source or the SDK tries the next configured source.

Internet

Before accessing the Internet the SDK prompts the client for permission by sending a ConnectionEvent with the state CaliAccessInternet. The client can grant (default) or deny access by setting the boolean field accessInternet of the event object. If denied, the SDK tries the next source or publishes CaliMissing, if it was the last configured source. If granted, the SDK sends CaliInternetDownload and begins the download process. On success the state moves to CaliAcquired. On failure the SDK either tries the next source or publishes CaliMissing, if no more sources are available.