Configuration

The configuration file defines the device specific settings for the camera and optionally attached processing interfaces.

File Name

<Serial Number>.xml

How To Get It

The configuration file is automatically generated by the SDK when connecting to a new camera. The file is placed in the user settings directory

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

SDK Search Hierarchy

Working directory of the application.
User settings directory
- <User AppData>\Roaming\Imager\Configs on Windows
- ~/.config/optris/Configs on Linux

The configuration is split into several sections for clarity. These sections should be included between the <imager> tags in the XML configuration file in the sequence they are discussed here.

<?xml version="1.0" encoding="UTF-8"?>
 
<imager>
  <!-- Insert configuration sections here -->
</imager>

Version

<version>
  <configuration>2</configuration>
  <sdk>10.0.0</sdk>
</version>

configuration

Type	Constraint	Default	Required	Availability
int	> 0	-	yes	>= v1

Configuration file version. Its value is used by the SDK to determine how to parse the configuration file.

sdk

Type	Constraint	Default	Required	Availability
string	-	-	no	>= v1

Version of the SDK that generated the configuration file. Currently, not parsed by the SDK.

Serial Number

<serial_number>1234567</serial_number>

serial_number

Type	Constraint	Default	Required	Availability
int	> 0	0	yes	>= v1

The serial number identifies the device the configuration file applies to. The cameras typically have a sticker with their serial number on it. Sometimes it also features the serial number of the optics.

Connection

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

interface

Type	Constraint	Default	Required	Availability	Remarks
string		usb	yes	>= v1	case insensitive

Defines the connection interface that the SDK should use to communicate with the device. Natively, the SDK supports the following interfaces:

usb
ethernet (respectively network connection)

For more details about the the communication between the SDK and the device please refer to the chapter Device Communication.

Attention: When using the ethernet interface the settings for the IP address and the port should align with the ones set on the device with the help of the PixConnect or the otc_configure_ethernet commandline tool.

ip_address

Type	Constraint	Default	Required	Availability
string	IP v4 address in dot notation	192.168.0.101	no	>= v1

When using the ethernet interface the IP address refers to the IP v4 address of the device.

port

Type	Constraint	Default	Required	Availability
int	>= 0	50101	no	>= v1

In case of the ethernet interface this option refers to the local port on which the SDK can receive the frame data from the device.

check_ip

Type	Constraint	Default	Required	Availability
bool	-	true	no	>= v1

If set to true, the SDK will only accept and process data packages from the IP address specified above.

timeout

Type	Constraint	Default	Unit	Required	Availability
int	>= 0	10	seconds	no	>= v1

Specifies the the time in seconds until a device connection is considered to have timed out because no frame data was being received. When a timeout occurs the SDK will trigger the onConnectionTimeout() callback of the IRImagerClients.

Buffer Queue Size

<buffer_queue_size>5</buffer_queue_size>

buffer_queue_size

Type	Constraint	Default	Required	Availability
int	> 0	5	no	>= v1

Specifies the number of buffers to be used by the SDK to receive frame data. This option does not affect the actual size the individual buffers.

Optics

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

field_of_view

Type	Constraint	Default	Unit	Required	Availability
int	>= 0	0	degrees	no	>= v1

Identifies the optics used by the device via their field of view in degrees.

text

Type	Constraint	Default	Required	Availability
string	-		no	>= v1

Sometimes specifying the field of view is not enough to unambiguously identify the optics. In such a case an additional text is used to differentiate between them.

Note: If the field of view is set to 0 and the text is left blank, the SDK will automatically choose the first optics specified in the calibrations.

Temperature Range

<temperature_range>
  <min>150</min>
  <max>900</max>
 
  <extended>false</extended>
  <enable_high_precision>true</enable_high_precision>
</temperature_range>

min

Type	Constraint	Default	Unit	Required	Availability
int	-	0	degree Celsius	no	>= v1

Defines the non-extended lower limit of the temperature range in degree Celsius.

max

Type	Constraint	Default	Unit	Required	Availability
int	-	0	degree Celsius	no	>= v1

Defines the non-extended upper limit of the temperature range in degree Celsius.

Note: If min and max are set to 0, the SDK will automatically choose the first temperature range defined in the calibrations that is available for the configured optics.

Please refer to the Supported Camera section to get a list of all the available temperature ranges for the different devices.

extended

