MVTec Software GmbH
  Building Vision For Business
Halcon

HALCON 9.0: Image Acquisition Interface for GigE Vision compliant cameras

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.

Revision: 4.3

System Requirements

  • Intel compatible PC with Windows XP SP1/Vista/7, Windows XP x64/Vista x64/7 x64, or Linux x86/x86_64 with kernel 2.6 (or higher).
  • 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. 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 to connect to the camera and to receive incoming images, otherwise the grabbing will fail.
  • Windows: Visual Studio C++ 2005 SP1 Redistributable Runtime Package, particularly msvcp80.dll and msvcr80.dll. If this package is not installed please download and install it from the Microsoft Download Center for Windows x86 or Windows x64. In addition it might be necessary to install the Microsoft Visual C++ 2005 Service Pack 1 Redistributable Package ATL Security Update for your system.
    Note: It is not sufficient to copy the missing files!
  • Filter driver under Windows x86: This version of the HALCON GigEVision interface automatically uses a filter driver to enhance the performance while streaming images. Currently the filter driver needs to be installed manually as a service and is not available for Windows x64. See section Filter Driver for more details.
  • GenICam version 2.0.1. 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_0, PATH, LD_LIBRARY_PATH must be set or modified. Old variables referencing GenICam V1.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.
  • 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'.

Features

  • User-space implementation of the GigE Vision protocol.
    For Windows x86 the HALCON 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.
  • 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.
  • Support of ForceIP.
  • Automatic packet size optimization.

Limitations

  • The HALCON GigE Vision Streaming Filter is only available for Windows x86. For more details see paragraph HALCON GigE Vision Streaming Filter.
  • Only acquisition modes 'Continuous', 'SingleFrame' and 'MultiFrame' are supported.
  • No support of BayerXXPacked, BGRXXPlanar, and RGBXXPlanar pixel formats yet.
  • Only stream channel 0 supported.
  • No support of GigE Vision events and the message channel yet.
  • grab_data and grab_data_async (and therefore chunk data) not yet supported.

HALCON GigE Vision Streaming Filter

  • For Windows x86 a so called 'filter driver' is available. It is used automatically, if it is installed and activated. This kernel mode driver enhances the performance.
  • Installation:
    Currently the filter driver needs to be installed manually. To do this close all your network connections and log in as administrator. Now open your network connections (Windows XP: Start -> Settings; Windows 7: Start -> Control Panel -> Network and Internet -> Network and Sharing Center -> Change adapter settings), right-click an interface and select the interface and select the properties. Then click install and add a service. Select 'Have Disk' and browse to %HALCONROOT%\misc\drivers\win_xp_32. Select the hgevstrm.inf file and follow the instructions. This will install and enable the filter on all your Ethernet interfaces.
    To disable the filter for a specific interface, you can deselect the 'HALCON GigE Vision Streaming Filter' in the interface properties.
  • Note that the filter driver is officially signed, but not WHQL-certified, i.e., the installation will warn that the driver is not Windows logo certified. Furthermore, Windows XP will warn that the service is not properly signed. These warnings can be safely ignored.
  • Currently, the filter driver does not support all parameters of the userspace driver, especially those regarding resending and buffer handling mode.
  • 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, so the CPU load may reach higher values (especially under Windows) while grabbing images. If possible, use larger packet sizes (Jumbo frames) to decrease the CPU load.

GenICam

  • This interface uses GenICam version 2.0.1, for more detail 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 HALCONGEV_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.
  • 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 _V2_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 on your own risk! When using GenApi and device port pointer 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 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 of custom pixel formats a compatible BitsPerChannel value and a ColorSpace with value 'raw' were set. If no BitsPerChannel value according to the current PixelFormat can be determined, the fallback value is 8. The resulting HALCON image might look incorrect. Finally, the user can then call get_image_pointer1 to access the image data for further processing.

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.

Naming of the parameters

In the HALCON GigEVision interface three different types of parameter names exist:

  • 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.
  • GTL parameters are provided by the HALCON 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 Standard Feature Naming Convention (SFNC) this should be 'GigE Vision Transport Layer'.
    If an important parameter is not present in the XML file, a GTL parameter with the same name, as described in the SFNC, is used, otherwise only the parameter of the XML file is visible.
  • 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.

Description

Parameters for open_framegrabber():


