HALCON 9.0: Image Acquisition Interface for GenICamTL compliant cameras

This page provides the documentation of the universal HALCON GenICamTL interface for accessing all GenICamTL compliant cameras. Registered customers can download the latest revision of this interface from the MVTec WWW server.

Revision: 4.4

System Requirements

• 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), or Linux x86/x86_64 with kernel 2.6 (or higher).
• Successfully installed GenICam GenTL Producer. The corresponding .cti file must be located in one of the directories specified by the environment variable GENICAM_GENTL32_PATH or GENICAM_GENTL64_PATH, respectively.
• Depending on the used transport layer make sure that you have access to the camera. Especially for Gigabit Ethernet the following points have to be checked:
  • 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. 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 to connect to the camera and to receive incoming images, otherwise the grabbing will fail.
• GenICam version 2.0.1. The corresponding files are part of the HALCON 9.0 runtime installation and are located in the directory genicam within the HALCON base directory %HALCONROOT%. Since the HALCON GenICamTL interface sets all necessary environment variables on its own, no environment variables like GENICAM_ROOT_V2_0, PATH, LD_LIBRARY_PATH must be set or modified. See section GenICam GenApi for more details.
• Windows: HALCON image acquisition interface hAcqGenICamTL.dll or hAcqGenICamTLxl.dll, respectively. 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 hAcqGenICamTL.so or hAcqGenICamTLxl.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.
• The current acquisition mode assumes the computer is fast enough to process all buffers from the camera. If this is not the case, they are silently discarded.

Features

• Implementation of a GenICam GenTL consumer.
• Grabbing from multiple cameras.
• Synchronous and asynchronous grabbing.
• Software control of all generic camera parameters using GenApi.
• Support of various pixel formats and flexible color transformation.
• Support of 'Continuous' and 'SingleFrame' acquisition modes.
• Support of callbacks for device-specific events.
• grab_data and grab_data_async (and therefore chunk data) supported.
• No Administrator or root privileges required.

Limitations

• No support of BayerXXPacked, BGRXXPlanar, and RGBXXPlanar pixel formats yet.
• Only stream channel 0 supported.
• When using multiple devices the same GenICam GenTL Producer has to be used for all devices.
• GenICam events are supported, but no event data.

GenICam GenApi

• This interface uses GenICam version 2.0.1, for more details refer to the GenICam homepage. The corresponding files are part of the HALCON runtime installation 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 GenICamTL 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 2.0 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.

GenICam GenTL

• GenTL works from the interaction between one or more GenTL Producers and a GenTL Consumer. The Producer provides the Consumer access to the hardware, e.g. a camera, so that it can be configured and send (image) data independent from the underlying transport technology. GenTL establishes only the communication from/to the device, the features have to be accessed via GenApi.
• The available GenICam GenTL Producers are searched within the path set by the environment variable GENICAM_GENTL32_PATH or GENICAM_GENTL64_PATH, respectively. If none of these variables is set, the interface searches the GenTL Producers in the directory $GENICAM_ROOT_V2_1/bin/<architecture>/TLIs.
• Currently, the HALCON GenIcamTL interface has a restriction when using more than one camera. If the streaming of the first opened camera has already been started when the second camera is opened, the parameter 'do_abort_grab' has to be called first to disable streaming. Otherwise you will get timeouts, when trying to grab images from the first camera.

Parameter Naming

In the HALCON GenICamTL image acquisition interface exist three different kinds of parameter types:

• Parameters of the acquisition device (Device)
  The parameters supported by the used acquisition device are hardware dependent and differ between each model. So each device contains an XML file, which describes the supported features. The names of the available parameters appear in HALCON in the same naming as in the XML file and always start with capital letters, e.g. 'PixelFormat'.They can be queried by get_framegrabber_param(...,'available_param_names',...). Additional information, e.g. about the valid values of a parameter, can be queried by the different suffixes as described below in section Parameters for get_framegrabber_param.
