 |
|
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:
- packet_size:
The desired packet size of the camera can be set by entering
a value greater or equal 500. Default setting uses the
maximum value of the network card. Please note that
jumbo frames should be enabled to reach optimal performance.
Note that you can only use packet
size values ≥ 1500 if the camera supports such values and all
underlying network components support Jumbo frames and are
configured appropriately.
- num_buffers:
To set the maximum number of buffers used in the HALCON acquisition
interface a value between 1 and 500 has to be set. Default: 5.
|
|
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'].
All these postfixed parameter names are not returned when calling
info_framegrabber(..,'parameters',..) and are used
to enable the easy parameterization via a generic graphical user
interface, particularly the HDevelop Image Acquisition Assistant.
|
'available_param_descriptions'
|
|
descriptions
|
|
Returns a list containing additional information about all parameters.
The order of the entries is equal to the order of the parameter names
returned by 'available_param_names'.
|
|
'available_param_names'
|
parameters
|
Returns a list containing the names of all available parameters.
|
|
'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):
|