Type	Constraint	Default	Required	Availability
bool	-	false	no	>= v1

Some temperature ranges can be extended beyond the limits specified with min and max. If set to true, this extension will be enabled when available.

Attention: Extended temperature ranges feature poor precision and should not be used for measurements. The main purpose of this feature is to give users an easier time to physically align the field of view of the device when a temperature range has a high lower limit.

enable_high_precision

Type	Constraint	Default	Required	Availability
bool	-	true	no	>= v1

Some temperature ranges for some devices feature a higher temperature measurement precision. If set to true, the SDK will automatically use the higher precision when available.

Video Format

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

width

Type	Constraint	Default	Unit	Required	Availability
int	>= 0	0	pixel	no	>= v1

Specifies the width of the output thermal frame in pixels.

height

Type	Constraint	Default	Unit	Required	Availability
int	>= 0	0	pixel	no	>= v1

Defines the height of the output thermal frame in pixels.

framerate

Type	Constraint	Default	Unit	Required	Availability
int	>= 0	0	Hz	no	>= v1

Specifies the framerate in Hz with with which the device provides the thermal frames.

Note: If width, height and framerate are all set to 0, the SDK will automatically choose the first video format that is available for the configured optics and temperature range.

Please refer to the Supported Camera section to get a list of all the available video formats for the different devices.

Note: The availability of a video format depends on the used optics, the configured connection interface and the configured temperature range.

subsampled_framerate

Type	Constraint	Default	Unit	Required	Availability
float	-	-1.	Hz	no	>= v1

Sets the rate in Hz to which the SDK should limit the output of thermal frames. This option does not affect the rate which the device provides frame data. This rate is set by the firmware of the device and can not be changed by the SDK.

Leave it blank or set it to a negative value to deactivate this option.

Auto Flag

All devices feature an internal shutter flag that can completely block the field of view of the sensor chip. It has to be closed periodically to enable the SDK to compensate for drifting temperature measurements.

The SDK uses readings of internal temperature probes of the device to determine when to start a flag cycle by closing the shutter flag. During this cycle the SDK updates the temperature drift compensation.

Note: If the processing interface is used to control the flag, these settings will have no effect.

<auto_flag>
  <enable>true</enable>
 
  <min_interval>12</min_interval>
  <max_interval>0</max_interval>
</auto_flag>

enable

Type	Constraint	Default	Required	Availability
bool	-	true	no	>= v1

If set to true, the flag will automatically be controlled by the SDK.

min_interval

Type	Constraint	Default	Unit	Required	Availability
float	>= 0.	12.	seconds	no	>= v1

Defines the minimum amount of time in seconds that has to pass after a completed flag cycle before a new one can be triggered.

max_interval

Type	Constraint	Default	Unit	Required	Availability
float	>= 0.	0.	seconds	no	>= v1

Specifies the maximum amount of time in seconds that can pass before after a completed flag cycle before a new one is forced. Set it to 0 to deactivate this feature.

Sensor Chip Heating

All devices feature an internal heating for the sensor chip. For some devices the sensor chip needs to be heated to a specific temperature so that the provided calibrations are correct.

<chip_heating>
  <mode>floating</mode>
 
  <temperature>40</temperature>
</chip_heating>

mode

Type	Constraint	Default	Required	Availability	Remarks
string		floating	no	>= v1	case insensitive

Defines how the sensor chip should be heated. The available modes are:

floating - The heating is deactivated.
auto - The sensor chip is heated to the temperature specified in the calibrations.
fixed - The sensor chip is heated to a fixed temperature.

temperature

Type	Constraint	Default	Unit	Required	Availability
float	>= 0.	40.	degree Celsius	no	>= v1

Specifies the temperature in degree Celsius the sensor chip should be heated to in the fixed heating mode.

Focus Motor Position

Devices of the Xi series feature an internal motor that can be used to adjust the focus of the optics. For all other devices this has to be done manually.

<focus_motor_position></focus_motor_position>

focus_motor_position

Type	Constraint	Default	Unit	Required	Availability
float	-	-1.	percent	no	>= v1

Specifies the focus motor position in percent ([0., 100.]). Leave it blank or set it to a negative value, if the position should not be adjusted.

Radiation Parameters

The radiation parameters specified here affect the overall thermal frame. The radiation parameters for measurement fields are defined in their respective configurations.

