MVTec Software GmbH
 

Documentation

GigEVision / HALCON 12.0 / MVTec Software GmbH

Image Acquisition Interface for GigE Vision compliant cameras

Interface: GigEVision
Revision: 6.10
Date: 2017-11-28
HALCON Version: 12.0

General

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

System Requirements

  • Intel compatible PC with Windows Vista/7/8/10, Windows Vista/7/8/10 x64, also WoW64 (using 32-bit HALCON on 64-bit Windows), Linux with kernel 2.6 (or higher) , or OS X.
  • 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 settings allow your application or HDevelop to connect to the camera and to receive incoming images, otherwise the grabbing will fail.
  • MVTec GigE Vision Streaming Filter under Windows x86, WoW64 or Windows x64: The HALCON GigEVision interface automatically uses a filter driver to enhance the performance while streaming images. When installing HALCON 12.0 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 v1.0.7.0 for Windows 10 and driver version v1.0.6.6 for older Windows versions is actually installed (check your network properties). Older driver versions will not work!
  • GenICam version 3.0.2 . The corresponding files are part of the HALCON GigEVision package and are located in the directory genicam within the HALCON base directory %HALCONROOT%. Since the HALCON GigEVision interface sets all necessary environment variables on its own, no environment variables like GENICAM_ROOT_V2_x, PATH, LD_LIBRARY_PATH must be set or modified. Old variables referencing GenICam V1.1, V2.0 or V2.1 are not used anymore and should be deleted if not needed by other software. See section GenICam for more details.
  • Windows: HALCON image acquisition interface hAcqGigEVision.dll or hAcqGigEVisionxl.dll, respectively. Furthermore, the DLL pthreadVC2.dll must be within the search path %PATH%. 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 hAcqGigEVision.so or hAcqGigEVisionxl.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.

    OS X: HALCON image acquisition interface hAcqGigEVision.dylib or hAcqGigEVisionxl.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 buffer handling mode assumes the computer is fast enough to process all buffers from the camera. If this is not the case, they are silently discarded. The parameter 'GtlBlockID' can be used to check if every frame is received. The mode can be changed with the parameter 'GtlBufferHandlingMode'.

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 /Users/Shared/Library/Application Support/HALCON-12.0
    • The doc folder to /Library/Application Support/HALCON-12.0

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.
  • Grabbing from multiple cameras.
  • Synchronous and asynchronous grabbing.
  • 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.
  • Support of ForceIP.
  • Support of callbacks for device-specific events and driver-specific callbacks.
  • Support of 'Continuous', 'SingleFrame', and also 'MultiFrame' acquisition modes.

Limitations

  • The MVTec GigE Vision Streaming Filter works only under Windows. For more details see paragraph MVTec GigE Vision Streaming Filter.
  • No support of BayerXXPacked, BGRXXPlanar, and RGBXXPlanar pixel formats yet.
  • No support of GenICam chunk data.
  • Only stream channel 0 supported.
  • On 32 bit systems, 64 bit parameter values cannot be used.

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 12.0 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 will warn that the driver is not Windows logo certified. This warning can be safely ignored.
  • The generic parameter 'GtlForceSocketDriver' is available, when it is necessary to disable the use of the filter driver for a specific device.
  • The parameter 'GtlAcquisitionEngine' 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 'GtlNumBuffers' in this case.
  • If the filter driver cannot be used, the underlying GVSP streaming is performed in user-space by the socket driver, so the CPU load may reach higher values (especially under Windows) while grabbing images.
  • When using the MVTec GigE Vision Streaming Filter incomplete buffers are silently discarded. Check the GtlBlockID to see if buffers are missing.

GenICam

  • This interface uses GenApi version 3.0.2 , for more details refer to the GenICam homepage. The corresponding files are part of the HALCON GigEVision package and are located in the directory genicam within the HALCON base directory %HALCONROOT% or $HALCONROOT, respectively. This version is the same as the official release version.
  • The HALCON GigEVision interface sets all necessary environment variables on its own and ignores other installed GenICam packages by default.
    On Linux the environment variable $LD_LIBRARY_PATH cannot be disabled by the interface and if it contains a reference to any other GenICam version the automatic loading of the correct GenICam version may fail. In this case please remove the unnecessary entries from $LD_LIBRARY_PATH by hand.
    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. Only one GenICam version can be used at the same time even by different acquisition interfaces (that may also use external GenICam installations)!
  • The caching of device XML files is activated to speedup processing, Windows uses %TEMP% and Linux uses $TMP or /tmp if $TMP is not set.
  • If you upgraded from an older version of the HALCON GigEVision interface you can eventually remove the old GenICam package and all variables which reference it. This means to remove the reference to the old GenICam package from the %PATH% variable on Windows or the $LD_LIBRARY_PATH on Linux respectively. You may also want to remove all environment variables starting with GENICAM_ and not ending in _V3_0 .
  • To use GenApi in your programs references to the node map pointer and to the port pointer of the device are available as parameters.
    Caution, use at your own risk! When using the GenApi and device port pointers directly, the HALCON GigEVision image acquisition interface may become unstable as it will not be able to track changes.

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 'GtlGVSPInterpacketDelay' might be necessary to improve the performance.

Custom Pixel Formats

The HALCON GigEVision interface has a built-in converter from the GigE Vision pixel formats to the desired HALCON image format. With the parameters 'ColorSpace' and 'BitsPerChannel' the resulting HALCON image is specified.
To offer a basic support for custom pixel formats a compatible BitsPerChannel value and a ColorSpace with value 'raw' will be set for unsupported formats. If no BitsPerChannel value according to the current PixelFormat can be determined, the fallback value is 8 and the image dimensions are calculated accordingly. The resulting HALCON image might look incorrect, but this enables the user to convert the raw image on his own by calling get_image_pointer1 and directly processing the raw image data.

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 don't.
  • The display of integer parameter values follows the HALCON conventions which means that they might be displayed as signed values and that there is a difference between 64 bit and 32 bit systems. Of course you can also specify hexadecimal values (start numbers with 0x) for input or display an integer value as hex e.g. with HexValue := IntValue$'#x' as always in HDevelop.

Naming of the parameters

In the HALCON GigEVision interface three different kinds of parameter types exist. Note that a complete list of the available parameters of the connected camera can be obtained by calling get_framegrabber_param(..., 'available_param_names', ...).
  • GigE Vision parameters are described in the XML file of the camera and appear in HALCON in the same naming and category as in the XML file. The naming of the parameters follows the corresponding version of the Standard Features Naming Convention (SFNC) of the GenICam standard if the device is fully GigE Vision compliant.
  • GTL parameters are provided by the MVTec GigE Vision driver and described below. They can be recognized by the prefix 'Gtl'. GTL parameters belong to the category, where the node 'PayloadSize' is found. According to the GenICam SFNC this should be 'GigE Vision Transport Layer'.
  • HALCON parameters are provided by the HALCON image acquisition interface and described below. They can be recognized by the underscore in the name. HALCON parameters belong to the category 'HALCON Interface'.

Using Internal Color Conversion

The HALCON GigEVision 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:', 'xml', '<path>', 'default'] string pre-defined Syntax for camera 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', 'default', 0, 0] mixed pre-defined Default values for open_framegrabber.
'device' ['<device>'] string dynamic Device names of the available devices.
'external_trigger' [] Unused.
'field' [] Unused.
'general' [] string pre-defined Information about the HALCON GigEVision interface.
'generic' ['', 'GtlForceIP=<MACAddress, IPAdress/Netmask[, Gateway][, Timeout]>', 'GtlUseCameraPacketSize=1', 'GtlDisableAutomaticTestPackets=1', 'GtlNumBuffers=<num>', 'GtlGVCPTimeout=<microseconds>', 'GtlGVCPRetries=<retries>', 'GtlForceSocketDriver=1'] string pre-defined Value list for the Generic parameter.
'horizontal_resolution' [0, 1, 2, 4] integer pre-defined Value list for horizontal resolution.
'image_height' [] Unsupported query.
'image_width' [] Unsupported query.
'info_boards' ['unique_name:<unique_name> | user_name:<user_device_id> | ip_address:<ip_address> | netmask:<netmask> | gateway_address: <gateway_address> | ip_config_current:<config> | mac_address: <mac_address> | interface_ip_address:<ip_address> | interface_netmask:<netmask> | version:<version> | serial: <serial> | gev_version:<version> | status:<status> | device: <device_id>'] string dynamic Shows all connected devices with additional information as a string. Some values are only shown, if they are available.
  • unique_name is a string, which contains the MAC address of the device, the vendor, and the model separated by underscores. No other device should have the same string, so this string is a unique name for the device. This value can also be queried by the parameter 'GtlDeviceUniqueName'.
  • 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.
  • ip_address shows the IP address of the device, e.g. 169.54.12.243. This value can also be queried by the feature 'GevCurrentIPAddress'.
  • netmask shows the netmask of the device, e.g. 255.255.0.0. This value can also be queried by the feature 'GevCurrentSubnetMask'.
  • gateway_address is the address of the gateway. This value can also be queried by the feature 'GevCurrentDefaultGateway'.
  • ip_config_current shows the current IP configuration of the device. This can be 'DHCP', 'PersistentIP', 'LLA', or a combination of these values concatenated by a plus. This value can also be queried by the feature 'GevCurrentIPConfiguration'.
  • mac_address shows the hexadecimal MAC address of the device separated by colons. This value can also be queried by the feature 'GevMACAddress'.
  • interface_ip_address is the IP address of the interface (mostly a network card), which has detected the device by a broadcast request.
  • interface_netmask is the netmask of the interface (mostly a network card), which has detected the device by a broadcast request.
  • version represents the value of the feature 'DeviceVersion'. The content is vendor-specific.
  • serial represents the value of the feature 'DeviceID'. The content is vendor-specific.
  • gev_version represents the value of the features 'GevVersionMajor' and 'GevVersionMinor' separated by a dot, e.g. 1.0.
  • status shows, if the device is correctly configured or not. The possible values are 'available' or 'misconfigured'.
  • device 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.
