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 current values for the corresponding integer or float parameter as a tuple with 4 elements, e.g., get_framegrabber_param(.., 'Shutter_range', ..) will return the output tuple [min, max, step, current].
• '_type': These parameters provide the type of the corresponding parameter as string.
• '_values': These parameters provide the valid value list for the corresponding parameter as a tuple, e.g., get_framegrabber_param(.., 'volatile_values', ..) will return the output tuple ['enable', 'disable'].
• '_visibility': These parameters provide the visibility of the corresponding parameter as a string. Possible values are 'beginner', 'expert', and 'guru'.

All these postfixed parameter names are not returned when calling info_framegrabber(.., 'parameters', ..) and are used to enable the easy parameterization via a generic graphical user interface, particularly the HDevelop Image Acquisition Assistant.

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 Features Naming Convention (available here) lists all features a device must or can have. Below you find the list of all mandatory features, which every device must support. Please note, that the value types and values are adapted to HALCON.

Not supported by this interface.

Not supported by this interface.

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

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

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

The signature of the callback function is Herror (__stdcall *HAcqCallback)(void *AcqHandle, void *Context, void *UserContext) for Windows operating systems. All other operating systems use their native calling convention instead of __stdcall.
The callback function uses the following parameters:

• AcqHandle Acquisition handle of the corresponding image acquisition instance.
• Context Optional context data of the specific callback. Reserved for future use and therefore it should be set to NULL.
• UserContext User context as set via set_framegrabber_callback.

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

The following driver-specific callback types are supported. In contrast to the device-specific callback types which are written in CamelCase these are written in lowercase letters and separated with an underscore.

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

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

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

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

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

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

• Used HALCON and acquisition interface versions.
• Low-level error message.
• Camera details.
• Details about network card (PCI, CardBus, Jumbo frames, link speed, ...).
• Details about network topology (directly connected, switches, ...).
• Details about computer system (laptop, workstation, CPU, ...). Please run the HDevelop example gigevision_information.hdev to gather information about the system and the camera configuration, and then attach the resulting files when requesting support.

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

• Pthreads-Win32 - used without modifications

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

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