Note: If the emissivity and/or the ambient temperature are controlled by the processing interface, these settings will only define their initial values.

<radiation>
  <emissivity>1</emissivity>
  <transmissivity>1</transmissivity>
  <ambient></ambient>
</radiation>

emissivity

Type	Constraint	Default	Required	Availability
float	[0.01, 1.1]	1.	no	>= v1

Defines the emissivity for the thermal frame.

transmissivity

Type	Constraint	Default	Required	Availability
float	[0.01, 1.1]	1.	no	>= v1

Specifies the emissivity for the thermal frame.

ambient

Type	Constraint	Default	Unit	Required	Availability
float	-	-100.	degree Celsius	no	>= v1

Specifies the ambient temperature for the thermal frame in degree Celsius. Leave it blank or set it to value equal or less than -100. to force the SDK to estimate the ambient temperature based on internal temperature probe readings.

Fail Safe

The fail safe mechanism of the SDK provides a heart beat signal on process interface outputs indicating that the camera and the processing chain are working correctly. The fail safe can be activated by failing one of the following conditions:

Processing chain is not updated. If the processing chain is not updated with new frame data in regular intervals, the fail safe will be activated.
Processing chain timeouts. If the end points of the processing chain are not reached within certain time frames, the fail safe will be triggered.
Flag timeouts. If the shutter flag does not reach its expected position within a given time, the corresponding flag cycle will be considered to have failed. If more than the configured amount flag cycles fail, the fail safe will be activated.

For more details refer to the Fail Safe chapter.

<fail_safe>
  <flag_timeouts>
    <enable>true</enable>
    <max_cycle_failures>0</max_cycle_failures>
  </flag_timeouts>
 
  <processing_chain_timeouts>
    <enable>true</enable>
  </processing_chain_timeouts>
</fail_safe>

flag_timeouts.enable

Type	Constraint	Default	Required	Availability
bool	-	true	no	>= v2

If set to true, flag timeouts will trigger the fail safe, if they cause enough flag cycles to fail.

flag_timeouts.max_cycle_failures

Type	Constraint	Default	Required	Availability
int	>= 0	0	no	>= v2

Determines the maximum number of flag cycles that are allowed to fail due to flag timeouts before the fail safe is triggered.

processing_chain_timeouts.enable

Type	Constraint	Default	Required	Availability
bool	-	true	no	>= v2

If set to true, the fail safe will be triggered, if the end points of the processing chain are not reached within a certain time frame.

Measurement Fields

In this section of the configuration file you can define an arbitrary amount of measurement fields that will automatically be created when a device connection is established. Each individual field is specified within its own set of <field> tags.

<measurement_fields>
  <field>
  ...
  </field>
 
  ...
</measurement_fields>

You have the following options when specifying a measurement field:

<field>
  <name>PIF</name>
 
  <shape>rectangle</shape>
  <mode>mean</mode>
 
  <position>
    <x>35</x>
    <y>55</y>
  </position>
 
  <dimensions>
    <width>40</width>
    <height>40</height>
  </dimensions>
 
  <radiation>
    <emissivity>1</emissivity>
    <transmissivity>1</transmissivity>
    <ambient></ambient>
  </radiation>
</field>

name

Type	Constraint	Default	Required	Availability
string	-		no	>= v2

Defines the name of the measurement field. It does not have to be unique.

shape

Type	Constraint	Default	Required	Availability	Remarks
string		rectangle	no	>= v2	case insensitive

Specifies the shape of the measurement field. Currently, the SDK supports the following shapes:

rectangle

mode

Type	Constraint	Default	Required	Availability	Remarks
string		mean	no	>= v2	case insensitive

Specifies which data point will be returned by the getDataPoint() method of the MeasurementField class:

mean - arithmetic mean temperature of all the pixels within the measurement field.
minimum - minimum temperature in the measurement field.
maximum - maximum temperature in the measurement field.

Note: The mean, minimum and maximum temperatures are always calculated for each measurement field and can be accessed through their respective getters in the MeasurementField class. This setting primarily influences which data point will be output via the processing interface.

position

Specifies the position of the measurement field within the thermal frame. The origin of coordinates is located at the upper left corner of the thermal frame. Depending on the shape of the measurement field this position refers to aspects of its shape:

rectangle - Upper left corner.

