MVTec Software GmbH
 

Documentation

GigEVision2 / HALCON / MVTec Software GmbH

Image Acquisition Interface for GigE Vision compliant cameras

Interface: GigEVision2
Revision: 13.0.2
Date: 2018-04-27

General

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).

System Requirements

  • 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.
  • 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.1.8.1.
  • GenICam version 3.0.2 . The corresponding files are part of the HALCON GigEVision2 package and are located in the directory genicam within the HALCON base directory %HALCONROOT%.
  • 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.

Environment Variables

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.

Installation

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
    • The genicam folder to /Library/Frameworks/HALCON.framework/Libraries
    • The examples folder to the version subdirectory at /Users/Shared/Library/Application Support
    • The doc folder to the version subdirectory at /Library/Application Support

Features

  • User-space implementation of the GigE Vision protocol.
    For Windows the MVTec GigE Vision Streaming Filter is available and used automatically if installed to improve performance.
  • Support for GigE Vision 1.x up to 2.x (preliminary support for upcoming 2.1 multipart payload)
  • 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 chunk data.
  • Support of GenICam event data.
  • 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.

Limitations

  • The MVTec GigE Vision Streaming Filter is available only under Windows. For more details see paragraph MVTec GigE Vision Streaming Filter.
  • No support of BayerXXPacked, BGRXXPlanar, and RGBXXPlanar pixel formats yet.
  • Only stream channel 0 supported.
  • No support of acquisition from devices with read-only access mode
  • On 32 bit systems, 64 bit parameter values cannot be used.
  • The new SFNC 'Transfer Control' features are currently not considered for acquisition control – there are currently not enough devices with such functionality on the market.

GenICam GenApi

  • This interface uses GenApi version 3.0.2, 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, Windows uses %TEMP% and Linux/macOS use $TMP or /tmp if $TMP is not set for cached XML files.

GigE Vision

  • This interface implements GigE Vision specification version 2.0, covering all three basic protocols it defines: control, image/data streaming including chunk data and asynchronous device events.
  • The interface also provides support for the new functionality proposed for (not yet ratified) specification version 2.1, including in particular the multi-part streaming used e.g. by 3D devices.
  • The device features control is accessed via GenApi.
  • To provide a consistent user experience, the control features of the GigE Vision Producer of this interface are also controlled via GenApi.

GigE Vision Device Access

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

MVTec GigE Vision Streaming Filter

  • 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.
  • 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 by the installer in %HALCONROOT%\misc. To do this, 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:
    For updating from an older version of the 'MVTec GigE Vision Streaming Filter', please 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.
  • 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.

Using Multiple Cameras

  • 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.

Identifying and Opening a Device

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. Finally, instead of the unique device ID, the user-defined name attached to the device can be used. 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. Only the ' | device:<device id>' string entry is mandatory for open_framegrabber, the others might be omitted.

If you know the device ID in advance, you can create the string yourself – without using info_framegrabber. As shown above, it consists of entries separated by ' | ', the 'device' entry being the only significant one. The optional 'interface' entry specifies the network interface to look for the device.
When a string without any ' | ' 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). Note that 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.

Selection of GenICam Feature Description File(s)

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.

Parameters – Naming Conventions

The following groups of parameters exist:
  • Internal parameters of the HALCON GigEVision2 image acquisition interface itself. These are named following the "underscore" naming style, e.g., color_space, and are all lowercase.
  • 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.

Parameters – Sharing Among Devices

The parameters belonging to the system and interface modules of the GigE Vision Producer (ie. 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.

Parameters – GenICam Data Types

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 and when the GenICam feature in question is identified to be an IP or MAC address, the string representation of the address 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.

Parameters – Persisting Device Status

The current status of the device settings (values of all the parameters defining its working state) might be persisted at any moment. The persistence functionality consists of two steps, storing the current configuration to a file and later re-loading it back to the device. The current device settings 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.

Note that while the format of the file is intentionally human readable and the file 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 file can lead to errors when using it.

It is important to know that while performed by the software, the feature settings persistence is actually a camera-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 camera manufacturer could provide additional information or help.

The same persistence file can be applied to the entire set of devices of the same type and firmware version. Applying the persistence file 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). The persistence file entry in the ini file will have the format RemotePersistence=%PATH_TO_PERSISTENCE_FILE_OF_THE_DEVICE%

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.

Acquisition – Overview, Device Control

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', ...).
Note that the interface properly recognizes the 'Continuous', 'SingleFrame' and 'MultiFrame' acquisition modes configured on the device and adjusts the acquisition control logic accordingly.
Note that the HALCON acquisition interface itself 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.

Acquisition – Buffer Handling

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.

Acquisition – Image Format Handling

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.

Acquisition – Grab Operators

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.

Using 3D Devices

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.

Raw Output Format – Custom Pixel Formats, Non-image Buffers

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 'raw_buffer_type' and 'raw_buffer_padding_bytes' parameters.

Chunk Data

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.
It is important to remember, that the chunk data related features will provide only 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).

Feature Change Notifications (Callbacks)

It is possible to receive notifications about changes of any features exposed through the GenICam interface by the camera and GigE Vision Producer.
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.
The notification callbacks can be registered for individual features using set_framegrabber_callback - see corresponding operator documentation.

Event Data

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, i.e. get_framegrabber_param. 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, 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.
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.

Advanced Streaming Engine Control

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 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 eg. 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.
On the other hand, the engine provides various statictics 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.

Advanced Event Engine Control

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.

Debugging GigE Vision Applications

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'.

Using HDevelop Image Acquisition Assistant

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.

Using Internal Color Conversion

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.

Parameters for info_framegrabber

Parameter Value List Type Kind Description
'bits_per_channel' [-1, 8, 10, 12, 14, 16] integer pre-defined Values for bits per channel.
'camera_type' ['CAMFILE:', 'ini;xml', '<path>', 'default'] string pre-defined Syntax for connection configuration file and default value.
'color_space' ['default', 'gray', 'raw', 'rgb', 'yuv'] string pre-defined Values for color space.
'defaults' [0, 0, 0, 0, 0, 0, 'progressive', -1, 'default', -1.0, 'false', 'default', '0', 0, 0] mixed pre-defined Default values for open_framegrabber.
'device' [' | device:<device id> | unique_name:<unique name> | user_name:<user-defined name> | interface:<interface id> | producer:Esen'] string dynamic List of GigE Vision devices discovered in the system with information about their device ID, unique name, user-defined name, interface to which they are connected and identifier of the image acquisition interface. See the full description in section about device opening. Only devices that are currently available for opening are listed.
'external_trigger' [] Ignored.
'field' [] Unused.
'general' [] string pre-defined Information about the HALCON GigEVision2 interface.
'generic' ['', 'num_buffers=<num>', 'direct_connection=<mode>', 'force_ip=<interface_ip/device_mac/force_device_ip/force_device_mask[/force_device_gateway/force_command_timeout]>', 'force_sockdrv=1', 'streaming_mode=0', 'device_event_handling=0', 'workarounds=<list>'] string pre-defined Value list for the Generic parameter.
'horizontal_resolution' [0, 1] integer pre-defined Value list for horizontal resolution.
'image_height' [] Unsupported query.
'image_width' [] Unsupported query.
'info_boards' [' | device:<device_id> | unique_name:<unique_name> | user_name:<user_defined_name> | interface:<interface_id> | producer:Esen | vendor:<device_vendor> | model:<device_model> | device_ip:<device_ip> | interface_ip:<interface_ip> | status:<device_status> | suggestion:<generic_param>'] string dynamic List of GigE Vision devices discovered in the system with additional information as a string. Some values are only shown, if they are available. For misconfigured devices (such as those having an IP of a wrong subnet) a corresponding generic parameter to resolve the problem is suggested.
  • device_id is the name of the device, which will be shown by info_framegrabber(...,'device',...). If a user_name (or 'DeviceUserID') is set, then this will be shown. Otherwise the unique_name is used.
  • unique_name is a string, which contains the device MAC address, the vendor and the model separated by underscores. No other device should have the same string, so this is a unique name for the device.
  • user_name represents the value of the feature 'DeviceUserID', which is a user-defined name for the device. It can be set if the device is opened and provides this feature.
  • interface shows the hardware interface by which the device is connected to the PC. For GigEVision2 the value of this entry is 'Esen_ITF_' with the MAC address, IP and subnet mask of the the network interface card appended.
  • producer shows the name of the underlying GenICamTL producer.
  • vendor represents the value of the feature 'DeviceVendorName'.
  • model represents the value of the feature 'DeviceModelName'.
  • tl_type shows the type of the underlying transport layer, i.e. 'U3V'.
  • device_ip shows the IP address of the device, e.g. 169.54.12.243/16. This value can also be queried by the feature 'GevCurrentIPAddress'.
  • interface_ip is the IP address of the interface (mostly a network card), which has detected the device by a broadcast request, e.g. 169.54.18.34/16.
  • status shows, if the device is correctly configured or not. The possible values are 'available', 'read-only', 'busy', 'misconfigured' and 'unknown'. For misconfigured devices (such as those with IP settings for incorrect subnet) a corresponding generic parameter to resolve the problem is suggested through the suggestion info token. Status of 'busy' means the device is currently opened by another application. Even devices that are currently not available for opening are listed.
  • suggestion is added only if status is reported as 'misconfigured' because the device is on wrong subnet. The value of the suggestion info will be the generic 'force_ip' parameter that can be used to resolve the problem. This means that if you will pass the suggested 'force_ip' parameter as-is in the open_framegrabber operator's Generic parameter (see its documentation), the GigEVision2 interface will attempt to switch the device temporarily to correct subnet and open it.
'parameters' ['<parameters>'] string pre-defined Pre-defined parameters of the HALCON interface.
'parameters_readonly' ['<parameters>'] string pre-defined Pre-defined read-only parameters of the HALCON interface.
'parameters_writeonly' ['<parameters>'] string pre-defined Pre-defined write-only parameters of the HALCON interface.
'port' [] Unused.
'revision' '<revision>' string pre-defined Revision number of the GigEVision2 interface.
'start_column' [] Unsupported query.
'start_row' [] Unsupported query.
'vertical_resolution' [0, 1] integer pre-defined Value list for vertical resolution.

Parameters for open_framegrabber

Parameter Values Default Type Description
Name 'GigEVision2' string Name of the HALCON interface.
HorizontalResolution 0, 1, resolution 1 integer Set the desired horizontal resolution of the camera image:
  • 0: Keep the current Width settings of the camera.
  • 1: If vertical_resolution is also set to 1, configure full resolution of the camera using GenICam SFNC features (resetting binning/decimation features and setting the image size to maximum).
  • resolution: Use the value directly as image Width.
VerticalResolution 0, 1, resolution 1 integer Set the desired vertical resolution of the camera image:
  • 0: Keep the current Height settings of the camera.
  • 1: If horizontal_resolution is also set to 1, configure full resolution of the camera using GenICam SFNC features (resetting binning/decimation features and setting the image size to maximum).
  • resolution: Use the value directly as image Height.
