Image Acquisition Interface for GigE Vision compliant cameras

This page provides the documentation of the universal HALCON GigEVision2 interface for accessing all GigE Vision compliant cameras. Registered customers can download the latest revision of this interface from the MVTec WWW server.

(This GigEVision2 interface replaces the old, deprecated HALCON acquisition GigEVision interface. Users switching from the previous implementation of the GigEVision acquisition interface to this new version, GigEVision2, please pay attention to the section highlighting differences between the two interface versions for easy transition).

• Intel compatible PC with Windows 7 (32-bit or 64-bit) or newer, also WoW64 (using 32-bit HALCON on 64-bit Windows), Linux with kernel 2.6 (or higher) , or macOS.
• Gigabit Ethernet network adapter. It is recommended to use a PCIe network adapter which supports Jumbo frames. Please configure the network adapter accordingly, e.g., to a MTU value of 9000, to reduce the amount of interrupts. Furthermore, the camera should be connected directly to the network adapter to avoid interference with other network traffic. Please be aware that networking equipment like switches not necessarily supports Jumbo frames.
• If you are using a firewall please make sure that your firewall configuration allows your application or HDevelop to connect to the camera and to receive incoming images, otherwise the grabbing will fail. Cameras that support firewall traversal might work anyway.
• For devices with GigE Vision 3.0 RDMA streaming support:
  • Windows: network adapter with RDMA/RoCEv2 support under Windows. Up-to-date drivers must be installed including the NDSPI interface (Windows user mode RDMA/RoCEv2 support). Refer to the network adapter manufacturer documentation for details.
  • Linux: network adapter with RDMA/RoCEv2 support under Linux. Up-to-date drivers/firmware must be installed. Up-to-date versions of the ibverbs and rdmacm libraries must be installed including corresponding ibverbs provider for given adapter. Refer to the network adapter manufacturer documentation for details.
  • macOS: RDMA/RoCEv2 is not supported by the macOS operating system.
• MVTec GigE Vision Streaming Filter under Windows x86, WoW64 or Windows x64: The HALCON GigEVision2 interface automatically uses a filter driver to enhance the performance while streaming images. When installing HALCON the filter driver will be automatically installed, if you enable the corresponding check box during installation.
  Please make sure that at least the driver version v2.1.8.0 is actually installed (check your network properties). Older driver versions will not work! For full functionality you need driver version v2.2.8.4.
• GenICam GenApi. The corresponding files are part of the HALCON GigEVision2 package and are located in the directory genicam within the HALCON base directory %HALCONROOT%. See section GenICam GenApi for more details.
• Windows: HALCON image acquisition interface hAcqGigEVision2.dll or hAcqGigEVision2xl.dll, respectively. If you have properly installed the interface, all these DLLs should reside in bin\%HALCONARCH% within the HALCON base directory %HALCONROOT% you have chosen during the installation of HALCON.
  Linux: HALCON image acquisition interface hAcqGigEVision2.so or hAcqGigEVision2xl.so, respectively. If you have properly installed the interface, the shared objects should reside in lib\$HALCONARCH within the HALCON base directory $HALCONROOT you have chosen during the installation of HALCON.
  macOS: HALCON image acquisition interface hAcqGigEVision2.dylib or hAcqGigEVision2xl.dylib, respectively. If you have properly installed the interface, the shared objects should reside in the HALCON framework /Library/Frameworks/HALCON.framework or the HALCON XL framework /Library/Frameworks/HALCONxl.framework in the Libraries subdirectory.
• The default acquisition mode assumes the computer is fast enough to process all buffers from the camera. If this is not the case, they are silently discarded.

The interface can be controlled through several environment variables:

• HALCON_ACQUIRED_FILE_PAYLOAD_DIR is used to specify the directory where non-image payload types (usually files or 'raw' data) are stored using the filename given by the device.
• When specifying a directory with HALCON_GENICAM_WRITE_XMLFILE and/or HALCON_GENICAM_WRITE_RAW_XMLFILE, the GenICam description files (in XML and/or raw format) will be stored there while working with HALCON. These files can also be stored by setting the interface parameter 'do_write_configuration'.
• If you want to use an already installed GenApi version instead of the one supplied with HALCON, you must set the environment variable HALCON_USE_EXTERNAL_GENAPI. Additionally, all environment variables which are necessary for GenApi must also be set in this case. This is only for experts, see also section GenICam GenApi.

MVTec interfaces for digital I/O and image acquisition are always compatible to a range of HALCON versions. Therefore, the versioning scheme both describes the compatibility of the interface and also the revision of the interface itself. An interface version always consists of three numbers, separated by dots, i.e. 24.11.5. The first two numbers describe the minimum HALCON version the interface is compatible with. For the example version 24.11.5 this means that the interface is compatible with all HALCON versions since HALCON 24.11. The last number describes the revision of the interface, in this example this is revision 5.

Only when installing or updating the interface manually follow these steps:

• Windows: Extract the archive containing the interface files to the HALCON base directory %HALCONROOT% (Note: Administrator privileges may be required for this step). Additionally, you have to move the interface examples to the directory %HALCONEXAMPLES% manually.
• Linux: Extract the archive containing the interface files to the HALCON base directory $HALCONROOT.
• OS X: Extract the archive. Manually move the following files:
  • The .dylib files located in lib/x64-macosx to /Library/Frameworks/HALCON.framework/Libraries or /Library/Frameworks/HALCONxl.framework/Libraries repectively.
  • The genicam folder to /Library/Frameworks/HALCON.framework/Libraries or /Library/Frameworks/HALCONxl.framework/Libraries respectively.
  • The examples folder to the version subdirectory at /Users/Shared/Library/Application Support
  • The doc folder to the version subdirectory at /Library/Application Support

• User-space implementation of the GigE Vision protocol.
  For Windows the MVTec GigE Vision Streaming Filter is available and used if installed to improve performance.
