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.

• Intel compatible PC with Windows XP SP1/Vista/7, Windows XP x64/Vista x64/7 x64, also WoW64 (using 32-bit HALCON on 64-bit Windows), Linux x86/x86_64 with kernel 2.6 (or higher) , or Mac 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.
• 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 and the Microsoft Visual C++ 2005 Service Pack 1 Redistributable Package MFC Security Update for your system.
  Note: It is not sufficient to copy the missing files!
• HALCON GigE Vision Streaming Filter v1.0.6.7 under Windows x86, WoW64 or Windows x64: This version of the HALCON GigEVision interface automatically uses a filter driver to enhance the performance while streaming images. When installing HALCON 11.0 the filter driver will be automatically installed, if you enable the corresponding check box during installation. In all other cases, the filter driver needs to be installed manually as a service.
  Please make sure that at least the driver version v1.0.6.6 is actually installed (check your network properties). Older driver versions will not work!
• GenICam version 2.3.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_3, 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.
  Max 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'.

• User-space implementation of the GigE Vision protocol.
  For Windows 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 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.

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

• 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 11.0 the filter driver will be installed automatically, if you enable the corresponding check box during installation.
  In all other cases, the filter driver needs to be installed manually as a service. 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 or %HALCONROOT%\misc\drivers\win_xp_64, for all 32 bit or 64 bit Windows systems. 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 network interface properties.
  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 'HALCON 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. Furthermore, Windows XP will warn that the service is not properly signed, as it does not support Microsoft Authenticode. These warnings 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.

• This interface uses GenApi version 2.3.1, 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 _V2_3.
• 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.

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

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.

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.

In the HALCON GigEVision interface three different kinds of parameter types 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. 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 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 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 Interface'.

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:

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.

We recommend not to use the following parameters, because they are handled internally: 'AcquisitionStart', 'AcquisitionStop', and 'TLParamsLocked'.

All GenICam compliant devices contain a XML file, which describes the features of the device. The Standard Feature 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.

Not supported by this interface.

Not supported by this interface.

This interface supports device-specific events and driver-specific events via the operators set_framegrabber_callback and get_framegrabber_callback.

All actually supported callback types of the driver and of the specific image acquisition device can be queried by calling get_framegrabber_param with the parameter 'available_callback_types'. Once the callback is registered, on every occurrence of the callback (e.g., the notification that the exposure has finished) the specified callback function will be called. If the callback function is set to NULL, the corresponding callback will be unregistered. Please remember that in case of device-specific callback types, you have to activate and deactivate the underlying device-specific events via the GenApi.

Attention:To activate or deactivate the device-specific callbacks, the corresponding device-specific event has to be enabled or disabled. This means you have to set the GenApi parameter 'EventSelector' to the specific event type, and the 'EventNotification' parameter to 'GigEVisionEvent' (sometimes 'GenICamEvent') or 'On' depending on the 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 user-callback functions
Note that if the execution time of a user-specific callback function is faster than processing of the images, the internal used callback queue will increase if further callbacks are notified in the meantime. To get further information about the state of the internal callback queue, please see also the parameter 'num_queued_callbacks' and the callback type 'callback_queue_overflow'. The maximum of internal queued callbacks could be specified via the parameter 'max_num_queued_callbacks'.

The following static callback types are supported by any GigE Vision compliant camera:

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.

Starts a new asynchronous grab. See also grab_image_start.

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

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

Not supported by this interface.

Not supported by this interface.

This operator closes the device. See also close_framegrabber.

For this interface there are the following examples available:

• gigevision.hdev - Benchmark.
• gigevision_crop.hdev - Example for grabbing images with software and hardware image cropping.
• gigevision_forceip.hdev - Using ForceIP to correctly configure a misconfigured GigE Vision device.
• gigevision_frame_rate.hdev - Grabbing images from a GigE Vision compliant camera and determine the actual frame rate with full resolution.
• gigevision_link_aggregation.hdev - Show usage in combination with static link aggregation (LAG).
• 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_parameters.hdev - Lists all parameters of a device.
• gigevision_simple.hdev - A simple example to show the usage of the interface.

For this interfaces 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/.

For this interfaces 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\.

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

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