MVTec Software GmbH
  Building Vision For Business
Halcon

HALCON 8.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: 3.5

System Requirements

  • Intel compatible PC with Windows XP/Vista, Windows XP/Vista 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 value of 9000. Furthermore, the camera should be connected directly to the network adapter to avoid interference with other network traffic.
  • 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. Note: It is not sufficient to copy the missing files!
  • GenApi version 1.1. The corresponding files are part of the HALCON GigEVision package and should be located in the directory genicam within the HALCON base directory %HALCONROOT%. For using GenApi 1.1 the environment variable GENICAM_ROOT_V1_1 must be set to %HALCONROOT%\genicam.
    Windows: Please make sure that %GENICAM_ROOT_V1_1%\bin\Win32_i86 (or %GENICAM_ROOT_V1_1%\bin\Win64_x64, respectively) is within the search path %PATH%.
    Linux: Please add ${GENICAM_ROOT_V1_1}/lib (or ${GENICAM_ROOT_V1_1}/lib64, respectively) to your search library path ${LD_LIBRARY_PATH}.
  • Windows: HALCON image acquisition interface hAcqGigEVision.dll or parhAcqGigEVision.dll, respectively. Furthermore, the DLL pthreadVC2.dll must be within your 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. 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
  • Grabbing from multiple cameras.
  • Synchronous and asynchronous grabbing.
  • Support of Jumbo frames.
  • Software control of all generic camera parameters via 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

  • Since the underlying GigE Vision driver is performed in user-space, 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.
  • Only support of AcquisitionMode='Continuous' and 'SingleFrame'.
  • No support of BayerXXPacked, BGRXXPlanar, and RGBXXPlanar pixel formats yet.
  • No support of GigE Vision events and the message channel yet.
  • Only stream channel 0 supported yet.
  • No support of chunk data yet.
  • grab_data and grab_data_async not supported.

Custom PixelFormats

The HALCON GigEVision interface has a build-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 gets a pointer to the image data to access it 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.

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 '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 GenICam Standard Feature Naming Convention 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]'] 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 only use 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 the 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.
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.

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.
  • '_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'.
  • '_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.
'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.
'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.
'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.
'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).
  • 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 and GENICAM_ROOT_V1_1 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 3.5 (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 3.4 (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 3.3 (Dec 11, 2008):
    • 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 behaviour 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 2009, MVTec Software GmbH, corporate/legal/privacy information






Last modified: Mon Jun 15 10:14:51 CEST 2009