ImageWidth --- 0 Ignored.
ImageHeight --- 0 Ignored.
StartRow --- 0 Ignored. Configure the image size through device parameters.
StartColumn --- 0 Ignored. Configure the image size through device parameters.
Field --- Ignored.
BitsPerChannel -1, 8, 10, 12, 14, 16 -1 integer Number of bits per channel of the resulting HALCON image. In case of -1 the bit depth of each respective acquired buffer is used. By specifying a value greater than 8 the grabbed images are delivered as uint2 images.
ColorSpace 'default', 'gray', 'raw', 'rgb', 'yuv' 'default' string Specify the desired color space and thus the number of image channels of the resulting HALCON image. In case of 'default' for Mono pixel formats, ColorSpace is set to 'gray', otherwise to 'rgb' (and for unknown pixel formats to 'raw').
Generic '', ['num_buffers=<num>', 'direct_connection=<mode>', 'force_ip=<interface_ip/device_mac/force_device_ip/force_device_mask[/force_device_gateway/force_command_timeout]>', 'force_sockdrv=1', 'streaming_mode=0', 'device_event_handling=0', 'workarounds=<list>'], -1 -1 mixed With the Generic parameter some important values can be set before the camera is initialized. Note that the parameter names including the values must be strings, e.g., 'num_buffers=5' sets the number of buffers to 5.
The following parameters are available:
  • num_buffers: To set the maximum number of acquisition buffers used. Note that depending on the image size of the used camera a high number of buffers can exceed the available memory size of your computer. We recommend to use at least 2 buffers. 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. Default: 4.
  • direct_connection: Enables direct connection to the device using its known GenTL interface and device ID. The GenTL specification allows opening the device directly when the device/interface ID is known, without explicitly instructing the GenTL Producer to refresh its internal device list, thus optimizing unnecessary timeouts. Because some GenTL Producers fail to implement this properly, the parameter is disabled by default. Possible values are 'enable' and 'disable'.
  • force_ip: Request to force temporary new IP settings to the device before connecting. Used in situations when the device is configured for subnet not matching the interface it is connected to. The parameter format is 'force_ip=interface_ip/device_mac/force_device_ip/force_device_mask', where interface_ip is current IP address of the interface the device is expected to be connected to (ie. the interface on which the force IP request should be sent), device_mac is the MAC address of the device to be configured, force_device_ip and force_device_mask is the new IP address and subnet mask to be forced into the device. All the IP addresses are in the usual decimal dot-separated format, the MAC address in the usual hexadecimal colon-separated format. Note that the forced IP settings are not persistent (will not have effect beyond device's reboot. The basic format of the parameter described above can be optionally extended by two additional parameters 'force_ip=interface_ip/device_mac/force_device_ip/force_device_mask/force_device_gateway/force_command_timeout', where force_device_gateway is the new default gateway to be configured on the device and force_command_timeout specifies the time in microseconds, how long the operation should wait for device's acknowledge of the force IP success. When not present, default gateway '0.0.0.0' will be used and suitable (short) command acknowledge timeout. Note also that when querying the device list using info_framegrabber(...'info_boards'...), for each device with incorrect IP settings (wrong subnet), the GigEVision2 will suggest the force_ip generic parameter including suitable IP address and other parameters corresponding with the interface device was discovered on (verifying that given suggested IP address is not currently in use on that network segment. When working with the HDevelop Image Acquisition Assistant, it will directly suggest to apply the generic parameter when connecting to the device.
  • force_sockdrv: When present, the socket driver is always used for handling of the devices' data stream. The filter driver will not be automatically used even if available.
    This parameter is applicable on Windows systems only.
  • streaming_mode: In order to disable streaming (grab-related operators), this parameter has to be set to 0. The streaming is by default switched on for devices with streaming support.
  • device_event_handling: In order to disable device events which can be useful in case of handling multiple cameras to reduce the used resources like the number of transfers in the Producer, this parameter has to be set to 0. The event handling is by default switched on for devices with event support.
  • workarounds: Enables one or more of the workarounds supported by the GigEVision2 image acquisition interface. The workarounds are options slightly altering the image acquisition interface behavior in order to cope with some common problems of devices . The individual workaround names might be listed using any separator, for example a space or comma. Supported workarounds are:
    • enable_range_validation: When this workaround is enabled, an additional check is performed when querying the range of a parameter: check if min <= max – and an error is returned if the check fails. The invalid range of a GenICam based parameter might be the result of a bug in the corresponding GenICam description file.
ExternalTrigger --- Ignored. To configure the trigger mode please use set_framegrabber_param with the generic (SFNC) trigger parameters of the camera.
CameraType 'default', <ini/xml filename> 'default' string Full path to the configuration file with the specification of alternative GenICam description files to be loaded for the device and GigE Vision Producer, see detailed description in section about device opening.
Device ' | device:<device id> | unique_name:<unique name> | user_name:<user-defined name> | interface:<interface id> | producer:Esen', '<device id>' string To open a camera, the device name as shown in info_framegrabber(...'device'...) or info_framegrabber(...'info_boards'...) can be used. Some of the string entries might be skipped or set as 'default'. To open a specific camera, either device or unique_name has to be set. As a shortcut, only the device ID or user-defined name might be specified or the string 'default' can be used. See full description in section about device opening.
Port --- Unused.
LineIn --- Ignored.

Parameters for set_framegrabber_param

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 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:
Parameter Values Default Type Description
'[Device]DeviceEventsThreadApplyPriority' --- integer Applies the thread priority and scheduling policy (if applicable on given operating system) configured through the '[Device]DeviceEventsThreadPriority' and '[Device]DeviceEventsThreadSchedulingPolicy' parameters to the event processing thread. If the thread is running, the values are directly applied. If the thread is not running in the moment, the values are stored and will be applied as soon as the thread is started again. It is responsibility of the application to ensure that the calling process has sufficient privileges.
The feature is not available for devices not supporting device events or if the event handling was disabled using the 'device_event_handling=0' generic parameter.
BEWARE: Setting this parameter can lead to an unusable or poorly performing system, use with care.
'[Device]DeviceEventsThreadPriority' <thread_priority> integer OS-specific thread priority value to be used for the internal event processing thread. The actual values are directly the priority identifiers of the operating system, e.g. THREAD_PRIORITY_HIGHEST under Windows or a real-time priority value under Linux.
The actual priority is applied only after executing the '[Device]DeviceEventsThreadApplyPriority' command parameter, possibly together with the '[Device]DeviceEventsThreadSchedulingPolicy' value if applicable on given system.
It is the responsibility of the application to ensure that the calling process has sufficient privileges to apply the priority change and that the value written to the parameter is a valid priority identifier. After applying '[Device]DeviceEventsThreadApplyPriority', the application can read back the priority value to verify if it was properly applied.
Note that when opening the device, the GigE Vision Producer attempts itself to elevate the thread priority to a suitable value.
The feature is not available for devices not supporting device events or if the event handling was disabled using the 'device_event_handling=0' generic parameter.
BEWARE: Setting this parameter can lead to an unusable or poorly performing system, use with care.
'[Device]DeviceEventsThreadSchedulingPolicy' <scheduling_policy> integer OS-specific scheduling policy value to be used for the internal event processing thread. The actual values are directly the priority identifiers of the operating system, e.g. SCHED_FIFO under Linux. Note that this feature is not available under Windows.
The actual scheduling policy is applied only after executing the '[Device]DeviceEventsThreadApplyPriority' command parameter, together with the '[Device]DeviceEventsThreadPriority' value.
It is the responsibility of the application to ensure that the calling process has sufficient privileges to apply the scheduling policy and that the value written to the parameter is a valid scheduling policy identifier. After applying '[Device]DeviceEventsThreadApplyPriority', the application can read back the scheduling policy value to verify if it was properly applied.
The feature is not available for devices not supporting device events or if the event handling was disabled using the 'device_event_handling=0' generic parameter.
BEWARE: Setting this parameter can lead to an unusable or poorly performing system, use with care.
'[Device]DeviceLinkHeartbeatMode' 'Off', 'On' 'Off' string Allows to disable the heartbeat control on the device. The parameter will be only present if supported by given device. It is usually only good idea to disable the heartbeat if debugging the application (to prevent loosing the device connection when hitting a breakpoint). When disabling and not re-enabling the device and if the application fails to properly close the connection (such as during crash or hard debugger stop), the device will never assume the connection has expired and will have to be rebooted. fails to maintain the heartbeat protocol. In most cases leaving the default value intact is the best solution. A possible exception can be to significantly prolong the timeout while debugging, if given device does not support heartbeat disabling.
'[Device]DeviceLinkHeartbeatTimeout' <timeout> integer Heartbeat timeout (in usec) after which the device disconnects if the application fails to maintain the heartbeat protocol. In most cases leaving the default value intact is the best solution. A possible exception can be to significantly prolong the timeout while debugging, if given device does not support heartbeat disabling.
'[Device]DeviceMessageChannelKeepAliveTimeout' 30000 float Interval (in milliseconds) between keep-alive packets sent while listening for device events to the device's message channel port to simulate the events traffic is outbound rather than inbound, thus helping to receive the events reliably in presence of a firewall. The actual required interval might be specific to the actual firewall in use. Zero means no keep-alive packets are sent at all.
'[Device]EventNotification' 'Off', 'On' 'Off' string Enables/disables delivery of GigE Vision Producer device module event selected in '[Device]EventSelector'.
'[Device]EventSelector' 'DeviceLost' string Selects a GigE Vision Producer device module event to be enabled/disabled using '[Device]EventNotification'.
'[Device]LinkCommandRetryCount' 3 integer Specifies number of times the HALCON GigEVision2 should attempt to retry sending a given control command to the device when not receiving corresponding command acknowledge from the device (assuming the command got lost). Works together with '[Device]LinkCommandTimeout' and usually should stay intact.
'[Device]LinkCommandTimeout' 200000 integer Specifies the timeout (in usec) the HALCON GigEVision2 should wait for device acknowledge for individual control commands before assuming the command got lost and trying to send it again. Works together with '[Device]LinkCommandRetryCount' and usually should stay intact.
'[Interface]GevDeviceForceGateway' <gateway> integer Default gateway to be forced (together with IP address) into the device selected in '[Interface]DeviceSelector'. This parameter is only used to prepare the desired IP configuration values for the device (together with '[Interface]GevDeviceForceIPAddress' and '[Interface]GevDeviceForceSubnetMask', the settings are actually applied together using '[Interface]GevDeviceForceIP'.
Use with care, using configuration not matching the interface the device is conected to may render the device unreachable. Intended to fix exactly these kinds of situations. Applicable only on devices that are not currently open.
Note that the 'force_ip' generic parameter in open_framegrabber can serve similar purpose.
'[Interface]GevDeviceForceIP' --- integer Sends request to change current IP settings (IP address, subnet mask and default gateway) to the device selected in '[Interface]DeviceSelector'. The requested new settings are those previously stored into parameters '[Interface]GevDeviceForceIPAddress', '[Interface]GevDeviceForceSubnetMask' and '[Interface]GevDeviceForceGateway'. Use with care, using configuration not matching the interface the device is conected to may render the device unreachable. Intended to fix exactly these kinds of situations. Applicable only on devices that are not currently open, opened devices will ignore the request. The settings will not persist the device's power cycle.
Note that the 'force_ip' generic parameter in open_framegrabber can serve similar purpose.
'[Interface]GevDeviceForceIPAddress' <ip_address> integer IP address to be forced (together with subnet mask and gateway) into the device selected in '[Interface]DeviceSelector'. This parameter is only used to prepare the desired IP configuration values for the device (together with '[Interface]GevDeviceForceSubnetMask' and '[Interface]GevDeviceForceGateway', the settings are actually applied together using '[Interface]GevDeviceForceIP'.
Use with care, using configuration not matching the interface the device is conected to may render the device unreachable. Intended to fix exactly these kinds of situations. Applicable only on devices that are not currently open.
Use '[Interface]GevDeviceProposeIP' to fill this parameter automatically with suitable value.
Note that the 'force_ip' generic parameter in open_framegrabber can serve similar purpose.
'[Interface]GevDeviceForceSubnetMask' <subnet_mask> integer Subnet mask to be forced (together with IP address) into the device selected in '[Interface]DeviceSelector'. This parameter is only used to prepare the desired IP configuration values for the device (together with '[Interface]GevDeviceForceIPAddress' and '[Interface]GevDeviceForceGateway', the settings are actually applied together using '[Interface]GevDeviceForceIP'.
Use with care, using configuration not matching the interface the device is conected to may render the device unreachable. Intended to fix exactly these kinds of situations. Applicable only on devices that are not currently open.
Note that the 'force_ip' generic parameter in open_framegrabber can serve similar purpose.
'[Interface]GevDeviceProposeIP' --- integer Generates proposal for suitable IP settings (IP address, subnet mask and default gateway) to the device selected in '[Interface]DeviceSelector'. The settings are proposed to match the subnet of the interface where the device is connected, so that the device would be directly reachable.
The proposed settings are stored into parameters '[Interface]GevDeviceForceIPAddress', '[Interface]GevDeviceForceSubnetMask' and '[Interface]GevDeviceForceGateway' and can be applied to the device using '[Interface]GevDeviceForceIP'.
'[Stream]DeviceStreamChannelKeepAliveTimeout' 30000 float Interval (in milliseconds) between keep-alive packets sent during active streaming to the device's stream channel port to simulate the stream traffic is outbound rather than inbound, thus helping to stream reliably in presence of a firewall. The actual required interval might be specific to the actual firewall in use. Zero means no keep-alive packets are sent at all.
'[Stream]DeviceStreamChannelNegotiatePacketSize' --- integer Starts negotiation for the optimal packet size considering the remote device, host and their connection path. The negotiation result is applied on the device and reflected in '[Stream]DeviceStreamChannelPacketSize'. If the negotiation fails, the algorithm attempts to revert the configuration to the initial packet size value.
Note that the negotiation is applied automatically when opening the device.
'[Stream]DeviceStreamChannelPacketSize' <packet_size> integer Packet size configured for the device stream channel (similar feature might appear also in feature set of the remote device itself). Configures both the remote device and GigE Vision Producer.
'[Stream]DeviceStreamChannelPacketSizeInc' --- integer Controls desired increment of the packet size feature to be used for the stream channel. Affects both the direct control of the packet size ('[Stream]DeviceStreamChannelPacketSize') as well as the negotiation algorithm ('[Stream]DeviceStreamChannelNegotiatePacketSize').
The limit should be usually set in sync with actual limits imposed by the device itself, unless there are reasons to apply stricter limits. When the device limits are unknown, the initial value is set to 4.
'[Stream]DeviceStreamChannelPacketSizeMax' --- integer Controls desired maximum of the packet size feature to be used for the stream channel. Affects both the direct control of the packet size ('[Stream]DeviceStreamChannelPacketSize') as well as the negotiation algorithm ('[Stream]DeviceStreamChannelNegotiatePacketSize').
The limit should be usually set in sync with actual limits imposed by the device itself, unless there are reasons to apply stricter limits. When the device limits are unknown, the initial value is set to the MTU size accepted by the network interface the device is connected to.
'[Stream]DeviceStreamChannelPacketSizeMin' --- integer Controls desired minimum of the packet size feature to be used for the stream channel. Affects both the direct control of the packet size ('[Stream]DeviceStreamChannelPacketSize') as well as the negotiation algorithm ('[Stream]DeviceStreamChannelNegotiatePacketSize').
The limit should be usually set in sync with actual limits imposed by the device itself, unless there are reasons to apply stricter limits. When the device limits are unknown, the initial value is set to 576.
'[Stream]EventNotification' 'Off', 'On' 'Off' string Enables/disables delivery of GigE Vision Producer data stream module event selected in '[Stream]EventSelector'.
'[Stream]EventSelector' 'TransferEnd' string Selects a GigE Vision Producer data stream module event to be enabled/disabled using '[Stream]EventNotification'.
'[Stream]GevStreamDeliverIncompleteBlocks' 0, 1 1 integer Flag indicating if incomplete buffers (with one or more missing packets) should be delivered or discarded. Note that if the leader or trailer of a block is missing it will be discarded anyway.
'[Stream]GevStreamFullBlockTerminatesPrev' 0, 1 0 integer Flag indicating whether receiving a complete buffer immediately terminates any previous ones in the acquisition queue, no matter if resend is still pending for them, thus avoiding blocking the full one.
'[Stream]GevStreamMaxBlockDuration' 0 float Maximal duration ('on the wire') of a block in microseconds. When it expires, the engine will assume the block trailer (block trailing control packet) should be already received - and if packet resend is supported, it will ask to resend it.
Zero means no limit, which is suitable for example for line scan devices with sparse line triggers.
Note: for filter driver this is rounded to milliseconds. If it expires the oldest block is checked if it can be delivered. If this is not the case resends for the oldest block are requested. This block is also marked for delivery if more packets than the trailing ones are missing. When the timer expires a second time marked blocks are either discarded or delivered.
'[Stream]GevStreamMaxPacketGaps' 30 integer Socket driver: Maximal number of packet gaps in a block. Affects the amount of resources allocated for the resend mechanism.
Filter driver: Percentage of allowed missing packets for an incomplete block. Consequently this is also the maximum number of resend requests sent out per block.
When exceeded, the engine will give up trying to finish this block and will discard it.
'[Stream]StreamBufferHandlingMode' 'OldestFirst', 'OldestFirstOverwrite', 'NewestOnly' 'OldestFirst' string Selects the mode the streaming engine uses to handle newly acquired data, in particular when the camera runs faster than the application processing. The parameter is writeable only if no acquisition is active. Supported values are:
  • 'OldestFirst': The acquired buffers are always delivered in FIFO manner (oldest first). If the acquisition engine receives a new buffer from the camera but has no available free buffer to fill it in, the new data is discarded.
  • 'OldestFirstOverwrite': The acquired buffers are always delivered in FIFO manner (oldest first). If the acquisition engine receives a new buffer from the camera but has no available free buffer to fill it in, it checks, whether there are older buffers waiting for delivery, not yet picked up by the consumer. If yes, it takes the oldest of them, overwrites it with the new data and appends it to the end of the output queue. If the output queue is empty (no buffer available for overwriting), the new data is discarded.
  • 'NewestOnly': The output queue of buffers waiting for delivery never contains more than a single (newest) buffer. If the acquisition engine receives a new buffer and there is already an older buffer waiting for delivery in the output queue, the new buffer is put to the output queue instead and the old one is reused for next acquisition. If there are no available free buffers and the output queue is also empty, new data is discarded.
'[Stream]StreamThreadApplyPriority' --- integer Applies the thread priority and scheduling policy (if applicable on the given operating system) configured through '[Stream]StreamThreadPriority' and '[Stream]StreamThreadSchedulingPolicy' parameters to the stream processing thread. If the thread is running (acquisition started), the values are directly applied. If the thread is not running in the moment, the values are stored and will be applied as soon as the thread is started again. It is the responsibility of the application to ensure that the calling process has sufficient privileges.
BEWARE: Setting this parameter can lead to an unusable or poorly performing system, use with care.
'[Stream]StreamThreadPriority' <thread_priority> integer OS-specific thread priority value to be used for the internal stream processing thread. The actual values are directly the priority identifiers of the operating system, e.g. THREAD_PRIORITY_HIGHEST under Windows or a real-time priority value under Linux.
The actual priority is applied only after executing the '[Stream]StreamThreadApplyPriority' command parameter, possibly together with the '[Stream]StreamThreadSchedulingPolicy' value if applicable on given system.
It is the responsibility of the application to ensure that the calling process has sufficient privileges to apply the priority change and that the value written to the parameter is a valid priority identifier. After applying '[Stream]StreamThreadApplyPriority', the application can read back the priority value to verify if it was properly applied.
Note that when opening the device, the GigE Vision Producer attempts itself to elevate the thread priority to a suitable value.
BEWARE: Setting this parameter can lead to an unusable or poorly performing system, use with care.
'[Stream]StreamThreadSchedulingPolicy' <scheduling_policy> integer OS-specific scheduling policy value to be used for the internal stream processing thread. The actual values are directly the priority identifiers of the operating system, e.g. SCHED_FIFO under Linux. Note that this feature is not available under Windows.
The actual scheduling policy is applied only after executing the '[Stream]StreamThreadApplyPriority' command parameter, together with the '[Stream]StreamThreadPriority' value.
It is the responsibility of the application to ensure that the calling process has sufficient privileges to apply the scheduling policy and that the value written to the parameter is a valid scheduling policy identifier. After applying '[Stream]StreamThreadApplyPriority', the application can read back the scheduling policy value to verify if it was properly applied.
BEWARE: Setting this parameter can lead to an unusable or poorly performing system, use with care.
'add_objectmodel3d_overlay_attrib' 'disable', 'enable' 'disable' string Controls if the acquisition interface should attempt to append the intensity/color overlay to the generated 3D object models. Applicable only if a 3D object model is being output from given grab operator. When switched on, the acquisition interface will try to find suitable information within the acquired data (if it is provided by the device). If so, it appends the overlay information for each point in the output model in form of an extended attribute. Note that in some advanced use cases there might be multiple potential overlay images output by the device, the acquisition interface therefore attempts to find the most suitable one.
First, it tries to identify data marked as "intensity" image in the acquired data. If found and provided as monochrome 2D image, it is appended as '&intensity_gray' extended attribute. If found and provided as RGB image, it is appended as three extended attributes, '&intensity_red', '&intensity_green' and '&intensity_blue'.
If "intensity" data cannot be identified, it tries to find data marked as "reflectance". If found and provided as monochrome 2D image, it is appended as '&reflectance_gray' extended attribute. If found and provided as RGB image, it is appended as three extended attributes, '&reflectance_red', '&reflectance_green' and '&reflectance_blue'.
Finally, if neither "intensity" nor "reflectance" data can be identified (either not present or not correctly marked by the device, it picks the first 2D image within the acquired data than can be mapped to the 3D coordinates. If found and provided as monochrome 2D image, it is appended as '&overlay_gray' extended attribute. If found and provided as RGB image, it is appended as three extended attributes, '&overlay_red', '&overlay_green' and '&overlay_blue'.
If no suitable 2D image is found, no overlay is appended. The actually appended extended attributes can be queried for example using the get_object_model_3d_params operator with the 'extended_attribute_names' parameter. The overlay can be also used for visualization purposes.
'bits_per_channel' -1, 8, 10, 12, 14, 16 integer Number of bits per channel of the resulting HALCON image. In case of -1 the bit depth of each respective acquired buffer is used. By specifying a value greater than 8 the grabbed images are delivered as uint2 images.
'buffer_reallocation_mode' 'only_increase_size', 'follow_payloadsize' 'only_increase_size' string Defines the strategy to follow when reallocating the buffers for a new acquisition. In case of 'only_increase_size', the buffers will be only reallocated when the payload size increases. In case of 'follow_payloadsize', the buffers will be reallocated every time the payload size changes.
'clear_buffer' 'disable', 'enable' 'disable' string If enabled, each buffer content is cleared before re-queueing (all bytes set to 0xF0 regardless the expected pixel format), so you can see which parts of an image are missing, in case e.g. the transfer of some image packets failed. This parameter adds of course an runtime overhead to write the 0xF0 data every time a buffer is queued. It is mainly useful for debugging in combination with transport layers which do not guarantee the transfer of complete images. Please note, that this parameter does not modify the buffer queue, only the content of a buffer will be set to a defined state.
'color_space' 'default', 'gray', 'raw', 'rgb', 'yuv' string Specify the desired color space and thus the number of image channels of the resulting HALCON image. In case of 'default' for Mono pixel formats, ColorSpace is set to 'gray', otherwise to 'rgb' (and for unknown pixel formats to 'raw').
'confidence_mode' 'off', 'object_model_3d' 'off' string Controls if (and how) the information about pixel confidence level is used by the acquisition interface. Applicable only for devices and use cases where the confidence information is delivered (per-pixel) together with the actual pixel data.
The threshold to distinguish between valid and invalid pixels is controlled using the 'confidence_threshold' parameter.
Note that in some use cases there might be other criteria how to mark given pixel invalid, for example if the device uses "invalid pixel value" for a 3D coordinate. These cases are not covered by the 'confidence_mode' parameter and such invalid pixels are always rejected from the 3D object model. Possible values are:
  • off: Default value. The pixel confidence information is not applied to any of the grab operator outputs, even if supplied by the device.
  • object_model_3d: If the pixel confidence level information is available, it is applied to the eventually generated 3D object models (but not to any other outputs, in particular not to the image outputs). This means that pixels ("points") with confidence lower than the configured threshold are not included in the generated 3D object model.
'confidence_threshold' [0.0, 1.0] 0.5 float Threshold separating between valid and invalid pixels. Applicable only for devices and use cases where the confidence information is delivered (per-pixel) together with the actual pixel data. The decision how (to which outputs) the confidence threshold is applied is controlled using the 'confidence_mode' parameter.
The threshold is interpreted as a (float) ratio between 0.0 and 1.0. The acquisition interface will remap this ratio to the actual confidence range provided by the device and use it to decide which pixels are valid and which not. Pixels with confidence lower than the specified threshold are considered invalid.
'coordinate_transform_mode' 'none', 'cartesian', 'reference' 'reference' string Controls which coordinate transformation operations should the acquisition interface attempt to perform when building the 3D object model from acquired 3D coordinates. Note that the decision which transformation should be performed and which parameters should be used fully depends on the 3D configuration information provided by the device together with the acquired data. If this information is insufficient or coordinates are inaccurate, the result of the transformation(s) might be meaningless or unpredictable. Refer to Using 3D Devices for more details.
Possible values are:
  • none: The acquisition interface will not perform any coordinate transformation. The 3D object model will contain the "raw" coordinates, possibly only scaled depending on the hints from the device.
  • cartesian: If the coordinate system used by the device is other than Cartesian, the acquisition interface will convert the coordinates to Cartesian system (native for HALCON's 3D object model). It will not attempt to further transform the coordinates from the device's internal ("anchor") coordinate system to the reference system.
  • reference: Default mode. Will transform to Cartesian coordinates if needed and then attempt to transform to the "reference" coordinate system if the device supports it and provides corresponding instructions. The purpose of the reference system is to allow merging and aligning data from multiple devices. The reference system is in contrast with the native ("anchor") coordinate system which is device specific and corresponds to its actual measurement system and actual configuration.
    The position and orientation of the reference system should be indicated by a reference point marker on the device's housing.
    This always directly implies the transformation to Cartesian coordinates because the reference coordinate system is always Cartesian.
'create_objectmodel3d' 'disable', 'enable' 'disable' string Controls whether the acquisition interface should attempt to generate HALCON 3D object model(s) when encountering 3D coordinates within the acquired data.
To obtain a 3D object model, the application has to use the grab_data/grab_data_async operators which can return the handles to the generated models through the control data outputs. The grab_image/grab_image_async operators cannot return the 3D object models.
IMPORTANT: the parameter is disabled by default. When enabling, the application is responsible for releasing the generated object models and associated resources using the clear_object_model_3d operator once it does not need given model(s) any more. It should do so by tracking which of the control data outputs of every single grab_data/grab_data_async calls carry 3D object model handle(s). This can be done using the 'data_contents' parameter.
When generating the 3D object model, the acquisition interface processes the 3D coordinates found in the acquired data and builds the point cloud with help of the information about the actual 3D configuration reported by the device. Refer to Using 3D Devices for more details.
'delay_after_stop' <milliseconds> 0 integer The time to wait (in milliseconds) between stopping the acquisition on the device (AcquisitionStop command) and GigE Vision Producer.
'do_abort_grab' --- Aborts the current image acquisition and unlocks parameters, that might be locked when acquisition is active. See acquisition overview.
'do_load_settings' <input_file> string Restores the previously stored settings of the opened device. See detailed description in section Parameters - Persisting Device Status.
'do_write_configuration' <output_directory> string Writes a configuration (ini) file specified with full path through the string parameter value. Writes also GenICam description files of the remote device and each GigE Vision Producer module associated with currently opened device. The GenICam description files are written to the same directory as the ini file itself. The written ini file contains in particular paths to the written GenICam description files and can be reused through the 'CameraType' parameter of open_framegrabber operator, see detailed description in section about device opening. Instead of specifying the path of the output ini file, 'default' or an empty string can be used. In this case the files will be written to the %TEMP% directory and the filename of the configuration file will be halcon_gentl_config.ini. Note that this default option will apply also when using the Image Acquisition Assistant.
'do_write_settings' <output_directory> string Writes the current settings of the opened device to be able to restore the settings later. See detailed description in section Parameters - Persisting Device Status.
'event_notification_helper' 'disable', 'enable' 'disable' string Controls if the acquisition interface should attempt to automatically (un)set 'EventNotification' during set_framegrabber_callback if the callback is being (un)registered on an SFNC-compliant event. Note that this will only work if the callback is being registered on the actual event feature (e.g. 'EventExposureEnd'), not on one of the event data features (e.g. 'EventExposureEndTimestamp'). For further information on events, see Event Data.
'grab_timeout' <milliseconds> 5000 integer Desired timeout (milliseconds) for aborting a pending grab. If -1 is specified, the timeout is set to INFINITE.
'image_height' --- 0 Unsupported (read-only parameter).
'image_width' --- 0 Unsupported (read-only parameter).
'register_<addr>_<len>' integer Direct register access for reading and writing integers. Caution: This is a dangerous function intended for debugging and special cases. Usually only features in the XML should be used.
'split_param_values_into_dwords' 'disable', 'enable' 'disable' string Enables a special mode allowing the treatment of integer parameters as tuple of two 32-bit integers. For compatibility with the single-parameter mode, the first tuple element carries always the low 32-bit part of the value, second element carries the high 32-bit part. It is user's responsibility to combine the two parts correctly. This mode is intended especially to help to overcome the problem of 32-bit HALCON featuring only 32-bit integer parameters but having to face up to 64-bit wide GenICam features. In this mode, the get_framegrabber_param returns always a tuple of two integers, set_framegrabber_param accepts both a single parameter or a tuple. Note that this mode affects only integer parameters and only the GenICam based ones, not the internal parameters of HALCON GigEVision2 image acquisition interface - with two exceptions, the 'buffer_timestamp' and 'buffer_frameid' internal parameters.
'start_async_after_grab_async' 'disable', 'enable' 'enable' string By default a new asynchronous grab command is automatically given to the acquisition device at the end of grab_image_async. If the parameter 'start_async_after_grab_async' is set to 'disable', this new grab command is omitted.
'start_column' --- 0 Unsupported (read-only parameter). Configure the image size through device parameters.
'start_row' --- 0 Unsupported (read-only parameter). Configure the image size through device parameters.
'volatile' 'disable', 'enable' 'disable' string When enabled, switches on the volatile mode in which the image buffers are used directly to create HALCON images. This is the fastest mode avoiding the copy of raw images in memory. However, be aware that older images might be overwritten by the acquisition engine with new data at any time. When changing the device configuration in a way that acquisition buffers must be reallocated, the older HALCON images would even become invalid (pointing to no more existing memory). See also details about acquisition buffer handling.
Please note that the volatile mode can be switched on at any time, regardless of the current configuration. However, at runtime only the acquired images compatible with the volatile mode will be delivered to the application (the others will be discarded). Compatible means in particular that the PixelFormat of the acquired image matches the color_space and bits_per_channel settings configured for HALCON image output format.

Parameters for get_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), and 'rw' (read/write).
  • '_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].
  • '_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.

Parameter Values Default Type Kind Description
'[Device]DeviceEventsThreadPriority' <thread_priority> integer pre-defined OS-specific thread priority value to be used for the internal event processing thread. The actual values are directly the priority identifiers of the operating system, e.g. THREAD_PRIORITY_HIGHEST under Windows or a real-time priority value under Linux.
The actual priority is applied only after executing the '[Device]DeviceEventsThreadApplyPriority' command parameter, possibly together with the '[Device]DeviceEventsThreadSchedulingPolicy' value if applicable on given system.
It is the responsibility of the application to ensure that the calling process has sufficient privileges to apply the priority change and that the value written to the parameter is a valid priority identifier. After applying '[Device]DeviceEventsThreadApplyPriority', the application can read back the priority value to verify if it was properly applied.
Note that when opening the device, the GigE Vision Producer attempts itself to elevate the thread priority to a suitable value.
The feature is not available for devices not supporting device events or if the event handling was disabled using the 'device_event_handling=0' generic parameter.
BEWARE: Setting this parameter can lead to an unusable or poorly performing system, use with care.
'[Device]DeviceEventsThreadSchedulingPolicy' <scheduling_policy> integer pre-defined OS-specific scheduling policy value to be used for the internal event processing thread. The actual values are directly the priority identifiers of the operating system, e.g. SCHED_FIFO under Linux. Note that this feature is not available under Windows.
The actual scheduling policy is applied only after executing the '[Device]DeviceEventsThreadApplyPriority' command parameter, together with the '[Device]DeviceEventsThreadPriority' value.
It is the responsibility of the application to ensure that the calling process has sufficient privileges to apply the scheduling policy and that the value written to the parameter is a valid scheduling policy identifier. After applying '[Device]DeviceEventsThreadApplyPriority', the application can read back the scheduling policy value to verify if it was properly applied.
The feature is not available for devices not supporting device events or if the event handling was disabled using the 'device_event_handling=0' generic parameter.
BEWARE: Setting this parameter can lead to an unusable or poorly performing system, use with care.
'[Device]DeviceLinkHeartbeatMode' 'Off', 'On' 'Off' string pre-defined Allows to disable the heartbeat control on the device. The parameter will be only present if supported by given device. It is usually only good idea to disable the heartbeat if debugging the application (to prevent loosing the device connection when hitting a breakpoint). When disabling and not re-enabling the device and if the application fails to properly close the connection (such as during crash or hard debugger stop), the device will never assume the connection has expired and will have to be rebooted. fails to maintain the heartbeat protocol. In most cases leaving the default value intact is the best solution. A possible exception can be to significantly prolong the timeout while debugging, if given device does not support heartbeat disabling.
'[Device]DeviceLinkHeartbeatTimeout' <timeout> integer pre-defined Heartbeat timeout (in usec) after which the device disconnects if the application fails to maintain the heartbeat protocol. In most cases leaving the default value intact is the best solution. A possible exception can be to significantly prolong the timeout while debugging, if given device does not support heartbeat disabling.
'[Device]DeviceMessageChannelKeepAliveTimeout' 30000 float pre-defined Interval (in milliseconds) between keep-alive packets sent while listening for device events to the device's message channel port to simulate the events traffic is outbound rather than inbound, thus helping to receive the events reliably in presence of a firewall. The actual required interval might be specific to the actual firewall in use. Zero means no keep-alive packets are sent at all.
'[Device]EventDeviceLost' integer pre-defined Delivers notification about "device lost" event (losing connection with the device). To receive such notification, it is necessary to register 'DeviceLost' event delivery using '[Device]EventSelector' and '[Device]EventNotification' and register notification callback for this feature ('[Device]EventDeviceLost') as described in Feature Change Notifications (Callbacks). When receiving the notification, it is recommended to try to read the value of [Device]EventDeviceLost. If readable, the connection to the device was actually lost (note that the actually read value of this parameter is insignificant). After losing connection to the device, the device handle is no more usable and should be closed.
'[Device]EventNotification' 'Off', 'On' 'Off' string pre-defined Enables/disables delivery of GigE Vision Producer device module event selected in '[Device]EventSelector'.
'[Device]EventSelector' 'DeviceLost' string pre-defined Selects a GigE Vision Producer device module event to be enabled/disabled using '[Device]EventNotification'.
'[Device]GevDeviceGateway' <gateway> integer pre-defined Default gateway address of the device, in integer format.
'[Device]GevDeviceIPAddress' <ip_address> integer pre-defined IP address of the device, in integer format.
'[Device]GevDeviceMACAddress' <mac_address> integer pre-defined MAC address of the device, in integer format.
'[Device]GevDeviceSubnetMask' <subnet_mask> integer pre-defined Subnet mask of the device, in integer format.
'[Device]LinkCommandRetryCount' 3 integer pre-defined Specifies number of times the HALCON GigEVision2 should attempt to retry sending a given control command to the device when not receiving corresponding command acknowledge from the device (assuming the command got lost). Works together with '[Device]LinkCommandTimeout' and usually should stay intact.
'[Device]LinkCommandTimeout' 200000 integer pre-defined Specifies the timeout (in usec) the HALCON GigEVision2 should wait for device acknowledge for individual control commands before assuming the command got lost and trying to send it again. Works together with '[Device]LinkCommandRetryCount' and usually should stay intact.
'[Interface]GevDeviceForceGateway' <gateway> integer pre-defined Default gateway to be forced (together with IP address) into the device selected in '[Interface]DeviceSelector'. This parameter is only used to prepare the desired IP configuration values for the device (together with '[Interface]GevDeviceForceIPAddress' and '[Interface]GevDeviceForceSubnetMask', the settings are actually applied together using '[Interface]GevDeviceForceIP'.
Use with care, using configuration not matching the interface the device is conected to may render the device unreachable. Intended to fix exactly these kinds of situations. Applicable only on devices that are not currently open.
Note that the 'force_ip' generic parameter in open_framegrabber can serve similar purpose.
'[Interface]GevDeviceForceIPAddress' <ip_address> integer pre-defined IP address to be forced (together with subnet mask and gateway) into the device selected in '[Interface]DeviceSelector'. This parameter is only used to prepare the desired IP configuration values for the device (together with '[Interface]GevDeviceForceSubnetMask' and '[Interface]GevDeviceForceGateway', the settings are actually applied together using '[Interface]GevDeviceForceIP'.
Use with care, using configuration not matching the interface the device is conected to may render the device unreachable. Intended to fix exactly these kinds of situations. Applicable only on devices that are not currently open.
Use '[Interface]GevDeviceProposeIP' to fill this parameter automatically with suitable value.
Note that the 'force_ip' generic parameter in open_framegrabber can serve similar purpose.
'[Interface]GevDeviceForceSubnetMask' <subnet_mask> integer pre-defined Subnet mask to be forced (together with IP address) into the device selected in '[Interface]DeviceSelector'. This parameter is only used to prepare the desired IP configuration values for the device (together with '[Interface]GevDeviceForceIPAddress' and '[Interface]GevDeviceForceGateway', the settings are actually applied together using '[Interface]GevDeviceForceIP'.
Use with care, using configuration not matching the interface the device is conected to may render the device unreachable. Intended to fix exactly these kinds of situations. Applicable only on devices that are not currently open.
Note that the 'force_ip' generic parameter in open_framegrabber can serve similar purpose.
'[Interface]GevInterfaceMACAddress' <mac_address> integer pre-defined MAC address of the host's network interface the device is connected to, in integer format.
'[Interface]GevInterfaceMTU' <timeout> integer pre-defined Maximum tramsmission unit (MTU) currently accepted by the host's network interface the device is connected to.
'[Interface]GevInterfaceSubnetIPAddress' <ip_address> integer pre-defined IP address of the host's network interface the device is connected to, in integer format.
'[Interface]GevInterfaceSubnetMask' <subnet_mask> integer pre-defined Subnet mask of the host's network interface the device is connected to, in integer format.
'[Stream]DeviceStreamChannelKeepAliveTimeout' 30000 float pre-defined Interval (in milliseconds) between keep-alive packets sent during active streaming to the device's stream channel port to simulate the stream traffic is outbound rather than inbound, thus helping to stream reliably in presence of a firewall. The actual required interval might be specific to the actual firewall in use. Zero means no keep-alive packets are sent at all.
'[Stream]DeviceStreamChannelPacketSize' <packet_size> integer pre-defined Packet size configured for the device stream channel (similar feature might appear also in feature set of the remote device itself). Configures both the remote device and GigE Vision Producer.
'[Stream]DeviceStreamChannelPacketSizeInc' --- integer pre-defined Controls desired increment of the packet size feature to be used for the stream channel. Affects both the direct control of the packet size ('[Stream]DeviceStreamChannelPacketSize') as well as the negotiation algorithm ('[Stream]DeviceStreamChannelNegotiatePacketSize').
The limit should be usually set in sync with actual limits imposed by the device itself, unless there are reasons to apply stricter limits. When the device limits are unknown, the initial value is set to 4.
'[Stream]DeviceStreamChannelPacketSizeMax' --- integer pre-defined Controls desired maximum of the packet size feature to be used for the stream channel. Affects both the direct control of the packet size ('[Stream]DeviceStreamChannelPacketSize') as well as the negotiation algorithm ('[Stream]DeviceStreamChannelNegotiatePacketSize').
The limit should be usually set in sync with actual limits imposed by the device itself, unless there are reasons to apply stricter limits. When the device limits are unknown, the initial value is set to the MTU size accepted by the network interface the device is connected to.
'[Stream]DeviceStreamChannelPacketSizeMin' --- integer pre-defined Controls desired minimum of the packet size feature to be used for the stream channel. Affects both the direct control of the packet size ('[Stream]DeviceStreamChannelPacketSize') as well as the negotiation algorithm ('[Stream]DeviceStreamChannelNegotiatePacketSize').
The limit should be usually set in sync with actual limits imposed by the device itself, unless there are reasons to apply stricter limits. When the device limits are unknown, the initial value is set to 576.
'[Stream]EventNotification' 'Off', 'On' 'Off' string pre-defined Enables/disables delivery of GigE Vision Producer data stream module event selected in '[Stream]EventSelector'.
'[Stream]EventSelector' 'TransferEnd' string pre-defined Selects a GigE Vision Producer data stream module event to be enabled/disabled using '[Stream]EventNotification'.
'[Stream]EventTransferEnd' integer pre-defined Delivers notification about "transfer end" event (finishing transfer of a buffer within the streaming engine). To receive such notification, it is necessary to register 'TransferEnd' event delivery using '[Stream]EventSelector' and '[Stream]EventNotification' and register notification callback for this feature ('[Stream]EventTransferEnd') as described in Feature Change Notifications (Callbacks). The actual value read from this parameter is insignificant. Additional information about the event can be obtained using '[Stream]EventTransferEndFrameID' and '[Stream]EventTransferEndBufferUndeliverable'.
IMPORTANT: there is no 1:1 mapping between generated transfer end events and actually delivered buffers. Corrupted/undeliverable buffers will be discarded by the streaming engine. Even valid buffers can still be dropped within the output queue based on the queue state and '[Stream]StreamBufferHandlingMode' parameter.

Note: this notification is currently not generated if filter driver is active.
'[Stream]EventTransferEndBufferUndeliverable' 0, 1 integer pre-defined Flag indicating whether the last buffer for which the transfer end event was signalled through '[Stream]EventTransferEnd' was deliverable (valid). Corrupted/undeliverable buffers will be discarded by the streaming engine. Even valid buffers can still be dropped within the output queue based on the queue state and '[Stream]StreamBufferHandlingMode' parameter.
'[Stream]EventTransferEndFrameID' integer pre-defined Frame ID of the last buffer for which the transfer end event was signalled through '[Stream]EventTransferEnd'.
'[Stream]GevStreamActiveEngine' 'SocketDriver', 'FilterDriver' string pre-defined Informs which stream engine (socket or filter driver is currently active). Available only on Windows systems (on other systems always socket driver is used).
'[Stream]GevStreamDeliveredPacketCount' 0 integer pre-defined All packets successfully received in the delivered blocks. The packets from undelivered (skipped or discarded) blocks are not counted.
Note: this information is currently not provided if filter driver is active.
'[Stream]GevStreamDeliverIncompleteBlocks' 0, 1 1 integer pre-defined Flag indicating if incomplete buffers (with one or more missing packets) should be delivered or discarded. Note that if the leader or trailer of a block is missing it will be discarded anyway.
'[Stream]GevStreamDiscardedBlockCount' 0 integer pre-defined Number of blocks that were discarded for any reason including corruption, too many missing packets (according to the selected input parameters) or missing leader and/or trailer.
'[Stream]GevStreamDuplicatePacketCount' 0 integer pre-defined Packets that were received twice (typically because the resend request arrived too early).
Note: this information is currently not provided if filter driver is active.
'[Stream]GevStreamEngineUnderrunCount' 0 integer pre-defined Number of blocks that were discarded because no buffers were scheduled into the acq engine when given block arrived.
'[Stream]GevStreamFullBlockTerminatesPrev' 0, 1 0 integer pre-defined Flag indicating whether receiving a complete buffer immediately terminates any previous ones in the acquisition queue, no matter if resend is still pending for them, thus avoiding blocking the full one.
'[Stream]GevStreamIncompleteBlockCount' 0 integer pre-defined Number of blocks that were delivered incomplete (with one or more missing packets in them).
'[Stream]GevStreamLostPacketCount' 0 integer pre-defined All packets missing (even after resends) in the delivered blocks. The packets from undelivered (skipped or discarded) blocks are not counted.
Note: this information is currently not provided if filter driver is active.
'[Stream]GevStreamMaxBlockDuration' 0 float pre-defined Maximal duration ('on the wire') of a block in microseconds. When it expires, the engine will assume the block trailer (block trailing control packet) should be already received - and if packet resend is supported, it will ask to resend it.
Zero means no limit, which is suitable for example for line scan devices with sparse line triggers.
Note: for filter driver this is rounded to milliseconds. If it expires the oldest block is checked if it can be delivered. If this is not the case resends for the oldest block are requested. This block is also marked for delivery if more packets than the trailing ones are missing. When the timer expires a second time marked blocks are either discarded or delivered.
'[Stream]GevStreamMaxPacketGaps' 30 integer pre-defined Socket driver: Maximal number of packet gaps in a block. Affects the amount of resources allocated for the resend mechanism.
Filter driver: Percentage of allowed missing packets for an incomplete block. Consequently this is also the maximum number of resend requests sent out per block.
When exceeded, the engine will give up trying to finish this block and will discard it.
'[Stream]GevStreamOversizedBlockCount' 0 integer pre-defined Number of blocks that were detected as oversized, ie. one or more packets did not fit into the allocated buffer. Counted no matter if the buffer was actually delivered or not.
Note: this information is currently not provided if filter driver is active.
'[Stream]GevStreamResendCommandCount' 0 integer pre-defined Number of resend requests (no matter if single or multi-packet ones). Each resend is counted, even if sent multiple times for the same packet. Even those belonging to buffers which never get delivered are counted.
Note: this information is currently not provided if filter driver is active.
'[Stream]GevStreamResendPacketCount' 0 integer pre-defined Number of resend-requested packets. Each resend is counted, even if sent multiple times for the same packet. Even those belonging to buffers which never get delivered are counted. When asking for resend of buffer tail (with unknown number of packets in it) only a single packet is counted.
'[Stream]GevStreamSeenPacketCount' 0 integer pre-defined All packets (even invalid or duplicates) seen by the stream.
'[Stream]GevStreamSkippedBlockCount' 0 integer pre-defined Number of blocks that were skipped somewhere (we have never seen any valid packet belonging to them).
Note: this information is currently not provided if filter driver is active.
'[Stream]GevStreamUnavailablePacketCount' 0 integer pre-defined All packets explicitly announced as unavailable (after resend) by the device (contrary to those that were simply silently not resent). This typically means the resend request came too late.
'[Stream]StreamBufferHandlingMode' 'OldestFirst', 'OldestFirstOverwrite', 'NewestOnly' 'OldestFirst' string pre-defined Selects the mode the streaming engine uses to handle newly acquired data, in particular when the camera runs faster than the application processing. The parameter is writeable only if no acquisition is active. Supported values are:
  • 'OldestFirst': The acquired buffers are always delivered in FIFO manner (oldest first). If the acquisition engine receives a new buffer from the camera but has no available free buffer to fill it in, the new data is discarded.
  • 'OldestFirstOverwrite': The acquired buffers are always delivered in FIFO manner (oldest first). If the acquisition engine receives a new buffer from the camera but has no available free buffer to fill it in, it checks, whether there are older buffers waiting for delivery, not yet picked up by the consumer. If yes, it takes the oldest of them, overwrites it with the new data and appends it to the end of the output queue. If the output queue is empty (no buffer available for overwriting), the new data is discarded.
  • 'NewestOnly': The output queue of buffers waiting for delivery never contains more than a single (newest) buffer. If the acquisition engine receives a new buffer and there is already an older buffer waiting for delivery in the output queue, the new buffer is put to the output queue instead and the old one is reused for next acquisition. If there are no available free buffers and the output queue is also empty, new data is discarded.
'[Stream]StreamThreadPriority' <thread_priority> integer pre-defined OS-specific thread priority value to be used for the internal stream processing thread. The actual values are directly the priority identifiers of the operating system, e.g. THREAD_PRIORITY_HIGHEST under Windows or a real-time priority value under Linux.
The actual priority is applied only after executing the '[Stream]StreamThreadApplyPriority' command parameter, possibly together with the '[Stream]StreamThreadSchedulingPolicy' value if applicable on given system.
It is the responsibility of the application to ensure that the calling process has sufficient privileges to apply the priority change and that the value written to the parameter is a valid priority identifier. After applying '[Stream]StreamThreadApplyPriority', the application can read back the priority value to verify if it was properly applied.
Note that when opening the device, the GigE Vision Producer attempts itself to elevate the thread priority to a suitable value.
BEWARE: Setting this parameter can lead to an unusable or poorly performing system, use with care.
'[Stream]StreamThreadSchedulingPolicy' <scheduling_policy> integer pre-defined OS-specific scheduling policy value to be used for the internal stream processing thread. The actual values are directly the priority identifiers of the operating system, e.g. SCHED_FIFO under Linux. Note that this feature is not available under Windows.
The actual scheduling policy is applied only after executing the '[Stream]StreamThreadApplyPriority' command parameter, together with the '[Stream]StreamThreadPriority' value.
It is the responsibility of the application to ensure that the calling process has sufficient privileges to apply the scheduling policy and that the value written to the parameter is a valid scheduling policy identifier. After applying '[Stream]StreamThreadApplyPriority', the application can read back the scheduling policy value to verify if it was properly applied.
BEWARE: Setting this parameter can lead to an unusable or poorly performing system, use with care.
'[System]GevTLSubsystemInfo' '<subsystem_info>' string pre-defined Information about the subsystems in GigE Vision Producer implementation. Intended primarily for troubleshooting and support.
'add_objectmodel3d_overlay_attrib' 'disable', 'enable' 'disable' string pre-defined Controls if the acquisition interface should attempt to append the intensity/color overlay to the generated 3D object models. Applicable only if a 3D object model is being output from given grab operator. When switched on, the acquisition interface will try to find suitable information within the acquired data (if it is provided by the device). If so, it appends the overlay information for each point in the output model in form of an extended attribute. Note that in some advanced use cases there might be multiple potential overlay images output by the device, the acquisition interface therefore attempts to find the most suitable one.
First, it tries to identify data marked as "intensity" image in the acquired data. If found and provided as monochrome 2D image, it is appended as '&intensity_gray' extended attribute. If found and provided as RGB image, it is appended as three extended attributes, '&intensity_red', '&intensity_green' and '&intensity_blue'.
If "intensity" data cannot be identified, it tries to find data marked as "reflectance". If found and provided as monochrome 2D image, it is appended as '&reflectance_gray' extended attribute. If found and provided as RGB image, it is appended as three extended attributes, '&reflectance_red', '&reflectance_green' and '&reflectance_blue'.
Finally, if neither "intensity" nor "reflectance" data can be identified (either not present or not correctly marked by the device, it picks the first 2D image within the acquired data than can be mapped to the 3D coordinates. If found and provided as monochrome 2D image, it is appended as '&overlay_gray' extended attribute. If found and provided as RGB image, it is appended as three extended attributes, '&overlay_red', '&overlay_green' and '&overlay_blue'.
If no suitable 2D image is found, no overlay is appended. The actually appended extended attributes can be queried for example using the get_object_model_3d_params operator with the 'extended_attribute_names' parameter. The overlay can be also used for visualization purposes.
'available_callback_types' ['<callback_types>'] string dynamic Returns a list containing all parameters, for which a callback can be registered. This includes all parameters published by the device and GigE Vision Producer via the GenICam interface, including those temporarily unavailable, because availability change might be coupled with the callback.
'available_param_names' ['<names>'] string dynamic Returns a list containing all available parameters, i.e. those used by the HALCON GigEVision2 image acquisition interface and those published by the device and GigE Vision Producer via the GenICam interface (see parameter naming conventions). Note that availability of some parameters might depend on acquisition status, values of other parameters or other conditions, so the list dynamically changes during runtime.
'bits_per_channel' -1, 8, 10, 12, 14, 16 -1 integer pre-defined Number of bits per channel of the resulting HALCON image. In case of -1 the bit depth of each respective acquired buffer is used. By specifying a value greater than 8 the grabbed images are delivered as uint2 images.
'buffer_frameid' <frame_id> integer dynamic Frame ID attached to the last grabbed (image) buffer by the device (or GigE Vision Producer). Typically sequentially incremented number of the frame. Skipped ID's in the sequence could indicate that one or more frames was dropped in the device or GigE Vision Producer, for example due to acquisition engine overflow reasons. Note that on 32-bit systems only the lower 32-bit part of up to 64-bit timestamp is delivered (unless 'split_param_values_into_dwords' parameter is enabled). See acquisition buffer handling.
'buffer_is_incomplete' 0, 1 integer dynamic Shows if the last grabbed image is incomplete (e.g. due to lost packets). See acquisition buffer handling.
'buffer_reallocation_mode' 'only_increase_size', 'follow_payloadsize' 'only_increase_size' string pre-defined Defines the strategy to follow when reallocating the buffers for a new acquisition. In case of 'only_increase_size', the buffers will be only reallocated when the payload size increases. In case of 'follow_payloadsize', the buffers will be reallocated every time the payload size changes.
'buffer_timestamp' <timestamp> integer dynamic Timestamp attached to the last grabbed (image) buffer by the device (or GigE Vision Producer). The unit and actual meaning of the timestamp (when it is generated) is device specific. Note that on 32-bit systems only the lower 32-bit part of up to 64-bit timestamp is delivered (unless 'split_param_values_into_dwords' parameter is enabled). See acquisition buffer handling.
'camera_type' 'default', <ini/xml filename> 'default' string pre-defined Returns the path to the configuration file used for the CameraType parameter in open_framegrabber.
'clear_buffer' 'disable', 'enable' 'disable' string pre-defined If enabled, each buffer content is cleared before re-queueing (all bytes set to 0xF0 regardless the expected pixel format), so you can see which parts of an image are missing, in case e.g. the transfer of some image packets failed. This parameter adds of course an runtime overhead to write the 0xF0 data every time a buffer is queued. It is mainly useful for debugging in combination with transport layers which do not guarantee the transfer of complete images. Please note, that this parameter does not modify the buffer queue, only the content of a buffer will be set to a defined state.
'color_space' 'default', 'gray', 'raw', 'rgb', 'yuv' 'default' string pre-defined Returns the current color space.
'confidence_mode' 'off', 'object_model_3d' 'off' string pre-defined Controls if (and how) the information about pixel confidence level is used by the acquisition interface. Applicable only for devices and use cases where the confidence information is delivered (per-pixel) together with the actual pixel data.
The threshold to distinguish between valid and invalid pixels is controlled using the 'confidence_threshold' parameter.
Note that in some use cases there might be other criteria how to mark given pixel invalid, for example if the device uses "invalid pixel value" for a 3D coordinate. These cases are not covered by the 'confidence_mode' parameter and such invalid pixels are always rejected from the 3D object model. Possible values are:
  • off: Default value. The pixel confidence information is not applied to any of the grab operator outputs, even if supplied by the device.
  • object_model_3d: If the pixel confidence level information is available, it is applied to the eventually generated 3D object models (but not to any other outputs, in particular not to the image outputs). This means that pixels ("points") with confidence lower than the configured threshold are not included in the generated 3D object model.
'confidence_threshold' [0.0, 1.0] 0.5 float pre-defined Threshold separating between valid and invalid pixels. Applicable only for devices and use cases where the confidence information is delivered (per-pixel) together with the actual pixel data. The decision how (to which outputs) the confidence threshold is applied is controlled using the 'confidence_mode' parameter.
The threshold is interpreted as a (float) ratio between 0.0 and 1.0. The acquisition interface will remap this ratio to the actual confidence range provided by the device and use it to decide which pixels are valid and which not. Pixels with confidence lower than the specified threshold are considered invalid.
'coordinate_transform_mode' 'none', 'cartesian', 'reference' 'reference' string pre-defined Controls which coordinate transformation operations should the acquisition interface attempt to perform when building the 3D object model from acquired 3D coordinates. Note that the decision which transformation should be performed and which parameters should be used fully depends on the 3D configuration information provided by the device together with the acquired data. If this information is insufficient or coordinates are inaccurate, the result of the transformation(s) might be meaningless or unpredictable. Refer to Using 3D Devices for more details.
Possible values are:
  • none: The acquisition interface will not perform any coordinate transformation. The 3D object model will contain the "raw" coordinates, possibly only scaled depending on the hints from the device.
  • cartesian: If the coordinate system used by the device is other than Cartesian, the acquisition interface will convert the coordinates to Cartesian system (native for HALCON's 3D object model). It will not attempt to further transform the coordinates from the device's internal ("anchor") coordinate system to the reference system.
  • reference: Default mode. Will transform to Cartesian coordinates if needed and then attempt to transform to the "reference" coordinate system if the device supports it and provides corresponding instructions. The purpose of the reference system is to allow merging and aligning data from multiple devices. The reference system is in contrast with the native ("anchor") coordinate system which is device specific and corresponds to its actual measurement system and actual configuration.
    The position and orientation of the reference system should be indicated by a reference point marker on the device's housing.
    This always directly implies the transformation to Cartesian coordinates because the reference coordinate system is always Cartesian.
'create_objectmodel3d' 'disable', 'enable' 'disable' string pre-defined Controls whether the acquisition interface should attempt to generate HALCON 3D object model(s) when encountering 3D coordinates within the acquired data.
To obtain a 3D object model, the application has to use the grab_data/grab_data_async operators which can return the handles to the generated models through the control data outputs. The grab_image/grab_image_async operators cannot return the 3D object models.
IMPORTANT: the parameter is disabled by default. When enabling, the application is responsible for releasing the generated object models and associated resources using the clear_object_model_3d operator once it does not need given model(s) any more. It should do so by tracking which of the control data outputs of every single grab_data/grab_data_async calls carry 3D object model handle(s). This can be done using the 'data_contents' parameter.
When generating the 3D object model, the acquisition interface processes the 3D coordinates found in the acquired data and builds the point cloud with help of the information about the actual 3D configuration reported by the device. Refer to Using 3D Devices for more details.
'data_contents' 'unknown', 'object_model_3d', 'text_report' 0 string pre-defined Tuple describing logical type of the control data outputs returned by the last grab operator. Not applicable if last successful grab was performed through grab_image/grab_image_async. In case of grab_data/grab_data_async it returns tuple of the size corresponding to the number of control data values returned through those operators. Possible values are:
  • unknown: The logical type of the data could not be identified.
  • object_model_3d: Integer representing a handle of the 3D object model generated from the acquired data. IMPORTANT: the model has to be released (clear_object_model_3d) when no more used, otherwise the associated resources will be leaking. The generation of the 3D object models is controlled using 'create_objectmodel3d' parameter (disabled by default). Beware that in special use cases more than one object models can be generated.
  • text_report: Might be used for internal purposes and during support cases. Should be ignored by all applications.
'data_purpose_id' --- 0xFFFFFFFFFFFFFFFF integer pre-defined Tuple of integer values allowing to track data purpose IDs associated to individual control data outputs returned by the last grab operator. Intended for advanced use cases when the data should be matched with the device configuration. The use of the parameter is application specific and requires knowledge of the GenICam SFNC data model and specific device. Not applicable if last successful grab was performed through grab_image/grab_image_async. In case of grab_data/grab_data_async it returns tuple of the size corresponding to the number of control data values returned through those operators. If the ID could not be identified (eg. because the underlying communication protocol does not provide such information), invalid value will be returned (max value of given integer range).
'data_region_id' --- 0xFFFFFFFFFFFFFFFF integer pre-defined Tuple of integer values allowing to track region IDs associated to individual control data outputs returned by the last grab operator. Intended for advanced use cases when the data should be matched with the device configuration. The use of the parameter is application specific and requires knowledge of the GenICam SFNC data model and specific device. Not applicable if last successful grab was performed through grab_image/grab_image_async. In case of grab_data/grab_data_async it returns tuple of the size corresponding to the number of control data values returned through those operators. If the ID could not be identified (eg. because the underlying communication protocol does not provide such information), invalid value will be returned (max value of given integer range).
'data_source_id' --- 0xFFFFFFFFFFFFFFFF integer pre-defined Tuple of integer values allowing to track source IDs associated to individual control data outputs returned by the last grab operator. Intended for advanced use cases when the data should be matched with the device configuration. The use of the parameter is application specific and requires knowledge of the GenICam SFNC data model and specific device. Not applicable if last successful grab was performed through grab_image/grab_image_async. In case of grab_data/grab_data_async it returns tuple of the size corresponding to the number of control data values returned through those operators. If the ID could not be identified (eg. because the underlying communication protocol does not provide such information), invalid value will be returned (max value of given integer range).
'delay_after_stop' <milliseconds> 0 integer pre-defined The time to wait (in milliseconds) between stopping the acquisition on the device (AcquisitionStop command) and GigE Vision Producer.
'device' ' | device:<device id> | unique_name:<unique name> | user_name:<user-defined name> | interface:<interface id> | producer:Esen', '<device id>' string dynamic Returns the Device parameter string used when opening the device (open_framegrabber).
'device_event_handling' 0, 1 1 integer pre-defined Value of the device_event_handling generic parameter specified in open_framegrabber. The device_event_handling is by default switched on for devices with event delivery (message channel) support and off for devices without the event capability. The generic parameter device_event_handling explicitly allows switching the event handling functionality off even for devices with event support.
'direct_connection' 'disable', 'enable' 'disable' string pre-defined Value of the direct_connection generic parameter specified in open_framegrabber.
'event_notification_helper' 'disable', 'enable' 'disable' string pre-defined Controls if the acquisition interface should attempt to automatically (un)set 'EventNotification' during set_framegrabber_callback if the callback is being (un)registered on an SFNC-compliant event. Note that this will only work if the callback is being registered on the actual event feature (e.g. 'EventExposureEnd'), not on one of the event data features (e.g. 'EventExposureEndTimestamp'). For further information on events, see Event Data.
'external_trigger' <default> 'false' string pre-defined The value is not used, so a default value is returned.
'field' '<default>' 'progressive' string pre-defined The value is not used, so a default value is returned.
'generic' '', ['num_buffers=<num>', 'direct_connection=<mode>', 'streaming_mode=0', 'device_event_handling=0', 'workarounds=<list>'], -1 -1 mixed pre-defined Values of the Generic parameter.
'grab_timeout' <milliseconds> 5000 integer pre-defined Current grab timeout in milliseconds.
'horizontal_resolution' 0, 1, resolution 1 integer pre-defined Current value of horizontal resolution.
'image_available' 0, 1 integer dynamic Shows if there is currently an image waiting for delivery by the GigE Vision Producer.
'image_contents' 'unknown', 'image', 'coord_a', 'coord_b', 'coord_c', 'coord_mixed', 'confidence' 0 string pre-defined Tuple describing logical type of the image data returned by the last grab operator. If the last successful grab was performed through grab_image/grab_image_async, the parameter returns always single value. In case of grab_data/grab_data_async it returns tuple of the size corresponding to the number of images returned through those operators. Possible values are:
  • unknown: The logical type of the image could not be identified, typically this means some kind of custom, possibly raw data.
  • image: A regular 2D image. The format of the generated HALCON image is affected by the parameters 'bits_per_channel' and 'color_space' if used.
  • coord_a: The output HALCON image contains data corresponding to the 3D "coordinate A" according to the GenICam 3D model. The interpretation of the coordinate depends on the coordinate system used by the device: X for Cartesian, theta for spherical and theta for cylindrical coordinates (refer to GenICam SFNC standard for further details). The data are provided without any conversion, ignoring the 'bits_per_channel' and 'color_space' parameters.
  • coord_b: The output HALCON image contains data corresponding to the 3D "coordinate B" according to the GenICam 3D model. The interpretation of the coordinate depends on the coordinate system used by the device: Y for Cartesian, phi for spherical and Y for cylindrical coordinates (refer to GenICam SFNC standard for further details). The data are provided without any conversion, ignoring the 'bits_per_channel' and 'color_space' parameters.
  • coord_c: The output HALCON image contains data corresponding to the 3D "coordinate C" according to the GenICam 3D model. The interpretation of the coordinate depends on the coordinate system used by the device: Z for Cartesian, rho for spherical and rho for cylindrical coordinates (refer to GenICam SFNC standard for further details). The data are provided without any conversion, ignoring the 'bits_per_channel' and 'color_space' parameters.
  • coord_mixed: Used when the data is recognized as 3D coordinates but the format is unknown. In this case the data are output in the HALCON image "as is" without any transformations, the application has to know how to treat the custom data format. The data are provided without any conversion, ignoring the 'bits_per_channel' and 'color_space' parameters.
  • confidence: The output HALCON image contains data corresponding to the pixel confidence, which expresses the level of validity of corresponding pixel. The interpretation depends on the actual underlying pixel format used by the device to represent confidence (refer to GenICam SFNC standard for further details). The data are provided without any conversion, ignoring the 'bits_per_channel' and 'color_space' parameters.
'image_height' <height> 0 integer pre-defined Height of the last acquired image. See acquisition buffer handling. If there is no valid last buffer available, the last queried value of the 'Height' parameter of the remote device is returned.
'image_pixel_format' --- 0 integer pre-defined Tuple of integer values representing the ID of the original pixel formats of the source data used to generate individual image outputs. This is typically the PFNC 32-bit ID of given pixel format - if unknown or if the data used to generate given image output is not naturally an image, zero will be reported. If the source data is a multi-component image (such as RGB or multi-component 3D coordinate format), the original multi-component pixel format is reported, no matter if all of the components were used to generate given image output (such as an RGB image) or if the image output reflects only one of the components (such as individual 3D coordinate planes, output as separate HALCON images). The original multi-component pixel format might be planar format or not. Note that the color space and bit depth of the actual HALCON image might significantly differ from the source format if the user requests color space conversion through the 'bits_per_channel' and 'color_space' parameters.
'image_purpose_id' --- 0xFFFFFFFFFFFFFFFF integer pre-defined Tuple of integer values allowing to track data purpose IDs associated to individual image outputs returned by the last grab operator. Intended for advanced use cases when the data should be matched with the device configuration. The use of the parameter is application specific and requires knowledge of the GenICam SFNC data model and specific device. If the last successful grab was performed through grab_image/grab_image_async, the parameter returns always single value. In case of grab_data/grab_data_async it returns tuple of the size corresponding to the number of images returned through those operators. If the ID could not be identified (eg. because the underlying communication protocol does not provide such information), invalid value will be returned (max value of given integer range).
'image_raw_buffer_padding_bytes' --- 0 integer pre-defined Tuple of integers reporting for raw buffers of type 'blob' (see 'image_raw_buffer_type') the size of unused padding bytes at the end of such grabbed HALCON image. Because artificial dimensions need to be chosen for the resulting HALCON image in this case, the size of such image might not exactly equal the size of the buffer data and thus the padding might be needed. Zero is reported for buffers of type 'image'. Applies only in case of the 'raw' color format. See raw output format chapter. If the last successful grab was performed through grab_image/grab_image_async, the parameter returns always single value. In case of grab_data/grab_data_async it returns tuple of the size corresponding to the number of images returned through those operators.
'image_raw_buffer_type' 'image', 'blob' 0 string pre-defined Tuple of strings showing whether the last grabbed HALCON image(s) is created from buffer containing real image data with known properties (in particular image size and pixel format) or if it is created from a blob of other data (non-image data or image data of unknown format). Note that in case of the blob data the dimensions of the HALCON image are meaningless. Applies mainly in case of the 'raw' color format. Possible values are 'image' and 'blob'. See raw output format chapter. If the last successful grab was performed through grab_image/grab_image_async, the parameter returns always single value. In case of grab_data/grab_data_async it returns tuple of the size corresponding to the number of images returned through those operators.
'image_region_id' --- 0xFFFFFFFFFFFFFFFF integer pre-defined Tuple of integer values allowing to track region IDs associated to individual image outputs returned by the last grab operator. Intended for advanced use cases when the data should be matched with the device configuration. The use of the parameter is application specific and requires knowledge of the GenICam SFNC data model and specific device. If the last successful grab was performed through grab_image/grab_image_async, the parameter returns always single value. In case of grab_data/grab_data_async it returns tuple of the size corresponding to the number of images returned through those operators. If the ID could not be identified (eg. because the underlying communication protocol does not provide such information), invalid value will be returned (max value of given integer range).
'image_source_id' --- 0xFFFFFFFFFFFFFFFF integer pre-defined Tuple of integer values allowing to track source IDs associated to individual image outputs returned by the last grab operator. Intended for advanced use cases when the data should be matched with the device configuration. The use of the parameter is application specific and requires knowledge of the GenICam SFNC data model and specific device. If the last successful grab was performed through grab_image/grab_image_async, the parameter returns always single value. In case of grab_data/grab_data_async it returns tuple of the size corresponding to the number of images returned through those operators. If the ID could not be identified (eg. because the underlying communication protocol does not provide such information), invalid value will be returned (max value of given integer range).
'image_width' <width> 0 integer pre-defined Width of the last acquired image. See acquisition buffer handling. If there is no valid last buffer available, the last queried value of the 'Width' parameter of the remote device is returned.
'line_in' <default> 0 integer pre-defined The value is not used, so a default value is returned.
'name' 'GigEVision2' string pre-defined Name of the HALCON interface.
'num_buffers' <number> 4 integer pre-defined Number of buffers used for the image acquisition.
'num_buffers_await_delivery' <number> integer dynamic Number of (image) buffers waiting for delivery by the GigE Vision Producer.
'num_buffers_underrun' <number> integer dynamic Number of lost buffers due to buffer queue underrun since opening the device. Queue underrun occurs when the GigE Vision Producer has a new image data available, but it has no free buffer to store them.
'port' <port> -1 integer pre-defined The value is not used, so a default value is returned.
'raw_buffer_padding_bytes' 0 integer pre-defined Deprecated, prefer 'image_raw_buffer_padding_byptes' which supports also grab_data. For raw buffers of type 'blob' (see 'raw_buffer_type') reports the size of unused padding bytes at the end of such grabbed HALCON image. Because artificial dimensions need to be chosen for the resulting HALCON image in this case, the size of such image might not exactly equal the size of the buffer data and thus the padding might be needed. Zero is reported for buffers of type 'image'. Applies only in case of the 'raw' color format. See raw output format chapter.
'raw_buffer_type' 'image', 'blob' 0 string pre-defined Deprecated, prefer 'image_raw_buffer_type' which supports also grab_data. Shows whether the last grabbed HALCON image is created from buffer containing real image data with known properties (in particular image size and pixel format) or if it is created from a blob of other data (non-image data or image data of unknown format). Note that in case of the blob data the dimensions of the HALCON image are meaningless. Applies mainly in case of the 'raw' color format. Possible values are 'image' and 'blob'. See raw output format chapter.
'register_<addr>_<len>' integer pre-defined Direct register access for reading and writing integers. Caution: This is a dangerous function intended for debugging and special cases. Usually only features in the XML should be used.
'revision' '<revision>' string pre-defined Revision number of the GigEVision2 interface.
'split_param_values_into_dwords' 'disable', 'enable' 'disable' string pre-defined Enables a special mode allowing the treatment of integer parameters as tuple of two 32-bit integers. For compatibility with the single-parameter mode, the first tuple element carries always the low 32-bit part of the value, second element carries the high 32-bit part. It is user's responsibility to combine the two parts correctly. This mode is intended especially to help to overcome the problem of 32-bit HALCON featuring only 32-bit integer parameters but having to face up to 64-bit wide GenICam features. In this mode, the get_framegrabber_param returns always a tuple of two integers, set_framegrabber_param accepts both a single parameter or a tuple. Note that this mode affects only integer parameters and only the GenICam based ones, not the internal parameters of HALCON GigEVision2 image acquisition interface - with two exceptions, the 'buffer_timestamp' and 'buffer_frameid' internal parameters.
'start_async_after_grab_async' 'disable', 'enable' 'enable' string pre-defined Status of 'start_async_after_grab_async'.
'start_column' <column> 0 integer pre-defined Unsupported, returns always 0.
'start_row' <row> 0 integer pre-defined Unsupported, returns always 0.
'streaming_mode' 0, 1 1 integer pre-defined Value of the streaming_mode generic parameter specified in open_framegrabber. The streaming_mode is by default switched on for devices with streaming support and off for peripheral devices (devices without any data streams). The generic parameter streaming_mode explicitly allows switching the streaming functionality off, even for devices with streaming support.
'vertical_resolution' 0, 1, resolution 1 integer pre-defined Current value of vertical resolution.
'volatile' 'disable', 'enable' 'disable' string pre-defined Current value of the volatile mode.
'workarounds' ['', 'enable_range_validation' ] '' string pre-defined List of workarounds enabled by the 'workarounds' generic parameter in open_framegrabber. Individual workaround names are separated by spaces.

Operator set_framegrabber_lut

Not supported by this interface.

Operator get_framegrabber_lut

Not supported by this interface.

Operator set_framegrabber_callback

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. 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.

Operator get_framegrabber_callback

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

Operator grab_image_start

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 camera and locks features protected during acquisition. The acquisition can be stopped (and the features unlocked) using set_framegrabber_param(..., 'do_abort_grab', ...).

Operator grab_image

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'.

Operator grab_image_async

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.

Operator grab_data

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.

Operator grab_data_async

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.

Operator close_framegrabber

This operator closes the device. See also close_framegrabber.

HDevelop Examples

For this interface there are the following examples available:
  • gigevision2.hdev - Benchmark.
  • gigevision2_2cameras.hdev - Grabbing images from two cameras.
  • gigevision2_chunkdata.hdev - Using GigE Vision Chunk Data.
  • gigevision2_crop.hdev - Example for grabbing images with software and hardware image cropping.
  • gigevision2_do_abort_grab.hdev - Aborting an ongoing image acquisition.
  • gigevision2_forceip.hdev - Using ForceIP to correctly configure a misconfigured GigE Vision device.
  • gigevision2_flir_ax5.hdev - Acquisition from a FLIR AX5 thermal imaging camera, visualization using an iron LUT and temperature alarm detection.
  • gigevision2_frame_rate.hdev - Grabbing images from a GigE Vision compliant camera and determine the actual frame rate with full resolution.
  • gigevision2_information.hdev - Program for gathering information about the system and the camera configuration. Please attach the resulting files when requesting support.
  • gigevision2_link_aggregation.hdev - Show usage in combination with static link aggregation (LAG).
  • gigevision2_multiframe.hdev - Show usage of MultiFrame mode.
  • gigevision2_atc4_objectmodel3d.hdev - Acquisition and visualization of 3D data for the Automation Technology C4 sensor.
  • gigevision2_photonfocus3d_objectmodel3d.hdev - Acquisition and visualization of 3D data for the Photonfocus 3D sensor.
  • gigevision2_wenglor_wecat3d_objectmodel3d.hdev - Acquisition and visualization of 3D data for the wenglor weCat3D sensors.
  • gigevision2_ip_address_handling.hdev - Reading IPv4 address and assigning IPv4 address statically.
  • gigevision2_interpacket_delay.hdev - Adjusting interpacket delay to enable the use of two cameras connected via a single switch to one network interface.
  • gigevision2_software_trigger.hdev - GenICam compliant usage of software trigger.
  • gigevision2_parameters.hdev - Lists all parameters of a device.
  • gigevision2_simple.hdev - A simple example to show the usage of the interface.

Switching From Previous Implementation of the GigEVision Interface

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: 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:
    • num_buffers instead of GtlNumBuffers
    • force_sockdrv instead of GtlForceSocketDriver
  • 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)
    • buffer_is_incomplete (GtlBufferIncomplete)
    • buffer_timestamp (GtlBufferTimestamp)
    • 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 callbacks (set_framegrabber_callback) are currently not supported (some of the will be re-introduced in GenICam compatible way in a future update):
  • transfer_end
  • device_lost
  • callback_queue_overflow

Troubleshooting

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 your device is connected via Ethernet and 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.
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 ESEN_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.

Release Notes

  • 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.