HALCON 8.0: Image Acquisition Interface for GigE Vision compliant cameras
This page provides the documentation of the universal HALCON GigEVision interface for accessing all GigE Vision compliant cameras. Registered customers can download the latest revision of this interface from the MVTec WWW server.
Revision: 3.0
System Requirements
- Intel compatible PC with Windows XP/Vista or Linux x86/x86_64 with kernel 2.6 (or higher).
- Gigabit Ethernet network adapter. It is recommended to use a PCIe network adapter which supports Jumbo frames. Please configure the network adapter accordingly, e.g., to a value of 9000. Furthermore, the camera should be connected directly to the network adapter to avoid interference with other network traffic.
- If you are using a firewall please make sure that your firewall settings allow to connect to the camera and to receive incoming images, otherwise the grabbing will fail.
- Windows: Visual Studio C++ 2005 Runtime Package, particularly msvcp80.dll and msvcr80.dll.
-
GenApi version 1.1. The corresponding files are part of the
HALCON GigEVision package and should be located in the directory
genicam within the HALCON base directory %HALCONROOT%.
For using GenApi 1.1 the environment variable
GENICAM_ROOT_V1_1 must be set to
%HALCONROOT%\genicam.
Windows: Please make sure that %GENICAM_ROOT_V1_1%\bin\Win32_i86 is within the search path %PATH%.
Linux: Please add ${GENICAM_ROOT_V1_1}/lib/Linux32_i86 (or ${GENICAM_ROOT_V1_1}/lib/Linux64_i86, respectively) to your search library path ${LD_LIBRARY_PATH}. - Windows:
HALCON image acquisition interface hAcqGigEVision.dll or
parhAcqGigEVision.dll, respectively. Furthermore, the
DLL pthreadVC2.dll must be within your search path %PATH%.
If you have properly installed the interface, all these DLLs should reside
in bin\%HALCONARCH% within the HALCON base directory
%HALCONROOT% you have chosen during the installation of HALCON.
Linux: HALCON image acquisition interface hAcqGigEVision.so If you have properly installed the interface, the shared object should reside in lib\%HALCONARCH% within the HALCON base directory %HALCONROOT% you have chosen during the installation of HALCON.
Features
- User-space implementation of the GigE Vision protocol
- Grabbing from multiple cameras.
- Synchronous and asynchronous grabbing.
- Support of Jumbo frames.
- Software control of all generic camera parameters via GenApi.
- No Administrator or root privileges required.
Limitations
- Since the underlying GigE Vision driver is performed in user-space, the CPU load may reach higher values (especially under Windows) while grabbing images. If possible, use larger packet sizes (Jumbo frames) to decrease the CPU load.
- Each camera must be reachable within the network. Thus, it is recommended to assign the IP address of the camera either by using a persistent IP or by using DHCP.
- No dynamically setting of transport layer-related parameters like pixel format, and image size.
- Only support of Mono and raw pixel formats (no packed formats). In case of raw images you can use the HALCON operator cfa_to_rgb to decode the Bayer pattern.
- Only support of AcquisitionMode='Continuous'.
- No support of GigE Vision events and the message channel yet.
- No support of chunk data yet.
- grab_data and grab_data_async not supported.
Description
Parameters for open_framegrabber():
| Name | 'GigEVision' | The name of the HALCON interface. | |||
| HorizontalResolution | --- | Ignored. | |||
| VerticalResolution | --- | Ignored. | |||
| ImageWidth | 0, width | The width of the desired image part ('0' stands for the complete image). Default: 0. | |||
| ImageHeight | 0, height | The height of the desired image part ('0' stands for the complete image). Default: 0. | |||
| StartRow | 0, row | The row coordinate of the upper left pixel within the desired image part. Default: 0. | |||
| StartColumn | 0, column | The column coordinate of the upper left pixel within the desired image part. Default: 0. | |||
| Field | --- | Ignored. | |||
| BitsPerChannel | --- | Ignored. | |||
| ColorSpace | 'default', 'BayerRG8', 'BayerBG8', 'BayerGB8', 'BayerGR8', 'Mono8', 'Mono16' | Specify the desired color space and thus the number of image channels of the resulting HALCON image. If set to default, the color space currently set in the camera is used. Default: 'default'. | |||
| Generic | [packet_size (int), num_buffers (int)] |
By default, the used packet size is adjusted automatically depending
on the MTU setting of the network adapter (which should be
set to approx. 9000 by enabling Jumbo frames in the configuration
of the network adapter). To set the packet size manually,
you can specify this value in the Generic parameter. Furthermore,
you can also set the number of image buffers:
|
|||
| ExternalTrigger | --- | The external trigger in open_framegrabber is ignored. You can change these values with set_framegrabber_param via the generic trigger parameters. | |||
| CameraType | 'default', file | By default, the XML description file with the camera parameters is derived directly from the camera. Alternatively, you can specify the name of the XML camera description file directly, e.g., 'C:\\MyCameraDescription.xml'. Default: 'default'. | |||
| Device | 'default', device name | To open a specific camera the device name as shown in info_framegrabber('info_boards',...,...) has to be set. 'default' opens the first available camera. Default: 'default'. | |||
| Port | --- | Ignored. | |||
| LineIn | --- | Ignored. | |||
Parameters for set_framegrabber_param():
The parameters of the cameras are based on GenApi, so they can be
different for each camera. A call of get_framegrabber_param(..., 'available_param_names', ...)
returns a tuple containing all available parameters of the connected camera.
To read e.g. the current gain of the camera AcqHandle
refers to (after calling open_framegrabber), the user can call get_framegrabber_param(AcqHandle, 'GainRaw', Gain)
Additionally to the GenApi parameters of the camera, the following
HALCON parameters are supported:
| 'do_abort_grab' | --- | Abort the current image acquisition. | |||
| 'grab_timeout' | msec | Specify the desired timeout (milliseconds) for aborting a pending grab. Default: 5000. | |||
| 'gvcp_retries' | retries | Specify the number of retries for the current device, if reading/writing a register has failed. Default: 3. | |||
| 'gvcp_timeout' | timeout | Specify the timeout in µs for the current device, if a register does not answer. Default: 2000000. | |||
| 'gvsp_resends' | resends | Specify the number of resends for the current device, if a packet was lost or incomplete. Use 0 to disable the packet resend mechanism. Default: 5. | |||
| 'packet_size' | size | Specify the current packet size of the transport layer. Please note that the maximum value depends on the settings of your network card. For reaching optimal performance, Jumbo frames should be enabled. If setting the packet size is also supported via the XML file of the camera, please use the parameter of the XML file. | |||
| 'start_async_after_grab_async' | 'disable', 'enable' | By default, at the end of grab_image_async a new asynchronous grab command is automatically given to the acquisition device. If the parameter 'start_async_after_grab_async' is set to 'disable' this new grab command is omitted. Default: 'enable'. | |||
| 'volatile' | 'enable', 'disable' | Grayscale only. In the volatile mode the two image buffers are used directly to store HALCON images. This is the fastest mode avoiding to copy raw images in memory. However, be aware that older images are overwritten again and again as a side-effect. Thus, you can only process one image while you grab another image. Older images are invalid! Default: 'disable'. | |||
Parameters for get_framegrabber_param():
Additional parameters supported by get_framegrabber_param only. Note that all parameters supported by set_framegrabber_param except the ones with prefix 'do_' can also be accessed by get_framegrabber_param. Furthermore, corresponding to the parameters supported by set_framegrabber_param, there may exist additional read-only parameters with the following postfixes:
- '_description': These parameters provide the tooltip of the corresponding parameter as a string.
- '_range': These parameters provide the minimum, maximum, stepwidth, and default values for the corresponding integer or float parameter as a tuple with 4 elements, e.g., get_framegrabber_param(..,'Shutter_range',..) will return the output tuple [min,max,step,default]. Optionally, this tuple can also contain additional valid string values like 'auto' or 'manual'.
- '_values': These parameters provide the valid value list for the corresponding parameter as a tuple, e.g., get_framegrabber_param(..,'volatile_values',..) will return the output tuple ['enable','disable'].
| 'available_param_descriptions' | descriptions | Returns a list containing additional information about all parameters. The order of the entries is equal to the order of the parameter names returned by 'available_param_names'. | |||
| 'available_param_names' | parameters | Returns a list containing the names of all available parameters. | |||
| 'buffer_timestamp' | timestamp | Returns the timestamp of the current buffer in µs. | |||
| 'device_id' | id | Returns the ID of the current device. | |||
| 'device_ip' | ip | Returns the IP address of the current device. | |||
| 'device_mac' | mac | Returns the MAC address of the current device. | |||
| 'device_manufacturer' | manufacturer | Returns the name of the device manufacturer. | |||
| 'device_model' | model | Returns the model name of the current device. | |||
| 'device_serialnumber' | serialnumber | Returns the serialnumber of the current device. | |||
| 'frame_number' | frame | Returns the number of the last grabbed frame. If no buffer has been grabbed, -1 is returned. | |||
| 'image_available' | 0, 1 | Returns the status of the last asynchronous grab command. The value 1 means that the image is already acquired and thus can be fetched by grab_image_async without delay. | |||
| 'interface_id' | id | Returns the ID of the first interface. Please note that this doesn't has to be the one where the current device is connected. | |||
| 'interface_ip' | ip | Returns the IP address of the first interface. Please note that this doesn't has to be the one where the current device is connected. | |||
| 'port_manufacturer' | manufacturer | Returns the name of the port manufacturer. | |||
| 'port_model' | model | Returns the name of the port model. | |||
| 'port_module' | module | Returns the name of the port module. | |||
| 'port_version' | version | Returns the version number of the port. | |||
| 'revision' | revision | The revision number of the HALCON GigEVision interface. | |||
| 'stream_incomplete_frames' | incomplete frames | Returns the current number of incomplete frames received. | |||
| 'stream_received_packets' | packets | Returns the current number of packets received. | |||
| 'system_displayname' | displayname | Returns the displayname name of the system. | |||
| 'system_manufacturer' | manufacturer | Returns the name of the system manufacturer. | |||
| 'system_model' | model | Returns the model of the system. | |||
| 'system_tltype' | TL type | Returns the type of the system transport layer. | |||
| 'system_version' | version | Returns the version number of the system. | |||
Release Notes
-
Revision 3.0 (Apr 24, 2008):
- First official release.
