GenICam Standard

The GenICam™ standard (Generic Interface for Cameras) provides a generic software interface for any kind of vision acquisition devices, independent of their hardware interface. It allows access to devices such as cameras or strobe controllers via a standardised interface, no matter which technology such as GigE Vision, CameraLink, CameraLink HS, CoaXPress or USB3 Vision-is used.

The GenICam standard consists of different modules, each addressing a specific part of a typical vision system:

GenTL: GENeric Transport Layer is the transport layer interface for enumerating cameras, grabbing images from the camera and moving images to the user application.
GenApi: GENeric Application Programming Interface enables listing and configuration of features available with a device.
SFNC: The Standard Features Naming Convention defines the name, type and behaviour of the device settings.

For more information refer the EMVA homepage: http://www.emva.org/standards-technology/genicam/

CVB Driver Structure

Compared to manufacturer specific SDKs Common Vision Blox with GenICam offers manufacturer independence and increased image acquisition functionality. Hardware compatibility is accomplished by supporting various acquisition technologies including any GenICam GenTL provider (transport layer). Being the GenICam GenTL standard maintainers we can assure best support for compliant GenTL providers.

‍Attention: With Common Vision Blox 13.3 the GenICam.vin driver interface has been extended by the new GenTL acquisition interface. This document will only describe the new GenTL interface. If you are still using the GenICam.vin, you will find a detailed description online documentation of CVB 14.0.

CVB Image Manager SDK
GenICam GenTL Consumer
GigE Vision GenTL Producer	USB Vision GenTL Producer	3rd Party GenTL Producer

The following acquisition device interface standards are generally used for new applications:

For cameras to connect directly to a PC:

GigE Vision
USB3 Vision

Supported Operating systems and other system requirements for the GenICam driver

Microsoft Windows 32-bit / 64-bit
Linux Ubuntu 64-bit
ARM 64-bit

For more details please refer to Release Notes chapter.

If possible use the newest CVB version because of many improvements in the GenICam package.

GenICam Driver Options

The GenICam driver options are described in the section Persistent Settings in GenICam Driver and should be set by your code. If you are using the deprecated vin driver, you can also set the option with the GenICam Browser (for further information about the deprecated vin driver got to the online documentation of CVB 14.0).

Transport Layer

Information about all supported Transport Layers (*.cti files) can be found in the GenICam Browser in the Available Devices window. In this example the STEMMER IMAGING CVB USB3 Vision (CVUSBTL) and the GigE Vision Transport Layer (GEVTL) are available.

For detailed information, please refer to:

GigE Vision
USB3 Vision
Other Transport Layer

Nodemap

A nodemap displayed in the Property Grid is part of the Transport Layer and therefore available for all GenICam compliant cameras. Nodemaps are based on the acquisition hardware *.xml file and structured in different ports:

DevicePort
DeviceTLPort
DataStreamPort
FactoryPort
InterfacePort
TLPort

If the device has no *.xml file in its memory a "Nodemap unavailable" message is returned when the device is opened. Be aware that setting a correct XML file for the device is a precondition, if there are problems, refer trouble shooting section.

For Parameter Reference refer to GenICam Standard, SFNC (Standard Features Naming Convention) part.

Get access to the nodemaps in your code:

⭐ Code Example

Get access to the nodemaps via GenICam Browser:

DevicePort

This is the port, which contains the nodemap for the device (remote device). It is the normal nodemap for all device features and is used by default.

In the CVB getter function for nodemaps it is referenced with Device.

DeviceTLPort

This is the port, which contains the nodemap for the device module of the GenTL. The device module represents the GenTL Producers' proxy for one physical remote device. The responsibility of the device module is to enable the communication with the remote device and to enumerate and instantiate data stream modules. The device module also presents signaling- and module configuration capabilities.

In the CVB getter function for nodemaps it is referenced with TLDevice.

DataStreamPort

This is the port, which contains the nodemap for the Data Stream module. A single (image) data stream from the device is represented by the Data Stream module. The purpose of this module is to provide the acquisition engine and to maintain the internal buffer pool. Beside that the Data Stream module also presents Signaling and module configuration capabilities.