'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 GigEVision interface.
'start_column' [] Unsupported query.
'start_row' [] Unsupported query.
'vertical_resolution' [0, 1, 2, 4] integer pre-defined Value list for vertical resolution.

Parameters for open_framegrabber

Parameter Values Default Type Description
Name 'GigEVision' string Name of the HALCON interface.
HorizontalResolution 0, 1, 2, 4, resolution 1 integer Set the desired horizontal resolution of the camera image:
  • 0: Take the current settings of the camera.
  • 1: Use full resolution, reset all previous settings. If Width is bigger than 16000 or smaller than the current value, the current value is left untouched (we assume the XML file is incorrect). If a bigger value is desired, the value must be set manually (do not use 1 for HorizontalResolution). If this setting doesn't work, the interface automatically tries to use the current settings of the camera.
  • 2, 4: If binning is available, it is set to the factor, otherwise, it is tried to set decimation instead.
  • resolution: User defined horizontal resolution is set.
VerticalResolution 0, 1, 2, 4, resolution 1 integer Set the desired vertical resolution of the camera image:
  • 0: Take the current settings of the camera
  • 1: Use full resolution, reset all previous settings. If Height is bigger as 16000 in case of an area scan camera or smaller than the current value, the current value is left untouched (we assume the XML file is incorrect). If a bigger value is desired, the value must be set manually (do not use 1 for VerticalResolution). If this setting doesn't work the interface automatically tries to use the current settings of the camera.
  • 2, 4: If binning is available, it is set to the factor, otherwise, it is tried to set decimation instead. If this also fails, half or quarter of the maximum image size is set.
  • resolution: User defined vertical resolution is set.
ImageWidth 0, <width> 0 integer Width of the desired image part ('0' stands for the complete image). If this value is not set, the interface assumes the user always wants to get the maximum possible image size.
ImageHeight 0, <height> 0 integer Height of the desired image part ('0' stands for the complete image). If this value is not set, the interface assumes the user always wants to get the maximum possible image size.
StartRow 0, <row> 0 integer Row coordinate of the upper left pixel within the desired image part.
StartColumn 0, <column> 0 integer Column coordinate of the upper left pixel within the desired image part.
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 current bit depth of the camera is used. By specifying a value greater than 8 the grabbed images are delivered as uint2 images.
ColorSpace 'default', 'gray', 'raw', 'rgb', 'yuv' 'gray' 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'.
Generic '', ['GtlForceIP=<MACAddress, IPAdress/Netmask[, Gateway][, Timeout]>', 'GtlUseCameraPacketSize=1', 'GtlDisableAutomaticTestPackets=1', 'GtlNumBuffers=<num>', 'GtlGVCPTimeout=<microseconds>', 'GtlGVCPRetries=<retries>', 'GtlForceSocketDriver=1'], -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. ['GtlGVCPTimeout=200000', 'GtlForceIP=110401beef00, 192.168.4.1/24'] sets the GtlGVCPTimeout to 200 ms and the device with the MAC address 11:04:01:be:ef:00 to IP 192.168.4.1 with a subnet mask of 24 byte, which is equal to 255.255.255.0.
The following parameters are available:
  • GtlNumBuffers
    To set the maximum number of buffers used in the HALCON acquisition interface a value between 1 and 65535 has to be set. 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. Default: 5.
  • GtlGVCPRetries
    The number of GVCP retries represents how often the application tries to set a value to the camera if it does not work the first time.
  • GtlGVCPTimeout
    The GVCP timeout has to be set in microseconds. It defines the time the application waits for an acknowledge from the camera about the status of the last action. Internally the timeout for writing into the memory of the camera is set to the desired value times 5.
  • GtlUseCameraPacketSize
    If this parameter is set to 1, the current packet size value of the camera is used. Default: 0.
  • GtlDisableAutomaticTestPackets
    By default, GTL automatically sends test packets to determine the optimal packet size. If this parameter is set to 1, sending of the test packets is disabled. Default: 0.
  • GtlForceIP
    To set a temporary IP address to a specific camera defined by the MAC address. At minimum 3 input values are needed: MAC address, new IP address for the device, and subnet mask. The values must be separated by commas (except the subnet mask, where the separator is a slash).
    The MAC address can be used either separated by colons or without a separator. The IP address must be decimal numbers separated by dots, followed either by a slash and the subnet mask in bytes or by a comma and the subnet mask in decimal numbers separated by dots. Optionally, a gateway with decimal numbers separated by dots and a timeout (in microseconds) can be set.
  • GtlForceSocketDriver
    If this option is set to 1, the camera uses the socket driver and does not automatically use the filter driver even if it is available. Default: 0.
ExternalTrigger --- Ignored. You can change these values with set_framegrabber_param via the generic trigger parameters of the camera.
CameraType 'default', '<xml_filename>' 'default' string By default, the XML description file with the camera parameters is derived directly from the camera. Alternatively, you can specify the name of the XML camera description file directly, e.g., 'C:\\MyCameraDescription.xml'.
Device 'default', <device_name> 'default' string To open a specific camera the device name as shown in info_framegrabber(...'device'...) has to be set. Alternatively, the MAC address without separators or the DeviceUserID can be used. If DeviceUserID is set, the HDevelop Image Acquisition Assistant shows this name instead of the GTL default name (MACAddress_VendorName_ModelName). If multiple devices have the same DeviceUserID, only the first device is listed by DeviceUserID. The other devices are shown with the GTL default name. To make sure the correct device is opened, either use the unique name or unique DeviceUserIDs. 'default' opens the first available camera.
Port --- Ignored.
LineIn --- Ignored.

Parameters for set_framegrabber_param

The parameters of the cameras are based on GenApi, so they can be different for each camera. A call of get_framegrabber_param(..., 'available_param_names', ...) returns a tuple containing all available parameters of the connected camera. To read e.g. the current gain of the camera AcqHandle refers to (after calling open_framegrabber), the user can call get_framegrabber_param(..., 'GainRaw', ...).
Additionally to the GenApi parameters of the camera, the following HALCON and GTL (GigE Vision Transport Layer) parameters are supported:
Parameter Values Default Type Description
'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 current bit depth of the camera is used. By specifying a value greater than 8 the grabbed images are delivered as uint2 images.
'callback_timeout' <milliseconds> 2000 integer Timeout in milliseconds for the callback waiting function. With -1 an infinite callback timeout is specified. To get further information, see set_framegrabber_callback.
'clear_buffer' 'disable', 'enable' 'disable' string If enabled, each buffer 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 (see also 'GtlGVSPDiscardIncompleteBuffers'). 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 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'.
'delay_after_stop' <milliseconds> 50 integer Specify the time to wait (in milliseconds) between calling AcquisitionStop and stopping the transport layer. The optimal value depends on the camera.
'do_abort_grab' --- Aborts the current image acquisition and unlocks parameters, which are locked according to the status of the transport layer.
'do_flush_buffers' 'oldest' string Discards the oldest image buffer without further processing.
'do_flush_callback_queue' --- Delete the currently queued callbacks from the internal callback event queue.
'do_write_xml_file' '<file_name>' string Specify the file name (including path) for writing the XML file of the camera to a specified file. Note that the HDevelop Image Acquisition Assistant saves the file either with the unique device name or as 'camera.xml' if the device name including the full path is longer than 1024 characters.
'GevCurrentIPConfigurationDHCP' 0, 1 integer Enable / disable the usage of DHCP to get the IP address for the current camera. If the usage of a persistent IP address is also enabled, the persistent IP address is used. Note that many cameras already provide this parameter directly via GenApi.
'GevCurrentIPConfigurationPersistentIP' 0, 1 integer Enable / disable the usage of a persistent IP address for the current camera. To have no problems connecting the camera after power off, please make sure that it has a valid IP address, subnet mask, and gateway (see parameters 'GevPersistentIPAddress', 'GevPersistentSubnetMask', and 'GevPersistentDefaultGateway'). Note that many cameras already provide this parameter directly via GenApi.
'GevPersistentDefaultGateway' <gateway> integer Specify a persistent gateway for the current camera. Please note that this setting is only valid if the persistent IP flag is enabled (see parameter 'GevCurrentIPConfigurationPersistentIP'). Note that many cameras already provide this parameter directly via GenApi.
'GevPersistentIPAddress' <address> integer Specify a persistent IP address for the current camera. Please note that this setting is only valid if the persistent IP flag is enabled (see parameter 'GevCurrentIPConfigurationPersistentIP'). Note that many cameras already provide this parameter directly via GenApi.
'GevPersistentSubnetMask' <mask> integer Specify a persistent subnet mask for the current camera. Please note that this setting is only valid if the persistent IP flag is enabled (see parameter 'GevCurrentIPConfigurationPersistentIP'). Note that many cameras already provide this parameter directly via GenApi.
'GevSCPSPacketSize' <size> integer Specify the current packet size of the transport layer. Please note that the maximum value depends on the settings of your network card. For reaching optimal performance, Jumbo frames should be enabled. Note that many cameras already provide this parameter directly via GenApi.
'grab_timeout' <milliseconds> 5000 integer Desired timeout (milliseconds) for aborting a pending grab. If -1 is specified, the timeout is set to INFINITE.
'GtlBlockTimeout' <GtlBlockTimeoutUnit> integer Timeout for the current device, in which a complete block has to be received. Big images need bigger values. In case of receiving as much complete buffers as possible, a high value is recommended. Then, the resending mechanism tries to get the missing packets from the camera as long as the timeout is not elapsed. The unit of this parameter is specified by GtlBlockTimeoutUnit.
'GtlBlockTimeoutUnit' 'ns', 'us', 'ms' 'us' string Unit that applies to the value specified by the parameter GtlBlockTimeout.
'GtlBufferHandlingMode' '1', '2' '1' string Specify the mode gtl handles the buffers internally.
  • '1': As long as input buffers are available, all images are acquired and stored in the output buffer queue. Each call of grab_image_async returns the oldest acquired image from the output buffer queue. If the application is not fast enough to process all buffers, newly acquired images will be silently discarded.
  • '2': If no input buffer is available, the oldest acquired image in the output buffer queue is discarded silently and this buffer is used as new input buffer. Each call of grab_image_async always returns the oldest acquired image from the output buffer queue.