• Parameters of the GenTL modules (GenTL Producer)
  Each GenTL interface has a layered structure of five modules, which are the System Module, the Interface Module, the Device Module, the Stream Module, and the Buffer Module. The GenTL Producer provides also parameters for each module (except the Buffer Module). To distinguish the parameters of each module, the HALCON GenICamTL interface adds a prefix with the module name of the parameter in square brackets, e.g., '[Device]DeviceID' for the parameter 'DeviceID' of the Device Module.
  To use these parameters with get_framegrabber_param or set_framegrabber_param the prefix has to be used.
• Parameters of the HALCON interface (GenTL Consumer)
  All parameters described in this documentation are parameters provided by the HALCON interface. They use only lower-case letters separated by underscores, e.g., 'num_buffers'.
  Some of these parameters provide additional information about the Transport Layer or the used buffers, which is not delivered by the module parameters.

Custom Pixel Formats

The HALCON GenICamTL interface has a built-in converter from the pixel formats described in the GenICam Standard Feature Naming Convention to the desired HALCON image format. With the parameters ColorSpace and BitsPerChannel the resulting HALCON image is specified.
To offer a basic support of custom pixel formats a compatible BitsPerChannel value and a ColorSpace with value 'raw' were set. If no BitsPerChannel value according to the current PixelFormat can be determined, the fallback value is 8. The resulting HALCON image might look incorrect.

Using HDevelop Image Acquisition Assistant

In case of using the HDevelop Image Acquisition Assistant the following hints will help to avoid problems:

• Some parameters depend on special conditions, e.g., a valid buffer or another parameter activated. After opening the camera these conditions may not yet be fulfilled, so the depending parameters are not shown. By using the 'Refresh' button all parameters are read again and the depending parameters should appear, if the conditions are fulfilled then.
• There are also some parameters regarding the image size and the payload size, which can only be changed, if no acquisition takes place. The safest way to ensure this, is to apply the action parameter 'do_abort_grab'. Please note that 'Update Image' has to be disabled first.
• 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.

Description

Parameters for open_framegrabber():

	Name		'GenICamTL'		The name of the HALCON interface.
	HorizontalResolution		0, 1, 2, 4, resolution		Set the desired horizontal resolution of the camera image: 0: Take the current settings of the camera. 1: Use full resolution, reset all previous settings. If Width is bigger than 16000 or smaller than the current value, the current value is left untouched (we assume the XML file is incorrect). If a bigger value is desired, the value must be set manually (do not use 1 for HorizontalResolution). If this setting doesn't work, the interface automatically tries to use the current settings of the camera. 2, 4: If binning is available, it is set to the factor, otherwise, it is tried to set decimation instead. resolution: User defined horizontal resolution is set. Default: 0.
	VerticalResolution		0, 1, 2, 4, resolution		Set the desired vertical resolution of the camera image: 0: Take the current settings of the camera 1: Use full resolution, reset all previous settings. If Height is bigger than 16000 in case of an area scan camera or smaller than the current value, the current value is left untouched (we assume the XML file is incorrect). If a bigger value is desired, the value must be set manually (do not use 1 for VerticalResolution). If this setting doesn't work the interface automatically tries to use the current settings of the camera. 2, 4: If binning is available, it is set to the factor, otherwise, it is tried to set decimation instead. If this also fails, half or quarter of the maximum image size is set. resolution: User defined vertical resolution is set. Default: 0.
	ImageWidth		0, width		The width of the desired image part ('0' stands for the complete image). If this value is not set, the interface assumes the user always wants to get the maximum possible image size. Default: 0.
	ImageHeight		0, height		The height of the desired image part ('0' stands for the complete image). If this value is not set, the interface assumes the user always wants to get the maximum possible image size. Default: 0.
	StartRow		0, row		The row coordinate of the upper left pixel within the desired image part. If this value is not set, the interface assumes the user always wants to get the maximum possible image offset. Default: 0.
	StartColumn		0, column		The column coordinate of the upper left pixel within the desired image part. If this value is not set, the interface assumes the user always wants to get the maximum possible image offset. Default: 0.
	Field		---		Ignored.
	BitsPerChannel		-1, 8, 10, 12, 14, 16		The number of significant bits per channel of the resulting HALCON image. In case of -1 the bit depth of the current PixelFormat is used. Default: -1.
	ColorSpace		'default', 'gray', 'raw', 'rgb', 'yuv'		Specify the desired color space and thus the number of image channels of the resulting HALCON image. In case of 'default' for Mono pixel formats, ColorSpace is set to 'gray', otherwise to 'rgb'. Default: 'default'.
	Generic		'device_access=mode 'num_buffers=number', 'streaming_mode=0'		With the Generic parameter some important values can be set before the camera is initialized. Note that the parameter names including the values must be strings, e.g., 'num_buffers=5' sets the number of buffers to 5. The following parameters are available: device_access: With this parameter the access mode of the device can be set. Valid values are 'control' for read/write access, 'exclusive' for full control, and 'read-only' for read-only access. Default: 'exclusive'. num_buffers: To set the maximum number of buffers used in the HALCON acquisition interface a value greater than 1 has to be used. Note that depending on the image size of the used camera a high number of buffers can exceed the available memory size of your computer. We recommend to use at least 2 buffers. Default: 3. streaming_mode: To generally disable image streaming, this parameter has to be set to 0.
	ExternalTrigger		---		Ignored. To configure the trigger mode please use set_framegrabber_param with the generic trigger parameters of the camera.
	CameraType		'default', xml_filename		By default, the XML description file with the camera parameters is derived directly from the camera. Alternatively, you can specify the name of the XML camera description file directly, e.g., 'C:\\MyCameraDescription.xml'. Default: 'default'.
	Device		'device:<device id> producer:<cti file including path> interface:<interface index>:<interface id> vendor:<device vendor> model:<device model>'		To open a specific camera the device name as shown in info_framegrabber('info_boards',...,...) has to be set. To open the device at least the device id, cti file and interface id are needed. As a shortcut, it is possible to open the device only with its device id, but in this case always the first found GenTL Producer is used.
	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).