In the CVB getter function for nodemaps it is referenced with TLDatastream.

Sample Code in C++: CameraConfig example

In the following two section nodes for buffer handling control and statistic nodes are described in detail.

Buffer Handling Control

Std::StreamAnnouncedBufferCount: These are the buffers known to the GenTL which can hold image data. Only known buffers can be queued (and thus filled with incoming frame data). This has direct influence on the amount of memory allocated by the driver to hold image data.
Std::StreamBufferHandlingMode: Available buffer handling modes of this Data Stream:
- OldestFirst: The application always gets the buffer from the head of the Output Buffer Queue (thus, the oldest available one).
Std::StreamAnnounceBufferMinimum: Minimal number of buffers to announce to enable selected buffer handling mode.
Std::StreamDeliveredFrameCount: Number of delivered frames since last acquisition start.
Std::StreamLostFrameCount: Number of lost frames due to queue underrun. This number is initialized with zero at the time the stream is opened and incremented every time the data could not be acquired because there was no buffer in the input buffer pool.
Std::StreamInputBufferCount: Number of buffers which, at a given point in time, can take new data. Only queued buffers can take new image data. Buffers, which are not queued, are basically locked.
In CVB, before grabbing starts, all announced buffers are also queued for acquisition. So until the first image starts the StreamInputBufferCount = StreamAnnouncedBufferCount.
While the first image is transferred the number of queued images is one less than at the start.
After the first image finished until the first call to wait for the next image to be acquired, the StreamInputBufferCount = StreamAnnouncedBufferCount-1 and the pending frames = 1.
After waiting for the image and before the second image starts StreamInputBufferCount = StreamAnnouncedBufferCount-1, delivered buffers=1, pending frames=0. And so on.
Std::StreamOutputBufferCount: Number of buffers in the output buffer queue.
Std::StreamStartedFrameCount: Number of frames started in the acquisition engine. This number is incremented every time a new buffer is started to be filled (data written to) regardless if the buffer is later delivered to the user or discarded for any reason. This number is initialized with 0 at at the time of the stream is opened. It is not reset until the stream is closed.
Std::StreamIsGrabbing: Flag indicating whether the acquisition engine is started or not. This is independent from the acquisition status of the remote device.

Statistics

Cust::NumBuffersInIncompleteList: Number of buffers which have been started to fill but are not yet done.
In case this (internal) incomplete list is full the buffer will, depending on the configuration of the driver, delivered as corrupt buffer to the host application or discarded.
In other words this counter indicates that a new frame arrived but the old one is not complete yet due to missing packets. It is only updated when packet resend is enabled.
Cust::NumFramesLostQueueUnderrun: This is a lost frame counter indicating that an new incoming frame from a camera could not be filled because no buffers where queued. This normally means that the processing is too slow and cannot keep up with the frame-rate of the camera.
Cust::NumFramesCorruptOnDelivery: Number of images which were corrupt (not complete) when delivered through waiting for next image to be acquired. A corrupt delivered image cannot/will not be completed after delivery.
Cust::StreamStartedFrameCount: The number of buffers taken from the input queue. This means the number of frames the GenTL tries to fill with incoming data.
Cust::FramesCorrupt: Number of images which were corrupt on arrival in the host no matter if or if not resend requests have been issued. This setting indicates if something is wrong with the transmission. In case the user wants to discard corrupt images he needs to configure his video interface/TL accordingly.
A corrupt image is an image which in the first run did not arrive properly.
This includes also images which for example had missing packets and which have been completed later on using resend requests.
So a corrupt image may not be corrupt on delivery because the transport mechanisms underneath corrected the failure.
Cust::NumPacketsReceived: This is related to GigE and indicates the number of data packets (not frames) received on the GigE Vision streaming channel. received.
Cust::NumResends: This is related to GigE and indicates the number of resend requests issued by the host. If this number increases it indicates that something is wrong with the data transmission.
Possible reasons may be: Settings of the network card, CPU-load on the host, cable/switch problems, bandwidth problems on the Link (only incremented if missing packets occur and packet resend is enabled).
Following examples show how to access features within a CVB program.