'GtlDeviceRegister_#addr_#len' '<register_values>' string With this parameter it is possible to access device registers directly. The register base address and the number of bytes to be written or to be read need to be specified in the name of the parameter. If you want to use hexadecimal representation, you need to prepend a '0x' to the value. The '#len' must be a multiple of 4 Byte, as a single register access reads or writes 4 bytes. You will need to specify a tuple of 'register_values', each one representing the value of one register in host byte order. It will be automatically converted to and from network byte order by the operator.
Caution, use at your own risk and be extremely careful! This bypasses the HALCON image acquisition interface and talks directly to the device. This can result in unstable behavior or even crashes of your system!
'GtlGVCPRetries' <num_retries> 3 integer Number of retries for the current device, if reading/writing a register has failed.
'GtlGVCPTimeout' <microseconds> 400000 integer Timeout in microseconds for the current device, if the read/write operation from/to a register is not acknowledged. Internally the timeout for writing into the memory of the camera is set to the desired value times 5.
'GtlGVSPDiscardIncompleteBuffers' 'disable', 'enable' 'disable' string If disabled every buffer is shown regardless which state it has. For getting only complete buffers in HALCON this setting must be enabled, see also parameter 'clear_buffer'. If using the filter driver incomplete buffers are always discarded.
'GtlGVSPDynamicPacketTrailer' 'disable', 'enable' 'disable' string Some cameras have problems using dynamic trailer IDs. Therefore, the default is to use a fixed packet trailer ID. This parameter is also useful for line scan cameras.
'GtlGVSPInterpacketDelay' <nanoseconds> 0 integer Delay time between the packets in nanoseconds. This parameter is useful, if a camera sends the packets faster than the computer can handle them. Values between 1000 and 20000 fit for most cases.
'GtlGVSPPacketTimeout' <GtlGVSPPacketTimeoutUnit> 20000 integer Timeout for a GVSP packet resend request if no following packet is received in the unit specified by the parameter GtlGVSPPacketTimeoutUnit.
'GtlGVSPPacketTimeoutUnit' 'ns', 'us', 'ms' 'ns' string Unit that applies to the value specified by the parameter GtlGVSPPacketTimeout.
'GtlGVSPResends' <num_resends> 3 integer Number of resends for the current device, if a packet was lost or incomplete. Use 0 to disable the packet resend mechanism. If the initial value is 0, the device doesn't support resending.
'GtlGVSPResendWait' <num_packets> 4 integer Number of GVSP packets to wait before starting a resend request for a missing packet.
'image_height' 0, <min ... max> integer Height of the resulting HALCON image. 0 specifies the maximum image height. If this value is not set, the interface assumes the user always wants to get the maximum possible image size.
'image_width' 0, <min ... max> integer Width of the resulting HALCON image. 0 specifies the maximum image width. If this value is not set, the interface assumes the user always wants to get the maximum possible image size.
'max_num_queued_callbacks' <queue_size> 256 integer Specify the size of the internal callback queue.
'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 ... <max> integer Column coordinate of the upper left corner of the resulting HALCON image part. If this value is not set, the interface assumes the user always wants to get the maximum possible image size.
'start_row' 0 ... <max> integer Row coordinate of the upper left corner of the resulting HALCON image part. If this value is not set, the interface assumes the user always wants to get the maximum possible image size.
'volatile' 'disable', 'enable' 'disable' string Raw and grayscale only. In the volatile mode the image buffers are used directly to store HALCON images. This is the fastest mode avoiding to copy raw images in memory. However, be aware that older images are overwritten again and again as a side-effect. Thus, you can only process one image while you grab another image. Older images are invalid! Please note that the HDevelop Image Acquisition Assistant offers only the 'enable' value, if the current PixelFormat and color_space allows volatile mode. So after changing these parameters, the refresh button has to be used to get the new status of the values for volatile.

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
'available_callback_types' ['<callback_type>'] string dynamic Query all callback types which are supported by this interface.
'available_param_descriptions' ['<parameters>'] string dynamic A list containing additional information about all parameters. The order of the entries is equal to the order of the parameter names returned by 'available_param_names'.
'available_param_names' ['<parameters>'] string dynamic The list contains the names of all available parameters.
'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 current bit depth of the camera is used. By specifying a value greater than 8 the grabbed images are delivered as uint2 images.
'callback_timeout' <milliseconds> 2000 integer pre-defined Timeout in milliseconds for the callback waiting function. With -1 an infinite callback timeout is specified. To get further information, see set_framegrabber_callback.
'camera_type' '<xml_filename>' 'default' string pre-defined Name of the used XML file.
'clear_buffer' 'disable', 'enable' 'disable' string pre-defined If enabled each buffer is cleared before re-queueing.
'color_space' 'gray', 'raw', 'rgb', 'yuv' 'gray' string pre-defined Desired color space and thus the number of image channels of the resulting HALCON image.
'delay_after_stop' <milliseconds> 50 integer pre-defined Returns the current delay after stop in milliseconds.
'device' <device_name> 'default' string dynamic Device names of the available devices.
'DeviceID' '<device_id>' string dynamic ID of the current device.
'DeviceModelName' '<model>' string dynamic Model name of the current device.
'DeviceVendorName' '<vendor>' string dynamic Name of the device vendor.
'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.
'GenApiCNodeMapRefPtr' <pointer> integer dynamic A pointer to the GenApi node map of the device. Use at your own risk!
'generic' '', ['GtlForceIP=<MACAddress, IPAdress/Netmask[, Gateway][, Timeout]>', 'GtlUseCameraPacketSize=1', 'GtlDisableAutomaticTestPackets=1', 'GtlNumBuffers=<num>', 'GtlGVCPTimeout=<microseconds>', 'GtlGVCPRetries=<retries>', 'GtlForceSocketDriver=1'], -1 -1 mixed pre-defined Values of the Generic parameter.
'GevCurrentIPAddress' '<ip_address>' integer dynamic IP address of the current interface.
'GevCurrentIPConfigurationDHCP' 0, 1 integer dynamic Usage of DHCP to get the IP address for the current camera.
'GevCurrentIPConfigurationPersistentIP' 0, 1 integer dynamic Usage of a persistent IP address for the current camera.
'GevPersistentDefaultGateway' <gateway> integer dynamic Persistent gateway of the current camera.
'GevPersistentIPAddress' <address> integer dynamic Persistent IP address of the current camera.
'GevPersistentSubnetMask' <mask> integer dynamic Persistent subnet mask of the current camera.
'GevSCPSPacketSize' <size> integer dynamic Current packet size of the transport layer.
'grab_timeout' <milliseconds> 5000 integer pre-defined Current grab timeout in milliseconds.
'GtlAcquisitionEngine' '<driver_type>' string dynamic Driver type used by the acquisition engine for this device. This can be 'filter driver' or 'socket driver'. The filter driver enhances the performance and is automatically used if available. Use the generic parameter 'GtlForceSocketDriver' when opening the device to disable the use of the filter driver for it.
'GtlBlockID' <block_id> integer dynamic ID of the last received block (typically of type image) as reported by the device. If no block has been received 0 is returned.
'GtlBlockTimeout' <GtlBlockTimeoutUnit> integer pre-defined Timeout for the current device, in which a complete block has to be received. Big images need bigger values. In case of receiving as much complete buffers as possible, a high value is recommended. Then, the resending mechanism tries to get the missing packets from the camera as long as the timeout is not elapsed. The unit of this parameter is specified by GtlBlockTimeoutUnit.
'GtlBlockTimeoutUnit' 'ns', 'us', 'ms' 'us' string pre-defined Unit that applies to the value specified by the parameter GtlBlockTimeout.
'GtlBufferHandlingMode' '1', '2' '1' string pre-defined The mode gtl handles the buffers internally.
'GtlBufferIncomplete' 0, 1 integer dynamic State of the current buffer. In case of an incomplete buffer 1 is returned. When using the filter driver incomplete buffers are silently discarded. Check the GtlBlockID to see if buffers are missing.
'GtlBufferTimestamp' <ticks> integer dynamic Time stamp of the current buffer in ticks. The time in seconds can be calculated via the parameter 'GevTimestampTickFrequency' (if available).
'GtlCurrentIPAddress' '<ip_address>' string dynamic IP address of the current device.
'GtlDeviceMACAddress' '<mac_address>' string dynamic MAC address of the current device.
'GtlDeviceRegister_#addr_#len' '<register_values>' string dynamic With this parameter it is possible to access device registers directly. The register base address and the number of bytes to be written or to be read need to be specified in the name of the parameter. If you want to use hexadecimal representation, you need to prepend a '0x' to the value. The '#len' must be a multiple of 4 Byte, as a single register access reads or writes 4 bytes. You will need to specify a tuple of 'register_values', each one representing the value of one register in host byte order. It will be automatically converted to and from network byte order by the operator.
Caution, use at your own risk and be extremely careful! This bypasses the HALCON image acquisition interface and talks directly to the device. This can result in unstable behavior or even crashes of your system!
'GtlDeviceUniqueName' '<unique_name>' string dynamic Unique name of the current device.
'GtlDisableAutomaticTestPackets' 0, 1 0 integer pre-defined Shows if the automatic test packet for optimization of the packet size was disabled.
'GtlDisplayName' '<display_name>' string dynamic Display name of the system.
'GtlFileName' '<file_name>' string dynamic File name of the system.
'GtlForceSocketDriver' 0, 1 0 integer pre-defined Shows if the socket driver was forced to use, even if the filter driver was available.
'GtlGVCPRetries' <num_retries> 3 integer pre-defined Number of retries for the current device, if reading/writing a register has failed.
'GtlGVCPTimeout' <microseconds> 400000 integer pre-defined Timeout in microseconds for the current device, if the read/write operation from/to a register is not acknowledged. Internally the timeout for writing into the memory of the camera is set to the desired value times 5.
'GtlGVSPDiscardIncompleteBuffers' 'disable', 'enable' 'disable' string pre-defined Shows if also incomplete buffers are shown.
'GtlGVSPDynamicPacketTrailer' 'disable', 'enable' 'disable' string pre-defined Shows if dynamic or static trailer IDs are used.
'GtlGVSPInterpacketDelay' <nanoseconds> 0 integer pre-defined Delay time between the packets in nanoseconds.
'GtlGVSPPacketTimeout' <GtlGVSPPacketTimeoutUnit> 20000 integer pre-defined Timeout for a GVSP packet resend request if no following packet is received in the unit specified by the parameter GtlGVSPPacketTimeoutUnit.
'GtlGVSPPacketTimeoutUnit' 'ns', 'us', 'ms' 'ns' string pre-defined Unit that applies to the value specified by the parameter GtlGVSPPacketTimeout.
'GtlGVSPReceivedPackets' <num_packets> integer dynamic Current number of packets received.
'GtlGVSPResends' <num_resends> 3 integer pre-defined Number of resends for the current device, if a packet was lost or incomplete.
'GtlGVSPResendsRequested' <num_requests> integer dynamic Returns the number of resends requested for the current stream.
'GtlGVSPResendWait' <num_packets> 4 integer pre-defined Number of GVSP packets to wait before starting a resend request for a missing packet.
'GtlIncompleteBuffers' <num_incomplete> integer dynamic Current number of incomplete buffers received.
'GtlInterfaceID' '<interface_id>' string dynamic ID of the current interface.
'GtlModelName' '<model_name>' string dynamic Model name of the system.
'GtlNumBuffers' <number> 5 integer pre-defined Number of currently used buffers for the internal ring buffer.
'GtlPathName' '<path_name>' string dynamic Path name of the system.
'GtlPortPtr' <pointer> integer dynamic Pointer to the device port which enables direct device access. Use at your own risk!
'GtlSerialNumber' '<serial_number>' string dynamic Serial number of the current device.
'GtlSupportedIPConfigurationDHCP' 0, 1 integer dynamic Returns 1 if IP configuration via DHCP is supported by the camera.
'GtlSupportedIPConfigurationPersistent' 0, 1 integer dynamic Returns 1 if IP configuration via Persistent IP is supported by the camera.
'GtlTLType' '<tl_type>' string dynamic Type of the system transport layer.
'GtlUseCameraPacketSize' 0, 1 0 integer pre-defined Shows if the packet size of the camera was used with open_framegrabber.
'GtlVendorName' '<vendor>' string dynamic Name of the system vendor.
'GtlVersion' '<version>' string dynamic Version number of the system.
'horizontal_resolution' 0, 1, 2, 4, resolution 1 integer pre-defined Current value of horizontal resolution.
'image_available' 0, 1 integer dynamic Status of the last asynchronous grab command. The value 1 means that the image is already acquired and thus can be fetched by grab_image_async without delay. Note that this parameter is especially useful in combination with external triggering.
'image_height' <height> 0 integer pre-defined Height of the desired image part ('0' stands for the complete image).
'image_width' <width> 0 integer pre-defined Width of the desired image part ('0' stands for the complete image).
'line_in' <default> 0 integer pre-defined The value is not used, so a default value is returned.
'max_num_queued_callbacks' <queue_size> 256 integer dynamic Specify the size of the internal callback queue.
'name' 'GigEVision' string pre-defined Name of the HALCON interface.
'num_queued_callbacks' <queued_callbacks> integer dynamic Number of internally queued callbacks.
'parameters_hidden' ['<parameters>'] string dynamic A list containing the names of all hidden parameters.
'port' <default> 0 integer pre-defined The value is not used, so a default value is returned.
'revision' '<revision>' string pre-defined Revision number of the GigEVision interface.
'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 Returns the current start column of the HALCON image.
'start_row' <row> 0 integer pre-defined Returns the current start row of the HALCON image.
'vertical_resolution' 0, 1, 2, 4, resolution 1 integer pre-defined Current value of vertical resolution.
'volatile' 'disable', 'enable' 'disable' string pre-defined Grayscale only. In the volatile mode the two image acquisition interface buffers are used directly to store HALCON images. This is the fastest mode avoiding to copy raw images in memory. However, be aware that older images are overwritten again and again as a side-effect. Thus, you can only process one image while you grab another image. Older images are invalid!

