Interface Documentation
Image Acquisition Interface for SICK 3D Cameras
| Interface: | SICK-3DCamera |
| Revision: | 13.0.3 |
| Date: | 2018-08-08 |
- General
- System Requirements
- Installation
- Features
- Limitations
- Reading Mark Data
- 3D Calibration and Rectification
- Representation of Images in Ranger Studio and HALCON
- Using SICK frame grabber's internal queue of buffers
- Parameters for info_framegrabber
- Parameters for open_framegrabber
- Parameters for set_framegrabber_param
- Parameters for get_framegrabber_param
- Operator set_framegrabber_lut
- Operator get_framegrabber_lut
- Operator set_framegrabber_callback
- Operator get_framegrabber_callback
- Operator grab_image_start
- Operator grab_image
- Operator grab_image_async
- Operator grab_data
- Operator grab_data_async
- Operator close_framegrabber
- HDevelop Examples
- Release Notes
General
This page provides the documentation of the HALCON SICK-3DCamera image acquisition interface for
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.
System Requirements
- Intel compatible PC with Windows 7 (32-bit or 64-bit) or newer that is also supported by the vendor-specific SDK. Note that WoW64 (using 32-bit HALCON on 64-bit Windows) is not supported and can lead to a crash.
- Ethernet cameras:
Intel PRO/1000 network adapter with successfully installed eBUS driver (version 3.1). We recommend enabling continuous grabbing for best performance.
Camera Link cameras (legacy):
DALSA Camera Link board X64-CL with successfully installed Sapera LT software library (version 7.10 or higher) and drivers. - Successfully installed SICK iCon API version 5.1 SR1. Please make sure that the icon_51.dll (or icon_51_x64.dll, respectively), is available via the %PATH% environment variable.
- 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.
Installation
Only when installing or updating the interface manually follow these steps:
- Windows: Extract the archive containing the interface files to the HALCON base directory %HALCONROOT% (Note: Administrator privileges may be required for this step). Additionally, you have to move the interface examples to the directory %HALCONEXAMPLES% manually.
Features
- Synchronous and asynchronous grabbing.
- Image or measurement configuration available.
- Access to multiple measurement components either via multi-channel images (with grab_image/grab_image_async) or via image tuples (with grab_data/grab_data_async).
- Access to calibrated and rectified measurement data via grab_data/grab_data_async.
- Access to mark data via grab_data/grab_data_async.
- Software control of all camera parameters.
Limitations
- Mark data is only available in continuous grabbing mode.
- No support of traits.
- Parameters 'image_height' (lines per frame) and '<Measurement>scan height' are internally set to the same value.
- Changing parameters in Ranger Studio (in Ethernet camera case) when using HDevelop in parallel can lead to an invalid parameters configuration.
- Due to current iCon API limitations, Ranger C devices may not behave as expected in case of continuous synchronous grabbing and in case of continuous asynchronous grabbing with 'buffer_queue' and 'start_async_after_grab_async' disabled.
Reading Mark Data
The SICK 3D cameras can be configured to deliver the optional mark data (either a counter or the actual encoder values). To query these data
together with the grabbed image data, the operator grab_data or
grab_data_async have to be used. If the mark data is enabled in the used
camera configuration file, the output parameter 'Data' of
grab_data/grab_data_async contains for every mark subcomponent 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 SICK 3D cameras can be configured to deliver calibrated and rectified range data. To generate these data you have to create a lookup-table (LUT)
with the SICK Coordinator tool. The LUT can either be 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. If you
want to use a LUT file, this has to be set before the calibration filter
is enabled.
You have the choice between enabling only the calibration via the parameter
'calibration_filter' and also enabling the rectification via the parameter
'rectification_filter'. The method of the rectification filter can be
set via the parameter 'rectification_method'. The rectification width can
be set via the parameter 'rectification_width'.
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 Data (Range)',
'Rectified Data (Intensity)').
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 object must have the same size. In this case we recommend using grab_data and grab_data_async instead.
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 object must have the same size. In this case we recommend using grab_data and grab_data_async instead.
Using SICK frame grabber's internal queue of buffers
In case of continuous ('continuous_grabbing' = 'enable') asynchronous grabbing (grab_image_async/grab_data_async), the use of SICK frame grabber's internal queue of buffers can be activated by setting 'buffer_queue' to 'enable'. Notice that the default value for the 'buffer_queue' is 'disable'.
The HDevelop example sick-3dcamera_buffer_queue.hdev shows how to enable the use of the SICK frame grabber's internal queue of buffers, how to calculate the available number of buffers, how to detect overflow using the mark data and how to recover from overflow using 'do_abort_grab'.
The HDevelop example sick-3dcamera_grabbing_modes.hdev shows the behavior of the different grabbing modes (asynchronous/synchronous) depending on the following parameters: 'continuous_grabbing', 'buffer_queue' and 'start_async_after_grab_async'.
In case of Ethernet cameras (Ranger E/D), the buffer size can be set by means of the Generic parameter 'buffer_size' in open_framegrabber. Its default value is 50 [MB]. The number of buffers can be calculated as follows depending on the current configuration:
| Configuration | Number of Buffers |
|---|---|
| 'measurement' | 'buffer_size'[MB] * 2^20[bytes/MB] / ('scan_size'[bytes/scan] * '<Measurement>scan height'[scans/buffer]) |
| 'image' | 'buffer_size'[MB] * 2^20[bytes/MB] / ('scan_size'[bytes/scan] * 1) |
The current queue size can be also known by activating the SICK message
errors (set 'use_error_handler=1' in open_framegrabber) and by checking
the "Queue size" in the connection message shown in the HDevelop output
console:
"message: 13:36:13
Notice that the Generic parameter 'num_buffers' in open_framegrabber has been removed to avoid confusion with SICK frame grabber's internal queue of buffers.
Parameters for info_framegrabber
| Parameter | Value List | Type | Kind | Description |
|---|---|---|---|---|
| 'bits_per_channel' | [] | Unused. | ||
| 'camera_type' | ['CAMFILE:', 'prm', '<path>', 'default'] | string | pre-defined | Syntax for camera file and default value. |
| 'color_space' | ['image', 'measurement'] | string | pre-defined | Value list for configuration. |
| 'defaults' | [1, 1, 0, 0, 0, 0, 'progressive', -1, 'measurement', -1.0, 'false', 'default', 'default', 0, 0] | mixed | pre-defined | Default values for open_framegrabber. |
| 'device' | ['<ip_address>'] | string | dynamic | Returns the list of available Ethernet devices if possible. Otherwise, a place-holder is returned. Camera Link devices (legacy) are ignored. |
| 'external_trigger' | [] | Unused. | ||
| 'field' | [] | Unused. | ||
| 'general' | [] | string | pre-defined | Information about the HALCON SICK-3DCamera interface. |
| 'generic' | ['', 'buffer_size=<MB>', 'camera_reset_on_close=1', 'low_level_timeout=<ms>', 'use_error_handler=1', 'use_socket_driver=1'] | string | pre-defined | Value list for the Generic parameter. |
| 'horizontal_resolution' | [] | Unused. | ||
| 'image_height' | [] | Unsupported query. | ||
| 'image_width' | [] | Unsupported query. | ||
| 'info_boards' | ['device:<ip_address> | default_gateway:<default_gateway> | netmask:<netmask> | manufacturer:<manufacturer_name> | model_name:<model_name> | device_version:<device_version> | manufacturer_specific:<manufacturer_specific> | mac_address: <mac_address>'] | string | dynamic | Returns the list of available Ethernet devices with additional information. Camera Link devices (legacy) are ignored. |
| 'parameters' | ['<parameters>'] | string | pre-defined | Pre-defined parameters of the HALCON interface. |
| 'parameters_readonly' | ['<parameters>'] | string | pre-defined | Pre-defined read-only parameters of the HALCON interface. |
| 'parameters_writeonly' | ['<parameters>'] | string | pre-defined | Pre-defined write-only parameters of the HALCON interface. |
| 'port' | <port> | integer | pre-defined | Returns the static value list for port (for Ranger C devices). |
| 'revision' | '<revision>' | string | pre-defined | Revision number of the SICK-3DCamera interface. |
| 'start_column' | [] | Unsupported query. | ||
| 'start_row' | [] | Unsupported query. | ||
| 'vertical_resolution' | [] | Unused. |
Parameters for open_framegrabber
| Parameter | Values | Default | Type | Description |
|---|---|---|---|---|
| Name | 'SICK-3DCamera' | string | Name of the HALCON interface. | |
| HorizontalResolution | --- | Ignored. | ||
| VerticalResolution | --- | Ignored. | ||
| ImageWidth | 0, 256 ... 1536 | 0 | integer | 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. |
| ImageHeight | 0, <height> | 0 | integer | 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. |
| StartRow | --- | Ignored. | ||
| StartColumn | 0, 1 ... 1280 | 0 | integer | 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 value is defined by prm file. | ||
| ColorSpace | 'image', 'measurement' | 'measurement' | string | 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. |
| Generic | '', ['buffer_size=<MB>', 'camera_reset_on_close=1', 'low_level_timeout=<ms>', 'use_error_handler=1', 'use_socket_driver=1'], -1 | -1 | mixed | Generic parameters:
|
| ExternalTrigger | --- | Ignored. Note that this parameter has been deprecated, your code may require an adaptation. If activated, the 'use enable' parameter of the SICK API was set to '2' (rising edge), otherwise to '0'.The different trigger modes were manually selected via set_framegrabber_param. Now the SICK parameter '<Image>use enable' or '<Measurement>use enable' can be directly modified using the set_framegrabber_param operator. | ||
| CameraType | '<prm_file>', 'default' | 'default' | string | Name of the camera parameter file. In case of 'default' the current camera settings are used. |
| Device | '<ip_address>', '<device_id>' | 'default' | string | For Ethernet cameras, the IP address of the camera must be specified here. For Ranger C cameras, the 'Camera Link API port index' as indicated in the Sapera Configuration Tool must be used. |
| Port | <port> | 0 | integer | Port value. In case of:
|
| LineIn | --- | Ignored. |
Parameters for set_framegrabber_param
The SICK parameters of the camera can be different depending on the device type and the current loaded configuration file (.prm). Therefore, use
get_framegrabber_param(..., 'available_param_names', ...) to obtain
a tuple containing all available parameters of the connected camera. To set
a parameter, e.g. the 'exposure time' of the 'HorThr 1' component in
'Measurement' configuration, the user can call set_framegrabber_param(...,
'<Measurement><HorThr 1>exposure time', ...). Note that
in case of 'Argument' parameter type (see SICK documentation regarding SICK
parameter types), the camera will be internally stopped before changing the
parameter and the data format will be automatically updated if required.
| Parameter | Values | Default | Type | Description |
|---|---|---|---|---|
| 'active_channel' | -1, value | -1 | integer | Number of the active channel, if measurement configuration is chosen. -1 uses all channels. |
| 'buffer_queue' | 'disable', 'enable' | 'disable' | string | Enables/disables the use of SICK frame grabber's internal queue of buffers in case of continuous asynchronous grabbing. Notice that in case of continuous asynchronous grabbing with 'buffer_queue' disabled but 'start_async_after_grab_async' enabled, the 'buffer_queue' parameter will be ignored and the SICK frame grabber's internal queue of buffers will be used (no buffers lost). See also 'continuous_grabbing' parameter description. |
| 'calibration_filter' | 'disable', 'enable' | 'disable' | string | Enables/disables the calibration filter for the 'Range' subcomponent. In measurement configuration, grab_data/grab_data_async then returns two additional images with the 'Range X' and 'Range R' data. Note that in case a LUT file is used, it has to be loaded before the calibration filter is enabled. |
| 'camera_start_delay' | <milliseconds> | 20 | integer | 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. |
| 'configuration' | 'image', 'measurement' | 'measurement' | string | 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. Please note that when changing this parameter in HDevelop Image Acquisition Assistant, the 'Refresh' button has to be applied to update the current 'active_channel' values list. |
| 'continuous_grabbing' | 'disable', 'enable' | 'disable' | string | 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. See also 'buffer_queue' parameter. Note: due to
iCon API limitations, in case of Ranger C devices, 'continuous_grabbing'
mode may not behave as expected:
|
| 'do_abort_grab' | --- | Aborts the current image acquisition and flushes the SICK frame grabber's internal queue of buffers. | ||
| 'do_load_parameters' | --- | Load the parameter settings file specified in 'parameters_file' parameter. | ||
| 'do_save_parameters' | '<prm_file>' | 'saved_sick_parameters.prm' | string | Save the parameter settings to the specified filename. |
| 'grab_timeout' | <milliseconds> | 5000 | integer | Desired timeout (milliseconds) for aborting a pending grab. If -1 is specified, the timeout is set to INFINITE. |
| 'interpolation_method' | 'linear', 'nearest_neighbor' | 'nearest_neighbor' | string | Interpolation method for the registration filter. |
| 'lut_file' | '<LUT-file>', 'flash' | 'flash' | string | 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. The LUT file has to be set before the calibration filter is enabled. |
| 'parameters_file' | '<prm_file>' | string | Parameter file name (e.g. C:\prm-files\RangerE.prm) to be used by 'do_load_parameters' action parameter. | |
| 'rectification_filter' | 'disable', 'enable' | 'disable' | string | Enables/disables the rectification filter for the 'Range' subcomponent. In measurement configuration, grab_data/grab_data_async then returns two additional images with the rectified 'Range' and 'Intensity' data. Please note that to enable this parameter, the 'calibration_filter' has to be previously enabled. |
| 'rectification_method' | 'bottom_most', 'mean', 'top_most' | 'mean' | string | Method for the rectification filter. |
| 'rectification_width' | integer | Width of rectified buffer (X-direction). | ||
| 'shift_blue' | <shift> | 0.0 | float | 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. Continuous asynchronous grabbing is required (grab_image_async/grab_data_async with 'continuous_grabbing' enabled). |
| 'shift_green' | <shift> | 0.0 | float | 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. Continuous asynchronous grabbing is required (grab_image_async/grab_data_async with 'continuous_grabbing' enabled). |
| 'shift_red' | <shift> | 0.0 | float | 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. Continuous asynchronous grabbing is required (grab_image_async/grab_data_async with 'continuous_grabbing' enabled). |
| 'start_async_after_grab_async' | 'disable', 'enable' | 'enable' | string | By default a new asynchronous grab command is automatically given to the acquisition device at the end of grab_image_async. If the parameter 'start_async_after_grab_async' is set to 'disable', this new grab command is omitted. |
Parameters for get_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.
- '_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].
- '_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'.
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.
The SICK parameters of the camera can be different depending on the device type and the current loaded configuration file (.prm). Therefore, use get_framegrabber_param(..., 'available_param_names', ...) to obtain a tuple containing all available parameters of the connected camera. To get a parameter, e.g. the current 'exposure time' of the 'HorThr 1' component in 'Measurement' configuration, the user can call get_framegrabber_param(..., '<Measurement><HorThr 1>exposure time', ...).| Parameter | Values | Default | Type | Kind | Description |
|---|---|---|---|---|---|
| 'active_channel' | -1, value | -1 | integer | dynamic | Number of the active channel, if measurement configuration is chosen. -1 uses all channels. |
| 'available_callback_types' | ['<callback_type>'] | string | dynamic | Query all callback types which are supported by this interface. | |
| 'available_param_descriptions' | ['<descriptions>'] | string | dynamic | 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>'] | string | dynamic | The list contains the names of all available parameters. | |
| 'available_parameters' | '<iCon parameters tree>' | string | dynamic | Complete XML subtree of the current configuration ('image' or 'measurement'). | |
| 'bits_per_channel' | <default> | -1 | integer | pre-defined | The value is not used, so a default value is returned. |
| 'buffer_queue' | 'disable', 'enable' | 'disable' | string | pre-defined | Enables/disables the use of SICK frame grabber's internal queue of buffers in case of continuous asynchronous grabbing. Notice that in case of continuous asynchronous grabbing with 'buffer_queue' disabled but 'start_async_after_grab_async' enabled, the 'buffer_queue' parameter will be ignored and the SICK frame grabber's internal queue of buffers will be used (no buffers lost). See also 'continuous_grabbing' parameter description. |
| 'buffer_size' | <MB> | 50 | integer | dynamic | Size in Megabyte of the buffers used for the image acquisition. Only valid for Ethernet cameras. |
| 'calibration_filter' | 'disable', 'enable' | 'disable' | string | pre-defined | Enables/disables the calibration filter for the 'Range' subcomponent. In measurement configuration, grab_data/grab_data_async then returns two additional images with the 'Range X' and 'Range R' data. Note that in case a LUT file is used, it has to be loaded before the calibration filter is enabled. |
| 'camera_reset_on_close' | 0,1 | 0 | integer | pre-defined | Camera reset enabled in close_framegrabber. |
| 'camera_start_delay' | <milliseconds> | 20 | integer | dynamic | 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. |
| 'camera_status' | '<status>' | string | dynamic | Current status of the SICK camera. | |
| 'camera_type' | '<prm_file>' | string | pre-defined | Name of the camera parameter file. | |
| 'channel_names' | '<channel names>' | string | dynamic | Names of the data channels. Format: 'Component Name (Measure)' (e.g.['HorThr 1 (Range)', 'Gray 2 (Gray)', 'HiResGray 1 (Gray)', 'Scatter 1 (Direct)', 'Scatter 1 (Scatter)', 'Range X', 'Range R', 'Rectified Data (Range)', 'Rectified Data (Intensity)']). | |
| 'color_space' | '<configuration>' | 'measurement' | string | pre-defined | Current configuration. |
| 'configuration' | 'image', 'measurement' | 'measurement' | string | pre-defined | 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. Please note that when changing this parameter in HDevelop Image Acquisition Assistant, the 'Refresh' button has to be applied to update the current 'active_channel' values list. |
| 'continuous_grabbing' | 'disable', 'enable' | 'disable' | string | pre-defined | 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. See also 'buffer_queue' parameter. Note: due to
iCon API limitations, in case of Ranger C devices, 'continuous_grabbing'
mode may not behave as expected:
|
| 'device' | '<ip_address>' or '<device_id>' | string | dynamic | Current device. | |
| 'device_type' | '<type>' | string | dynamic | Type of the current device. | |
| 'external_trigger' | <default> | 'false' | string | pre-defined | The value is not used, so a default value is returned. |
| 'field' | '<default>' | 'progressive' | string | pre-defined | The value is not used, so a default value is returned. |
| 'generic' | '', ['buffer_size=<MB>', 'camera_reset_on_close=1', 'low_level_timeout=<ms>', 'use_error_handler=1', 'use_socket_driver=1'], -1 | -1 | mixed | pre-defined | Values of the Generic parameter. |
| 'grab_timeout' | <milliseconds> | 5000 | integer | pre-defined | Current grab timeout in milliseconds. |
| 'horizontal_resolution' | <default> | 1 | integer | pre-defined | The value is not used, so a default value is returned. |
| 'image_available' | 0, 1 | integer | dynamic | 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. Note that this parameter is especially useful in combination with external triggering. | |
| 'image_height' | <height> | 0 | integer | pre-defined | Height of the desired image part ('0' stands for the complete image). |
| 'image_width' | <width> | 0 | integer | pre-defined | Width of the desired image part ('0' stands for the complete image). |
| 'interpolation_method' | 'linear', 'nearest_neighbor' | 'nearest_neighbor' | string | pre-defined | Interpolation method for the registration filter. |
| 'line_in' | <default> | 0 | integer | pre-defined | The value is not used, so a default value is returned. |
| 'low_level_timeout' | <ms> | 0 | integer | pre-defined | Low level timeout value in milliseconds for Pleora eBus. |
| 'lut_file' | '<LUT-file>', 'flash' | 'flash' | string | dynamic | 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. The LUT file has to be set before the calibration filter is enabled. |
| 'name' | 'SICK-3DCamera' | string | pre-defined | Name of the HALCON interface. | |
| 'parameters_file' | '<prm_file>' | string | dynamic | Parameter file name (e.g. C:\prm-files\RangerE.prm) to be used by 'do_load_parameters' action parameter. | |
| 'port' | <port> | 0 | integer | pre-defined | Current port number. |
| 'rectification_filter' | 'disable', 'enable' | 'disable' | string | pre-defined | Enables/disables the rectification filter for the 'Range' subcomponent. In measurement configuration, grab_data/grab_data_async then returns two additional images with the rectified 'Range' and 'Intensity' data. Please note that to enable this parameter, the 'calibration_filter' has to be previously enabled. |
| 'rectification_method' | 'bottom_most', 'mean', 'top_most' | 'mean' | string | pre-defined | Method for the rectification filter. |
| 'rectification_width' | integer | pre-defined | Width of rectified buffer (X-direction). | ||
| 'revision' | '<revision>' | string | pre-defined | Revision number of the SICK-3DCamera interface. | |
| 'scan_size' | <bytes> | integer | dynamic | Size in bytes of one profile (scan). | |
| 'serial_number' | '<serial number>' | string | dynamic | Serial number of the camera. | |
| 'shift_blue' | <shift> | 0.0 | float | pre-defined | 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. Continuous asynchronous grabbing is required (grab_image_async/grab_data_async with 'continuous_grabbing' enabled). |
| 'shift_green' | <shift> | 0.0 | float | pre-defined | 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. Continuous asynchronous grabbing is required (grab_image_async/grab_data_async with 'continuous_grabbing' enabled). |
| 'shift_red' | <shift> | 0.0 | float | pre-defined | 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. Continuous asynchronous grabbing is required (grab_image_async/grab_data_async with 'continuous_grabbing' enabled). |
| 'software_version' | '<version>' | string | dynamic | Version number of the SICK software SDK. | |
| 'start_async_after_grab_async' | 'disable', 'enable' | 'enable' | string | pre-defined | Status of 'start_async_after_grab_async'. |
| 'start_column' | <column> | 0 | integer | pre-defined | Returns the current start column of the HALCON image. |
| 'start_row' | <default> | 0 | integer | pre-defined | The value is not used, so a default value is returned. |
| 'use_error_handler' | 0, 1 | 0 | integer | pre-defined | Status of the SICK error handler. |
| 'use_socket_driver' | 0, 1 | 0 | integer | pre-defined | Current driver mode (1: Normal (Socket driver) / 0: Fast (Fast Ethernet driver). |
| 'vertical_resolution' | <default> | 1 | integer | pre-defined | The value is not used, so a default value is returned. |
Operator set_framegrabber_lut
Not supported by this interface.
Operator get_framegrabber_lut
Not supported by this interface.
Operator 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, on every occurrence of the underlying 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.
The signature of the callback function is Herror (__stdcall *HAcqCallback)(void *AcqHandle, void *Context, void *UserContext) and uses the following parameters:
- AcqHandle Acquisition handle of the corresponding image acquisition instance.
- Context Optional context data of the specific callback.
- UserContext User context as set via set_framegrabber_callback.
Note that the execution time of a user-specific callback function should 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.
| Type | Description |
|---|---|
| 'transfer_end' | Corresponds to the end of the buffer copy in SICK callback routine. This callback is called by the frame grabber as soon as there is a full buffer available. See SICK documentation for more details. |
Operator get_framegrabber_callback
This interface supports device specific events via the operators set_framegrabber_callback and get_framegrabber_callback. For more
information see set_framegrabber_callback.
Operator grab_image_start
Starts a new asynchronous grab. See also grab_image_start.
Operator grab_image
grab_image starts a new synchronous grab. See also grab_image. Note that
the interface converts the image from the device to the desired image format
specified by the parameters 'image_width', 'image_height', 'start_row',
'start_column', 'bits_per_channel', and 'color_space'.
Operator grab_image_async
grab_image_async returns an image and starts the next asynchronous grab. See also grab_image_async. Note that the interface converts the image
from the device to the desired image format specified by the parameters
'image_width', 'image_height', 'start_row', 'start_column',
'bits_per_channel', and 'color_space'. 'MaxDelay' argument parameter is
ignored, that means that the image age check is deactivated.
Operator grab_data
The SICK-3DCamera interface allows the grabbing of additional data like mark data or calibrated images. grab_data returns an array of
images instead of a multi-channel image like grab_image or grab_image_async.
See also sections Reading Mark Data and
3D Calibration and Rectification.
| Parameter | Type | Count | Description |
|---|---|---|---|
| 'image' | Depending on the used configuration an array of images is returned. If calibration and rectification is used, the resulting image data is also returned. The names of the images can be queried by the parameter 'channel_names'. The type and the number of images depend on the used configuration. | ||
| 'contours' | Not used. | ||
| 'region' | Not used. | ||
| 'data' | tuple | If mark data is enabled, the values for each component are returned. |
Operator grab_data_async
Same return values as grab_data, but here an asynchronous grab is started.
Operator close_framegrabber
This operator closes the device. See also close_framegrabber.
HDevelop Examples
For this interface there are the following examples available:
- sick-3dcamera.hdev - Benchmark.
- sick-3dcamera_buffer_queue.hdev - Usage of SICK frame grabber's internal queue of buffers.
- sick-3dcamera_calibration.hdev - Usage of calibration and rectification.
- sick-3dcamera_components.hdev - Usage of different parameter sets.
- sick-3dcamera_grabbing_modes.hdev - Usage of the different grabbing modes.
- sick-3dcamera_objectmodel3d.hdev - Acquisition and visualization of SICK calibrated 3D data.
- sick-3dcamera_parameters.hdev - Lists all parameters of a device.
- sick-3dcamera_simple.hdev - A simple example to show the usage of the interface.
Release Notes
- Revision 13.0.3 (Aug 8, 2018):
- The technical dependency from the HALCON Library has been removed.
- Camera Link devices support has been set to legacy.
- Now info_framegrabber(.., 'device'/'info_boards', ..) only lists the available Ethernet devices, but not the Camera Link devices (legacy).
- Now open_framegrabber using 'default' as Device parameter only works for Ethernet devices. Camera Link devices (legacy) are ignored. To open a Camera Link device (Ranger C) the device name has to be indicated, see 'Device' parameter in open_framegrabber.
- Revision 13.0.2 (Jul 14, 2017):
- The registration filter (used for color shifting) was allocated and de-allocated for each grab call, discarding the previous profiles and avoiding the reuse of the data for shifting. This problem has been fixed; and now the allocation is done only once.
- Using a camera configuration with no intensity subcomponent led to a crash in HDevelop when calling a grabbing operator after enabling the rectification filter. This problem has been fixed.
- The HDevelop example sick-3dcamera_objectmodel3d.hdev has been improved by checking if a Range component has been loaded and if the 'Rectified Data (Intensity)' is available.
- 'do_load_parameters' did not re-initialize the calibration, rectification and registration filter, if needed. This problem has been fixed.
- Changing the '<Measurement>number of columns' could lead to a crash in HDevelop. This problem has been fixed.
- Revision 13.0.1 (Oct 28, 2016):
- HALCON 13 version of the interface.
- Revision 6.4 (Jun 24, 2016):
- The interface has been adapted to support SICK iCon API 5.1 SR1.
- The new Generic parameter 'low_level_timeout' has been added to set a low level timeout value for Pleora eBus.
- In case of asynchronous grabbing with 'continuous_grabbing' disabled and 'start_async_after_grab_async' enabled (default mode), a timeout could happen although a new acquired buffer was already available. This problem has been fixed.
- The parameter 'image_available' could be '1' in case of continuous asynchronous grabbing with 'buffer_queue' and 'start_async_after_grab_async' disabled. Since all current buffers in the SICK frame grabber's internal queue will be discarded, in the next grabbing call, 'image_available' must remain '0'. This problem has been fixed.
- Setting 'do_save_parameters' without specifying a value led to a crash. This problem has been fixed.
- The error code H_ERR_FGABORTED (#5336) is now returned by the grab operators when a grab has been aborted instead of the former H_ERR_FGF (#5306).
- In case that the Generic parameter 'use_error_handler' was set to 1 in open_framegrabber, the SICK error handler was not removed in close_framegrabber. This problem been fixed.
- A WoW64 note has been added to the System Requirements section.
- Revision 6.3 (Aug 26, 2015):
- When enabling the 'rectification_filter', only the rectified range was returned. Now the rectified intensity is also returned. Notice that the channel name (value in 'channel_names') for the rectified range has been changed from 'Rectified Data' to 'Rectified Data (Range)'. See section 3D Calibration and Rectification for further information.
- The HDevelop example sick-3dcamera_objectmodel3d.hdev has been adapted to extract and display the 'Rectified Data (Range)' and 'Rectified Data (Intensity)'.
- The rectification width was internally set to the same value as the calibration width. Now this value can be changed via the parameter 'rectification_width'.
- The parameter 'available_param_names' returned some empty parameters and the subcomponents parameters were missing. This problem has been fixed. Notice that with SICK iCon 5 API the <PC> parameters are not available anymore.
- The protocol timeout could not be changed when resetting the camera in close_framegrabber (case 'camera_reset_on_close' = 1), because this SICK parameter has to be accessed in another way with SICK iCon 5 API. This problem has been fixed.
- The Generic parameter 'camera_reset_on_close' is only required for Ethernet devices. For Camera Link devices, this parameter is now ignored and a note has been added to the parameter description in this documentation.
- Revision 6.2 (Jul 22, 2015):
- close_framegrabber crashed if the 'rectification_filter' was enabled. This problem has been fixed.
- The resources used by the rectification filter were not freed when disabling the 'rectification_filter'. This problem has been solved.
- Revision 6.1 (May 4, 2015):
- Adapted to SICK iCon API 5.1.
- Removed extraordinary runtime dependencies.
- When using Measurement Component Hi3D COG with a Ranger D or E, bad images were returned. This problem has been fixed.
- Revision 6.0 (Oct 31, 2014):
- HALCON 12 version of the interface.
- Revision 5.9 (Aug 27, 2014):
- Adapted to SICK iCon API 4.4.3 and eBus driver 3.1.
- Fixed checking relative or absolute path in 'do_save_parameters'.
- Improved error handling of Generic parameter in open_framegrabber.
- Revision 5.8 (May 23, 2014):
- Fixed bug in open_framegrabber when freeing resources in case of an error.
- Improved info_framegrabber(.., 'camera_type', ..). Now the search path is defined by the environment variable IVP_3D_CAMERA.
- Fixed bug in set_framegrabber_param when trying to set a parameter without specifying a value.
- Fixed bug in open_framegrabber when loading a camera parameter (.prm) file. In some cases, the internal state of the SICK parameters was not correctly updated.
- Revision 5.7 Addendum (Mar 20, 2014):
- The LUT file is now set before the calibration filter is enabled in the HDevelop example sick-3dcamera_calibration.hdev and sick-3dcamera_objectmodel3d.hdev.
- Revision 5.7 Addendum (Oct 11, 2013):
- Added, to this documentation, a hint to load the LUT file before the calibration filter is enabled. Here, the internal behaviour of the interface was changed in order to solve a bug in revision 5.4.
- Revision 5.7 (Jul 23, 2013):
- Adapted to SICK iCon API 4.4: support of eBus driver 3.0, static port allocation (see 'Port' parameter in open_framegrabber) and 64-bit Windows support for Ranger C.
- Added Generic parameter 'camera_reset_on_close' as a workaround to solve an internal camera problem in case of Ethernet devices.
- Removed the legacy parameters 'module_path', 'module_name' and 'module_value' used to set/get SICK parameter values. Please use the new handling method for SICK parameters instead (see Release Notes from Aug 23, 2012).
- Removed the legacy parameter 'trigger_mode'. Please use '<Image>trig mode' or '<Measurement>trig mode' instead.
- Fixed bug in open_framegrabber in case of Generic parameter with empty string values.
- Revision 5.6 (May 27, 2013):
- Added new example sick-3dcamera_grabbing_modes.hdev that shows the behavior of the different grabbing modes (asynchronous/synchronous) depending on the following parameters: 'continuous_grabbing', 'buffer_queue' and 'start_async_after_grab_async'.
- Improved example sick-3dcamera_buffer_queue.hdev to show how to recover from overflow in SICK frame grabber's internal queue of buffers by using 'do_abort_grab'.
- Fixed deadlock bug when registering the 'transfer_end' callback after enabling 'continuous_grabbing'.
- Fixed bug in 'image_available' parameter in case of continuous asynchronous grabbing with 'buffer_queue' and 'start_async_after_grab_async' disabled.
- Fixed bug in grab_image_start. Now the camera and frame grabber will be correctly set for the next asynchronous grabbing.
- Changed behavior of the 'continuous_grabbing' enabling. Now the camera and frame grabber will be first started in grab_image_start or in the corresponding grabbing operator.
- Fixed calibration filter bug in case of error in grab_data or grab_data_async.
- Fixed synchronization bug when using more than one camera.
- Revision 5.5 (Mar 25, 2013):
- Fixed bug in case of using only one component with a 16 bit representation.
- Reviewed and adapted documentation.
- Revision 5.4 (Feb 26, 2013):
- Added new parameter 'scan_size' to calculate the current number of buffers in SICK frame grabber's internal queue.
- Added new example sick-3dcamera_buffer_queue.hdev that shows how to use the SICK frame grabber's internal queue of buffers.
- Added new documentation section 'Using SICK frame grabber's internal queue of buffers section'.
- Fixed typo in the documentation: 'parameter_file' to 'parameters_file'.
- Fixed bug when enabling the mark data with set_framegrabber_param.
- Fixed bug in the initialization of the calibration filter that could lead to a corrupted image.
- Fixed thread-safety bug in the initialization of the calibration filter.
- Fixed bug in 'Range R' and 'Range X' images width in case that the 'rectification_filter' is disabled.
- Revision 5.3 (Nov 16, 2012):
- Added new example sick-3dcamera_objectmodel3d.hdev that shows how to acquire and visualize SICK calibrated 3D data.
- Fixed bug in case of image acquisition timeout.
- Documentation improvement regarding SICK parameter handling and 'transfer_end' callback.
- Revision 5.2 (Sep 28, 2012):
- Fixed bug in measurement configuration with only 1 component and 'active_channel' = -1.
- Adapted the HDevelop example sick-3dcamera_components.hdev to be compatible with cameras that only support one single measurement configuration component.
- Fixed bug when changing some SICK parameters with 'Argument' type (e.g., '<Measurement>scan height'). Now, if the data from the camera has changed, not only the camera and the frame grabber are stopped, but also disconnected.
- Improvement in info_framegrabber(.., 'defaults', ..): Now the 'device' parameter default value is 'default' (instead of '0'). When using the 'default' value in open_framegrabber, the first Ethernet (or Camera Link) device found will be opened.
- Revision 5.1 (Aug 23, 2012):
- The open_framegrabber input parameter 'ExternalTrigger' has been deprecated to avoid confusion with SICK trigger mode methodology. Now this parameter is ignored and current camera configuration is kept. Please notice that your code may require an adaptation. Notice that, in case of 'ExternalTrigger'='true', 'use enable' was set to '2' and in case of 'ExternalTrigger'='false', 'use enable' was set to '0'.
- Fixed bug in the 'Rectified Data'. If a high-resolution measurement component was available, the 'Rectified Data' width was not correctly set. Now 'Range R' and 'Rectified Data' have the same width.
- Fixed bug in parameter 'channel_names'. When enabling the calibration/ rectification filter, in case of only 1 measurement component, 'channel_names' was not correctly updated.
- Improvement in parameter 'rectification_filter'. Now to enable this parameter, the 'calibration_filter' has to be previously enabled.
- Improvement to verify if the Ethernet camera application version is compatible (>= 4.3.0.88) with the fast driver mode. If not compatible an error is returned.
- Adapted grab engine to allow the use of frame grabber's internal queue of buffers in case of 'continuous_grabbing' enabled and improve CPU usage.
- Added new parameter 'buffer_queue' to enable/disable the use of the frame grabber's internal queue of buffers.
- Removed Generic parameter 'num_buffers' to avoid confusion with frame grabber's internal queue of buffers.
- Fixed bug in 'grab_timeout' parameter. Now '-1'(INFINITE) value is correctly set.
- Added 'do_abort_grab' functionality.
- Adapted parameter 'camera_status' to also show Ranger C camera status.
- Added implementation of queries info_framegrabber (.., 'info_boards', ..) and info_framegrabber (.., 'device', ..) to also list Ranger C devices in case of 32 bit OS. In case of 'info_boards', more detailed information is returned.
- Updated the HDevelop example sick-3dcamera.hdev to use info_framegrabber(.., 'device', ..) query to list the available devices.
- Fixed bug in parameter 'active_channel' when changing from one channel to another channel with bigger image width.
- Fixed bug in parameter 'configuration'. Now after changing the configuration, 'active_channel' is set to '-1' in case of 'measurement' configuration and to '0' in case of 'image' configuration.
- Added new parameter handling method for SICK parameters. Values can be set/get using set_framegrabber_param/get_framegrabber_param. The name of the parameter needs a prefix to indicate the corresponding configuration and component (e.g. '<Measurement><Gray 2>start row'). Use 'available_param_names' parameter to obtain a list of the current available parameters.
- Added new parameters 'available_param_names' and 'available_param_descriptions' to list the current available parameters and the corresponding description.
- The parameters 'module_path', 'module_name' and 'module_value' are set legacy (not available in HDevelop Image Acquisition Assistant).
- The parameter 'trigger_mode' is set legacy (not available in HDevelop Image Acquisition Assistant). Instead, use '<Image>trig mode' or '<Measurement>trig mode'.
- Updated the HDevelop examples sick-3dcamera_components.hdev and sick-3dcamera_parameters.hdev to show the new parameters handling method.
- Added functionality to handle 'transfer_end' callback and the new parameter 'available_callback_types'.
- Improved parameter handling in HDevelop Image Acquisition Assistant.
- Added new parameters 'do_load_parameters' and 'parameters_file' to be able to load previous saved configurations (.prm file).
- Updated the HDevelop example sick-3dcamera_components.hdev to show how to use the new parameters 'do_load_parameters' and 'parameters_file'.
- Revision 5.0 (May 15, 2012):
- HALCON 11 version of the interface (included in HALCON 11 DVD).
- 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 (driver mode: Normal).
- Added setting of 'redundancy frequency' and 'heartbeat 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/grab_image_async and grab_data/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 necessary 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.