FactoryPort

This is the port which contains the NodeMap for the Factory.

In the CVB getter function for nodemaps it is referenced with TLFactory.

InterfacePort

This is the port which contains the NodeMap for the interface module. An interface module represents one physical interface in the system. For Ethernet based Transport Layer technologies this would be a Network Interface Card (NIC), for a Camera Link based implementation this would be one frame grabber board. The enumeration and instantiation of available devices on this interface is the main role of this module. The interface module also presents signaling and module configuration capabilities.

In the CVB getter function for nodemaps it is referenced with TLInterface.

python Code Example: DeviceConfiguration example

Action Control

Action Control allows sending "action signals" over ethernet to one or multiple devices in the network to trigger specific configured actions in the device.

Device Key (Std::ActionDeviceKey): Must be equal on the camera and on the host PC. Before a camera accepts an Action Command, it verifies if the received key is identical with its configured key
Group Key (Std::ActionGroupKey): Each camera can be assigned to exactly one group for each available action. All grouped cameras perform an action at the same time. If this key is identical on the sender and the receiving camera, the camera performs the assigned action.
Device Mask (Std::ActionGroupMask): Serves as a filter that specifies which cameras within a group react to an Action Command. It can be used to create sub-groups. To react to an Action Command, the value in the camera must have one bit in common with the received value from the sender. You can define different Group Masks for each action.
Action Command (Std::ActionCommand): Sends the configured command.

Please refer to the manual of your camera for more information on how to setup Action Control for your needs.

TLPort

This is the port which contains the NodeMap for the system module. For every GenTL Consumer the system module as the root of the hierarchy is the entry point to a GenTL Producer software driver. It represents the whole system (not global, just the whole system of the GenTL Producer driver) on the host side from the GenTL libraries point of view. The main task of the system module is to enumerate and instantiate available interfaces covered by the implementation. The system module also provides signaling capability and configuration of the module's internal functionality.

In the CVB getter function for nodemaps it is referenced with TLSystem.

User Nodemaps

Unlike previous nodemaps, such as DeviceTL nodemap, the VinDevice nodemap and VinBuffer nodemap are not displayed in the property grid, even though they are available for all GenICam-compliant cameras. These parameters can be individually tuned by users, enabling them to customize camera settings to their liking.

VinDevice Nodemap

This user nodemap aims to configure the device and its corresponding driver settings. A user can read and adjust parameters of a device opened through CVB in the 3rd acquisition stack (GenTL) only. The nodemap includes features related to TurboDrive and chunk data transmission.

The following list describes all available nodes:

AttachChunk (Cust::AttachChunk): This node controls attaching chunk data to the buffers. This is the pendant to the .ini file configuration AttachChunk. The boolean value set to true enables the chunk transmission - if the device is able to.
TurboDrive Nodes
- TurboDriveEnabled (Cust::TurboDriveEnabled): This node indicates the activation of the TurboDrive transmission, if its value is true, TurboDrive is enabled and otherwise, it is disabled.
- TurboDriveAlgorithm (Cust::TurboDriveAlgorithm): This node indicates the selection of the two options of TurboDrive versions. TurboDrive Version 1 is always lossless, but does not guarantee a bandwidth, and TurboDrive Version 2 may be lossy, but has guaranteed bandwidth.
- Quality (Cust::Quality): The Quality node indicates the Level for even lines or the global quality level for mono images. The quality level sets the lowest bits per pixel to be discarded. The value is of type integer and legal values are between 0 and 6, with 0 indicating always lossless encoding and 6 the highest level compression. A high value is not necessarily lossy, but more likely to be lossy.
- QualityOddLines (Cust::QualityOddLines): This node is for Quality Level for odd lines in bayer images. Its properties are same as Quality node for even lines.

VinBuffer Nodemap

The VinBuffer nodemap provides means to gather information about a single buffer returned by the stream wait function. It is - also - only available in the 3rd generation acquisition stack (GenTL).

The following nodes are retrievable through the nodmap:

Cust::FrameID: The unique ID of the frame (or image) that is transported in the corresponding buffer (if applicable).
Cust::IsIncomplete: Indicates a corrupt buffer. In case of incomplete transmission (such as if there are missing packets), the number of bytes successfully written to the buffer are reported in the SizeFilled node.
Cust::SizeFilled: The total number of bytes written into the buffer. In case of incomplete transmission (such as if there are missing packets), this shows the number of bytes successfully written to the buffer.
Cust::Timestamp: Timestamp (UINT64) the buffer was acquired. The unit is device/transport layer dependent. In case the technology and/or the device does not support this, this nodes value is not available.

Here is an example of how you might use the VinDevice to check the activation of TurboDrive and VinBuffer nodemap to check for indication of a corrupt buffer:

import os
import cvb
 
discovery_information = cvb.DeviceFactory.discover_from_root(cvb.DiscoverFlags.IgnoreVins)
device = cvb.DeviceFactory.open(discovery_information[0].access_token,
    cvb.AcquisitionStack.GenTL)
 
vin_dev_node_map = device.node_maps["VinDevice"]
# This node's value set to True or False indicates activation or deactivation of TurboDrive compression
print(vin_dev_node_map.TurboDriveEnabled.value)
print(vin_dev_node_map.TurboDrive.verify_mode)
print(vin_dev_node_map.nodes)
 
stream = device.stream(cvb.ImageStream,0)
stream.start()
for i in range(10):
    image, status, nodemap_enum = stream.wait()
    
    vinbuffer_nodemap = nodemap_enum["VinBuffer"]
    # This node's value indicates a corrupt buffer
    print(vinbuffer_nodemap.IsIncomplete.value)
    print(vinbuffer_nodemap.nodes)

Camera XML file

Getting GenICam XML information

A GenICam device is always equipped with a certain version of firmware. Every firmware revision has a dedicated XML file to describe the abilities and features of the device. When opening a camera its XML file is going to be read when the device is plugged in for the first time. The downloaded structure serves as the base for the property grid (Nodemap).

Set the XML file

To set a new XML file, run the EditBindings console application. With this console application you can see the current linked *.xml file and you can add/delete/bind a new XML file. For future access to the device, the XML file is saved within a database on the host machine and loaded automatically whenever the camera is connected. Camera xml files for Common Vision Blox are saved under %CVBDATA%GenICam\xml\Registry\Files (Windows) and /var/opt/cvb/GenICam/xml (Linux). It is possible that an XML file is changed over time by the vendor to simplify the interface, while the firmware remains the same. It then suffices to set the new XML file with the CVB EditBindings application since the internal functionality remains the same. In case a new revision of camera firmware is published, it is generally distributed by STEMMER IMAGING with further remarks about the changes made as well as the installation procedure. If you don't find an appropriate update please contact our technical support.

Trouble Shooting

If something is GenICam compliant does it need to be GigE Vision Compliant?
The camera is not seen in the GenICam Browser
I can open the camera in the GenICam Browser but get a white picture
I can open the camera in the GenICam Browser but get a flickering picture
Image contains a logo or is complete grey
Error message: Nodemap unavailable
I get a large number of lost frames
The acquired images show defects
I can acquire images but the GigEVision events from the camera are not fired
GigE Cameras disappear in the GenICam Browser
Occasionally Time Out errors when performing image acquisition with Software Trigger
How can I discard corrupt frames in the driver?
How can I find the installed transport layer ?

If something is GenICam compliant does it need to be GigE Vision Compliant?

GenICam is frequently called the compatibility layer. A device which is GigE Vision compliant must by definition also be GenICam compliant since GigE Vision and USB3 Vision has a mandatory reference to GenICam. So in a way the use of the GenICam layer is what distinguishes GigE Vision and USB3 Vision from plain GigE/USB3. The reverse, however, is not the case: GenICam may in principle also be applied to other transport technologies.

Note, by the way, that the "Vision" bit in "GigE Vision" and "USB3 Vision" has lower-level implications as it defines the expected format of the packets sent back and forth on the physical infrastructure.