Attention: Due to limitations imposed by the algorithm used to process measurement fields a field can not cover a one pixel wide margin at the edges of thermal frame. Trying to create such a field will result in an error or and exception.

Defining a rectangular measurement field within a thermal frame.

position.x

Type	Constraint	Default	Unit	Required	Availability
int	>= 1 && <= frame width -1	0	pixel	no	>= v2

Defines the x-position in pixels of the measurement field.

position.y

Type	Constraint	Default	Unit	Required	Availability
int	>= 1 && <= frame height - 1	0	pixel	no	>= v2

Defines the y-position in pixels of the measurement field.

dimensions

Specifies the dimensions of the measurement fields. Depending on the configured shape different dimensions options may need to be set:

rectangle - width and height

Attention: Due to their internal implementation measurement fields can cover a one pixel sized margin on the edges of the thermal frame.

dimensions.width

Type	Constraint	Default	Unit	Required	Availability
int	> 0 && x + width < frame width - 1	0	pixel	no	>= v2

Defines the width of a rectangular measurement field in pixels.

dimensions.height

Type	Constraint	Default	Unit	Required	Availability
int	> 0 && y + height < frame height -1	0	pixel	no	>= v2

Defines the height of a rectangular measurement field in pixels.

radiation.emissivity

Type	Constraint	Default	Required	Availability
float	[0.01, 1.1]	1.	no	>= v2

Defines the emissivity for the measurement field.

radiation.transmissivity

Type	Constraint	Default	Required	Availability
float	[0.01, 1.1]	1.	no	>= v2

Specifies the emissivity for the measurement field.

radiation.ambient

Type	Constraint	Default	Unit	Required	Availability
float	-	-100.	degree Celsius	no	>= v2

Sets the ambient temperature for the measurement field in degree Celsius. Leave it blank or set it to value equal or less than -100. to force the SDK to estimate the ambient temperature based on internal temperature probe readings.

Process Interface (PIF)

This section determines the configuration of the process interface (PIF). The first thing to do is specify the type and count of the used PIF. Then its individual channels can be configured.

For the analog inputs, the digital inputs, the analog outputs and the digital outputs multiple channels can be configured. For each of these channels their configuration has to be provided within individual <channel> tags. If no explicit configuration is provided for an available channel, the SDK will set its mode to off. The channels are each addressed by a combination of a <device_index> specifying the PIF device and a <pin_index> referring to the specific pin on this device.

Some PIFs feature a dedicated fail safe channel that can be switched on or off. In the case of stackable PIFs each device features a set of pins for this channel. If they are stacked together, these pins will always output the same signal. Therefore, ever only a maximum of one fail safe channel needs to be configured. The Fail Safe chapter offers more insights into the functionality of this channel type.

<process_interface>
  <device_type>stackable</device_type>
  <device_count>3</device_count>
 
  <analog_inputs>
    <channel>
      <device_index>0</device_index>
      <pin_index>0</pin_index>
      ...
    </channel>
 
    ...
  </analog_inputs>
 
  <digital_inputs>
    <channel>
      <device_index>0</device_index>
      <pin_index>0</pin_index>
      ...
    </channel>
 
    ...
  </digital_inputs>
  
  <analog_outputs>
    <channel>
      <device_index>0</device_index>
      <pin_index>0</pin_index>
      ...
    </channel>
 
    ...
  </analog_outputs>
 
  <digital_outputs>
    <channel>
      <device_index>0</device_index>
      <pin_index>0</pin_index>
      ...
    </channel>
 
    ...
  </digital_outputs>
 
  <fail_safe>
    <mode>off</mode>
  </fail_safe>
</process_interface>

Device

device_type

Type	Constraint	Default	Required	Availability	Remarks
string		automatic	no	>= v2	case insensitive

Specifies the PIF device type.

Depending on the used camera different PIF devices types can be set:

Autonomous (Xi 80, Xi 410(MT), Xi 1M)

automatic - The SDK uses the PIF device type and count stored in the on-device settings.
none - No PIF device is used.
internal - The built-in internal PIF is used.
stackable - External stackable PIF(s) are used.

Based on this setting the SDK will explicitly instruct the camera firmware to use/expect the specified PIF device type.

Non-autonomous (all other cameras)

