HALCON 10 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, Ruler E, and ColorRanger E cameras. Registered customers can download the latest revision of this interface from the MVTec WWW server.
Revision: 4.7
System Requirements
- Intel compatible PC with Windows XP SP3/7 or Windows XP x64/7 x64.
-
Ethernet cameras:
Intel PRO/1000 network adapter with successfully installed eBUS driver (version 2.0.1). We recommend to enable continuous grabbing for best performance. Camera Link cameras:
DALSA Camera Link board X64-CL with successfully installed Sapera LT software library (version 6.10 or higher) and drivers (not supported on 64-bit Windows). - Successfully installed SICK icon API version 4.3. Please make sure that the the icon_c_43.dll (or icon_c_43_x64.dll, respectively), 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.
- Windows x64: Visual Studio C++ 2010 Redistributable Runtime Package, particularly msvcp100.dll. If this package is not installed please download and install it from the Microsoft Download Center for Windows x64. Note: It is not sufficient to copy the missing files!
- Windows x86: Visual Studio C++ 2008 Redistributable Runtime Package, particularly msvcp90.dll. If this package is not installed please download and install it from the Microsoft Download Center for Windows x86. Note: It is not sufficient to copy the missing files!
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.
- No support of traits.
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 name of the corresponding component and all mark values. The order of these integer values corresponds to the order of the components. 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.
In some cases when using high resolution components and "normal"
components, some image channels received from grab_image and
grab_image_async are black at the right part of
the image. This is caused by the higher width of the high resolution images
and the restriction that the channels of one HALCON image objects must
have the same size. In this case we recommend to use grab_data and
grab_data_async instead.
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', 'num_buffers=num', 'use_error_handler=1', 'use_socket_driver=1', -1] |
Generic parameter:
|
|||
| ExternalTrigger | 'true', 'false' | Activate/deactivate external triggering. If activated, the 'use enable' parameter of the SICK API is set to '2' (rising edge), otherwise to '0'. Please note that you have to set different trigger modes manually via set_framegrabber_param. | |||
| 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' | -1, value | Sets the number of the active channel, if measurement configuration is chosen. -1 uses all channels. Default: -1. | |||
| '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'. | |||
| 'camera_start_delay' | milliseconds | In some cases packets are lost, if the camera is started too soon after starting the Grabber. With this parameter a delay for starting the camera can be set. Default: 20. | |||
| '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. | |||
| 'interpolation_method' | 'linear', 'nearest_neighbor' | Sets the interpolation method for the registration filter. Default: 'nearest_neighbor'. | |||
| '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'. | |||
| 'shift_blue' | shift (float) | Sets the shift value (as float) of the blue channel. Please note that this value must be set according to your configuration, if color components are used. Default: 0.0. | |||
| 'shift_green' | shift (float) | Sets the shift value (as float) of the green channel. Please note that this value must be set according to your configuration, if color components are used. Default: 0.0. | |||
| 'shift_red' | shift (float) | Sets the shift value (as float) of the red channel. Please note that this value must be set according to your configuration, if color components are used. Default: 0.0. | |||
| 'start_async_after_grab_async' | 'enable', 'disable' | By default, at the end of grab_image_async a new request for an asynchronous grab command is automatically given to the camera. If the parameter 'start_async_after_grab_async' is set to 'disable' this new grab command is omitted. Default: 'enable'. | |||
| 'trigger_mode' | '0', '2', '3', '4', '5' |
Sets the trigger mode (trig mode 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'].
| 'buffer_size' | MB (int) | The size in MB of the buffers used for the image acquisition. | |||
| 'camera_status' | status (string) | Returns the current status of the SICK camera. Please note that this parameter supports only Ethernet cameras. | |||
| 'channel_names' | channel_names (string) | The component names of the accessible channels are returned as a tuple of strings. | |||
| 'device_type' | type&npsp;(string) | The type of the current device. | |||
| '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. | |||
| 'num_buffers' | number (int) | The number of buffers used for the image acquisition. | |||
| '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. | |||
| 'use_error_handler' | 0, 1 (int) | Shows if the SICK error handler is used to display additional error messages. This parameter can be enabled only via the parameter Generic in open_framegrabber. |
Release Notes
-
Revision 4.7 (Oct 13, 2011):
- Adapted to SICK icon API 4.3 with support of eBus driver for 64-bit Windows.
- Changed requirements for x86 version of the interface from Microsoft Visual C++ 2005 Redistributable Package to Microsoft Visual C++ 2008 Redistributable Package.
- Fixed problems with lost packets when setting parameters 'configuration', 'module_value', or 'trigger_mode'.
- Fixed problem with message boxes of the SICK error handler.
- Added parameter 'camera_status' to show the current camera status.
- Added generic parameter 'use_socket_driver=1' to allow usage of the Socket driver.
- Added setting of 'redundancy frequency' and 'heatbeat interval' to open_framegrabber. If these values are zero a default of 10s for 'redundancy frequency' and 180s for 'heartbeat interval' are set.
- Added parameter 'camera_start_delay' to make it possible to delay the start of the camera.
-
Revision 4.6 (May 30, 2011):
- Fixed problem in set_framegrabber_param regarding setting specific parameter values via 'module_value'. Now, the value is correctly set.
-
Revision 4.5 (Mar 11, 2011):
- Adapted to SICK icon API 4.2 with support of Windows 7 and Windows XP x64 editions.
- Fixed display problem of grab_image/grab_image_async if a configuration with only one high resolution channel is used.
- Fixed exception when using parameter 'active_channel' in combination with a high resolution image.
- Improved behavior of parameter 'channel_names': Now the correct values are returned, even if only one channel is active.
- Changed default value of parameter 'active_channel' to -1. Thus, it is also possible to reset this value.
-
Revision 4.4 (Oct 20, 2010):
- Fixed crashes while grabbing an image (caused by using wrong runtime libraries).
- Fixed additional restart of acquisition when using external trigger with asynchronous grab and calibration filter.
- Fixed problem causing error message #6001 ('Not enough memory available') when using calibration and rectification filter.
-
Revision 4.3 (Jul 30, 2010):
- Adapted to SICK icon API 4.1.
- Added support of color components to grab_image[_async] and grab_data[_async].
- Added parameters 'buffer_size', 'device_type', 'interpolation_method', 'num_buffers', 'shift_blue', 'shift_green', 'shift_red', 'start_async_after_grab_async', and 'use_error_handler'.
- Added additional mark data information. Now the mark data for every scan is returned. The component name of the mark data values has been added for better readability.
- Added trigger modes 3, 4, and 5 to parameter 'trigger_mode'.
- Added 'num_buffers' to the Generic parameter in open_framegrabber to allow setting of the used number of buffers.
- Added the possibility to enable SICK error handler to the Generic parameter in open_framegrabber.
- Added descriptions of parameters, which can be requested by get_framegrabber_param(...,'<parameter_name>_description',...).
- Fixed problem when trying to set parameter 'trigger_mode' before an image has been grabbed.
- Adapted example programs to support prm files with color components.
- HALCON 10 version of the interface (included in HALCON 10 DVD).
-
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.
