Dokumentation
Image Acquisition Interface for SICK ScanningRuler
| Interface: | SICK-ScanningRuler |
| Revision: | 5.1 |
| Date: | 2014-09-12 |
| HALCON Version: | 11.0 |
- General
- System Requirements
- Features
- Limitations
- 3D Calibration and Rectification
- Representation of Images in Ranger Studio and HALCON
- 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-ScanningRuler image acquisition interface for
Scannning Ruler cameras.
Registered customers can download the
latest revision of this interface from the
MVTec WWW server.
System Requirements
- Intel compatible PC with Windows XP/7 or Windows XP x64/7 x64, also WoW64 (using 32-bit HALCON on 64-bit Windows).
- Gigabit Ethernet adapter supporting Jumbo Frames with successfully installed eBUS driver (version 3.1). Note that Intel Gigabit network adapters are recommended.
- Successfully installed SICK icon API version 5.1. Please make sure that the icon_51.dll (or icon_51_x64.dll, respectively), is available via the %PATH% environment variable.
- Visual Studio C++ 2005 SP1 Redistributable Runtime Package, particularly
msvcp80.dll and msvcr80.dll. If this package is not
installed please download and install it from the Microsoft Download
Center for Windows x86 or
Windows x64.
Visual Studio C++ 2008 SP1 Redistributable Runtime Package, particularly msvcp90.dll and msvcr90.dll. If this package is not installed please download and install it from the Microsoft Download Center for Windows x86 or Windows x64.
Note: It is not sufficient to copy the missing files! - HALCON image acquisition interface hAcqSICK-ScanningRuler.dll or hAcqSICK-ScanningRulerxl.dll, respectively. If you have installed the interface properly, both DLLs should reside in bin\%HALCONARCH% within the HALCON base directory %HALCONROOT% you have chosen during the installation of HALCON.
Features
- Access to measurement component and sub-components via image tuples (with grab_data/grab_data_async).
- Access to calibrated and rectified measurement data via grab_data/grab_data_async.
- Support of hardware and software trigger.
- Software control of all camera parameters.
Limitations
- No support of Traits to get further information about the x and y values in case of rectifying the 3D images.
- Only measurement mode is supported, image mode is not supported.
- Changing parameters in Ranger Studio when using HDevelop in parallel can lead to an invalid parameters configuration.
3D Calibration and Rectification
The SICK ScanningRuler is configured by default to deliver calibrated 3D data and always use the same setup of components and sub-components: one component - CIR, which contains four sub-components - X, Y, Z and Intensity. When using grab_data/grab_data_async to access the 3D data an image array is returned containing these four sub-components: ['Cir 1 (X)', 'Cir 1 (Y)', 'Cir 1 (Z)', 'Cir 1 (Intensity)']
If the rectification is enabled via configuration file (.icx), the calibrated and rectified data can be also accessed using grab_data/grab_data_async. In this case, the returned image array contains only two sub-components: ['Cir 1 (Z) - Rectified', 'Cir 1 (Intensity) - Rectified']
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.
Parameters for info_framegrabber
| Parameter | Value List | Type | Kind | Description |
|---|---|---|---|---|
| 'bits_per_channel' | [] | Unsupported query. | ||
| 'camera_type' | ['CAMFILE:', 'icx;prm', '<path>', 'default'] | string | pre-defined | Syntax for camera file and default value. |
| 'color_space' | [] | Unsupported query. | ||
| 'defaults' | [0, 0, 0, 0, 0, 0, 'default', -1, 'default', -1.0, 'false', 'default', 'default', -1, -1] | mixed | pre-defined | Default values for open_framegrabber. |
| 'device' | ['<ip_address>'] | string | dynamic | Returns the list of available devices if possible. Otherwise, a place-holder is returned. |
| 'external_trigger' | [] | Unsupported query. | ||
| 'field' | [] | Unsupported query. | ||
| 'general' | [] | string | pre-defined | Information about the HALCON SICK-ScanningRuler interface. |
| 'generic' | [' ', 'buffer_size=<MB>', 'use_error_handler=1'] | string | pre-defined | Value list for the Generic parameter. |
| 'horizontal_resolution' | [] | Unsupported query. | ||
| '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 devices with additional information. |
| 'line_in' | [] | Unsupported query. | ||
| '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' | [] | Unsupported query. | ||
| 'revision' | '<revision>' | string | pre-defined | Revision number of the SICK-ScanningRuler interface. |
| 'start_column' | [] | Unsupported query. | ||
| 'start_row' | [] | Unsupported query. | ||
| 'vertical_resolution' | [] | Unsupported query. |
Parameters for open_framegrabber
| Parameter | Values | Default | Type | Description |
|---|---|---|---|---|
| Name | 'SICK-ScanningRuler' | string | Name of the HALCON interface. | |
| HorizontalResolution | --- | Ignored. The value in the icx/prm-file (or the current setting of the camera) is used. | ||
| VerticalResolution | --- | Ignored. The value in the icx/prm-file (or the current setting of the camera) is used. | ||
| ImageWidth | --- | Ignored. The value in the icx/prm-file (or the current setting of the camera) is used. | ||
| ImageHeight | --- | Ignored. The value in the icx/prm-file (or the current setting of the camera) is used. | ||
| StartRow | --- | Ignored. The value in the icx/prm-file (or the current setting of the camera) is used. | ||
| StartColumn | --- | Ignored. The value in the icx/prm-file (or the current setting of the camera) is used. | ||
| Field | --- | Ignored. | ||
| BitsPerChannel | --- | Ignored. The value in the icx/prm-file (or the current setting of the camera) is used. | ||
| ColorSpace | --- | Ignored. | ||
| Generic | ' ', ['buffer_size=<MB>', 'use_error_handler=1'], -1 | -1 | mixed | Generic parameters:
|
| ExternalTrigger | --- | Ignored. The value in the icx/prm-file (or the current setting of the camera) is used. | ||
| CameraType | '<icx_file>', '<prm_file>', 'default' | 'default' | string | Name of the configuration file (.icx) or the camera parameter file (.prm). Notice that the following parameter values are ignored: 'camera IP address', 'frame grabber memory', 'buffer callbacks enabled' and 'calibration enabled'. In case of 'default', the current loaded settings on the camera are used. |
| Device | '<ip_address>' | 'default' | string | The IP address of the camera. In case of 'default', the IP address of the first device found will be used. |
| Port | --- | Ignored. | ||
| 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 (icx/prm). Therefore, use
get_framegrabber_param(...,'available_param_names', ...) to obtain
a tuple containing all available parameters of the connected camera. To set
a camera parameter, e.g. the 'gain' of the 'Cir 1' component in
'Measurement', the user can call set_framegrabber_param(...,
'<Camera><Measurement><Cir 1>gain', ...). Note that
the camera will be internally stopped before changing the
parameter and the data format will be automatically updated if required.
| Parameter | Values | Type | Description |
|---|---|---|---|
| 'do_abort_grab' | --- | Aborts the current image acquisition. | |
| 'do_load_parameters' | --- | Load the parameter settings file specified in 'parameters_file' parameter. Notice that the following parameter values are ignored: 'camera IP address', 'frame grabber memory', 'buffer callbacks enabled' and 'calibration enabled'. | |
| 'do_save_parameters' | '<icx_file>', '<prm_file>' | string | Save the parameter settings to the specified filename (icx/prm file). |
| 'do_software_trigger' | --- | Executes software trigger. Note that the device has to be in trigger mode, that means that the SICK parameter
' |
|
| 'grab_timeout' | <milliseconds> | integer | Specify the desired timeout (milliseconds) for aborting a pending grab. If -1 is specified, the timeout is set to INFINITE. |
| 'invalid_data_value' | <value> | float | Value that substitutes invalid (NaN) pixel values delivered by the device. |
| 'parameters_file' | '<icx_file>', '<prm_file>' | string | Parameter file name (e.g. C:\icx-files\ScanningRuler.icx) to be used by 'do_load_parameters' action parameter. |
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]. Optionally, this tuple can also contain additional valid string values like 'auto' or 'manual'.
- '_values': These parameters provide the valid value list for the corresponding parameter as a tuple, e.g., get_framegrabber_param(..,'volatile_values',..) will return the output tuple ['enable','disable'].
- '_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 (icx/prm). Therefore, use get_framegrabber_param(...,'available_param_names', ...) to obtain a tuple containing all available parameters of the connected camera. To get a camera parameter, e.g. the current 'gain' of the 'Cir 1' component in 'Measurement', the user can call get_framegrabber_param(..., '<Camera><Measurement><Cir 1>gain', ...).| Parameter | Values | Default | Type | Kind | Description |
|---|---|---|---|---|---|
| '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. | |
| 'bits_per_channel' | <default> | -1 | integer | pre-defined | The value is not used, so a default value is returned. |
| 'camera_status' | '<status>' | string | dynamic | Current status of the ScanningRuler. | |
| 'camera_type' | '<icx_file>', '<prm_file>', 'default' | 'default' | string | pre-defined | Name of the configuration file (.icx) or the camera parameter file (.prm). If 'default', the current loaded settings on the camera are used. |
| 'channel_names' | '<channel names>' | string | dynamic | Names of the data channels. Format: 'Component Name (Measure)' (e.g. ['Cir 1 (X)', 'Cir 1 (Y)', 'Cir 1 (Z)', 'Cir 1 (Intensity)']). | |
| 'color_space' | '<default>' | 'default' | string | pre-defined | The value is not used, so a default value is returned. |
| 'device' | '<ip_address>' | string | dynamic | IP address of the device. | |
| 'external_trigger' | '<default>' | 'false' | string | pre-defined | The value is not used, so a default value is returned. |
| 'field' | '<default>' | 'default' | string | pre-defined | The value is not used, so a default value is returned. |
| 'generic' | ' ', ['buffer_size=<MB>', 'use_error_handler=1'], -1 | -1 | mixed | pre-defined | Values of the Generic parameter. |
| 'grab_timeout' | <milliseconds> | 15000 | integer | pre-defined | Current grab timeout in milliseconds. |
| 'horizontal_resolution' | <default> | integer | pre-defined | Current value of horizontal resolution. | |
| 'image_height' | <height> | integer | pre-defined | Current image height. | |
| 'image_width' | <width> | integer | pre-defined | Current image width. | |
| 'invalid_data_value' | <value> | 0.0 | float | dynamic | Value that substitutes invalid (NaN) pixel values delivered by the device. |
| 'line_in' | <default> | -1 | integer | pre-defined | The value is not used, so a default value is returned. |
| 'name' | 'SICK-ScanningRuler' | string | pre-defined | Name of the HALCON interface. | |
| 'parameters_file' | '<icx_file>', '<prm_file>' | string | dynamic | Parameter file name (e.g. C:\icx-files\ScanningRuler.icx) to be used by 'do_load_parameters' action parameter. | |
| 'port' | '<default>' | -1 | integer | pre-defined | The value is not used, so a default value is returned. |
| 'revision' | '<revision>' | string | pre-defined | Revision number of the SICK-ScanningRuler interface. | |
| 'start_column' | <default> | integer | pre-defined | The value is not used, so a default value is returned. | |
| 'start_row' | <default> | 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. |
| 'vertical_resolution' | <default> | integer | pre-defined | Current value of vertical resolution. |
Operator set_framegrabber_lut
Not supported by this interface.
Operator get_framegrabber_lut
Not supported by this interface.
Operator set_framegrabber_callback
Not supported by this interface.
Operator get_framegrabber_callback
Not supported by this interface.
Operator grab_image_start
grab_image_start has no effect in this interface.
Operator grab_image
grab_image gets the next available buffer in SICK frame grabber's internal queue of buffers and returns the CIR-Z sub-component.
Operator grab_image_async
grab_image_async gets the next available buffer in SICK frame grabber's internal queue of buffers and returns the CIR-Z sub-component.
'MaxDelay' argument parameter is ignored, that means that the image
age check is deactivated.
Operator grab_data
The SICK-ScanningRuler interface allows the grabbing of calibrated data and rectified data. grab_data gets the next available buffer in SICK
frame grabber's internal queue of buffers and returns an array of
images containing the CIR sub-components. For further information see
section
3D Calibration and Rectification.
| Parameter | Type | Count | Description |
|---|---|---|---|
| 'image' | Depending on the used configuration (calibrated data or calibrated and rectified data) the corresponding array of images is 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. Please refer to section
3D Calibration and Rectification
for more information about how to enable these configurations.
|
||
| 'contours' | Not used. | ||
| 'region' | Not used. | ||
| 'data' | Not used. |
Operator grab_data_async
Same return values as grab_data.
Operator close_framegrabber
This operator closes the device. See also close_framegrabber.
HDevelop Examples
For this interface there are the following examples available:
- sick-scanningruler_objectmodel3d.hdev - Acquisition and visualization of ScanningRuler calibrated 3D data.
- sick-scanningruler_parameters.hdev - Lists all parameters of a device.
- sick-scanningruler_simple.hdev - A simple example to show the usage of the interface.
Release Notes
- Revision 5.1 (Sep 12, 2014):
- Changed from SICK icon API version 5.0 to 5.1.
- Added 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. '<Camera><Measurement><Cir 1>gain'). Use 'available_param_names' parameter to obtain a list of the current available parameters.
- Adapted the HDevelop example sick-scanningruler_objectmodel3d.hdev to show how to disable the rectification filter and enable the trigger mode using the parameter handling method for SICK parameters.
- Added new parameter 'available_param_descriptions' to list the description of the current available parameters.
- Added new parameters 'do_load_parameters' and 'parameters_file' to be able to load previous saved configurations (icx/prm file).
- Added new parameter 'do_save_parameters' to save the current configuration (icx/prm file).
- Added new parameter 'invalid_data_value' that substitutes invalid (NaN) pixel values delivered by the device.
- Revision 5.0 (May 23, 2014):
- First official release.