Name
'GigEVision'
The name of the HALCON interface.
HorizontalResolution 0, 1, 2, 4, resolution 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 as 16000 or smaller as 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.
Default: 0.
VerticalResolution 0, 1, 2, 4, resolution 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.
Default: 0.
ImageWidth 0, width The 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. Default: 0.
ImageHeight 0, height The 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. Default: 0.
StartRow 0, row The row coordinate of the upper left pixel within the desired image part. If this value is not set, the interface assumes the user always wants to get the maximum possible image offset. Default: 0.
StartColumn 0, column The column coordinate of the upper left pixel within the desired image part. If this value is not set, the interface assumes the user always wants to get the maximum possible image offset. Default: 0.
Field --- Ignored.
BitsPerChannel -1, 8, 10, 12, 14, 16 The number of significant bits per channel of the resulting HALCON image. In case of -1 the bit depth of the current PixelFormat is used. Default: -1.
ColorSpace 'default', 'gray', 'raw', 'rgb', 'yuv' 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'. Default: 'default'.
Generic ['GevSCPSPacketSize=size', 'GtlNumBuffers=number', 'GtlGVCPRetries=number', 'GtlGVCPTimeout=timeout, 'GtlUseCameraPacketSize=number', 'GtlDisableAutomaticTestPacket=state, 'GtlForceIP=MAC,IP/mask[,gateway,timeout]', 'GtlForceSocketDriver'] 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=003242d4,192.168.0.12/24'] sets the GtlGVCPTimeout to 200 ms and the device with the MAC address 00:32:42:D4 to IP 192.168.0.12 with a subnet mask of 24 byte, which is equal to 255.255.255.0.
The following parameters are available:
  • GevSCPSPacketSize (deprecated)
    By default, the used packet size is adjusted automatically depending on the MTU setting of the network adapter (which should be set to approx. 9000 by enabling Jumbo frames in the configuration of the network adapter). Please note that jumbo frames should be enabled to reach optimal performance. Note that you can use only packet size values > 1500, if the camera supports such values and all underlying network components support Jumbo frames and are configured appropriately.
  • GtlNumBuffers
    To set the maximum number of buffers used in the HALCON acquisition interface a value between 1 and 1000 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.
  • GtlDisableAutomaticTestPacket
    By default, GTL automatically sends a test packet to determine the optimal packet size. If this parameter is set to 1, sending of the test packet is disabled.
  • 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. Optionally, a gateway and a timeout for ForceIP can also be defined. 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 can be set with decimal numbers separated by dots. Also a timeout (in microseconds) for the ForceIP command can be set optionally.
  • GtlForceSocketDriver
    If this option is set then the camera uses the socket driver and does not automatically use the filter driver if it is available.
ExternalTrigger --- Ignored. You can change these values with set_framegrabber_param via the generic trigger parameters of the camera.
CameraType 'default', xml_filename 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'. Default: 'default'.
Device 'default', device_name 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. Default: 'default'.
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(AcqHandle, 'GainRaw', Gain).
Additionally to the GenApi parameters of the camera, the following HALCON and GTL (GigE Vision Transport Layer) parameters are supported:


'bits_per_channel'
-1, 8, 10, 12, 14, 16
The number of significant bits per channel.
'clear_buffer' 'disable', 'enable' If enabled each buffer is cleared before re-queueing (set to 0xF0 for 8 bit images and shifted for other bit depths). This parameter is useful in combination with the parameter 'GtlDiscardIncompleteBuffers'. Default: 'disable'.
'color_space' 'default', 'gray', 'raw', 'rgb', 'yuv' Sets the desired color space of the resulting HALCON image.
'delay_after_stop' msec Specify the time to wait (in milliseconds) between calling AcquisitionStop and stopping the transport layer. The optimal value depends on the camera. Default: 50.
'do_abort_grab' --- Aborts the current image acquisition and unlocks parameters, which are locked according to the status of the transport layer.
'do_write_xml_file' file_name 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.
'grab_timeout' msec Specify the desired timeout (milliseconds) for aborting a pending grab. If -1 is specified, the timeout is set to INFINITE. Default: 5000.
'image_height' 0, min ... max Sets the 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 Sets the 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.
'start_async_after_grab_async' 'disable', 'enable' By default, at the end of grab_image_async a new asynchronous grab command is automatically given to the acquisition device. If the parameter 'start_async_after_grab_async' is set to 'disable', this new grab command is omitted. Default: 'enable'.
'start_column' 0 ... max Sets the 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 Sets the 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' 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. Default: 'disable'.
'GevCurrentIPConfigurationDHCP' 0, 1 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 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 GevPersistentGateway). Note that many cameras already provide this parameter directly via GenApi.
'GevPersistentGateway' gateway 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 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 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 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.
'GtlBlockTimeout' usec Specify the timeout in microseconds 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. Default: at least one scheduling period + estimated transfer time.
'GtlBufferHandlingMode' '1', '2' 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, they 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 newest acquired image from the output buffer queue. This mode ensures that the application can always process the newest image.
Default: '1'.
'GtlGVCPRetries' num_retries Specify the number of retries for the current device, if reading/writing a register has failed. Default: 3.
'GtlGVCPTimeout' usec Specify the timeout in µs 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. Default: 400000.
'GtlGVSPDiscardIncompleteBuffers' 'disable', 'enable' 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'. Default: 'disable'.
'GtlGVSPDynamicPacketTrailer' 'disable', 'enable' 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. Default: 'disable'.
'GtlGVSPInterpacketDelay' nsec Sets the 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. Default: 0.
'GtlGVSPResends' num_resends Specify the 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. Default: 3.
'GtlDeviceRegister_#addr_#len' register_values 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 on 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!

