Image Acquisition Interface for GenICam GenTL compliant cameras
|
Interface:
|
GenICamTL
|
|
Revision:
|
13.0.5
|
|
Date:
|
2018-10-30
|
General
System Requirements
- Intel compatible PC with Windows 7 (32-bit or 64-bit)
or newer that is also supported by the used GenTL Producer,
XP SP1/Vista/7/8, Windows XP/Vista/7/8 x64,
also WoW64 (using 32-bit HALCON on 64-bit Windows),
Linux with kernel 2.6 (or higher)
, or macOS.
- Successfully installed GenICam GenTL Producer.
The corresponding .cti file must be located in one of the
directories specified by the environment variable
GENICAM_GENTL32_PATH or GENICAM_GENTL64_PATH,
respectively. Otherwise, the full path to the GenTL Producer has to be
specified when opening the device.
- Depending on the used transport layer make sure that you have access
to the device. Follow all requirements and recommendations specified
by the respective GenTL Producer(s) to guarantee flawless and effective
access to the device(s). Especially for (Gigabit) Ethernet the following
points have to be checked:
- It is recommended to use a PCIe network adapter which supports
jumbo frames. Please configure the network adapter
accordingly, e.g., to a MTU value of 9000.
Furthermore, the camera should be connected directly to the network
adapter to avoid interference with other network traffic. Please be
aware that networking equipment like switches not necessarily
supports Jumbo frames.
- If you are using a firewall please make sure that your firewall
settings allow communication with the camera for discovery,
control and streaming, depending on your used transport layer.
For Windows the easiest way to do this is to allow the application
(i.e. HDevelop, or your compiled application) at the firewall.
- GenICam version
3.0.2
. The corresponding files are part of the
HALCON runtime installation and are located in the directory
genicam within the HALCON base directory %HALCONROOT%.
Since the HALCON GenICamTL interface sets all necessary environment
variables on its own, no environment variables like
GENICAM_ROOT_V2_x, PATH, LD_LIBRARY_PATH
must be set or modified. Old variables referencing GenICam V1.1, V2.0
or V2.1 are not used anymore and should be deleted if not needed by other
software. See section GenICam GenApi for more details.
- Windows:
HALCON image acquisition interface hAcqGenICamTL.dll or
hAcqGenICamTLxl.dll, respectively.
If you have properly installed the interface, all these DLLs should
reside in bin\%HALCONARCH% within the HALCON base directory
%HALCONROOT% you have chosen during the installation of HALCON.
Linux:
HALCON image acquisition interface hAcqGenICamTL.so or
hAcqGenICamTLxl.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.
macOS: HALCON image acquisition interface
hAcqGenICamTL.dylib or hAcqGenICamTLxl.dylib,
respectively. If you have properly installed the interface, the shared
objects should reside in the HALCON framework
/Library/Frameworks/HALCON.framework or the HALCON XL framework
/Library/Frameworks/HALCONxl.framework in the Libraries
subdirectory.
- The default acquisition mode assumes the computer is fast enough to
process all buffers from the camera. If this is not the case, they
are silently discarded (by the GenTL Producer).
Installation
Only when installing or updating the interface manually follow these steps:
- Windows: Extract the archive containing the interface files to the
HALCON base directory %HALCONROOT% (Note: Administrator privileges may be
required for this step). Additionally, you have to move the interface
examples to the directory %HALCONEXAMPLES% manually.
- Linux: Extract the archive containing the interface files to the
HALCON base directory $HALCONROOT.
- OS X: Extract the archive. Manually move the following files:
- The .dylib files located in lib/x64-macosx to
/Library/Frameworks/HALCON.framework/Libraries
- The genicam folder to /Library/Frameworks/HALCON.framework/Libraries
- The examples folder to the version subdirectory at
/Users/Shared/Library/Application Support
- The doc folder to the version subdirectory at
/Library/Application Support
Environment Variables
The interface can be controlled through several environment variables:
- GENICAM_GENTL32_PATH, GENICAM_GENTL64_PATH are standard
GenTL variables holding the list of directories where individual GenTL
Producers are installed. The installer of a GenTL producer usually adapts
these variables automatically. Alternatively you can specify the full path
to the producer when opening the device.
- HALCON_ACQUIRED_FILE_PAYLOAD_DIR is used to specify the directory
where non-image payload types (usually files or 'raw' data) are stored
using the filename given by the
device or GenTL Producer.
- When specifying a directory with HALCON_GENICAM_WRITE_XMLFILE
and/or HALCON_GENICAM_WRITE_RAW_XMLFILE, the GenICam description
files (in XML and/or raw format) will be stored there while working with
HALCON. These files can also be stored by setting the interface parameter
'do_write_configuration'.
- If you want to use an already installed GenApi version instead of the
one supplied with HALCON, you must set the environment variable
HALCON_USE_EXTERNAL_GENAPI. Additionally, all environment variables
which are necessary for GenApi must also be set in this case. This is
only for experts, see also section
GenICam GenApi.
Features
- Implementation of a GenICam GenTL consumer.
- Grabbing from multiple cameras.
- Flexible device lookup and connection options.
- Synchronous and asynchronous grabbing.
- Software control of all generic camera parameters using GenApi.
- Software control of all generic GenTL Producer parameters using GenApi.
- Support of various pixel formats and flexible color transformation.
- Support of 'Continuous', 'MultiFrame' and 'SingleFrame' acquisition modes.
- Support of GenICam action control.
- Support of GenICam chunk data.
- Support of GenICam event data.
- Support of GenICam feature persistence.
- Support of GenICam file access.
- Support of GenICam FWUpdate.
- Support of callbacks for feature change notifications.
- Support of non-streamable devices.
Limitations
- No support of BayerXXPacked, BGRXXPlanar, and RGBXXPlanar pixel formats yet.
- Simultaneous acquisition from multiple data streams of the same device
is currently not possible.
- No support of acquisition from devices with read-only access mode
- Limited support for devices with multiple ROI functionality.
GenICam GenApi
- This interface uses GenApi version 3.0.2,
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 GenICamTL 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,
Windows uses %TEMP% and Linux/macOS use $TMP or
/tmp if $TMP is not set for cached XML files.
GenICam GenTL
- GenTL is part of the GenICam standard and allows generic communication between a GenTL consumer like the HALCON GenICamTL
acquisition interface which is independent of specific transport layers
and hardware, and one or more GenTL producers which implement access
to the specific device hardware (usually a camera).
- GenTL producers are usually provided by the device manufacturer.
They implement the communication with the device regarding control and
data streaming (images) and present it in a uniform way to a GenTL
consumer. The consumer uses GenApi to access and control the device
features.
- The available GenICam GenTL Producers are searched within the path
set by the environment variable GENICAM_GENTL32_PATH or
GENICAM_GENTL64_PATH, respectively.
If none of these variables is set, the full path to the GenTL producer
has to be specified (see Identifying and opening
a device).
Identifying and Opening a Device
A device accessible through the GenTL interface is usually described as a set of four entities where the names are given by the specific GenTL
Producer.
- 'producer' - the name of the GenTL Producer which is used to
access the device.
- 'interface' - the name of the (logical) interface where the device
is connected. For example an Ethernet based GenTL Producer running on a
system with multiple network cards might present the IP or MAC address of
the network card where the device is connected as interface name.
- 'device' - the name of the device (typically camera). Note that
a device might be accessible through multiple producers or interfaces and
might therefore also be shown with different (hopefully similar) names.
- 'stream' - the name of each data stream of the device. Currently
only devices with no stream (peripherals) or a single (image) data stream
are fully supported, therefore this is not yet used.
The list of devices can be obtained using
info_framegrabber with parameter
'info_boards' (all detectable devices) or 'device' (only available ones).
Each entry consists of entries (the entities listed above and usually some
additionally ones) separated with a ' | ' (space - pipe - space) sequence.
The result of
info_framegrabber can be passed directly to
open_framegrabber.
Alternatively you can specify the device directly. For this
one or more of the entries can be omitted (or specified as 'default') - which
is like using wildcards, meaning that the particular ID for that entity
should not be considered (any ID would match). The HALCON acquisition
interface will walk the GenTL device tree (producer -> interface ->
device -> stream), until it finds an exact match for all non-default
entries.
The values for the individual entries are evaluated as follows for
open_framegrabber:
- 'producer': The value is interpreted as filename of the GenTL
Producer (always a file with .cti extension). If it is specified
using the full path, it's opened directly. If only a filename without path
is specified, the GenTL installation directories (specified via
GENICAM_GENTL32_PATH respectively GENICAM_GENTL64_PATH)
are searched. If the entry is 'default' or omitted, any GenTL Producer
found within the GenTL installation directories would match.
- 'interface': The value is interpreted as GenTL interface ID
(string identifier assigned to the interface by GenTL producer). When
'default' or omitted, any interface would match.
- 'device': GenTL device ID (string identifier assigned by GenTL
producer). When 'default' or omitted, any device would match, but only a
device that is currently reported as accessible by the GenTL producer,
non-accessible devices are skipped.
- 'stream': GenTL data stream ID. When 'default' or omitted, the
first data stream reported for given device is used.
When a string without any ' | ' separator is used, it is interpreted
directly as GenTL device ID (without the leading
device:, assuming
that producer, interface and stream are 'default'.
Alternative IDs:
- In addition to the GenTL device ID, devices can be opened by their
user-defined name ('DeviceUserID') if the device supports it.
If set, the string obtained by info_framegrabber will contain the entry
'user_name:<user-defined name>'. To make it easier
for the user, the 'device' entry reflects the user-defined name
if it is unique. If the same user-defined name is assigned
to more than one device, only the first one will use it,
all others will use the unique name instead.
- Some devices might (optionally) allow identifying the interfaces and/or
devices using other strings than the GenTL IDs. This might be for example
the device's MAC or IP address, serial number
or similar. If a GenTL producer supports this, alternative IDs can be used
also when opening devices.
- The GenICamTL interface has to maintain reference counting of the opened
producers, interfaces and devices. This is based on GenTL IDs; if using
alternative IDs it might be possible that the reference counting does
not work properly. We therefore recommend to use either always GenTL IDs
or always alternative IDs.
Selection of GenICam Feature Description File(s)
The features of a device or GenTL Producer are described by GenICam feature description files (XML files) that are automatically parsed
and offered to the user. The HALCON GenICamTL image acquisition interface
provides access to the features exposed through the following GenICam feature
description files:
- Features of the connected device
(in GenTL terminology "remote device"),
typically a camera, are usually loaded directly from the connected device.
- Features of the GenTL Producer, potentially one for each
(so called) GenTL module which corresponds to a node in the GenTL device
tree to the connected device:
- The "system", in GenTL terminology representing the overall behavior
of the GenTL Producer itself.
- The "interface" which is used to connect (logically) the device to the
system.
- The "device" (also "local device") which is a kind of proxy device,
controlling the GenTL producer's view of the device.
- The "data stream" used for the acquisition (if the device provides any
data streams).
In most cases the GenICam description files are provided by the device and
the GenTL Producer. It is possible to store a copy of these
files corresponding to an open connection by using the parameter
'do_write_configuration' (see
set_framegrabber_param).
The command will write all the GenICam
description files and an "ini" file (details in
set_framegrabber_param) with
various information, including the location of the written GenICam
description files, in the following format:
RemoteFile=%PATH_TO_GENICAM_FILE_OF_THE_DEVICE%
SystemFile=%PATH_TO_GENICAM_FILE_OF_GENTL_SYSTEM_MODULE%
InterfaceFile=%PATH_TO_GENICAM_FILE_OF_GENTL_INTERFACE_MODULE%
DeviceFile=%PATH_TO_GENICAM_FILE_OF_GENTL_DEVICE_MODULE%
StreamFile=%PATH_TO_GENICAM_FILE_OF_GENTL_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.
Parameters – Naming Conventions
The following groups of parameters exist:
- Internal parameters of the HALCON GenICamTL image acquisition
interface itself. These are named following the "underscore" naming
style, e.g., color_space, and are all lowercase.
- GenICam-based parameters of the
(remote)
device, usually a camera, use by
convention the "CamelCase" style, e.g., ExposureTime.
- GenICam-based parameters of the individual GenTL 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 – Sharing Among Devices
The parameters belonging to the system and interface modules of the GenTL Producer (ie. those with "[System]" and "[Interface]" prefix see
Parameters – Naming Conventions ) must be treated in a special way.
To grasp their behavior, it is important to understand that they do not describe
or configure the device itself and do not thus fully belong to the opened instance of the device.
The interface module parameters belong to the interface on which given device was discovered
and is shared among all devices open under this interface (see also
Identifying and Opening a Device).
The system module parameters belong to the entire GenTL Producer and are shared
among all devices open within this GenTL Producer.
This has several implications. In particular, when accessing the system or interface module parameters
through multiple device instances, those parameters must be treated as shared resources.
Modifying those parameters through one device instance affects their values (and possibly values
of other features depending on them) as seen through other device instances. Initial values of those
parameters after opening a device instance might depend on the interactions with these features
from previously opened device instances.
Parameters – GenICam Data Types
HALCON native parameter types are
- integer – signed integer, 64-bit on 64-bit platforms, 32-bit on
32-bit ones
- real – floating point type
- string – classical string
When accessing GenICam-based features, the GenICam data types must be mapped
to the parameter types recognized by HALCON. GenICam offers the following
types:
- 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
The current status of the device settings (values of all the parameters defining its working state) might be persisted while no acquisition
is active, i.e. before
grab_image_start or
grab_image_async or after
set_framegrabber_param(..., 'do_abort_grab', 1).
The persistence functionality consists of two steps, storing the current configuration
to a file and later re-loading it back to the device.
The current device settings can be stored using the 'do_write_settings' parameter
and re-loaded later using the 'do_load_settings' parameter, specifying the desired
persistence file path in both cases.
Note that while the format of the file is intentionally human readable and the file
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 file can lead to errors when using it.
It is important to know that while performed by the software, the feature settings
persistence is actually a camera-side function. If the persistence support is implemented
incorrectly or incompletely by the device, it will not work as expected – in such
a case the camera manufacturer could provide additional information or help.
The same persistence file can be applied to the entire set of devices of the same type
and firmware version. Applying the persistence file to a device of another type
or using even different firmware version will probably lead to inconsistencies
or will even fail completely – the corresponding device manufacturer should provide
guidelines for such use cases.
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 also generate persistence files for all the GenTL 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_GENTL_SYSTEM_MODULE%
InterfacePersistence=%PATH_TO_PERSISTENCE_FILE_OF_GENTL_INTERFACE_MODULE%
DevicePersistence=%PATH_TO_PERSISTENCE_FILE_OF_GENTL_DEVICE_MODULE%
StreamPersistence=%PATH_TO_PERSISTENCE_FILE_OF_GENTL_STREAM_MODULE%
If the persistence functionality is not supported properly (or at all) by a given
device, use the GenICam features UserSetSave/UserSetLoad, if supported by the device.
These features will allow to store/load the device settings in the device's
non-volatile memory.
Acquisition – Overview, Device Control
The image acquisition can be either synchronous (
grab_image/
grab_data) or asynchronous (
grab_image_start/
grab_image_async/
grab_data_async),
see the reference documentation of the operators.
The interface fully configures and controls the acquisition process on the
camera and GenTL producer.
Note that some of the camera
or producer
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', ...).
Note that the interface properly recognizes the 'Continuous', 'SingleFrame'
and 'MultiFrame' acquisition modes configured on the device and adjusts the
acquisition control logic accordingly.
Note that the HALCON acquisition interface itself 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 – Buffer Handling
The interface allocates 4 buffers for the acquisition engine by default (the number of buffers can be changed through the 'Generic' parameter of
open_framegrabber).
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'. This applies also to
Chunk Data
eventually present in the buffer and is also usable in volatile
mode.
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.
With modern, generic image acquisition interfaces an application cannot make valid assumptions about the image format coming from the device based on the
current settings. Some devices for example allow changing the image format
properties while the acquisition is active.
Other setups contain multiple devices in the
acquisition path (and e.g. a frame grabber might be modifying the image
format provided by the camera).
The HALCON GenICamTL image acquisition interface fully supports these
use cases. It checks the image format and other important properties of
every single buffer and generates HALCON images corresponding to both the
acquired image format and eventual user configured output format parameters
such as 'color_space' and 'bits_per_channel'. Only if the necessary
information about the buffer are missing
(i.e., the GenTL Producer does not support it)
, the current settings are used as a fallback.
Acquisition – Grab Operators
The acquisition interface provides two mechanisms for acquisition of the image (or other) data from the device,
grab_image/
grab_image_async and
grab_data/
grab_data_async. Each of them might be more suitable for different
use cases. Internally, both mechanisms work exactly the same (in particular
how they acquire and process the data from the device), they differ in the way
how the outputs are provided to the application.
The "traditional"
grab_image/
grab_image_async operators are still well suitable
in simple use cases when just a single 2D image is acquired from the device.
It is also currently used e.g. by the HDevelop's Image Acquisition Assistant.
However, in case when the device is streaming more complex data structures,
such as 3D data, multi-AOI or similar data,
grab_image/
grab_image_async
is not able to provide all the outputs. In all these cases it will simply
provide the first image found in the acquired data.
The "extended"
grab_data/
grab_data_async operators allow to output arbitrary
number of HALCON images and also arbitrary number of control data. It is therefore
suitable for use in advanced use cases when more than just a single HALCON image
should be output. An important use case is acquisition from 3D devices
(
Using 3D Devices) when the operators can build and output
the 3D object model through the control data output. It can be also used
in other (possibly even device-specific) situations when the device outputs
multiple images for a single acquisition.
The structure of the provided outputs can be queried with help of the
'image_contents', 'data_contents' and related parameters.
The
grab_data/
grab_data_async can also be used in the simple single-image
use cases - in that case they will simply provide a single HALCON image
and zero control data outputs. They can thus be used as full replacement
of the traditional
grab_image/
grab_image_async operators.
Using 3D Devices
The acquisition interface fully supports the GenICam standard 3D device model and is thus capable to seamlessly integrate 3D devices compliant with this
model. This means in particular that the application does not need to care
about device-specific ways of 3D data formatting, the acquisition interface
will generate the 3D data under the hood using the information from the device.
If instructed so (using the 'create_objectmodel3d' parameter), the acquisition
interface will generate the 3D object model from the coordinate data acquired
from the device. This model can be directly used by the HALCON's 3D object model
related operators.
The completeness and accuracy of the final 3D object model strongly depends
on the actual coordinate data and in particular on the 3D configuration information
provided by the device. Because the 3D configuration metadata are typically passed
from the device through the chunk data mechanism
(
Chunk Data), it is essential to observe that
the chunk data generation is fully enabled on the device.
If some of the important 3D configuration information is missing, the acquisition
interface will try to use the suitable defaults, but the quality of the 3D object
model output can be lowered.
The creation of the 3D object model can be further affected by additional parameters
such as 'coordinate_transform_mode', 'confidence_mode', 'confidence_threshold',
'add_objectmodel3d_overlay_attrib'.
Note: for devices not complying with the GenICam standard 3D device model
the HALCON 3D object model cannot be automatically generated.
Note that the 3D object model output is only supported by the
grab_data/
grab_data_async
operators, it cannot be acquired using
grab_image/
grab_image_async. Besides the
3D object model, the
grab_data/
grab_data_async operators also output the actual
raw coordinate data in form of HALCON images. The individual outputs can be identified
with help of 'image_contents', 'data_contents' and related parameters.
Raw Output Format – Custom Pixel Formats, Non-image Buffers
The HALCON GenICamTL image acquisition interface has a built-in converter from the pixel formats described in the GenICam Standard Features Naming
Convention to the desired HALCON image format. The parameters ColorSpace
and BitsPerChannel (
open_framegrabber, eventually
set_framegrabber_param)
define the desired format of the resulting HALCON image. If these parameters
are set to defaults, the original pixel format coming from the device is
preserved.
To offer a basic support of custom pixel formats (i.e., pixel formats not
defined by PFNC or not supported by HALCON), the ColorSpace value 'raw' can
be used. In this case the image acquisition interface delivers the buffer to the
application without any format conversions.
Note that the same principle is applied whenever a buffer containing other
than image data is acquired. Examples of such buffers can be files (e.g.,
compressed images) or raw data (results of smart camera processing). Such
buffers are not real "images", but can still be delivered to the application
as 'raw' HALCON images. It is the responsibility of the application to know
how to interpret such data.
Last but not least, the 'raw' color space can also be used if the user explicitly wishes
to receive raw input data without any conversions. For example when
acquiring Bayer encoded images, specifying 'raw' means that the interface
should not attempt to decode them to RGB or monochrome format, but deliver
the data directly to the application.
It is important to know that when the interface does not have full information
about the image format (dimensions and pixel format), it has to choose an
artificial one. In such a case it delivers always an 8-bit image with
dimensions matching the buffer size (square root of the image size).
Eventually an unused tail of the HALCON image (if such an artificial image is
bigger than the source buffer) will be padded with zeroes. The fact whether
the last acquired buffer contained an image of known properties or a blob of
other data (so that the artificial HALCON image size had to be used) as well
as the size of the eventual tail padding can be queried using
'raw_buffer_type' and 'raw_buffer_padding_bytes' parameters.
Chunk Data
GenICam compatible cameras can deliver additional meta-data with every image in a so-called chunk data format. It is usually necessary to enable
the delivery of individual meta-data "chunks" using the features
'ChunkModeActive' and 'ChunkSelector'/'ChunkEnable' first.
The decoding of the chunk data and matching them to the corresponding camera
features is performed transparently by the interface.
The actual values might be read through the regular parameter reading
mechanism, i.e.,
get_framegrabber_param. The choice of the meta-data to be
delivered is device-specific. The names of the chunk related features usually
start by convention with a prefix 'Chunk' (examples might be
'ChunkExposureTime' or 'ChunkGain'), however, the camera documentation should
contain all the information about supported chunks and their corresponding
feature names.
It is important to remember, that the chunk data related features will
provide only meaningful values if the "last acquired buffer" is valid, i.e.,
between delivery of the last image and next call to any grab-related operator
(refer to section
Acquisition – Buffer Handling).
Feature Change Notifications
It is possible to receive notifications about changes of any features exposed through the GenICam interface by the camera and GenTL Producer.
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.
Note that the notifications are raised whenever the feature is "marked dirty"
(its cache invalidated) by one of the actions described above. It does not
necessarily mean that its value has really changed, it is up to the
application to check this.
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
GenICam compatible devices can deliver asynchronous events which optionally carry additional data. It is usually necessary to enable delivery
of individual event types using the features
'EventSelector'/'EventNotification' first.
For SFNC-compliant events, this is done automatically if the parameter
'event_notification_helper' is enabled.
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 GenTL Producer (system, interface, device
and data stream). The information provided above about handling of the device
events applies similarly also to the GenTL 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.
The interface will automatically capture and decode the events and match them
to the corresponding GenTL Producer features. It is only important
to understand that because the system and interface modules are potentially
shared among multiple opened devices
(see
Parameters – Sharing Among Devices) and so,
the same applies for asynchronous events generated by these shared modules.
Event Message Queues
This interface supports feature change notifications via message queues. Select the desired target feature with
set_framegrabber_param(..., 'event_selector', ...).
It is the same plain feature name as used with
set_framegrabber_param, including a possible prefix, such as '[Device]' (refer to
the
Parameters – Naming Conventions).
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 GenTL Producer
through the GenICam description files. The list of supported
targets can be queried by calling
get_framegrabber_param(..., 'available_event_types', ...).
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.
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>:<device>'. 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.
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 available.
Using HDevelop Image Acquisition Assistant
In case of using the HDevelop Image Acquisition Assistant the following hints will help to avoid problems:
- 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.
Using Internal Color Conversion
The HALCON GenICamTL interface supports an internal color conversion performed in software. The conversion is automatically applied for PFNC (Pixel Format Naming Convention) compatible cameras, when the color format delivered by the camera differs from the user defined format if set via the parameter 'color_space'. The used transformation algorithms are basic and optimized for speed.
Following transformations from the camera color space (see also PFNC) to the interface color space (see also 'color_space' parameter in this document) are supported:
- Bayer pattern to 'rgb':
| Bayer_LMMN |
|
|
|
|
⇾
|
[R,G,B] |
[R,G,B] |
[R,G,B] |
[R,G,B] |
|
|
| Bayer_NMML |
|
|
|
|
⇾
|
[R,G,B] |
[R,G,B] |
[R,G,B] |
[R,G,B] |
|
|
with G = (G1 + G2) / 2
.
- Y'CbCr to 'rgb' (Note: gamma correction is not considered):
R = Y' + 1.4020 * (Cr- M)
G = Y' - 0.34414 * (Cb- M) -0.71414 * (Cr- M)
B = Y' + 1.7720 * (Cb - M)
- RGB to 'yuv' ('yuv' corresponds to Y'CbCr of PFNC, Note: gamma correction is not considered):
Y' = 0.299 * R + 0.587 * G + 0.114 * B
Cb = -0.16874 * R - 0.33126 * G + 0.5 * B + M
Cr = 0.5 * R - 0.41869 * G - 0.08131 * B + M
- RGB to 'gray':
Y' = 0.299 * R + 0.587 * G + 0.114 * B
with
M = 128
for 8 bit raw data, and
M = 32768
for 16 bit raw data.
The accuracy of the results is limited due to internal 16.16 fix-point arithmetic for 8 bit ( 0...255), and 24.8 fix-point arithmetic for 16 bit raw data.
Firmware Update
The acquisition interface supports the GenICam FWUpdate standard, allowing to update firmware on devices supporting the same standard in a generic way.
If the device supports the standard, its vendor would distribute the firmware
update files in form of GUF files, i.e. files with
.guf extension.
To apply the firmware update, the device must be opened (
open_framegrabber)
in a special configuration mode (called "safe mode"). This mode is selected
through the 'Generic' parameter of
open_framegrabber - the parameter must
include 'device_access=safe-mode'.
When opened in the safe mode, most of the usual parameters (either those
provided by HALCON acquisition interface, the device itself or the
GenTL Producer) will be unavailable. Instead, the configuration
parameters corresponding to the given device and interface technology and in
particular the parameters related to firmware update will become available.
To update the device, the GUF file is first selected in 'fwupdate_file_path',
one of the (possibly multiple) updates from the file selected using
'fwupdate_update_selector' and finally applied through 'do_fwupdate_apply'.
Documentation of these parameters provides further details.
Note that the update procedure may include one or more device resets,
after which the device has to be re-discovered by the acquisition interface.
The time needed for reset and re-discovery is specified by device vendor
in the GUF file. However, there might be situations (depending on the device
itself, its connection technology and system setup) when the re-discovery
timeout is not sufficient and the device fails to get safely re-discovered.
In such case, it is possible to specify an addtional timeout that would be added
to the one specified in the GUF file, allowing to successfully complete
the process. This parameter, 'fwupdate_wait_after_reset', specifies the
additional timeout in milliseconds.
See also the HDevelop example genicamtl_fwupdate.hdev.
| Parameter |
Value List |
Type |
Kind |
Description |
| 'bits_per_channel' |
[-1, 8, 10, 12, 14, 16] |
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> | user_name:<user-defined name> | interface:<interface id> | producer:<cti file including path>'] |
string |
dynamic |
List of GenTL devices discovered in the system with information about their device ID, unique name, user-defined name,
interface ID and path to the GenTL Producer file.
See the full description in section about device
opening.
Only devices that are currently available for opening are listed.
|
| 'external_trigger' |
[] |
|
|
Ignored. |
| 'field' |
[] |
|
|
Unused. |
| 'general' |
[] |
string |
pre-defined |
Information about the HALCON GenICamTL interface. |
| 'generic' |
['', 'num_buffers=<num>', 'device_access=<mode>',
'direct_connection=<mode>',
'streaming_mode=0',
'device_event_handling=0',
'workarounds=<list>']
|
string |
pre-defined |
Value list for the Generic parameter. |
| 'horizontal_resolution' |
[0, 1] |
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> | user_name:<user_defined_name> | interface:<interface_id> | producer:<cti file including path> |
vendor:<device_vendor> | model:<device_model> | tl_type:<tl_type> |
status:<device_status>']
|
string |
dynamic |
List of GenTL devices discovered in the system with additional information as a string. Some values are only shown, if they are available.
- device_id is the name of the device, which will be shown by
info_framegrabber(...,'device',...). If a user_name (or
'DeviceUserID') is set, then this will be shown. Otherwise the unique_name
is used.
- unique_name is a unique identifier for the device. The format of
the string depends on the type of transport layer.
- user_name represents the value of the feature 'DeviceUserID',
which is a user-defined name for the device. It can be set if the
device is opened and provides this feature.
- interface shows the hardware interface by which the device is
connected to the PC. For transport layer type 'GEV' for example, this is the
MAC address of the network card.
- producer shows the full path of the GenICamTL producer's cti file.
- vendor represents the value of the feature 'DeviceVendorName'.
- model represents the value of the feature 'DeviceModelName'.
- tl_type shows the type of the underlying transport layer, e.g.
'GEV', 'U3V'.
- status shows, if the device is correctly configured or not. The
possible values are 'available', 'read-only', 'busy', and 'unknown'.
Even devices that are currently not available for opening are listed.
|
| '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 GenICamTL interface. |
| 'start_column' |
[] |
|
|
Unsupported query. |
| 'start_row' |
[] |
|
|
Unsupported query. |
| 'vertical_resolution' |
[0, 1] |
integer |
pre-defined |
Value list for vertical resolution. |
| Parameter |
Values |
Default |
Type |
Description |
| Name |
'GenICamTL' |
|
string |
Name of the HALCON interface. |
| HorizontalResolution |
0, 1, resolution |
1 |
integer |
Set the desired horizontal resolution of the camera image:
- 0: Keep the current Width settings of the camera.
- 1: If vertical_resolution is also set to 1, configure
full resolution of the camera using GenICam SFNC features
(resetting binning/decimation features and setting the image
size to maximum).
- resolution: Use the value directly as image Width.
|
| VerticalResolution |
0, 1, resolution |
1 |
integer |
Set the desired vertical resolution of the camera image:
- 0: Keep the current Height settings of the camera.
- 1: If horizontal_resolution is also set to 1, configure
full resolution of the camera using GenICam SFNC features
(resetting binning/decimation features and setting the image
size to maximum).
- resolution: Use the value directly as image Height.
|
| 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, 8, 10, 12, 14, 16 |
-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. By specifying a value
greater than 8 the grabbed images are delivered as uint2 images.
|
| 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>', 'device_access=<mode>',
'direct_connection=<mode>',
'streaming_mode=0',
'device_event_handling=0',
'workarounds=<list>'], -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:
- num_buffers:
To set the maximum number of acquisition buffers used. Note that
depending on the image size of the used camera a high number of
buffers can exceed the available memory size of your computer. We
recommend to use at least 2 buffers. Notice that the interface internally
locks 1 buffer (see acquisition buffer
handling), therefore if your application requires n buffers,
'num_buffers' must be set to n+1. Default: 4.
- device_access:
With this parameter the access mode of the device can be set. Valid
values are 'exclusive' for exclusive read/write access,
'control' for read/write access with possibility that another application
connects in read-only mode, and 'read-only' for read-only access.
Special value 'safe-mode' opens the device in restricted mode allowing
to execute firmware update (see Firmware Update).
Default: 'exclusive'.
- direct_connection:
Enables direct connection to the device using its known GenTL interface
and device ID. The GenTL specification allows opening the device directly
when the device/interface ID is known, without explicitly instructing
the GenTL Producer to refresh its internal device list, thus optimizing
unnecessary timeouts.
Because some GenTL Producers fail to implement this properly, the
parameter is disabled by default. Possible values are 'enable' and
'disable'.
- streaming_mode:
In order to disable streaming (grab-related operators), this parameter
has to be set to 0. The streaming is by default switched on for
devices with streaming support.
- device_event_handling:
In order to disable device events which can be useful in case of handling
multiple cameras to reduce the used resources like the number of transfers
in the Producer, this parameter has to be set to 0. The event handling is
by default switched on for devices with event support.
- workarounds:
Enables one or more of the workarounds supported by the GenICamTL
image acquisition interface. The workarounds are options slightly altering
the image acquisition interface behavior in order to cope with some common
problems of devices
and GenTL Producers
.
The individual workaround names might be listed using any separator, for
example a space or comma. Supported workarounds are:
- enable_range_validation:
When this workaround is enabled, an additional check is performed when
querying the range of a parameter: check if min <= max – and an error is
returned if the check fails. The invalid range of a GenICam based
parameter might be the result of a bug in the corresponding GenICam
description file.
- buffer_alloc_by_consumer:
The acquisition buffers are allocated by the image acquisition interface
itself (the "GenTL Consumer") rather than by the GenTL Producer. To be
used in rare situations when the GenTL problems fails to support buffer
allocation properly. Both ways of allocation are equivalent in most
cases, except situations when the Producer has special requirements, such
as allocating aligned memory or similar - therefore the allocation by the
GenTL Producer is chosen by default.
- ignore_buffer_pixelformat:
This workaround requires that the image pixel format reported by GenTL
Producer in individual buffers is ignored. Pixel format currently
configured in the GenICam feature 'PixelFormat' of the device is used
instead. Intended for rare situations when the pixel format reported in
the buffer might be incorrect for given GenTL Producer and device
combination. Note that this approach might not lead to correct results,
for example when the GenTL Producer modifies the image data or when the
device might allow changing the pixel format during active acquisition.
Therefore this workaround should be used with special care.
- indirect_event_handling:
Some aspects of event handling between, especially related to the
'EventKill()' GenTL function were not specified fully unambiguously
in the GenTL standard. If the GenTL Producer implements the event
handling in an unexpected way, various problems including deadlocks
could occur. This workaround allows to avoid such problems
by handling the event related GenTL calls in the Consumer rather than
relying on the GenTL Producer.
- tolerate_missing_acquisition_control_features:
Tolerates if otherwise required features to control acquisition
(in particular the 'AcquisitionStart' and 'AcquisitionStop' commands)
are not provided by the device. Note that in this case it is automatically
assumed that the device uses 'Continuous' acquisition mode (unlimited
number of frames per acquisition) and any other acquisition mode would not
work reliably. This workaround is automatically switched on for
CameraLink devices.
|
| 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 GenTL Producer,
see detailed description in section
about device opening.
|
| Device |
' | device:<device id> | unique_name:<unique name> | user_name:<user-defined name> | interface:<interface id> | producer:<cti file (including path)> | stream:<stream id>', '<device id>' |
|
string |
To open a camera, 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 camera, either device or unique_name has to be set.
Additionally, the ID of the device's data stream to be used for
acquisition might be specified.
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 section about device opening.
|
| Port |
--- |
|
|
Unused. |
| LineIn |
--- |
|
|
Ignored. |
The parameters of the cameras and GenTL Producer are accessed through GenICam and defined in GenICam description file(s) of the respective
camera or GenTL Producer, so the parameter set is different for
every product (although the parameter naming should adhere to SFNC
and GenTL SFNC
GenICam standard). A call of
get_framegrabber_param(...,
'available_param_names', ...) returns a tuple containing all available
parameters of the connected camera and GenTL Producer. See also
section about
parameter naming convention.
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
GenTL Producer, the following HALCON interface parameters are
supported by
set_framegrabber_param:
| Parameter |
Values |
Default |
Type |
Description |
| '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.
|
| 'bits_per_channel' |
-1, 8, 10, 12, 14, 16 |
|
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. By specifying a value
greater than 8 the grabbed images are delivered as uint2 images.
|
| '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.
|
| '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 an 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').
|
| '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:
- off:
Default value. The pixel confidence information is not applied to any of the grab operator outputs,
even if supplied by the device.
- object_model_3d:
If the pixel confidence level information is available, it is applied to the eventually generated
3D object models (but not to any other outputs, in particular not to the image outputs).
This means that pixels ("points") with confidence lower than the configured threshold are not included
in the generated 3D object model.
|
| '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.
|
| '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 Using 3D Devices for more details.
Possible values are:
- none:
The acquisition interface will not perform any coordinate transformation. The 3D object model
will contain the "raw" coordinates, possibly only scaled depending on the hints from the device.
- cartesian:
If the coordinate system used by the device is other than Cartesian, the acquisition interface
will convert the coordinates to Cartesian system (native for HALCON's 3D object model).
It will not attempt to further transform the coordinates from the device's internal ("anchor")
coordinate system to the reference system.
- reference:
Default mode.
Will transform to Cartesian coordinates if needed and then attempt to transform to
the "reference" coordinate system if the device supports it and provides corresponding
instructions. The purpose of the reference system is to allow merging and aligning data
from multiple devices. The reference system is in contrast with the native ("anchor")
coordinate system which is device specific and corresponds to its actual measurement
system and actual configuration.
The position and orientation of the reference system should be indicated
by a reference point marker on the device's housing.
This always directly implies the transformation to Cartesian coordinates because the reference
coordinate system is always Cartesian.
|
| '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
Using 3D Devices 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 GenTL Producer.
The optimal value depends on the speed of the used device and extra safety
required by the GenTL Producer. With a robust GenTL Producer, no delay
should be needed.
|
| 'do_abort_grab' |
--- |
|
|
Aborts the current image acquisition and unlocks parameters, that might be locked when acquisition is active.
See acquisition overview.
|
| 'do_fileaccess_delete' |
--- |
|
|
Deletes content of device file 'fileaccess_remote_name', provided that the device supports the file delete operation.
Note that all file access related parameters are available only if given
device supports the GenICam file access functionality.
|
| 'do_fileaccess_download' |
--- |
|
|
Downloads content of device file 'fileaccess_remote_name' into host file specified in 'fileaccess_file_path'.
Note that all file access related parameters are available only if given
device supports the GenICam file access functionality.
|
| 'do_fileaccess_upload' |
--- |
|
|
Uploads data from host file 'fileaccess_file_path' into device file specified in 'fileaccess_remote_name'. It is user's responsibility
that the size and content of the source file matches device's expectations.
Note that all file access related parameters are available only if given
device supports the GenICam file access functionality.
|
| 'do_fwupdate_apply' |
--- |
|
|
Applies the firmware update selected in 'fwupdate_update_selector'. Note that all firmware update related parameters are available only in the dedicated
"safe mode", see Firmware Update.
|
| 'do_load_settings' |
<input_file> |
|
string |
Restores the previously stored settings of the opened device. See detailed description in section Parameters - Persisting
Device Status.
|
| 'do_write_configuration' |
<output_directory> |
|
string |
Writes a configuration (ini) file specified with full path through the string parameter value. Writes also GenICam description files
of the remote device and each GenTL Producer module
associated with currently opened device. The GenICam description
files are written to the same directory as the ini file itself.
The written ini file contains in particular paths to the written
GenICam description files and can be reused through the 'CameraType'
parameter of open_framegrabber operator, see
detailed description in section about device opening.
Additionally, it writes also persistence files with current
configuration of the device and all GenTL Producer modules
that can be loaded back when next time opening the device
using the same 'CameraType' parameter of open_framegrabber
described above.
Instead of specifying the path of the output ini file, 'default'
or an empty string can be used. In this case the files will be
written to the %TEMP% directory and the filename of the configuration
file will be halcon_gentl_config.ini. Note that this default option
will apply also 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. See detailed description in section
Parameters - Persisting Device Status.
|
| 'event_data' |
'<genicam_feature>' |
|
string |
Selects GenICam features to be added to the message queue specified by 'event_message_queue' and 'event_selector'. Features
can be added individually or as a tuple. 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.
The corresponding GenICam feature needs to be
previously specified by 'event_selector'.
Read more about the usage of this mechanism at
Event Message Queues.
|
| '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>' |
|
string |
Selects a GenICam feature for which the acquisition interface should send
Feature Change Notifications.
They are sent to the message queue specified by 'event_message_queue'.
Read more about the usage of this mechanism at
Event Message Queues.
|
| 'fileaccess_file_path' |
'<file_path>' |
|
string |
Specifies full path to a local file (in host filesystem) that should be used for file exchange operations between host and the device,
'do_fileaccess_download', or 'do_fileaccess_upload'.
The current user/process must have sufficient rights to access the file.
Note that all file access related parameters are available only if given
device supports the GenICam file access functionality.
|
| 'fileaccess_remote_name' |
'<file_name>' |
|
string |
Selects a file on the device that should be subject to one of the file access handling operations, 'do_fileaccess_download', 'do_fileaccess_upload',
or 'do_fileaccess_delete'.
The name must be one of the files implemented by the device - the set
of valid names can be queried using 'fileaccess_remote_name_values'.
Note that all file access related parameters are available only if given
device supports the GenICam file access functionality.
|
| 'fwupdate_file_path' |
'<file_name>' |
|
string |
Path to the file carrying GenICam compatible firmware update (guf-file). When set, the file will be validated and included firmware updates enumerated.
When invalid or when no updates matching the current device will be found,
error will be raised. If successful, the set of matching updates can be queried
using 'fwupdate_update_selector_values' and the actual update to apply selected
using 'fwupdate_update_selector'. Finally, the selected update can be applied
using 'do_fwupdate_apply'.
Note that all firmware update related parameters are available only in the dedicated
"safe mode", see Firmware Update.
|
| 'fwupdate_update_selector' |
'<firmware_update_label>' |
|
string |
Selects firmware update that can be applied through 'do_fwupdate_apply'. The selector will become available after selecting a valid firmware update
file in 'fwupdate_file_path'. The options (labels describing the matching
firmware updates found in that file) can be queried using
'fwupdate_update_selector_values'.
Note that all firmware update related parameters are available only in the dedicated
"safe mode", see Firmware Update.
|
| 'fwupdate_wait_after_reset' |
'<timeout>' |
|
integer |
Additional timeout (in ms) applied before device re-discovery if a device reset is required during the firmware update procedure. The timeout is added to corresponding timeout
specified in the firmware update file itself. Intended to resolve system-specific
problems when the device cannot be safely re-discovered using the original timeout.
Note that all firmware update related parameters are available only in the dedicated
"safe mode", see Firmware Update.
|
| 'grab_timeout' |
<milliseconds> |
5000 |
integer |
Desired timeout (milliseconds) for aborting a pending grab. If -1 is specified, the timeout is set to INFINITE.
|
| 'image_height' |
--- |
0 |
|
Unsupported (read-only parameter). |
| 'image_width' |
--- |
0 |
|
Unsupported (read-only parameter). |
| 'register_<addr>_<len>' |
|
|
integer |
Direct register access for reading and writing integers. The value has to be hexadecimal, e.g. 0x0938. Note that only 4 or 8 Byte length values
are accepted.
Caution: This is a dangerous function intended for debugging and special
cases. Usually only features in the XML should be used.
|
| '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 GenICamTL
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.
|
| '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.
|
There may exist additional read-only parameters with the following postfixes:
- '_access': These parameters provide the access permissions of
the corresponding parameter as a string. Possible values are
'ro' (read-only), 'wo' (write-only), and
'rw' (read/write).
- '_category': These parameters provide the category of the
corresponding parameter as a string.
- '_description': These parameters provide the tool-tip of the
corresponding parameter as a string.
- '_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'.
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 |
| '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.
|
| '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
GenTL 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 GenICamTL image acquisition interface and those published by the device
and GenTL Producer via the GenICam interface (see
parameter naming conventions). Note that availability
of some parameters might depend on acquisition status, values of other
parameters or other conditions, so the list dynamically changes during
runtime.
|
| 'bits_per_channel' |
-1, 8, 10, 12, 14, 16 |
-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. By specifying a value
greater than 8 the grabbed images are delivered as uint2 images.
|
| 'buffer_frameid' |
<frame_id> |
|
integer |
dynamic |
Frame ID attached to the last grabbed (image) buffer by the device (or GenTL 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 GenTL 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. DSGetBufferInfo -> BUFFER_INFO_FRAMEID
|
| '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. DSGetBufferInfo -> BUFFER_INFO_IS_INCOMPLETE
|
| '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 GenTL 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. DSGetBufferInfo -> BUFFER_INFO_TIMESTAMP
|
| 'buffer_timestamp_ns' |
<timestamp> |
|
integer |
dynamic |
Timestamp attached to the last grabbed (image) buffer by the device (or GenTL 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. DSGetBufferInfo -> BUFFER_INFO_TIMESTAMP_NS
|
| '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.
|
| '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 an 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. |
| '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:
- off:
Default value. The pixel confidence information is not applied to any of the grab operator outputs,
even if supplied by the device.
- object_model_3d:
If the pixel confidence level information is available, it is applied to the eventually generated
3D object models (but not to any other outputs, in particular not to the image outputs).
This means that pixels ("points") with confidence lower than the configured threshold are not included
in the generated 3D object model.
|
| '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.
|
| '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 Using 3D Devices for more details.
Possible values are:
- none:
The acquisition interface will not perform any coordinate transformation. The 3D object model
will contain the "raw" coordinates, possibly only scaled depending on the hints from the device.
- cartesian:
If the coordinate system used by the device is other than Cartesian, the acquisition interface
will convert the coordinates to Cartesian system (native for HALCON's 3D object model).
It will not attempt to further transform the coordinates from the device's internal ("anchor")
coordinate system to the reference system.
- reference:
Default mode.
Will transform to Cartesian coordinates if needed and then attempt to transform to
the "reference" coordinate system if the device supports it and provides corresponding
instructions. The purpose of the reference system is to allow merging and aligning data
from multiple devices. The reference system is in contrast with the native ("anchor")
coordinate system which is device specific and corresponds to its actual measurement
system and actual configuration.
The position and orientation of the reference system should be indicated
by a reference point marker on the device's housing.
This always directly implies the transformation to Cartesian coordinates because the reference
coordinate system is always Cartesian.
|
| '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
Using 3D Devices 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 tuple of the size
corresponding to the number of control data values returned through those operators.
Possible values are:
- unknown:
The logical type of the data could not be identified.
- object_model_3d:
Integer representing a handle of the 3D object model generated from the acquired data.
IMPORTANT: the model has to be released (clear_object_model_3d) when no more
used, otherwise the associated resources will be leaking. The generation of the
3D object models is controlled using 'create_objectmodel3d' parameter (disabled
by default). Beware that in special use cases more than one object models can be
generated.
- text_report:
Might be used for internal purposes and during support cases. Should be ignored by all
applications.
|
| '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 tuple of the size
corresponding to the number of control data values returned through those operators.
If the ID could not be identified (eg. 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 tuple of the size
corresponding to the number of control data values returned through those operators.
If the ID could not be identified (eg. 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 tuple of the size
corresponding to the number of control data values returned through those operators.
If the ID could not be identified (eg. 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 GenTL Producer.
The optimal value depends on the speed of the used device and extra safety
required by the GenTL Producer. With a robust GenTL Producer, no delay
should be needed.
|
| 'device' |
' | device:<device id> | unique_name:<unique name> | user_name:<user-defined name> | interface:<interface id> | producer:<cti file (including path)> | stream:<stream id>', '<device id>' |
|
string |
dynamic |
Returns the Device parameter string used when opening the device (open_framegrabber).
|
| 'device_access' |
'exclusive', 'control', 'read-only', 'safe-mode' |
'exclusive' |
string |
pre-defined |
Value of the device_access generic parameter specified in 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). DevGetInfo -> DEVICE_INFO_TIMESTAMP_FREQUENCY
|
| 'direct_connection' |
'disable', 'enable' |
'disable' |
string |
pre-defined |
Value of the direct_connection generic parameter specified in open_framegrabber.
|
| 'event_data' |
'<genicam_feature>' |
|
string |
pre-defined |
Selects GenICam features to be added to the message queue specified by 'event_message_queue' and 'event_selector'. Features
can be added individually or as a tuple. 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.
The corresponding GenICam feature needs to be
previously specified by 'event_selector'.
Read more about the usage of this mechanism at
Event Message Queues.
|
| '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>' |
|
string |
pre-defined |
Selects a GenICam feature for which the acquisition interface should send
Feature Change Notifications.
They are sent to the message queue specified by 'event_message_queue'.
Read more about the usage of this mechanism at
Event Message Queues.
|
| '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. |
| 'fileaccess_file_path' |
'<file_path>' |
|
string |
pre-defined |
Specifies full path to a local file (in host filesystem) that should be used for file exchange operations between host and the device,
'do_fileaccess_download', or 'do_fileaccess_upload'.
The current user/process must have sufficient rights to access the file.
Note that all file access related parameters are available only if given
device supports the GenICam file access functionality.
|
| 'fileaccess_remote_name' |
'<file_name>' |
|
string |
pre-defined |
Selects a file on the device that should be subject to one of the file access handling operations, 'do_fileaccess_download', 'do_fileaccess_upload',
or 'do_fileaccess_delete'.
The name must be one of the files implemented by the device - the set
of valid names can be queried using 'fileaccess_remote_name_values'.
Note that all file access related parameters are available only if given
device supports the GenICam file access functionality.
|
| 'fwupdate_file_path' |
'<file_name>' |
|
string |
pre-defined |
Path to the file carrying GenICam compatible firmware update (guf-file). When set, the file will be validated and included firmware updates enumerated.
When invalid or when no updates matching the current device will be found,
error will be raised. If successful, the set of matching updates can be queried
using 'fwupdate_update_selector_values' and the actual update to apply selected
using 'fwupdate_update_selector'. Finally, the selected update can be applied
using 'do_fwupdate_apply'.
Note that all firmware update related parameters are available only in the dedicated
"safe mode", see Firmware Update.
|
| 'fwupdate_update_selector' |
'<firmware_update_label>' |
|
string |
pre-defined |
Selects firmware update that can be applied through 'do_fwupdate_apply'. The selector will become available after selecting a valid firmware update
file in 'fwupdate_file_path'. The options (labels describing the matching
firmware updates found in that file) can be queried using
'fwupdate_update_selector_values'.
Note that all firmware update related parameters are available only in the dedicated
"safe mode", see Firmware Update.
|
| 'fwupdate_wait_after_reset' |
'<timeout>' |
|
integer |
pre-defined |
Additional timeout (in ms) applied before device re-discovery if a device reset is required during the firmware update procedure. The timeout is added to corresponding timeout
specified in the firmware update file itself. Intended to resolve system-specific
problems when the device cannot be safely re-discovered using the original timeout.
Note that all firmware update related parameters are available only in the dedicated
"safe mode", see Firmware Update.
|
| 'generic' |
'', ['num_buffers=<num>', 'device_access=<mode>',
'direct_connection=<mode>',
'streaming_mode=0',
'device_event_handling=0',
'workarounds=<list>'], -1
|
-1 |
mixed |
pre-defined |
Values of the Generic parameter. |
| 'grab_timeout' |
<milliseconds> |
5000 |
integer |
pre-defined |
Current grab timeout in milliseconds. |
| 'horizontal_resolution' |
0, 1, resolution |
1 |
integer |
pre-defined |
Current value of horizontal resolution. |
| 'image_available' |
0, 1 |
|
integer |
dynamic |
Shows if there is currently an image waiting for delivery by the GenTL Producer. DSGetStreamInfo -> STREAM_INFO_NUM_AWAIT_DELIVERY
|
| 'image_contents' |
'unknown', 'image', 'coord_a', 'coord_b', 'coord_c', 'coord_mixed', 'confidence' |
0 |
string |
pre-defined |
Tuple describing 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 tuple of the size
corresponding to the number of images returned through those operators.
Possible values are:
- unknown:
The logical type of the image could not be identified, typically this means some kind
of custom, possibly raw data.
- image:
A regular 2D image. The format of the generated HALCON image is affected by the parameters
'bits_per_channel' and 'color_space' if used.
- coord_a:
The output HALCON image contains data corresponding to the 3D "coordinate A" according
to the GenICam 3D model. The interpretation of the coordinate depends on the coordinate
system used by the device: X for Cartesian, theta for spherical and theta for cylindrical
coordinates (refer to GenICam SFNC standard for further details). The data are provided
without any conversion, ignoring the 'bits_per_channel' and 'color_space' parameters.
- coord_b:
The output HALCON image contains data corresponding to the 3D "coordinate B" according
to the GenICam 3D model. The interpretation of the coordinate depends on the coordinate
system used by the device: Y for Cartesian, phi for spherical and Y for cylindrical
coordinates (refer to GenICam SFNC standard for further details). The data are provided
without any conversion, ignoring the 'bits_per_channel' and 'color_space' parameters.
- coord_c:
The output HALCON image contains data corresponding to the 3D "coordinate C" according
to the GenICam 3D model. The interpretation of the coordinate depends on the coordinate
system used by the device: Z for Cartesian, rho for spherical and rho for cylindrical
coordinates (refer to GenICam SFNC standard for further details). The data are provided
without any conversion, ignoring the 'bits_per_channel' and 'color_space' parameters.
- coord_mixed:
Used when the data is recognized as 3D coordinates but the format is unknown. In this
case the data are output in the HALCON image "as is" without any transformations,
the application has to know how to treat the custom data format. The data are provided
without any conversion, ignoring the 'bits_per_channel' and 'color_space' parameters.
- confidence:
The output HALCON image contains data corresponding to the pixel confidence, which
expresses the level of validity of corresponding pixel. The interpretation depends
on the actual underlying pixel format used by the device to represent confidence
(refer to GenICam SFNC standard for further details). The data are provided
without any conversion, ignoring the 'bits_per_channel' and 'color_space' parameters.
|
| '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 tuple of the size
corresponding to the number of images returned through those operators.
If the ID could not be identified (eg. 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 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 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 tuple of the size
corresponding to the number of images returned through those operators.
If the ID could not be identified (eg. 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 tuple of the size
corresponding to the number of images returned through those operators.
If the ID could not be identified (eg. 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.
|
| 'line_in' |
<default> |
0 |
integer |
pre-defined |
The value is not used, so a default value is returned. |
| 'name' |
'GenICamTL' |
|
string |
pre-defined |
Name of the HALCON interface. |
| '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 GenTL Producer. DSGetStreamInfo -> STREAM_INFO_NUM_AWAIT_DELIVERY
|
| 'num_buffers_underrun' |
<number> |
|
integer |
dynamic |
Number of lost buffers due to buffer queue underrun since opening the device. Queue underrun occurs when the GenTL Producer has a new image
data available, but it has no free buffer to store them. DSGetStreamInfo -> STREAM_INFO_NUM_UNDERRUN
|
| 'port' |
<port> |
-1 |
integer |
pre-defined |
The value is not used, so a default value is returned. |
| 'raw_buffer_padding_bytes' |
|
0 |
integer |
pre-defined |
Deprecated, prefer 'image_raw_buffer_padding_byptes' which supports also grab_data. For raw buffers of type 'blob' (see 'raw_buffer_type') reports 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.
|
| 'raw_buffer_type' |
'image', 'blob' |
0 |
string |
pre-defined |
Deprecated, prefer 'image_raw_buffer_type' which supports also grab_data. Shows whether the last grabbed HALCON image 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.
|
| 'register_<addr>_<len>' |
|
|
integer |
pre-defined |
Direct register access for reading and writing integers. The value has to be hexadecimal, e.g. 0x0938. Note that only 4 or 8 Byte length values
are accepted.
Caution: This is a dangerous function intended for debugging and special
cases. Usually only features in the XML should be used.
|
| 'revision' |
'<revision>' |
|
string |
pre-defined |
Revision number of the GenICamTL interface. |
| '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 GenICamTL
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.
|
| 'tl_displayname' |
'<name>' |
|
string |
dynamic |
Human-readable name of the used GenTL Producer. TLGetInfo -> TL_INFO_DISPLAYNAME |
| 'tl_filename' |
'<file name>' |
|
string |
pre-defined |
File name of the used GenTL Producer. TLGetInfo -> TL_INFO_NAME |
| 'tl_id' |
'<id>' |
|
string |
dynamic |
Unique identifier of the used GenTL Producer. TLGetInfo -> TL_INFO_ID |
| 'tl_model' |
'<model name>' |
|
string |
dynamic |
Name of the used GenTL Producer to distinguish different kinds of GenTL Producer implementations from one vendor. TLGetInfo -> TL_INFO_MODEL
|
| 'tl_pathname' |
'<path name>' |
|
string |
pre-defined |
Full path of the used GenTL Producer. TLGetInfo -> TL_INFO_PATHNAME |
| 'vertical_resolution' |
0, 1, resolution |
1 |
integer |
pre-defined |
Current value of vertical resolution. |
| 'volatile' |
'disable', 'enable' |
'disable' |
string |
pre-defined |
Current value of the volatile mode. |
| 'workarounds' |
['', 'enable_range_validation' , 'buffer_alloc_by_consumer'
, 'ignore_buffer_pixelformat'
]
|
'' |
string |
pre-defined |
List of workarounds enabled by the 'workarounds' generic parameter in open_framegrabber. Individual workaround names are separated by spaces.
|
Not supported by this interface.
Not supported by this interface.
This interface supports feature change callbacks via the operators
set_framegrabber_callback and
get_framegrabber_callback.
The callback can be registered for any GenICam based features,
i.e., features published by the device and GenTL Producer
through the GenICam description files. 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.
grab_image_async returns a single image and starts the next asynchronous grab. See also
grab_image_async,
section about acquisition control and
about grab operators.
Note that the interface converts the acquired image to the
desired image format specified by the parameters 'bits_per_channel' and
'color_space'.
The 'MaxDelay' parameter of the
grab_image_async operator is ignored by the
HALCON GenICamTL acquisition interface, because there is no way to support it
reliably
across all GenTL producers
. If needed, the application needs to
implement alternative functionality on its own.
grab_data starts a new synchronous grab, resulting possibly in tuple of output images and tuple of data outputs of various kind, depending on the input
and configuration. See also
grab_data,
section about acquisition control and
about grab operators. Note that the
interface converts the acquired images to the desired image format
specified by the parameters 'bits_per_channel' and 'color_space'.
The output tuples are described using the 'data_contents', 'image_contents'
and related parameters.
grab_data_async returns acquired images/data and starts the next asynchronous grab. See also
grab_data_async,
section about acquisition control and
about grab operators.
Note that the interface converts the acquired image to the
desired image format specified by the parameters 'bits_per_channel' and
'color_space'.
The output tuples are described using the 'data_contents', 'image_contents'
and related parameters.
The 'MaxDelay' parameter of the
grab_image_async operator is ignored by the
HALCON GenICamTL acquisition interface, because there is no way to support it
reliably
across all GenTL producers
. If needed, the application needs to
implement alternative functionality on its own.
HDevelop Examples
For this interface there are the following examples available:
- genicamtl.hdev - Benchmark.
- genicamtl_parameters.hdev - Lists all parameters of a device.
- genicamtl_simple.hdev - A simple example to show the usage of
the interface.
- genicamtl_fileaccess.hdev -
Example how to upload and download files from GenICam devices.
- genicamtl_fwupdate.hdev -
Example how to apply a firmware update using GenICam's FWUpdate module.
- genicamtl_vrmagic_areascan3d_objectmodel3d.hdev - Example for
the usage of the VRmagic AreaScan3D calibrated 3D area sensor.
- genicamtl_basler_tof_objectmodel3d.hdev - Example for the
usage of the Basler TOF sensor.
- genicamtl_lmi_gocator_objectmodel3d.hdev - Example for the
usage of the LMI Gocator calibrated 3D sensor.
- genicamtl_smartray_ecco_objectmodel3d.hdev - Example for the
usage of a SmartRay 3D sensor.
- genicamtl_devicelost_event.hdev - Example how to handle DeviceLost
event with message queues.
- genicamtl_acquisition_events.hdev - Example how to handle events
with additional event data using message queues.
Troubleshooting
In case of problems with the HALCON GenICamTL Interface the following hints might help to solve them.
General:
- Check if the latest revision
of the HALCON GenICamTL interface is used.
- Check the System Requirements.
- Check for a newer version of the used GenICam GenTL Producer.
- Check if the device has the latest firmware.
- Enable low-level error messages in HALCON to query more information
about the problem (and check the output console in HDevelop if applicable).
- If your device is connected via Ethernet and
a firewall is active in the system, it has to be configured in a way
so that all applications expected to be using the GigE Vision devices
(e.g. HDevelop, but also any user-developed applications) have full
access to the connected devices.
GenICam:
- Check if the correct GenICam binaries are in use. HALCON uses the official
binaries in a private installation (folder genicam in the HALCONROOT
directory). If other GenICam binaries are in your path or in some system
path (for Windows e.g. in c:\Windows\System32\ for Linux e.g. in /usr/lib
or similar directories) make sure these are the official ones by comparing
them with the ones in the HALCON installation. Using unofficial binaries
might result in strange problems.
If there are still problems, please contact your local distributor.
The following information is needed for your support request to avoid
unnecessary inquiries.
- Used HALCON and acquisition interface versions.
- Used HALCON architecture (especially 32 or 64 bit).
- Low-level error messages if there are any.
- Camera manufacturer, model and firmware version.
- Details about the used GenICam GenTL Producer (at least name and version).
- Details about computer system, like operating system, RAM and CPU.
- Minimal sample code (e.g. HDevelop script) to reproduce the issue.
- Description of observed and expected behavior.
Release Notes
- Revision 13.0.5 (Oct 30, 2018):
- Updated underlying GenApi version to latest official release v3.1.
Please note that therefore also the genicam directory of your HALCON
installation will be updated.
The Update includes an accelerated MathParser, improved persistence
in combination with sequencers and a fix where values were available
even though the corresponding feature was not.
- GenICam's File Access is now supported. See the new parameters
'fileaccess_file_path', 'fileaccess_remote_name',
'do_fileaccess_download', 'do_fileaccess_upload',
'do_fileaccess_delete', and the new HDevelop example
genicamtl_fileaccess.hdev.
- GenICam's FWUpdate is now supported. See
Firmware Update and the new HDevelop example
genicamtl_fwupdate.hdev.
- Receiving GenICam events on message queues is now supported, see
Event Message Queues.
So far, GenICam events were only supported via callbacks and thus
not usable in HDevelop. Additionally, two new HDevelop examples have been
added to show this functionality genicamtl_acquisition_events.hdev
and genicamtl_devicelost_event.hdev.
- 'do_write_configuration' has been extended to store not only the
current device configuration but also generate persistence files
for all the GenTL Producer modules
(system, interface, device and data stream), see
Parameters – Persisting Device Status.
- Added new parameters 'buffer_timestamp_ns' and
'device_timestamp_frequency' to improve the usability of
'buffer_timestamp' which on its own is unit-agnostic.
- If a GenTL Producer did not implement an immediate stop of the
acquisition engine (ACQ_STOP_FLAGS_KILL), stopping the engine (e.g.
close_framegrabber) could lead to a deadlock.
This problem has been fixed.
- On Windows, GenTL Producers that required additional dependencies which
were on the same location but not in PATH were not loaded correctly.
This problem has been fixed.
- On aarch64-linux, GenTL Producers were searched in GENICAM_GENTL32_PATH
instead of GENICAM_GENTL64_PATH. This problem has been fixed.
- Some generic parameters passed to open_framegrabber were not available
through get_framegrabber_param. This problem has been fixed.
- String parameters longer than 1024 characters were silently cropped by
get_framegrabber_param. This problem has been fixed.
- When 'start_async_after_grab_async' was set 'disable',
the acquisition was stopped on the remote device after each frame.
This problem has been fixed.
- For consistency, the following examples have been renamed:
genicamtl_areascan3d_objectmodel3d.hdev to
genicamtl_vrmagic_areascan3d_objectmodel3d.hdev,
genicamtl_gocator_objectmodel3d.hdev to
genicamtl_lmi_gocator_objectmodel3d.hdev, and
genicamtl_smartray_3dsensor_objectmodel3d.hdev to
genicamtl_smartray_ecco_objectmodel3d.hdev.
- Revision 13.0.4 (Apr 27, 2018):
- Added support for the 'Mono4p' pixel format.
- Added support for the 'YCbCr411_8' pixel format.
- Unsupported pixel formats are now tried to be returned in their actual
image dimensions if they are similar enough to a supported Mono format.
Before, all unsupported formats were returned as square images (see
Raw Output Format).
- On Unix systems, HALCON crashed when ended without calling
close_framegrabber. This problem has been fixed.
- When 'DeviceUserID' was set to ' ' (a single space), it could not be
used to connect. This problem has been fixed.
- When trying to connect to a busy device using its DeviceUserID,
a misleading low-level error appeared. This problem has been fixed.
- Revision 13.0.3 (Nov 28, 2017):
- The technical dependency from the HALCON Library has been removed.
- Added support of GenTL module events. They are used just as the device
events but including the module's square bracket prefix. So you can