MVTec Software GmbH
 
O3D3xx / HALCON 13.0 / MVTec Software GmbH

Image Acquisition Interface for ifm 3D Time of Flight Cameras (O3D3xx)

Interface: O3D3xx
Revision: 13.0.2
Date: 2017-06-19
HALCON Version: 13.0

General

This page provides the documentation of the HALCON image acquisition interface for ifm 3D time of flight cameras (O3D3xx). 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, also WoW64 (using 32-bit HALCON on 64-bit Windows), or Linux with kernel 2.6 (or higher).
  • Windows: HALCON image acquisition interface hAcqO3D3xx.dll or hAcqO3D3xxxl.dll, respectively. If you have properly installed the interface, all these DLLs should reside in bin\%HALCONARCH% within the HALCON base directory %HALCONROOT% you have chosen during the installation of HALCON.
    Linux: HALCON image acquisition interface hAcqO3D3xx.so or hAcqO3D3xxxl.so, respectively. If you have properly installed the interface, the shared objects should reside in lib\$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.

Description

  • Synchronous and asynchronous grabbing of x, y, and z images, amplitude and distance image, and some diagnostic data.
  • Grabbing of the data delivered by the 3D time of flight camera (O3D3xx) using the 'halcon_application' inside the camera. Synchronous grabs can switch the trigger mode of the application. If the camera is currently in 'free_run' mode, it is switched to the trigger mode 'process_interface'. Before each synchronous grab, a software trigger is implicitly sent and ignores all images stored in the camera buffer. This can cause a delay if the synchronous grab has to switch the trigger mode since then possibly the complete buffer of the camera has to be flushed. In case that a synchronous grab changed the trigger mode, this setting is reverted by the next call of an asynchronous grab or close_framegrabber. An asynchronous grab gets the next image on the camera if it is set to 'free_run' or to an external trigger source. In case that the trigger mode is set to 'process_interface', grab_image_start performs a software trigger and after each asynchronous grab a software trigger is performed, too. Nevertheless, if a manual software trigger was executed before grabbing asynchronously, the image from this trigger is received.
  • If the camera is opened for the first time from HALCON, a new application ('halcon_application') will be created on the camera so that all settings that are made do not influence other applications. In case that the 'halcon_application' already exists and is not active it will be activated.
  • Get and set parameters of the camera.
  • XMLRPC fault messages are returned as Low Level Errors in HALCON.

Limitations

  • Switching from 'trigger_mode' 'free_run' to any other mode flushes the camera buffers. This might take up to 1.5s and is implicitly done when using synchronous grabs after asynchronous grabbing.
  • Automatic discovery of the camera on the network is not supported. You need to know the camera's IP address. Also you cannot switch the camera's IP address from within HALCON.
  • The password protection has to be turned off on the camera in order to use the camera in HALCON.
  • Creation and modification of camera applications other than 'halcon_application' is not possible.
  • Automatic optimization of the parameters 'exposure_time' and 'exposure_time_ratio' is not possible.
  • The interface only supports process interface version 3.
  • Settings and applications cannot be imported or exported.
  • It is not possible to choose which images should be returned by the sensor.
  • The parameter 'binning' is only available with firmware version 1.3.1001 or higher.
  • The ability for setting the 'binning' value to 1 is disabled since firmware version 1.6.2038.

Parameters for info_framegrabber

Parameter Value List Type Kind Description
'defaults' [0, 0, 0, 0, 0, 0, 'default', 0, 'default', -1, 'false', 'default', 'default', -1, 0] mixed pre-defined Default values for open_framegrabber.
'general' [] string pre-defined Information about the HALCON O3D3xx interface.
'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.
'revision' '<revision>' string pre-defined Revision number of the O3D3xx interface.

Parameters for open_framegrabber

The interface checks if the application 'halcon_application' exists on the camera. Otherwise it will be created and set as active application. If this application already exists, it is checked if it is active and if necessary, it will be activated. The timeout for connecting with the camera can be set by a generic parameter.
Parameter Values Default Type Description
Name 'O3D3xx' 'O3D3xx' string Name of the HALCON interface.
HorizontalResolution --- Unused.
VerticalResolution --- Unused.
ImageWidth --- Unused.
ImageHeight --- Unused.
StartRow --- Unused.
StartColumn --- Unused.
Field --- Ignored.
BitsPerChannel --- Unused.
ColorSpace --- Unused.
Generic '', 'connect_timeout=<milliseconds>', -1 -1 mixed With the generic parameter, the timeout that is used during the connection with the camera can be specified.
ExternalTrigger --- Unused.
CameraType --- Unused.
Device 'default', '<ip_address>' default string The device has to be identified by the IP address. If default is chosen, the standard IP address '192.168.0.69' is used to identify the camera.
Port --- Unused.
LineIn --- Unused.