The camera is not seen in the GenICam Browser

For GigE Vision make sure the IP addresses of both the camera and the NIC the camera is connected to, are on the same subnet,if you have multiple NIC's in the system make sure they don’t share the same subnet's. Otherwise this can result in unpredictable behavior. Refer GigE Vision checklist.

For USB3 Vision please ensure that USB 3.0 ports are used and all other hardware requirements are fulfilled. Refer USB3 checklist. Seldom it could be necessary to delete the GenIcam XML file and directory manually: %CVBDATA%GenICam and start the application again. For all other vision hardware components (cameras, grabber) ensure that the necessary software and driver is installed.

I can open the camera in the GenICam Browser but get a white picture

Change the Display Engine type from OpenGL to Raster. Display Engine can be changed only if no device is open. If the selection is disabled, all devices must be closed.

I can open the camera in the GenICam Browser but get a flickering picture

This can occur with high performance cameras or multi-camera scenarios which are producing pictures with a higher bandwith than the communication link is able to transfer (GigE Vision, USB3 Vision).
Cameras transfers empty pictures as soon as a bottleneck is detected. This can be observed with the flickering effect on freerun pictures in CVB and watching the Data Stream Port statistic values. Exposure time adaption, Framerate decreasing to a value matching the transfer capabilities and optimizing the network configuration for GigE hardware should solve the problem.

Image contains a logo or complete grey images ( value 128) appear

If the cameras are not licensed via CameraSuite or any other valid Image Manager license like a dongle, a Node-locked or Triallicense there are sent some kind of distorted images. This could be either a logo as a watermark in the left top part of the image:

or that grey images with a grey value of 128 appear from time to time. Additional there appears a red text overlay in the display which says " Common Vision Blox evaluation".

Error message: Nodemap unavailable

If the device has no XML file in its memory "Nodemap unavailable" message is returned when a device is opened. Be aware that setting a correct XML file for the device is a precondition - so it has to be (re)generated. Availability, version and binding information of a camera GenICam XML-file can be checked with the EditBindings application. Sometimes it could be necessary to backup and delete the GenIcam XML file and directory manually: %CVBDATA%GenICam and start the application again.

I get a large number of lost frames

Check the hardware components and configuration if they inter-work with the camera configuration and capability. Most problems are caused due to unsatisfactory performance.

The acquired images show defects

If sections of the acquired images are missing or random noise is visible, the reason is probably a transmission problem. The following image shows an example of this type of transmission problems:

Maybe you see black lines or lines with old image data. Check the hardware components and configuration if they inter-work with the camera configuration and capability. Please refer the corresponding chapters in this User Guide for optimization.

I can acquire images but the GigEVision events from the camera are not fired

Disable the firewall. Enable the events with the EventNotification feature.

GigE Cameras disappear in the CVB GenICam Browser

The system was already working and without changing anything the GigE camera does not appear any more in the GenICam Browser. But it is possible to PING the camera. Means IP configuration and camera is OK. Solution: Please delete the following file in the CVB Root path ..\Genicam\Registry\xml\db.xml Restart the CVB GenICam Browser and you should see the GigE camera again connected.

Occasionally Time Out errors when performing image acquisition with Software Trigger

This problem may occur mainly on cameras with high data rate. Check the hardware components and configuration if they inter-work with the camera configuration and capability. Please refer the corresponding chapters in this User Guide for optimization.

How can I discard corrupt frames in the driver?

By default corrupt frames are passed thrue the driver. You can disable pass corrupt frames with the DataStream Nodemap of the driver. In the NodeMaps section you can read how to access the DataStream Nodemap. There is also an example in C++ how to discard corrupt frames.

How can I find the installed transport layer?

Transport Layer environment variable: GENICAM_GENTL64_PATH to find all *.cti files

Windows: can be checked with cmd shell command "set": refer screen shot example below

Linux: can be also checked with cmd shell command "env": e.g. GENICAM_GENTL64_PATH=/opt/cvb/drivers/genicam


Contact Legal Privacy Statement	Copyright © 2024.
	All rights reserved.

Table of Contents