1.16. GenICam#

Summary:

Camera control of devices that support the GenICam standard

Type:

DataIO

License:

licensed under LGPL, this plugin is based on GenICam licensed under the GenICam license 1.5 (see GenICam_License.txt)

Platforms:

Windows, Linux

Devices:

Camera control of devices that support the GenICam standard

Author:

M. Gronle, ITO, Universität Stuttgart

1.16.1. Overview#

This plugins is a wrapper for the GenICam 3 interface and is able to control cameras, that support the GenICam standard. The connection is realized by a transport layer library of the specific camera vendor. This library has the file suffix .cti and must be in the same binary representation (32/64bit) than itom and this plugin.

Usually, the locations of cti-files are contained in the environment variable GENICAM_GENTL64_PATH or GENICAM_GENTL32_PATH. Indicate the path to your desired transport layer in order to access a camera. If the parameter GenTLProducer is kept empty, a list of all detected cti-files is printed to the command line. Every transport layer can support one or multiple interfaces (USB3, GigE, Firewire…). Indicate the right interface or leave ‘interface’ empty, in order to get a list of all supported interfaces by the selected transport layer.

In order to keep this plugin compatible to other camera plugins, the additional parameters ‘integration_time’, ‘roi’, ‘sizex’, ‘sizey’, and ‘bpp’ are added to the plugin are kept synchronized with ‘ExposureTime’, ‘Width’, ‘Height’, ‘OffsetX’, ‘OffsetY’ or ‘PixelFormat’.

Up to now the following pixel formats are supported: Mono8, Mono10, Mono10p, Mono10Packed, Mono12, Mono12p, Mono12Packed, Mono14, Mono16, YCbCr422_8, RGB8, BGR8, BGR10p, BGR12p, BayerRG8, BayerRG10g40IDS (IDS specific). In order to operate framegrabber-based cameras (CoaXPress, Camera Link) with this plugin, please read the additional information in the documentation of this plugin. Colored pixel formats, with a single-color bitdepth of more than 8 bit are reduced to 8bit per color, since rgba32 is the single color datatype of itom.dataObject.

Please notice, that some cameras require more than one allocator buffer (see parameter ‘numBuffers’). Sometimes, it is better to set the parameter ‘AcquisitionMode’ to ‘SingleFrame’ instead of ‘Continuous’. If a camera is not robustly working, try to change these parameters before starting the device.

This plugin has been tested with the following cameras:

  • Allied Vision, Manta (Firewire)

  • Allied Vision, Goldeye G-008 SWIR (GigE)

  • Basler puA1280-54uc (USB3)

  • Basler acA1920-50gm (GigE)

  • Baumer TXG12 (GigE)

  • Dalsa calibIr GXM640

  • FLIR AX5 (GigE)

  • Mikrotron (CoaXPress) with Active Silicon Framegrabber (FireBird)

  • Vistek, exo174MU3 (USB3)

  • Vistek, exo174MGE (GigE)

  • Ximea (USB3)

  • IDS Imaging, U3-3200SE-M-GL (USB3)

  • IDS Imaging, U3-3800SE-M-GL (USB3)

  • IDS Imaging, UI-5880CP-M-GL (GigE)

  • IDS Imaging, U3-38J0XLE-C-HQ (USB3, only format BayerRG10g40IDS)

  • IDS Imaging, U3-3280CP-C-HQ Rev 2.2 (USB3)

  • IDS Imaging, U3-3280CP-M-GL Rev 2.2 (USB3)

1.16.2. Initialization#