Parameters for get_framegrabber_param():

Additional parameters supported by get_framegrabber_param only. Note that all parameters supported by set_framegrabber_param except the ones with prefix 'do_' can also be accessed by get_framegrabber_param. Furthermore, corresponding to the parameters supported by set_framegrabber_param, there may exist additional read-only parameters with the following postfixes:

  • '_access': These parameters provide the access permissions of the corresponding parameter as a string. Possible values are 'ro' (read-only), 'wo' (write-only), 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 default 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,default]. Optionally, this tuple can also contain additional valid string values like 'auto' or 'manual'.
  • '_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.


'available_param_descriptions'
descriptions
Returns 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 Returns a list containing the names of all available parameters.
'parameters_hidden' parameters Returns a list containing the names of all hidden parameters.
'image_available' 0, 1 Returns the 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.
'revision' revision The revision number of the HALCON GigEVision interface.
'DeviceID' device_id Returns the ID of the current device.
'DeviceModelName' model Returns the model name of the current device.
'DeviceVendorName' vendor Returns the name of the device vendor.
'GenApiCNodeMapRefPtr' pointer Returns a pointer to the GenApi node map of the device. Use on your own risk!
'GevCurrentIPAddress' ip_address Returns the IP address of the current interface.
'GevSupportedIPConfigurationDHCP' 0, 1 Returns 1, if IP configuration via DHCP is supported by the camera.
'GevSupportedIPConfigurationPersistent' 0, 1 Returns 1, if IP configuration via Persistent IP is supported by the camera.
'GtlAcquisitionEngine' driver_type Returns the 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 Returns the number of the last received buffer. If no image has been grabbed, -1 is returned.
'GtlBufferIncomplete' 0, 1 Returns the state of the current buffer. In case of an incomplete buffer 1 is returned.
'GtlBufferTimestamp' usec Returns the time stamp of the current buffer in µs.
'GtlCurrentIPAddress' ip_address Returns the IP address of the current device.
'GtlDeviceMACAddress' mac_address Returns the MAC address of the current device.
'GtlDeviceUniqueName' unique_name Returns the unique name of the current device.
'GtlDisplayName' display_name Returns the display name of the system.
'GtlFileName' file_name Returns the file name of the system.
'GtlInterfaceID' interface_id Returns the ID of the current interface.
'GtlIncompleteBuffers' num_incomplete Returns the current number of incomplete buffers received.
'GtlModelName' model_name Returns the model name of the system.
'GtlPathName' path_name Returns the path name of the system.
'GtlPortPtr' pointer Returns the pointer to the device port which enables direct device access. Use on your own risk!
'GtlReceivedPackets' num_packets Returns the current number of packets received.
'GtlSerialNumber' serial_number Returns the serial number of the current device.
'GtlTLType' tl_type Returns the type of the system transport layer.
'GtlVendorName' vendor Returns the name of the system vendor.
'GtlVersion' version Returns the version number of the system.

Troubleshooting

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

  • General:
    • Check if the camera has the latest firmware.
    • Check if the latest revision of the HALCON GigEVision Interface is used.
    • 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 the device (GVCP) and streaming data (GVSP). A incomplete configured firewall under Windows 7 will lead to the following low-level error: 'gtlOpenDevice failed - GVCP link error'.
  • 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): (only Windows) install Microsoft Visual C++ 2005 SP1 Redistributable Runtime Package. Note: It is not sufficient to add the two missing files (msvcp80.dll and msvcr80.dll) to your PATH!
    • Solution d): 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.
  • Only corrupted image received:
    • Reason: packets must be resent because of slow Ethernet cards, slow computers or slow bus.
    • Solution a): set GtlGVSPInterpacketDelay to a higher value.
    • Solution b): increase packet size (on network card and camera).
    • Solution c): reduce bus load from other applications or cameras.
  • Parameter is not writable 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.


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

Release Notes

  • 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 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 this 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 loosing 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 'GtlDisableAutomaticTestPacket' 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 actual 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 'GtlDisableAutomaticTestPacket' 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 'GtlDisableAutomaticTestPacket'.
    • 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 (MAC address_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.

© Copyright 2010, MVTec Software GmbH, corporate/legal/privacy information






Last modified: Fri Feb 19 10:43:53 CET 2010