Additional parameters for set_framegrabber_param

We recommend not to use the following parameters, because they are handled internally: 'AcquisitionStart', 'AcquisitionStop', and 'TLParamsLocked'.
Parameter Values Default Type Description
'AcquisitionMode' 'Continuous', 'SingleFrame', 'MultiFrame' string The acquisition mode of the device.
'AcquisitionStart' 0, 1 integer Starts the acquisition of the device.
'AcquisitionStop' 0, 1 integer Stops the acquisition of the device at the end of the current frame.
'Device' Provides the default GenICam port of the device. Note that this feature is not visible in HALCON.
'Height' <height> integer Height of the image provided by the device (in pixels).
'PixelFormat' <PixelFormat> string Format of the pixel provided by the device.
'TLParamsLocked' 0, 1 integer Used by the Transport Layer to prevent critical features changing during acquisition.
'Width' <width> integer Width of the image provided by the device (in pixels).

Additional parameters for get_framegrabber_param

All GenICam compliant devices contain a XML file, which describes the features of the device. The Standard Features Naming Convention (available here) lists all features a device must or can have. Below you find the list of all mandatory features, which every device must support. Please note, that the value types and values are adapted to HALCON.
Parameter Values Default Type Kind Description
'AcquisitionMode' 'Continuous', 'SingleFrame', 'MultiFrame' string dynamic The acquisition mode of the device.
'Device' dynamic Provides the default GenICam port of the device. Note that this feature is not visible in HALCON.
'Height' <height> integer dynamic Height of the image provided by the device (in pixels).
'PayloadSize' <bytes> integer dynamic Provides the number of bytes transferred for each image or chunk on the stream channel.
'PixelFormat' <PixelFormat> string dynamic Format of the pixel provided by the device.
'Root' dynamic Provides the root of the GenICam features tree. Note that this feature is not visible in HALCON.
'TLParamsLocked' 0, 1 integer dynamic Used by the Transport Layer to prevent critical features changing during acquisition.
'Width' <width> integer dynamic Width of the image provided by the device (in pixels).

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 device-specific events and driver-specific callbacks via the operators set_framegrabber_callback and get_framegrabber_callback.

All actually supported callback types of the driver and of the specific device can be queried by calling get_framegrabber_param with the parameter 'available_callback_types'. Once a callback function is registered by calling the operator set_framegrabber_callback, on every occurrence of the callback type (e.g., the notification that the exposure has been finished) the user-specified callback function will be called. If the callback function is set to NULL, the corresponding callback will be unregistered. Note that device-specific callback types must be activated before you can use them.

Attention: To activate or deactivate the device-specific callback types, the corresponding device-specific event has to be enabled or disabled. This means you have to set the GenICam SFNC feature 'EventSelector' to the specific event type, and the 'EventNotification' feature to 'On' (or sometimes 'GenICamEvent' or 'GigEVisionEvent') depending on the GenICam SFNC version which is used by the device.

The signature of the callback function is Herror (__stdcall *HAcqCallback)(void *AcqHandle, void *Context, void *UserContext) for Windows operating systems. All other operating systems use their native calling convention instead of __stdcall.
The callback function uses the following parameters:
  • AcqHandle Acquisition handle of the corresponding image acquisition instance.
  • Context Optional context data of the specific callback. Reserved for future use and therefore it should be set to NULL.
  • UserContext User context as set via set_framegrabber_callback.

Using callback functions
Please make sure the execution time of the user-specified callback function is shorter than the time between the events which trigger this callback, else the internal callback queue will increase till it reaches the 'max_num_queued_callbacks' limit and further callbacks will be discarded. You can query the parameter 'num_queued_callbacks' or register a callback for the callback type 'callback_queue_overflow' to detect this situation. The maximum number of internally queued callbacks can be specified using the parameter 'max_num_queued_callbacks'. There are also C++ and C# examples which demonstrate the use of callbacks.

The following driver-specific callback types are supported. In contrast to the device-specific callback types which are written in CamelCase these are written in lowercase letters and separated with an underscore.
Type Description
'transfer_end' Notification when the requested image is completely transferred to the host computer.
'device_lost' Notification when the connection to the device gets lost. This is detected by observing the GigE Vision heartbeat.
'callback_queue_overflow' Notification when the internal callback queue reaches the maximum defined value specified via the parameter 'max_num_queued_callbacks'. The internal callback queue will constantly increase when the execution time of the user-specified callback is longer than the time between the events which trigger this callback. When 'max_num_queued_callbacks' is reached all new signaled callback types will be dropped. The notification of the 'callback_queue_overflow' callback is done only once while the 'max_num_queued_callbacks' limit is reached.

Operator get_framegrabber_callback

This interface supports device-specific events and driver-specific events 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.

Operator grab_image

grab_image starts a new synchronous grab. See also grab_image. Note that the interface converts the image from the device to the desired image format specified by the parameters 'image_width', 'image_height', 'start_row', 'start_column', 'bits_per_channel', and 'color_space'.

Operator grab_image_async

grab_image_async returns an image and starts the next asynchronous grab. See also grab_image_async. Note that the interface converts the image from the device to the desired image format specified by the parameters 'image_width', 'image_height', 'start_row', 'start_column', 'bits_per_channel', and 'color_space'.

Operator grab_data

Not supported by this interface.

Operator grab_data_async

Not supported by this interface.

Operator close_framegrabber

This operator closes the device. See also close_framegrabber.

HDevelop Examples

