LOG OUT
interfaces mvtec

Dokumentation

Image Acquisition Interface for SICK 3D Cameras

Interface: SICK-3DCamera
Revision: 6.5
Date: 2017-07-14
HALCON Version: 12.0

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 or Windows 7 x64. 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:
    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.
  • Linux: Extract the archive containing the interface files to the HALCON base directory $HALCONROOT.

Features

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.

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 Message: Connected: Queue size: 11 @512x9216 bytes. Driver mode: Fast"

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>'] or ['<device_id>'] string dynamic Returns the list of available devices if possible. Otherwise, a place-holder is returned.
'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'
  • Ethernet: ['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>']
  • Camera Link: ['device:<device_id> | manufacturer:<camera_link_ board_manufacturer> | device_COM:<COM_port>']
string dynamic Returns the list of available devices with additional information. The listed information is different for Ethernet and Camera Link device.
'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:
  • buffer_size: Set the internal buffer size in Megabyte. Only valid for Ethernet cameras. Default: 50.
  • camera_reset_on_close: Enable the camera reset in close_framegrabber as a workaround to an internal camera problem for Ethernet devices (in case of repeatedly opening and closing the device). Notice that this setting can considerably increase the execution time of close_framegrabber, therefore use it only if necessary (for instance, every 20 open and close iterations). For Camera Link devices this parameter has no effect.
  • low_level_timeout: Set a low level timeout value in milliseconds for Pleora eBus to guarantee that buffer callbacks occur without delays even if network packets are lost. Default: 0 (infinite).
  • use_error_handler: Enable the SICK error handler to show the same error messages as in Ranger Studio.
  • use_socket_driver: This setting makes it possible to use the socket driver (driver mode: Normal) instead of the new Fast Ethernet driver (driver mode: Fast). Notice that fast driver mode requires the Ethernet camera version 4.3.0.88 (or higher).
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:
  • Camera Link device: used camera port on the X64-CL board.
  • Ethernet device: if default value (0) used, then the port will be dynamically allocated, otherwise the value will be used to allocate the port statically and in that case, the 'port'+1 value will be internally used as redundancy port. Therefore, notice that in case of using more than one camera, the port values should not be consecutive values (e.g. set port 1000 for the first camera and port 1002 for the second camera). Static allocation shall only be used if the dynamic port reservation causes trouble or for some reason, the port to be used has to be exactly specified. Notice that in case of using the socket driver ('use_socket_driver=1'), the static port allocation is not possible and, therefore, the port has to be set to the default value (0).
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:
    • if synchronous grabbing (grab_image/grab_data): next available buffer in SICK frame grabber's internal queue of buffers is delivered.
    • if asynchronous grabbing (grab_image_async/grab_data_async) and 'start_async_after_grab_async' and 'buffer_queue' disabled: next available buffer in SICK frame grabber's internal queue of buffers is delivered.
'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:
    • if synchronous grabbing (grab_image/grab_data): next available buffer in SICK frame grabber's internal queue of buffers is delivered.
    • if asynchronous grabbing (grab_image_async/grab_data_async) and 'start_async_after_grab_async' and 'buffer_queue' disabled: next available buffer in SICK frame grabber's internal queue of buffers is delivered.
'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.
Using user-callback functions

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 6.5 (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 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.
Produkte/MVTec-Schnittstellen