The following parameters are mandatory or optional for initializing an instance of this plugin:

  • GenTLProducer: str, optional

    Indicate either a string containing the vendor and model name separated with a semicolon (e.g. ‘XIMEA GmbH.;xiApi’) or the path to a cti file (GenICam GenTL transport layer) with the file suffix .cti of the respective camera driver. If nothing is indicated, a list of all auto-detected vendors and models is returned.

    default: “C:XIMEAGenTL Producerx64ximea.gentlX64.cti”

  • interface: str, optional

    interface to be opened (e.g. IIDC, U3V, USB3, USB, Ethernet…). Open with an empty string to get a list of all possible interfaces for the chosen transport layer. Default: ‘auto’ opens the first supported interface of the chosen transport layer.

    default: “auto”

  • deviceID: str, optional

    name of the device to be opened. Leave empty to open first detected device of given transport layer and interface. Some cameras don’t have a persistent device ID. Then, it is better to identify them with their serial number. If this is desired this parameter can also be set to ‘Serial:your_serial_number’.

    default: “”

  • streamIndex: int, optional

    index of data stream to be opened (default: 0).

    Value range: [0, inf], Default: 0

  • paramVisibilityLevel: int, optional

    Visibility level of parameters (0: Beginner, 1: Expert, 2: Guru, 3: Invisible).

    Value range: [0, 3], Default: 1

  • portIndex: int, optional

    port index to be opened (default: 0).

    Value range: [0, inf], Default: 0

  • verbose: int, optional

    verbose level (0: print nothing, 1: only print errors, 2: print errors and warnings, 3: print errors, warnings, information, 4: debug, 5: all (gives even information about parameter changes or buffer states), higher: special debug values).

    Value range: [0, 5], Default: 1

  • accessLevel: int, optional

    Access level to the device: (Readonly: 2, Control: 3, Exclusive: 4).

    Value range: [2, 4], Default: 4

  • flushAllBuffersToInput: int, optional

    If 1: all announced buffers will be additionally flushed with ‘ACQ_QUEUE_ALL_TO_INPUT’ to the input queue in startDevice or in case of any buffer errors. If 0: this is not the case (default). It seems that the Allied Vision Goldeye G-008 camera requires this option to be set to 1.

    Value range: [0, 1], Default: 0

1.16.3. Starting a device#

In order to better understand how a device is opened by this plugin, it is necessary to shortly explain the architecture of a GenICam compliant device:

  • Each camera manufacturer provides access to the parameterization and the image acquisition and transfer between the camera and the computer by a so-called GenICam transport layer producer (GenTLProducer). Therefore, the manufacturer has to provide one or multiple transport layer drivers that usually have the file suffix cti.

  • The technology, how a camera is connected to the computer (e.g. GigE, USB3, CoaxPress, Firewire…), is called an interface. Sometimes, every interface is supported by a distinct cti file, sometimes one cti file can support multiple interfaces.

  • Every connected camera is represented by a device, that is opened by its corresponding interface.

  • A device provides different sets of cameras. The entire set of parameters and their descriptions and meta information, is stored in a xml- or zip-file. This file can either be stored on the camera itself (default) or on the harddrive. In order to parameterize a camera using a specific xml- or zip-file, a certain port is opened to the camera.

  • A camera can provide multiple data streams. Usually, a standard camera has exactly one stream that delivers image data. However, it might be possible to access devices that deliver different type of output data, e.g. image data or point clouds…

The initialization parameters of a GenICam plugin mostly represent the different items of the connection architecture, as listed above. It is possible to receive a list of detected transport layers, interfaces or devices if you leave the level, which you are currently interested in, empty. For instance, if you don’t indicate a GenTLProducer, a list of all detected producers is printed to the command line.

If you indicated a certain GenTLProducer, you can leave the ‘interface’ parameter empty, to get a list of all supported interfaces of this producer. If you chose ‘auto’, the first interface with at least one connected camera device will be chosen.

In order to precisely select a device, e.g. based on its name or serial number, indicate the GenTLProducer and the interface, but leave the deviceID empty in order to get a list of all currently connected devices.

Information about possible ports and streams can be obtained by choosing a high verbosity level as initialization parameter ‘verbose’.

Note

With some cameras it may be necessary to set the parameter numBuffers to a value of 2 (e. g. FLIR AX5).

1.16.4. Parameters#