automatic - The SDK uses the PIF device type detected by the firmware.
none - No PIF is used.
standard - A standard PIF is used.
industrial_ma - An industrial PIF with current based analog outputs is used.
industrial_mv - An industrial PIF with voltage based analog outputs is used.
temperature_probe - Instead of a PIF an external temperature probe is used on the PIF connector.
proprietary - The pins of the PIF connector are used directly.

Note: If the PIF device type is set to none, the SDK will adhere to it and will ignore attached PIF devices.

Attention: If the PIF device type is set to automatic or if the configured PIF device type does not match the attached one, the SDK will still try to apply the channel configurations. This, however, may fail because not all of the PIF devices support the same analog output modes.

Note: If a specific PIF device is configured but none is actually attached, the SDK will assume the none type and will ignore the channel configurations.

device_count

Type	Constraint	Default	Required	Availability
int	[1, 3]	1	no	>= v2

This option is only relevant for stackable PIFs. For all other PIF devices the SDK can derive it from the configured type:

none - 0
all others - 1

This count specifies how many stackable PIFs can be accessed and configured through the SDK. The number of actual connected devices can be lower! Manipulating a device that is configurable but not actually connected has currently no tangible effects. This behavior will become relevant once the SDK supports autonomous on-device configurations.

Attention: The SDK tells the camera firmware how many stackable PIFs to expected based on this setting. As a consequence, the firmware will only try to detect as many stackable PIFs as this setting suggests. In short: If you set this count to 2 but connect three stackable PIFs, the SDK will report that two PIFs are connected.

Channels

All channels that are not explicitly configured will be set to the mode off by the SDK.

channel.device_index

Type	Constraint	Default	Required	Availability
int	[0, device_count)	0	no	>= v2

First part of the channel identification indicating on which PIF device its corresponding pins are located. Starts at 0 and is at its maximum one less than the device count.

channel.pin_index

Type	Constraint	Default	Required	Availability
int	[0, pin_count)	0	no	>= v2

Second part of the channel identification indicating which pins on the PIF device correspond with the channel. Starts at 0 and is at its maximum one less than the pin count. The concrete pin count depends on the channel and PIF device type.

Note: The SDK ignores channel configurations with invalid device and pin indices. If multiple configurations are provided for the same channel, the SDK will only apply the one that was specified first in the configuration file.

For more details on addressing channels please refer to the corresponding section in the Public API chapter.

analog_inputs

Currently, all PIF devices feature analog inputs that can be used to read voltages between 0 and 10 V. The currently read voltages can always be accessed through the FrameMetadata object provided through the onThermalFrame() callback to IRImagerClients.

Note: The SDK may report slightly higher voltages. This is due to an offset that is applied internally to calibrate the voltage measurements. Voltages above 10 V register as 10 V with the PIF and the SDK.

By specifying a <mode> the channels can be assigned a certain functionality. All other settings specify various parameters for these modes. UNIQUE modes can only be applied once across all channel types.

<channel>
  <device_index>0</device_index>
  <pin_index>0</pin_index>
 
  <mode>off</mode>
 
  <slope>
    <gain>1.</gain>
    <offset>0.</offset>
  </slope>
 
  <trigger>
    <threshold>5.</threshold>
    <low_active>true</low_active>
  </trigger>
 
  <uncommitted_value>
    <name>Temperature</name>
    <unit>Celsius</unit>
  </uncommitted_value>
</channel>

mode

Type	Constraint	Default	Required	Availability	Remarks
string		off	no	>= v2	case insensitive

Specifies the functionality assigned to this channel. The SDK currently supports the following modes:

off - The channel is switched off.
ambient_temperature (UNIQUE) - The ambient temperature for the radiation parameters of the thermal frame is derived from the input voltage. The radiation parameters are updated at most every 500 ms.
emissivity (UNIQUE) - The emissivity for the radiation parameters of the thermal frame is derived from the input voltage. The radiation parameters are updated at most every 500 ms tops.
flag_control (UNIQUE) - The shutter flag can be controlled based on the input voltage.

Attention
When this mode is activated the SDK and its clients will no longer be able to control the shutter flag. Thus, it is completely up to the entity providing the voltage signal to make sure that the flag is closed periodically to prevent temperature drifts and to pass the initial calibration period.
uncommitted_value - The incoming voltage value is subjected to a custom linear transformation and is then provided by the SDK to all IRImagerClients along with its configured name and unit through the onPifUncommittedValue() callback.

