LOG OUT
interfaces mvtec

Interface Documentation

Image Acquisition Interface for Ensenso 3D Sensors

Interface: Ensenso-NxLib
Revision: 13.0.4
Date: 2018-02-19

General

This page provides the documentation of the HALCON image acquisition interface for Ensenso 3D sensors. Registered customers can download the latest revision of this interface from the MVTec WWW server.

General system requirements for using Ensenso-NxLib

  • 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)
  • Windows: HALCON image acquisition interface hAcqEnsenso-NxLib.dll or hAcqEnsenso-NxLibxl.dll. If you have properly installed the interface, both DLLs should reside in bin\%HALCONARCH% within the HALCON base directory %HALCONROOT% you have chosen during the installation of HALCON.
    For N10 camera models: IDS uEye driver version 4.40 or higher.
    For N20 camera models: IDS uEye driver version 4.41 or higher.
    Successful installation of EnsensoSDK 1.3.171 or higher.
    Linux: HALCON image acquisition interface hAcqEnsenso-NxLib.so or hAcqEnsenso-NxLibxl.so. If you have properly installed the interface, both DLLs should reside in lib\%HALCONARCH% within the HALCON base directory %HALCONROOT% you have chosen during the installation of HALCON.
    For N10 camera models: IDS uEye driver version 4.40 or higher.
    For N20 camera models: IDS uEye driver version 4.41 or higher.
    Successful installation of EnsensoSDK-1.3.180 or higher.
  • Please check, if the installation of the NxLib drivers was successful by opening a camera within the NxView program provided by Ensenso.

Installation

Only when installing or updating the interface manually follow these steps:
  • Windows: Extract the archive containing the interface files to the HALCON base directory %HALCONROOT% (Note: Administrator privileges may be required for this step). Additionally, you have to move the interface examples to the directory %HALCONEXAMPLES% manually.

Features

  • Support of grab_image to get the left and right sensor image.
  • Support of grab_data. Pending on the configuration the user can retrieve the sensor image, the calibrated X, Y, and Z images (each float) and the corresponding region.
  • Support of multiple sensors.
  • Support of trigger multiple sensors simultaneously.

Limitations

  • Asynchronous grabbing is only supported by executing NxLib commands manually.

Use multiple sensors simultaneously

  • The HALCON Ensenso-NxLib Image Acquisition Interface provides the option to use multiple devices simultaneously. Therefor a global item handle to the global NxLib Tree node could be defined. The global NxLib Tree is a full representation of all Options and features provided by the interface. If the global handle is used together with set_framegrabber_param, and e.g. with the parameter 'do_execute', all connected devices will receive the specified command simultaneously.
  • Please have a look at the example ensenso-nxlib_2cameras.hdev and the NxLib documentation.
  • To get information about how to create a global NxLib Tree node handle with access to the global parameter, please see also the open_framgrabber parameter 'CameraType' and the required 'Item' value.

Parameters for info_framegrabber

Parameter Value List Type Kind Description
'bits_per_channel' [] Unsupported Query
'camera_type' ['Stereo', 'Monocular', 'Item'] string pre-defined Value list for camera type parameter.
'color_space' 'Raw', 'Rectified' string pre-defined Image type from grab_image.
'defaults' [0, 0, 0, 0, 0, 0, 'default', -1, 'Raw', -1.0, 'false', 'Stereo', '', 0, 0] mixed pre-defined Default values for open_framegrabber.
'device' <serial_number> string dynamic Shows all connected devices listed via the serial number.
'external_trigger' [] Unsupported Query
'field' [] Unsupported Query
'general' [] string pre-defined Information about the HALCON Ensenso-NxLib interface.
'generic' [-1, '', 'auto_grab_data=<0|1>', 'parallel_execution=<0|1>'] string pre-defined Possible values of the Generic parameter.
'horizontal_resolution' [] Unsupported Query
'image_height' [] Unsupported Query
'image_width' [] Unsupported Query
'info_boards' <device:serial_number status:[available, used]> string dynamic Shows all connected devices listed via the serial number.
'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 Ensenso-NxLib interface.
'start_column' [] Unsupported Query
'start_row' [] Unsupported Query
'vertical_resolution' [] Unsupported Query