An instance of the GenICam plugin contains both parameters, that are directly redirected to the parameter set of the camera as well as some parameters, that are always available and are created by the plugin itself. Usually, the original parameters from the transport layer of the camera start with a capital letter, while plugin parameters have a small letter as first character.

The set of parameters, that is exposed from the device-specific set, announced by the transport layer, depend on the initialization parameter ‘paramVisibilityLevel’. In general, device parameters are categorized into the three visibility categories ‘Beginner (0)’, ‘Expert (1)’ or ‘Guru (2)’. Depending on the ‘paramVisibilityLevel’, only parameters are loaded and created in the plugin instance, whose visibility level is lower or equal than the selected limit. Usually, the ‘Guru’ level is only necessary for special parameterizations of the plugin.

The following list contains all parameters, that are related to the GenICam plugin in itom itself:

name: {str}, read-only

name of the plugin: ‘GenICam’

sizex: {int}, read-only

Current width of the acquired image; this parameter is synchronized with the standard parameter ‘Width’ of the GenICam transport layer. This parameter is a mandatory parameter for dataIO-instances in itom.

sizey: {int}, read-only

Current height of the acquired image; this parameter is synchronized with the standard parameter ‘Height’ of the GenICam transport layer. This parameter is a mandatory parameter for dataIO-instances in itom.

bpp: {int}, read-only

Current bitdepth per pixel; this parameter is derived from the ‘PixelFormat’ standard parameter of the GenICam transport layer. This parameter is a mandatory parameter for dataIO-instances in itom.

integration_time: {float}

Integration or exposure time in seconds. This parameter is mapped to the standard parameter ‘ExposureTime’ (in ms).

roi: {int rect [x0,y0,width,height]}

Current region of interest of the image. Changes in this parameter influence the standard parameters ‘OffsetX’, ‘OffsetY’, ‘Width’ and ‘Height’.

timeout: {float}

Timeout (in s) for waiting for the arrival of a new image after the acquire command. This parameter is only used within the itom GenICam plugin.

numBuffers: {int}, default: 1

Number of image buffers that should be created in the ‘startDevice’ command. Some devices indicate a minimum number of image buffers. Use this parameter to set this number before starting the device. This parameter is only used within the itom GenICam plugin.

userDefinedPayloadSize: {int}, default: 0

Usually, the ideal size of an image buffer is returned by the transport layer of GenICam or by the standard parameter ‘PayloadSize’. However, if you set this parameter to a value bigger than 0, a user-defined buffer size in bytes can be selected. Usually, it is not necessary to change this parameter.

1.16.5. Verbose level#

During the initialization of a GenICam camera instance, it is possible to select a certain verbose level. The higher the number, the more information, warning or error messages will be printed to the command line of itom. The different verbose levels are:

  • 0: nothing is printed to the command line

  • 1: error: only severe errors are displayed

  • 2: warning: errors and warnings are displayed

  • 3: info: errors, warnings and few information are displayed

  • 4: debug: this level contains all levels above including detailed information about the startup process as well as detected parameters of the device

  • 5: all: all information is printed including details about the state of all image buffers and reported changes in device-specific parameters.

In verbose level 5, both the zipper or unzipped xml configuration file of the camera (and framegrabber, if available) are saved to files on the harddrive. The filenames are printed to the command line of itom.

1.16.7. IDS Imaging Development Systems specific adaptions#

We recognized, that the device ID of IDS camera is not persistent and might change, e.g. after a re-initialization. Therefore, it is more convenient to start such a camera, as well as all other cameras, by their serial number instead of the device ID. To do this, use the deviceID initialization parameter and write “Serial:<your serial number>”. If the prefix “Serial:” is recognized, the rest of the string is used to detect a camera with this specific serial number instead of the device ID.