For this interface there are the following examples available:
  • gigevision.hdev - Benchmark.
  • gigevision_2cameras.hdev - Grabbing images from two cameras.
  • gigevision_crop.hdev - Example for grabbing images with software and hardware image cropping.
  • gigevision_do_abort_grab.hdev - Aborting an ongoing image acquisition.
  • gigevision_forceip.hdev - Using ForceIP to correctly configure a misconfigured GigE Vision device.
  • gigevision_flir_ax5.hdev - Acquisition from a FLIR AX5 thermal imaging camera, visualization using an iron LUT and temperature alarm detection.
  • gigevision_frame_rate.hdev - Grabbing images from a GigE Vision compliant camera and determine the actual frame rate with full resolution.
  • gigevision_information.hdev - Program for gathering information about the system and the camera configuration. Please attach the resulting files when requesting support.
  • gigevision_link_aggregation.hdev - Show usage in combination with static link aggregation (LAG).
  • gigevision_multiframe.hdev - Show usage of MultiFrame mode.
  • gigevision_atc4_objectmodel3d.hdev - Acquisition and visualization of 3D data for the Automation Technology C4 sensor.
  • gigevision_photonfocus3d_objectmodel3d.hdev - Acquisition and visualization of 3D data for the Photonfocus 3D sensor.
  • gigevision_wenglor_wecat3d_objectmodel3d.hdev - Acquisition and visualization of 3D data for the wenglor weCat3D sensors.
  • gigevision_ip_address_handling.hdev - Reading IPv4 address and assigning IPv4 address statically.
  • gigevision_interpacket_delay.hdev - Adjusting interpacket delay to enable the use of two cameras connected via a single switch to one network interface.
  • gigevision_software_trigger.hdev - GenICam compliant usage of software trigger.
  • gigevision_parameters.hdev - Lists all parameters of a device.
  • gigevision_simple.hdev - A simple example to show the usage of the interface.

C++ Examples

For this interface there is also a further C++ Visual Studio Project to demonstrate the usage of the operators get_framegrabber_callback and set_framegrabber_callback. Please check the directory %HALCONEXAMPLES%\cpp\console\vs2005\. If you prefer building the example via the console, please check the following folder %HALCONEXAMPLES%\cpp\console\. With a Linux OS please use $HALCONEXAMPLES/cpp/console/.

C# Examples

For this interface there is also a further C# Visual Studio Project to demonstrate the usage of the operators get_framegrabber_callback and set_framegrabber_callback. Please check the directory %HALCONEXAMPLES%\cpp\console\vs2005\.

Troubleshooting

In case of problems with the HALCON GigEVision Interface the following hints might help to solve them.
  • General:
    • Check if the camera has the latest firmware and is GigE Vision compatible.
    • Check if the latest revision of the HALCON GigEVision Interface is used.
    • Windows: check if the filter driver is used (see parameter 'GtlAcquisitionEngine').
    • Enable low-level error messages in HALCON to query more information about the problem.
    • Check if the settings of your firewall (Windows or other) allow the communication with the GigE Vision camera. Note that different connections are used for controlling the device (GVCP) and streaming data (GVSP). An incomplete configured firewall under Windows 7 will lead to the following low-level error: 'gtlOpenDevice failed - GVCP link error'.
      Note that it might be necessary to explicitly allow the specific application (e.g., HDevelop) using the Windows firewall settings dialog instead of using the default Windows dialog which appears when an application is blocked by the firewall for the first time.
    • 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.
  • HALCON GigEVision Interface could not be loaded:
    • Reason: the library itself or some dependencies could not be found.
    • Solution a): check PATH/LD_LIBRARY_PATH environment variables.
    • Solution b): (only Windows) check if pthreadVC2.dll is in the PATH
    • Solution c): check with Dependency Walker if there are further missing dependencies.
  • HALCON GigEVision Interface loaded, but connection fails:
    • Reason: could have several reasons, e.g., wrong network settings or interfering programs.
    • Solution a): check firewall settings.
    • Solution b): check miniport drivers of your camera which might steal the packets.
    • Solution c): check if the camera is reachable in the network (e.g., via ping).
    • Solution d): check if the camera is really GigE Vision compliant or needs a firmware update.
    • Solution e): In case of low-level error "no exclusive access":
      - somebody else is using the camera
      - heartbeat of the camera set too high
      - try power-cycling the camera
      - camera is not reachable in the current network
  • Connecting to the camera fails with GenICam exception:
    • Reason: a parameter should be set to a value, which does not fit into the valid range of the parameter.
    • Solution: call open_framegrabber with the parameters HorizontalResolution and VerticalResolution set to 0.
  • Grabbing images from the camera fails:
    • Reason: could have several reasons, e.g., blocking programs, network problems or parameter settings.
    • Solution a): check firewall settings.
    • Solution b): check miniport drivers of your camera which might steal the packets.
    • Solution c): reduce the amount of data by reducing the image size via the parameters Width and Height.
    • Solution d): check parameters of the camera, especially trigger mode, pixel format, or image size parameters (also parameters like PartialScan, etc.).
    • Solution e): reduce the duration of the image processing application, because in the current acquisition mode the computer must be fast enough to receive the images from the camera before all buffers are filled.
  • Corrupted images are received:
    • Reason: the system cannot receive or process all necessary packets and resending fails because of slow Ethernet cards, slow computers, slow network access or slow/heavily-loaded bus.
    • Solution a): Windows only: check if the filter driver is used.
    • Solution b): set GtlGVSPInterpacketDelay to a higher value to avoid bursting of packets which lead to overload.
    • Solution c): increase packet size (on network card and camera) to reduce the interrupt load and overhead.
    • Solution d): reduce bus load from other applications or cameras.
  • Parameter is not writeable anymore:
    • Reason: image acquisition is running.
    • Solution: stop image acquisition by calling set_framegrabber_param with parameter 'do_abort_grab'. If the HDevelop Image Acquisition Assistant is used, 'Update Image' must be disabled and the Refresh button pressed, to request the parameter list again.
  • Setting of GVCP parameters fails:
    • Reason: camera needs more time to set parameter.
    • Solution: increase GtlGVCPTimeout parameter.
  • Filter driver (MVTec GigE Vision Streaming Filter): In case there are problems with streaming while the filter driver is active it is possible to capture a network packet trace to analyse the problems. Set the environment variable ESEN_FILTER_PASSTHROUGH=1 to give other filters like Wireshark's pcap access to the packets.

If there are still problems, please contact your local distributor. The following information is needed for your support request to get an overview of the used hard- and software:

  • Used HALCON and acquisition interface versions.
  • Low-level error message.
  • Camera details.
  • Details about network card (PCI, CardBus, Jumbo frames, link speed, ...).
  • Details about network topology (directly connected, switches, ...).
  • Details about computer system (laptop, workstation, CPU, ...).

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

Usage of 3rd party libraries

This interface depends on the following 3rd party libraries. See the files third_party_copyrights.html and third_party_licenses.txt in the HALCON base directory for copyright and license information.

The corresponding sources can be downloaded from the MVTec WWW server.