Parameters for open_framegrabber

This operator opens a camera and returns a handle to it. Each camera handle is a reference to an NxLib API Tree node. Note that to each camera only one handle can be opened.
Parameter Values Default Type Description
Name 'Ensenso-NxLib' string Name of the HALCON interface.
HorizontalResolution [] Ignored
VerticalResolution [] Ignored
ImageWidth [] Ignored
ImageHeight [] Ignored
StartRow [] Ignored
StartColumn [] Ignored
Field [] Ignored
BitsPerChannel [] Ignored
ColorSpace 'Raw', 'Rectified' 'Raw' string Specifies the image type returned by grab_image.
Generic [-1, '', 'auto_grab_data=<0|1>', 'parallel_execution=<0|1>'] -1 mixed With the Generic parameter some important values can be set before the device is initialized. Note that the parameter names including the values must be strings.
  • auto_grab_data: With 'auto_grab_data=1' grabbing is done automatically (default) within the operator grab_image and grab_data. With 'auto_grab_data=0' no NxLib commands are executed automatically, i.e. no images are acquired and only the current images will be returned. Therewith the user can (and must) execute all NxLib commands manually and has full control over the NxLib functions. This is useful to grab from several devices simultaneously or use other NxLib functionality from within HALCON. To get further information about simultaneuous grabbing, please have a look at the Develop example ensenso-nxlib_2cameras.hdev. Specifying an empty string will also disable the auto_grab_data feature.
  • parallel_execution With 'parallel_execution=1', the handle uses its own execute node in the NxLib. Herewith you can execute multiple commands in parallel.
CameraType 'Stereo', 'Monocular', 'Item' 'Stereo' string Camera type of the used device model. With 'Stereo' or 'Monocular' open_framegrabber configures the returned handle to acquire 3D data or images from the device. If the value 'Item' is specified, no camera will be opened and the interface returns a handle associated with an arbitrary NxLib tree item. The item path can be specified in the 'device' parameter. This is useful to access global parameters or to use advanced functions of NxLib from within HALCON.
Device ['', <serial_number>, <eeprom_id>] string Possible values to connect to a device. With an empty string the first available device will be used.
Port [] Ignored
LineIn [] Ignored

Parameters for set_framegrabber_param

This operator is used for direct write access on the NxLib API Tree and HALCON specific parameters.
Parameter Values Default Type Description
'auto_grab_data' 'true', 'false' 'true' string With 'auto_grab_data' set to 'true' the necessary steps to acquire an image or 3D data is handled internally by the HALCON Ensenso-NxLib Image Acquisition Interface.
By disabling this flag, the user has full control of the NxLib functions. In this case, the user has to run all NxLib commands manually.
'do_close_tcp_port' [] integer Close the TCP port for NxLibRemote.
'do_execute' 'Capture', 'ComputeDisparityMap', 'ComputePointMap', ... string The parameter 'do_execute' provides the command execution of NxLib. The 'do_execute' parameter is only supported on handles referencing the tree's root node. To get a handle to the tree root node, please see the open_framegrabber parameter CameraType with the value 'Item'. If the parameter 'auto_grab_data' is set to 'true', the NxLib commands are handled inside the HALCON Ensenso-NxLib Image Acquisition Interface automatically.
'do_open_tcp_port' <port> integer Open a TCP port. If a socket is created by the call of 'do_open_tcp_port', a connection from NxTreeEdit could be established. NxTreeEdit is a Tree Viewer provided with the installation of Ensenso. Please note, that you have to take care about the correct architecture of NxTreeEdit. Please use the NxTreeEdit matching the architecture of your running HALCON instance (32bit/64bit).
'grab_data_items' ['<image_node_path>'] 'Images/PointMap' string The parameter controls the data returned by the operator grab_image. If e.g. ['Images/Rectified/Left', 'Images/PointMap'] will be passed as parameter value, a rectified image of the left sensor and a point map will be returned by grab_data. Please note that the node paths must be given relative to the path of the node to which the handle refers.
'parallel_execution' 'true', 'false' 'false' string With 'parallel_execution' set to 'true' the handle uses its own execute node in the NxLib. Herewith you can execute multiple commands in parallel.
relative_node_path <value> string Write value to a NxLib node. The node is specified by a relative path. The path is relative to the node to which the handle refers.
'replace_nans' 'true', 'false' 'true' string All internal binary fields use the NaN (Not a number) value of the IEEE floating point format to indicate that a certain point is invalid (i.e. not triangulated). Unfortunately NaN values within image cause various problems. Therefore by default grab_data replaces NaN values within floating point images with 0. This behavior can be controlled by this parameter.