Additionally, IDS provides some easy cameras, which do (only) support IDS specific pixel formats, e.g. BayerRG10g40IDS (see https://www.1stvision.com/cameras/IDS/IDS-manuals/en/basics-raw-bayer-pixel-formats.html). itom supports the IDS specific color format BayerRG10g40IDS. Some camera sensors of IDS cameras have another specific behaviour, such that they deliver a certain amount of additional black lines at the beginning of every image. These additional lines are skipped by this plugin, such that the real requested image size is provided. The following rules are implemented:

1.16.8. Compilation#

In order to compile this plugin, download the latest GenICam(TM) GenApi reference implementation from http://www.emva.org/standards-technology/genicam/genicam-downloads/. Download the latest GenICam Reference Implementation (e.g. GenICamTM GenApi reference implementation v. 3.4.1.1). Open the Zip File and extract the SDK archive to a location of your licking ** (e.g. C:/Genicam/SDK). Open the Zip File and extract the Release-Runtime archive-sourcess to the same location.

Set the CMake variable GenICam_Dir or system environment variable GENICAM_ROOT to this base folder. After re-configuring CMake the other variables (e.g. GENICAM_GCBASE_LIBRARY…) should be found automatically.

1.16.9. GenICam License#

This plugin uses the official GenICam library to access the camera devices. Here is a copy of the GenICam license file:

GenICam comes in two versions

  • a runtime version

  • a development version.

The runtime version comes under the following license:

Copyright (c) EMVA and contributors (see source files) All rights reserved

Redistribution and use in source and binary forms, without modification, are permitted provided that the following conditions are met:

  • Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

  • Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

  • Neither the name of the GenICam standard group nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS “AS IS” AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

The development version comes under the GenICam license (see below).

GenICam uses the following 3rd party software packages:

Package

License

Internet

Mathparser

LGPL

http://kirya.narod.ru/mathparser.html

–

–

http://www.sama.ru/~despair/ccalc/

Log4Cpp

LGPL

http://log4cpp.sourceforge.net

CppUnit

LGPL

http://cppunit.sourceforge.net

CLSerAll

NI

http://sourceforge.net/projects/clallserial

xs3p

DSTC

http://xml.fiforms.org/xs3p/index.html

xxhash

New BSD

https://code.google.com/p/xxhash/

XSLTProc

MIT license

http://xmlsoft.org/XSLT/xsltproc2.html

XSDe

Proprietary

NA

Note that the XSDe license was purchased by one of the members of the committee but allows all members to re-compile the parser as long as only the GenApi XML vocabulary is used.

All license texts come as part of the GenICam distribution in the licenses subdiretory. If not, you can download them from the internet.

License

File

Where to find the license texts

LGPL

LGPL.txt

http://www.gnu.org/licenses/lgpl.html

GenICam

GenICam_License.pdf

http://www.genicam.org

CLSerAll

CLSerAll_LICENSE.txt

http://sourceforge.net/projects/clallserial

xs3p

xs3p_License.mht

http://xml.fiforms.org/xs3p/index.html

xxhash

xxhash_License.txt

http://opensource.org/licenses/BSD-3-Clause

XSLTProc

MIT_License.txt

http://opensource.org/licenses/mit-license.html

XSDe

XSDe License.pdf

NA

Last but not least GenICam redistributes the C/C++ runtime DLLs of the Microsoft Visual C++ compiler in the version 12.0

1.16.10. Changelog#

  • itom setup 3.1.0: This plugin has been compiled using GenICam 3.0.2

  • itom setup 3.2.1: This plugin has been compiled using GenICam GenAPI 3.1.0

  • itom setup 4.0.0: This plugin has been compiled using GenICam GenAPI 3.2.0

  • itom setup 4.1.0: This plugin has been compiled using GenICam GenAPI 3.2.0

  • itom setup 4.3.0: This plugin has been compiled using GenICam GenAPI 3.4.1.1

1.16.11. Workaround#

  • Vistek, GigE, Windows: It seems that the Camera Link transport layer library (cti-file) has to be loaded by itom before the GigE transport layer is loaded. This is implicitly done, if a vistek cti file is loaded. It is also possible to load the CL cti file using a load library command in Python.