libirimager
IR Imager Direct-SDK

Linux installation

Before installation, a basic test should be performed in order to verify that the PI imager series can be run on the desired system. For some devices passing the nodrop option to the UVC kernel module is mandatory. The need for this can be checked with a standard application like guvcview. If the camera's raw data (a green noisy image) cannot be displayed at a high framerate the nodrop option needs to be activated. On some devices the nodrop option can lead to incomplete frame transmissions. Therefore it should only be activated if it is really needed.

The nodrop option can be passed at system startup by creating the following file:
$ sudo bash -c 'echo "options uvcvideo nodrop=1" > /etc/modprobe.d/uvcvideo.conf'
This makes the option permanent for the UVC driver (after the next reboot).

Temporary activation can be achieved with:
$ sudo rmmod uvcvideo; sudo modprobe uvcvideo nodrop=1

Alternatively, the parameter can be modified via sysfs during runtime:
$ sudo bash -c 'echo -n 1 > /sys/module/uvcvideo/parameters/nodrop'

Accessing video devices may need the user to be in the system's video group. Checking membership can be done with:
$ groups

Add the current user to this group, if video is not listed there:
$ sudo usermod -a -G video <username>

A new login is necessary afterwards.

Basic installation

The driver is dependant of the following packages:

  • cmake
  • freeglut3-dev (only if the user wants to compile the OpenGL example)

$ sudo apt-get install cmake freeglut3-dev libusb-1.0-0-dev

Do the basic installation as follows:
$ sudo dpkg -i libirimager-<VERSION>-<ARCH>.deb

Calibration/Configuration

Before using the camera, mandatory calibration files need to be installed. Please connect your camera via the USB cable and ensure access to the internet. Then call the following service application:
$ sudo ir_download_calibration

Everything is installed to /usr/share/libirimager/cali.

If you like to specify a user-defined directory for the calibration files, append the following option:
$ ir_download_calibration -t /tmp
The driver makes use of this calibration directory, if it is specified in the xml configuration file (see Generating configuration files).

Determining serial number

The serial number of an attached device can be determined programmatically. Call the following service application to obtain the serial number:
$ ir_find_serial

You might want to search for a specific device, if more than one camera is connected:
$ ir_find_serial -d<Your camera's serial>

Generating configuration files

For an attached device, an xml configuration file can be generated with the command:
$ ir_generate_configuration > <user-defined file>

You might consider to combine the service application calls to concatenate a generic command, e.g.,
$ ir_generate_configuration > `ir_find_serial`.xml

The generated file contains several parameters that can be adjusted regarding the application's requirements:
$ cat `ir_find_serial`.xml
<imager xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<serial>YOURSERIAL</serial>
  <videoformatindex>0</videoformatindex>
  <calipath>/usr/share/libirimager/cali</calipath>
  <fov>33</fov>
  <temperature>
    <min>-20</min>
    <max>100</max>
  </temperature>
  <framerate>32.0</framerate>
  <outputmode>2</outputmode>
  <bispectral>0</bispectral>
  <average>0</average>
  <autoflag>
   <enable>1</enable>
   <mininterval>15.0</mininterval>
   <maxinterval>0.0</maxinterval>
  </autoflag>
</imager>

For PI200/230 devices, the bispectral parameter needs to be activated (set to 1), if the visible channel is desired to be used.

Example applications

The directory /usr/share/doc/libirimager contains examples, which one can copy to the preferred development directory, e.g.
$ cp /usr/share/doc/libirimager/examples/minimal/‍* ~/workspace/mydestination

You might consider the minimal application as a template for your own application. Before compilation, necessary dependencies need to be installed:
$ sudo apt-get install build-essential cmake

Compilation is performed straightforward:
$ cd ~/workspace/mydestination
$ mkdir build
$ cd build
$ cmake ..
$ make

The examples rely on an XML configuration file (see subdirectory /usr/share/doc/libirimager/examples/config), describing the attached camera and its optics. The directory containing calibration files can be overwritten by the tag <calipath>, e.g.:
<calipath>/opt/piimager/cali</calipath>

Additionally the folder containing the file Formats.def (describing raw camera formats) can be configured with the tag <formatspath>, e.g.:
<formatspath>/opt/piimager</formatspath>

For the OpenGL examples, ensure to have freeglut installed. Ubuntu users execute the following:
$ sudo apt-get install freeglut3 freeglut3-dev

Basic interface usage

Typically, a control loop checks for the availability of data at a high frame rate (method getFrame of IRDeviceUVC). It returns with raw data that needs to be converted to temperature data. This is done within the method process of class IRImager. It uses itself the above-mentioned callback functions/methods to pass temperature data to the user. The following sequence diagram documents this typical usage.

sequencediagram_libirimager.png
Typical usage of SDK on Linux platforms
A C-style example is also available. The main difference is the usage of callback functions, instead of callback class methods.

MATLAB Integration

Data streams can be accessed in MATLAB via a C-style interface, called DirectBinding. Please see the MATLAB application contained in the examples folder.

Troubleshooting

If the example applications do not provide a proper thermal image in false color representation, check

  • ... if a standard UVC camera player can display the raw data stream. Please install guvcview and open the appropriate imager device. guvcview is able to display the obtainable frame rate. Activate this option and check whether the frame rate is >> 1.
  • ... whether the USB bandwidth is sufficient. Unplug every other device on the same USB bus. You can list all attached devices with lsusb -t. Ensure that the thermal imager is the only device on a certain bus.
  • ... if calibration files for your camera (compare serial number, field of view and temperature range) are present (path can be set with the xml configuration, default: /usr/share/libirimager/cali) and whether they are readable with your system account. The serial number is determined automatically, if it is not set in the xmlConfig file. Field of view and temperature range need to be adjusted in this xmlConfig file, too. The calibration files are looked up in dependency of these settings, e.g.,
  • ... if you use Ubuntu 18.04 or newer versions and receive the error "sh: 1: /sbin/route: not found" you've to install net-tools via "sudo apt install net-tools"

    <fov>30</fov>
    <temperature>
      <min>-20</min>
      <max>100</max>
    </temperature>

        will configure the file names:

    Cali-<SERIAL#>.xml
    Cali-<SERIAL#>-30-M20-100.dat
    Kennlinie-<SERIAL#>-30-M20-100.prn

  • ... if the Windows application PIConnect can display thermal data with your camera correctly. If not, hardware concerns may be the reason for your problem.

Windows installation

The Windows SDK is delivered either as delayed-loadable Dynamic Link Library (.dll) and as Static Library (.lib). The user might use his own DirectShow graph to acquire raw data from the optris PI devices or the included classes VideoCapture and IRDeviceDS. Raw data is to be passed to an IRImager instance.

Basic installation

The windows SDK comes as a zip archive. It can be decompressed to any location on the disk, e.g., to a subfolder of the user's development directory. Environment variables might be needed to be set in order to link against the library or to use it at runtime, e.g.:
set PATH=%PATH%;myfolder\sdk