Parameters for set_framegrabber_param

Read the camera manual for further details of the parameters.
Parameter Values Default Type Description
'binning' 1, 2 2 integer Enable or disable binning on the camera. If the binning is set to 2 the resulting resolution is 176x132. Otherwise the sensor will return the full resolution of 352x264.
'camera_name' '<camera_name>' 'New Sensor' string Name of the camera (max. 64 characters).
'channel' 0, 1, 2, 3 0 integer Frequency channel.
'description' '<description>' '' string Description of the camera (max. 500 characters).
'distance_unit' 'millimeter','meter' 'millimeter' string If the parameter 'pixel_format' is set to 'Mono32F', this parameter specifies the unit of distance for the X-, Y-, Z- and distance image.
'do_software_trigger' any 1 any Action parameter that performs a software trigger. In order to perform a software trigger, the parameter 'trigger_mode' has to be set to 'process_interface'. The forwarded value will be ignored and can be set arbitrarily.
'exposure_time' 1...10000 1000 integer Exposure time of the long exposure in milliseconds. This parameter is only available if the parameter 'imager_configuration_type' is set to a value ending with '_low' or '_moderate'.
'exposure_time_ratio' 2...50 40 integer Ratio of the long exposure time to the short exposure time. This parameter is only available if the parameter 'imager_configuration_type' is set to a value ending with '_moderate'.
'frame_rate' 0.0167 ... 30 5 float Frame rate of the camera in frames per second.
'grab_timeout' <milliseconds> 5000 integer Desired timeout (milliseconds) for aborting a pending grab. If -1 is specified, the timeout is set to INFINITE.
'imager_configuration_type' 'under5m_low', 'under5m_moderate', 'under5m_high', 'upto30m_low', 'upto30m_moderate', 'upto30m_high', 'morethan30m_low', 'morethan30m_moderate' 'under5m_low' string Configuration type of the imager. This parameter also specifies the availability of the parameters 'exposure_time' and 'exposure_time_ratio'.
'mask_size' '3x3', '5x5' '3x3' string Mask size of the spatial filter. This parameter is only available if the parameter 'spatial_filter_type' is not set to 'off'.
'number_of_images' 2...25 2 integer Number of images used for the temporal mean filter. This parameter is only available if the parameter 'temporal_filter_type' is set to 'temporal_mean_filter'.
'pixel_format' 'Raw16','Mono32F' 'Raw16' string The format of the returned images is switched with this parameter. If Raw16 is used, the images will be returned in the format as given by the sensor (X, Y and Z as int2 images, distance and amplitude image as uint2 images). If 'Mono32F' is chosen all images, except the confidence image, will be internally converted into a real image. In both cases the confidence image is returned as byte image. For 'Raw16' the parameter 'distance_unit' is ignored.
'spatial_filter_type' 'off', 'median_filter', 'mean_filter', 'bilateral_filter' 'off' string Spatial filter that is used on the camera after acquisition. This parameter also specifies the availability of the parameter 'mask_size'.
'temporal_filter_type' 'off', 'temporal_mean_filter', 'adaptive_exponential_filter' 'off' string Temporal filter that is used on the camera after acquisition. This parameter also specifies the availability of the parameter 'number_of_images'.
'temporary_channel' 0, 1, 2, 3 0 integer Temporarily set the frequency channel. This parameter can be set while the camera is in run mode, however, this parameter is not persistent and is lost when setting any non-temporary parameter.
'temporary_exposure_time' 1...10000 1000 integer Temporarily set the value of the exposure time of the long exposure in milliseconds. This parameter can be set while the camera is in run mode. However, this parameter is only available if the parameter 'imager_configuration_type' is set to a value ending with '_low' or '_moderate'. This parameter is not persistent and is lost when setting any non-temporary parameter.
'temporary_exposure_time_ratio' 2...50 40 integer Temporarily set the value of the ratio of the long exposure time to the short exposure time. This parameter can be set while the camera is in run mode. However, this parameter is only available if the parameter 'imager_configuration_type' is set to a value ending with '_moderate'. This parameter is not persistent and is lost when setting any non-temporary parameter.
'trigger_mode' 'free_run', 'process_interface', 'positive_edge', 'negative_edge', 'positive_and_negative_edge' 'free_run' string Triggered mode. In 'free_run' mode the camera continuously captures images (and buffers up to 50 images on the internal camera storage). If set to 'process_interface' the camera only captures an image if a software trigger is send (this feature is not yet implemented). The last three modes correspond to the hardware trigger.