slope

These settings define the parameters of the linear transformation that converts the measured input voltage U_in into the desired target values:

Mode	Symbol	Transformation
`ambient_temperature`	`t_ambient`	`U_in[V] = gain[V/°C] * t_ambient[°C] + offset[V]`
`emissivity`	`e`	`U_in[V] = gain[V] * e + offset[V]`
`uncommitted_value`	`x`	`U_in[V] = gain[V/?] * x[?] + offset[V]`

slope.gain

Type	Constraint	Default	Unit	Required	Availability
float	-	1.	mode dependent	no	>= v2

Specifies the gain of the linear transformation.

slope.offset

Type	Constraint	Default	Unit	Required	Availability
float	-	0.	volt	no	>= v2

Defines the offset of the linear transformation.

trigger

Specifies the type of input voltages U_in for which actions are triggered.

Mode	Action	`low_active`	`!low_active`
`flag_control`	close the shutter flag	`U_in < U_threshold`	`U_in >= U_threshold`
	open the shutter flag	`U_in >= U_threshold`	`U_in < U_threshold`

trigger.threshold

Type	Constraint	Default	Unit	Required	Availability
float		0.	volt	no	>= v2

Defines the threshold voltage U_threshold. The configured value is automatically clipped to 0 - 10 V.

trigger.low_active

Type	Constraint	Default	Required	Availability
bool	-	true	no	>= v2

Specifies whether the trigger is low active.

uncommitted_value

Specifies some additional information about an uncommitted value that will be passed alongside the transformed input voltage to the onPifUncommittedValue() callback of IRImagerClients.

uncommitted_value.name

Type	Constraint	Default	Required	Availability
string	-		no	>= v2

Sets the name of the uncommitted value.

uncommitted_value.unit

Type	Constraint	Default	Required	Availability
string	-		no	>= v2

Specifies the unit of the uncommitted value.

digital_inputs

On PIF devices that feature digital input channels binary voltage signals can be read. The current state of the signal - low/false or high/true - can always be accessed through the FrameMetadata object provided by the onThermalFrame() callback to IRImagerClients.

By specifying a <mode> the channels can be assigned a certain functionality. All other settings specify various parameters for these modes. UNIQUE modes can only be applied once across all channel types.

<channel>
  <device_index>0</device_index>
  <pin_index>0</pin_index>
 
  <mode>off</mode>
 
  <trigger>
    <low_active>true</low_active>
  </trigger>
</channel>

mode

Type	Constraint	Default	Required	Availability	Remarks
string		off	no	>= v2	case insensitive

Specifies the functionality assigned to this channel. The SDK currently supports the following modes:

off - The channel is switched off.
flag_control (UNIQUE) - The shutter flag can be controlled based on the input signal.

Attention
When this mode is activated the SDK and its clients will no longer be able to control the shutter flag. Thus, it is completely up to the entity providing the voltage signal to make sure that the flag is closed periodically to prevent temperature drifts and to pass the initial calibration period.

trigger

Specifies based on which input signal S_in actions are triggered.

Mode	Action	`low_active`	`!low_active`
`flag_control`	close the shutter flag	`S_in == low`	`S_in == high`
	open the shutter flag	`S_in == high`	`S_in == low`

trigger.low_active

Type	Constraint	Default	Required	Availability
bool	-	true	no	>= v2

Specifies whether the trigger is low active.

analog_outputs

Depending on the PIF device type the analog output channels can provide voltage and/or current based signals.

By specifying a <mode> the channels can be assigned a certain functionality. All other settings specify various parameters for these modes. UNIQUE modes can only be applied once across all channel types.

<channel>
  <device_index>0</device_index>
  <pin_index>0</pin_index>
 
  <mode>off</mode>
  <output_mode>0-10v</output_mode>
 
  <slope>
    <gain>1.</gain>
    <offset>0.</offset>
  </slope>
 
  <field_index>0</field_index>
 
  <output>
    <active>10.</active>
    <intermediate>10.</intermediate>
    <inactive>0.</inactive>
  </output>
</channel>

mode

Type	Constraint	Default	Required	Availability	Remarks
string		off	no	>= v2	case insensitive

Specifies the functionality assigned to this channel. The SDK currently supports the following modes:

off - The channel is switched off.
external_communication - SDK clients can output a custom signal on the channel with the help of the setAoValue() method of the ProcessInterface.
fail_safe (UNIQUE) - A heart beat signal is output on the channel indicating that the camera and processing pipeline are working correctly.
flag_status (UNIQUE) - The current flag status is output on the channel.
frame_sync (UNIQUE) - Outputs a pulse on the channel every time a new frame is captured.
internal_temperature (UNIQUE) - The internal temperature is output on the channel. The internal temperature is equivalent to the value returned by the getTemperatureBox() method of the IRImager.
measurement_field - The data point defined by the mode of the measurement field is output on the channel.

output_mode

Type	Constraint	Default	Required	Availability	Remarks
string		0-10v	no	>= v2	case insensitive, no blanks

Specifies the output output mode of the channel. Depending on the used PIF device one or more of the following modes are available:

0-10v - 0 - 10 V
0-20ma - 0 - 20 mA
4-20ma - 4 - 20 mA

slope

These settings define the parameters of the linear transformation that converts data points into output values X_out. Depending on the chosen output mode [X_out] is either V or mA.

Mode	Symbol	Transformation
`internal_temperature`	`t_internal`	`X_out[x] = gain[x/°C] * t_internal[°C] + offset[x]`
`measurement_field`	`x_field`	`X_out[x] = gain[x/?] * x_field[?] + offset[x]`

Note: What data point x_field of a measurement field is provided depends on the mode setting of the measurement field.

slope.gain

Type	Constraint	Default	Unit	Required	Availability
float	-	1.	mode and output mode dependent	no	>= v2

Specifies the gain of the linear transformation.

slope.offset

Type	Constraint	Default	Unit	Required	Availability
float	-	0.	output mode dependent	no	>= v2

Defines the offset of the linear transformation.

field_index

Type	Constraint	Default	Required	Availability
int	[0, count of configured measurement fields)	0	no	>= v2

Identifies the measurement field whose data point should be output. The index 0 refers to the first measurement field specified in the configuration and adheres to the sequence in which they are defined.

If there are three measurements field configured, then 0 refers to the first, 1 to the second and 2 to the third field specified.

output

These configuration options specify what values X_out are output for different states or events. There values are automatically clipped to the limits of the set output mode.

Mode	`active`	`intermediate`	`inactive`
`fail_safe`	pulse height	-	-
`flag_status`	flag is closed	flag is moving	flag is open
`frame_sync`	pulse height	-	-

output.active

Type	Constraint	Default	Unit	Required	Availability
float		10.	output mode dependent	no	>= v2

Defines the output level for an "active" event/state. Its value is automatically clipped to the limits of the set output mode.

output.intermediate

Type	Constraint	Default	Unit	Required	Availability
float		10.	output mode dependent	no	>= v2

Defines the output level for an "intermediate" event/state. Its value is automatically clipped to the limits of the set output mode.

output.inactive

Type	Constraint	Default	Unit	Required	Availability
float		0.	output mode dependent	no	>= v2

Defines the output level for an "inactive" event/state. Its value is automatically clipped to the limits of the set output mode.

digital_outputs

By specifying a <mode> the channels can be assigned a certain functionality. All other settings specify various parameters for these modes. UNIQUE modes can only be applied once across all channel types.

<channel>
  <device_index>0</device_index>
  <pin_index>0</pin_index>
 
  <mode>off</mode>
 
  <output>
    <low_active>true</low_active> 
  </output>
</channel>

mode

Type	Constraint	Default	Required	Availability	Remarks
string		off	no	>= v2	case insensitive

Specifies the functionality assigned to this channel. The SDK currently supports the following modes:

off - The channel is switched off.
external_communication - SDK clients can output a custom signal on the channel with the help of the setDoValue() method of the ProcessInterface.
fail_safe (UNIQUE) - A heart beat signal is output on the channel indicating that the camera and processing pipeline are working correctly.
flag_status (UNIQUE) - The current flag status is output on the channel.
frame_sync (UNIQUE) - Outputs a pulse on the channel every time a new frame is captured.

output

These settings adjust the output signal.

Mode	`low_active`	`!low_active`
`flag_status`	low if flag is closed	high if flag is closed

low_active

Type	Constraint	Default	Required	Availability
bool	-	true	no	>= v2

Defines whether a high or low signal is output on an "active" state and/or event.

fail_safe

