HALCON 9.0 Image Acquisition Interface for SICK 3D Cameras

This page provides the documentation of the HALCON SICK-3DCamera image acquisition interface for SICK Ranger C/D/E and Ruler E cameras. Registered customers can download the latest revision of this interface from the MVTec WWW server.

Revision: 4.2

System Requirements

• Intel compatible PC with Windows XP SP3.
• Ethernet cameras: Intel PRO/1000 network interface card with successfully installed eBUS high performance driver.
  Camera Link cameras: DALSA Camera Link board X64-CL with successfully installed Sapera LT software library (version 6.10 or higher) and drivers.
• Successfully installed SICK 3DCamera version 4.0.2.0. Please make sure that the the icon_c_40.dll is available via the %PATH% environment variable. Note that for using the HALCON SICK-3DCamera interface you need a valid .prm file (e.g., Ranger E55 Default.prm) for your specific camera configuration, which must be created using Ranger Studio.
• HALCON image acquisition interface hAcqSICK-3DCamera.dll or hAcqSICK-3DCameraxl.dll, respectively. If you have installed the interface properly, both DLLs should reside in bin\%HALCONARCH% within the HALCON base directory %HALCONROOT% you have chosen during the installation of HALCON.

Features

• Synchronous and asynchronous grabbing.
• Image or measurement configuration available.
• Access to multiple measurement components either via multi-channel images (with grab_image[_async]) or via image tuples (with grab_data[_async]).
• Access to calibrated and rectified measurement data via grab_data[_async].
• Access to mark data via grab_data[_async].
• Software control of all camera parameters.

Limitations

• No LUTs.
• Mark data is only available in continuous grabbing mode.

Reading Mark Data

The Ranger 3D cameras allow to read the optional mark data (either a counter or the actual encoder values). To query these data together with the grabbed image data, you have to use the operators grab_data or grab_data_async. If the mark data is enabled in the used camera configuration file, the output parameter Data of grab_data[_async] contains for every mark sub-component the value and the status. The order of these integer values corresponds to the order of the images in the parameter Image. Please note that the parameter 'continuous_grabbing' must be set to 'enable' to get the mark data continuously.

3D Calibration and Rectification

The Ranger 3D cameras allow to calibrate and rectify range data. To generate these data you have to create a lookup-table (LUT) with the SICK Coordinator tool. The LUT can be either stored in the flash of the camera or in a file. With the parameter 'lut_file' you can use your LUT file for the calibration. If no LUT file is set, the calibration filter tries to load it from the flash of the camera. You can choose to enable only the calibration via the parameter 'calibration_filter' or also the rectification via the parameter 'rectification_filter'. The method of the rectification filter can be set via the parameter 'rectification_method'. To access the calibrated (and rectified) data the operators grab_data or grab_data_async have to be used. Here, the additional measurement data is provided as additional images ('Range X', 'Range R', 'Rectified Range').

Representation of Images in Ranger Studio and HALCON

Note that there is a general difference regarding the image representation between Ranger Studio and HALCON: The coordinate system of the SICK 3D cameras is right to left and top to down, but in order to display the images in the "correct" way, the SICK Ranger Studio flips the images automatically. In HALCON, the coordinate system is always left to right and top to down, thus, the images as they come from the buffers from the SICK 3D camera look mirrored in comparison to the ones of Ranger Studio.

Description

Parameters for open_framegrabber():

	Name		'SICK-3DCamera'		The name of the HALCON image acquisition interface.
	HorizontalResolution		---		Ignored.
	VerticalResolution		---		Ignored.
	ImageWidth		0, 256 ... 1536		The width of the desired image part. Please note that the image width must be divisible by 8. If set to 0 the value in the prm-file (or the current setting of the camera) is used. Default: 0.
	ImageHeight		0, height		The height of the desired image part (in image mode) or the number of scans (in measurement mode). If set to 0 the value in the prm-file (or the current setting of the camera) is used. Default: 0.
	StartRow		---		Ignored.
	StartColumn		0, 1 ... 1280		The column coordinate of the upper left pixel within the desired image part. Note that the sum of StartColumn and ImageWidth must not exceed 1536. If set to 0 the value in the prm-file (or the current setting of the camera) is used.
	Field		---		Ignored.
	BitsPerChannel		---		Ignored (the number of bits per channel is determined automatically by reading the parameter file).
	ColorSpace		'image', 'measurement'		The desired camera configuration. If set to 'image', every call of grab_image and grab_image_async will result in a gray value image. If set to 'measurement', a multi-channel image containing the measurement components as defined in the prm-file will be returned. Default: 'measurement'.
	Generic		'buffer_size=MB', -1		Buffer size in MB. Only valid for Ethernet cameras. Default: 50.
	ExternalTrigger		'true', 'false'		Activate/deactivate external triggering. If activated, the 'use enable' parameter of the SICK API is set to '2' (rising edge).
	CameraType		prm-file, 'default'		Name of the camera parameter file. In case of 'default', the current camera settings are used. Default: 'default'.
	Device		ip_address or device		For Ethernet cameras the IP address of the camera must be specified here. In case of Ranger C cameras, the physical port as selected in the Sapera Configuration Tool has to be set.
	Port		0, 1		The used camera port on the X64-CL board. In case of Ethernet cameras this parameter is ignored. Default: 0
	LineIn		---		Ignored.