• Support for GigE Vision 1.0 up to 3.0.
• Support of RDMA streaming over the RoCEv2 protocol.
• Support of GenDC streaming.
• Grabbing from multiple cameras.
• Synchronous and asynchronous grabbing.
• Grabbing of 3D data and creation of object model 3d.
• Support of Jumbo frames and automatic packet size optimization.
• Software control of all generic camera parameters using GenApi.
• Software control of transport layer-dependent parameters.
• Support of various pixel formats and flexible color transformation.
• No Administrator or root privileges required, except for the installation of the filter driver (and internal thread priority control).
• Support of Forced IP.
• Support of 'Continuous', 'SingleFrame', and also 'MultiFrame' acquisition modes.
• Support of GenICam action control.
• Support of GenICam chunk data.
• Support of GenICam event data.
• Support of GenICam feature persistence.
• Support of GenICam file access.
• Support of GenICam FWUpdate.
• Support of callbacks for feature change notifications.
• Support of non-streamable devices (devices that can be controlled by means of GenICam, but do not stream any image (or other) data.
• Support of pending acknowledges which allow to wait for device response to long taking commands without needing to manually adjust the timeout.

• The MVTec GigE Vision Streaming Filter is available only under Windows. For more details see paragraph MVTec GigE Vision Streaming Filter.
• Only stream channel 0 supported.
• No support of acquisition from devices with read-only access mode.

• This interface implements GigE Vision specification version 2.2 and the latest draft of version 3.0, covering all three basic protocols it defines: control, image/data streaming and asynchronous device events.
• The interface supports GenDC streaming used e.g. by 3D devices.
• The interface is also fully compatible with older cameras implementing the GigE Vision 1.0, 1.1 or 1.2 standard.

• This interface uses GenApi version 3.5.0, for more details refer to the GenICam homepage. The corresponding files are part of the HALCON runtime installation and are located in the directory genicam within the HALCON base directory %HALCONROOT% or $HALCONROOT, respectively. This version is the same as the officially released version at the time of writing.
• The HALCON GigEVision2 interface sets all necessary environment variables on its own and ignores other installed GenICam packages by default.
  If you want to use another GenICam package, you need to set the environment variable HALCON_USE_EXTERNAL_GENAPI. This skips the step of setting all necessary variables and paths internally, so you have to make sure they are set correctly. Please note that it might not be possible to use different GenApi versions with different interfaces at the same time and that you must use the required GenApi version for this interface.
• The caching of device XML files is activated to speed up processing, writing to a temporary directory subject to availability of %TEMP%, %TMP%, $TMPDIR, /tmp or %HALCONROOT%.
• The remote device control features as well as the GigE Vision Producer control features of this interface are controlled via GenApi.

To ensure full access to the device, the following preconditions have to be fulfilled:

General:

• If a firewall is active in the system, it has to be configured in a way so that all applications expected to be using the GigE Vision devices (e.g. HDevelop, but also any user-developed applications) have full access to the connected devices. Cameras that support firewall traversal might work anyway.
• If possible, guarantee that the used devices are configured properly to match IP configuration of the network interface they are connected to (either by means of Persistent IP configuration of the device or by means of DHCP).
• If the device's IP configuration does not match that of the network interface the device is connected to, the HALCON GigEVision2 acquisition interface will discover the device, but will mark it as inaccessible and opening it will not be possible.
• If you are using the HDevelop Image Acquisition Assistant, it will automatically prompt you to add the correct generic parameter to force a suitable temporary IP address to the device. Please keep in mind that this temporary IP address will not survive the device's power cycle. It is still desirable to configure the device properly (Persistent IP or DHCP) so that it starts with suitable IP configuration upon next power up.

Linux:

• On Linux, the discovery of misconfigured (wrong subnet) devices might not be possible if 'reverse path filtering' is switched on in the system. Reverse path filtering is a security option dropping incoming packets on the interface if the reverse path traffic (to the source of the incoming packet) would not be routed on that interface. In practice this means that the discovery packet where the device announces itself would be dropped. To prevent this, we recommend to switch off reverse path filtering option on any interfaces where GigE Vision devices are to be discovered (perhaps unless you are sure that the devices will never be misconfigured). To temporarily disable reverse path filtering on eth0, execute
  sudo sysctl -w net.ipv4.conf.all.rp_filter=0
  sudo sysctl -w net.ipv4.conf.eth0.rp_filter=0
  To make the changes permanent, adjust these options in the sysctl configuration file (such as /etc/sysctl.conf or /etc/sysctl.d tree):
  net.ipv4.conf.all.rp_filter=0
  net.ipv4.conf.eth0.rp_filter=0

The GigE Vision standard versions lower than 3.0 recognize only one stream type, called GVSP (GigE Vision Streaming Protocol) which transports the stream data over GigE Vision specific packets. GigE Vision 3.0 introduces a new stream type transporting the stream using Remote DMA (RDMA) technology, in particular using the Remote DMA over Converged Ethernet version 2 (RoCEv2) protocol. RoCEv2 offers hardware-offloaded, zero-copy data transfers and is defined within the InfiniBand specification.
The RDMA streaming requires dedicated hardware with RoCEv2 support including full integration in the operating system (see system requirements).
The HALCON GigEVision2 acquisition interface automatically selects the stream type to use:

• If the device supports GigE Vision RDMA streaming and is connected to a network adapter supporting RDMA/RoCEv2 on the given system, the RDMA stream type will be selected.
• Otherwise the GVSP stream type will be used if the device supports it.
• If the device supports only RDMA streaming, but is connected to a network adapter without RDMA/RoCEv2 support on the given system, the GigEVision2 acquisition interface cannot choose either of the stream types and the device will be treated as non-streamable. It will be possible to control the device parameters, but acquisition using the grab operators will not be possible.

• For Windows x86 and x64 a so-called 'filter driver' is available. It is used automatically, if it is installed and activated. This kernel mode driver enhances the performance and should be used if possible. Applicable for devices using the GVSP stream type (see GVSP vs. RDMA stream types).
• Installation:
  When installing HALCON the filter driver will be installed automatically, if you enable the corresponding check box during installation.
  The filter driver can also be installed separately. The necessary installer can be found in %HALCONROOT%\misc. If you downloaded the GigEVision2 package individually from the MVTec website, the filter driver installer can be found in the subfolder misc inside the package. To install, close all your network connections and execute the installer as administrator. It will install and enable the filter on all your Ethernet interfaces. The driver files will additionally be placed in %HALCONROOT%\..\GevStreamingFilter.
  To disable the filter for a specific interface, you can deselect the 'MVTec GigE Vision Streaming Filter' in the network interface properties. The filter driver can be uninstalled completely by the uninstaller in %HALCONROOT%\..\GevStreamingFilter. To do this, close all your network connections and execute the uninstaller as administrator.
  Please reboot after the installation of the driver to make sure it can be used.
• Update Installation:
  When updating the GigEVision2 interface and a new version of the filter driver is included, you should also update the driver. Check the version number of the 'GevStreamingFilter' installer inside the misc subfolder of the package and compare it with the version found in the network interface properties. Then, if necessary, de-install the old version first before installing the new version (see instructions above). Please reboot to make sure the new version will be used.
• Versioning:
  The filter driver version number has 4 digits. The first two digits indicate the maximum GigE Vision standard that is supported. The third digit indicates the major version, which is used by the GigEVision2 interface to decide if binary compatibility is given (i.e. if the filter driver can be actively used). The fourth digit is the minor version, indicating that internal changes have been made to the driver.
  Example:
  2.2.x.x = Cameras with features according to the GigE Vision Standard 2.2 are fully supported by the driver. Older versions of the standard are always included.
  x.x.8.1 = Major version 8, minor version 1. If the GigEVision2 interface expects a major version 8 the driver will be used. This is reflected in the parameter [System]GevTLSubsystemInfo, which would for example display filter driver: 2020803/2010802. This means the native version for the GigEVision2 interface is 2.2.8.3, installed on the system is the driver version 2.1.8.2, compatibility is given because x.x.8.x == x.x.8.x. If on this system a version x.x.7.x were installed, it would not be used. We strongly recommend to always update the filter driver, such that also the minor version matches.
• Note that the filter driver is officially signed with Microsoft Authenticode, but not WHQL-certified, i.e., the installation might warn that the driver is not Windows logo certified. This warning can be safely ignored.
• The generic parameter 'force_sockdrv' is available, when it is necessary to disable the use of the filter driver for a specific device.
• The parameter '[Stream]GevStreamActiveEngine' can be queried to check if a specific device uses the filter driver.
• The filter driver may run out of kernel memory, although there is enough free user memory. Please decrease the generic parameter 'num_buffers' in this case.
• If the filter driver cannot be used, the underlying GVSP streaming is performed in user-space by the socket driver which increases the CPU load.
• When using the MVTec GigE Vision Streaming Filter some parameters behave different from socket driver as documented.

• The recommended way of using multiple cameras is to attach each camera to its own interface.
• If cameras share a single interface, you need to calculate the resulting load on the link. You can do this roughly, if you multiply the size of one image with the frame rate. This means, e.g., for a VGA gray-scale image with a depth of 8 bit per pixel and a frame rate of 100 frames/s:
  640*480*1 Byte*100/s = 3072000 Byte/s or about 30 MByte/s
  As a GigE link can transport about 120 MByte/s, theoretically 4 cameras can be attached to one link, in practice it might be limited to 3 cameras. The reason for this smaller number is the overhead for the GVSP protocol and maybe necessary resends, which the above calculation does not take into account. Also depending on the behavior of the camera and the network interface the single packets of the frames (also called blocks) are sent as a burst or equally distributed over a frame time.
  Additionally, the behavior of the necessary network equipment, like a switch, needs to be taken into account and might result in using small packets and even loss of packets.
  In such case adjusting network relevant parameters like device's inter-packet delay might be necessary to improve the performance. When in doubts, follow also performance related recommendations of the corresponding device manufacturer.

The connection to the (acquisition) device is established through the open_framegrabber operator. The operator provides a set of parameters allowing to configure the basic properties of the device and how the HALCON GigEVision2 interface controls it – see corresponding section. Some of the parameters can be also modified at runtime through set_framegrabber_param. This section concentrates solely on the 'Device' parameter of open_framegrabber, identifying the device (usually camera) that should be opened.
A connection to the device accessible through the GigEVision2 interface is established using the device ID which is guaranteed to be unique per GigE Vision device and (usually) stays persistent across multiple sessions. Optionally, the connection can be further defined through the interface ID, defining a single network interface of the host to be used for device lookup. Instead of the unique device ID, the user-defined name attached to the device can be used. Finally, it is also possible to use the IP address of the device or its serial number.
The list of all devices currently available in the system can be at any point obtained using info_framegrabber parameter 'device' or 'info_boards' – see corresponding section. Both parameters return a list of devices, each specified using the above listed entities in the format ' | device:<device id> | ... | interface:<interface id> | ... ', where '<device id>' is either the unique device ID or a user-defined name ('DeviceUserID'). If a user-defined name is set on the device, the string obtained by info_framegrabber will contain the entry 'user_name:<user-defined name>'. To make it easier for the user, the 'device' entry reflects the user-defined name if it is unique. If the same user-defined name is assigned to more than one device, only the first one will use it, all others will use the unique name instead. The full string (obtained from the info_framegrabber call) can be directly used for the 'Device' parameter of open_framegrabber, it uses the same format. As shown above, it consists of entries of the form 'token:value', separated by ' | '. The 'device' entry is the most significant one. The optional 'interface' entry specifies the network interface to look for the device.
Alternatively you can specify the device directly. For this, one or more of the entries can be omitted (or specified as 'default') - which behaves like using wildcards, meaning that the particular ID for that entity should not be considered (any ID would match). Only the ' | device:<device id>' string entry is important for open_framegrabber, the others are ignored and might be omitted. In addition to the device ID, devices can be opened by their alternative identifiers: user-defined name (specify the device using string in format 'user_name:<user_defined_name>'), IP address ('device_ip:<device_ip>') or the serial number ('device_sn:<device_serial_number>').
When a pure string without any 'token:' and without the ' | ' separator is used, it is interpreted directly as the device ID.
As a special case, the string 'default' can be used – in this case the HALCON acquisition interface will use the first available device (devices currently reported as non-accessible will be skipped). When using the same 'default' string again, that device will no more be accessible, therefore the next accessible device will be opened. This way, all devices connected to the system may be easily opened in a loop.

Note that the current version of the interface supports only single-stream devices and the first available stream is always open. If support for devices with multiple image streams will be added in future, the format to open the device might be extended with the stream entry.

The features of a device or GigE Vision Producer are described by GenICam feature description files (XML files) that are automatically parsed and offered to the user. The HALCON GigEVision2 image acquisition interface provides access to the features exposed through the following GenICam feature description files:

• Features of the connected device ("remote device"), typically a camera, are usually loaded directly from the connected device.
• Features of the GigE Vision Producer are exposed through a set of GenICam description files, one for each internal entity to control the device tree:
  • The "system" – representing the overall behavior of the acquisition interface
  • The interface used to connect the device to the system.
  • A proxy (called "local device") to the device, controlling the GigE Vision Producer view of the device.
  • The data stream used for the acquisition (if the device provides any data streams).

In most cases the GenICam description files are provided by the device and the GigE Vision Producer. It is possible to store a copy of these files corresponding to an open connection by using the parameter 'do_write_configuration' (see set_framegrabber_param). The command will write all the GenICam description files and an "ini" file (details in set_framegrabber_param) with various information, including the location of the written GenICam description files, in the following format:

 
RemoteFile=%PATH_TO_GENICAM_FILE_OF_THE_DEVICE% 
SystemFile=%PATH_TO_GENICAM_FILE_OF_THE_SYSTEM_MODULE% 
InterfaceFile=%PATH_TO_GENICAM_FILE_OF_THE_INTERFACE_MODULE% 
DeviceFile=%PATH_TO_GENICAM_FILE_OF_THE_LOCAL_DEVICE_MODULE% 
StreamFile=%PATH_TO_GENICAM_FILE_OF_THE_STREAM_MODULE% 

The same ini-file format can be reused to force the HALCON acquisition interface to load an alternative XML file for one or more of these entities. This can be useful, e.g., for updates or troubleshooting. The files listed in the ini file will be used for the given entity instead of the original ones. For the entities excluded from the ini file, the GenICam description file will be searched and loaded the usual way. To apply the ini file, pass its full path to open_framegrabber in the 'CameraType' parameter.

Note that the ini-file can be reused also for other purposes such as storing/restoring configuration as described in Parameters – Persisting Device Status. Be aware that when persistence files are specified, they have priority over other explicit settings passed to open_framegrabber.

The following groups of parameters exist:

• Internal parameters of the MVTec GenTL Consumer itself (GenICamTL acquisition interface). These are named following the "underscore" naming style, e.g., color_space, and are all lowercase. However, MVTec EasyParams are prefixed with "[Consumer]", e.g., [Consumer]gain.
• GenICam-based parameters of the device, usually a camera, use by convention the "CamelCase" style, e.g., ExposureTime.
• GenICam-based parameters of the individual GigE Vision Producer modules (system, interface, device and data stream) use by convention the same style but are prefixed with the module name in square brackets. Beware that the system and interface modules might potentially be shared by multiple opened devices, so changing their configuration might have side effects on other connections as well. The following prefixes are used:
  • "[System]", e.g., [System]TLVendorName.
  • "[Interface]", e.g., [Interface]InterfaceType.
  • "[Device]", e.g., [Device]DeviceID.
  • "[Stream]", e.g., [Stream]StreamBufferHandlingMode.

The parameters belonging to the system and interface modules of the GigE Vision Producer (i.e. those with "[System]" and "[Interface]" prefix see Parameters – Naming Conventions ) must be treated in a special way.
To grasp their behavior, it is important to understand that they do not describe or configure the device itself and do not thus fully belong to the opened instance of the device.
The interface module parameters belong to the interface on which given device was discovered and is shared among all devices open under this interface (see also Identifying and Opening a Device). The system module parameters belong to the entire GigE Vision Producer and are shared among all devices open within this GigE Vision Producer.
This has several implications. In particular, when accessing the system or interface module parameters through multiple device instances, those parameters must be treated as shared resources. Modifying those parameters through one device instance affects their values (and possibly values of other features depending on them) as seen through other device instances. Initial values of those parameters after opening a device instance might depend on the interactions with these features from previously opened device instances.

HALCON native parameter types are

• integer – signed integer, 64-bit on 64-bit platforms, 32-bit on 32-bit ones
• real – floating point type
• string – classical string

When accessing GenICam-based features, the GenICam data types must be mapped to the parameter types recognized by HALCON. GenICam offers the following types:

• IInteger – integer value, mapped directly to HALCON's integer parameter type. It will also accept real parameters. When the GenICam feature in question has a representation associated that identifies it as IPV4Address, MACAddress or HexNumber, the corresponding string representation will also be accepted. It should be highlighted that a problem can occur when running HALCON on a 32-bit platform (where integer parameters are 32-bit wide) and accessing a GenICam feature that is naturally 64-bit. In such cases the full range of the feature will not be available to the application and its value might be truncated. Also the sign of the parameter might be misinterpreted. To solve this problem, the parameter 'split_param_values_into_dwords' can be used. This maps the 64-bit IInteger value into two 32-bit integer values and vice versa.
• IFloat – floating point value, mapped directly to HALCON's real parameter type. It will also accept integer parameters.
• IString – string value, mapped directly to HALCON's string parameter type.
• IBoolean – boolean type is handled through HALCON's integer parameters, a value of 0 (zero) means logical false, other values mean logical true.
• IEnumeration – enumeration is a type that allows selecting from a set of values that are primarily identified by their name (the values are called 'enum entries'). Enumerations are interfaced through HALCON's string parameter type, while the enum entry names are used as the parameter values.
• ICommand – The command type allows to "execute" actions. To execute a command, use set_framegrabber_param with an integer parameter of any value (the value is ignored). Some commands' execution might take longer time and the command provides feedback when it is done. To query the status, use get_framegrabber_param for that command. It will return an integer value of 1 if it "is done" (command execution has finished), 0 if it has not finished yet. Note that if some other features are designed to be dependent on the command, querying the "is done" status might be essential to get the depending features invalidated (and updated with new values) as soon as the command execution finishes.
• IRegister – The register data type is used for plain memory blobs that cannot be mapped to any other data type. They are interfaced through HALCON's string parameter type, the register value is the hexadecimal string representation of the register's memory.

The current status of the acquisition device settings (values of all the parameters defining its working state) might be persisted while no acquisition is active, i.e. before grab_image_start or grab_image_async or after set_framegrabber_param(..., 'do_abort_grab', 1). This applies not only to actual device parameters, but also to parameters configuring the GigE Vision Producer and internal parameters of the GigEVision2 image acquisition interface. Device parameters are usually kept until the device is powered down. The GigE Vision Producer modules and the Consumer parameters are kept until close_framegrabber is called. To indicate which parameters to persist, use the parameter 'settings_selector'. The persistence functionality consists of two steps, storing the current configuration to a file and later re-loading it back to the device. The selected module settings, indicated by 'settings_selector', can be stored using the 'do_write_settings' parameter and re-loaded later using the 'do_load_settings' parameter, specifying the desired persistence file path in both cases. To query if a feature can be persisted use the postfix '_streamable'.

Note that while the format of the files is intentionally human readable and the files can be hand-modified if desired, such modifications should be done with care by someone familiar with the GenICam persistence functionality internals and given device. Improper modifications of the files can lead to errors when using it.

It is important to know that while performed by the software, persistence of the device-related features is actually a device-side function. If the persistence support is implemented incorrectly or incompletely by the device, it will not work as expected – in such a case the manufacturer could provide additional information or help.

The persistence related operations might be blocked by the device and/or GigE Vision Producer based on the current state, for example while an acquisition is in progress.

The same persistence files can be applied to the entire set of devices of the same type and firmware version. Applying the persistence files to a device of another type or using even different firmware version will probably lead to inconsistencies or will even fail completely – the corresponding device manufacturer should provide guidelines for such use cases .

Apart from the 'do_write_settings', the feature persistence file will also be written together with the ini file documented in the section Selection of GenICam Feature Description File(s) - using parameter 'do_write_configuration'. This command will generate extended version of the persistence file, storing not only the current device configuration, but also contents of its user sets and sequencer sets (if the device supports them). Additionally, it will also generate persistence files for all the GigE Vision Producer modules (system, interface, device and data stream). The persistence file entries in the ini file will have the format

 
RemotePersistence=%PATH_TO_PERSISTENCE_FILE_OF_THE_DEVICE% 
SystemPersistence=%PATH_TO_PERSISTENCE_FILE_OF_THE_SYSTEM_MODULE% 
InterfacePersistence=%PATH_TO_PERSISTENCE_FILE_OF_THE_INTERFACE_MODULE% 
DevicePersistence=%PATH_TO_PERSISTENCE_FILE_OF_THE_LOCAL_DEVICE_MODULE% 
StreamPersistence=%PATH_TO_PERSISTENCE_FILE_OF_THE_STREAM_MODULE% 

If the persistence functionality is not supported properly (or at all) by a given device, use the GenICam features UserSetSave/UserSetLoad, if supported by the device. These features will allow to store/load the device settings in the device's non-volatile memory.

The MVTec EasyParams is a group of MVTec GenTL Consumer parameters based on the regular GenICam features of the device. These parameters allow easy access to the most commonly used camera parameters.
The list of EasyParams can be obtained calling 'available_easyparam_names'. Note that 'available_param_names' does not include the EasyParams. The MVTec EasyParams start with the prefix [Consumer], indicating they are internal parameters of the HALCON GenTL consumer itself.
Since HALCON 22.11 they are available via an own tab in the HDevelop Image Acquisition Assistant.
If your device does not support one of the EasyParams, querying its access will return 'ni' (not implemented). If instead 'na' (not available) is returned, the EasyParam is supported but currently not available, e.g., it depends on the current state of another EasyParam or the access of one or more GenICam features, or because the image acquisition is running. In the latter case, use set_framegrabber_param(..., 'do_abort_grab', ...) to stop the acquisition.
List of MVTec EasyParams:

• General device information:
  • [Consumer]info_general
• Exposure feature:
  • [Consumer]exposure_auto
  • [Consumer]exposure
• Gain feature:
  • [Consumer]gain_auto
  • [Consumer]gain
• Trigger feature:
  • [Consumer]trigger
  • [Consumer]trigger_activation
  • [Consumer]trigger_delay
  • [Consumer]trigger_software

Detailed information of each MVTec EasyParam can be found in sections about getting framegrabber parameters and setting framegrabber parameters.
See also the HDevelop example gigevision2_easyparams.hdev.

The image acquisition can be either synchronous (grab_image/grab_data) or asynchronous (grab_image_start/grab_image_async/grab_data_async), see the reference documentation of the operators.
The interface fully configures and controls the acquisition process on the camera. Note that some of the camera features might be locked by GenICam when an acquisition is active.
With synchronous grab (grab_image/grab_data), a new acquisition is started internally for each image, so that the application always gets a new image. Before delivering the image, the acquisition is stopped again, so between individual grab_image/grab_data calls, all acquisition related features remain unlocked.
With asynchronous grabbing, started explicitly by grab_image_start or implicitly by grab_image_async/grab_data_async, the interface keeps the acquisition running internally, collecting further images to be delivered through future grab_image_async/grab_data_async calls. The acquisition related features are locked, until the acquisition is stopped using set_framegrabber_param(..., 'do_abort_grab', ...).
The HALCON acquisition interface properly recognizes the 'Continuous', 'SingleFrame' and 'MultiFrame' acquisition modes configured on the device and adjusts the acquisition control logic accordingly.
Furthermore, the interface takes over exclusive access to several remote device features essential for the acquisition control (AcquisitionStart, AcquisitionStop, AcquisitionAbort, TLParamsLocked). The user application has no direct way to control these features.
The differences between the "image" and "data" version of the grab operators is documented in Acquisition – Grab Operators.

The interface allocates 4 buffers for the acquisition engine by default (the number of buffers can be changed through the 'Generic' parameter of open_framegrabber).
Whenever a new image is acquired successfully and passed to the application as a HALCON image, the interface keeps the buffer locked (not returning it to the acquisition engine) until a new grab-related operator is called by the application or the acquisition is aborted using set_framegrabber_param(..., 'do_abort_grab', ...). During this period, it is fully safe to query information about this "last acquired" buffer – for example query buffer properties through get_framegrabber_param parameters such as 'buffer_timestamp', 'buffer_is_incomplete', 'image_width' and 'image_height'. This applies also to Chunk Data eventually present in the buffer and is also usable in volatile mode.
When a new grab-related operator is called by the application, the interface returns the buffer to the acquisition engine and buffer-related queries are not valid anymore.

It can happen, that the camera is temporarily or constantly acquiring data in higher speed than the application is processing them. In such case the streaming engine of the GigE Vision Producer decides how to treat the acquired buffers based on the '[Stream]StreamBufferHandlingMode' parameter.

Note that the streaming engine behavior can be further controlled through additional parameters described in Advanced Streaming Engine Control.

With modern, generic image acquisition interfaces an application cannot make valid assumptions about the image format coming from the device based on the current settings. Some devices for example allow changing the image format properties while the acquisition is active.
The HALCON GigEVision2 image acquisition interface fully supports these use cases. It checks the image format and other important properties of every single buffer and generates HALCON images corresponding to both the acquired image format and eventual user configured output format parameters such as 'color_space' and 'bits_per_channel'. Only if the necessary information about the buffer are missing , the current settings are used as a fallback.

The acquisition interface provides two mechanisms for acquisition of the image (or other) data from the device, grab_image/grab_image_async and grab_data/grab_data_async. Each of them might be more suitable for different use cases. Internally, both mechanisms work exactly the same (in particular how they acquire and process the data from the device), they differ in the way how the outputs are provided to the application.
The "traditional" grab_image/grab_image_async operators are still well suitable in simple use cases when just a single 2D image is acquired from the device. It is also currently used e.g. by the HDevelop's Image Acquisition Assistant. However, in case when the device is streaming more complex data structures, such as 3D data, multi-AOI or similar data, grab_image/grab_image_async is not able to provide all the outputs. In all these cases it will simply provide the first image found in the acquired data.
The "extended" grab_data/grab_data_async operators allow to output arbitrary number of HALCON images and also arbitrary number of control data. It is therefore suitable for use in advanced use cases when more than just a single HALCON image should be output. An important use case is acquisition from 3D devices (Using 3D Devices) when the operators can build and output the 3D object model through the control data output. It can be also used in other (possibly even device-specific) situations when the device outputs multiple images for a single acquisition.
The structure of the provided outputs can be queried with help of the 'image_contents', 'data_contents' and related parameters.
The grab_data/grab_data_async can also be used in the simple single-image use cases - in that case they will simply provide a single HALCON image and zero control data outputs. They can thus be used as full replacement of the traditional grab_image/grab_image_async operators.

The acquisition interface fully supports the GenICam standard 3D device model and is thus capable to seamlessly integrate 3D devices compliant with this model. This means in particular that the application does not need to care about device-specific ways of 3D data formatting, the acquisition interface will generate the 3D data under the hood using the information from the device.
If instructed so (using the 'create_objectmodel3d' parameter), the acquisition interface will generate the 3D object model from the coordinate data acquired from the device. This model can be directly used by the HALCON's 3D object model related operators.
The completeness and accuracy of the final 3D object model strongly depends on the actual coordinate data and in particular on the 3D configuration information provided by the device. Because the 3D configuration metadata are typically passed from the device through the chunk data mechanism (Chunk Data), it is essential to observe that the chunk data generation is fully enabled on the device.
If some of the important 3D configuration information is missing, the acquisition interface will try to use the suitable defaults, but the quality of the 3D object model output can be lowered.
The creation of the 3D object model can be further affected by additional parameters such as 'coordinate_transform_mode', 'confidence_mode', 'confidence_threshold', 'add_objectmodel3d_overlay_attrib'.
Note: for devices not complying with the GenICam standard 3D device model the HALCON 3D object model cannot be automatically generated.
Note that the 3D object model output is only supported by the grab_data/grab_data_async operators, it cannot be acquired using grab_image/grab_image_async. Besides the 3D object model, the grab_data/grab_data_async operators also output the actual raw coordinate data in form of HALCON images. The individual outputs can be identified with help of 'image_contents', 'data_contents' and related parameters.

The HALCON GigEVision2 image acquisition interface has a built-in converter from the pixel formats described in the GenICam Standard Features Naming Convention to the desired HALCON image format. The parameters ColorSpace and BitsPerChannel (open_framegrabber, eventually set_framegrabber_param) define the desired format of the resulting HALCON image. If these parameters are set to defaults, the original pixel format coming from the device is preserved.
To offer a basic support of custom pixel formats (i.e., pixel formats not defined by PFNC or not supported by HALCON), the ColorSpace value 'raw' can be used. In this case the image acquisition interface delivers the buffer to the application without any format conversions.
Note that the same principle is applied whenever a buffer containing other than image data is acquired. Examples of such buffers can be files (e.g., compressed images) or raw data (results of smart camera processing). Such buffers are not real "images", but can still be delivered to the application as 'raw' HALCON images. It is the responsibility of the application to know how to interpret such data.
Last but not least, the 'raw' color space can also be used if the user explicitly wishes to receive raw input data without any conversions. For example when acquiring Bayer encoded images, specifying 'raw' means that the interface should not attempt to decode them to RGB or monochrome format, but deliver the data directly to the application.
It is important to know that when the interface does not have full information about the image format (dimensions and pixel format), it has to choose an artificial one. In such a case it delivers always an 8-bit image with dimensions matching the buffer size (square root of the image size). Eventually an unused tail of the HALCON image (if such an artificial image is bigger than the source buffer) will be padded with zeroes. The fact whether the last acquired buffer contained an image of known properties or a blob of other data (so that the artificial HALCON image size had to be used) as well as the size of the eventual tail padding can be queried using 'image_raw_buffer_type' and 'image_raw_buffer_padding_bytes' parameters.

GenICam compatible cameras can deliver additional meta-data with every image in a so-called chunk data format. It is usually necessary to enable the delivery of individual meta-data "chunks" using the features 'ChunkModeActive' and 'ChunkSelector'/'ChunkEnable' first.
The decoding of the chunk data and matching them to the corresponding camera features is performed transparently by the interface.
The actual values might be read through the regular parameter reading mechanism, i.e., get_framegrabber_param. The choice of the meta-data to be delivered is device-specific. The names of the chunk related features usually start by convention with a prefix 'Chunk' (examples might be 'ChunkExposureTime' or 'ChunkGain'), however, the camera documentation should contain all the information about supported chunks and their corresponding feature names.
Some GenICam compatible devices might implement a chunk-only mode, in which meta-data without an image is transmitted. This mode is incompatible with the grab_image operators, but can be used with the grab_data operators. For some devices it might be necessary to switch the parameter [Stream]GevStreamAssumeImageInChunkPayload to false to allow this use-case.
The chunk data related features will only provide meaningful values if the "last acquired buffer" is valid, i.e., between delivery of the last image and next call to any grab-related operator (refer to section Acquisition – Buffer Handling).

It is possible to receive notifications about changes of any features exposed through the GenICam interface by the camera and GigE Vision Producer as well as for internal parameters of the acquisition interface.
Note that the notifications might be raised in various circumstances, including:

• The application (you) explicitly changed that feature.
• Another feature has changed and the notified feature "depends" on the changed feature (the dependencies are defined in the GenICam description file).
• Access mode or current range for the feature has changed.
• As a result of regular "polling" in case of uncached features.
• As a result of device event delivery if the feature is connected to that event.
• As a result of new buffer delivery for features corresponding to chunk data.

Note that the notifications are raised whenever the feature is "marked dirty" (its cache invalidated) by one of the actions described above. It does not necessarily mean that its value has really changed, it is up to the application to check this.
Notification callbacks can be registered for individual features using set_framegrabber_callback - see corresponding operator documentation. Additionally, it is possible to use message queues to receive the event notification. In those cases it is necessary to create a message queue and then register the individual feature - see event message queues.

GenICam compatible devices can deliver asynchronous events which optionally carry additional data. It is usually necessary to enable delivery of individual event types using the features 'EventSelector'/'EventNotification' first. For SFNC-compliant events, this is done automatically if the parameter 'event_notification_helper' is enabled.
The decoding of the event data and matching them to the corresponding features, including potential notifications, is performed transparently by the interface.
The actual values might be read through the regular parameter reading mechanism like get_framegrabber_param or by get_message_tuple if you are using message queues to receive events. The choice of the event types to be generated is device-specific. The names of the event related features usually start by convention with a prefix 'Event' (examples might be 'EventFrameTrigger' and 'EventFrameTriggerTimestamp'), however, the device documentation should contain all the information about supported events and their corresponding feature names.
Although the data corresponding to the last delivered event can be in general read at any time, when using callback to receive events it is highly recommended that reading the event data is synchronized to notifications for corresponding event feature(s). Only in such a case it is guaranteed that the read data correspond exactly to the very event instance being notified – and that the feature values are not just being modified through a new instance of the same event. Note that the notifications are raised from context of the event handling/dispatching thread, so when processing the user callback, the event handling mechanism is paused. If multiple data items are associated with the same event, it is enough to register notification just for the actual event feature and read all the data during the callback.
If using message queues to receive events, you can decide to add additional data to be delivered with the corresponding event feature(s), see Event Message Queues. For this case the interface will read all the specified event features as soon as the event is generated and add it to the corresponding message. This guarantees that the delivered information corresponds with the actual value at the time the event was generated.
Besides the asynchronous events generated by the actual device, asynchronous events (optionally including additional data) can be generated by any module of the GigE Vision Producer (system, interface, device and data stream). The information provided above about handling of the device events applies similarly also to the GigE Vision Producer events, including enabling/disabling them (typically using 'EventSelector'/'EventNotification' features provided by given module, i.e. with corresponding module prefix in the feature name). For SFNC-compliant events, this is done automatically if the parameter 'event_notification_helper' is enabled.
The interface will automatically capture and decode the events and match them to the corresponding GigE Vision Producer features. It is only important to understand that because the system and interface modules are potentially shared among multiple opened devices (see Parameters – Sharing Among Devices) and so, the same applies for asynchronous events generated by these shared modules.

This interface supports feature change notifications via message queues. Select the desired target feature with set_framegrabber_param(..., 'event_selector', ...). It is the same plain feature name (GenICam feature or internal parameter) as used with set_framegrabber_param, including a possible prefix, such as '[Device]' (refer to the Parameters – Naming Conventions).
Create a message queue at which you want to receive the notifications with create_message_queue and assign it to the selected feature with set_framegrabber_param(..., 'event_message_queue', QueueHandle).
The message queue can be registered for any GenICam based features, i.e., features published by the device and GigE Vision Producer or for internal features of the acquisition interface. On top of that, the notification can be registered also for internal events occurring within the acquisition interface, in particular 'event_new_buffer' which gets fired whenever the information about last acquired buffer is updated (new buffer grabbed or last buffer info invalidated when restarting the acquisition).
The list of supported targets can be queried by calling get_framegrabber_param(..., 'available_event_names', ...).
One of the important use cases for feature change callbacks is the device event delivery mechanism, see details in Event Data and Feature Change Notifications sections.
A new message would be added to the specified queue whenever a given feature is potentially changed (including its other properties such as range or access mode). Note that it does not necessarily always mean that the feature actually has a new value. A call to set_framegrabber_param(..., 'event_message_queue', 0) unregisters the previously registered message queue from the specified event. Note that the interface keeps just a single registration for every feature, if you attempt to register a new message queue for a feature that already had a message queue registered, the previous registration will be replaced with the new one.
The messages incoming on an event can be retrieved with dequeue_message and will contain at least three tuples. The first tuple (key 'id') is a unique identifier of the acquisition instance the event is coming from. It is a string composed as '<interface>:<unique_name>'. The second tuple (key 'event_name') is the name of the corresponding feature previously specified by 'event_selector'. The third tuple (key 'event_value') contains the value if the corresponding feature if available and readable.
If you decide to add additional data to be delivered with the corresponding event feature(s), add the features of interest with set_framegrabber_param(..., 'event_data', ...). Each event data feature will be appended to the event message with the key being its name and the tuple its value if readable. Note that duplicities possibly specified through 'event_data' are ignored The value of the notified feature itself (already reported in 'event_value') would also be considered as a duplicity and not reported again.

The streaming engine attempts to work well for all standard use cases. However, to reach optimal performance (whatever that means from perspective of each application), fine-tuning some parameters might be desirable to match given device type and application needs. One important aspect of the GigE Vision streaming protocol (GVSP) is management of resend-requests for missing packets (which can get lost between the device and application due to various reasons including in particular high CPU load). The control of the resend-requests might need to be considered both from application perspective (preferring low latency and high throughput or high reliability) as well as from device perspective (fixed predictable packet/block timing versus irregular streaming expectable e.g. for line scan cameras). It is desirable that based on known characteristics of the device and the system the resend requests are neither issued too late (the device might no longer store copies of those packets) nor too early (which can lead to duplicate packets being sent).
The engine can therefore be configured through various stream parameters including '[Stream]GevStreamMaxPacketGaps', '[Stream]GevStreamMaxBlockDuration', or '[Stream]GevStreamDeliverIncompleteBlocks'. When changing a parameter, it will be passed to the packet handling engine at closest suitable point (typically when re-queueing a buffer back to the engine) and applied to subsequent buffer acquisitions.
Some of the parameters, in particular '[Stream]GevStreamRingBufferSize' or '[Stream]GevStreamReceiveSocketSize' can have significant impact when tuning the interface performance with very high speed devices (when filter driver is not used). Their use can be strongly system specific and should be tuned, together with configuration of the actual network card driver, based on test experience on the actual target system.
On the other hand, the engine provides various statistics that might help to observe its performance and behavior and help to fine tune the input parameters. The statistics include for example '[Stream]GevStreamLostPacketCount', '[Stream]GevStreamResendCommandCount', or '[Stream]GevStreamIncompleteBlockCount'. The statistics are updated regularly and reset on each acquisition start.
Refer to the documentation of the stream parameters for complete list and details.
If the stream filter driver is not used, the ability to process incoming data has a heavy effect on the performance of the streaming engine. This is strongly affected by the priority of the streaming engine thread relative to other threads in the system. Refer to the documentation of the parameters '[Stream]StreamThreadPriority', '[Stream]StreamThreadSchedulingPolicy' and '[Stream]StreamThreadApplyPriority' for details. Upon device open, generally suitable default priority is selected.
Finally, the streaming infrastructure can be completely disabled using the 'streaming_mode=0' generic parameter while opening the device.
Note that many of the topics and parameters discussed in this section apply only for the GVSP stream type, not for the new RDMA stream type introduced in GigE Vision 3.0 (see GVSP vs. RDMA stream types). When in doubt refer to the documentation of the individual parameters.

The event engine works well for standard use cases. However, in specific use cases, the behavior must be fine tuned. The parameters described in this section are intended for this advanced use only and should be treated with care - wrong configuration can significantly affect performance.
The event engine thread priority is controlled by the parameters '[Device]DeviceEventsThreadPriority', '[Device]DeviceEventsThreadSchedulingPolicy' and '[Device]DeviceEventsThreadApplyPriority'. Upon device open, generally suitable default priority is selected.
The event handling infrastructure can be completely disabled using the 'device_event_handling=0' generic parameter while opening the device.

When debugging applications using GigE Vision devices, it is important to know that a core concept of the GigE Vision protocol is maintaining connection with the device using the regular 'heartbeat' packets. When the application stops maintaining the heartbeat, the device disconnects. The HALCON GigEVision2 handles the heartbeat control fully transparently, but there is a specific case when it cannot do so - when the application is being debugged and hits a breakpoint. In such case all threads are typically halted, including the one responsible for heartbeat maintenance.
To prevent loosing connection to the device while debugging, it is possible to significantly prolong the heartbeat timeout period or fully disable the heartbeat control on the device. Learn details from description of the parameters '[Device]DeviceLinkHeartbeatTimeout' and '[Device]DeviceLinkHeartbeatMode'.

In case of using the HDevelop Image Acquisition Assistant the following hints will help to avoid problems:

• Some parameters depend on special conditions, e.g., a valid buffer or another parameter activated. After opening the camera these conditions may not yet be fulfilled, so the depending parameters are not shown. By using the 'Refresh' button, all parameters are read again and the depending parameters should appear if the conditions are fulfilled then.
• There are also some parameters regarding the image size and the payload size, which can only be changed if no acquisition takes place. The safest way to ensure this is to apply the action parameter 'do_abort_grab'. Please note that 'Update Image' has to be disabled first.
• The behavior of allowing changes to parameters while streaming is active depends on the capabilities of the device. It is possible that some cameras give you control over, e.g., the exposure time, while streaming and others do not.

The HALCON GigEVision2 interface supports an internal color conversion performed in software. The conversion is automatically applied for PFNC (Pixel Format Naming Convention) compatible cameras, when the color format delivered by the camera differs from the user defined format if set via the parameter 'color_space'. The used transformation algorithms are basic and optimized for speed.

Following transformations from the camera color space (see also PFNC) to the interface color space (see also 'color_space' parameter in this document) are supported:

• Bayer pattern to 'rgb':
  

  Bayer_LMMN R G1 G2 B ⇾ [R,G,B] [R,G,B] [R,G,B] [R,G,B]

  Bayer_NMML B G1 G2 R ⇾ [R,G,B] [R,G,B] [R,G,B] [R,G,B]

  with G = (G1 + G2) / 2.

• Y'CbCr to 'rgb' (Note: gamma correction is not considered):
  

  R = Y' + 1.4020 * (Cr- M)
G = Y' - 0.34414 * (Cb- M) -0.71414 * (Cr- M)
B = Y' + 1.7720 * (Cb - M)

• RGB to 'yuv' ('yuv' corresponds to Y'CbCr of PFNC, Note: gamma correction is not considered):
  

  Y' = 0.299 * R + 0.587 * G + 0.114 * B
Cb = -0.16874 * R - 0.33126 * G + 0.5 * B + M
Cr = 0.5 * R - 0.41869 * G - 0.08131 * B + M

• RGB to 'gray':
  

  Y' = 0.299 * R + 0.587 * G + 0.114 * B

with M = 128 for 8 bit raw data, and M = 32768 for 16 bit raw data.
The accuracy of the results is limited due to internal 16.16 fix-point arithmetic for 8 bit ( 0...255), and 24.8 fix-point arithmetic for 16 bit raw data.

The acquisition interface supports the GenICam FWUpdate standard, allowing to update firmware on devices supporting the same standard in a generic way. If the device supports the standard, its vendor would distribute the firmware update files in form of GUF files, i.e. files with .guf extension.
To apply the firmware update, the device must be opened (open_framegrabber) in a special configuration mode (called "safe mode"). This mode is selected through the 'Generic' parameter of open_framegrabber - the parameter must include 'device_access=safe-mode'.
When opened in the safe mode, most of the usual parameters (either those provided by HALCON acquisition interface, the device itself or the GigE Vision Producer) will be unavailable. Instead, the configuration parameters corresponding to the given device and interface technology and in particular the parameters related to firmware update will become available.
To update the device, the GUF file is first selected in 'fwupdate_file_path', one of the (possibly multiple) updates from the file selected using 'fwupdate_update_selector' and finally applied through 'do_fwupdate_apply'. Documentation of these parameters provides further details.
Note that the update procedure may include one or more device resets, after which the device has to be re-discovered by the acquisition interface. The time needed for reset and re-discovery is specified by device vendor in the GUF file. However, there might be situations (depending on the device itself, its connection technology and system setup) when the re-discovery timeout is not sufficient and the device fails to get safely re-discovered. In such case, it is possible to specify an additional timeout that would be added to the one specified in the GUF file, allowing to successfully complete the process. This parameter, 'fwupdate_wait_after_reset', specifies the additional timeout in milliseconds.
See also the HDevelop example gigevision2_fwupdate.hdev.

The parameters of the cameras and GigE Vision Producer are accessed through GenICam and defined in GenICam description file(s) of the respective camera or GigE Vision Producer, so the parameter set is different for every product (although the parameter naming should adhere to SFNC and GenTL SFNC GenICam standard). A call of get_framegrabber_param(..., 'available_param_names', ...) returns a tuple containing all available parameters of the connected camera and GigE Vision Producer. See also section about parameter naming convention.
To set e.g. the current gain of the camera AcqHandle refers to (after calling open_framegrabber), the user can call set_framegrabber_param(AcqHandle, 'Gain', 6.0).
Please note that the interface sets the value of a parameter only if the value is valid. Integer and float values not matching the allowed range for given feature are aligned to the closest valid value. Invalid values of other feature types are refused.
Additionally to the GenICam parameters of the camera and of the GigE Vision Producer, the following HALCON interface parameters are supported by set_framegrabber_param:

There may exist additional read-only parameters with the following postfixes:

• '_access': These parameters provide the access permissions of the corresponding parameter as a string. Possible values are 'ro' (read-only), 'wo' (write-only), 'rw' (read/write), 'na' (not available), and 'ni' (not implemented).
• '_category': These parameters provide the category of the corresponding parameter as a string.
• '_description': These parameters provide the tool-tip of the corresponding parameter as a string.
• '_displayname': These parameters provide the displayname of the corresponding parameter as a string.
• '_longdescription': These parameters provide the description of the corresponding parameter as a string.
• '_range': These parameters provide the minimum, maximum, step width, and current values for the corresponding integer or float parameter as a tuple with 4 elements, e.g., get_framegrabber_param(.., 'Shutter_range', ..) will return the output tuple [min, max, step, current].
• '_representation': These parameters provide the GenICam representation of the corresponding parameter as a string. They only exist for integer-parameters. Possible values are 'Linear', 'Logarithmic', 'Boolean', 'PureNumber', 'HexNumber', 'IPV4Address' and 'MACAddress'. The purpose of the representation is to aid in GUI design.
• '_streamable': These parameters provide the persistence of the corresponding parameter as an integer. Possible values are 0 if false or 1 if true.
• '_string': These parameters provide the integer values formatted as a string according to the '_representation' postfix. Especially useful for the '_representation' values 'IPV4Address', 'MACAddress' and 'HexNumber'.
• '_type': These parameters provide the type of the corresponding parameter as string.
• '_values': These parameters provide the valid value list for the corresponding parameter as a tuple, e.g., get_framegrabber_param(.., 'volatile_values', ..) will return the output tuple ['enable', 'disable'].
• '_visibility': These parameters provide the visibility of the corresponding parameter as a string. Possible values are 'beginner', 'expert', and 'guru'.

All these postfixed parameter names are not returned when calling info_framegrabber(.., 'parameters', ..) and are used to enable the easy parameterization via a generic graphical user interface, particularly the HDevelop Image Acquisition Assistant.

Not supported by this interface.

Not supported by this interface.

This interface supports feature change callbacks via the operators set_framegrabber_callback and get_framegrabber_callback.
The callback can be registered for any GenICam based features, i.e., features published by the device and GigE Vision Producer through the GenICam description files as well as for internal parameters of the acquisition interface.
The list of supported callback targets can be queried by calling get_framegrabber_param(..., 'available_callback_types', ...).
One of the important use cases for feature change callbacks is the device event delivery mechanism, see details in event data and feature notifications sections. The 'CallbackType' parameter of set_framegrabber_callback defines the feature for which the callback is registered. It is the same plain feature name as used with set_framegrabber_param, including a possible prefix, such as '[Device]' (refer to the parameter naming convention).
The registered callback function would be called whenever a given feature is potentially changed (including its other properties such as range or access mode). Note that it does not necessarily always mean that the feature actually has a new value. If the callback function is set to NULL, the corresponding callback will be unregistered. Note that the interface keeps just a single registration for every feature, if you attempt to register a new callback for a feature that already had a callback registered, the previous registration will be replaced with the new one.

The signature of the callback function is Herror (__stdcall *HAcqCallback)(void *AcqHandle, void *Context, void *UserContext) and uses the following parameters:

• AcqHandle: Acquisition handle of the corresponding image acquisition instance.
• Context: Optional context data of the specific callback. Up to now, this parameter is not used, i.e., Context is set to NULL.
• UserContext: Optional context data of the specific callback. Up to now, this parameter is not used, i.e., UserContext is set to NULL.

Note that the execution time of a user-specific callback function must always be as short as possible since during the execution of a callback function the handling of further internal callbacks might be blocked. This can be achieved by removing the current processing from the user-specific callback function to a separate thread that is controlled via signals or events. The callback function is executed in the context of the underlying interface or driver.
It is also important to understand that the callbacks might be fired as a side-effect of parameter-setting or grab operations, ie. it might be called from within their respective locks. The user is responsible to take this into account in the callback handler to avoid risk of a deadlock.

This interface supports feature callbacks via the operators set_framegrabber_callback and get_framegrabber_callback. For more information see set_framegrabber_callback.

Starts a new asynchronous grab. See also grab_image_start and section about acquisition control. Note that this operator starts acquisition on the GigE Vision Producer and device and locks features protected during acquisition. If grab_image_start is called repeatedly, the acquisition is restarted on both GigE Vision Producer and device. That means, that the buffer queue and all stream related statistics parameters like 'buffer_frameid' are reset. The acquisition can be stopped (and the features unlocked) using set_framegrabber_param(..., 'do_abort_grab', ...).

grab_image starts a new synchronous grab of a single image. See also grab_image, section about acquisition control and about grab operators. Note that the interface converts the acquired image to the desired image format specified by the parameters 'bits_per_channel' and 'color_space'.

grab_image_async returns a single image and starts the next asynchronous grab. See also grab_image_async, section about acquisition control and about grab operators. Note that the interface converts the acquired image to the desired image format specified by the parameters 'bits_per_channel' and 'color_space'.
The 'MaxDelay' parameter of the grab_image_async operator is ignored by the HALCON GigEVision2 acquisition interface, because there is no way to support it reliably . If needed, the application needs to implement alternative functionality on its own.

grab_data starts a new synchronous grab, resulting possibly in tuple of output images and tuple of data outputs of various kind, depending on the input and configuration. See also grab_data, section about acquisition control and about grab operators. Note that the interface converts the acquired images to the desired image format specified by the parameters 'bits_per_channel' and 'color_space'. The output tuples are described using the 'data_contents', 'image_contents' and related parameters.

grab_data_async returns acquired images/data and starts the next asynchronous grab. See also grab_data_async, section about acquisition control and about grab operators. Note that the interface converts the acquired image to the desired image format specified by the parameters 'bits_per_channel' and 'color_space'. The output tuples are described using the 'data_contents', 'image_contents' and related parameters.
The 'MaxDelay' parameter of the grab_image_async operator is ignored by the HALCON GigEVision2 acquisition interface, because there is no way to support it reliably . If needed, the application needs to implement alternative functionality on its own.

This operator closes the device. See also close_framegrabber.

For this interface there are the following examples available:

• gigevision2.hdev - Benchmark.
• gigevision2_2cameras.hdev - Grabbing images from two cameras.
• gigevision2_acquisition_events.hdev - Example how to handle events with additional event data using message queues.
• gigevision2_action_control.hdev - Using Action Control feature.
• gigevision2_automation_technology_c4_objectmodel3d.hdev - Acquisition and visualization of 3D data for the Automation Technology C4 sensor.
• gigevision2_chunkdata.hdev - Using GigE Vision Chunk Data.
• gigevision2_crop.hdev - Example for grabbing images with software and hardware image cropping.
• gigevision2_devicelost_event.hdev - Example how to handle DeviceLost event with message queues.
• gigevision2_do_abort_grab.hdev - Aborting an ongoing image acquisition.
• gigevision2_easyparams.hdev - Handling MVTec EasyParams.
• gigevision2_fileaccess.hdev - Example how to upload and download files from GenICam devices.
• gigevision2_flir_ax5.hdev - Acquisition from a FLIR AX5 thermal imaging camera, visualization using an iron LUT and temperature alarm detection.
• gigevision2_forceip.hdev - Using ForceIP to correctly configure a misconfigured GigE Vision device.
• gigevision2_frame_rate.hdev - Example to measure the effective frame rate of an acquisition device.
• gigevision2_fwupdate.hdev - Example how to apply a firmware update through GenICam FWUpdate.
• gigevision2_hardware_trigger.hdev - Usage of hardware trigger.
• gigevision2_information.hdev - Program for gathering information about the system and the camera configuration. Please attach the resulting files when requesting support.
• gigevision2_interpacket_delay.hdev - Adjusting interpacket delay to enable the use of two cameras connected via a single switch to one network interface.
• gigevision2_io_control.hdev - Example how to control the GPIOs of a device.
• gigevision2_ip_address_handling.hdev - Reading IPv4 address and assigning IPv4 address statically.
• gigevision2_link_aggregation.hdev - Show usage in combination with static link aggregation (LAG).
• gigevision2_multiframe.hdev - Show usage of MultiFrame mode.
• gigevision2_parameters.hdev - Lists all parameters of a device.
• gigevision2_parameter_persistence.hdev - Demonstrates writing parameter values to files and restoring parameter values from files.
• gigevision2_photonfocus3d_objectmodel3d.hdev - Acquisition and visualization of 3D data for the Photonfocus 3D sensor.
• gigevision2_roboception_rcvisard_objectmodel3d.hdev - Acquisition and visualization of 3D data for the Roboception rc_visard sensors.
• gigevision2_scheduled_action_command_ptp_ieee1588.hdev - Trigger multiple cameras synchronously with the GigE Vision feature 'scheduled action commands'.
• gigevision2_sick_ranger3_objectmodel3d.hdev - Acquisition and visualization of 3D data for the Sick Ranger3 sensor.
• gigevision2_simple.hdev - A simple example to show the usage of the interface.
• gigevision2_software_trigger.hdev - Usage of software trigger.
• gigevision2_hyperspectral_linescan.hdev - Example how to generate multi-channel images from hyperspectral linescan camera data.
• gigevision2_wenglor_shapedrive_objectmodel3d.hdev - Acquisition and visualization of 3D data for the wenglor ShapeDrive sensors.
• gigevision2_wenglor_wecat3d_objectmodel3d.hdev - Acquisition and visualization of 3D data for the wenglor weCat3D sensors.

This chapter is intended as a help for users switching to the new version of this acquisition interface (GigEVision2) from its previous implementation (GigEVision). Users starting new applications directly based on GigEVision2 interface can fully ignore contents of this chapter.

The GigEVision2 interface is a significant rewrite of the previous interface targetting support of the GigE Vision 2 specification, thorough compatibility with the modern versions of the GenICam standards family and similar user experience among all GenICam based HALCON acquisition interfaces (in particular GigEVision2, USB3Vision and GenICamTL). It was not therefore possible to keep full backward compatibility with the previous version of this interface.

The most important new features introduced in GigEVision2:

• Support of the GigE Vision specification version 2.x.
• Tight compatibility with current versions of the GenICam standards.
• Full support of GigE Vision Chunk Data and Event Data.
• Support of multi-part data and in particular native support of 3D devices (Using 3D Devices).
• Introduced support for grab_data and grab_data_async operators (Acquisition – Grab Operators).

Current limitations that will be addressed in future updates of the interface:

• The streaming filter is intended to keep working with both versions of the acquisition interface. Its current version does not yet implement all of the stream engine parameters (stream control and statistics) of the GigEVision2 interface. All those differences are clearly highlighted in sections about getting framegrabber parameters and setting framegrabber parameters.

Changes related to opening the device (open_framegrabber and info_framegrabber):

• The name of the acquisition interface itself has changed (GigEVision2 instead of GigEVision) while both versions currently co-exist.
• The format of the string identifying the device and the set of options to identify the device has changed, see details about the current format in Identifying and Opening a Device. The same changes are also reflected in the device and info_boards queries in info_framegrabber operator.
• Following parameters are ignored in the open_framegrabber operator: ImageWidth, ImageHeight, StartRow, StartColumn, Field, ExternalTrigger, Port, LineIn. Corresponding functionality should be configured by setting the GenICam features of each corresponding device.
• The ability to detect misconfigured devices (IP subnet not matching the network interface the device is connected to) and option to force new temporary IP address to the device while opening still exists - but the format of the string requesting the new IP address has changed to match the new underlying device discovery architecture. Refer to the force_ip generic parameter in open_framegraber (replacing the old GtlForceIP generic parameter that was using different internal format).
• Following generic parameters in open_framegrabber have new names:
  • force_sockdrv instead of GtlForceSocketDriver
  • num_buffers instead of GtlNumBuffers
    Notice that the interface internally locks 1 buffer (see acquisition buffer handling), therefore if your application requires n buffers, 'num_buffers' must be set to n+1.
• Generic parameters GtlGVCPRetries and GtlGVCPTimeout are not supported, their functionality is newly accessible through set_framegrabber_param parameters [Device]LinkCommandRetryCount and [Device]LinkCommandTimeout.
• Generic parameters GtlUseCameraPacketSize and GtlDisableAutomaticTestPackets are currently not supported at all.

Various parameters configuring the acquisition interface and the connected device has changed or were removed in the GigEVision2 interface version. This reflects the significantly changed internal architecture, now following the GenICam GenTL architecture model reused by all GenICam based HALCON acquisition interfaces. See details in getting framegrabber parameters and setting framegrabber parameters.

• The parameters starting with the Gtl prefix no more exist (see below to find which of them were replaced by similar parameters with different name).
• The parameters starting with the Gev prefix no more exist (depending on the actual connected device, some of these parameters might still be available, if the device itself provides them).
• Following additional parameters are no more supported:
  • do_flush_buffers
  • do_flush_callback_queue, max_num_queued_callbacks, num_queued_callbacks, callback_timeout
  • do_write_xml_file
  • DeviceID, DeviceModelName, DeviceVendorName (similar as for the parameters with Gev prefix, these might be available if the device itself supports them).
  • parameters_hidden
  • GenApiCNodeMapRefPtr

• Some of the missing parameters listed above were replaced by same or similar purpose parameters with new names (old name of the parameter mentioned in brackets):
  • [Device]DeviceID (DeviceID)
  • [Device]DeviceVendorName (DeviceVendorName)
  • [Device]DeviceModelName (DeviceModelName)
  • [Device]DeviceSerialNumber (GtlSerialNumber)
  • [Device]GevDeviceIPAddress (GtlCurrentIPAddress)
  • [Device]GevDeviceMACAddress (GtlDeviceMACAddress)
  • [Device]LinkCommandRetryCount/[Device]LinkCommandTimeout (GtlGVCPRetries/GtlGVCPTimeout)
  • [Stream]StreamBufferHandlingMode (GtlBufferHandlingMode) - refer to the documentation of the new parameter, the list of supported values is different
  • [Stream]GevStreamDeliverIncompleteBlocks (GtlGVSPDiscardIncompleteBuffers) - beware of the reversed logic of the flag
  • [Stream]GevStreamMaxBlockDuration (GtlBlockTimeout) - the new feature supports specifying 'infinite' duration, refer to the feature documentation for details
  • [Stream]GevStreamActiveEngine (GtlAcquisitionEngine) - beware of different output strings
  • [Stream]GevStreamIncompleteBlockCount (GtlIncompleteBuffers)
  • [Stream]GevStreamPacketOrderDelay (GtlGVSPResendWait)
  • [Interface]InterfaceID (GtlInterfaceID) - beware of different output strings
  • GevSCPD (GtlGVSPInterpacketDelay) - note that this is a device feature, not mandatory
  • buffer_is_incomplete (GtlBufferIncomplete)
  • buffer_timestamp (GtlBufferTimestamp)
  • buffer_frameid (GtlBlockID)
  • do_write_configuration (do_write_xml_file) - the new parameter does not only replace the old one but extends it with wider functionality
  • We recommend to refer to the documentation of all the currently available parameters in getting framegrabber parameters and setting framegrabber parameters.

The following callback (set_framegrabber_callback) is currently not supported:

• callback_queue_overflow

In case of problems with the HALCON GigEVision2 Interface the following hints might help to solve them.

General:

• Check if the latest revision of the HALCON GigEVision2 interface is used.
• Check the System Requirements.
• Check if the device has the latest firmware.
• Enable low-level error messages in HALCON to query more information about the problem (and check the output console in HDevelop if applicable).
• If a firewall is active in the system, it has to be configured in a way so that all applications expected to be using the GigE Vision devices (e.g. HDevelop, but also any user-developed applications) have full access to the connected devices.
• If you observe random acquisition timeouts, it might be that packet loss is too high in your network setup (when using the GVSP stream type). Verify that all your networking components can keep up with the data rate sent by the camera. Check how frequently packet gaps occur with '[Stream]GevStreamResendPacketCount'. Then try to parameterize the resending mechanism for your setup, for example by increasing '[Stream]GevStreamMaxPacketGaps' or by using '[Stream]GevStreamMaxBlockDuration'.

GigE Vision 3.0 RDMA stream based devices:

• If the device supports only the new RDMA stream type, but is connected to a network adapter which does not support RDMA/RoCEv2 on the given operation system, the HALCON GigEVision2 interface cannot instantiate the stream and will treat the device as non-streamable. Refer to System Requirements and GVSP vs. RDMA stream types.

Filter driver (MVTec GigE Vision Streaming Filter):

• In case there are problems with streaming while the filter driver is active it is usually not possible to capture a network packet trace to analyse the problems. Starting with v2.1.8.0 of the filter driver it is possible to set the environment variable MVTEC_GIGEVISION_FILTER_PASSTHROUGH=1 to give other filters like Wireshark's pcap access to the packets.

GenICam:

• Check if the correct GenICam binaries are in use. HALCON uses the official binaries in a private installation (folder genicam in the HALCONROOT directory). If other GenICam binaries are in your path or in some system path (for Windows e.g. in c:\Windows\System32\ for Linux e.g. in /usr/lib or similar directories) make sure these are the official ones by comparing them with the ones in the HALCON installation. Using unofficial binaries might result in strange problems.

If there are still problems, please contact your local distributor.

The following information is needed for your support request to avoid unnecessary inquiries.

• Used HALCON and acquisition interface versions.
• Used HALCON architecture (especially 32 or 64 bit).
• Low-level error messages if there are any.
• Camera manufacturer, model and firmware version.
• Details about computer system, like operating system, RAM and CPU.
• Minimal sample code (e.g. HDevelop script) to reproduce the issue.
• Description of observed and expected behavior.

Please run the HDevelop example gigevision2_information.hdev to gather information about the system and the camera configuration, and then attach the resulting files when requesting support.

This interface depends on third-party libraries. See the file third_party_gigevision2.txt in the HALCON base directory for copyright and license information. Libraries are used without modifications unless explicitly stated in the file.

You can request the source for those third-party libraries licensed under GPL or LGPL via email to info@mvtec.com with the subject "Request source code of third-party libraries".

• Revision 24.11.23 (Apr 20, 2026):
  • Support for the finalized GigE Vision 3.0 specification has been added. Device firmware must match the updated specification.
  • According to a recommendation of the Linux C library interface documentation, waiting for events on file descriptors is now performed by poll instead of select.
  • The decompression mechanism for GenICam feature description files failed for some zip files with: 'Failed to decompress file (unexpected uncompressed size 0)'. This problem has been fixed.
  • The parameter '[Stream]GevStreamAssumeImageInChunkPayload' has been added to deal with the GigE Vision payload type chunk data. Its default value is true. This fixes a problem where setting 'ChunkModeActive' to true did result in 'grab_image' and 'grab_image_async' not delivering an image.
  • zlib has been updated to version 1.3.2.
• Revision 24.11.22 (Oct 9, 2025):
  • GigE Vision specification version 3.0 is now also supported on Linux. It adds remote direct memory access (RDMA) over Converged Ethernet (RoCE).
  • The decompression method for GenICam feature description files has been changed to zlib 1.3.1.
  • libjpeg-turbo has been updated to version 3.1.0.
  • There was a memory leak when registering for feature change notifications with set_framegrabber_callback or with 'event_message_queue'. This problem has been fixed.
  • Action commands could fail due to an uninitialized source port. This problem has been fixed.
  • A Software Bill of Materials (SBOM) in the System Package Data Exchange (SPDX) format has been added next to each binary file with the same name extended by ".spdx.json".
• Revision 24.11.21 (Apr 16, 2025):
  • The underlying GenApi version has been updated to the latest official release 3.5.0. The previous version failed to load settings that contained empty string parameters. This problem has been fixed.
• Revision 20.11.20 (Oct 10, 2024):
  • GigE Vision specification version 3.0 is now supported on Windows. It adds remote direct memory access (RDMA) over Converged Ethernet version 2 (RoCEv2).
  • libjpeg-turbo has been updated to version 3.0.3.
• Revision 20.11.19 (Sep 24, 2024):
  • The execution of the 'do_abort_grab' command could take up to a value specified by the parameter '[Stream]GevStreamAbortCheckPeriod'. The 'do_abort_grab' command is now executed significantly faster.
  • grab_image_start failed with HALCON error code 5329 in certain multi-camera setups. This problem has been fixed.
  • The initialization of the MVTec EasyParam [Consumer]trigger_delay crashed in the rare case that TriggerActivation did not support any of the following values: 'RisingEdge', 'FallingEdge' and 'AnyEdge'.
  • The first access to the MVTec EasyParam [Consumer]exposure_auto and [Consumer]gain_auto could lead to a change in ExposureTime or Gain GenICam device parameter, respectively. This problem has been fixed.
  • Multithread usage of the MVTec EasyParams could lead to abnormal program termination. This problem has been fixed.
• Revision 20.11.18 (Feb 28, 2024):
  • The open_framegrabber's ColorSpace parameter has been extended with the value 'rgbx'. The new value can be used to obtain a 4 channel HALCON image, if the input pixel format is a supported 4 channel PFNC pixel format.
  • Pixel formats 'RGB14', 'RGBa10', 'RGBa12', 'RGBa14', 'RGBa16', 'BGR14', 'BGR16', 'BGRa10', 'BGRa12', 'BGRa14' and 'BGRa16' are now supported.
  • The underlying GenApi version has been updated to the latest official release 3.4.2. This fixes a compatibility break with certain persistence files introduced in version 3.4.1.
  • The HDevelop example gigevision2_hyperspectral_linescan.hdev has been added to demonstrate how to generate multi-channel images from hyperspectral linescan camera data.
  • Loading of configuration files during open_framegrabber (with the parameter CameraType) did not raise an exception, even when the file could not be read. This problem has been fixed.
  • When passing GenICam persistence files to open_framegrabber, the remote device was silently ignored. This problem has been fixed.
  • The HDevelop example gigevision2_hardware_trigger.hdev has been added to demonstrate how to use the hardware trigger mode.
  • Instead of a range, numeric GenICam parameters can also report a list of values. This is now available through the parameter suffix '_values'.
• Revision 20.11.17 (Aug 7, 2023):
  • The underlying GenApi version has been updated to the latest official release 3.4.1. This improves the validation of the string representation of parameters written through the '_string' postfix.
  • Pixel formats 'YCbCr420_8_YY_CbCr_Semiplanar', 'YCbCr420_8_YY_CrCb_Semiplanar', 'YCbCr422_8_YY_CbCr_Semiplanar', and 'YCbCr422_8_YY_CrCb_Semiplanar' are now supported.
  • Parallel execution of set_framegrabber_param (..., 'do_abort_grab', ...) could lead to a crash when the filter driver was active. This problem has been fixed.
  • Execution of 'do_write_configuration' with 'streaming_mode' off returned an error. This problem has been fixed.
  • The first access to an MVTec EasyParam could change the value of its equivalent GenICam device parameter. This problem has been fixed.
  • Accessing an MVTec EasyParam could lead to a crash if any of the underlying GenICam parameters had an unexpected type. This problem has been fixed.
  • Querying the '_representation' of an MVTec EasyParam could in some cases lead to a crash. This problem has been fixed.
  • In rare cases, the access of not implementable MVTec EasyParams was erroneously set to 'na', instead of 'ni'. This problem has been fixed.
  • The robustness of setting/restoring the device trigger state in gigevision2_information.hdev has been improved.
• Revision 20.11.16 (Apr 6, 2023):
  • If a numerical parameter has a special representation besides its pure value, the type of representation can now be queried by using the '_representation' postfix.
  • The string representation of a parameter value can be now queried by using the '_string' postfix.
  • grab_data and grab_data_async failed when receiving data of payload type Chunk Data. This problem has been fixed. See also Chunk Data.
  • The libCLAllSerial shared object has been removed from the redistribution of GenApi 3.4.0.
  • The example gigevision2_do_abort_grab.hdev has been rewritten.
  • The example gigevision2_software_trigger.hdev has been rewritten.
  • The HDevelop example gigevision2_scheduled_action_command_ptp_ieee1588.hdev has been added to demonstrate synchronous triggering of multiple cameras with the GigE Vision feature 'scheduled action commands'.
  • third_party_gigevision2.txt now contains links to the corresponding software location. See also Usage of third-party libraries.
• Revision 18.11.15 (Oct 7, 2022):
  • The MVTec GigE Vision Streaming Filter installer failed when its file location contained non-ASCII characters. This problem has been fixed.
  • The MVTec EasyParams have been implemented to deal with the most common GenICam features in a simple and user-friendly way.
  • The new parameter 'available_easyparam_names' has been added to return the list of the MVTec EasyParams.
  • The HDevelop example gigevision2_easyparams.hdev has been added to demonstrate how to handle the MVTec EasyParams.
  • On a Unix system, loading GenICam persistence files that contained Windows line endings failed. This problem has been fixed.
• Revision 18.11.14 (May 11, 2022):
  • In some cases, the 'info_boards' query of info_framegrabber failed to detect an available IP address for misconfigured devices. This problem has been fixed.
  • On a Unix system, loading Consumer persistence or configuration ini that was written on a Windows system failed. This problem has been fixed. Moreover, writing Consumer persistence or configuration ini files on a Windows system has been changed to use Unix line ending.
  • Connection with serial number is now possible, see Identifying and Opening a Device.
  • The underlying GenApi version has been updated to the latest official release 3.4. This fixes a crash during 'do_load_settings' when a device failed to execute the underlying command 'DeviceRegistersStreamingEnd'.
  • It is now possible to receive Feature Change Notifications on any parameter listed by 'available_param_names'.
  • A new parameter 'event_new_buffer' has been added which is only available as an event, see Feature Change Notifications and following.
  • There was a memory leak with each message delivered through the Event Message Queues mechanism. This problem has been fixed.
  • The identifier (key 'id') of the messages incoming on an event was not always unique. This problem has been fixed. The device name in the string ':' now corresponds with the 'unique_name' from info_framegrabber.
  • Retrieving GenICam XML description files from the host file system was broken. This problem has been fixed.
  • The calculation of the B (Y) coordinates in case of Disparity data from a Linescan device was incorrect. This problem has been fixed.
  • grab_data and grab_data_async failed when 'add_objectmodel3d_overlay_attrib' was enabled but the ObjectModel3D contained no points. This problem has been fixed.
  • The HDevelop script gigevision2_information.hdev now saves the output data into the user's Documents folder to avoid problems with missing writing permissions. Further, the script can now deal with non-alphanumerical characters in the device unique name. Moreover, a problem related to the restoring of the original trigger settings has been fixed.
• Revision 18.11.13 (Oct 20, 2021):
  • JPEG payload as specified by the GigE Vision and GenICam GenDC standards can now be decoded.
  • Packed Bayer formats as specified by the GigE Vision standard and the GenICam Pixel Format Naming Convention are now supported.
  • Pixel formats 'Coord3D_AC32f', 'Coord3D_AC16', and 'Coord3D_AC8' are now supported.
  • The read-write parameters of the Consumer module are streamable, i.e. they can be persisted with 'do_write_settings' or 'do_write_configuration'. However, get_framegrabber_param returned 0 for these parameters with postfix '_streamable'. This problem has been fixed.
  • HALCON crashed in rare cases with connection loss during the execution of open_framegrabber. This problem has been fixed.
  • When open_framegrabber with forced IP was called shortly after a device discovery, it could have failed even though the force-IP command had actually succeeded. This problem has been fixed.
  • The HDevelop example gigevision2_information.hdev now includes information about the MTU configured on the receiver side.
  • The HDevelop example gigevision2_roboception_rcvisard_objectmodel3d.hdev has been extended to support Roboception's GenTL Producer. Further, DepthDispRange is now calculated implicitly and a problem with the color overlay of the ObjectModel3D has been fixed.
  • The distribution package of this interface now contains files providing meta information for the HDevelop example browser.
• Revision 18.11.12 (Feb 15, 2021):
  • The performance of the Socket Driver has been revised including two new parameters '[Stream]GevStreamRingBufferSize' and '[Stream]GevStreamReceiveSocketSize', see also Advanced Streaming Engine Control.
  • The parameter [Stream]EventTransferEndUndeliverabilityReason has been added to be used in conjunction with [Stream]EventTransferEnd.
  • The MVTec GigE Vision Streaming Filter (filter driver) has been updated to version 2.2.8.4 which comes with the following changes:
    • With the streaming filter, the EventTransferEnd was only fired for successfully received blocks but not for undeliverable ones. This problem has been fixed.
    • In rare cases, when an application did not shutdown gracefully while streaming was underway, automatic unloading of the streaming filter could have led to a crash of the operating system. This problem has been fixed.
  • The underlying GenApi version has been updated to the latest official release 3.3.
  • The assembly of an ObjectModel3D from encoder-controlled Linescan 3D devices has been accelerated significantly. To allow this acceleration, the devices must announce ChunkEncoderValue and ChunkScanLineSelector through their ValueArrayCandidates as described by GenICam Standard Feature Naming Convention 2.7 and later.
  • For open_framegrabber with a device string in the 'token:value' form, it was mandatory to contain the separator ' | '. This restriction has been removed.
  • The GenICam caching mechanism was inactive unless one of the environment variables TEMP, TMP or TMPDIR was set. Now, /tmp or HALCONROOT are used as a fallback.
  • The HDevelop example gigevision2_frame_rate.hdev has been optimized.
  • The HDevelop example gigevision2_acquisition_events.hdev ran into a deadlock in case of very quickly incoming events. This problem has been fixed.
  • Section Switching From Previous Implementation of the GigEVision Interface has been extended with further old parameters and their new correspondences.
  • The HDevelop example gigevision2_information.hdev has been refactored and now it calls the new procedure library genicamtl_information.hdpl. Moreover, this new version switches off TriggerMode in order to test image acquisition and logs more details in case of an image acquisition failure.
  • The error handling has been improved. Additional information about the cause of an error can now be queried with the operator get_extended_error_info. For the HALCON language interfaces (C# and C++), the HALCON exception class provides methods to access the additional error information.
• Revision 18.11.11 (Oct 27, 2020):
  • This interface couldn't be loaded from .NET Core applications on Linux and macOS. This problem has been fixed.
  • Added support for 'YCbCr411_8_CbYYCrYY', 'YCbCr422_8' and 'YCbCr422_8_CbYCrY' pixel formats.
• Revision 13.0.10 (Sep 18, 2020):
  • Most file operations did not support UTF-8 file names. This problem has been fixed. However, some of the operations like Firmware Update are managed by GenICam GenApi which might not support them.
  • In the previous revision 'do_write_configuration' did not write the path to generated xml files into the generated ini file. This problem has been fixed.
• Revision 13.0.9 (Aug 7, 2020):
  • 'do_write_configuration' has been extended to also generate a persistence file for the GenTL Consumer (persisting internal parameters of the HALCON GigEVision2 image acquisition interface itself like 'grab_timeout'), see Parameters – Persisting Device Status.
  • It is now possible to write and load persistence files for individual GenTL Producer modules or the GenTL Consumer when the device has already been opened. This was so far only possible for the remote device. The persistence file to be written or loaded is selected with the parameter 'settings_selector'.
  • When loading persistence files with open_framegrabber, some of the persisted parameter values were overwritten. This problem has been fixed.
  • The features '[Interface]GevInterfaceGatewaySelector' and '[Interface]GevInterfaceGateway' have been added. Note that they are currently not implemented on macOS.
  • The HDevelop example gigevision2_parameter_persistence.hdev has been added to demonstrate writing parameter values to files and restoring parameter values from files.
  • The parameter 'available_event_names' was wrongly written as 'available_event_types'. This problem has been fixed.
• Revision 13.0.8 (Apr 24, 2020):
  • GigE Vision specification version 2.2 is now supported. This includes GenDC streaming used e.g. by 3D devices.
  • get_framegrabber_param(..., 'event_message_queue', ...) failed with HALCON versions prior to 18.05. This problem has been fixed.
  • The MVTec GigE Vision Streaming Filter (filter driver) has been updated to version 2.2.8.3 which comes with the following changes:
  • When using '[Stream]EventTransferEnd' on multiple NICs, the filter driver sporadically stopped to deliver events. This problem has been fixed.
  • get_framegrabber_param (..., 'num_buffers_underrun', ...) was not available with the filter driver. This problem has been fixed.
• Revision 13.0.7 (Feb 19, 2020):
  • The time to get a buffer from the buffer queue was linearly rising with the buffer index. This was most noticeable when using a large 'num_buffers'. This problem has been fixed.
  • The HDevelop example gigevision2_action_control.hdev does not depend on the optional device feature GevCurrentIPAddress anymore.
• Revision 13.0.6 (Dec 10, 2019):
  • Updated underlying GenApi version to latest official release v3.2. The Update includes a bug fix on persistence of user and sequencer sets and other minor bug fixes.
  • The parameter 'num_buffers' was limited to an arbitrary maximum of 1023. This limitation has been removed.
  • The default timeout for force IP requests has been increased to allow devices verification of the requested IP as per RFC 5227. Further, the new parameters '[Interface]GevDeviceForceIPTimeout' and '[Interface]GevDeviceLastForceIPSuccess' have been added for better control of the operation.
  • The generic parameter 'direct_connection' passed to open_framegrabber was neither listed in info_framegrabber (..., 'generic', ...) nor available from get_framegrabber_param. This problem has been fixed.
  • The MVTec GigE Vision Streaming Filter (filter driver) was inactive on systems with more than 24 NICs. This problem has been fixed.
  • The HDevelop example gigevision2_link_aggregation.hdev has been extended for usage with the socket driver.
  • The HDevelop example gigevision2_link_aggregation.hdev was incomplete. This problem has been fixed. Now, '[Stream]GevStreamPacketOrderDelay' is adjusted to the specific setup.
  • The HDevelop example gigevision2_roboception_rcvisard_objectmodel3d.hdev has been adapted to discard incomplete buffers.
  • Added new HDevelop example gigevision2_sick_ranger3_objectmodel3d.hdev that shows how to acquire and visualize 3D data with the Sick Ranger3 sensor.
• Revision 13.0.5 (Jul 22, 2019):
  • Fast direct connection with IP address is now possible, see Identifying and Opening a Device.
  • You can now query if a feature can be persisted by using the '_streamable' postfix.
  • The HDevelop example gigevision2_parameters.hdev has been extended to check if a parameter can be persisted.
  • The HDevelop example gigevision2_information.hdev has been extended to check if the camera supports firewall traversal.
  • The 'add_objectmodel3d_overlay_attrib' mechanism has been extended according to SFNC 2.5 which specifies how to map overlay data of different resolution than the 3D data.
  • The HDevelop example gigevision2_roboception_rcvisard_objectmodel3d.hdev has been simplified accordingly.
  • The file third_party_gigevision2.txt has been added to the distribution package of this interface.
• Revision 13.0.4 Addendum (May 2, 2019):
  • The new HDevelop example gigevision2_io_control.hdev has been added to demonstrate how to control the GPIOs of a device.
  • In the HDevelop example gigevision2_roboception_rcvisard_objectmodel3d.hdev, 'DepthMaxDepth' has been decreased to 5 meters in order to reduce unwanted background data.
• Revision 13.0.4 (Mar 5, 2019):
  • Added support for 'BiColorRGBG8' and 'BiColorBGRG8' pixel formats.
  • 3D object models from grab_data and grab_data_async are now generated with 2D mapping. This significantly speeds up several operators working on 3D object models.
  • The mechanism to generate a HALCON ObjectModel3D from 3D images has been extended for Disparity images. Such images need to include the following chunks specified in SFNC 2.4: 'ChunkScan3dFocalLength', 'ChunkScan3dBaseline', 'ChunkScan3dPrincipalPointU', 'ChunkScan3dPrincipalPointV'.
  • On Linux systems, 'do_abort_grab' could take an unexpectedly long time. This problem has been fixed.
  • Further, the parameter '[Stream]GevStreamAbortCheckPeriod' has been introduced to configure the check period for 'do_abort_grab'.
  • The MVTec GigE Vision Streaming Filter (filter driver) has been updated to version 2.1.8.2 which comes with the following changes:
  • '[Stream]EventTransferEnd' and its related event data are now also available when using the filter driver.
  • The following statistics available with get_framegrabber_param were missing from the filter driver but have now been implemented: '[Stream]GevStreamDeliveredPacketCount', '[Stream]GevStreamDuplicatePacketCount', '[Stream]GevStreamLostPacketCount', '[Stream]GevStreamOversizedBlockCount', '[Stream]GevStreamResendCommandCount', '[Stream]GevStreamSkippedBlockCount'
  • Added new HDevelop example gigevision2_roboception_rcvisard_objectmodel3d.hdev that shows how to acquire and visualize 3D data with the Roboception rc_visard sensors.
  • Added new HDevelop example gigevision2_wenglor_shapedrive_objectmodel3d.hdev that shows how to acquire and visualize 3D data from a wenglor ShapeDrive sensor.
• Revision 13.0.3 (Oct 30, 2018):
  • Updated underlying GenApi version to latest official release v3.1. Please note that therefore also the genicam directory of your HALCON installation will be updated. The Update includes an accelerated MathParser, improved persistence in combination with sequencers and a fix where values were available even though the corresponding feature was not.
  • GenICam's File Access is now supported. See the new parameters 'fileaccess_file_path', 'fileaccess_remote_name', 'do_fileaccess_download', 'do_fileaccess_upload', 'do_fileaccess_delete', and the new HDevelop example gigevision2_fileaccess.hdev.
  • GenICam's FWUpdate is now supported. See Firmware Update and the new HDevelop example gigevision2_fwupdate.hdev.
  • Receiving GenICam events on message queues is now supported, see Event Message Queues. So far, GenICam events were only supported via callbacks and thus not usable in HDevelop. Additionally, two new HDevelop examples have been added to show this functionality gigevision2_acquisition_events.hdev and gigevision2_devicelost_event.hdev.
  • The GigE Vision Producer now supports GenICam action control. For more information, please refer to the new HDevelop example gigevision2_action_control.hdev.
  • The GigE Vision Producer now supports pending acknowledges which allow to wait for device response to long taking commands without needing to manually adjust the timeout.
  • 'do_write_configuration' has been extended to store not only the current device configuration but also generate persistence files for all the GigE Vision Producer modules (system, interface, device and data stream), see Parameters – Persisting Device Status.
  • Added new parameters 'buffer_timestamp_ns' and 'device_timestamp_frequency' to improve the usability of 'buffer_timestamp' which on its own is unit-agnostic.
  • Some generic parameters passed to open_framegrabber were not available through get_framegrabber_param. This problem has been fixed.
  • String parameters longer than 1024 characters were silently cropped by get_framegrabber_param. This problem has been fixed.
  • When 'start_async_after_grab_async' was set 'disable', the acquisition was stopped on the remote device after each frame. This problem has been fixed.
  • Some parameters depending on '[Interface]DeviceSelector' (like '[Interface]DeviceTLVersionMajor') were not updated when '[Interface]DeviceSelector' was changed. This problem has been fixed.
  • For consistency, the example gigevision2_atc4_objectmodel3d has been renamed to gigevision2_automation_technology_c4_objectmodel3d.hdev.
• Revision 13.0.2 (Apr 27, 2018):
  • Added support for the 'Mono4p' pixel format.
  • Added support for the 'YCbCr411_8' pixel format.
  • Unsupported pixel formats are now tried to be returned in their actual image dimensions if they are similar enough to a supported Mono format. Before, all unsupported formats were returned as square images (see Raw Output Format).
  • On Unix systems, HALCON crashed when ended without calling close_framegrabber. This problem has been fixed.
  • When 'DeviceUserID' was set to ' ' (a single space), it could not be used to connect. This problem has been fixed.
  • When trying to connect to a busy device using its 'DeviceUserID', a misleading low-level error appeared. This problem has been fixed.
  • Device discovery per network interface is now done in parallel.
  • The Windows Firewall can now be traversed if the camera supports the Message Channel Source Port (MCSP) and Stream Channel Source Port (SCSPx) registers. The traversal can be configured with the new parameters '[Device]DeviceMessageChannelKeepAliveTimeout' and '[Stream]DeviceStreamChannelKeepAliveTimeout'.
  • The default value of the parameter '[Device]LinkCommandTimeout' has been changed from 400000 to 200000 microseconds.
  • The packet size negotiation algorithm has been revised regarding compliance with the GigE Vision specification. To make it more transparent and configurable, the following parameters have been introduced: '[Interface]GevInterfaceMTU', '[Stream]DeviceStreamChannelPacketSize', '[Stream]DeviceStreamChannelPacketSizeMin', '[Stream]DeviceStreamChannelPacketSizeMax', '[Stream]DeviceStreamChannelPacketSizeInc', '[Stream]DeviceStreamChannelNegotiatePacketSize'.
  • When changing 'GevSCPSPacketSize' dynamically, corrupt or no images at all could be acquired. This problem has been fixed.
  • The Streaming Filter now works on WiFi interfaces. Before, devices connected via a WiFi interface fell back on the socket driver.
  • The Streaming Filter did not work on Killer network interface cards with jumbo frames. This problem has been fixed.
  • The socket driver could fail to request a resend of a missing block trailer. This problem has been fixed.
  • The internal locking of the Streaming Filter has been improved to increase performance and stability especially for multiple cameras.
  • The resend strategy of the Streaming Filter has been revised and optimized for low latency streaming.
  • The parameter '[Stream]GevStreamMaxBlockDuration' had no effect on the Streaming Filter and was instead fixed to 200ms. This problem has been fixed.
  • The following parameters of the socket driver have been adapted or introduced to the Streaming Filter: '[Stream]GevStreamUnavailablePacketCount', '[Stream]GevStreamMaxPacketGaps', '[Stream]GevStreamMaxBlockDuration', '[Stream]GevStreamDeliverIncompleteBlocks', '[Stream]GevStreamFullBlockTerminatesPrev', '[Stream]GevStreamEngineUnderrunCount'.
  • Example for using GigE Vision Chunk Data has been added.
• Revision 13.0.1 (Nov 28, 2017):
  • First official release.