Dokumentation
Image Acquisition interface for Intel RealSense devices
Interface: | RealSense |
Revision: | 18.11.3 |
Date: | 2022-05-11 |
- General
- System Requirements
- Interface Versioning
- Installation
- RealSense Dependencies and Device Compatibility
- Features
- Limitations
- Identifying and Opening a Device
- Configuring the Sensor Hardware
- Acquisition – Overview, Device Control
- Acquisition – Grab Operators
- Acquisition – Acquiring 3D Data (ObjectModel3D)
- Acquisition – Configuring the Datastream
- Acquisition – Buffer Handling
- GenICam GenApi
- Selection of GenICam Feature Description File(s)
- Parameters – Naming Conventions
- Parameters – GenICam Data Types
- Parameters – Persisting Device Status
- Feature Change Notifications
- Event Data
- Event Message Queues
- Using HDevelop Image Acquisition Assistant
- 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
The interface internally contains a GenTL producer for RealSense devices which is refered to as 'RealSense Producer' in this document.
System Requirements
- General:
- GenICam GenApi. The corresponding files are part of the HALCON RealSense package and are located in the directory genicam within the HALCON base directory %HALCONROOT%. See section GenICam GenApi for more details.
- The computer has to be equipped with a USB 3.0 interface to connect the RealSense Device.
- Windows:
- Windows 10 operating system.
- HALCON image acquisition interface hAcqRealSense.dll or
hAcqRealSensexl.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.
- The realsense2 shared library (realsense2.dll) must be present and found in the system in
version 2.43.0.
Please download and install the RealSense SDK package for Windows 10.
Make sure that the realsense2.dll is found in the windows PATH variable, or copy it to
bin\%HALCONARCH% within the HALCON base directory %HALCONROOT% you have chosen during
the installation of HALCON.
- Linux:
- Linux system with a working installation of the RealSense SDK. For additional system requirements please check the 'Supported Platforms' of the SDK.
- HALCON image acquisition interface hAcqRealSense.so
or hAcqRealSensexl.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.
- The realsense2 shared library (librealsense2.so) must be present and found in the system in version 2.43.0.
- Please follow the RealSense instructions for installation on linux. Specific versions of the packages can be installed via sudo apt-get install <package>=<version>. If for your platform no dpkg packages are available, follow the build from source instructions.
Interface Versioning
Installation
- 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.
RealSense Dependencies and Device Compatibility
Features
- Automatic generation of an ObjectModel3D.
- Automatic handling of the color overlay for the ObjectModel3D.
- Invalid points are automatically excluded from the generated ObjectModel3D.
- Synchronous and asynchronous grabbing.
- Support of feature persistence.
Limitations
- No external triggering.
- No configuration of the resolution.
- No support of SoftwareTrigger.
- Only AcquisitionMode 'Continuous' is available.
Identifying and Opening a Device
A connection to the device accessible through the RealSense interface is established using the device ID which is guaranteed to be unique per device and stays persistent across multiple sessions. The list of all devices currently available in the system can be obtained using info_framegrabber parameter 'device' or 'info_boards' – see corresponding section. Both parameters return a list of devices, each specified using entities in the format ' | device:<device id> | unique_name:<unique name> | ... '. The device id and the unique name are guaranteed to be always the same for each device. To increase compatibility with other HALCON image acquisition Interfaces they are both listed. The full string (obtained from the info_framegrabber call) can be directly used for the 'Device' parameter of open_framegrabber, which uses the same format. Only the ' | device:<device id>' string entry is mandatory for open_framegrabber, the others might be omitted.
When a pure string without any 'token:' and without the ' | ' separator is used, it is interpreted directly as the device ID.
As a special case, the string 'default' can be used – in this case the HALCON acquisition interface will use the first available device (devices currently reported as non-accessible will be skipped). However this can result in non deterministic opening of devices when multiple devices are connected to the system.
Configuring the Sensor Hardware
Configuration options are managed on a per-module basis. This means some options might be only available for one of the modules, some options might be available for both. As an example, the 'ExposureTime' feature can be configured for the depth and the color module, the 'LaserPower' feature can only be configured for the depth module. To cover this use case while keeping features like 'ExposureTime' singular, the SFNC (GenICam Standard Feature Naming Convention specifies the 'SourceSelector'. It allows to switch the target of the configuration option.
Even if a specific feature exists only for one of the modules, it will not be configurable while the 'SourceSelector' is pointing to the wrong module.
The usage concept is ilustrated by the following example, which configures the 'ExposureTime' for each module differently:
set_framegrabber_param (AcqHandle,'SourceSelector','Depth')
set_framegrabber_param (AcqHandle,'ExposureTime',10000)
set_framegrabber_param (AcqHandle,'SourceSelector','Color')
set_framegrabber_param (AcqHandle,'ExposureTime',15000)
The names of the features reflect the names of the RealSense SDK sensor options, except where the SFNC dictates a specific different name. For each feature that maps to a RealSense SDK option, this document states the option explicitly (for example RS_OPTION_BACKLIGHT_COMPENSATION and so on). Those identifiers are contained in the RealSense SDK header file 'librealsense2/h/rs_option.h'.
Acquisition – Overview, Device Control
The interface fully configures and controls the acquisition process on the camera. Note that some of the camera features might be locked by GenICam when an acquisition is active.
With synchronous grab (grab_image/grab_data), a new acquisition is started internally for each image, so that the application always gets a new image. Before delivering the image, the acquisition is stopped again, so between individual grab_image/grab_data calls, all acquisition related features remain unlocked.
With asynchronous grabbing, started explicitly by grab_image_start or implicitly by grab_image_async/grab_data_async, the interface keeps the acquisition running internally, collecting further images to be delivered through future grab_image_async/grab_data_async calls. The acquisition related features are locked, until the acquisition is stopped using set_framegrabber_param(..., 'do_abort_grab', ...).
The HALCON acquisition interface properly recognizes the 'Continuous', 'SingleFrame' and 'MultiFrame' acquisition modes configured on the device and adjusts the acquisition control logic accordingly.
Furthermore, the interface takes over exclusive access to several remote device features essential for the acquisition control (AcquisitionStart, AcquisitionStop, AcquisitionAbort, TLParamsLocked). The user application has no direct way to control these features.
The differences between the "image" and "data" version of the grab operators is documented in Acquisition – Grab Operators.
Acquisition – Grab Operators
The grab_image/grab_image_async operators can only output a single image. For RealSense devices this single image will contain the Z coordinates of the 3D points. It will be returned as an image of the image type 'real', where each pixel is a float value. This approach is also currently used by the HDevelop's Image Acquisition Assistant.
For RealSense devices the grab_image/grab_image_async operators are too limited to deal with all the data available. Instead the grab_data/grab_data_async operators should be used. The image tuple returned in the first output variable of the operators always contains the X, Y and Z planes of the 3D points. All of those are images of the 'real' image type. Additionally, if activated and if the device provides the necessary videostreams, the image tuple will contain the color overlay and the confidence map. To switch those additional components on and off, please refered to the SFNC features 'ComponentSelector' and 'ComponentEnable'. The operators can also return an automatically generated ObjectModel3D in the 'Data' output variable.
The structure of the provided outputs can also be queried with the help of the 'image_contents', 'data_contents' and related parameters.
Acquisition – Acquiring 3D Data (ObjectModel3D)
The ObjectModel3D can also be generated manually by extracting the X, Y and Z planes from the image tuple and using the HALCON operator 'xyz_to_object_model_3d'.
Acquisition – Configuring the Datastream
Acquisition – Buffer Handling
Whenever a new image is acquired successfully and passed to the application as a HALCON image, the interface keeps the buffer locked (not returning it to the acquisition engine) until a new grab-related operator is called by the application or the acquisition is aborted using set_framegrabber_param(..., 'do_abort_grab', ...). During this period, it is fully safe to query information about this "last acquired" buffer – for example query buffer properties through get_framegrabber_param parameters such as 'buffer_timestamp', 'buffer_is_incomplete', 'image_width' and 'image_height'.
When a new grab-related operator is called by the application, the interface returns the buffer to the acquisition engine and buffer-related queries are not valid anymore.
It can happen, that the camera is temporarily or constantly acquiring data in higher speed than the application is processing them. In such case the streaming engine of the RealSense Producer decides how to treat the acquired buffers based on the '[Stream]StreamBufferHandlingMode' parameter.
GenICam GenApi
- This interface uses GenApi version 3.4, for more details refer to the GenICam homepage. The corresponding files are part of the HALCON runtime installation and are located in the directory genicam within the HALCON base directory %HALCONROOT% or $HALCONROOT, respectively. This version is the same as the officially released version at the time of writing.
- The HALCON RealSense interface sets all necessary environment
variables on its own and ignores other installed GenICam
packages by default.
If you want to use another GenICam package, you need to set the environment variable HALCON_USE_EXTERNAL_GENAPI. This skips the step of setting all necessary variables and paths internally, so you have to make sure they are set correctly. Please note that it might not be possible to use different GenApi versions with different interfaces at the same time and that you must use the required GenApi version for this interface. - The caching of device XML files is activated to speed up processing, writing to a temporary directory subject to availability of %TEMP%, %TMP%, $TMPDIR, /tmp or %HALCONROOT%.
- The remote device control features as well as the RealSense Producer control features of this interface are controlled via GenApi.
Selection of GenICam Feature Description File(s)
- Features of the connected RealSense device are wrapped by the RealSense Producer and presented via a GenICam compatible XML file. Names for those features follow the SFNC recommendation as far as applicable.
- Features of the RealSense Producer are exposed through
a set of GenICam description files, one for each internal entity to control
the device tree:
- The "system" – representing the overall behavior of the acquisition interface
- The interface used to connect the device to the system.
- A proxy (called "local device") to the device, controlling the RealSense Producer view of the device.
- The data stream used for the acquisition (if the device provides any data streams).
RemoteFile=%PATH_TO_GENICAM_FILE_OF_THE_DEVICE% SystemFile=%PATH_TO_GENICAM_FILE_OF_THE_SYSTEM_MODULE% InterfaceFile=%PATH_TO_GENICAM_FILE_OF_THE_INTERFACE_MODULE% DeviceFile=%PATH_TO_GENICAM_FILE_OF_THE_LOCAL_DEVICE_MODULE% StreamFile=%PATH_TO_GENICAM_FILE_OF_THE_STREAM_MODULE%The same ini-file format can be reused to force the HALCON acquisition interface to load an alternative XML file for one or more of these entities. This can be useful, e.g., for updates or troubleshooting. The files listed in the ini file will be used for the given entity instead of the original ones. For the entities excluded from the ini file, the GenICam description file will be searched and loaded the usual way. To apply the ini file, pass its full path to open_framegrabber in the 'CameraType' parameter.
Note that the ini-file can be reused also for other purposes such as storing/restoring configuration as described in Parameters – Persisting Device Status. Be aware that when persistence files are specified, they have priority over other explicit settings passed to open_framegrabber.
Parameters – Naming Conventions
- Internal parameters of the HALCON GenTL consumer itself (GenICamTL acquisition interface). These are named following the "underscore" naming style, e.g., color_space, and are all lowercase.
- GenICam-based parameters of the device, usually a camera, use by convention the "CamelCase" style, e.g., ExposureTime.
- GenICam-based parameters of the individual RealSense Producer
modules (system, interface, device and data stream) use by convention
the same style but are prefixed with the module name in square brackets.
Beware that the system and interface modules might potentially be shared by
multiple opened devices, so changing their configuration might have side
effects on other connections as well. The following prefixes are used:
- "[System]", e.g., [System]TLVendorName.
- "[Interface]", e.g., [Interface]InterfaceType.
- "[Device]", e.g., [Device]DeviceID.
- "[Stream]", e.g., [Stream]StreamBufferHandlingMode.
Parameters – GenICam Data Types
- integer – signed integer, 64-bit on 64-bit platforms, 32-bit on 32-bit ones
- real – floating point type
- string – classical string
- IInteger – integer value, mapped directly to HALCON's integer parameter type. It will also accept real parameters and when the GenICam feature in question is identified to be an IP or MAC address, the string representation of the address will also be accepted. It should be highlighted that a problem can occur when running HALCON on a 32-bit platform (where integer parameters are 32-bit wide) and accessing a GenICam feature that is naturally 64-bit. In such cases the full range of the feature will not be available to the application and its value might be truncated. Also the sign of the parameter might be misinterpreted. To solve this problem, the parameter 'split_param_values_into_dwords' can be used. This maps the 64-bit IInteger value into two 32-bit integer values and vice versa.
- IFloat – floating point value, mapped directly to HALCON's real parameter type. It will also accept integer parameters.
- IString – string value, mapped directly to HALCON's string parameter type.
- IBoolean – boolean type is handled through HALCON's integer parameters, a value of 0 (zero) means logical false, other values mean logical true.
- IEnumeration – enumeration is a type that allows selecting from a set of values that are primarily identified by their name (the values are called 'enum entries'). Enumerations are interfaced through HALCON's string parameter type, while the enum entry names are used as the parameter values.
- ICommand – The command type allows to "execute" actions. To execute a command, use set_framegrabber_param with an integer parameter of any value (the value is ignored). Some commands' execution might take longer time and the command provides feedback when it is done. To query the status, use get_framegrabber_param for that command. It will return an integer value of 1 if it "is done" (command execution has finished), 0 if it has not finished yet. Note that if some other features are designed to be dependent on the command, querying the "is done" status might be essential to get the depending features invalidated (and updated with new values) as soon as the command execution finishes.
- IRegister – The register data type is used for plain memory blobs that cannot be mapped to any other data type. They are interfaced through HALCON's string parameter type, the register value is the hexadecimal string representation of the register's memory.
Parameters – Persisting Device Status
Note that while the format of the files is intentionally human readable and the files can be hand-modified if desired, such modifications should be done with care by someone familiar with the GenICam persistence functionality internals and given device. Improper modifications of the files can lead to errors when using it.
The same persistence files can be applied to the entire set of devices of the same type and firmware version. Applying the persistence files to a device of another type or using even different firmware version will probably lead to inconsistencies or will even fail completely .
Apart from the 'do_write_settings', the feature persistence file will also be written together with the ini file documented in the section Selection of GenICam Feature Description File(s) - using parameter 'do_write_configuration'. This command will generate extended version of the persistence file, storing not only the current device configuration, but also contents of its user sets and sequencer sets (if the device supports them). Additionally, it will also generate persistence files for all the RealSense Producer modules (system, interface, device and data stream). The persistence file entries in the ini file will have the format
RemotePersistence=%PATH_TO_PERSISTENCE_FILE_OF_THE_DEVICE% SystemPersistence=%PATH_TO_PERSISTENCE_FILE_OF_THE_SYSTEM_MODULE% InterfacePersistence=%PATH_TO_PERSISTENCE_FILE_OF_THE_INTERFACE_MODULE% DevicePersistence=%PATH_TO_PERSISTENCE_FILE_OF_THE_LOCAL_DEVICE_MODULE% StreamPersistence=%PATH_TO_PERSISTENCE_FILE_OF_THE_STREAM_MODULE%
Feature Change Notifications
Note that the notifications might be raised in various circumstances, including:
- The application (you) explicitly changed that feature.
- Another feature has changed and the notified feature "depends" on the changed feature (the dependencies are defined in the GenICam description file).
- Access mode or current range for the feature has changed.
- As a result of regular "polling" in case of uncached features.
- As a result of device event delivery if the feature is connected to that event.
- As a result of new buffer delivery for features corresponding to chunk data.
Notification callbacks can be registered for individual features using set_framegrabber_callback - see corresponding operator documentation. Additionally, it is possible to use message queues to receive the event notification. In those cases it is necessary to create a message queue and then register the individual feature - see event message queues.
Event Data
The decoding of the event data and matching them to the corresponding features, including potential notifications, is performed transparently by the interface.
The actual values might be read through the regular parameter reading mechanism like get_framegrabber_param or by get_message_tuple if you are using message queues to receive events. The choice of the event types to be generated is device-specific. The names of the event related features usually start by convention with a prefix 'Event' (examples might be 'EventFrameTrigger' and 'EventFrameTriggerTimestamp'), however, the device documentation should contain all the information about supported events and their corresponding feature names.
Although the data corresponding to the last delivered event can be in general read at any time, when using callback to receive events it is highly recommended that reading the event data is synchronized to notifications for corresponding event feature(s). Only in such a case it is guaranteed that the read data correspond exactly to the very event instance being notified – and that the feature values are not just being modified through a new instance of the same event. Note that the notifications are raised from context of the event handling/dispatching thread, so when processing the user callback, the event handling mechanism is paused. If multiple data items are associated with the same event, it is enough to register notification just for the actual event feature and read all the data during the callback.
If using message queues to receive events, you can decide to add additional data to be delivered with the corresponding event feature(s), see Event Message Queues. For this case the interface will read all the specified event features as soon as the event is generated and add it to the corresponding message. This guarantees that the delivered information corresponds with the actual value at the time the event was generated.
Besides the asynchronous events generated by the actual device, asynchronous events (optionally including additional data) can be generated by any module of the RealSense Producer (system, interface, device and data stream). The information provided above about handling of the device events applies similarly also to the RealSense Producer events, including enabling/disabling them (typically using 'EventSelector'/'EventNotification' features provided by given module, i.e. with corresponding module prefix in the feature name). For SFNC-compliant events, this is done automatically if the parameter 'event_notification_helper' is enabled.
Event Message Queues
Create a message queue at which you want to receive the notifications with create_message_queue and assign it to the selected feature with set_framegrabber_param(..., 'event_message_queue', QueueHandle).
The message queue can be registered for any GenICam based features, i.e., features published by the device and RealSense Producer or for internal features of the acquisition interface. On top of that, the notification can be registered also for internal events occuring within the acquisition interface, in particular 'event_new_buffer' which gets fired whenever the information about last acquired buffer is updated (new buffer grabbed or last buffer info invalidated when restarting the acquisition).
The list of supported targets can be queried by calling get_framegrabber_param(..., 'available_event_names', ...).
One of the important use cases for feature change callbacks is the device event delivery mechanism, see details in Event Data and Feature Change Notifications sections.
A new message would be added to the specified queue whenever a given feature is potentially changed (including its other properties such as range or access mode). Note that it does not necessarily always mean that the feature actually has a new value. A call to set_framegrabber_param(..., 'event_message_queue', 0) unregisters the previously registered message queue from the specified event. Note that the interface keeps just a single registration for every feature, if you attempt to register a new message queue for a feature that already had a message queue registered, the previous registration will be replaced with the new one.
The messages incoming on an event can be retrieved with dequeue_message and will contain at least three tuples. The first tuple (key 'id') is a unique identifier of the acquisition instance the event is coming from. It is a string composed as '<interface>:<unique_name>'. The second tuple (key 'event_name') is the name of the corresponding feature previously specified by 'event_selector'. The third tuple (key 'event_value') contains the value if the corresponding feature if available and readable.
If you decide to add additional data to be delivered with the corresponding event feature(s), add the features of interest with set_framegrabber_param(..., 'event_data', ...). Each event data feature will be appended to the event message with the key being its name and the tuple its value if readable. Note that duplicities possibly specified through 'event_data' are ignored The value of the notified feature itself (already reported in 'event_value') would also be considered as a duplicity and not reported again.
Using HDevelop Image Acquisition Assistant
- Some parameters depend on special conditions, e.g., a valid buffer or another parameter activated. After opening the camera these conditions may not yet be fulfilled, so the depending parameters are not shown. By using the 'Refresh' button, all parameters are read again and the depending parameters should appear if the conditions are fulfilled then.
- There are also some parameters regarding the image size and the payload size, which can only be changed if no acquisition takes place. The safest way to ensure this is to apply the action parameter 'do_abort_grab'. Please note that 'Update Image' has to be disabled first.
- The behavior of allowing changes to parameters while streaming is active depends on the capabilities of the device. It is possible that some cameras give you control over, e.g., the exposure time, while streaming and others do not.
Parameters for info_framegrabber
Parameter | Value List | Type | Kind | Description |
---|---|---|---|---|
'bits_per_channel' | [-1] | integer | pre-defined | Values for bits per channel. |
'camera_type' | ['CAMFILE:', 'ini;xml', '<path>', 'default'] | string | pre-defined | Syntax for connection configuration file and default value. |
'color_space' | ['default', 'gray', 'raw', 'rgb', 'yuv'] | string | pre-defined | Values for color space. |
'defaults' | [0, 0, 0, 0, 0, 0, 'progressive', -1, 'default', -1.0, 'false', 'default', '0', 0, 0] | mixed | pre-defined | Default values for open_framegrabber. |
'device' | [' | device:<device id> | unique_name:<unique name> | interface:<interface id> | producer:RZwoa'] | string | dynamic | List of RealSense devices discovered in the system with information about their device ID, unique name, interface ID and producer. This corresponds to the RealSense devices plugged to USB ports on the machine. See the full description in section about device opening. |
'external_trigger' | [] | Ignored. | ||
'field' | [] | Unused. | ||
'general' | [] | string | pre-defined | Information about the HALCON RealSense interface. |
'generic' | ['', 'num_buffers=<num>' ] | string | pre-defined | Value list for the Generic parameter. |
'horizontal_resolution' | [0] | integer | pre-defined | Value list for horizontal resolution. |
'image_height' | [] | Unsupported query. | ||
'image_width' | [] | Unsupported query. | ||
'info_boards' | [' | device:<device_id> | unique_name:<unique_name> | interface:<interface_id> | producer:Rzwoa | vendor:Intel | model:<device_model> | tl_type:Custom | status:<device_status>'] | string | dynamic | List of RealSense devices discovered in the system. This corresponds to the RealSense devices plugged to USB ports on the machine.
|
'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' | [] | Unused. | ||
'revision' | '<revision>' | string | pre-defined | Revision number of the RealSense interface. |
'start_column' | [] | Unsupported query. | ||
'start_row' | [] | Unsupported query. | ||
'vertical_resolution' | [0] | integer | pre-defined | Value list for vertical resolution. |
Parameters for open_framegrabber
Parameter | Values | Default | Type | Description |
---|---|---|---|---|
Name | 'RealSense' | string | Name of the HALCON interface. | |
HorizontalResolution | 0, resolution | 0 | integer | 0: Keep the current Width settings of the camera. Values other than 0 are not supported. |
VerticalResolution | 0, resolution | 0 | integer | 0: Keep the current Width settings of the camera. Values other than 0 are not supported. |
ImageWidth | --- | 0 | Ignored. | |
ImageHeight | --- | 0 | Ignored. | |
StartRow | --- | 0 | Ignored. Configure the image size through device parameters. | |
StartColumn | --- | 0 | Ignored. Configure the image size through device parameters. | |
Field | --- | Ignored. | ||
BitsPerChannel | -1 | -1 | integer | Number of bits per channel of the resulting HALCON image. In case of -1 the bit depth of each respective acquired buffer is used. |
ColorSpace | 'default', 'gray', 'raw', 'rgb', 'yuv' | 'default' | string | Specify the desired color space and thus the number of image channels of the resulting HALCON image. In case of 'default' for Mono pixel formats, ColorSpace is set to 'gray', otherwise to 'rgb' (and for unknown pixel formats to 'raw'). |
Generic | '', ['num_buffers=<num>' ], -1 | -1 | mixed | With the Generic parameter some important values can be set before the camera is initialized. Note that the parameter names including the values
must be strings, e.g., 'num_buffers=5' sets the number of buffers to 5. The following parameters are available:
|
ExternalTrigger | --- | Ignored. To configure the trigger mode please use set_framegrabber_param with the generic (SFNC) trigger parameters of the camera. | ||
CameraType | 'default', <ini/xml filename> | 'default' | string | Full path to the configuration file with the specification of alternative GenICam description files to be loaded for the device and RealSense Producer, see detailed description in the section about device opening. |
Device | ' | device:<device id> | unique_name:<unique name> | interface:<interface id> | producer:RZwoa' | string | To open a RealSense sensor, the device name as shown in info_framegrabber(...'device'...) or info_framegrabber(...'info_boards'...) can be used. Some of the string entries might be skipped or set as 'default'. To open a specific sensor, either device or unique_name has to be set. As a shortcut, only the device ID or user-defined name might be specified or the string 'default' can be used. See full description in the section about device opening. | |
Port | --- | Unused. | ||
LineIn | --- | Ignored. |
Parameters for set_framegrabber_param
To set e.g. the current gain of the camera AcqHandle refers to (after calling open_framegrabber), the user can call set_framegrabber_param(AcqHandle, 'Gain', 6.0).
Please note that the interface sets the value of a parameter only if the value is valid. Integer and float values not matching the allowed range for given feature are aligned to the closest valid value. Invalid values of other feature types are refused.
Additionally to the GenICam parameters of the camera and of the RealSense Producer, the following HALCON interface parameters are supported by set_framegrabber_param:
Parameter | Values | Default | Type | Description |
---|---|---|---|---|
'[Device]DeviceEventsThreadApplyPriority' | --- | integer | Applies the thread priority and scheduling policy (if applicable on given operating system) configured through the '[Device]DeviceEventsThreadPriority'
and '[Device]DeviceEventsThreadSchedulingPolicy' parameters to the event
processing thread.
If the thread is running, the values are directly applied. If the thread is
not running in the moment, the values are stored and will be applied as soon
as the thread is started again.
It is responsibility of the application to ensure that the calling process
has sufficient privileges. The feature is not available for devices not supporting device events or if the event handling was disabled using the 'device_event_handling=0' generic parameter. BEWARE: Setting this parameter can lead to an unusable or poorly performing system, use with care. |
|
'[Device]DeviceEventsThreadPriority' | <thread_priority> | integer | OS-specific thread priority value to be used for the internal event processing thread. The actual values are directly the priority identifiers
of the operating system, e.g. THREAD_PRIORITY_HIGHEST under Windows
or a real-time priority value under Linux. The actual priority is applied only after executing the '[Device]DeviceEventsThreadApplyPriority' command parameter, possibly together with the '[Device]DeviceEventsThreadSchedulingPolicy' value if applicable on given system. It is the responsibility of the application to ensure that the calling process has sufficient privileges to apply the priority change and that the value written to the parameter is a valid priority identifier. After applying '[Device]DeviceEventsThreadApplyPriority', the application can read back the priority value to verify if it was properly applied. Note that when opening the device, the RealSense Producer attempts itself to elevate the thread priority to a suitable value. The feature is not available for devices not supporting device events or if the event handling was disabled using the 'device_event_handling=0' generic parameter. BEWARE: Setting this parameter can lead to an unusable or poorly performing system, use with care. |
|
'[Device]DeviceEventsThreadSchedulingPolicy' | <scheduling_policy> | integer | OS-specific scheduling policy value to be used for the internal event processing thread. The actual values are directly the priority identifiers
of the operating system, e.g. SCHED_FIFO under Linux.
Note that this feature is not available under Windows. The actual scheduling policy is applied only after executing the '[Device]DeviceEventsThreadApplyPriority' command parameter, together with the '[Device]DeviceEventsThreadPriority' value. It is the responsibility of the application to ensure that the calling process has sufficient privileges to apply the scheduling policy and that the value written to the parameter is a valid scheduling policy identifier. After applying '[Device]DeviceEventsThreadApplyPriority', the application can read back the scheduling policy value to verify if it was properly applied. The feature is not available for devices not supporting device events or if the event handling was disabled using the 'device_event_handling=0' generic parameter. BEWARE: Setting this parameter can lead to an unusable or poorly performing system, use with care. |
|
'[Stream]StreamBufferHandlingMode' | 'OldestFirst', 'OldestFirstOverwrite', 'NewestOnly' | 'OldestFirst' | string | Selects the mode the streaming engine uses to handle newly acquired data, in particular when the camera runs faster than the application processing.
The parameter is writeable only if no acquisition is active.
Supported values are:
|
'[Stream]StreamThreadApplyPriority' | --- | integer | Applies the thread priority and scheduling policy (if applicable on the given operating system) configured through
'[Stream]StreamThreadPriority' and '[Stream]StreamThreadSchedulingPolicy'
parameters to the stream processing thread.
If the thread is running (acquisition started), the values are directly
applied. If the thread is not running in the moment, the values are
stored and will be applied as soon as the thread is started again.
It is the responsibility of the application to ensure that the calling
process has sufficient privileges. BEWARE: Setting this parameter can lead to an unusable or poorly performing system, use with care. |
|
'[Stream]StreamThreadPriority' | <thread_priority> | integer | OS-specific thread priority value to be used for the internal stream processing thread. The actual values are directly the priority identifiers
of the operating system, e.g. THREAD_PRIORITY_HIGHEST under Windows
or a real-time priority value under Linux. The actual priority is applied only after executing the '[Stream]StreamThreadApplyPriority' command parameter, possibly together with the '[Stream]StreamThreadSchedulingPolicy' value if applicable on given system. It is the responsibility of the application to ensure that the calling process has sufficient privileges to apply the priority change and that the value written to the parameter is a valid priority identifier. After applying '[Stream]StreamThreadApplyPriority', the application can read back the priority value to verify if it was properly applied. Note that when opening the device, the RealSense Producer attempts itself to elevate the thread priority to a suitable value. BEWARE: Setting this parameter can lead to an unusable or poorly performing system, use with care. |
|
'[Stream]StreamThreadSchedulingPolicy' | <scheduling_policy> | integer | OS-specific scheduling policy value to be used for the internal stream processing thread. The actual values are directly the priority identifiers
of the operating system, e.g. SCHED_FIFO under Linux.
Note that this feature is not available under Windows. The actual scheduling policy is applied only after executing the '[Stream]StreamThreadApplyPriority' command parameter, together with the '[Stream]StreamThreadPriority' value. It is the responsibility of the application to ensure that the calling process has sufficient privileges to apply the scheduling policy and that the value written to the parameter is a valid scheduling policy identifier. After applying '[Stream]StreamThreadApplyPriority', the application can read back the scheduling policy value to verify if it was properly applied. BEWARE: Setting this parameter can lead to an unusable or poorly performing system, use with care. |
|
'add_objectmodel3d_overlay_attrib' | 'disable', 'enable' | 'disable' | string | Controls if the acquisition interface should attempt to append the intensity/color overlay to the generated 3D object models. Applicable only if a 3D object model is being output
from given grab operator.
When switched on, the acquisition interface will try to find suitable information within
the acquired data (if it is provided by the device). If so, it appends the overlay
information for each point in the output model in form of an extended attribute.
Note that in some advanced use cases there might be multiple potential overlay images
output by the device, the acquisition interface therefore attempts to find the most
suitable one. First, it tries to identify data marked as "intensity" image in the acquired data. If found and provided as monochrome 2D image, it is appended as '&intensity_gray' extended attribute. If found and provided as RGB image, it is appended as three extended attributes, '&intensity_red', '&intensity_green' and '&intensity_blue'. If "intensity" data cannot be identified, it tries to find data marked as "reflectance". If found and provided as monochrome 2D image, it is appended as '&reflectance_gray' extended attribute. If found and provided as RGB image, it is appended as three extended attributes, '&reflectance_red', '&reflectance_green' and '&reflectance_blue'. Finally, if neither "intensity" nor "reflectance" data can be identified (either not present or not correctly marked by the device, it picks the first 2D image within the acquired data than can be mapped to the 3D coordinates. If found and provided as monochrome 2D image, it is appended as '&overlay_gray' extended attribute. If found and provided as RGB image, it is appended as three extended attributes, '&overlay_red', '&overlay_green' and '&overlay_blue'. If no suitable 2D image is found, no overlay is appended. The actually appended extended attributes can be queried for example using the get_object_model_3d_params operator with the 'extended_attribute_names' parameter. The overlay can be also used for visualization purposes. |
'AlternateIR' | 'Off', 'On' | string | RealSense Remote Device Parameter: Enables/disables the alternate IR feature (RealSense option RS2_OPTION_ALTERNATE_IR). Availability of this parameter depends on the connected device and the current setting of the 'SourceSelector'. | |
'BacklightCompensation' | real | RealSense Remote Device Parameter: Control the backlight compensation (RealSense option RS_OPTION_BACKLIGHT_COMPENSATION). Availability of this parameter depends on the connected device and the current setting of the 'SourceSelector'. | ||
'BalanceRatio' | real | RealSense Remote Device Parameter: Controls the white balance of the color image. If 'BalanceWhiteAuto' is currently 'Continuous' it will automatically fall back to 'Off'. (RealSense option RS2_OPTION_ENABLE_WHITE_BALANCE). Availability of this parameter depends on the connected device and the current setting of the 'SourceSelector'. | ||
'BalanceWhiteAuto' | 'Off', 'Continuous' | string | RealSense Remote Device Parameter: Controls the mode for automatic white balancing between the color channels (RealSense option RS2_OPTION_ENABLE_AUTO_WHITE_BALANCE). Availability of this parameter depends on the connected device and the current setting of the 'SourceSelector'. | |
'bits_per_channel' | -1 | integer | Number of bits per channel of the resulting HALCON image. In case of -1 the bit depth of each respective acquired buffer is used. | |
'Brightness' | real | RealSense Remote Device Parameter: Control the brightness (RealSense option RS_OPTION_BRIGHTNESS). Availability of this parameter depends on the connected device and the current setting of the 'SourceSelector'. | ||
'buffer_reallocation_mode' | 'only_increase_size', 'follow_payloadsize' | 'only_increase_size' | string | Defines the strategy to follow when reallocating the buffers for a new acquisition. In case of 'only_increase_size', the buffers will be only reallocated when the payload size increases. In case of 'follow_payloadsize', the buffers will be reallocated every time the payload size changes. |
'ChunkComponentSelector' | string | RealSense Remote Device Parameter: refer to the SFNC for the meaning of this parameter. | ||
'ChunkModeActive' | integer | RealSense Remote Device Parameter: refer to the SFNC for the meaning of this parameter. | ||
'ChunkScan3dCoordinateReferenceSelector' | string | RealSense Remote Device Parameter: refer to the SFNC for the meaning of this parameter. Automatically evaluated during ObjectModel3D generation. | ||
'ChunkScan3dCoordinateSelector' | string | RealSense Remote Device Parameter: refer to the SFNC for the meaning of this parameter. Automatically evaluated during ObjectModel3D generation. | ||
'clear_buffer' | 'disable', 'enable' | 'disable' | string | If enabled, each buffer content is cleared before re-queueing (all bytes set to 0xF0 regardless the expected pixel format), so you can see which parts of an image are missing, in case e.g. the transfer of some image packets failed. This parameter adds of course a runtime overhead to write the 0xF0 data every time a buffer is queued. It is mainly useful for debugging in combination with transport layers which do not guarantee the transfer of complete images. Please note, that this parameter does not modify the buffer queue, only the content of a buffer will be set to a defined state. |
'color_space' | 'default', 'gray', 'raw', 'rgb', 'yuv' | string | Specify the desired color space and thus the number of image channels of the resulting HALCON image. In case of 'default' for Mono pixel formats, ColorSpace is set to 'gray', otherwise to 'rgb' (and for unknown pixel formats to 'raw'). | |
'ComponentEnable' | integer | RealSense Remote Device Parameter: allows to switch off (and on) the component currently selected via 'ComponentSelector'. The depth stream cannot be switched off. Additionally refer to the SFNC for the meaning of this parameter. | ||
'ComponentSelector' | 'Range', 'Intensity', 'Confidence' | string | RealSense Remote Device Parameter: for RealSense devices allows to select 'Range', 'Intensity' (if available) and 'Confidence' (if available). Used in combination with 'ComponentEnable'. Range is the SFNC terminology for the depth data. In RealSense SDK terminology this is the depth stream. Intensity is the SFNC terminology for the color overlay. In RealSense SDK terminology this is the color stream. Additionally refer to the SFNC for the meaning of this parameter. | |
'confidence_mode' | 'off', 'object_model_3d' | 'off' | string | Controls if (and how) the information about pixel confidence level is used by the acquisition interface. Applicable only for devices and use cases where the confidence information is delivered (per-pixel)
together with the actual pixel data. The threshold to distinguish between valid and invalid pixels is controlled using the 'confidence_threshold' parameter. Note that in some use cases there might be other criteria how to mark given pixel invalid, for example if the device uses "invalid pixel value" for a 3D coordinate. These cases are not covered by the 'confidence_mode' parameter and such invalid pixels are always rejected from the 3D object model. Possible values are:
|
'confidence_threshold' | [0.0, 1.0] | 0.5 | float | Threshold separating between valid and invalid pixels. Applicable only for devices and use cases where the confidence information is delivered (per-pixel)
together with the actual pixel data.
The decision how (to which outputs) the confidence threshold is applied is controlled using the
'confidence_mode' parameter. The threshold is interpreted as a (float) ratio between 0.0 and 1.0. The acquisition interface will remap this ratio to the actual confidence range provided by the device and use it to decide which pixels are valid and which not. Pixels with confidence lower than the specified threshold are considered invalid. |
'Contrast' | real | RealSense Remote Device Parameter: Control the contrast (RealSense option RS_OPTION_CONTRAST). Availability of this parameter depends on the connected device and the current setting of the 'SourceSelector'. | ||
'coordinate_transform_mode' | 'none', 'cartesian', 'reference' | 'reference' | string | Controls which coordinate transformation operations should the acquisition interface attempt to perform when building the 3D object model from acquired 3D coordinates. Note that the decision
which transformation should be performed and which parameters should be used fully depends
on the 3D configuration information provided by the device together with the acquired data.
If this information is insufficient or coordinates are inaccurate, the result of the transformation(s)
might be meaningless or unpredictable.
Refer to for more details. Possible values are:
|
'create_objectmodel3d' | 'disable', 'enable' | 'disable' | string | Controls whether the acquisition interface should attempt to generate HALCON 3D object model(s) when encountering 3D coordinates within the acquired data. To obtain a 3D object model, the application has to use the grab_data/grab_data_async operators which can return the handles to the generated models through the control data outputs. The grab_image/grab_image_async operators cannot return the 3D object models. IMPORTANT: the parameter is disabled by default. When enabling, the application is responsible for releasing the generated object models and associated resources using the clear_object_model_3d operator once it does not need given model(s) any more. It should do so by tracking which of the control data outputs of every single grab_data/grab_data_async calls carry 3D object model handle(s). This can be done using the 'data_contents' parameter. When generating the 3D object model, the acquisition interface processes the 3D coordinates found in the acquired data and builds the point cloud with help of the information about the actual 3D configuration reported by the device. Refer to for more details. |
'delay_after_stop' | <milliseconds> | 0 | integer | The time to wait (in milliseconds) between stopping the acquisition on the device (AcquisitionStop command) and RealSense Producer. |
'DepthResolution' | string | RealSense Remote Device Parameter: Configures the resolution of the depth data stream. The values are in the form ' |
||
'DeviceFeaturePersistenceEnd' | integer | RealSense Remote Device Parameter: refer to the SFNC for the meaning of this parameter. Automatically used during 'do_write_persistence' command. | ||
'DeviceFeaturePersistenceStart' | integer | RealSense Remote Device Parameter: refer to the SFNC for the meaning of this parameter. Automatically used during 'do_write_persistence' command. | ||
'DeviceRegistersStreamingEnd' | integer | RealSense Remote Device Parameter: refer to the SFNC for the meaning of this parameter. Automatically used during 'do_load_persistence' command. | ||
'DeviceRegistersStreamingStart' | integer | RealSense Remote Device Parameter: refer to the SFNC for the meaning of this parameter. Automatically used during 'do_load_persistence' command. | ||
'DeviceReset' | integer | RealSense Remote Device Parameter: triggers a hardware reset of the connected RealSense device. Additionally refer to the SFNC for the meaning of this parameter. | ||
'do_abort_grab' | --- | Aborts the current image acquisition and unlocks parameters, that might be locked when acquisition is active. See acquisition overview. | ||
'do_load_settings' | <input_file> | string | Restores the previously stored settings of the opened device. The paramter 'settings_selector' specifies if the settings of the actual (remote) device, one of the RealSense Producer modules or the Consumer parameters (internal parameters of RealSense image acquisition interface) are to be restored. See detailed description in section Parameters - Persisting Device Status. | |
'do_write_configuration' | <output_file> | string | Writes a configuration (ini) file and additionally writes GenICam description files and persistence files with the current configuration
of the device into the same directory. The string parameter must be the filename (including full path) of the target ini file. The path must exist prior to writing. The written ini file contains a list of paths to the written description and persistence files. GenICam description files are written for the remote device and each RealSense Producer module associated with currently opened device. Persistence files are written for the remote device and each RealSense Producer module as well as for the internal parameters of the RealSense image acquisition interface. The complete configuration can be loaded using the 'CameraType' parameter of open_framegrabber operator, see detailed description in the section about device opening. The persisted values of the internal parameters override the corresponding parameters passed to 'open_framegrabber' (in particular 'BitsPerChannel' and 'ColorSpace'). Instead of specifying the full name of the output ini file, 'default' or an empty string can be used. In this case the files will be written to a temporary directory (subject to availability of %TEMP%, %TMP%, $TMPDIR, /tmp or %HALCONROOT%) and the filename of the configuration file will be halcon_gentl_config.ini. This default option will also apply when using the Image Acquisition Assistant. See also related sections Selection of GenICam Feature Description File(s) and Parameters – Persisting Device Status. |
|
'do_write_settings' | <output_file> | string | Writes the current settings of the opened device to be able to restore the settings later. The paramter 'settings_selector' specifies if the settings of the actual (remote) device, one of the RealSense Producer modules or the Consumer parameters (internal parameters of RealSense image acquisition interface) are to be written. See detailed description in section Parameters - Persisting Device Status. | |
'EmitterAlwaysOn' | 'Off', 'On' | string | RealSense Remote Device Parameter: Allows to switch the emitter to always on (RealSense option RS2_OPTION_EMITTER_ALWAYS_ON). Availability of this parameter depends on the connected device and the current setting of the 'SourceSelector'. | |
'event_data' | '<list of genicam_feature/internal_parameter>' | string | Configures GenICam features and/or internal parameters (free mix) to be added to the message queue specified by 'event_message_queue'
for feature change notifications for feature selected in 'event_selector'. Features can be added individually or as a tuple - each 'set' operation for this parameter appends to the current list of event_data. To remove individual features, prepend them with a '~'. To clear all currently added features, call set_framegrabber_param(..., 'event_data', []). Read more about the usage of this mechanism at Event Message Queues. |
|
'event_message_queue' | 0, '<queue_handle>' | handle | Selects a message queue to which the acquisition interface should send feature change notifications (see further details in
Event Message Queues). The corresponding feature/parameter needs to be previously selected by 'event_selector'. Setting 0 (NULL) unregisters the previously selected message queue from notifications about given feature/parameter. |
|
'event_notification_helper' | 'disable', 'enable' | 'disable' | string | Controls if the acquisition interface should attempt to automatically (un)set 'EventNotification' during set_framegrabber_callback if the callback is being (un)registered on an SFNC-compliant event. Note that this will only work if the callback is being registered on the actual event feature (e.g. 'EventExposureEnd'), not on one of the event data features (e.g. 'EventExposureEndTimestamp'). For further information on events, see Event Data. |
'event_selector' | '<genicam_feature/internal_parameter>' | 'grab_timeout' | string | Selects a GenICam feature or internal parameter for which feature change notifications through message queues
should be configured. They are sent to the message queue specified by 'event_message_queue', together with additional data configured in 'event_data'. Read more about the usage of this mechanism at Event Message Queues (which is another alternative to notifications through callbacks, Feature Change Notifications). |
'ExposureAuto' | 'Off', 'Continuous' | string | RealSense Remote Device Parameter: Sets the automatic exposure mode when 'ExposureMode' is 'Timed' (for RealSense devices this is always the case). (RealSense option RS_OPTION_ENABLE_AUTO_EXPOSURE). Availability of this parameter depends on the connected device and the current setting of the 'SourceSelector'. | |
'ExposureTime' | real | RealSense Remote Device Parameter: Sets the Exposure time. If 'ExposureAuto' is currently 'Continuous' it will automatically fall back to 'Off'. This controls the duration where the photosensitive cells are exposed to light. (RealSense option RS2_OPTION_EXPOSURE). Availability of this parameter depends on the connected device and the current setting of the 'SourceSelector'. | ||
'Gain' | real | RealSense Remote Device Parameter: Controls the selected gain as an absolute physical value. This is an amplification factor applied to the video signal (RealSense option RS2_OPTION_GAIN). Availability of this parameter depends on the connected device and the current setting of the 'SourceSelector'. | ||
'Gamma' | real | RealSense Remote Device Parameter: Control the gamma (RealSense option RS_OPTION_GAMMA). Availability of this parameter depends on the connected device and the current setting of the 'SourceSelector'. | ||
'grab_timeout' | <milliseconds> | 5000 | integer | Desired timeout (milliseconds) for aborting a pending grab. If -1 is specified, the timeout is set to INFINITE. |
'HDREnabled' | 'Off', 'On' | string | RealSense Remote Device Parameter: Enables/disables the HDR feature (RealSense option RS_OPTION_HDR_ENABLED). Availability of this parameter depends on the connected device and the current setting of the 'SourceSelector'. | |
'Hue' | real | RealSense Remote Device Parameter: Control the hue (RealSense option RS_OPTION_HUE). Availability of this parameter depends on the connected device and the current setting of the 'SourceSelector'. | ||
'image_height' | --- | 0 | Unsupported (read-only parameter). | |
'image_width' | --- | 0 | Unsupported (read-only parameter). | |
'LaserPower' | real | RealSense Remote Device Parameter: Power (intensity) of the infrared projector (RealSense option RS2_OPTION_LASER_POWER). Availability of this parameter depends on the connected device and the current setting of the 'SourceSelector'. | ||
'MinDistance' | real | RealSense Remote Device Parameter: Control the minimum distance to the target (RealSense option RS2_OPTION_MIN_DISTANCE). Availability of this parameter depends on the connected device and the current setting of the 'SourceSelector'. | ||
'NoiseFiltering' | real | RealSense Remote Device Parameter: Control edges and background noise (RealSense option RS2_OPTION_NOISE_FILTERING). Availability of this parameter depends on the connected device and the current setting of the 'SourceSelector'. | ||
'PostProcessingSharpening' | real | RealSense Remote Device Parameter: Controls the amount of sharpening in the post processed image (RealSense option RS2_OPTION_POST_PROCESSING_SHARPENING). Availability of this parameter depends on the connected device and the current setting of the 'SourceSelector'. | ||
'PreProcessingSharpening' | real | RealSense Remote Device Parameter: Controls the amount of sharpening in the pre processed image (RealSense option RS2_OPTION_PRE_PROCESSING_SHARPENING). Availability of this parameter depends on the connected device and the current setting of the 'SourceSelector'. | ||
'ReceiverGain' | real | RealSense Remote Device Parameter: Controls the exposure time of the avalanche photo diode in the receiver (RealSense option RS_OPTION_AVALANCHE_PHOTO_DIODE). Availability of this parameter depends on the connected device and the current setting of the 'SourceSelector'. | ||
'Saturation' | real | RealSense Remote Device Parameter: Control the saturation (RealSense option RS_OPTION_SATURATION). Availability of this parameter depends on the connected device and the current setting of the 'SourceSelector'. | ||
'settings_selector' | 'RemoteDevice', 'Stream', 'Device', 'System', 'Interface', 'Consumer' | 'RemoteDevice' | string | Selects for which component (set of parameters) the streamable parameters are persisted into a file or restored from a file when using set_framegrabber_param(..., 'do_write_settings', []) and set_framegrabber_param(..., 'do_load_settings', []). Selects among the actual (remote) device, one of the RealSense Producer modules or the Consumer parameters (internal parameters of RealSense image acquisition interface). Read more about the usage of this mechanism at Parameters – Persisting Device Status. |
'Sharpness' | real | RealSense Remote Device Parameter: Control the sharpness (RealSense option RS_OPTION_SHARPNESS). Availability of this parameter depends on the connected device and the current setting of the 'SourceSelector'. | ||
'SourceSelector' | 'Depth', 'Color' | string | RealSense Remote Device Parameter: Selects the hardware component that should currently be configured. Please see the corresponding section for more information. | |
'split_param_values_into_dwords' | 'disable', 'enable' | 'disable' | string | Enables a special mode allowing the treatment of integer parameters as tuple of two 32-bit integers. For compatibility with the single-parameter mode, the first tuple element carries always the low 32-bit part of the value, second element carries the high 32-bit part. It is user's responsibility to combine the two parts correctly. This mode is intended especially to help to overcome the problem of 32-bit HALCON featuring only 32-bit integer parameters but having to face up to 64-bit wide GenICam features. In this mode, the get_framegrabber_param returns always a tuple of two integers, set_framegrabber_param accepts both a single parameter or a tuple. Note that this mode affects only integer parameters and only the GenICam based ones, not the internal parameters of HALCON RealSense image acquisition interface - with few exceptions, the 'buffer_timestamp', 'buffer_timestamp_ns', 'device_timestamp_frequency' and 'buffer_frameid' internal parameters. |
'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. |
'start_column' | --- | 0 | Unsupported (read-only parameter). Configure the image size through device parameters. | |
'start_row' | --- | 0 | Unsupported (read-only parameter). Configure the image size through device parameters. | |
'VisualPreset' | string | RealSense Remote Device Parameter: Allows to load sets of predefined configuration options to optimize the sensor for certain application profiles (RealSense option RS_OPTION_VISUAL_PRESET). This parameter is only accessible for the depth module. | ||
'volatile' | 'disable', 'enable' | 'disable' | string | When enabled, switches on the volatile mode in which the image buffers are used directly to create HALCON images. This is the fastest mode avoiding
the copy of raw images in memory. However, be aware that older images
might be overwritten by the acquisition engine with new data at any time.
When changing the device configuration in a way that acquisition buffers
must be reallocated, the older HALCON images would even become invalid
(pointing to no more existing memory). See also
details about acquisition buffer handling.
Please note that the volatile mode can be switched on at any time, regardless of the current configuration. However, at runtime only the acquired images compatible with the volatile mode will be delivered to the application (the others will be discarded). Compatible means in particular that the PixelFormat of the acquired image matches the color_space and bits_per_channel settings configured for HALCON image output format. |
'WhiteBalance' | real | RealSense Remote Device Parameter: Controls the white balance of the color image. This parameter is provided as an alias for the 'BalanceRatio' parameter. |
Parameters for get_framegrabber_param
- '_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.
- '_displayname': These parameters provide the displayname of the corresponding parameter as a string.
- '_longdescription': These parameters provide the description of the corresponding parameter as a string.
- '_range': These parameters provide the minimum, maximum, step width, and current 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, current].
- '_type': These parameters provide the type of the corresponding parameter as string.
- '_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'.
- '_streamable': These parameters provide the persistence of the corresponding parameter as an integer. Possible values are 0 if false or 1 if true.
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 |
---|---|---|---|---|---|
'[Device]DeviceEventsThreadPriority' | <thread_priority> | integer | pre-defined | OS-specific thread priority value to be used for the internal event processing thread. The actual values are directly the priority identifiers
of the operating system, e.g. THREAD_PRIORITY_HIGHEST under Windows
or a real-time priority value under Linux. The actual priority is applied only after executing the '[Device]DeviceEventsThreadApplyPriority' command parameter, possibly together with the '[Device]DeviceEventsThreadSchedulingPolicy' value if applicable on given system. It is the responsibility of the application to ensure that the calling process has sufficient privileges to apply the priority change and that the value written to the parameter is a valid priority identifier. After applying '[Device]DeviceEventsThreadApplyPriority', the application can read back the priority value to verify if it was properly applied. Note that when opening the device, the RealSense Producer attempts itself to elevate the thread priority to a suitable value. The feature is not available for devices not supporting device events or if the event handling was disabled using the 'device_event_handling=0' generic parameter. BEWARE: Setting this parameter can lead to an unusable or poorly performing system, use with care. |
|
'[Device]DeviceEventsThreadSchedulingPolicy' | <scheduling_policy> | integer | pre-defined | OS-specific scheduling policy value to be used for the internal event processing thread. The actual values are directly the priority identifiers
of the operating system, e.g. SCHED_FIFO under Linux.
Note that this feature is not available under Windows. The actual scheduling policy is applied only after executing the '[Device]DeviceEventsThreadApplyPriority' command parameter, together with the '[Device]DeviceEventsThreadPriority' value. It is the responsibility of the application to ensure that the calling process has sufficient privileges to apply the scheduling policy and that the value written to the parameter is a valid scheduling policy identifier. After applying '[Device]DeviceEventsThreadApplyPriority', the application can read back the scheduling policy value to verify if it was properly applied. The feature is not available for devices not supporting device events or if the event handling was disabled using the 'device_event_handling=0' generic parameter. BEWARE: Setting this parameter can lead to an unusable or poorly performing system, use with care. |
|
'[Stream]StreamBufferHandlingMode' | 'OldestFirst', 'OldestFirstOverwrite', 'NewestOnly' | 'OldestFirst' | string | pre-defined | Selects the mode the streaming engine uses to handle newly acquired data, in particular when the camera runs faster than the application processing.
The parameter is writeable only if no acquisition is active.
Supported values are:
|
'[Stream]StreamThreadPriority' | <thread_priority> | integer | pre-defined | OS-specific thread priority value to be used for the internal stream processing thread. The actual values are directly the priority identifiers
of the operating system, e.g. THREAD_PRIORITY_HIGHEST under Windows
or a real-time priority value under Linux. The actual priority is applied only after executing the '[Stream]StreamThreadApplyPriority' command parameter, possibly together with the '[Stream]StreamThreadSchedulingPolicy' value if applicable on given system. It is the responsibility of the application to ensure that the calling process has sufficient privileges to apply the priority change and that the value written to the parameter is a valid priority identifier. After applying '[Stream]StreamThreadApplyPriority', the application can read back the priority value to verify if it was properly applied. Note that when opening the device, the RealSense Producer attempts itself to elevate the thread priority to a suitable value. BEWARE: Setting this parameter can lead to an unusable or poorly performing system, use with care. |
|
'[Stream]StreamThreadSchedulingPolicy' | <scheduling_policy> | integer | pre-defined | OS-specific scheduling policy value to be used for the internal stream processing thread. The actual values are directly the priority identifiers
of the operating system, e.g. SCHED_FIFO under Linux.
Note that this feature is not available under Windows. The actual scheduling policy is applied only after executing the '[Stream]StreamThreadApplyPriority' command parameter, together with the '[Stream]StreamThreadPriority' value. It is the responsibility of the application to ensure that the calling process has sufficient privileges to apply the scheduling policy and that the value written to the parameter is a valid scheduling policy identifier. After applying '[Stream]StreamThreadApplyPriority', the application can read back the scheduling policy value to verify if it was properly applied. BEWARE: Setting this parameter can lead to an unusable or poorly performing system, use with care. |
|
'[System]RSExpectedVersion' | string | RealSense Producer Custom Parameter: The version of the realsense2 shared library the RealSense image acquisition interface was compiled against. If newer versions are loaded by the operating system, initializing the framegrabber object for the RealSense device will fail. | |||
'[System]RSFoundVersion' | string | RealSense Producer Custom Parameter: The version of the realsense2 shared library that was loaded by the operating system. Basic compatibility is given if the version is lower or equal to the expected version. | |||
'AcquisitionFrameRate' | real | RealSense Remote Device Parameter: allows to query the framerate at which the hardware is currently acquiring frames. Additionally refer to the SFNC for the meaning of this parameter. | |||
'AcquisitionMode' | 'Continuous' | string | RealSense Remote Device Parameter: refer to the SFNC for the meaning of this parameter. Serves informational purposes. | ||
'add_objectmodel3d_overlay_attrib' | 'disable', 'enable' | 'disable' | string | pre-defined | Controls if the acquisition interface should attempt to append the intensity/color overlay to the generated 3D object models. Applicable only if a 3D object model is being output
from given grab operator.
When switched on, the acquisition interface will try to find suitable information within
the acquired data (if it is provided by the device). If so, it appends the overlay
information for each point in the output model in form of an extended attribute.
Note that in some advanced use cases there might be multiple potential overlay images
output by the device, the acquisition interface therefore attempts to find the most
suitable one. First, it tries to identify data marked as "intensity" image in the acquired data. If found and provided as monochrome 2D image, it is appended as '&intensity_gray' extended attribute. If found and provided as RGB image, it is appended as three extended attributes, '&intensity_red', '&intensity_green' and '&intensity_blue'. If "intensity" data cannot be identified, it tries to find data marked as "reflectance". If found and provided as monochrome 2D image, it is appended as '&reflectance_gray' extended attribute. If found and provided as RGB image, it is appended as three extended attributes, '&reflectance_red', '&reflectance_green' and '&reflectance_blue'. Finally, if neither "intensity" nor "reflectance" data can be identified (either not present or not correctly marked by the device, it picks the first 2D image within the acquired data than can be mapped to the 3D coordinates. If found and provided as monochrome 2D image, it is appended as '&overlay_gray' extended attribute. If found and provided as RGB image, it is appended as three extended attributes, '&overlay_red', '&overlay_green' and '&overlay_blue'. If no suitable 2D image is found, no overlay is appended. The actually appended extended attributes can be queried for example using the get_object_model_3d_params operator with the 'extended_attribute_names' parameter. The overlay can be also used for visualization purposes. |
'AlternateIR' | 'Off', 'On' | string | RealSense Remote Device Parameter: Enables/disables the alternate IR feature (RealSense option RS2_OPTION_ALTERNATE_IR). Availability of this parameter depends on the connected device and the current setting of the 'SourceSelector'. | ||
'available_callback_types' | ['<callback_types>'] | string | dynamic | Returns a list containing all parameters, for which a callback can be registered. This includes all parameters published by the device and RealSense Producer via the GenICam interface, including those temporarily unavailable, because availability change might be coupled with the callback. | |
'available_param_names' | ['<names>'] | string | dynamic | Returns a list containing all available parameters, i.e. those used by the HALCON RealSense image acquisition interface and those published by the device and RealSense Producer via the GenICam interface (see parameter naming conventions). The availability of some parameters might depend on acquisition status, values of other parameters or other conditions, so the list dynamically changes during runtime. | |
'BacklightCompensation' | real | RealSense Remote Device Parameter: Control the backlight compensation (RealSense option RS_OPTION_BACKLIGHT_COMPENSATION). Availability of this parameter depends on the connected device and the current setting of the 'SourceSelector'. | |||
'BalanceRatio' | real | RealSense Remote Device Parameter: Controls the white balance of the color image. If 'BalanceWhiteAuto' is currently 'Continuous' it will automatically fall back to 'Off'. (RealSense option RS2_OPTION_ENABLE_WHITE_BALANCE). Availability of this parameter depends on the connected device and the current setting of the 'SourceSelector'. | |||
'BalanceWhiteAuto' | 'Off', 'Continuous' | string | RealSense Remote Device Parameter: Controls the mode for automatic white balancing between the color channels (RealSense option RS2_OPTION_ENABLE_AUTO_WHITE_BALANCE). Availability of this parameter depends on the connected device and the current setting of the 'SourceSelector'. | ||
'bits_per_channel' | -1 | -1 | integer | pre-defined | Number of bits per channel of the resulting HALCON image. In case of -1 the bit depth of each respective acquired buffer is used. |
'Brightness' | real | RealSense Remote Device Parameter: Control the brightness (RealSense option RS_OPTION_BRIGHTNESS). Availability of this parameter depends on the connected device and the current setting of the 'SourceSelector'. | |||
'buffer_frameid' | <frame_id> | integer | dynamic | Frame ID attached to the last grabbed (image) buffer by the device (or RealSense Producer). Typically sequentially incremented number of the frame. Skipped ID's in the sequence could indicate that one or more frames was dropped in the device or RealSense Producer, for example due to acquisition engine overflow reasons. Note that on 32-bit systems only the lower 32-bit part of up to 64-bit timestamp is delivered (unless 'split_param_values_into_dwords' parameter is enabled). See acquisition buffer handling. | |
'buffer_is_incomplete' | 0, 1 | integer | dynamic | Shows if the last grabbed image is incomplete (e.g. due to lost packets). See acquisition buffer handling. | |
'buffer_reallocation_mode' | 'only_increase_size', 'follow_payloadsize' | 'only_increase_size' | string | pre-defined | Defines the strategy to follow when reallocating the buffers for a new acquisition. In case of 'only_increase_size', the buffers will be only reallocated when the payload size increases. In case of 'follow_payloadsize', the buffers will be reallocated every time the payload size changes. |
'buffer_timestamp' | <timestamp> | integer | dynamic | Timestamp attached to the last grabbed (image) buffer by the device (or RealSense Producer). The unit and actual meaning of the timestamp (when it is generated) is device specific. If the frequency of the timestamp counter is known, the value in nanoseconds can be read from 'buffer_timestamp_ns'. Note that on 32-bit systems only the lower 32-bit part of up to 64-bit timestamp is delivered (unless 'split_param_values_into_dwords' parameter is enabled). See acquisition buffer handling. | |
'buffer_timestamp_ns' | <timestamp> | integer | dynamic | Timestamp attached to the last grabbed (image) buffer by the device (or RealSense Producer). The value is in nanoseconds, but might not be available if the timestamp frequency is unknown (refer also to 'buffer_timestamp' and 'device_timestamp_frequency'). Note that on 32-bit systems only the lower 32-bit part of up to 64-bit timestamp is delivered (unless 'split_param_values_into_dwords' parameter is enabled). See acquisition buffer handling. | |
'camera_type' | 'default', <ini/xml filename> | 'default' | string | pre-defined | Returns the path to the configuration file used for the CameraType parameter in open_framegrabber. |
'ChunkComponentIDValue' | integer | RealSense Remote Device Parameter: refer to the SFNC for the meaning of this parameter. Automatically evaluated during ObjectModel3D generation. | |||
'ChunkComponentSelector' | string | RealSense Remote Device Parameter: refer to the SFNC for the meaning of this parameter. | |||
'ChunkModeActive' | integer | RealSense Remote Device Parameter: refer to the SFNC for the meaning of this parameter. | |||
'ChunkScan3dCoordinateOffset' | real | RealSense Remote Device Parameter: refer to the SFNC for the meaning of this parameter. Automatically evaluated during ObjectModel3D generation. | |||
'ChunkScan3dCoordinateReferenceSelector' | string | RealSense Remote Device Parameter: refer to the SFNC for the meaning of this parameter. Automatically evaluated during ObjectModel3D generation. | |||
'ChunkScan3dCoordinateReferenceValue' | real | RealSense Remote Device Parameter: refer to the SFNC for the meaning of this parameter. Automatically evaluated during ObjectModel3D generation. | |||
'ChunkScan3dCoordinateScale' | real | RealSense Remote Device Parameter: refer to the SFNC for the meaning of this parameter. Automatically evaluated during ObjectModel3D generation. | |||
'ChunkScan3dCoordinateSelector' | string | RealSense Remote Device Parameter: refer to the SFNC for the meaning of this parameter. Automatically evaluated during ObjectModel3D generation. | |||
'ChunkScan3dCoordinateSystem' | string | RealSense Remote Device Parameter: refer to the SFNC for the meaning of this parameter. Automatically evaluated during ObjectModel3D generation. | |||
'ChunkScan3dCoordinateSystemReference' | string | RealSense Remote Device Parameter: refer to the SFNC for the meaning of this parameter. Automatically evaluated during ObjectModel3D generation. | |||
'ChunkScan3dDistanceUnit' | string | RealSense Remote Device Parameter: refer to the SFNC for the meaning of this parameter. Automatically evaluated during ObjectModel3D generation. | |||
'ChunkScan3dInvalidDataFlag' | integer | RealSense Remote Device Parameter: refer to the SFNC for the meaning of this parameter. Automatically evaluated during ObjectModel3D generation. | |||
'ChunkScan3dInvalidDataValue' | real | RealSense Remote Device Parameter: refer to the SFNC for the meaning of this parameter. Automatically evaluated during ObjectModel3D generation. | |||
'ChunkScan3dOutputMode' | string | RealSense Remote Device Parameter: refer to the SFNC for the meaning of this parameter. Automatically evaluated during ObjectModel3D generation. | |||
'clear_buffer' | 'disable', 'enable' | 'disable' | string | pre-defined | If enabled, each buffer content is cleared before re-queueing (all bytes set to 0xF0 regardless the expected pixel format), so you can see which parts of an image are missing, in case e.g. the transfer of some image packets failed. This parameter adds of course a runtime overhead to write the 0xF0 data every time a buffer is queued. It is mainly useful for debugging in combination with transport layers which do not guarantee the transfer of complete images. Please note, that this parameter does not modify the buffer queue, only the content of a buffer will be set to a defined state. |
'color_space' | 'default', 'gray', 'raw', 'rgb', 'yuv' | 'default' | string | pre-defined | Returns the current color space. |
'ComponentEnable' | integer | RealSense Remote Device Parameter: allows to switch off (and on) the component currently selected via 'ComponentSelector'. The depth stream cannot be switched off. Additionally refer to the SFNC for the meaning of this parameter. | |||
'ComponentSelector' | 'Range', 'Intensity', 'Confidence' | string | RealSense Remote Device Parameter: for RealSense devices allows to select 'Range', 'Intensity' (if available) and 'Confidence' (if available). Used in combination with 'ComponentEnable'. Range is the SFNC terminology for the depth data. In RealSense SDK terminology this is the depth stream. Intensity is the SFNC terminology for the color overlay. In RealSense SDK terminology this is the color stream. Additionally refer to the SFNC for the meaning of this parameter. | ||
'confidence_mode' | 'off', 'object_model_3d' | 'off' | string | pre-defined | Controls if (and how) the information about pixel confidence level is used by the acquisition interface. Applicable only for devices and use cases where the confidence information is delivered (per-pixel)
together with the actual pixel data. The threshold to distinguish between valid and invalid pixels is controlled using the 'confidence_threshold' parameter. Note that in some use cases there might be other criteria how to mark given pixel invalid, for example if the device uses "invalid pixel value" for a 3D coordinate. These cases are not covered by the 'confidence_mode' parameter and such invalid pixels are always rejected from the 3D object model. Possible values are:
|
'confidence_threshold' | [0.0, 1.0] | 0.5 | float | pre-defined | Threshold separating between valid and invalid pixels. Applicable only for devices and use cases where the confidence information is delivered (per-pixel)
together with the actual pixel data.
The decision how (to which outputs) the confidence threshold is applied is controlled using the
'confidence_mode' parameter. The threshold is interpreted as a (float) ratio between 0.0 and 1.0. The acquisition interface will remap this ratio to the actual confidence range provided by the device and use it to decide which pixels are valid and which not. Pixels with confidence lower than the specified threshold are considered invalid. |
'Contrast' | real | RealSense Remote Device Parameter: Control the contrast (RealSense option RS_OPTION_CONTRAST). Availability of this parameter depends on the connected device and the current setting of the 'SourceSelector'. | |||
'coordinate_transform_mode' | 'none', 'cartesian', 'reference' | 'reference' | string | pre-defined | Controls which coordinate transformation operations should the acquisition interface attempt to perform when building the 3D object model from acquired 3D coordinates. Note that the decision
which transformation should be performed and which parameters should be used fully depends
on the 3D configuration information provided by the device together with the acquired data.
If this information is insufficient or coordinates are inaccurate, the result of the transformation(s)
might be meaningless or unpredictable.
Refer to for more details. Possible values are:
|
'create_objectmodel3d' | 'disable', 'enable' | 'disable' | string | pre-defined | Controls whether the acquisition interface should attempt to generate HALCON 3D object model(s) when encountering 3D coordinates within the acquired data. To obtain a 3D object model, the application has to use the grab_data/grab_data_async operators which can return the handles to the generated models through the control data outputs. The grab_image/grab_image_async operators cannot return the 3D object models. IMPORTANT: the parameter is disabled by default. When enabling, the application is responsible for releasing the generated object models and associated resources using the clear_object_model_3d operator once it does not need given model(s) any more. It should do so by tracking which of the control data outputs of every single grab_data/grab_data_async calls carry 3D object model handle(s). This can be done using the 'data_contents' parameter. When generating the 3D object model, the acquisition interface processes the 3D coordinates found in the acquired data and builds the point cloud with help of the information about the actual 3D configuration reported by the device. Refer to for more details. |
'data_contents' | 'unknown', 'object_model_3d', 'text_report' | 0 | string | pre-defined | Tuple describing logical type of the control data outputs returned by the last grab operator. Not applicable if last successful grab was performed through grab_image/grab_image_async.
In case of grab_data/grab_data_async it returns a tuple of the size
corresponding to the number of control data values returned through those operators.
Possible values are:
|
'data_purpose_id' | --- | 0xFFFFFFFFFFFFFFFF | integer | pre-defined | Tuple of integer values allowing to track data purpose IDs associated to individual control data outputs returned by the last grab operator. Intended for advanced use cases when the data should be matched with the device configuration. The use of the parameter is application specific and requires knowledge of the GenICam SFNC data model and specific device. Not applicable if last successful grab was performed through grab_image/grab_image_async. In case of grab_data/grab_data_async it returns a tuple of the size corresponding to the number of control data values returned through those operators. If the ID could not be identified (e.g. because the underlying communication protocol does not provide such information), invalid value will be returned (max value of given integer range). |
'data_region_id' | --- | 0xFFFFFFFFFFFFFFFF | integer | pre-defined | Tuple of integer values allowing to track region IDs associated to individual control data outputs returned by the last grab operator. Intended for advanced use cases when the data should be matched with the device configuration. The use of the parameter is application specific and requires knowledge of the GenICam SFNC data model and specific device. Not applicable if last successful grab was performed through grab_image/grab_image_async. In case of grab_data/grab_data_async it returns a tuple of the size corresponding to the number of control data values returned through those operators. If the ID could not be identified (e.g. because the underlying communication protocol does not provide such information), invalid value will be returned (max value of given integer range). |
'data_source_id' | --- | 0xFFFFFFFFFFFFFFFF | integer | pre-defined | Tuple of integer values allowing to track source IDs associated to individual control data outputs returned by the last grab operator. Intended for advanced use cases when the data should be matched with the device configuration. The use of the parameter is application specific and requires knowledge of the GenICam SFNC data model and specific device. Not applicable if last successful grab was performed through grab_image/grab_image_async. In case of grab_data/grab_data_async it returns a tuple of the size corresponding to the number of control data values returned through those operators. If the ID could not be identified (e.g. because the underlying communication protocol does not provide such information), invalid value will be returned (max value of given integer range). |
'delay_after_stop' | <milliseconds> | 0 | integer | pre-defined | The time to wait (in milliseconds) between stopping the acquisition on the device (AcquisitionStop command) and RealSense Producer. |
'DepthResolution' | string | RealSense Remote Device Parameter: Configures the resolution of the depth data stream. The values are in the form ' |
|||
'device' | ' | device:<device id> | unique_name:<unique name> | interface:<interface id> | producer:RZwoa' | string | dynamic | Returns the Device parameter string used when opening the device (open_framegrabber). | |
'device_event_handling' | 0, 1 | 1 | integer | pre-defined | Value of the device_event_handling generic parameter specified in open_framegrabber. The device_event_handling is by default switched on for devices with event delivery (message channel) support and off for devices without the event capability. The generic parameter device_event_handling explicitly allows switching the event handling functionality off even for devices with event support. |
'device_timestamp_frequency' | <frequency_hz> | integer | dynamic | Frequency of the timestamp counter of the device, in ticks per second (Hz). The frequency might not be known for all devices. The counter is used for example to attach timestamps to acquired buffers. Note that on 32-bit systems only the lower 32-bit part of up to 64-bit timestamp is delivered (unless 'split_param_values_into_dwords' parameter is enabled). | |
'DeviceFamilyName' | string | RealSense Remote Device Parameter: refer to the SFNC for the meaning of this parameter. For RealSense devices the output will be for example 'D400'. | |||
'DeviceModelName' | string | RealSense Remote Device Parameter: refer to the SFNC for the meaning of this parameter. For RealSense devices the output will be for example 'Intel RealSense L515'. | |||
'DeviceScanType' | 'AreaScan' | string | RealSense Remote Device Parameter: refer to the SFNC for the meaning of this parameter. Serves informational purposes. | ||
'DeviceSerialNumber' | string | RealSense Remote Device Parameter: Contains the serial number of the actual hardware device. Additionally refer to the SFNC for the meaning of this parameter. | |||
'DeviceVendorName' | string | RealSense Remote Device Parameter: refer to the SFNC for the meaning of this parameter. For RealSense devices the output will be 'Intel'. | |||
'DeviceVersion' | string | RealSense Remote Device Parameter: refer to the SFNC for the meaning of this parameter. For RealSense devices the output will be for example 'Intel RealSense L515'. | |||
'EmitterAlwaysOn' | 'Off', 'On' | string | RealSense Remote Device Parameter: Allows to switch the emitter to always on (RealSense option RS2_OPTION_EMITTER_ALWAYS_ON). Availability of this parameter depends on the connected device and the current setting of the 'SourceSelector'. | ||
'event_data' | '<list of genicam_feature/internal_parameter>' | string | pre-defined | Configures GenICam features and/or internal parameters (free mix) to be added to the message queue specified by 'event_message_queue'
for feature change notifications for feature selected in 'event_selector'. Features can be added individually or as a tuple - each 'set' operation for this parameter appends to the current list of event_data. To remove individual features, prepend them with a '~'. To clear all currently added features, call set_framegrabber_param(..., 'event_data', []). Read more about the usage of this mechanism at Event Message Queues. |
|
'event_message_queue' | 0, '<queue_handle>' | handle | pre-defined | Selects a message queue to which the acquisition interface should send feature change notifications (see further details in
Event Message Queues). The corresponding feature/parameter needs to be previously selected by 'event_selector'. Setting 0 (NULL) unregisters the previously selected message queue from notifications about given feature/parameter. |
|
'event_notification_helper' | 'disable', 'enable' | 'disable' | string | pre-defined | Controls if the acquisition interface should attempt to automatically (un)set 'EventNotification' during set_framegrabber_callback if the callback is being (un)registered on an SFNC-compliant event. Note that this will only work if the callback is being registered on the actual event feature (e.g. 'EventExposureEnd'), not on one of the event data features (e.g. 'EventExposureEndTimestamp'). For further information on events, see Event Data. |
'event_selector' | '<genicam_feature/internal_parameter>' | 'grab_timeout' | string | pre-defined | Selects a GenICam feature or internal parameter for which feature change notifications through message queues
should be configured. They are sent to the message queue specified by 'event_message_queue', together with additional data configured in 'event_data'. Read more about the usage of this mechanism at Event Message Queues (which is another alternative to notifications through callbacks, Feature Change Notifications). |
'ExposureAuto' | 'Off', 'Continuous' | string | RealSense Remote Device Parameter: Sets the automatic exposure mode when 'ExposureMode' is 'Timed' (for RealSense devices this is always the case). (RealSense option RS_OPTION_ENABLE_AUTO_EXPOSURE). Availability of this parameter depends on the connected device and the current setting of the 'SourceSelector'. | ||
'ExposureMode' | 'Timed' | string | RealSense Remote Device Parameter: refer to the SFNC for the meaning of this parameter. Serves informational purposes. | ||
'ExposureTime' | real | RealSense Remote Device Parameter: Sets the Exposure time. If 'ExposureAuto' is currently 'Continuous' it will automatically fall back to 'Off'. This controls the duration where the photosensitive cells are exposed to light. (RealSense option RS2_OPTION_EXPOSURE). Availability of this parameter depends on the connected device and the current setting of the 'SourceSelector'. | |||
'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. |
'Gain' | real | RealSense Remote Device Parameter: Controls the selected gain as an absolute physical value. This is an amplification factor applied to the video signal (RealSense option RS2_OPTION_GAIN). Availability of this parameter depends on the connected device and the current setting of the 'SourceSelector'. | |||
'Gamma' | real | RealSense Remote Device Parameter: Control the gamma (RealSense option RS_OPTION_GAMMA). Availability of this parameter depends on the connected device and the current setting of the 'SourceSelector'. | |||
'generic' | '', ['num_buffers=<num>' ], -1 | -1 | mixed | pre-defined | Values of the Generic parameter. |
'grab_timeout' | <milliseconds> | 5000 | integer | pre-defined | Current grab timeout in milliseconds. |
'HDREnabled' | 'Off', 'On' | string | RealSense Remote Device Parameter: Enables/disables the HDR feature (RealSense option RS_OPTION_HDR_ENABLED). Availability of this parameter depends on the connected device and the current setting of the 'SourceSelector'. | ||
'Height' | integer | RealSense Remote Device Parameter: Height of the currently configured sensor resolution. Contrary to the SFNC behaviour of this feature, for the RealSense Producer this parameter is a read only parameter. | |||
'horizontal_resolution' | 0, resolution | 1 | integer | pre-defined | Current value of horizontal resolution. |
'Hue' | real | RealSense Remote Device Parameter: Control the hue (RealSense option RS_OPTION_HUE). Availability of this parameter depends on the connected device and the current setting of the 'SourceSelector'. | |||
'image_available' | 0, 1 | integer | dynamic | Shows if there is currently an image waiting for delivery by the RealSense Producer. | |
'image_contents' | 'unknown', 'image', 'coord_a', 'coord_b', 'coord_c', 'coord_mixed', 'confidence' | 0 | string | pre-defined | Tuple describing the logical type of the image data returned by the last grab operator. If the last successful grab was performed through grab_image/grab_image_async, the parameter
returns always single value. In case of grab_data/grab_data_async it returns a tuple of the size
corresponding to the number of images returned through those operators.
Possible values are:
|
'image_height' | <height> | 0 | integer | pre-defined | Height of the last acquired image. See acquisition buffer handling. If there is no valid last buffer available, the last queried value of the 'Height' parameter of the remote device is returned. |
'image_pixel_format' | --- | 0 | integer | pre-defined | Tuple of integer values representing the ID of the original pixel formats of the source data used to generate individual image outputs. This is typically the PFNC 32-bit ID of given pixel format - if unknown or if the data used to generate given image output is not naturally an image, zero will be reported. If the source data is a multi-component image (such as RGB or multi-component 3D coordinate format), the original multi-component pixel format is reported, no matter if all of the components were used to generate given image output (such as an RGB image) or if the image output reflects only one of the components (such as individual 3D coordinate planes, output as separate HALCON images). The original multi-component pixel format might be planar format or not. Note that the color space and bit depth of the actual HALCON image might significantly differ from the source format if the user requests color space conversion through the 'bits_per_channel' and 'color_space' parameters. |
'image_purpose_id' | --- | 0xFFFFFFFFFFFFFFFF | integer | pre-defined | Tuple of integer values allowing to track data purpose IDs associated to individual image outputs returned by the last grab operator. Intended for advanced use cases when the data should be matched with the device configuration. The use of the parameter is application specific and requires knowledge of the GenICam SFNC data model and specific device. If the last successful grab was performed through grab_image/grab_image_async, the parameter returns always single value. In case of grab_data/grab_data_async it returns a tuple of the size corresponding to the number of images returned through those operators. If the ID could not be identified (e.g. because the underlying communication protocol does not provide such information), invalid value will be returned (max value of given integer range). |
'image_raw_buffer_padding_bytes' | --- | 0 | integer | pre-defined | Tuple of integers reporting for raw buffers of type 'blob' (see 'image_raw_buffer_type') the size of unused padding bytes at the end of such grabbed HALCON image. Because artificial dimensions need to be chosen for the resulting HALCON image in this case, the size of such image might not exactly equal the size of the buffer data and thus the padding might be needed. Zero is reported for buffers of type 'image'. Applies only in case of the 'raw' color format. See raw output format chapter. If the last successful grab was performed through grab_image/grab_image_async, the parameter returns always single value. In case of grab_data/grab_data_async it returns a tuple of the size corresponding to the number of images returned through those operators. |
'image_raw_buffer_type' | 'image', 'blob' | 0 | string | pre-defined | Tuple of strings showing whether the last grabbed HALCON image(s) is created from buffer containing real image data with known properties (in particular image size and pixel format) or if it is created from a blob of other data (non-image data or image data of unknown format). Note that in case of the blob data the dimensions of the HALCON image are meaningless. Applies mainly in case of the 'raw' color format. Possible values are 'image' and 'blob'. See raw output format chapter. If the last successful grab was performed through grab_image/grab_image_async, the parameter returns always single value. In case of grab_data/grab_data_async it returns a tuple of the size corresponding to the number of images returned through those operators. |
'image_region_id' | --- | 0xFFFFFFFFFFFFFFFF | integer | pre-defined | Tuple of integer values allowing to track region IDs associated to individual image outputs returned by the last grab operator. Intended for advanced use cases when the data should be matched with the device configuration. The use of the parameter is application specific and requires knowledge of the GenICam SFNC data model and specific device. If the last successful grab was performed through grab_image/grab_image_async, the parameter returns always single value. In case of grab_data/grab_data_async it returns a tuple of the size corresponding to the number of images returned through those operators. If the ID could not be identified (e.g. because the underlying communication protocol does not provide such information), invalid value will be returned (max value of given integer range). |
'image_source_id' | --- | 0xFFFFFFFFFFFFFFFF | integer | pre-defined | Tuple of integer values allowing to track source IDs associated to individual image outputs returned by the last grab operator. Intended for advanced use cases when the data should be matched with the device configuration. The use of the parameter is application specific and requires knowledge of the GenICam SFNC data model and specific device. If the last successful grab was performed through grab_image/grab_image_async, the parameter returns always single value. In case of grab_data/grab_data_async it returns a tuple of the size corresponding to the number of images returned through those operators. If the ID could not be identified (e.g. because the underlying communication protocol does not provide such information), invalid value will be returned (max value of given integer range). |
'image_width' | <width> | 0 | integer | pre-defined | Width of the last acquired image. See acquisition buffer handling. If there is no valid last buffer available, the last queried value of the 'Width' parameter of the remote device is returned. |
'LaserPower' | real | RealSense Remote Device Parameter: Power (intensity) of the infrared projector (RealSense option RS2_OPTION_LASER_POWER). Availability of this parameter depends on the connected device and the current setting of the 'SourceSelector'. | |||
'line_in' | <default> | 0 | integer | pre-defined | The value is not used, so a default value is returned. |
'MinDistance' | real | RealSense Remote Device Parameter: Control the minimum distance to the target (RealSense option RS2_OPTION_MIN_DISTANCE). Availability of this parameter depends on the connected device and the current setting of the 'SourceSelector'. | |||
'name' | 'RealSense' | string | pre-defined | Name of the HALCON interface. | |
'NoiseFiltering' | real | RealSense Remote Device Parameter: Control edges and background noise (RealSense option RS2_OPTION_NOISE_FILTERING). Availability of this parameter depends on the connected device and the current setting of the 'SourceSelector'. | |||
'num_buffers' | <number> | 4 | integer | pre-defined | Number of buffers used for the image acquisition. |
'num_buffers_await_delivery' | <number> | integer | dynamic | Number of (image) buffers waiting for delivery by the RealSense Producer. | |
'num_buffers_underrun' | <number> | integer | dynamic | Number of lost buffers due to buffer queue underrun since opening the device. Queue underrun occurs when the RealSense Producer has a new image data available, but it has no free buffer to store them. | |
'PayloadSize' | string | RealSense Remote Device Parameter: refer to the SFNC for the meaning of this parameter. Serves informational purposes. | |||
'PixelFormat' | string | RealSense Remote Device Parameter: refer to the SFNC for the meaning of this parameter. Serves informational purposes. | |||
'port' | <port> | -1 | integer | pre-defined | The value is not used, so a default value is returned. |
'PostProcessingSharpening' | real | RealSense Remote Device Parameter: Controls the amount of sharpening in the post processed image (RealSense option RS2_OPTION_POST_PROCESSING_SHARPENING). Availability of this parameter depends on the connected device and the current setting of the 'SourceSelector'. | |||
'PreProcessingSharpening' | real | RealSense Remote Device Parameter: Controls the amount of sharpening in the pre processed image (RealSense option RS2_OPTION_PRE_PROCESSING_SHARPENING). Availability of this parameter depends on the connected device and the current setting of the 'SourceSelector'. | |||
'ReceiverGain' | real | RealSense Remote Device Parameter: Controls the exposure time of the avalanche photo diode in the receiver (RealSense option RS_OPTION_AVALANCHE_PHOTO_DIODE). Availability of this parameter depends on the connected device and the current setting of the 'SourceSelector'. | |||
'revision' | '<revision>' | string | pre-defined | Revision number of the RealSense interface. | |
'Saturation' | real | RealSense Remote Device Parameter: Control the saturation (RealSense option RS_OPTION_SATURATION). Availability of this parameter depends on the connected device and the current setting of the 'SourceSelector'. | |||
'settings_selector' | 'RemoteDevice', 'Stream', 'Device', 'System', 'Interface', 'Consumer' | 'RemoteDevice' | string | pre-defined | Selects for which component (set of parameters) the streamable parameters are persisted into a file or restored from a file when using set_framegrabber_param(..., 'do_write_settings', []) and set_framegrabber_param(..., 'do_load_settings', []). Selects among the actual (remote) device, one of the RealSense Producer modules or the Consumer parameters (internal parameters of RealSense image acquisition interface). Read more about the usage of this mechanism at Parameters – Persisting Device Status. |
'Sharpness' | real | RealSense Remote Device Parameter: Control the sharpness (RealSense option RS_OPTION_SHARPNESS). Availability of this parameter depends on the connected device and the current setting of the 'SourceSelector'. | |||
'SourceSelector' | 'Depth', 'Color' | string | RealSense Remote Device Parameter: Selects the hardware component that should currently be configured. Please see the corresponding section for more information. | ||
'split_param_values_into_dwords' | 'disable', 'enable' | 'disable' | string | pre-defined | Enables a special mode allowing the treatment of integer parameters as tuple of two 32-bit integers. For compatibility with the single-parameter mode, the first tuple element carries always the low 32-bit part of the value, second element carries the high 32-bit part. It is user's responsibility to combine the two parts correctly. This mode is intended especially to help to overcome the problem of 32-bit HALCON featuring only 32-bit integer parameters but having to face up to 64-bit wide GenICam features. In this mode, the get_framegrabber_param returns always a tuple of two integers, set_framegrabber_param accepts both a single parameter or a tuple. Note that this mode affects only integer parameters and only the GenICam based ones, not the internal parameters of HALCON RealSense image acquisition interface - with few exceptions, the 'buffer_timestamp', 'buffer_timestamp_ns', 'device_timestamp_frequency' and 'buffer_frameid' internal parameters. |
'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 | Unsupported, returns always 0. |
'start_row' | <row> | 0 | integer | pre-defined | Unsupported, returns always 0. |
'streaming_mode' | 0, 1 | 1 | integer | pre-defined | Value of the streaming_mode generic parameter specified in open_framegrabber. The streaming_mode is by default switched on for devices with streaming support and off for peripheral devices (devices without any data streams). The generic parameter streaming_mode explicitly allows switching the streaming functionality off, even for devices with streaming support. |
'vertical_resolution' | 0, resolution | 1 | integer | pre-defined | Current value of vertical resolution. |
'VisualPreset' | string | RealSense Remote Device Parameter: Allows to load sets of predefined configuration options to optimize the sensor for certain application profiles (RealSense option RS_OPTION_VISUAL_PRESET). This parameter is only accessible for the depth module. | |||
'volatile' | 'disable', 'enable' | 'disable' | string | pre-defined | Current value of the volatile mode. |
'WhiteBalance' | real | RealSense Remote Device Parameter: Controls the white balance of the color image. This parameter is provided as an alias for the 'BalanceRatio' parameter. | |||
'Width' | integer | RealSense Remote Device Parameter: Width of the currently configured sensor resolution. Contrary to the SFNC behaviour of this feature, for the RealSense Producer this parameter is a read only parameter. |
Operator set_framegrabber_lut
Operator get_framegrabber_lut
Operator set_framegrabber_callback
The callback can be registered for any GenICam based features, i.e., features published by the device and RealSense Producer through the GenICam description files as well as for internal parameters of the acquisition interface.
The list of supported callback targets can be queried by calling get_framegrabber_param(..., 'available_callback_types', ...).
One of the important use cases for feature change callbacks is the device event delivery mechanism, see details in event data and feature notifications sections. The 'CallbackType' parameter of set_framegrabber_callback defines the feature for which the callback is registered. It is the same plain feature name as used with set_framegrabber_param, including a possible prefix, such as '[Device]' (refer to the parameter naming convention).
The registered callback function would be called whenever a given feature is potentially changed (including its other properties such as range or access mode). Note that it does not necessarily always mean that the feature actually has a new value. If the callback function is set to NULL, the corresponding callback will be unregistered. Note that the interface keeps just a single registration for every feature, if you attempt to register a new callback for a feature that already had a callback registered, the previous registration will be replaced with the new one.
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. Up to now, this parameter is not used, i.e., Context is set to NULL.
- UserContext: Optional context data of the specific callback. Up to now, this parameter is not used, i.e., UserContext is set to NULL.
Note that the execution time of a user-specific callback function must
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 current processing from the
user-specific callback function to a separate thread that is controlled
via signals or events. The callback function is executed in the context
of the underlying interface or driver.
It is also important to understand that the callbacks might be fired as
a side-effect of parameter-setting or grab operations, ie. it might be
called from within their respective locks. The user is responsible
to take this into account in the callback handler to avoid risk of
a deadlock.
Operator get_framegrabber_callback
Operator grab_image_start
Operator grab_image
Operator grab_image_async
The 'MaxDelay' parameter of the grab_image_async operator is ignored by the HALCON RealSense acquisition interface, because there is no way to support it reliably . If needed, the application needs to implement alternative functionality on its own. The single image returned will contain the Z values of the 3D points.
Operator grab_data
Operator grab_data_async
The 'MaxDelay' parameter of the grab_image_async operator is ignored by the HALCON RealSense acquisition interface, because there is no way to support it reliably . If needed, the application needs to implement alternative functionality on its own. The image tuple returned will contain the X, Y and Z values of the 3D points. Based on the current configuration and device it will also contain the color overlay and the confidence map. If activated via the parameter 'create_objectmodel3d' the data variable will contain the ObjectModel3D.
Operator close_framegrabber
HDevelop Examples
- realsense_frame_rate.hdev - Measure the effective frame rate of an acquisition device.
- realsense_parameter_persistence.hdev - Writing parameter values to files and restore parameter values from files.
- realsense_simple.hdev - Use the interface to acquire 2D images.
- realsense_objectmodel3d.hdev - Automatically generation an ObjectModel3D during grab_data.
Release Notes
- Revision 18.11.3 (May 11, 2022):
- The underlying GenApi version has been updated to the latest official release 3.4. This fixes a crash during 'do_load_settings' when a device failed to execute the underlying command 'DeviceRegistersStreamingEnd'.
- On a Unix system, loading Consumer persistence or configuration ini that was written on a Windows system failed. This problem has been fixed. Moreover, writing Consumer persistence or configuration ini files on a Windows system has been changed to use Unix line ending.
- It is now possible to receive Feature Change Notifications on any parameter listed by 'available_param_names'.
- A new parameter 'event_new_buffer' has been added which is only available as an event, see Feature Change Notifications and following.
- There was a memory leak with each message delivered through the Event Message Queues mechanism. This problem has been fixed.
- The identifier (key 'id') of the
messages incoming on an event was not
always unique. This problem has been fixed. The device name in the
string '
: ' now corresponds with the 'unique_name' from info_framegrabber.
- Revision 18.11.2 (Oct 20, 2021):
- This interface now is also available for Linux and Linux for Arm (64-bit) systems.
- The description of the system requirements for Windows have been changed to clarify that full compatibility can only be expected with the correct version of the RealSense SDK installed.
- The distribution package of this interface now contains files providing meta information for the HDevelop example browser.
- Revision 18.11.1 (May 14, 2021):
- First official release.