Parameters for get_framegrabber_param

There may exist additional read-only parameters with the following postfixes:
  • '_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'].

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.

Parameter Values Default Type Kind Description
'article_number' '<article_number>' 'O3D300' string dynamic Article number of the camera.
'binning' 1, 2 2 integer dynamic Enable or disable binning on the camera. If the binning is set to 2 the resulting resolution is 176x132. Otherwise the sensor will return the full resolution of 352x264.
'camera_name' '<camera_name>' 'New Sensor' string dynamic Name of the camera (max. 64 characters).
'channel' 0, 1, 2, 3 0 integer dynamic Frequency channel.
'description' '<description>' '' string dynamic Description of the camera (max. 500 characters).
'device' '<ip_address>' '192.168.0.69' string dynamic IP address of the camera.
'device_port' <device_port> 50010 integer dynamic Port number of the PCIC socket as documented in the ifm manual.
'distance_unit' 'millimeter','meter' 'millimeter' string dynamic If the parameter 'pixel_format' is set to 'Mono32F', this parameter specifies the unit of distance for the X-, Y-, Z- and distance image.
'exposure_time' 1...10000 1000 integer dynamic Exposure time of the long exposure in milliseconds. This parameter is only available if the parameter 'imager_configuration_type' is set to a value ending with '_low' or '_moderate'.
'exposure_time_ratio' 2...50 40 integer dynamic Ratio of the long exposure time to the short exposure time. This parameter is only available if the parameter 'imager_configuration_type' is set to a value ending with '_moderate'.
'firmware_version' '<firmware_version>' '' string dynamic Firmware version installed on the camera.
'frame_rate' <fps> 5 float dynamic Frame rate of the camera in frames per second.
'grab_timeout' <milliseconds> 5000 integer pre-defined Current grab timeout in milliseconds.
'image_height' <image_height> 132 integer pre-defined Current image height.
'image_width' <image_width> 176 integer pre-defined Current image width.
'imager_configuration_type' 'under5m_low', 'under5m_moderate', 'under5m_high', 'upto30m_low', 'upto30m_moderate', 'upto30m_high', 'morethan30m_low', 'morethan30m_moderate' 'under5m_low' string dynamic Configuration type of the imager. This parameter also specifies the availability of the parameters 'exposure_time' and 'exposure_time_ratio'.
'mask_size' '3x3', '5x5' '3x3' string dynamic Mask size of the spatial filter. This parameter is only available if the parameter 'spatial_filter_type' is not set to 'off'.
'name' 'O3D3xx' 'O3D3xx' string pre-defined Name of the HALCON interface.
'number_of_images' 2...25 2 integer dynamic Number of images used for the temporal mean filter. This parameter is only available if the parameter 'temporal_filter_type' is set to 'temporal_mean_filter'.
'pixel_format' 'Raw16','Mono32F' 'Raw16' string dynamic The format of the returned images is switched with this parameter. If Raw16 is used, the images will be returned in the format as given by the sensor (X, Y and Z as int2 images, distance and amplitude image as uint2 images). If 'Mono32F' is chosen all images, except the confidence image, will be internally converted into a real image. In both cases the confidence image is returned as byte image. For 'Raw16' the parameter 'distance_unit' is ignored.
'revision' '<revision>' string pre-defined Revision number of the O3D3xx interface.
'spatial_filter_type' 'off', 'median_filter', 'mean_filter', 'bilateral_filter' 'off' string dynamic Spatial filter that is used on the camera after acquisition. This parameter also specifies the availability of the parameter 'mask_size'.
'temporal_filter_type' 'off', 'temporal_mean_filter', 'adaptive_exponential_filter' 'off' string dynamic Temporal filter that is used on the camera after acquisition. This parameter also specifies the availability of the parameter 'number_of_images'.
'trigger_mode' 'free_run', 'process_interface', 'positive_edge', 'negative_edge', 'positive_and_negative_edge' 'free_run' string dynamic Current state of the triggered mode. In 'free_run' mode the camera continuously captures images (and buffers up to 50 images on the internal camera storage. If set to 'process_interface' the camera only captures an image if a software trigger is send (this feature is not yet implemented). The last three modes correspond to the hardware trigger.
'xmlrpc_port' <xmlrpc_port> 80 integer dynamic Port number of the socket used for the XMLRPC communication.

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

Starts a new asynchronous grab. See also grab_image_start. If a synchronous grab changed the trigger mode this setting is reverted. In case that the trigger mode is set to 'process_interface' grab_image_start sends a software trigger in order to start an asynchronous grab. However, if a software trigger is send via set_framegrabber_param the image captured with this trigger will be returned by the next asynchronous grab.

Operator grab_image

grab_image starts a new synchronous grab. See also grab_image. In case of the trigger mode set to 'free_run' it will be implicitly changed to 'process_interface'. The image buffer on the camera is flushed to ensure that a new image is captured. The z-image is returned in Cartesian coordinates as int2 or real, depending on the value of the 'pixel_format'. The unit is millimeter, but if the 'pixel_format' is set to 'Mono32F', the unit can be changed to meter using the 'distance_unit' parameter.

Operator grab_image_async

grab_image_async starts a new asynchronous grab. See also grab_image_async. If a synchronous grab changed the trigger mode this setting is reverted. In case that the trigger mode is set to 'process_interface' manually a software trigger is performed after retrieving the image from the camera. The parameter 'MaxDelay' is ignored. The z-image is returned in Cartesian coordinates as int2 or real, depending on the value of the 'pixel_format'. The unit is millimeter, but if the 'pixel_format' is set to 'Mono32F', the unit can be changed to meter using the 'distance_unit' parameter.

Operator grab_data

grab_data returns six images synchronously. In case of the trigger mode set to 'free_run' it will be implicitly changed to 'process_interface'. The image buffer on the camera is flushed to ensure that a new image is captured. In addition the tuple Data holds some diagnostic data that is provided with the images and the exposure times for this frame.
Parameter Type Count Description
'image' 6 This parameter returns all six images delivered by the camera during the acquisition.
  • x-image in Cartesian coordinates (int2 in millimeter or real in millimeter or meter)
  • y-image in Cartesian coordinates (int2 in millimeter or real in millimeter or meter)
  • z-image in Cartesian coordinates (int2 in millimeter or real in millimeter or meter)
  • normalized amplitude image (uint2 or real)
  • distance image (uint2 in millimeter or real in millimeter or meter)
  • confidence image (byte)
'data' 12 This tuple holds the diagnostic data delivered during the grab of the current images.
  • illumination temperature in 0.1 degree Celsius
  • frontend temperature 1 in 0.1 degree Celsius
  • frontend temperature 2 in 0.1 degree Celsius
  • i.mx6 temperature in 0.1 degree Celsius
  • processing time in ms
  • framecount of the data
  • timestamp of the data in µs (deprecated)
  • timestamp of the data in s
  • timestamp of the data in ns
  • exposure time 1 of the frame
  • exposure time 2 of the frame
  • exposure time 3 of the frame

Operator grab_data_async

grab_data_async returns six images asynchronously. If a synchronous grab changed the trigger mode this setting is reverted. In case that the trigger mode is set to 'process_interface' manually a software trigger is performed after retrieving the image from the camera. The parameter 'MaxDelay' is ignored. In addition the tuple Data holds some diagnostic data that is provided with the images.
Parameter Type Count Description
'image' 6 This parameter returns all six images delivered by the camera during the acquisition.
  • x-image in Cartesian coordinates (int2 in millimeter or real in millimeter or meter)
  • y-image in Cartesian coordinates (int2 in millimeter or real in millimeter or meter)
  • z-image in Cartesian coordinates (int2 in millimeter or real in millimeter or meter)
  • normalized amplitude image (uint2 or real)
  • distance image (uint2 in millimeter or real in millimeter or meter)
  • confidence image (byte)
'data' 12 This tuple holds the diagnostic data delivered during the grab of the current images.
  • illumination temperature in 0.1 degree Celsius
  • frontend temperature 1 in 0.1 degree Celsius
  • frontend temperature 2 in 0.1 degree Celsius
  • i.mx6 temperature in 0.1 degree Celsius
  • processing time in ms
  • framecount of the data
  • timestamp of the data in µs (deprecated)
  • timestamp of the data in s
  • timestamp of the data in ns
  • exposure time 1 of the frame
  • exposure time 2 of the frame
  • exposure time 3 of the frame

Operator close_framegrabber

This operator closes the device. See also close_framegrabber.

HDevelop Examples

For this interface there are the following examples available:
  • o3d3xx_simple.hdev - A simple example to show the usage of the interface.
  • o3d3xx_parameters.hdev - Lists all parameters of a device.
  • o3d3xx_objectmodel3d.hdev - Shows how to generate an object model 3D from the retrieved data.
  • o3d3xx_valid_data.hdev - Shows how to use the confidence image in order to find out which data points are valid.
  • o3d3xx_temporary_parameters.hdev - Shows how to use the temporary parameters.

Release Notes

  • Revision 13.0.2 Addendum (Jun 19, 2017):
    • This documentation was inconsistent about the additional values returned by grab_data. This problem has been fixed.
  • Revision 13.0.2 (Apr 27, 2017):
    • When using a firmware version higher than 1.5.x grabbing images led to a crash. This problem has been fixed.
    • The operator grab_data returns five additional values in the Data tuple. These values are the exposure times used for this frame. If the camera is used in a mode with only one or two exposures, the remaining exposure times will be zero. Please note, that this feature is only available with firmware version 1.8.x or higher. When using a lower firmware version the returned values will be zero.
    • Three temporary parameters have been added that can be set while the camera is in run mode. These changes are not persistent and are lost when entering edit mode, i.e. when changing any non-temporary parameter using set_framegrabber_param. The three new parameters are 'temporary_exposure_time', 'temporary_exposure_time_ratio' and 'temporary_channel'. Please note, that this feature is only available with firmware version 1.8.x or higher.
    • The example o3d3xx_temporary_parameters.hdev has been added that shows how to use the new temporary parameters.
  • Revision 13.0.1 (Oct 28, 2016):
    • HALCON 13 version of the interface.
  • Revision 6.5 (Mar 29, 2016):
    • If binning was disabled, the values of the image size were not set correctly. This problem has been fixed.
    • Querying the possible values of the parameter 'binning' returned zero as a possible value, which isn't correct. The list has been corrected.
  • Revision 6.4 (Mar 2, 2016):
    • The minimum value expected by the parameter 'exposure_time' was 0, but the correct minimum value is 1. This problem has been fixed.
    • The 'imager_configuration_type_values' parameter returned the unsupported value 'morethan30m_high'. This value has been removed.
  • Revision 6.3 (Feb 15, 2016):
    • The parameters 'pixel_format' and 'distance_unit' have been added to specify the output type of the images as well as the distance unit of the X, Y, Z and distance images, respectively.
    • The HDevelop example o3d3xx_objectmodel3d.hdev and o3d3xx_simple.hdev have been improved by using the new parameters 'pixel_format' and 'distance_unit'.
    • The binning mode could not be switched off. The parameter 'binning' has been added to enable this option. Note that it is only available with firmware version 1.3.1001 or higher.
    • The HDevelop example o3d3xx_valid_data.hdev has been added.
    • When setting the parameters 'exposure_time' and 'exposure_time_ratio', incorrect limits values were used. This caused that, in some cases, these parameters could not be set. This problem has been fixed.
    • The parameter 'reduce_motion_artifacts' had no impact. This parameter has been removed.
    • The HDevelop example o3d3xx_parameters.hdev has been improved to show the range and values of the available parameters.
    • The parameters list returned by 'available_param_names' (via get_framegrabber_param) and 'parameters', 'parameters_readonly', and 'parameters_writeonly' (via info_framegrabber) were not returned in alphabetical order. This problem has been fixed.
    • The O3D3xx interface was available for Linux, but not mentioned in this documentation. The Linux support has been added to the 'System Requirements' section.
  • Revision 6.2 Addendum (Sep 17, 2015):
    • The imager configuration type 'morethan30m_high' is not supported. This value option has been removed from the parameter 'imager_configuration_type' documentation.
  • Revision 6.2 (Jun 15, 2015):
    • First official release.
    • In case that there is no application on the sensor open_framegrabber crashed. This problem has been fixed.
    • Minor internal fixes.
  • Revision 6.1 (May 29, 2015):
    • Using set_framegrabber_param with the parameter 'exposure_time' led to a crash in most cases. This problem has been fixed.
  • Revision 6.0 (Apr 10, 2015):
    • HALCON 12 version of the interface.