Parameters for set_framegrabber_param():

Note that most of the following parameters (and also the valid parameter values!) depend on the capabilities of the used camera. Furthermore, the default values may depend on the current camera settings.

	'active_channel'		value		Sets the number of the active channel, if measurement configuration is chosen.
	'calibration_filter'		'disable', 'enable'		Enables/disables the calibration filter for the 'Range' subcomponent. In measurement configuration, grab_data[_async] then returns two additional images with the 'Range X' and 'Range R' data. Default: 'disable'.
	'configuration'		'image', 'measurement'		Sets the configuration of the camera. If set to 'image', every call of grab_image and grab_image_async will result in a gray value image. If set to 'measurement', a multi-channel image containing the measurement components as defined in the prm-file will be returned. Default: 'measurement'.
	'continuous_grabbing'		'enable', 'disable'		If 'continuous_grabbing' is enabled, data is continuously acquired by the camera. Otherwise data is only acquired when calling grab_image or grab_image_async.
	'do_save_parameters'		prm-file		Save the parameter settings to the specified filename.
	'grab_timeout'		value		Specify the desired timeout (milliseconds passed as an integer) for aborting a pending grab. The value -1 sets the timeout to 65535. Default: 5000.
	'lut_file'		LUT-file, 'flash'		Load the lookup-table for calibration from the specified path and filename. Set the parameter value to 'flash' to clear the file name and to use the lut file from the camera flash.
	'module_name'		name		The name of the parameter to be changed, e.g., 'number of rows'.
	'module_path'		path		The path to a component in the XML structure.
	'module_value'		value		The new value for the parameter specified by the parameters 'module_name' and 'module_path'.
	'rectification_filter'		'disable', 'enable'		Enables/disables the rectification filter for the 'Range' subcomponent. In measurement configuration, grab_data[_async] then returns one additional image with the rectified 'Range' data. Default: 'disable'.
	'rectification_method'		'bottom_most', 'mean', 'top_most'		Sets the method for the rectification filter. Default: 'mean'.
	'trigger_mode'		'0', '2'		If 'trigger_mode' is set to '0' the camera is set to free running mode; if set to '2' pulse triggering of the encoder is activated. This parameter doesn't effect the value of the 'external_trigger' parameter.

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, step width, and default values for the corresponding integer or float parameter as a tuple with 4 elements, e.g., get_framegrabber_param(..,'exposure_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'].

	'channel_names'		channel_names (string)		The component names of the accessible channels are returned as a tuple of strings.
	'image_available'		image_available (int)		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.
	'revision'		revision (string)		The revision number of the HALCON interface.
	'serial_number'		serial number (string)		The serial number of the camera.
	'software_version'		version (string)		The version number of the SICK software SDK.

Release Notes

• Revision 4.2 (Mar 10, 2010):
  • Fixed bug in 3D calibration functionality in combination with 'High 3D COG' configuration files. Note that for this fix it is neccessary to use version 4.0.2.0 of the SICK 3DCamera SDK installed. Otherwise, the call of grab_data or grab_data_async will crash.
  • Added implementation of info_framegrabber(..,'generic',...) to query all supported values for the Generic parameter in open_framegrabber.
• Revision 4.1 (Feb 12, 2010):
  • Fixed bug in operator info_framegrabber(..,'info_boards',..) to prevent application termination.
  • Changed behavior of parameters 'external_trigger' and 'trigger_mode': Now, 'external_trigger' correctly sets the parameter 'use enable' of the SICK API instead of 'trig mode'. The parameter 'trigger_mode' is now independent from the setting of the 'external_trigger' parameter.
  • In measurement mode, setting 'external trigger' to 'true' in open_framegrabber was ignored. This bug has been fixed.
  • Added paragraph about the difference between the image representation in Ranger Studio and HALCON.
• Revision 4.0 (Nov 11, 2009):
  • First official release.