There is always only one fail safe channel available per PIF or per set of stackable PIFs. Please refer to the Fail Safe chapter for more information about the signal that is provided on this channel.

This configuration will only be applied, if a fail safe channel is available.

<fail_safe>
  <mode>off</mode>
</fail_safe>

mode

Type	Constraint	Default	Required	Availability	Remarks
string		off	no	>= v2	case insensitive

Specifies the functionality assigned to this channel. The SDK currently supports the following modes:

off - The channel is switched off.
on - The channel is switched on.

Note: The fail safe mode is unique for analog and digital outputs but the fail safe channel can be activated indecently of that.

Calibration

The calibration files for a device consists out of up to three different file types:

A XML based configuration file called Cali-<Serial Number>.xml specifying available optics, temperature ranges, video formats and other device specific parameters.
Calibration files named Cali-<Serial Number>-<...>.dat
Optional files named Kennlinie-<Serial Number>-<...>.prn specifying characteristic curves.

How To Get Them

The SDK automatically tries to acquire missing calibration files. By default it attempts to copy them from a local source directory on the filesystem. The location of this source directory is not set out of the box. When that fails the SDK tries to download the missing files from Optris servers.

Note: You can adjust the priority of the different ways the SDK tries to acquire missing calibration files with the help of the Sdk class. Refer to the API documentation of its setCalibrationFileSources() method for more details.

The automatically downloaded or copied files will be placed in the user settings directory:

<User AppData>\Roaming\Imager\Cali on Windows
~/.config/optris/Cali on Linux

SDK Search Hierarchy

User settings directory
- <User AppData>\Roaming\Imager\Cali on Windows
- ~/.config/optris/Cali on Linux

Normalization

These files contain corrections for the temperature calculation when the emissivity is not 1. They consist of two different types of files:

A XML based file named Norm.xml defining which normalization file apply for a specific camera type.
Normalization files named Norm-<Id>.prn containing the corrections.

How To Get Them

These files are automatically installed.

SDK Search Hierarchy

Norm\ subfolder in the working directory of the application.
User settings directory
- <User AppData>\Roaming\Imager\Cali\Norm on Windows
- ~/.config/optris/Cali/Norm on Linux
SDK install directory
- <SDK Install Directory>\norm on Windows
- /usr/share/otcsdk/norm on Linux

Formats Definitions

The formats definitions file specifies what video formats are supported by the different devices. It also tells the SDK how to process received data frames.

File Name

Formats.def

How To Get It

The file is automatically installed. If lost, you can download it from an Optris server.

SDK Search Hierarchy

Working directory of the application.
User settings directory
- <User AppData>\Roaming\Imager\ on Windows
- ~/.config/optris/ on Linux
SDK install directory
- <SDK Install Directory>\ on Windows
- /usr/share/otcsdk/ on Linux

Dynamic Dead Pixels

This file contains dead pixels detected by the SDK.

File Name

DP-<Serial Number>.dat

How To Get It

The file is automatically generated by the SDK once a dead pixel is detected.

SDK Search Hierarchy

User settings directory
- <User AppData>\Roaming\Imager\DynamicDeadPixels on Windows
- ~/.config/optris/DynamicDeadPixels on Linux

Contents

Configuration

Version

configuration

sdk

Serial Number

serial_number

Connection

interface

ip_address

port

check_ip

timeout

Buffer Queue Size

buffer_queue_size

Optics

field_of_view

text

Temperature Range

min

max

extended

enable_high_precision

Video Format

width

height

framerate

subsampled_framerate

Auto Flag

enable

min_interval

max_interval

Sensor Chip Heating

mode

temperature

Focus Motor Position

focus_motor_position

Radiation Parameters

emissivity

transmissivity

ambient

Fail Safe

flag_timeouts.enable

flag_timeouts.max_cycle_failures

processing_chain_timeouts.enable

Measurement Fields

name

shape

mode

position

position.x

position.y

dimensions

dimensions.width

dimensions.height

radiation.emissivity

radiation.transmissivity

radiation.ambient

Process Interface (PIF)

Device

device_type

device_count

Channels

channel.device_index

channel.pin_index

analog_inputs

mode

slope

slope.gain

slope.offset

trigger

trigger.threshold

trigger.low_active

uncommitted_value

uncommitted_value.name

uncommitted_value.unit

digital_inputs

mode

trigger

trigger.low_active