Parameters for get_framegrabber_param

This operator is used for direct read access on the NxLib API Tree and HALCON specific parameters.
Parameter Values Default Type Kind Description
'auto_grab_data' 'true', 'false' 'true' string pre-defined With 'auto_grab_data' set to 'true' the necessary steps to acquire an image or 3D data is handled internally by the HALCON Ensenso-NxLib Image Acquisition Interface.
By disabling this flag, the user has full control of the NxLib functions. In this case, the user has to run all NxLib commands manually.
'available_param_names' ['<parameter>'] string dynamic The list contains the names of all available parameter. The HALCON Ensenso-NxLib Image Acquisition Interface provides the static HALCON parameter and also further generic parameter. To get the full list of supported parameter this parameter must be used.
'error_code' <error_code> string Retrieve the API error code.
'error_item' <error_item_path> string You can get extended error information of the last error by calling get_framegrabber_param on the device handle on which the error has happened. The parameter 'error_item' retrieves the path of the tree item which caused the error. Please see also the parameter 'error_code' and 'error_text'.
'error_text' <error_text> string Retrieve the error text.
'execute_node' <absolute_node_path> string Returns the path of the aqcuisition handle's execute node.
'type:' 'Null', 'Number', 'Bool', 'String', 'Array', 'Object', 'Inexistent'; string Returns the Json-Type from an NxLib node or 'Inexistent' if the node does not exist. The after the colon has to be replaced by one of the possible values.
'grab_data_items' ['<image_node_path>'] 'Images/PointMap' string pre-defined The parameter controls the data returned by the operator grab_image. If e.g. ['Images/Rectified/Left', 'Images/PointMap'] will be passed as parameter value, a rectified image of the left sensor and a point map will be returned by grab_data. Please note that the node paths must be given relative to the path of the node to which the handle refers.
'name' 'Ensenso-NxLib' string pre-defined Name of the HALCON interface.
'parallel_execution' 'true', 'false' 'false' string pre-defined With 'parallel_execution' set to 'true' the handle uses its own execute node in the NxLib. Herewith you can execute multiple commands in parallel.
'path' <absolute_node_path> string Returns the absolute path of the NxLib node the acquisition handle is referring to.
relative_node_path <value> string Read value from an NxLib node. The node is specified by a relative path. The path is relative to the node to which the handle refers.
'replace_nans' 'true', 'false' 'true' string pre-defined All internal binary fields use the NaN (Not a number) value of the IEEE floating point format to indicate that a certain point is invalid (i.e. not triangulated). Unfortunately NaN values within image cause various problems. Therefore by default grab_data replaces NaN values within floating point images with 0. This behavior can be controlled by this parameter.

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

Not supported.

Operator grab_image

Captures and returns an image of the camera associated with the given handle. On a stereo camera this function always returns an image from the left sensor. Notice: This function is not influenced by 'auto_grab_data' and always executes the Capture command.

Operator grab_image_async

Not supported.

Operator grab_data