Please note that the interface sets the value of a parameter only if the value is valid. Otherwise, the value is rounded down to the next valid value.
Additionally to the GenApi parameters of the camera and of the transport layer, the following HALCON interface parameters are supported:

	'bits_per_channel'		-1, 8, 10, 12, 14, 16		The number of significant bits per channel.
	'callback_timeout'		milliseconds		Sets the timeout in milliseconds for the callback waiting function. With -1 an infinite callback timout is specified. To get further information, see set_framegrabber_callback. Default: 2000.
	'clear_buffer'		'disable', 'enable'		If enabled each buffer is cleared before re-queueing (set to 0xF0 for 8 bit images and shifted for other bit depths). Default: 'disable'.
	'color_space'		'default', 'gray', 'raw', 'rgb', 'yuv'		Sets the desired color space of the resulting HALCON image.
	'delay_after_stop'		milliseconds		Specify the time to wait (in milliseconds) between calling AcquisitionStop and stopping the transport layer. The optimal value depends on the camera. Default: 50.
	'do_abort_grab'		---		Aborts the current image acquisition and unlocks parameters, which are locked according to the status of the transport layer.
	'do_write_xml_file'		path		Specify the path for writing the XML files of the remote device and each module to a specified directory. Note that the HDevelop Image Acquisition Assistant saves the files in the %TEMP% directory.
	'grab_timeout'		milliseconds		Specify the desired timeout (milliseconds) for aborting a pending grab. If -1 is specified, the timeout is set to INFINITE. Default: 5000.
	'image_height'		0, min ... max		Sets the height of the resulting HALCON image. 0 specifies the maximum image height. If this value is not set, the interface assumes the user always wants to get the maximum possible image size.
	'image_width'		0, min ... max		Sets the width of the resulting HALCON image. 0 specifies the maximum image width. If this value is not set, the interface assumes the user always wants to get the maximum possible image size.
	'start_async_after_grab_async'		'disable', 'enable'		By default, at the end of grab_image_async a new asynchronous grab command is automatically given to the acquisition device. If the parameter 'start_async_after_grab_async' is set to 'disable', this new grab command is omitted. Default: 'enable'.
	'start_column'		0 ... max		Sets the column coordinate of the upper left corner of the resulting HALCON image part. If this value is not set, the interface assumes the user always wants to get the maximum possible image size.
	'start_row'		0 ... max		Sets the row coordinate of the upper left corner of the resulting HALCON image part. If this value is not set, the interface assumes the user always wants to get the maximum possible image size.
	'verify_value'		'false', 'true'		Enables/disables the value verification, if a device parameter is set. Default: 'true'.
	'volatile'		'disable', 'enable'		Raw and grayscale only. In the volatile mode the image buffers are used directly to store HALCON images. This is the fastest mode avoiding to copy raw images in memory. However, be aware that older images are overwritten again and again as a side-effect. Thus, you can only process one image while you grab another image. Older images are invalid! Please note that the HDevelop Image Acquisition Assistant offers only the 'enable' value, if the current PixelFormat and color_space allows volatile mode. So after changing these parameters, the refresh button has to be used to get the new status of the values for volatile. Default: 'disable'.