Release Notes

  • Revision 6.10 (Nov 28, 2017):
    • Updated underlying GigE Vision transport layer (GTL) to v1.0.7.4 which fixes the broken access to some GtlGVSP parameters.
    • Updated the MVTec GigE Vision Streaming Filter to version 2.1.8.0 which fixes problems with resending and allows to capture a network packet trace with Wireshark.
    • The callback type names of device-specific events now follow the naming convention established in SFNC version 1.3. For compatibility, the old names as used by the EventSelector are still accepted in set_framegrabber_param.
    • The device-specific events of some devices were not recognized. This bug has been fixed.
    • Devices missing the Width and Height features could not be connected with full resolution specified. This bug has been fixed.
    • The HDevelop example gigevision_information.hdev has been added to gather information about the system and the camera configuration.
    • The HDevelop example gigevision_multiframe.hdev contained unwanted code lines. This problem has been fixed.
  • Revision 6.9 (May 3, 2017):
    • Updated underlying GenApi version to latest official release v3.0.2 which contains some minor bug fixes.
    • Updated underlying GigE Vision transport layer (GTL) to v1.0.7.3 where the internal data type of GtlBlockTimeout and GtlGVSPPacketTimeout has been changed from 32 to 64 bit unsigned integer. This allows to set higher values on 64 bit systems.
    • The previously hard-coded units of GtlBlockTimeout and GtlGVSPPacketTimeout can now be changed with the newly introduced parameters GtlBlockTimeoutUnit and GtlGVSPPacketTimeoutUnit. The default units are the previously hard-coded units 'us' (GtlBlockTimeout) and 'ns' (GtlGVSPPacketTimeout).
    • The parameters DeviceID, DeviceVendorName, DeviceModelName and some SFNC Transport Layer parameters were assigned the category of PayloadSize instead of their own one. This problem has been fixed.
    • The parameters callback_timeout and do_flush_callback_queue were not listed among available_param_names and available_param_descriptions. Further, they were missing attributes like access, category, range and visibility. This problem has been fixed.
    • Added new HDevelop example gigevision_2cameras.hdev that shows how to use the GigEVision interface with two cameras.
    • Added new HDevelop example gigevision_do_abort_grab.hdev that shows how to abort an ongoing image acquisition.
    • Added new HDevelop example gigevision_multiframe.hdev that shows how to use a GigEVision camera in MultiFrame mode.
    • Improved HDevelop example gigevision_wenglor_wecat3d_objectmodel3d.hdev.
  • Revision 6.8 (Aug 26, 2016):
    • Updated underlying GigE Vision transport layer (GTL) to v1.0.7.2. This improves the cleanup of a potentially remaining message channel before usage where certain cameras failed to connect.
    • Added new example gigevision_wenglor_wecat3d_objectmodel3d.hdev that shows how to acquire and visualize 3D data from a wenglor weCat3D sensor.
  • Revision 6.7 (May 13, 2016):
    • Updated underlying GenApi version to latest official release v3.0.1. With the previous version some specific cameras could not be opened and in the worst case the application also crashed when using such devices. This problem has been fixed. Please note that therefore also the genicam directory of your HALCON installation will be updated.
    • Updated underlying GigE Vision transport layer (GTL) to v1.0.7.1. This fixes a bug in v1.0.7.0 which made it impossible to receive events from some cameras. This problem has been fixed. It also avoids unnecessary resends in the socket driver if it is configured to skip incomplete buffers. This improves the performance of the filter driver in this case. Please note that the version of the HALCON GigE Vision Streaming Filter did not change.
    • Under Windows, open_framegrabber crashed if the environment variable PATH was empty. This problem has been fixed.
  • Revision 6.6 (Feb 15, 2016):
    • Updated underlying GenApi version to latest official release v3.0, which enables to open a device much faster and requires less memory. Please note that therefore also the genicam directory of your HALCON installation will be updated.
    • Updated the MVTec GigE Vision Streaming Filter for Windows 10 to version 1.0.7.0. Older Windows versions must still use the version 1.0.6.8. The installer will automatically install the correct version.
    • Added support for the 'Mono10p' and 'Mono12p' pixel formats.
    • Added paragraph 'Using internal color conversion' to this document.
    • According to this documentation, the fourth value returned by get_framegrabber_param(..., 'AnyParameter_range', ...) was a default value. Actually, it is the current value. Thus, this documentation has been adapted accordingly.
    • Added in the documentation that the filter driver automatically discards incomplete buffers. This information was missing previously.
  • Revision 6.5 (Nov 13, 2015):
    • set_framegrabber_param crashed when setting 'do_flush_buffers' or 'do_write_xml_file' with an empty tuple. This problem has been fixed.
  • Revision 6.4 (Oct 20, 2015):
    • The system requirements regarding the Visual Studio C++ Redistributable Package have been updated.
    • Updated underlying GigE Vision transport layer (GTL) to v1.0.6.14 in order to correct remaining occurrences of the old name HALCON GigE Vision Streaming Filter.
    • After loading a UserSet via the parameter 'UserSetLoad' in some cases the grabbing of an image failed. This problem has been fixed. Now the internal values of all important parameters are updated.
    • Added more detailed description of the information of info_framegrabber('info_boards',...).
    • This documentation did not list all available callback types. This problem has been fixed.
  • Revision 6.3 (Jun 10, 2015):
    • Under Windows, some GenICam dynamic libraries were not loaded/unloaded correctly and a low-level error was printed. This problem has been fixed.
    • In case the XML file for a device could not be loaded at all the interface crashed in some cases when internally cleaning up. This problem has been fixed.
    • Accessing GtlDeviceRegister_#addr_#len and GenericParameter_suffix crashed in some cases, especially when used in the C++ interface. This problem has been fixed.
    • The access, category and visibility properties were not supported for all parameters. This problem has been fixed.
    • The access and visibility properties returned 'undefined' in case the parameters had no such properties. Now they return an error if they are not available.
    • The access property for invisible parameters was mapped to 'na' (not available) as workaround for the image acquisition assistant. This mapping has been removed and now it returns the correct access property.
    • 'available_param_names' returned the names of invisible parameters but not all implemented parameters. Now it also returns 'na' parameters in addition to 'ro' (readonly), 'wo' (writeonly) and 'rw' (readwrite) parameters, but only when the visibility is not 'invisible'. Note that the access mode of parameters might change during runtime.
    • Removed 'TLParamsLocked' and 'AcquisitionAbort' from the list of 'available_param_names' as the user is not expected to touch these.
    • For some parameters (especially 'wo' ones), neither the range nor the values property was implemented. This problem has been fixed.
    • Renamed the parameter 'GevCurrentIPConfigurationPersistent' to the correct name 'GevCurrentIPConfigurationPersistentIP'.
    • The documentation for the parameter 'GtlBlockID' was wrong. This problem has been fixed.
    • The HDevelop example gigevision_parameters.hdev has been improved.
    • The following examples for typical use cases have been added: gigevision_software_trigger.hdev, gigevision_ip_address_handling.hdev, gigevision_interpacket_delay.hdev
    • Updated underlying GigE Vision transport layer (GTL) to v1.0.6.13 which comprises the following changes:
    • The message channel was not closed before and after usage. Therefore the events could not be used for some cameras when opening them a second time. This problem has been fixed.
    • Closing a device took up to 1s. This has been enhanced and now it takes up to 1/10s instead.
    • Note that the filter driver is still at v1.0.6.8 which comprises the following changes:
    • Instead of HALCON GigE Vision Streaming Filter, it is now called MVTec GigE Vision Streaming Filter.
    • There is now an installer available in %HALCONROOT%\misc to ease separate installation of the filter driver.
  • Revision 6.2 (Feb 26, 2015):
    • Updated underlying GenApi version to latest official release v2.4.1, including performance improvements and several minor bug fixes. Please note that therefore also the genicam directory of your HALCON installation will be updated.
    • Updated win32-pthread library pthreadVC2.dll to v2.9.1. This fixes the GigEVision interface hanging forever when used on Windows 8.x systems with .NET v4.5 and newer.
    • Updated underlying GigE Vision transport layer (GTL) to v1.0.6.12 to support newer win32-pthreads. Note that the filter driver is still at v1.0.6.8
    • Added troubleshooting hint in case unofficial GenICam binaries are used.
  • Revision 6.1 (Oct 31, 2014):
    • HALCON 12 version of the interface.
    • Added reference to 'available_param_names' parameter in section Naming of the parameters.
  • Revision 5.9 (May 23, 2014):
    • Fixed problem in set_framegrabber_callback. If an asynchronous grab was active and a previous registered callback was unregistered, the cleanup of the callback queue could run into an endless loop. In this case the unregister call with set_framegrabber_callback didn't return.
    • Fixed bug in set_framegrabber_param when trying to set a parameter without specifying a value.
  • Revision 5.8 (Mar 20, 2014):
    • Fixed problem when using multiple image acquisition interfaces, which do not use the same GenApi version, in arbitrary order.
    • Fixed crash when using multiple GenApi-based image acquisition interfaces which use the same GenApi version. In this case, when closing the last instance of one of the interfaces, GenApi could not be used by the remaining interfaces anymore.
    • When opening a device that is currently configured in 'SingleFrame' or 'MultiFrame' acquisition mode, this setting is no more overwritten with 'Continuous' acquisition mode.
    • Fixed 'MultiFrame' acquisition mode. Previously, an unnecessary 'AcquisitionStart' command was sent with every call of grab_image_async, now 'AcquisitionFrameCount' is used to determine when to send the 'AcquisitionStart'. Fixed also the behavior when disabling 'start_async_after_grab_async'.
    • Improved description of parameter 'clear_buffer'.
  • Revision 5.7 (Jan 31, 2014):
    • Added new HDevelop example gigevision_flir_ax5.hdev that shows how to use a FLIR AX5 GigE thermal imaging camera.
    • Fixed bug in 'available_param_descriptions'.
    • Updated underlying GigE Vision transport layer (GTL) to v1.0.6.11 to fix a deadlock situation with the socket driver and continuous grabbing. Note that the filter driver is still at v1.0.6.7
    • Fixed documentation of the Generic parameter GtlNumBuffers. The minimum value is 1.
    • Fixed bug in get_framegrabber_callback. In case of other callbacks than 'transfer_end' wrong return values were returned.
    • Fixed bug in close_framegrabber. Active driver-specific callbacks are now unregistered automatically.
    • Fixed bug when opening cameras with full resolution. Previously this could lead to an exception stating the XML is wrong because it was tried to set some resolution related parameters without checking if they are writeable.
  • Revision 5.6 (Jul 9, 2013):
    • Fixed handling of device-specific events. Now also events with hexadecimal event IDs are supported.
    • Fixed crash regarding the use of an unsupported callback type.
    • Updated underlying GigE Vision transport layer (GTL) to v1.0.6.10 to support the transfer_end callback also for WoW64. Note that the used filter and socket driver versions are unchanged.
    • Fixed bug in open_framegrabber in case of 'Generic' parameter with empty tuple values.
  • Revision 5.5 (Jun 14, 2013):
    • Fixed a crash when having more than one device open, closing the first one and then calling info_framegrabber with parameter 'info_boards' or 'device'.
    • Fixed a crash when accessing the parameter 'GtlDeviceRegister_#addr_#len' after the GenICam XML file could not be loaded correctly.
    • Fixed a bug which caused incorrect information about lost devices when calling info_framegrabber with parameter 'info_boards' or 'device'. To avoid wrong information lost devices are not listed anymore at all (but you will get a low-level warning if switched on). You need to call close_framegrabber for the specific AcqHandle to be sure the resources are cleaned up before being able to list or access the device again.
    • Added gateway and timeout to the documentation of ForceIP.
    • Improved documentation of parameter 'clear_buffer'.
    • Updated underlying GigE Vision transport layer (GTL) to v1.0.6.9 which shares the device information between all instances. This allows to detect lost devices correctly. Note that the used filter and socket driver versions are unchanged.
  • Revision 5.4 (May 24, 2013):
    • Added functionality to get notified in case of the occurrence of a 'transfer_end', 'device_lost' and 'callback_queue_overflow' callback type via user-specific callbacks.
    • Added parameters 'num_queued_callbacks', 'do_flush_callback_queue' and 'max_num_queued_callbacks'.
    • Added functionality to decouple the internal callback notifications. The callbacks are now sequentially processed by an internal callback queue.
  • Revision 5.3 (Apr 26, 2013):
    • Minimum number of buffers has been changed from 2 to 1 to allow receiving only the newest images without the need to flush buffers (GtlBufferHandlingMode='2').
    • Improved internal handling of parameters while grabbing, to enable some cameras to reach the full frame rate.
    • Enhanced free IP address suggestion on Mac OS X; on Windows now ICMP packets are used to determine free addresses to avoid problems with the Windows neighborhood cache.
    • Updated underlying GigE Vision transport layer (GTL) to v1.0.6.8 which allows broadcast discovery also on Mac OS X, supports a packet size (MTU) > 14k, improves the detection of test packets and flushes the operating system's input buffers before starting a new acquisition to avoid problems with old images. Note that the used filter and socket driver versions are unchanged.
    • Fixed 'do_flush_buffers' handling, to avoid a possible a crash.
    • Fixed handling of parameter 'CameraType' in open_framegrabber to avoid a crash, when the length of the filename was less than 4 characters.
    • Fixed a bug which led to wrong error handling in case of problems while acquiring images.
    • Improved example gigevision_photonfocus3d_objectmodel3d.hdev. Now the procedure 'detect_laser_line_procedure' also returns a laser line XLD. Moreover, if a laser line XLD is available, it will be displayed.
    • Corrected documentation of the 'generic' parameter.
  • Revision 5.2 (Oct 22, 2012):
    • Added internal GenApi callbacks for the parameters 'Width', 'Height', 'PayloadSize', 'AcquisitionMode' to enable automatic adaption when these are invalidated by changes to other nodes.
    • Added new example gigevision_atc4_objectmodel3d.hdev that shows how to acquire and visualize 3D data from an Automation Technology C4 sensor.
    • Added new example gigevision_photonfocus3d_objectmodel3d.hdev that shows how to acquire and visualize 3D data from a Photonfocus 3D sensor.
  • Revision 5.1 (Jul 11, 2012):
    • Updated GenApi to v2.3.1. Please note that therefore also the genicam directory of your HALCON installation will be updated.
    • Updated the underlying interface-specific GigE Vision transport layer (GTL) to v1.0.6.7. This fixes a problem with sockets which were not closed properly and a problem on 32 bit systems which could lead to lost buffers in rare cases.
    • Updated the filter driver to v1.0.6.7. This version has no functional changes compared to version v1.0.6.6, therefore existing installations do not need to install the updated filter driver. Version v1.0.6.7 fixes the problem that v1.0.6.6 was not timestamped when signing the driver and therefore cannot be installed on systems which verify the signature after 2013-02-10.
  • Revision 5.0 (May 15, 2012):
    • HALCON 11 version of the interface (included in HALCON 11 DVD).
    • Added support for Mac OS X 10.7.
    • Use of GenApi v2.3.
    • Added support for static link aggregation to filter driver, see also new HDevelop example program gigevision_link_aggregation.hdev.
    • Added new parameters 'do_flush_buffers', 'GtlGVSPResendWait', 'GtlGVSPPacketTimeout', and 'GtlGVSPResendsRequested'.
    • Renamed parameter 'GtlReceivedPackets' to 'GtlGVSPReceivedPackets'.
    • Fixed URL parsing and handling.
    • The interface now returns H_ERR_FGDEVLOST (5335) when the device is lost also for grab_image_async and set_framegrabber_param or get_framegrabber_param.
    • Fixed bug in unregistering callbacks via set_framegrabber_callback. Now, the function returns also further low-level errors.
    • Updated the underlying interface-specific GigE Vision transport layer (GTL) and the filter driver to v1.0.6.6.
    • Disabled support for older filter drivers due to binary incompatibility.
    • Handle oversized packets and vendor-specific status codes correctly.
    • Fixed wrong resend requests in case a device does not support resends.
    • Fixed wrong resend requests for outdated buffers.
  • Revision 4.8 (Nov 21, 2011):
    • Updated version of filter driver and socket driver to v1.0.6.4, to fix a problem which resulted in lost images especially when occasionally packets are delayed, e.g. using line scan cameras. Please note that you need to update the filter driver by hand to enable it.
    • Added notes about missing filter driver to troubleshooting section.
    • Corrected documentation of parameter 'callback_timeout'.
    • Fixed problem with HALCON image size, after BinningHorizontal, BinningVertical, DecimacitionHorizontal or DecimationVertical has been set.
    • Fixed color conversion of >8 bit/pixel Bayer formats, which could also lead to a crash.
    • Fixed incorrect color conversion of grayscale to YUV color formats.
    • Corrected wrong default setting of parameter 'clear_buffer' on Linux.
  • Revision 4.7 (May 30, 2011):
    • Fixed a bug in the Windows filter driver which caused a crash when the number of packets for one block increased after opening the device.
    • Starting with this version (v1.0.6.2), the HALCON GigE Vision Streaming Filter under Windows can only be enabled by an interface revision which is new enough. Please use the parameter 'GtlAcquisitionEngine' to check if the filter driver is actually enabled.
  • Revision 4.6 (Apr 14, 2011):
    • Improved the filter driver and adapted the documentation:
      • Support of WoW64, i.e., 32 bit applications on Windows x64 Editions can use the filter driver.
      • Better performance and stability especially in the resend case.
      • Better compatibility to foreign filter drivers.
    • Fixed bug in unregistering callbacks via set_framegrabber_callback. Now, the function returns an error if the user unregisters a callback that was not registered before.
    • Fixed a crash when 'image_width' and 'image_height' have not been adapted correctly in case the image dimensions have been changed implicitly.
    • Relaxed strict checking of the assigned CCP register value so even devices which do not use this register correctly can be opened.
    • The generic parameter 'GtlDisableAutomaticTestPackets' was sometimes spelled wrong. This has been fixed.
    • Fixed a problem with the filter driver when the parameter 'grab_timeout' was set to -1 (infinite).
    • Removed reference to generic parameter 'GevSCPSPacketSize'.
    • Reviewed and adapted documentation.
  • Revision 4.5 (Sep 8, 2010):
    • Adapted to GenICam version 2.1.
    • Added the HALCON GigE Vision Streaming Filter also for Windows x64.
    • Added support of peripheral (non-streaming) GigE Vision devices (e.g., a strobe light controller or a trigger box) according to the GigE Vision 1.2 standard. Note that these devices do not support image acquisition, so calling grab_image or grab_image_async returns an error.
    • Added functionality to get notified in case of any available device-specific event via user-specific callbacks.
    • Added functionality to ensure that also the filter driver supports all parameters, in particular those regarding resending and buffer handling mode.
    • Added read-only parameters 'GtlUseCameraPacketSize', 'GtlDisableAutomaticTestPackets', 'GtlNumBuffers', and 'GtlForceSocketDriver' to get_framegrabber_param.
    • Fixed problem with filter driver and parameter 'grab_timeout', which always returned an error if set to -1 (infinite).
    • Fixed memory leak when using the filter driver. The memory of the old buffers was not released, when the image dimensions had been changed.
    • Fixed asynchronous cancellation of a grab with the parameter 'do_abort_grab' when using the filter driver.
    • Corrected the returned error message, if a timeout occurs while grabbing images.
    • Corrected the return value of the parameter 'image_available'.
    • Corrected unit in description of parameter 'GtlBufferTimestamp'.
    • Corrected documentation of parameter 'GtlBufferHandlingMode'.
    • Changed syntax of generic parameter 'GtlForceSocketDriver', which now needs to be set to a value.
    • HALCON 10 version of the interface (included in HALCON 10 DVD).
  • Revision 4.4 (Mar 18, 2010):
    • Moved initialization of GenApi to open_framegrabber and optimized it.
    • Increased limit of GtlNumBuffers from 1000 to 65535.
    • Renamed the environment variable HALCONGEV_USE_EXTERNAL_GENAPI to HALCON_USE_EXTERNAL_GENAPI.
    • Updated the underlying interface-specific GigE Vision transport layer (GTL) to v1.0.4.1.
    • Updated filter driver to v1.0.0.2 to fix a bug which could lead to a system crash when increasing the payload size. Note that the filter driver has to be (re-)installed separately, see here for more details.
    • Fixed bug in open_framegrabber for reconnecting a previously lost device when using multiple cameras.
    • Corrected return values of info_framegrabber(.., 'generic', ...).
  • Revision 4.3 (Feb 15, 2010):
    • Updated the underlying interface-specific GigE Vision transport layer (GTL) to v1.0.4. This includes a new acquisition engine, which enables the use of the new HALCON GigE Vision Streaming Filter driver and initializes the GVSP streaming channel, when opening the device to speed up grab_image[_async].
    • Updated the underlying GenICam installation from 1.1.2 to 2.0.1.
    • Improved the robustness of the device discovery:
      • The timeout has been adjusted to one second as stated in the GEV specification. Additionally, it depends on the current GVCP timeout.
      • To speed up the device discovery, especially if there are multiple network interfaces installed, it is now done in parallel on all interfaces.
      • Fixed discovery of devices with a DeviceUserID set to an empty string or with very long DeviceManufacturerName or DeviceModelName strings.
    • Changed info_framegrabber(..., 'info_boards', ...):
      • Introduced new order of output.
      • Parameter 'user_name' is only displayed if not empty.
      • Added parameters 'netmask', 'gateway', 'mac_address', 'ip_config_current', 'interface_ip_address', 'version', 'serial', 'gev_version', 'status', and 'suggestion'.
      • Parameter 'suggestion' specifies a suggestion for the Generic parameter in open_framegrabber, which can be used to force a valid IP address of the device, when 'status:misconfigured' indicates the device uses an invalid network configuration.
        It is tried up to 254 times to assign a random IP address in the valid IP range for the network interface. If this does not succeed, the possible range instead of a single address is returned: GtlForceIP=mac, IPAddr1-IPAddrN/Netmaskbits.
        Attention: It might be necessary to ask your system administrator for a free IP address!
    • Added new paragraphs in this documentation: 'HALCON GigE Vision Streaming Filter', 'GenICam', and 'Using Multiple Cameras'.
    • More robust detection of maximum possible packet size: GenApi now gets notified, when the packet size has been changed directly by GTL, i.e., the corresponding parameter value (which is queried by GenApi) is correct now.
    • More robust detection of maximum image width and height when opening a device.
    • Enabled the use of the additional acquisition mode 'MultiFrame'.
    • Added new parameters: GtlDeviceRegister_#addr_#len, GenApiCNodeMapRefPtr, GtlPortPtr and GtlForceSocketDriver
    • Added new suffixes to get GenApi properties: '_longdescription', '_type', '_displayname'.
    • Fixed problem with ForceIP, which sometimes returned an error, even if it worked correctly.
    • Fixed handling of compressed device XML files. Some files didn't work correctly.
    • Fixed handling of GenApi parameters with an underscore ('_') in the name.
    • Fixed problem with setting of signed 32 bit values in unsigned 32 bit registers (did not happen on 64 bit architectures).
    • Fixed code used for debayering of input images with image width smaller than 8 pixels.
    • Enhanced low-level error messages when open_framegrabber fails.
    • Adapted the category of GTL-specific transport layer parameters: Now these parameters are included in the same category as the GenApi parameter 'PayloadSize'. This should be 'GigE Vision Transport Layer', but depending on the quality of some device XML files this might be different.
  • Revision 4.2 (Jun 15, 2009):
    • Updated underlying GenApi installation from 1.1 to 1.1.2. Important notice for Linux: Under Linux, the file system layout has been adapted to the official one, i.e., the library files have been moved to ${GENICAM_ROOT_V1_1}/lib and ${GENICAM_ROOT_V1_1}/lib64, respectively. For using this new version, you have to adapt your search library path ${LD_LIBRARY_PATH} accordingly, see also the updated System Requirements section.
    • More verbose low-level error message ("error: wrong alignment") for wrong alignment of GEV registers. Note that misaligned access is not allowed by the GEV specification.
    • Adjusted limit for automatic Width and Height adaption from 4096 to 16000 to better support area scan cameras with sensor resolution greater than 4096 pixel in width or height.
    • Fixed problem in RGB10/12/16_PACKED color conversion.
    • Fixed unintended behavior in software cropping, i.e., by default the resulting HALCON image now has the same size as specified by the GigE Vision parameters Width, Height, OffsetX, and OffsetY.
  • Revision 4.1 (Feb 10, 2009):
    • Added support of AcquisitionMode 'SingleFrame'.
    • Added handling of custom pixel formats. The application has to deal with these formats on its own.
    • Added parameter 'GtlDeviceUniqueName' to query the unique name of the current device.
    • Changed name of the XML file name to the unique device name, if the button 'do_write_xml_file' in the HDevelop Image Acquisition Assistant is used.
    • Changed default settings of horizontal and vertical resolution from full resolution (1) to current camera settings (0). This doesn't affect the HDevelop Image Acquisition Assistant.
    • Changed valid values for parameter 'GtlGVCPRetries' to avoid losing the communication to the device. Setting the value to 0 is not possible anymore.
    • Changed behavior of open_framegrabber. If opening a device with full resolution fails, it is retried to open it with the current resolution of the device.
    • Changed status of the Generic parameters 'GevSCPSPacketSize', 'GtlUseCameraPacketSize', and 'GtlDisableAutomaticTestPackets' used in open_framegrabber to deprecated. These parameters should be set via set_framegrabber_param after initializing the camera.
    • Improved parameter 'do_abort_grab' to avoid deadlocks in multi-threaded applications.
    • Improved color conversion for BayerXX8 to RGBXX8.
    • Fixed race condition under Windows, which could prevent GTL from receiving images and led to timeouts.
    • Corrected error codes for unknown parameters and grab timeout.
  • Revision 4.0 (Dec 10, 2008):
    • HALCON 9.0 version of the interface (included in HALCON 9.0 DVD). Note that the installation from the HALCON 9.0 DVD already installs the necessary GenApi runtime package, adapts the environment variables accordingly, and for Windows and Windows x64 also installs the required Visual Studio C++ 2005 SP1 Redistributable Runtime.
    • Changed unit of parameter 'GtlBlockTimeout' from nanoseconds into microseconds.
    • Added support for Windows x64.
    • Slightly improved performance under Windows.
    • Added default values if mandatory features are not in XML file.
    • Added support of write-only parameters in the HDevelop Image Acquisition Assistant.
    • Added new return value H_ERR_FGDEVLOST (5335) in case of the device is lost.
    • Fixed bug in broadcast device discovery if more than one NIC is used.
    • Fixed bug in close_framegrabber if camera got lost.
    • Fixed loss of the settings of some stream parameters. Now they are persistent.
    • Fixed problem opening multiple devices, if some cannot be opened.
    • Fixed timeout in case of initial block ID was bigger than 32767.
    • Fixed problem with long device strings.
    • Fixed buffer lossage in case of device errors after successfully grabbing an image.
    • Fixed wrong values of parameter 'GtlGVSPResends'.
    • Removed parameters with visibility 'invisible' from the parameters in the HDevelop Image Acquisition Assistant.
    • Improved automatic detection of packet size.
    • Improved precision of parameter 'grab_timeout' through new pthreadVC2.dll.
    • Improved low-level error messages.
    • Increased priority of the receive thread on Windows.
  • Revision 3.2 (Sep 30, 2008):
    • Added parameters 'GevPersistentIPAddress', 'GevPersistentSubnetMask', 'GevPersistentDefaultGateway', 'GevCurrentIPConfigurationDHCP', 'GevCurrentIPConfigurationPersistent', 'GevSupportedIPConfigurationDHCP', and 'GevSupportedIPConfigurationPersistentIP' to support persistent IP configurations.
    • Added parameter 'GtlBlockTimeout'.
    • Added parameter 'GtlBufferHandlingMode' to support additional buffer handling modes.
    • Added timeout and improved functionality for parameter 'GtlForceIP'.
    • Added broadcast discovery and additional information (IP address, MAC address, user name, unique name) to info_framegrabber(..., 'info_boards', ...).
    • Added automatic checking for firewall on Windows XP.
    • On Linux operating systems, the receive thread now uses a slightly higher priority, if the application runs with real-time scheduling policy.
    • Fixed bug in parameter 'clear_buffer', which had cleared only part of the buffer.
    • Fixed bug in setting parameters 'GtlGVCPRetries', 'GtlGVCPTimeout', 'GtlGVSPInterpacketDelay', and 'GtlGVSPResends'.
    • Fixed bug in parameters 'GtlBufferTimestamp' and 'GtlBlockID' to get always the correct values of the current buffer.
    • Fixed bug in parameter 'grab_timeout'. Now the value -1 stands for infinite.
    • info_framegrabber(..., 'info_boards', ...) now returns only the DeviceUserID, if it is unique. In case of multiple devices with the same DeviceUserID, only the first device is listed with the DeviceUserID. The other devices are shown by the default name of gtl.
    • Changed visibility of parameters 'GtlGVSPPacketSize', 'GtlGVSPResends', and 'GtlGVSPInterpacketDelay' from 'Beginner' to 'Expert'.
    • Adapted low level error messages in open_framegrabber.
  • Revision 3.1 (Jul 24, 2008):
    • Added dynamically setting of transport layer-related parameters like PixelFormat, Width, and Height.
    • Added support of more pixel formats and therefore changed behavior of ColorSpace and BitsPerChannel in open_framegrabber. Be aware that the image will be transformed automatically according to the settings of the camera (PixelFormat) and the desired HALCON image format (ColorSpace and BitsPerChannel).
    • Added default values for parameters BitsPerChannel and ColorSpace in open_framegrabber.
    • Added parameters 'bits_per_channel' and 'color_space' to enable the dynamically setting of the desired HALCON image format.
    • Added new value 0 for Horizontal/VerticalResolution in open_framegrabber to allow opening the camera without explicit setting of Width and Height.
    • Added parameters 'image_height', 'image_width', 'start_column', and 'start_row' to support software cropping.
    • Added automatic packet size optimization, i.e., depending on the current MTU setting of the network adapter, the interface by default tries to find a maximum suitable packet size via requesting test packets from the camera. Note that this procedure which might take some time is performed only for the first grab after adjusting any parameter which involves changing the buffer size. See also the parameters 'GtlUseCameraPacketSize' and 'GtlDisableAutomaticTestPackets' in the Generic parameter of open_framegrabber,
    • Added parameters 'GtlFileName' and 'GtlPathName'.
    • Added parameter 'delay_after_stop'.
    • Added parameters 'GtlDiscardIncompletBuffers', 'clear_buffer', and 'GtlIncompleteBuffers' to improve the buffer handling.
    • Added parameter 'GtlGVSPInterpacketDelay' to control the packet transmission in more detail.
    • Added parameter 'do_write_xml' to save the XML description file.
    • Changed usage of parameter Generic in open_framegrabber and added additional values 'GtlForceIP', 'GtlGVCPRetries', 'GtlGVCPTimeout', 'GtlUseCameraPacketSize, and 'GtlDisableAutomaticTestPackets'.
    • Changed names of parameters consistent to GenICam Standard Feature Naming Convention and GigE Vision specification. Thus, the names of the parameters 'gvcp_retries', 'gvcp_timeout', 'gvsp_resends', and 'packet_size have been renamed to 'GtlGVCPRetries', 'GtlGVCPTimeout', 'GtlGVSPResends', and 'GevSCPSPacketSize'. Furthermore, most read-only parameters have been renamed. The categories of all parameters have also been adapted accordingly.
    • Changed name of the devices to (MACaddress_manufacturer_camera model). Furthermore, also the MAC address only or the UserDeviceId can be used to specify the desired camera.
    • Default setting of the parameter 'GtlGVCPTimeout' has been changed from 200000µs to 400000µs.
    • Improved resend mechanism and enhanced stability.
    • Fixed bug in info_framegrabber regarding device detection if the camera is already opened.
    • Fixed bug regarding the stream parameters. If the stream was closed and reopened their value was lost.
    • Fixed bug in parameter 'grab_timeout'. Furthermore, the parameter 'grab_timeout' now supports also the value -1 (infinite timeout).
    • Fixed bug in parameter 'image_available'.
    • Fixed bug in parameter 'volatile', which allows only PixelFormats with correct pixel alignment.
    • Fixed bug in setting of parameters 'OffsetX' and 'OffsetY'.
    • Added check for maximum Width and Height in case of full resolution.
    • The parameters 'GtlInterfaceID' and 'GevCurrentIPAddress' now return the IP address and the ID of the current (not the first) interface.
  • Revision 3.0 (Apr 24, 2008):
    • First official release.