This operator is used to access the binary nodes of the NxLib API Tree. It will return all binary nodes set by the parameter 'grab_data_items'.
Parameter Type Count Description
'image' 1...4 Depending on the parameter 'grab_data_items' the following images can be returned:
  • On camera handles:
    • Images/Raw/Left, Images/Raw/Right (1 channel / byte): Raw camera images
    • Images/Rectified/Left, Images/Rectified/Right (1 channel / byte): Rectified images
    • Images/DisparityMap (1 channel / int2): Disparity map resulting from stereo matching
    • Images/PointMap (3 channels / real): calibrated 3d data as point cloud (x/y/z channel)
  • On root node handles:
    • Images/RenderPointMap (3 channels / real): depth image as orthographic/telecentric or perspective projection
    • Images/RenderPointMapTexture (4 channels / byte): color image with alpha channel containing the texture corresponding to the depth data of RenderPointMap
    • Images/RenderView (3 channels / byte): rendered color image of the captured surfaces from a viewer perspective
'contours' Not used.
'region' Region which describes the valid 3D points.
'data' Not used.

Operator grab_data_async

Not supported.

Operator close_framegrabber

This operator closes the device. See also close_framegrabber.

HDevelop Examples

For this interface there are the following examples available:
  • ensenso-nxlib_simple.hdev - Shows the simple usage of a devices.
  • ensenso-nxlib_2cameras.hdev - Shows the usage of two devices.
  • ensenso-nxlib_parameters.hdev - Shows the paramters provided by the device.
  • ensenso-nxlib_objectmodel3d.hdev - Shows the usage of the 3D object model.
  • ensenso-nxlib_surface_based_3d_matching.hdev - Shows the usage of the 3D matching.
  • ensenso-nxlib_workspace_calibration.hdev - Shows the usage to calibrate the workspace.

Release Notes

  • Revision 13.0.4 (Feb 19, 2018):
    • The technical dependency from the HALCON Library has been removed.
    • The error handling when trying to set a boolean value to a non-existing node was incorrect. This problem has been fixed.
  • Revision 13.0.3 (Jul 05, 2017):
  • Revision 13.0.2 (Feb 22, 2017):
    • Added support for Linux x64 architecture.
    • Added new parameters 'execute_node' and 'parallel_execution'. With at least Ensenso-NxLib SDK 1.9 the parallel execution of NxLib commands is supported.
    • Added new example ensenso-nxlib_workspace_calibration.hdev
    • With a specific setting inside the HDevelop example ensenso-nxlib_surface_based_3d_matching.hdev the execution could run into a state with uninitialized variables. This problem has been fixed.
  • Revision 13.0.1 (Oct 28, 2016):
    • HALCON 13 version of the interface.
  • Revision 6.3 (Feb 15, 2016):
    • During the parameter handling, invalid strings could appear. Therefore, the interface has been adapted to support Ensenso SDK version 1.3.171, which fixes this problem.
    • The internal parameter handling has been improved.
  • Revision 6.2 (May 20, 2015):
    • Fixed bug in get_framegrabber_param. Query several parameter values simultaneously has led to undefined results.
    • Fixed wrong device name in ensenso-nxlib_surface_based_3d_matching.hdev
  • Revision 6.1 (Mar 30, 2015):
    • Added new read-only parameters 'path' and 'type' for get_framegrabber_param.
    • Fixed bug in info_boards to list all detected devices, whether they are already in use or not.
    • Fixed bug in grab_image. Also in case of color cameras, always a single channel image was returned.
    • Improved performance of grab_data by using SSE2 instruction commands from Intel.
    • Replaced return value H_MSG_FAIL (5) inside set_framegrabber_param by H_ERR_FGSETPAR (5329).
  • Revision 5.0 Addendum (Oct 24, 2014):
    • Adapted system requirements section. Changed underling uEye SDK version to 4.4 in case of N10 cameras and adapt Ensenso SDK to the needed version 1.2.342 to provide dynamic loading of the runtime DLL.
  • Revision 5.0 (Mar 28, 2014):
    • First official release.
Products/MVTec Interfaces