Parameters for get_framegrabber_param():

Additional parameters supported by get_framegrabber_param only. Note that all parameters supported by set_framegrabber_param except the ones with prefix 'do_' can also be accessed by get_framegrabber_param. Furthermore, corresponding to the parameters supported by set_framegrabber_param, there may exist additional read-only parameters with the following postfixes:

• '_access': These parameters provide the access permissions of the corresponding parameter as a string. Possible values are 'ro' (read-only), 'wo' (write-only), and 'rw' (read/write).
• '_category': These parameters provide the category of the corresponding parameter as a string.
• '_description': These parameters provide the tool-tip of the corresponding parameter as a string.
• '_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'.

	'available_callback_types'		callback_type		Returns a list containing the device-specific callback types.
	'available_param_names'		[parameter] (strings)		Returns a list containing the names of all available parameters.
	'buffer_is_incomplete'		0, 1 (integer)		Shows if a grabbed image is incomplete due to lost packets.
	'buffer_timestamp'		timestamp (string)		Timestamp when the current buffer was acquired.
	'image_available'		0, 1 (integer)		Shows if a grabbed image is completely written and available.
	'num_buffers'		number (integer)		Returns the number of used buffers.
	'num_buffers_await_delivery'		number (integer)		Returns the number of grabbed buffers, which are already in the output queue and ready to be delivered.
	'num_buffers_underrun'		number (integer)		Returns the number of lost buffers due to buffer queue underrun.
	'revision'		revision (string)		The revision number of the HALCON GenICamTL interface.
	'tl_displayname'		displayname (string)		The user-readable name of the used GenTL Producer.
	'tl_filename'		filename (string)		The file name of the used GenTL Producer.
	'tl_id'		ID (string)		Unique identifier of the used GenTL Producer.
	'tl_model'		model (string)		Name of the used GenTL Producer to distinguish different kinds of GenTL Producer implementations from one vendor.
	'tl_pathname'		path (string)		Full path of the used GenTL Producer.

Parameters for set_framegrabber_callback():

All actually supported callback types of a specific image acquisition device can be queried by calling get_framegrabber_param with the parameter 'available_callback_types'. Once the callback is registered and the underlying event is activated, on every occurrence of the event (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 to deactivate the underlying event first.

Attention:To activate or deactive the device-specific callbacks, the corresponding device-specific event has to enabled or disabled. This means you have to set the GenApi parameter 'EventSelector' to the specific event type, and the 'EventNotification' parameter to 'GenICamEvent'.

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 the 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. Up to now, this parameter is not used, i.e., Context is set to NULL.
	UserContext		User context as set via set_framegrabber_callback.

Note that the execution time of a user-specific callback function must always be as short as possible since during the execution of a callback function the handling of further internal callbacks might be blocked. This can be achieved by removing the actual processing from the user-specific callback function to a separate thread that is controlled via signals or events. The callback function is executed in the context of the underlying interface or driver.

Grabbing Chunk Data with grab_data/grab_data_async

If a device supports chunk data and the user enables it, the HALCON GenICamTL interface receives this additional data with every buffer. Chunk data and also chunk images can be received by calling grab_data or grab_data_async using the following parameters:

	Image		Returns either a normal or a chunk image.
	Data		If chunk is enabled 'Data' returns the chunk data as a tuple of triples: Chunk name (string), value type (string), value (integer, float or string). Value types can be 'integer', 'float' or 'string'. In case of an 64-bit integer chunk value this value will be returned as a string (and also with value type 'string').

Troubleshooting

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

• General:
  • Check if the camera has the latest firmware.
  • Check for a newer version of the used GenICam GenTL Producer.
  • Check if the latest revision of the HALCON GenICamTL Interface is used.
  • Enable low-level-error messages in HALCON to query more information about the problem.

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 model and firmware version.
• Details about the used GenICam GenTL Producer.
• Details about network card and topology.
• Details about computer system.

Release Notes

• Revision 4.4 (Nov 21, 2011):
  • Fixed wrong return value in parameter 'buffer_timestamp' and changed type from integer to string.
  • Fixed adding GenICam path to PATH environment variable each time open_framegrabber was called.
  • Fixed problem when using more than one device with the same name, but different interfaces.
  • Fixed problem with starting the stream each time grab_image or grab_image_async was called.
  • Added support of chunk data via the operators grab_data and grab_data_async, see also new section Grabbing Chunk Data.
  • Added functionality to get notified in case of any available device-specific event via user-specific callbacks.
  • Added mutex protection for grabbing images.
  • Added parameters 'available_callback_types' and 'callback_timeout'.
  • Added parameters 'clear_buffer' and 'verify_value'.
  • Added generic parameters 'device_access' and 'streaming_mode'.
  • Changed info_framegrabber(..'general'..) to static list.
  • Changed behavior of grab_image if AcquisitionMode of the device is 'Continuous'. Now always a new image should be returned.
  • Changed behavior of parameter 'do_write_xml_file'. Now not only the XML file of the remote device but also the XML files of the GenTL Producer's modules are written (including the name of the used GenTL Producer).
  • Changed internal color conversion to rely on the information which is provided by the current buffer. Currently, the interface uses the PixelFormat of the device, if the BUFFER_INFO_PIXELFORMAT_NAMESPACE or the BUFFER_INFO_PIXELFORMAT returns unsupported values. In this case a low-level error message will be returned.
  • Removed setting of external trigger from open_framegrabber. To configure the trigger mode please use set_framegrabber_param with the generic trigger parameters of the camera.
• Revision 4.3 (Dec 13, 2010):
  • Changed default setting for horizontal/vertical resolution in open_framegrabber from 1 to 0.
  • Fixed parsing problems of the XML files under Linux, when opening a camera several times.
  • Fixed timeout when the image size has been changed and software trigger is used.
  • Fixed problem with setting module parameters, which in some cases led to an error.
  • Fixed error if more than one GenTL Producer was found, but one of them could not be loaded. Now the broken one is skipped and all others can be loaded correctly.
  • Improved color conversion for YUV pixel formats.
  • Added support of representation tags to show hexadecimal numbers correctly.
  • Added low-level error messages to improve error handling.
  • Added helper function to correct a value which exceeds the valid boundaries of a parameter.
• Revision 4.2 (Sep 30, 2010):
  • Changed order of starting the acquisition: Now the acquisition of the remote device is started after starting the acquisition of the GenTL Producer.
  • Fixed error when calling info_framegrabber with parameters 'info_boards', 'device' or 'general' more than once after each other.
• Revision 4.1 (Sep 10, 2010):
  • Fixed bug to prevent HDevelop crash if info_framegrabber(...,'info_boards',...) was called while a device was already open.
  • Fixed bug to prevent double calls of 'StartAcquisition' which led to problems with some devices.
  • Enabled use of multiple devices simultaneously.
  • Fixed memory leak.
  • Fixed bug to enable opening a device even if there exist no module parameters in the used GenTL Producer.
  • Module parameter names now start with the prefix of the corresponding module layer to ensure the uniqueness of all parameter names. Without the prefix the returned values and categories of these parameters could have been wrong.
  • If the environment variables for GenICam were not set correctly, the interface failed with H_ERR_DLOPEN. Now the delayed loading of the GenICam libraries is enabled, so that the environment variables can be set automatically.
  • Added parameters 'buffer_is_incomplete', 'buffer_timestamp', 'do_write_xml_file', 'num_buffers_await_delivery', 'num_buffers_underrun', 'tl_displayname', 'tl_filename', tl_id', 'tl_model', and 'tl_pathname'.
  • Added paragraphs 'GenICam GenTL' and 'Parameter Naming' in this documentation.
• Revision 4.0 (Jul 30, 2010):
  • First official release.