LOG OUT
interfaces mvtec

Interface Documentation

Image Acquisition Interface for USB3 Vision compliant cameras

Interface: USB3Vision
Revision: 20.11.20
Date: 2023-07-31

General

This page provides the documentation of the universal HALCON USB3Vision interface for accessing all USB3 Vision compliant cameras. Registered customers can download the latest revision of this interface from the MVTec WWW server.

System Requirements

  • Intel compatible PC with Windows 7 (32-bit or 64-bit) or newer, also WoW64 (using 32-bit HALCON on 64-bit Windows), Linux with kernel 3.5 (or higher), or OS X 10.8 (or higher).
  • The computer has to be equipped with a USB 3.0 interface. Make sure you use the latest drivers for the USB 3.0 host controller. Note that on Windows systems it is usually not sufficient to search with the built-in mechanism, instead you need to check the website of the host controller manufacturer for the newest version.
  • Ensure that the acquisition interface has full access to the connected USB3 Vision devices:
    • Windows: one of the supported drivers (WinUSB, libusb-win32 or libusbk) attached to the device's composite parent.
    • Linux: read-write access privilege for the corresponding device file(s).
    • macOS: access is provided automatically.
    • Further details in section USB3 Vision Device Access.
  • GenICam GenApi. The corresponding files are part of the HALCON USB3Vision package and are located in the directory genicam within the HALCON base directory %HALCONROOT%. See section GenICam GenApi for more details.
  • Windows: HALCON image acquisition interface hAcqUSB3Vision.dll or hAcqUSB3Visionxl.dll, respectively. Additionally you need libusb-1.0-usan.dll and libwdi-usan.dll third-party libraries and the hAcqUSB3VisionElevate.exe binary. The latter are necessary to allow correct driver assignment from within the interface. If you have properly installed the interface, all these files should reside in bin\%HALCONARCH% within the HALCON base directory %HALCONROOT% you have chosen during the installation of HALCON.
  • Linux: HALCON image acquisition interface hAcqUSB3Vision.so or hAcqUSB3Visionxl.so, respectively. Additionally you need the libusb-1.0-usan.so.0 third-party library and the hAcqUSB3VisionElevate SUID binary (with s-bit for root). The latter is necessary to allow correct device identification from within the interface in case you do not have permissions to send commands to the device. If you have properly installed the interface, the shared objects should reside in lib/$HALCONARCH, the third-party shared library in lib/$HALCONARCH/thirdparty, and the binary in bin/$HALCONARCH within the HALCON base directory $HALCONROOT you have chosen during the installation of HALCON.
    For device access libudev is required (specifically libudev.so.1 or higher) see section USB3 Vision Device Access.
    For adapting priority and scheduling policy administrator privileges or CAP_SYS_NICE capabilities are required, we suggest to add the capabilities to the video group (default group when you use the provided udev configuration) via an entry like @video - rtprio 99 e.g. to /etc/security/limits.d/video.conf (needs probably to be created).
  • macOS: HALCON image acquisition interface hAcqUSB3Vision.dylib or hAcqUSB3Visionxl.dylib, respectively. Additionally you need the libusb-1.0-usan.0.dylib third-party library. 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. Alternatively you can set the environment variable DYLD_LIBRARY_PATH to point to the corresponding directory.
    For adapting priority and scheduling policy the necessary privileges are required.
  • 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.

Interface Versioning

MVTec interfaces for digital I/O and image acquisition are always compatible to a range of HALCON versions. Therefore, the versioning scheme both describes the compatibility of the interface and also the revision of the interface itself. An interface version always consists of three numbers, separated by dots, i.e. 20.11.5. The first two numbers describe the minimum HALCON version the interface is compatible with. For the example version 20.11.5 this means that the interface is compatible with all HALCON versions since HALCON 20.11. The last number describes the revision of the interface, in this example this is revision 5.

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

Upgrading From Version 13.0.3 Or Earlier On Linux Systems

Starting with version 13.0.4, the shared library libusb-1.0-usan.so.0 is no longer located in the directory $HALCONROOT/lib/$HALCONARCH/. Instead, it is moved to the subdirectory $HALCONROOT/lib/$HALCONARCH/thirdparty. If you are upgrading from an earlier version of the interface, you will need to manually remove this library from the directory $HALCONROOT/lib/$HALCONARCH/.

Environment Variables

The interface can be controlled through several environment variables:
  • 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.
  • 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

  • User-space implementation of the USB3 Vision protocol.
  • Grabbing from multiple cameras.
  • Flexible device lookup and connection options.
  • Synchronous and asynchronous grabbing.
  • Support of GenDC streaming (GenDC Container Transfer Mode).
  • Grabbing of 3D data and creation of object model 3d.
  • Software control of all generic camera parameters using GenApi.
  • Software control of parameters controlling the interface's USB3 Vision Producer 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 (devices that can be controlled by means of GenICam, but do not stream any image (or other) data.
  • Support of pending acknowledges which allow to wait for device response to long taking commands without needing to manually adjust the timeout.

Limitations

  • Devices with multiple USB configurations are not fully supported.
  • On OS X 10.10.x and older stopping or aborting grabbing images leads to a hang for camera with large sensors (5MP and bigger). As a workaround please open the interface with the generic parameter 'num_buffers=2' and set the parameter '[Stream]StreamAuxiliaryBufferCount' to 0. Apple fixed this problem with OS X 10.11 'El Capitan'.

USB3 Vision Compatibility

  • This interface implements USB3 Vision specification version 1.2, covering all three basic protocols it defines: control, image/data streaming and asynchronous device events.
  • The interface supports the GenDC Container Transfer Mode (Serial and Parallel Flow modes currently not supported) - when supported by the device, the interface selects the GenDC mode as default to allow maximal flexibility.

GenICam GenApi

  • This interface uses GenApi version 3.4.1, 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 USB3Vision interface sets all necessary environment variables on its own and ignores other installed GenICam packages by default.
    If you want to use another GenICam package, you need to set the environment variable HALCON_USE_EXTERNAL_GENAPI. This skips the step of setting all necessary variables and paths internally, so you have to make sure they are set correctly. Please note that it might not be possible to use different GenApi versions with different interfaces at the same time and that you must use the required GenApi version for this interface.
  • The caching of device XML files is activated to speed up processing, writing to a temporary directory subject to availability of %TEMP%, %TMP%, $TMPDIR, /tmp or %HALCONROOT%.
  • The remote device control features as well as the USB3 Vision Producer control features of this interface are controlled via GenApi.

USB3 Vision Device Access

The HALCON USB3Vision image acquisition interface performs all access to the USB bus and connected USB devices through a libusb 1.x compatible interface. To ensure full access to the device, the following preconditions have to be fulfilled:

General:
  • The device has to be compatible with USB 3.0 and operate in the SuperSpeed transfer mode.
  • USB 2.0 (or lower) devices or devices connected through USB 2.0 hub will be discovered by the interface, but they will be marked as inaccessible and the interface will refuse to open them.
  • Note that when using an improper cable or when the cable connector is not fully plugged, the device might appear to be connected through USB 2.0 as well.
Windows:
  • On Windows, the access to the devices can be established through one of the following drivers: WinUSB, libusb-win32 or libusbk, while we currently recommend WinUSB as a default option.
  • The driver has to be attached to the composite parent of the device, not just to one of the device interfaces.
  • If the driver is not properly attached to the device, the HALCON USB3Vision acquisition interface will discover the device, but will mark it as inaccessible and opening it will not be possible.
  • If you are using the HDevelop Image Acquisition Assistant, it will automatically prompt you to add the correct generic parameter to install the driver if necessary. You can find an example in section HDevelop Examples if you want to do this manually. Please keep in mind that due to the necessary privilege elevation network drives might not be available to the elevated user and therefore driver installation might fail. Install HALCON locally if you see these kind of problems.
  • If you are using other image acquisition interfaces or other software to access the camera it might be necessary to use a different driver then the one this interface assigns. This is done by opening the device manager with administrative permissions. Then select the device, right click on it and choose to uninstall the driver. Please select the option to remove the driver, else it will be assigned automatically when you reconnect the device. Now unplug the device and reconnect it. It should install the other driver, if not please follow the instructions of the other software or interface.
  • If the interface is not able to detect the device at all, you need to assign the driver manually. Before doing so update, the driver for your USB 3.0 host controller to the newest available version from the manufacturer, most of the time this enables automatic detection afterwards.
  • The recommended way to install the driver manually is to use the Zadig driver installer (latest version). Run the tool with Administrator privileges, in Options menu check 'List All Devices' and uncheck 'Ignore Hubs or Composite Parents'. Select your device (important: its composite parent) in the drop-down list and install the driver (e.g., WinUSB) to be used with the device.
Linux:
  • On Linux, the enumeration and access to the devices is established through libudev (using usbfs as a fallback). At least libudev.so.1 is required.
  • The application needs sufficient privileges to open the device file in read-write mode. Without read-write access, the device might not be even properly enumerated, because the essential USB3 Vision related information about the device couldn't be queried.
  • If you are using the HDevelop Image Acquisition Assistant, it will automatically prompt you to add the correct generic parameter to add missing permissions if necessary.
  • To allow to fully access the devices from a regular user account, the system's udev subsystem should be configured to guarantee read-write access for device files corresponding with any USB3 Vision devices possibly connected to the system. The actual udev configuration strategy might be system-specific, however, a default solution suitable in most situations is packed together with the USB3Vision acquisition interface.
  • You can find the recommended udev configuration rule in $HALCONROOT/misc/linux/udev/rules.d/59-usb3vision.rules. This rule will guarantee read-write access to device files corresponding with USB3 Vision devices for all members of the 'video' user group plus to the users logged in interactively to the system. When such configuration matches your expectations, copy the file to /etc/udev/rules.d directory (valid on most distributions). When desired, modify the file according to the udev configuration strategy defined for your system.
  • As an additional last resort helper, for situations when the udev rules configuration fails to help (e.g. because another software package overrides it), the USB3Vision acquisition interface will try to use the utility $HALCONROOT/bin/$HALCONARCH/hAcqUSB3VisionElevate during device discovery. The only purpose of this utility is to read USB3 Vision related identity of the device to allow full device discovery. However, this tool needs reliable read-write access to the USB3 Vision device files, regardless of the actual user and the udev configuration. It is therefore recommended that the file owner is changed to root and setuid bit set. To achieve this you can need to execute the following commands as root: chown root $HALCONROOT/bin/$HALCONARCH/hAcqUSB3VisionElevate chmod 2755 $HALCONROOT/bin/$HALCONARCH/hAcqUSB3VisionElevate
  • The Linux kernel limits the size of buffers allocated for the USB transfers to 16MB. For cameras with large sensors, multiple cameras, lots of simultaneous scheduled transfers or similar (see also Advanced Streaming Engine Control) this limit is not sufficient and needs to be adjusted. To prevent image acquisition failures, it is necessary to increase this limit to a value that safely covers the total size of stream buffer transfers that might be concurrently scheduled for all open cameras at any moment - considering also other possible components or applications that could be sharing the USB subsystem with your application. The limit is controlled by the usbcore.usbfs_memory_mb kernel parameter (as size in MB). For example to increase this limit to 512MB you can add a kernel command line parameter like usbcore.usbfs_memory_mb=512 when booting or to your bootloader. Alternatively, you can adjust it on the fly as administrator privileges by executing echo 512 > /sys/module/usbcore/parameters/usbfs_memory_mb .
macOS:
  • Nothing special has to be done, you should have full device access by default.

Using Multiple Cameras

When using multiple USB3 Vision cameras simultaneously, some bandwidth management considerations might be necessary when planning the hardware setup. In particular, it is important to guarantee that the total bandwidth possibly used by the devices does not exceed the bandwidth of the USB bus topology segment they eventually share – or, if possible, guarantee that the devices are connected to the host via independent paths.

Note that the actual performance of USB components such as hubs might be significantly lower than the maximum theoretical USB 3.0 bus bandwidth.

Depending on the actual use case, the particular device properties, such as the presence and size of the device's frame buffer might also play a role on the overall system performance and reliability. Device vendors usually provide detailed guidelines and configuration options for bandwidth management of their devices.

Identifying and Opening a Device

The connection to the (acquisition) device is established through the open_framegrabber operator. The operator provides a set of parameters allowing to configure the basic properties of the device and how the HALCON USB3Vision interface controls it – see corresponding section. Some of the parameters can be also modified at runtime through set_framegrabber_param. This section concentrates solely on the 'Device' parameter of open_framegrabber, identifying the device (usually camera) that should be opened.
A connection to the device accessible through the USB3Vision interface is established using the device ID which is guaranteed to be unique per USB3 Vision device and stays persistent across multiple sessions and independent on the point where the device is connected to the USB bus. Instead of the unique device ID, the user-defined name attached to the device can be used. Finally, it is also possible to use the serial number of the device.
The list of all devices currently available in the system can be at any point obtained using info_framegrabber parameter 'device' or 'info_boards' – see corresponding section. Both parameters return a list of devices, each specified using the above listed entities in the format ' | device:<device id> | ...', where '<device id>' is either the unique device ID or a 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. The full string (obtained from the info_framegrabber call) can be directly used for the 'Device' parameter of open_framegrabber, it uses the same format. As shown above, it consists of entries of the form 'token:value', separated by ' | '. The 'device' entry is the most significant one.
Alternatively you can specify the device directly. For this, one or more of the entries can be omitted (or specified as 'default') - which behaves like using wildcards, meaning that the particular ID for that entity should not be considered (any ID would match). Only the ' | device:<device id>' string entry is important for open_framegrabber, the others are ignored and might be omitted. In addition to the device ID, devices can be opened by their alternative identifiers: user-defined name (specify the device using string in format 'user_name:<user_defined_name>') or the serial number ('device_sn:<device_serial_number>').
When a pure string without any 'token:' and without the ' | ' separator is used, it is interpreted directly as the device ID.
If you know the device ID in advance, you can create the string yourself – without using info_framegrabber. As shown above, it consists of entries of the form 'token:value', separated by ' | '. The 'device' entry is the most significant one. When a pure string without any 'token:' and without the ' | ' separator is used, it is interpreted directly as the device ID.
As a special case, the string 'default' can be used – in this case the HALCON acquisition interface will use the first available device (devices currently reported as non-accessible will be skipped). When using the same 'default' string again, that device will no more be accessible, therefore the next accessible device will be opened. This way, all devices connected to the system may be easily opened in a loop.

Note that since version 1.1 the USB3 Vision specification supports devices with multiple image streams. The HALCON USB3Vision interface currently supports only a single image stream, which is what vast majority of devices offers. This might change in future – in such a case the format to open the device will be extended with the stream entry. The current format would open the first available stream.
Similarly, in future the device string format might be extended with an entry specifying the 'interface' (i.e., the computer's USB 3.0 bus) to which the device is connected. In such a case, the current format would still work, searching all interfaces instead of just the one specified.

Selection of GenICam Feature Description File(s)

The features of a device or USB3 Vision Producer are described by GenICam feature description files (XML files) that are automatically parsed and offered to the user. The HALCON USB3Vision image acquisition interface provides access to the features exposed through the following GenICam feature description files:
  • Features of the connected device ("remote device"), typically a camera, are usually loaded directly from the connected device.
  • Features of the USB3 Vision Producer are exposed through a set of GenICam description files, one for each internal entity to control the device tree:
    • The "system" – representing the overall behavior of the acquisition interface
    • The interface used to connect the device to the system.
    • A proxy (called "local device") to the device, controlling the USB3 Vision Producer 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 USB3 Vision 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_THE_SYSTEM_MODULE% 
InterfaceFile=%PATH_TO_GENICAM_FILE_OF_THE_INTERFACE_MODULE% 
DeviceFile=%PATH_TO_GENICAM_FILE_OF_THE_LOCAL_DEVICE_MODULE% 
StreamFile=%PATH_TO_GENICAM_FILE_OF_THE_STREAM_MODULE%
The same ini-file format can be reused to force the HALCON acquisition interface to load an alternative XML file for one or more of these entities. This can be useful, e.g., for updates or troubleshooting. The files listed in the ini file will be used for the given entity instead of the original ones. For the entities excluded from the ini file, the GenICam description file will be searched and loaded the usual way. To apply the ini file, pass its full path to open_framegrabber in the 'CameraType' parameter.

Note that the ini-file can be reused also for other purposes such as storing/restoring configuration as described in Parameters – Persisting Device Status. Be aware that when persistence files are specified, they have priority over other explicit settings passed to open_framegrabber.

Parameters – Naming Conventions

The following groups of parameters exist:
  • Internal parameters of the MVTec GenTL Consumer itself (GenICamTL acquisition interface). These are named following the "underscore" naming style, e.g., color_space, and are all lowercase. However, MVTec EasyParams are prefixed with "[Consumer]", e.g., [Consumer]gain.
  • GenICam-based parameters of the device, usually a camera, use by convention the "CamelCase" style, e.g., ExposureTime.
  • GenICam-based parameters of the individual USB3 Vision 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 USB3 Vision Producer (i.e. 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 USB3 Vision Producer and are shared among all devices open within this USB3 Vision 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. When the GenICam feature in question has a representation associated that identifies it as IPV4Address, MACAddress or HexNumber, the corresponding string representation 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 acquisition 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). This applies not only to actual device parameters, but also to parameters configuring the USB3 Vision Producer and internal parameters of the USB3Vision image acquisition interface. Device parameters are usually kept until the device is powered down. The USB3 Vision Producer modules and the Consumer parameters are kept until close_framegrabber is called. To indicate which parameters to persist, use the parameter 'settings_selector'. The persistence functionality consists of two steps, storing the current configuration to a file and later re-loading it back to the device. The selected module settings, indicated by 'settings_selector', 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. To query if a feature can be persisted use the postfix '_streamable'.

Note that while the format of the files is intentionally human readable and the files can be hand-modified if desired, such modifications should be done with care by someone familiar with the GenICam persistence functionality internals and given device. Improper modifications of the files can lead to errors when using it.

It is important to know that while performed by the software, persistence of the device-related features is actually a device-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 manufacturer could provide additional information or help.

The persistence related operations might be blocked by the device and/or USB3 Vision Producer based on the current state, for example while an acquisition is in progress.

The same persistence files can be applied to the entire set of devices of the same type and firmware version. Applying the persistence files to a device of another type or using even different firmware version will probably lead to inconsistencies or will even fail completely – 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 generate extended version of the persistence file, storing not only the current device configuration, but also contents of its user sets and sequencer sets (if the device supports them). Additionally, it will also generate persistence files for all the USB3 Vision Producer modules (system, interface, device and data stream). The persistence file entries in the ini file will have the format 
 
RemotePersistence=%PATH_TO_PERSISTENCE_FILE_OF_THE_DEVICE% 
SystemPersistence=%PATH_TO_PERSISTENCE_FILE_OF_THE_SYSTEM_MODULE% 
InterfacePersistence=%PATH_TO_PERSISTENCE_FILE_OF_THE_INTERFACE_MODULE% 
DevicePersistence=%PATH_TO_PERSISTENCE_FILE_OF_THE_LOCAL_DEVICE_MODULE% 
StreamPersistence=%PATH_TO_PERSISTENCE_FILE_OF_THE_STREAM_MODULE%
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.

Parameters – MVTec EasyParams

The MVTec EasyParams is a group of MVTec GenTL Consumer parameters based on the regular GenICam features of the device. These parameters allow easy access to the most commonly used camera parameters.
The list of EasyParams can be obtained calling 'available_easyparam_names'. Note that 'available_param_names' does not include the EasyParams. The MVTec EasyParams start with the prefix [Consumer], indicating they are internal parameters of the HALCON GenTL consumer itself.
Since HALCON 22.11 they are available via an own tab in the HDevelop Image Acquisition Assistant.
If your device does not support one of the EasyParams, querying its access will return 'ni' (not implemented). If instead 'na' (not available) is returned, the EasyParam is supported but currently not available, e.g., it depends on the current state of another EasyParam or the access of one or more GenICam features, or because the image acquisition is running. In the latter case, use set_framegrabber_param(..., 'do_abort_grab', ...) to stop the acquisition.
List of MVTec EasyParams:
  • General device information:
    • [Consumer]info_general
  • Exposure feature:
    • [Consumer]exposure_auto
    • [Consumer]exposure
  • Gain feature:
    • [Consumer]gain_auto
    • [Consumer]gain
  • Trigger feature:
    • [Consumer]trigger
    • [Consumer]trigger_activation
    • [Consumer]trigger_delay
    • [Consumer]trigger_software
Detailed information of each MVTec EasyParam can be found in sections about getting framegrabber parameters and setting framegrabber parameters.
See also the HDevelop example usb3vision_easyparams.hdev.

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. Note that some of the camera features might be locked by GenICam when an acquisition is active.
With synchronous grab (grab_image/grab_data), a new acquisition is started internally for each image, so that the application always gets a new image. Before delivering the image, the acquisition is stopped again, so between individual grab_image/grab_data calls, all acquisition related features remain unlocked.
With asynchronous grabbing, started explicitly by grab_image_start or implicitly by grab_image_async/grab_data_async, the interface keeps the acquisition running internally, collecting further images to be delivered through future grab_image_async/grab_data_async calls. The acquisition related features are locked, until the acquisition is stopped using set_framegrabber_param(..., 'do_abort_grab', ...).
The HALCON acquisition interface properly recognizes the 'Continuous', 'SingleFrame' and 'MultiFrame' acquisition modes configured on the device and adjusts the acquisition control logic accordingly.
Furthermore, the interface takes over exclusive access to several remote device features essential for the acquisition control (AcquisitionStart, AcquisitionStop, AcquisitionAbort, TLParamsLocked). The user application has no direct way to control these features.
The differences between the "image" and "data" version of the grab operators is documented in Acquisition – Grab Operators.

Acquisition – 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.

It can happen, that the camera is temporarily or constantly acquiring data in higher speed than the application is processing them. In such case the streaming engine of the USB3 Vision Producer decides how to treat the acquired buffers based on the '[Stream]StreamBufferHandlingMode' parameter.

Note that the streaming engine behavior can be further controlled through additional parameters described in Advanced Streaming Engine Control.

Acquisition – Image Format Handling

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.
The HALCON USB3Vision 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 , 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 USB3Vision 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 'image_raw_buffer_type' and 'image_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.
Some GenICam compatible devices might implement a chunk-only mode, in which meta-data without an image is transmitted. This mode is incompatible with the grab_image operators, but can be used with the grab_data operators.
The chunk data related features will only provide 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 USB3 Vision Producer as well as for internal parameters of the acquisition interface.
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 USB3 Vision Producer (system, interface, device and data stream). The information provided above about handling of the device events applies similarly also to the USB3 Vision 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 USB3 Vision 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 (GenICam feature or internal parameter) 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 USB3 Vision Producer or for internal features of the acquisition interface. On top of that, the notification can be registered also for internal events occurring within the acquisition interface, in particular 'event_new_buffer' which gets fired whenever the information about last acquired buffer is updated (new buffer grabbed or last buffer info invalidated when restarting the acquisition).
The list of supported targets can be queried by calling get_framegrabber_param(..., 'available_event_names', ...).
One of the important use cases for feature change callbacks is the device event delivery mechanism, see details in Event Data and Feature Change Notifications sections.
A new message would be added to the specified queue whenever a given feature is potentially changed (including its other properties such as range or access mode). Note that it does not necessarily always mean that the feature actually has a new value. A call to set_framegrabber_param(..., 'event_message_queue', 0) unregisters the previously registered message queue from the specified event. Note that the interface keeps just a single registration for every feature, if you attempt to register a new message queue for a feature that already had a message queue registered, the previous registration will be replaced with the new one.
The messages incoming on an event can be retrieved with dequeue_message and will contain at least three tuples. The first tuple (key 'id') is a unique identifier of the acquisition instance the event is coming from. It is a string composed as '<interface>:<unique_name>'. The second tuple (key 'event_name') is the name of the corresponding feature previously specified by 'event_selector'. The third tuple (key 'event_value') contains the value if the corresponding feature if available and readable.
If you decide to add additional data to be delivered with the corresponding event feature(s), add the features of interest with set_framegrabber_param(..., 'event_data', ...). Each event data feature will be appended to the event message with the key being its name and the tuple its value if readable. Note that duplicities possibly specified through 'event_data' are ignored The value of the notified feature itself (already reported in 'event_value') would also be considered as a duplicity and not reported again.

Advanced Streaming Engine Control

The streaming engine works well for standard use cases. However, in specific use cases, the behavior must be fine tuned. The parameters described in this section are intended for this advanced use only and should be treated with care - wrong configuration can significantly affect performance.
As the streaming engine and the event engine share the same resources (such as the cpu time and USB subsystem) it is recommended to consider both of them (see Advanced Event Engine Control).
In particular if the frame rate of the camera exceeds the rate the application can handle the images it is necessary to adjust the behavior. If possible this use case should be avoided by setting appropriate parameters in the camera, e.g. by using triggering instead of free running acquisition mode.
For optimal performance when streaming over USB it is usually necessary to ensure that there is always a buffer ready to receive data and that this buffer is also "scheduled" for USB transfers to the system's USB subsystem. In any other case the camera might decide to discard the image, deliver only part of the image (especially if the camera has no or limited frame buffer) or even start misbehaving.
As described in Acquisition – Buffer Handling, the acquisition interface allocates a set of buffers used to deliver the acquired data to the user application ("user buffers"). If the application can not handle the frame rate of the camera, it will happen that all of these buffers are filled and are waiting in the output queue for processing, thus no user buffer can be temporarily scheduled for the next acquisition. For this reason, the streaming engine allocates '[Stream]StreamAuxiliaryBufferCount' auxiliary buffers (default 2). The number can be decreased (down to zero) to save memory if necessary or it can be further increased, if the default count is too low to prevent overflows, but in this case it might be better to schedule more user buffers.
The minimum number of buffers the streaming engine tries to keep scheduled at any moment can be adjusted by '[Stream]StreamScheduledBuffersTarget'. To satisfy this target, auxiliary buffers are being scheduled when there are not enough user buffers available. Especially with fast cameras the scheduled buffers might be quickly exhausted if the streaming thread is not scheduled for a while, thus the default value of 2 needs to be increased.
If an image has been acquired into an auxiliary buffer, the streaming engine checks if a new user buffer became available in the meanwhile. If not, the engine checks the '[Stream]StreamBufferHandlingMode' parameter to see if it is allowed to overwrite older buffers awaiting processing in the output queue. If there is a user buffer available, the data is copied to it, otherwise it is discarded. Making use of auxiliary buffers thus always yields additional overhead for copying.
On the other hand, the parameter '[Stream]StreamScheduledBuffersMaximum' controls the maximum number of buffers the engine should attempt to schedule at a time. The default value is 4 and is known to work well in most situations. It might only be desirable to increase it when using a camera streaming small images in very fast frame rate. Note that it does not make much sense to set this value higher than the actual number of acquisition buffers (refer to the 'num_buffers' generic parameter of open_framegrabber).

Note that this max-limit parameter was initially introduced due to a limitation in the underlying libusb library (under Windows) that was not able to cope with more than 64 concurrent USB transfers, which in turn could cause problems in multi-camera setups. This limitation does not exist any more, but the same defaults (known to work reliably in most cases) were kept for now to avoid backward compatibility issues.
Refer also to related features to control the event engine behavior (Advanced Event Engine Control).

The ability to schedule buffers in time has a heavy effect on the performance of the streaming engine. This is strongly affected by the priority of the streaming engine thread relative to other threads in the system. Refer to the documentation of the parameters '[Stream]StreamThreadPriority', '[Stream]StreamThreadSchedulingPolicy' and '[Stream]StreamThreadApplyPriority' for details. Upon device open, generally suitable default priority is selected.
Finally, the streaming infrastructure can be completely disabled using the 'streaming_mode=0' generic parameter while opening the device.

Advanced Event Engine Control

The event engine works well for standard use cases. However, in specific use cases, the behavior must be fine tuned. The parameters described in this section are intended for this advanced use only and should be treated with care - wrong configuration can significantly affect performance.
Fine tuning the event engine is very similar to adjusting the streaming engine. Since they share the same resources (such as the cpu time and USB subsystem) it makes sense to consider both of them. It is therefore recommended to study the corresponding explanations in (Advanced Streaming Engine Control), this section will just list the corresponding event related parameters.
Unlike the streaming engine, the event engine uses all buffers only internally. The engine will attempt to schedule as many transfers for incoming events as possible, but not more than specified by the '[Device]DeviceScheduledEventsMaximum' parameter. This parameter is currently read only (default 2) - it might become writeable in a future version of the interface, however, so far the default value is known to work well in all use cases.
The event engine thread priority is controlled by the parameters '[Device]DeviceEventsThreadPriority', '[Device]DeviceEventsThreadSchedulingPolicy' and '[Device]DeviceEventsThreadApplyPriority'. Upon device open, generally suitable default priority is selected.
The event handling infrastructure can be completely disabled using the 'device_event_handling=0' generic parameter while opening the device.

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 USB3Vision 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 G1
    G2 B
    		⇾
    [R,G,B] [R,G,B]
    [R,G,B] [R,G,B]
    Bayer_NMML
    B G1
    G2 R
    		⇾
    [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 USB3 Vision 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 additional 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 usb3vision_fwupdate.hdev.

Parameters for info_framegrabber

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:Usan | device_sn:<serial number>'] string dynamic List of USB3 Vision devices discovered in the system with information about their device ID, unique name, user-defined name, interface to which they are connected and identifier of the image acquisition interface. 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 USB3Vision interface.
'generic' ['', 'num_buffers=<num>' , 'direct_connection=<mode>' , 'install_driver=<vendor_id/product_id>' , 'add_permissions=<bus_number/device_address>' , 'streaming_mode=0' , 'device_event_handling=0' ] 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:Usan | vendor:<device_vendor> | model:<device_model> | device_sn:<device_serial_number> | tl_type:<tl_type> | status:<device_status> | suggestion:<generic_param>'] string dynamic List of USB3 Vision devices discovered in the system with additional information as a string. Some values are only shown, if they are available. For misconfigured devices (such as those using no or incorrect driver) a corresponding generic parameter to resolve the problem is suggested.
  • 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 string, which contains the device GUID, the vendor and the model separated by underscores. No other device should have the same string, so this is a unique name for the device. If the currently installed drivers don't allow reading the GUID, this string will start with 'TmpNA_'. However, there is a chance that this problem disappears during driver assignment.
  • 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 USB3Vision the value of this entry is 'Usan_VirtualIF'.
  • producer shows the name of the underlying GenICamTL producer.
  • vendor represents the value of the feature 'DeviceVendorName'.
  • model represents the value of the feature 'DeviceModelName'.
  • device_sn shows the serial number of the device, representing also the value of the feature 'DeviceSerialNumber'.
  • tl_type shows the type of the underlying transport layer, i.e. 'U3V'.
  • status shows, if the device is correctly configured or not. The possible values are 'available', 'read-only', 'busy', 'misconfigured' and 'unknown'. For misconfigured devices (such as those with wrong/no attached driver under Windows or insufficient permissions under Linux) a corresponding generic parameter to resolve the problem is suggested through the suggestion info token. Status of 'busy' means the device is currently opened by another application. Even devices that are currently not available for opening are listed.
  • suggestion is added only if status is reported as 'misconfigured' because the suitable driver is not attached to the device (Windows) or sufficient permissions are not available for the device's device file. The value of the suggestion info will be the generic 'install_driver' or 'add_permissions' parameter (depending on situation) that can be used to resolve the problem. This means that if you will pass the suggested 'install_driver'/'add_permissions' parameter as-is in the open_framegrabber operator's Generic parameter (see its documentation), the USB3Vision interface will attempt to switch the device temporarily to correct subnet and open it.
'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 USB3Vision interface.
'start_column' [] Unsupported query.
'start_row' [] Unsupported query.
'vertical_resolution' [0, 1] integer pre-defined Value list for vertical resolution.

Parameters for open_framegrabber

Parameter Values Default Type Description
Name 'USB3Vision' 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>' , 'direct_connection=<mode>' , 'install_driver=<vendor_id/product_id>' , 'add_permissions=<bus_number/device_address>' , 'streaming_mode=0' , 'device_event_handling=0' ], -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.
  • 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'.
  • install_driver: Request to install the required driver for devices specified by the USB vendor and product ID. The parameter format is 'install_driver=vendor_id/product_id', where the vendor_id and product_id are specified as hexadecimal numbers without any prefix. The driver (WinUSB) will be installed to the composite parent of the device(s) matching the vendor and product ID. Note that if another driver was attached before to the device, the applications using that driver will not work any more with the device. When installing the driver, the USB3Vision image acquisition interface will ask for administrator privileges when needed. Note also that when querying the device list using info_framegrabber(...'info_boards'...), for each device with no driver attached or using an unsupported driver, the USB3Vision will suggest the install_driver generic parameter including vendor and product ID corresponding with the device. When working with the HDevelop Image Acquisition Assistant, it will directly suggest to apply the generic parameter when connecting to the device.
    This parameter is applicable on Windows systems only.
  • add_permissions: Request to add access permissions for all users to the device file of the device which is specified using the USB bus number and device address. The parameter format is 'add_permissions=bus_number/device_address', where the bus_number and device_address are specified as decimal numbers. The access mode of the device file will be set to 0666 (read and write for everyone). Note that this has only a temporary effect and will be lost upon system reboot or even upon device reconnection. To achieve a permanent effect, the corresponding udev configuration is required. When changing the permissions, the USB3Vision image acquisition interface will ask for administrative (root) privileges when needed. By default, pkexec will be used to gain root privileges. In situations, when pkexec is not suitable or desired, another command to be used for privilege elevation (such as sudo, gksudo etc.) can be specified through the add_permissions parameter as another optional token. The extended form would be 'add_permissions=bus_number/device_address!elevation_command'. A real example thus could be 'add_permissions=5/2!gksudo'. Note also that this will allow specifying the elevation command with full path for increased security. Note also, that when querying the device list using info_framegrabber(...'info_boards'...), for each device not accessible due to insufficient permissions the USB3Vision image acquisition interface will suggest the add_permissions generic parameter including bus number and device address corresponding to the device. When working with the HDevelop Image Acquisition Assistant, it will directly suggest to apply the generic parameter when connecting to the device.
    This parameter is applicable on Linux systems only.
  • 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 to reduce the used resources like the number of transfers or CPU usage in the Producer, this parameter has to be set to 0. The event handling is by default switched on for devices with event support.
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 USB3 Vision Producer, see detailed description in the section about device opening.
Device ' | device:<device id> | unique_name:<unique name> | user_name:<user-defined name> | interface:<interface id> | producer:Usan | device_sn:<serial number>', '<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, unique_name or serial number of the device has to be set. As a shortcut, only the device ID or user-defined name might be specified or the string 'default' can be used. See full description in section about device opening.
Port --- Unused.
LineIn --- Ignored.

Parameters for set_framegrabber_param

The parameters of the cameras and USB3 Vision Producer are accessed through GenICam and defined in GenICam description file(s) of the respective camera or USB3 Vision 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 USB3 Vision 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 USB3 Vision Producer, the following HALCON interface parameters are supported by set_framegrabber_param:
Parameter Values Default Type Description
'[Consumer]exposure' real Specifies the exposure time. Usually the exposure time is specified in microseconds. However, cameras might deviate from this standard. Consult the documentation of your camera for more detailed information. If [Consumer]exposure_auto is not set to 'Off', [Consumer]exposure access is either read-only or not available. Besides, this EasyParam depends on the camera parameter ExposureMode. If [Consumer]exposure is not available, you might need to change ExposureMode manually to 'Timed'.
'[Consumer]exposure_auto' 'Off', 'Continuous', 'Once' string Specifies if the exposure time is set manually by the user or automatically by the camera.
  • Off: the exposure time is set manually by the user.
  • Once: the exposure time is automatically estimated by the camera device once, based on the next successfully captured image. This value might not be implemented on your device.
  • Continuous: the exposure time is automatically and continuously updated by the camera with every acquired image. This value might not be implemented on your device.
This EasyParam depends on the camera parameter ExposureMode. If [Consumer]exposure_auto is not available, you might need to change ExposureMode manually to 'Timed'
'[Consumer]gain' real Allows to increase the image brightness by applying an amplification factor. Consult the documentation of your camera for more detailed information. If [Consumer]gain_auto is not set to 'Off', [Consumer]gain access is either read-only or not available.
'[Consumer]gain_auto' 'Off', 'Continuous', 'Once' string Specifies if the gain is set manually by the user or automatically by the camera.
  • Off: the gain is set manually by the user.
  • Once: the gain is automatically estimated by the camera once, based on the next successfully captured image. This value might not be implemented on your device.
  • Continuous: the gain is automatically and continuously updated by the camera with every acquired image. This value might not be implemented on your device.
'[Consumer]trigger' 'Off', 'Software', 'Line<x>' string Specifies the mode in which the image acquisition is being triggered.
  • Off: the trigger mode is deactivated and the device operates in free run mode, acquiring images continuously.
  • Software: the trigger mode is activated and [Consumer]trigger_software can be used to generate an internal trigger.
  • Line<x>: the trigger mode is activated and the specified physical line is configured as external source for the trigger signal. Other hardware trigger signals are not supported via this EasyParam.
'[Consumer]trigger_activation' 'RisingEdge', 'FallingEdge', 'AnyEdge', 'LevelHigh', 'LevelLow' string Specifies the activation mode of the trigger. This EasyParam is available when using hardware trigger (i.e. [Consumer]trigger is 'Line<x>'), and if supported by your device.
  • RisingEdge: the trigger is considered valid on the rising edge of the source signal.
  • FallingEdge: the trigger is considered valid on the falling edge of the source signal.
  • AnyEdge: the trigger is considered valid on the falling or rising edge of the source signal.
  • LevelHigh: the trigger is considered valid as long as the level of the source signal is high.
  • LevelLow: the trigger is considered valid as long as the level of the source signal is low.
'[Consumer]trigger_delay' real Specifies the delay that should apply after the trigger has been received before activating the image acquisition. Usually the delay is specified in microseconds. However, cameras might deviate from this standard. Consult the documentation of your camera detailed information.
'[Consumer]trigger_software' integer Generates an internal signal. [Consumer]trigger must be set to 'Software', otherwise the EasyParam is not available.
'[Device]DeviceEventsThreadApplyPriority' --- integer Applies the thread priority and scheduling policy (if applicable on given operating system) configured through the '[Device]DeviceEventsThreadPriority' and '[Device]DeviceEventsThreadSchedulingPolicy' parameters to the event processing thread. If the thread is running, the values are directly applied. If the thread is not running in the moment, the values are stored and will be applied as soon as the thread is started again. It is responsibility of the application to ensure that the calling process has sufficient privileges.
The feature is not available for devices not supporting device events or if the event handling was disabled using the 'device_event_handling=0' generic parameter.
BEWARE: Setting this parameter can lead to an unusable or poorly performing system, use with care.
'[Device]DeviceEventsThreadPriority' <thread_priority> integer OS-specific thread priority value to be used for the internal event processing thread. The actual values are directly the priority identifiers of the operating system, e.g. THREAD_PRIORITY_HIGHEST under Windows or a real-time priority value under Linux.
The actual priority is applied only after executing the '[Device]DeviceEventsThreadApplyPriority' command parameter, possibly together with the '[Device]DeviceEventsThreadSchedulingPolicy' value if applicable on given system.
It is the responsibility of the application to ensure that the calling process has sufficient privileges to apply the priority change and that the value written to the parameter is a valid priority identifier. After applying '[Device]DeviceEventsThreadApplyPriority', the application can read back the priority value to verify if it was properly applied.
Note that when opening the device, the USB3 Vision Producer attempts itself to elevate the thread priority to a suitable value.
The feature is not available for devices not supporting device events or if the event handling was disabled using the 'device_event_handling=0' generic parameter.
BEWARE: Setting this parameter can lead to an unusable or poorly performing system, use with care.
'[Device]DeviceEventsThreadSchedulingPolicy' <scheduling_policy> integer OS-specific scheduling policy value to be used for the internal event processing thread. The actual values are directly the priority identifiers of the operating system, e.g. SCHED_FIFO under Linux. Note that this feature is not available under Windows.
The actual scheduling policy is applied only after executing the '[Device]DeviceEventsThreadApplyPriority' command parameter, together with the '[Device]DeviceEventsThreadPriority' value.
It is the responsibility of the application to ensure that the calling process has sufficient privileges to apply the scheduling policy and that the value written to the parameter is a valid scheduling policy identifier. After applying '[Device]DeviceEventsThreadApplyPriority', the application can read back the scheduling policy value to verify if it was properly applied.
The feature is not available for devices not supporting device events or if the event handling was disabled using the 'device_event_handling=0' generic parameter.
BEWARE: Setting this parameter can lead to an unusable or poorly performing system, use with care.
'[Device]DeviceScheduledEventsMaximum' <max_scheduled_events> 2 integer Maximum number of transfers the event engine will attempt to schedule in advance to the USB3 subsystem to collect device events, regardless of any other parameters. Writeable only if the event handling thread is not active. In the moment, the acquisition interface keeps the thread running permanently, thus the feature is effectively read-only. This can change in future.
The feature is not available for devices not supporting device events or if the event handling was disabled using the 'device_event_handling=0' generic parameter.
BEWARE: Setting this parameter can lead to an unusable or poorly performing system, use with care.
'[Stream]StreamAuxiliaryBufferCount' <num_aux_buffers> 2 integer Number of auxiliary buffers the stream engine will allocate for acquisition. The size of the buffers depends on the payload size reported by the device. The auxiliary buffers are scheduled for acquisition as needed if no free user buffers are available to fill (typically if the camera is acquiring faster than the application processing). Depending on the '[Stream]StreamBufferHandlingMode' parameter, the data acquired into the auxiliary buffer(s) can still be delivered to the application, either overwriting older buffers in the output queue or filling free user buffers that became available in the meanwhile.
Writeable only if no acquisition is active.
BEWARE: Setting this parameter can lead to an unusable or poorly performing system, use with care.
'[Stream]StreamBufferHandlingMode' 'OldestFirst', 'OldestFirstOverwrite', 'NewestOnly' 'OldestFirst' string Selects the mode the streaming engine uses to handle newly acquired data, in particular when the camera runs faster than the application processing. The parameter is writeable only if no acquisition is active. Supported values are:
  • 'OldestFirst': The acquired buffers are always delivered in FIFO manner (oldest first). If the acquisition engine receives a new buffer from the camera but has no available free buffer to fill it in, the new data is discarded.
  • 'OldestFirstOverwrite': The acquired buffers are always delivered in FIFO manner (oldest first). If the acquisition engine receives a new buffer from the camera but has no available free buffer to fill it in, it checks, whether there are older buffers waiting for delivery, not yet picked up by the Consumer. If yes, it takes the oldest of them, overwrites it with the new data and appends it to the end of the output queue. If the output queue is empty (no buffer available for overwriting), the new data is discarded.
  • 'NewestOnly': The output queue of buffers waiting for delivery never contains more than a single (newest) buffer. If the acquisition engine receives a new buffer and there is already an older buffer waiting for delivery in the output queue, the new buffer is put to the output queue instead and the old one is reused for next acquisition. If there are no available free buffers and the output queue is also empty, new data is discarded.
'[Stream]StreamScheduledBuffersMaximum' <max_scheduled_buffers> 4 integer Maximum number of buffers the stream engine will attempt to schedule in advance to the USB3 subsystem for acquisition, regardless of any other parameters. Note that each buffer is typically filled using 3-4 USB transfers.
Writeable only if no acquisition is active.
BEWARE: Setting this parameter can lead to an unusable or poorly performing system, use with care.
'[Stream]StreamScheduledBuffersTarget' <tgt_scheduled_buffers> 2 integer Desired optimal number of buffers the stream engine will attempt to schedule in advance to the USB3 subsystem for acquisition at any given moment. If the number of scheduled buffers decreases under this value, the stream engine will start scheduling auxiliary buffers, if available. As long as the level specified in this parameter is saturated, the auxiliary buffers are not used.
Writeable only if no acquisition is active.
Note that the actual number of scheduled buffers can never exceed '[Stream]StreamScheduledBuffersMaximum'.
BEWARE: Setting this parameter can lead to an unusable or poorly performing system, use with care.
'[Stream]StreamThreadApplyPriority' --- integer Applies the thread priority and scheduling policy (if applicable on the given operating system) configured through '[Stream]StreamThreadPriority' and '[Stream]StreamThreadSchedulingPolicy' parameters to the stream processing thread. If the thread is running (acquisition started), the values are directly applied. If the thread is not running in the moment, the values are stored and will be applied as soon as the thread is started again. It is the responsibility of the application to ensure that the calling process has sufficient privileges.
BEWARE: Setting this parameter can lead to an unusable or poorly performing system, use with care.
'[Stream]StreamThreadPriority' <thread_priority> integer OS-specific thread priority value to be used for the internal stream processing thread. The actual values are directly the priority identifiers of the operating system, e.g. THREAD_PRIORITY_HIGHEST under Windows or a real-time priority value under Linux.
The actual priority is applied only after executing the '[Stream]StreamThreadApplyPriority' command parameter, possibly together with the '[Stream]StreamThreadSchedulingPolicy' value if applicable on given system.
It is the responsibility of the application to ensure that the calling process has sufficient privileges to apply the priority change and that the value written to the parameter is a valid priority identifier. After applying '[Stream]StreamThreadApplyPriority', the application can read back the priority value to verify if it was properly applied.
Note that when opening the device, the USB3 Vision Producer attempts itself to elevate the thread priority to a suitable value.
BEWARE: Setting this parameter can lead to an unusable or poorly performing system, use with care.
'[Stream]StreamThreadSchedulingPolicy' <scheduling_policy> integer OS-specific scheduling policy value to be used for the internal stream processing thread. The actual values are directly the priority identifiers of the operating system, e.g. SCHED_FIFO under Linux. Note that this feature is not available under Windows.
The actual scheduling policy is applied only after executing the '[Stream]StreamThreadApplyPriority' command parameter, together with the '[Stream]StreamThreadPriority' value.
It is the responsibility of the application to ensure that the calling process has sufficient privileges to apply the scheduling policy and that the value written to the parameter is a valid scheduling policy identifier. After applying '[Stream]StreamThreadApplyPriority', the application can read back the scheduling policy value to verify if it was properly applied.
BEWARE: Setting this parameter can lead to an unusable or poorly performing system, use with care.
'add_objectmodel3d_overlay_attrib' 'disable', 'enable' 'disable' string Controls if the acquisition interface should attempt to append the intensity/color overlay to the generated 3D object models. Applicable only if a 3D object model is being output from given grab operator. When switched on, the acquisition interface will try to find suitable information within the acquired data (if it is provided by the device). If so, it appends the overlay information for each point in the output model in form of an extended attribute. Note that in some advanced use cases there might be multiple potential overlay images output by the device, the acquisition interface therefore attempts to find the most suitable one.
First, it tries to identify data marked as "intensity" image in the acquired data. If found and provided as monochrome 2D image, it is appended as '&intensity_gray' extended attribute. If found and provided as RGB image, it is appended as three extended attributes, '&intensity_red', '&intensity_green' and '&intensity_blue'.
If "intensity" data cannot be identified, it tries to find data marked as "reflectance". If found and provided as monochrome 2D image, it is appended as '&reflectance_gray' extended attribute. If found and provided as RGB image, it is appended as three extended attributes, '&reflectance_red', '&reflectance_green' and '&reflectance_blue'.
Finally, if neither "intensity" nor "reflectance" data can be identified (either not present or not correctly marked by the device, it picks the first 2D image within the acquired data than can be mapped to the 3D coordinates. If found and provided as monochrome 2D image, it is appended as '&overlay_gray' extended attribute. If found and provided as RGB image, it is appended as three extended attributes, '&overlay_red', '&overlay_green' and '&overlay_blue'.
If no suitable 2D image is found, no overlay is appended. The actually appended extended attributes can be queried for example using the get_object_model_3d_params operator with the 'extended_attribute_names' parameter. The overlay can be also used for visualization purposes.
'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 a runtime overhead to write the 0xF0 data every time a buffer is queued. It is mainly useful for debugging in combination with transport layers which do not guarantee the transfer of complete images. Please note, that this parameter does not modify the buffer queue, only the content of a buffer will be set to a defined state.
'color_space' 'default', 'gray', 'raw', 'rgb', 'yuv' string Specify the desired color space and thus the number of image channels of the resulting HALCON image. In case of 'default' for Mono pixel formats, ColorSpace is set to 'gray', otherwise to 'rgb' (and for unknown pixel formats to 'raw').
'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 USB3 Vision Producer.
'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. The parameter 'settings_selector' specifies if the settings of the actual (remote) device, one of the USB3 Vision Producer modules or the Consumer parameters (internal parameters of USB3Vision image acquisition interface) are to be restored. See detailed description in section Parameters - Persisting Device Status.
'do_write_configuration' <output_file> string Writes a configuration (ini) file and additionally writes GenICam description files and persistence files with the current configuration of the device into the same directory.
The string parameter must be the filename (including full path) of the target ini file. The path must exist prior to writing. The written ini file contains a list of paths to the written description and persistence files.
GenICam description files are written for the remote device and each USB3 Vision Producer module associated with currently opened device. Persistence files are written for the remote device and each USB3 Vision Producer module as well as for the internal parameters of the USB3Vision image acquisition interface.
The complete configuration can be loaded using the 'CameraType' parameter of open_framegrabber operator, see detailed description in the section about device opening. The persisted values of the internal parameters override the corresponding parameters passed to 'open_framegrabber' (in particular 'BitsPerChannel' and 'ColorSpace').
Instead of specifying the full name of the output ini file, 'default' or an empty string can be used. In this case the files will be written to a temporary directory (subject to availability of %TEMP%, %TMP%, $TMPDIR, /tmp or %HALCONROOT%) and the filename of the configuration file will be halcon_gentl_config.ini. This default option will also apply when using the Image Acquisition Assistant.
See also related sections Selection of GenICam Feature Description File(s) and Parameters – Persisting Device Status.
'do_write_settings' <output_file> string Writes the current settings of the opened device to be able to restore the settings later. The parameter 'settings_selector' specifies if the settings of the actual (remote) device, one of the USB3 Vision Producer modules or the Consumer parameters (internal parameters of USB3Vision image acquisition interface) are to be written. See detailed description in section Parameters - Persisting Device Status.
'event_data' '<list of genicam_feature/internal_parameter>' string Configures GenICam features and/or internal parameters (free mix) to be added to the message queue specified by 'event_message_queue' for feature change notifications for feature selected in 'event_selector'.
Features can be added individually or as a tuple - each 'set' operation for this parameter appends to the current list of event_data. To remove individual features, prepend them with a '~'. To clear all currently added features, call set_framegrabber_param(..., 'event_data', []).
Read more about the usage of this mechanism at Event Message Queues.
'event_message_queue' 0, '<queue_handle>' handle Selects a message queue to which the acquisition interface should send feature change notifications (see further details in Event Message Queues).
The corresponding feature/parameter needs to be previously selected by 'event_selector'.
Setting 0 (NULL) unregisters the previously selected message queue from notifications about given feature/parameter.
'event_notification_helper' 'disable', 'enable' 'disable' string Controls if the acquisition interface should attempt to automatically (un)set 'EventNotification' during set_framegrabber_callback if the callback is being (un)registered on an SFNC-compliant event. Note that this will only work if the callback is being registered on the actual event feature (e.g. 'EventExposureEnd'), not on one of the event data features (e.g. 'EventExposureEndTimestamp'). For further information on events, see Event Data.
'event_selector' '<genicam_feature/internal_parameter>' 'grab_timeout' string Selects a GenICam feature or internal parameter for which feature change notifications through message queues should be configured.
They are sent to the message queue specified by 'event_message_queue', together with additional data configured in 'event_data'.
Read more about the usage of this mechanism at Event Message Queues (which is another alternative to notifications through callbacks, Feature Change Notifications).
'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 milliseconds) 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. There is no conversion of the device byte order. Caution: This is a dangerous function intended for debugging and special cases. Usually only features in the XML should be used.
'settings_selector' 'RemoteDevice', 'Stream', 'Device', 'System', 'Interface', 'Consumer' 'RemoteDevice' string Selects for which component (set of parameters) the streamable parameters are persisted into a file or restored from a file when using set_framegrabber_param(..., 'do_write_settings', []) and set_framegrabber_param(..., 'do_load_settings', []). Selects among the actual (remote) device, one of the USB3 Vision Producer modules or the Consumer parameters (internal parameters of USB3Vision image acquisition interface). Read more about the usage of this mechanism at Parameters – Persisting Device Status.
'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 USB3Vision 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.

Parameters for get_framegrabber_param

There may exist additional read-only parameters with the following postfixes:
  • '_access': These parameters provide the access permissions of the corresponding parameter as a string. Possible values are 'ro' (read-only), 'wo' (write-only), and 'rw' (read/write).
  • '_category': These parameters provide the category of the corresponding parameter as a string.
  • '_description': These parameters provide the tool-tip of the corresponding parameter as a string.
  • '_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].
  • '_representation': These parameters provide the GenICam representation of the corresponding parameter as a string. They only exist for integer-parameters. Possible values are 'Linear', 'Logarithmic', 'Boolean', 'PureNumber', 'HexNumber', 'IPV4Address' and 'MACAddress'. The purpose of the representation is to aid in GUI design.
  • '_streamable': These parameters provide the persistence of the corresponding parameter as an integer. Possible values are 0 if false or 1 if true.
  • '_string': These parameters provide the integer values formatted as a string according to the '_representation' postfix. Especially useful for the '_representation' values 'IPV4Address', 'MACAddress' and 'HexNumber'.
  • '_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
'[Consumer]exposure' real pre-defined Specifies the exposure time. Usually the exposure time is specified in microseconds. However, cameras might deviate from this standard. Consult the documentation of your camera for more detailed information. If [Consumer]exposure_auto is not set to 'Off', [Consumer]exposure access is either read-only or not available. Besides, this EasyParam depends on the camera parameter ExposureMode. If [Consumer]exposure is not available, you might need to change ExposureMode manually to 'Timed'.
'[Consumer]exposure_auto' 'Off', 'Continuous', 'Once' string pre-defined Specifies if the exposure time is set manually by the user or automatically by the camera.
  • Off: the exposure time is set manually by the user.
  • Once: the exposure time is automatically estimated by the camera device once, based on the next successfully captured image. This value might not be implemented on your device.
  • Continuous: the exposure time is automatically and continuously updated by the camera with every acquired image. This value might not be implemented on your device.
This EasyParam depends on the camera parameter ExposureMode. If [Consumer]exposure_auto is not available, you might need to change ExposureMode manually to 'Timed'
'[Consumer]gain' real pre-defined Allows to increase the image brightness by applying an amplification factor. Consult the documentation of your camera for more detailed information. If [Consumer]gain_auto is not set to 'Off', [Consumer]gain access is either read-only or not available.
'[Consumer]gain_auto' 'Off', 'Continuous', 'Once' string pre-defined Specifies if the gain is set manually by the user or automatically by the camera.
  • Off: the gain is set manually by the user.
  • Once: the gain is automatically estimated by the camera once, based on the next successfully captured image. This value might not be implemented on your device.
  • Continuous: the gain is automatically and continuously updated by the camera with every acquired image. This value might not be implemented on your device.
'[Consumer]info_general' handle pre-defined Returns a dictionary handle containing general information about the device. Each key in the dictionary maps a GenICam device information feature. If one key is not implemented on your device, its value will be set to 'ni' (i.e. not implemented). Contained keys:
  • DeviceVendorName (string)
  • DeviceModelName (string)
  • DeviceVersion (string)
  • DeviceFirmwareVersion (string)
  • DeviceSerialNumber (string)
  • DeviceFamilyName (string)
  • SensorWidth (integer)
  • SensorHeight (integer)
The HDevelop Image Acquisition Assistant does not support this MVTec EasyParam.
'[Consumer]trigger' 'Off', 'Software', 'Line<x>' string pre-defined Specifies the mode in which the image acquisition is being triggered.
  • Off: the trigger mode is deactivated and the device operates in free run mode, acquiring images continuously.
  • Software: the trigger mode is activated and [Consumer]trigger_software can be used to generate an internal trigger.
  • Line<x>: the trigger mode is activated and the specified physical line is configured as external source for the trigger signal. Other hardware trigger signals are not supported via this EasyParam.
'[Consumer]trigger_activation' 'RisingEdge', 'FallingEdge', 'AnyEdge', 'LevelHigh', 'LevelLow' string pre-defined Specifies the activation mode of the trigger. This EasyParam is available when using hardware trigger (i.e. [Consumer]trigger is 'Line<x>'), and if supported by your device.
  • RisingEdge: the trigger is considered valid on the rising edge of the source signal.
  • FallingEdge: the trigger is considered valid on the falling edge of the source signal.
  • AnyEdge: the trigger is considered valid on the falling or rising edge of the source signal.
  • LevelHigh: the trigger is considered valid as long as the level of the source signal is high.
  • LevelLow: the trigger is considered valid as long as the level of the source signal is low.
'[Consumer]trigger_delay' real pre-defined Specifies the delay that should apply after the trigger has been received before activating the image acquisition. Usually the delay is specified in microseconds. However, cameras might deviate from this standard. Consult the documentation of your camera detailed information.
'[Device]DeviceEventsThreadPriority' <thread_priority> integer pre-defined OS-specific thread priority value to be used for the internal event processing thread. The actual values are directly the priority identifiers of the operating system, e.g. THREAD_PRIORITY_HIGHEST under Windows or a real-time priority value under Linux.
The actual priority is applied only after executing the '[Device]DeviceEventsThreadApplyPriority' command parameter, possibly together with the '[Device]DeviceEventsThreadSchedulingPolicy' value if applicable on given system.
It is the responsibility of the application to ensure that the calling process has sufficient privileges to apply the priority change and that the value written to the parameter is a valid priority identifier. After applying '[Device]DeviceEventsThreadApplyPriority', the application can read back the priority value to verify if it was properly applied.
Note that when opening the device, the USB3 Vision Producer attempts itself to elevate the thread priority to a suitable value.
The feature is not available for devices not supporting device events or if the event handling was disabled using the 'device_event_handling=0' generic parameter.
BEWARE: Setting this parameter can lead to an unusable or poorly performing system, use with care.
'[Device]DeviceEventsThreadSchedulingPolicy' <scheduling_policy> integer pre-defined OS-specific scheduling policy value to be used for the internal event processing thread. The actual values are directly the priority identifiers of the operating system, e.g. SCHED_FIFO under Linux. Note that this feature is not available under Windows.
The actual scheduling policy is applied only after executing the '[Device]DeviceEventsThreadApplyPriority' command parameter, together with the '[Device]DeviceEventsThreadPriority' value.
It is the responsibility of the application to ensure that the calling process has sufficient privileges to apply the scheduling policy and that the value written to the parameter is a valid scheduling policy identifier. After applying '[Device]DeviceEventsThreadApplyPriority', the application can read back the scheduling policy value to verify if it was properly applied.
The feature is not available for devices not supporting device events or if the event handling was disabled using the 'device_event_handling=0' generic parameter.
BEWARE: Setting this parameter can lead to an unusable or poorly performing system, use with care.
'[Device]DeviceScheduledEventsMaximum' <max_scheduled_events> 2 integer pre-defined Maximum number of transfers the event engine will attempt to schedule in advance to the USB3 subsystem to collect device events, regardless of any other parameters. Writeable only if the event handling thread is not active. In the moment, the acquisition interface keeps the thread running permanently, thus the feature is effectively read-only. This can change in future.
The feature is not available for devices not supporting device events or if the event handling was disabled using the 'device_event_handling=0' generic parameter.
BEWARE: Setting this parameter can lead to an unusable or poorly performing system, use with care.
'[Stream]StreamAuxiliaryBufferCount' <num_aux_buffers> 2 integer pre-defined Number of auxiliary buffers the stream engine will allocate for acquisition. The size of the buffers depends on the payload size reported by the device. The auxiliary buffers are scheduled for acquisition as needed if no free user buffers are available to fill (typically if the camera is acquiring faster than the application processing). Depending on the '[Stream]StreamBufferHandlingMode' parameter, the data acquired into the auxiliary buffer(s) can still be delivered to the application, either overwriting older buffers in the output queue or filling free user buffers that became available in the meanwhile.
Writeable only if no acquisition is active.
BEWARE: Setting this parameter can lead to an unusable or poorly performing system, use with care.
'[Stream]StreamBufferHandlingMode' 'OldestFirst', 'OldestFirstOverwrite', 'NewestOnly' 'OldestFirst' string pre-defined Selects the mode the streaming engine uses to handle newly acquired data, in particular when the camera runs faster than the application processing. The parameter is writeable only if no acquisition is active. Supported values are:
  • 'OldestFirst': The acquired buffers are always delivered in FIFO manner (oldest first). If the acquisition engine receives a new buffer from the camera but has no available free buffer to fill it in, the new data is discarded.
  • 'OldestFirstOverwrite': The acquired buffers are always delivered in FIFO manner (oldest first). If the acquisition engine receives a new buffer from the camera but has no available free buffer to fill it in, it checks, whether there are older buffers waiting for delivery, not yet picked up by the Consumer. If yes, it takes the oldest of them, overwrites it with the new data and appends it to the end of the output queue. If the output queue is empty (no buffer available for overwriting), the new data is discarded.
  • 'NewestOnly': The output queue of buffers waiting for delivery never contains more than a single (newest) buffer. If the acquisition engine receives a new buffer and there is already an older buffer waiting for delivery in the output queue, the new buffer is put to the output queue instead and the old one is reused for next acquisition. If there are no available free buffers and the output queue is also empty, new data is discarded.
'[Stream]StreamScheduledBuffersMaximum' <max_scheduled_buffers> 4 integer pre-defined Maximum number of buffers the stream engine will attempt to schedule in advance to the USB3 subsystem for acquisition, regardless of any other parameters. Note that each buffer is typically filled using 3-4 USB transfers.
Writeable only if no acquisition is active.
BEWARE: Setting this parameter can lead to an unusable or poorly performing system, use with care.
'[Stream]StreamScheduledBuffersTarget' <tgt_scheduled_buffers> 2 integer pre-defined Desired optimal number of buffers the stream engine will attempt to schedule in advance to the USB3 subsystem for acquisition at any given moment. If the number of scheduled buffers decreases under this value, the stream engine will start scheduling auxiliary buffers, if available. As long as the level specified in this parameter is saturated, the auxiliary buffers are not used.
Writeable only if no acquisition is active.
Note that the actual number of scheduled buffers can never exceed '[Stream]StreamScheduledBuffersMaximum'.
BEWARE: Setting this parameter can lead to an unusable or poorly performing system, use with care.
'[Stream]StreamThreadPriority' <thread_priority> integer pre-defined OS-specific thread priority value to be used for the internal stream processing thread. The actual values are directly the priority identifiers of the operating system, e.g. THREAD_PRIORITY_HIGHEST under Windows or a real-time priority value under Linux.
The actual priority is applied only after executing the '[Stream]StreamThreadApplyPriority' command parameter, possibly together with the '[Stream]StreamThreadSchedulingPolicy' value if applicable on given system.
It is the responsibility of the application to ensure that the calling process has sufficient privileges to apply the priority change and that the value written to the parameter is a valid priority identifier. After applying '[Stream]StreamThreadApplyPriority', the application can read back the priority value to verify if it was properly applied.
Note that when opening the device, the USB3 Vision Producer attempts itself to elevate the thread priority to a suitable value.
BEWARE: Setting this parameter can lead to an unusable or poorly performing system, use with care.
'[Stream]StreamThreadSchedulingPolicy' <scheduling_policy> integer pre-defined OS-specific scheduling policy value to be used for the internal stream processing thread. The actual values are directly the priority identifiers of the operating system, e.g. SCHED_FIFO under Linux. Note that this feature is not available under Windows.
The actual scheduling policy is applied only after executing the '[Stream]StreamThreadApplyPriority' command parameter, together with the '[Stream]StreamThreadPriority' value.
It is the responsibility of the application to ensure that the calling process has sufficient privileges to apply the scheduling policy and that the value written to the parameter is a valid scheduling policy identifier. After applying '[Stream]StreamThreadApplyPriority', the application can read back the scheduling policy value to verify if it was properly applied.
BEWARE: Setting this parameter can lead to an unusable or poorly performing system, use with care.
'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 USB3 Vision Producer via the GenICam interface, including those temporarily unavailable, because availability change might be coupled with the callback.
'available_easyparam_names' '[Consumer]exposure_auto', '[Consumer]exposure', '[Consumer]gain_auto', '[Consumer]gain', '[Consumer]info_general' , '[Consumer]trigger', '[Consumer]trigger_activation', '[Consumer]trigger_delay', '[Consumer]trigger_software' string pre-defined Returns a list containing all MVTec EasyParams (see MVTec EasyParams).
'available_param_names' ['<names>'] string dynamic Returns a list containing all available parameters, i.e. those used by the HALCON USB3Vision image acquisition interface (excluding the MVTec EasyParams, which can be listed using 'available_easyparam_names') and those published by the device and USB3 Vision Producer via the GenICam interface (see parameter naming conventions). The availability of some parameters might depend on acquisition status, values of other parameters or other conditions, so the list dynamically changes during runtime.
'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 USB3 Vision 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 USB3 Vision Producer, for example due to acquisition engine overflow reasons. Note that on 32-bit systems only the lower 32-bit part of up to 64-bit timestamp is delivered (unless 'split_param_values_into_dwords' parameter is enabled). See acquisition buffer handling.
'buffer_is_incomplete' 0, 1 integer dynamic Shows if the last grabbed image is incomplete (e.g. due to lost packets). See acquisition buffer handling.
'buffer_reallocation_mode' 'only_increase_size', 'follow_payloadsize' 'only_increase_size' string pre-defined Defines the strategy to follow when reallocating the buffers for a new acquisition. In case of 'only_increase_size', the buffers will be only reallocated when the payload size increases. In case of 'follow_payloadsize', the buffers will be reallocated every time the payload size changes.
'buffer_timestamp' <timestamp> integer dynamic Timestamp attached to the last grabbed (image) buffer by the device (or USB3 Vision Producer). The unit and actual meaning of the timestamp (when it is generated) is device specific. If the frequency of the timestamp counter is known, the value in nanoseconds can be read from 'buffer_timestamp_ns'. Note that on 32-bit systems only the lower 32-bit part of up to 64-bit timestamp is delivered (unless 'split_param_values_into_dwords' parameter is enabled). See acquisition buffer handling.
'buffer_timestamp_ns' <timestamp> integer dynamic Timestamp attached to the last grabbed (image) buffer by the device (or USB3 Vision Producer). The value is in nanoseconds, but might not be available if the timestamp frequency is unknown (refer also to 'buffer_timestamp' and 'device_timestamp_frequency'). Note that on 32-bit systems only the lower 32-bit part of up to 64-bit timestamp is delivered (unless 'split_param_values_into_dwords' parameter is enabled). See acquisition buffer handling.
'camera_type' 'default', <ini/xml filename> 'default' string pre-defined Returns the path to the configuration file used for the CameraType parameter in open_framegrabber.
'clear_buffer' 'disable', 'enable' 'disable' string pre-defined If enabled, each buffer content is cleared before re-queueing (all bytes set to 0xF0 regardless the expected pixel format), so you can see which parts of an image are missing, in case e.g. the transfer of some image packets failed. This parameter adds of course a runtime overhead to write the 0xF0 data every time a buffer is queued. It is mainly useful for debugging in combination with transport layers which do not guarantee the transfer of complete images. Please note, that this parameter does not modify the buffer queue, only the content of a buffer will be set to a defined state.
'color_space' 'default', 'gray', 'raw', 'rgb', 'yuv' 'default' string pre-defined Returns the current color space.
'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 a 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 a tuple of the size corresponding to the number of control data values returned through those operators. If the ID could not be identified (e.g. because the underlying communication protocol does not provide such information), invalid value will be returned (max value of given integer range).
'data_region_id' --- 0xFFFFFFFFFFFFFFFF integer pre-defined Tuple of integer values allowing to track region IDs associated to individual control data outputs returned by the last grab operator. Intended for advanced use cases when the data should be matched with the device configuration. The use of the parameter is application specific and requires knowledge of the GenICam SFNC data model and specific device. Not applicable if last successful grab was performed through grab_image/grab_image_async. In case of grab_data/grab_data_async it returns a tuple of the size corresponding to the number of control data values returned through those operators. If the ID could not be identified (e.g. because the underlying communication protocol does not provide such information), invalid value will be returned (max value of given integer range).
'data_source_id' --- 0xFFFFFFFFFFFFFFFF integer pre-defined Tuple of integer values allowing to track source IDs associated to individual control data outputs returned by the last grab operator. Intended for advanced use cases when the data should be matched with the device configuration. The use of the parameter is application specific and requires knowledge of the GenICam SFNC data model and specific device. Not applicable if last successful grab was performed through grab_image/grab_image_async. In case of grab_data/grab_data_async it returns a tuple of the size corresponding to the number of control data values returned through those operators. If the ID could not be identified (e.g. because the underlying communication protocol does not provide such information), invalid value will be returned (max value of given integer range).
'delay_after_stop' <milliseconds> 0 integer pre-defined The time to wait (in milliseconds) between stopping the acquisition on the device (AcquisitionStop command) and USB3 Vision Producer.
'device' ' | device:<device id> | unique_name:<unique name> | user_name:<user-defined name> | interface:<interface id> | producer:Usan | device_sn:<serial number>', '<device id>' string dynamic Returns the Device parameter string used when opening the device (open_framegrabber).
'device_event_handling' 0, 1 1 integer pre-defined Value of the device_event_handling generic parameter specified in open_framegrabber. The device_event_handling is by default switched on for devices with event delivery (message channel) support and off for devices without the event capability. The generic parameter device_event_handling explicitly allows switching the event handling functionality off even for devices with event support.
'device_timestamp_frequency' <frequency_hz> integer dynamic Frequency of the timestamp counter of the device, in ticks per second (Hz). The frequency might not be known for all devices. The counter is used for example to attach timestamps to acquired buffers. Note that on 32-bit systems only the lower 32-bit part of up to 64-bit timestamp is delivered (unless 'split_param_values_into_dwords' parameter is enabled).
'direct_connection' 'disable', 'enable' 'disable' string pre-defined Value of the direct_connection generic parameter specified in open_framegrabber.
'event_data' '<list of genicam_feature/internal_parameter>' string pre-defined Configures GenICam features and/or internal parameters (free mix) to be added to the message queue specified by 'event_message_queue' for feature change notifications for feature selected in 'event_selector'.
Features can be added individually or as a tuple - each 'set' operation for this parameter appends to the current list of event_data. To remove individual features, prepend them with a '~'. To clear all currently added features, call set_framegrabber_param(..., 'event_data', []).
Read more about the usage of this mechanism at Event Message Queues.
'event_message_queue' 0, '<queue_handle>' handle pre-defined Selects a message queue to which the acquisition interface should send feature change notifications (see further details in Event Message Queues).
The corresponding feature/parameter needs to be previously selected by 'event_selector'.
Setting 0 (NULL) unregisters the previously selected message queue from notifications about given feature/parameter.
'event_notification_helper' 'disable', 'enable' 'disable' string pre-defined Controls if the acquisition interface should attempt to automatically (un)set 'EventNotification' during set_framegrabber_callback if the callback is being (un)registered on an SFNC-compliant event. Note that this will only work if the callback is being registered on the actual event feature (e.g. 'EventExposureEnd'), not on one of the event data features (e.g. 'EventExposureEndTimestamp'). For further information on events, see Event Data.
'event_selector' '<genicam_feature/internal_parameter>' 'grab_timeout' string pre-defined Selects a GenICam feature or internal parameter for which feature change notifications through message queues should be configured.
They are sent to the message queue specified by 'event_message_queue', together with additional data configured in 'event_data'.
Read more about the usage of this mechanism at Event Message Queues (which is another alternative to notifications through callbacks, Feature Change Notifications).
'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 milliseconds) 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>' , 'direct_connection=<mode>' , 'streaming_mode=0' , 'device_event_handling=0' ], -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 USB3 Vision Producer.
'image_contents' 'unknown', 'image', 'coord_a', 'coord_b', 'coord_c', 'coord_mixed', 'confidence' 0 string pre-defined Tuple describing the logical type of the image data returned by the last grab operator. If the last successful grab was performed through grab_image/grab_image_async, the parameter returns always single value. In case of grab_data/grab_data_async it returns a tuple of the size corresponding to the number of images returned through those operators. Possible values are:
  • 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, i.e. 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 a tuple of the size corresponding to the number of images returned through those operators. If the ID could not be identified (e.g. because the underlying communication protocol does not provide such information), invalid value will be returned (max value of given integer range).
'image_raw_buffer_padding_bytes' --- 0 integer pre-defined Tuple of integers reporting for raw buffers of type 'blob' (see 'image_raw_buffer_type') the size of unused padding bytes at the end of such grabbed HALCON image. Because artificial dimensions need to be chosen for the resulting HALCON image in this case, the size of such image might not exactly equal the size of the buffer data and thus the padding might be needed. Zero is reported for buffers of type 'image'. Applies only in case of the 'raw' color format. See raw output format chapter. If the last successful grab was performed through grab_image/grab_image_async, the parameter returns always single value. In case of grab_data/grab_data_async it returns a tuple of the size corresponding to the number of images returned through those operators.
'image_raw_buffer_type' 'image', 'blob' 0 string pre-defined Tuple of strings showing whether the last grabbed HALCON image(s) is created from buffer containing real image data with known properties (in particular image size and pixel format) or if it is created from a blob of other data (non-image data or image data of unknown format). Note that in case of the blob data the dimensions of the HALCON image are meaningless. Applies mainly in case of the 'raw' color format. Possible values are 'image' and 'blob'. See raw output format chapter. If the last successful grab was performed through grab_image/grab_image_async, the parameter returns always single value. In case of grab_data/grab_data_async it returns a tuple of the size corresponding to the number of images returned through those operators.
'image_region_id' --- 0xFFFFFFFFFFFFFFFF integer pre-defined Tuple of integer values allowing to track region IDs associated to individual image outputs returned by the last grab operator. Intended for advanced use cases when the data should be matched with the device configuration. The use of the parameter is application specific and requires knowledge of the GenICam SFNC data model and specific device. If the last successful grab was performed through grab_image/grab_image_async, the parameter returns always single value. In case of grab_data/grab_data_async it returns a tuple of the size corresponding to the number of images returned through those operators. If the ID could not be identified (e.g. because the underlying communication protocol does not provide such information), invalid value will be returned (max value of given integer range).
'image_source_id' --- 0xFFFFFFFFFFFFFFFF integer pre-defined Tuple of integer values allowing to track source IDs associated to individual image outputs returned by the last grab operator. Intended for advanced use cases when the data should be matched with the device configuration. The use of the parameter is application specific and requires knowledge of the GenICam SFNC data model and specific device. If the last successful grab was performed through grab_image/grab_image_async, the parameter returns always single value. In case of grab_data/grab_data_async it returns a tuple of the size corresponding to the number of images returned through those operators. If the ID could not be identified (e.g. because the underlying communication protocol does not provide such information), invalid value will be returned (max value of given integer range).
'image_width' <width> 0 integer pre-defined Width of the last acquired image. See acquisition buffer handling. If there is no valid last buffer available, the last queried value of the 'Width' parameter of the remote device is returned.
'line_in' <default> 0 integer pre-defined The value is not used, so a default value is returned.
'name' 'USB3Vision' 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 USB3 Vision Producer.
'num_buffers_underrun' <number> integer dynamic Number of lost buffers due to buffer queue underrun since opening the device. Queue underrun occurs when the USB3 Vision Producer has a new image data available, but it has no free buffer to store them.
'port' <port> -1 integer pre-defined The value is not used, so a default value is returned.
'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. There is no conversion of the device byte order. 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 USB3Vision interface.
'settings_selector' 'RemoteDevice', 'Stream', 'Device', 'System', 'Interface', 'Consumer' 'RemoteDevice' string pre-defined Selects for which component (set of parameters) the streamable parameters are persisted into a file or restored from a file when using set_framegrabber_param(..., 'do_write_settings', []) and set_framegrabber_param(..., 'do_load_settings', []). Selects among the actual (remote) device, one of the USB3 Vision Producer modules or the Consumer parameters (internal parameters of USB3Vision image acquisition interface). Read more about the usage of this mechanism at Parameters – Persisting Device Status.
'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 USB3Vision image acquisition interface - with few exceptions, the 'buffer_timestamp', 'buffer_timestamp_ns', 'device_timestamp_frequency' and 'buffer_frameid' internal parameters.
'start_async_after_grab_async' 'disable', 'enable' 'enable' string pre-defined Status of 'start_async_after_grab_async'.
'start_column' <column> 0 integer pre-defined Unsupported, returns always 0.
'start_row' <row> 0 integer pre-defined Unsupported, returns always 0.
'streaming_mode' 0, 1 1 integer pre-defined Value of the streaming_mode generic parameter specified in open_framegrabber. The streaming_mode is by default switched on for devices with streaming support and off for peripheral devices (devices without any data streams). The generic parameter streaming_mode explicitly allows switching the streaming functionality off, even for devices with streaming support.
'vertical_resolution' 0, 1, resolution 1 integer pre-defined Current value of vertical resolution.
'volatile' 'disable', 'enable' 'disable' string pre-defined Current value of the volatile mode.

Operator set_framegrabber_lut

Not supported by this interface.

Operator get_framegrabber_lut

Not supported by this interface.

Operator set_framegrabber_callback

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 USB3 Vision Producer through the GenICam description files as well as for internal parameters of the acquisition interface.
The list of supported callback targets can be queried by calling get_framegrabber_param(..., 'available_callback_types', ...).
One of the important use cases for feature change callbacks is the device event delivery mechanism, see details in event data and feature notifications sections. The 'CallbackType' parameter of set_framegrabber_callback defines the feature for which the callback is registered. It is the same plain feature name as used with set_framegrabber_param, including a possible prefix, such as '[Device]' (refer to the parameter naming convention).
The registered callback function would be called whenever a given feature is potentially changed (including its other properties such as range or access mode). Note that it does not necessarily always mean that the feature actually has a new value. If the callback function is set to NULL, the corresponding callback will be unregistered. Note that the interface keeps just a single registration for every feature, if you attempt to register a new callback for a feature that already had a callback registered, the previous registration will be replaced with the new one.

The signature of the callback function is Herror (__stdcall *HAcqCallback)(void *AcqHandle, void *Context, void *UserContext) and uses the following parameters:

  • AcqHandle: Acquisition handle of the corresponding image acquisition instance.
  • Context: Optional context data of the specific callback. Up to now, this parameter is not used, i.e., Context is set to NULL.
  • UserContext: Optional context data of the specific callback. Up to now, this parameter is not used, i.e., UserContext is set to NULL.

Note that the execution time of a user-specific callback function must always be as short as possible since during the execution of a callback function the handling of further internal callbacks might be blocked. This can be achieved by removing the current processing from the user-specific callback function to a separate thread that is controlled via signals or events. The callback function is executed in the context of the underlying interface or driver.
It is also important to understand that the callbacks might be fired as a side-effect of parameter-setting or grab operations, ie. it might be called from within their respective locks. The user is responsible to take this into account in the callback handler to avoid risk of a deadlock.

Operator get_framegrabber_callback

This interface supports feature callbacks via the operators set_framegrabber_callback and get_framegrabber_callback. For more information see set_framegrabber_callback.

Operator grab_image_start

Starts a new asynchronous grab. See also grab_image_start and section about acquisition control. Note that this operator starts acquisition on the USB3 Vision Producer and device and locks features protected during acquisition. If grab_image_start is called repeatedly, the acquisition is restarted on both USB3 Vision Producer and device. That means, that the buffer queue and all stream related statistics parameters like 'buffer_frameid' are reset. The acquisition can be stopped (and the features unlocked) using set_framegrabber_param(..., 'do_abort_grab', ...).

Operator grab_image

grab_image starts a new synchronous grab of a single image. See also grab_image, 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'.

Operator grab_image_async

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 USB3Vision acquisition interface, because there is no way to support it reliably . If needed, the application needs to implement alternative functionality on its own.

Operator grab_data

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.

Operator grab_data_async

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 USB3Vision acquisition interface, because there is no way to support it reliably . If needed, the application needs to implement alternative functionality on its own.

Operator close_framegrabber

This operator closes the device. See also close_framegrabber.

HDevelop Examples

For this interface there are the following examples available:
  • usb3vision_acquisition_events.hdev - Example how to handle events with additional event data using message queues.
  • usb3vision_2cameras.hdev - Grabbing images from two cameras.
  • usb3vision_do_abort_grab.hdev - Aborting an ongoing image acquisition.
  • usb3vision_easyparams.hdev - Handling MVTec EasyParams.
  • usb3vision_fileaccess.hdev - Example how to upload and download files from GenICam devices.
  • usb3vision_frame_rate.hdev - Example to measure the effective frame rate of an acquisition device.
  • usb3vision_fwupdate.hdev - Example how to apply a firmware update using GenICam's FWUpdate module.
  • usb3vision_information.hdev - Program for gathering information about the system and the camera configuration. Please attach the resulting files when requesting support.
  • usb3vision_install_driver.hdev - Installs the necessary driver for a device and then opens it. This is the same mechanism the HDevelop Image Acquisition Assistant uses for this purpose.
  • usb3vision_io_control.hdev - Example how to control the GPIOs of a device.
  • usb3vision_parameters.hdev - Lists all parameters of a device.
  • usb3vision_parameter_persistence.hdev - Demonstrates writing parameter values to files and restoring parameter values from files.
  • usb3vision_simple.hdev - A simple example to show the usage of the interface.
  • usb3vision_software_trigger.hdev - Usage of software trigger.

Troubleshooting

In case of problems with the HALCON USB3Vision Interface the following hints might help to solve them.

General:
  • Check if the latest revision of the HALCON USB3Vision interface is used.
  • Check the System Requirements.
  • 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).
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 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.
Please run the HDevelop example usb3vision_information.hdev to gather information about the system and the camera configuration, and then attach the resulting files when requesting support.

Usage of third-party libraries

This interface depends on third-party libraries. See the file third_party_usb3vision.txt in the HALCON base directory for copyright and license information. Libraries are used without modifications unless explicitly stated in the file.

You can request the source for those third-party libraries licensed under GPL or LGPL via email to info@mvtec.com with the subject “Request source code of third-party libraries”.

Release Notes

  • Revision 20.11.20 (Jul 31, 2023):
    • The underlying GenApi version has been updated to the latest official release 3.4.1. This improves the validation of the string representation of parameters written through the '_string' postfix.
    • Pixel formats 'YCbCr420_8_YY_CbCr_Semiplanar', 'YCbCr420_8_YY_CrCb_Semiplanar', 'YCbCr422_8_YY_CbCr_Semiplanar', and 'YCbCr422_8_YY_CrCb_Semiplanar' are now supported.
    • Execution of 'do_write_configuration' with 'streaming_mode' off returned an error. This problem has been fixed.
    • The first access to an MVTec EasyParam could change the value of its equivalent GenICam device parameter. This problem has been fixed.
    • Accessing an MVTec EasyParam could lead to a crash if any of the underlying GenICam parameters had an unexpected type. This problem has been fixed.
    • The robustness of setting/restoring the device trigger state in usb3vision_information.hdev has been improved.
    • Querying the '_representation' of an MVTec EasyParam could in some cases lead to a crash. This problem has been fixed.
  • Revision 20.11.19 (Apr 5, 2023):
    • If a numerical parameter has a special representation besides its pure value, the type of representation can now be queried by using the '_representation' postfix.
    • The string representation of a parameter value can be now queried by using the '_string' postfix.
    • The libCLAllSerial shared object has been removed from the redistribution of GenApi 3.4.0.
    • The HDevelop example usb3vision_software_trigger.hdev has been added to demonstrate how to use software trigger in combination with grab_image_async.
    • The example usb3vision_do_abort_grab.hdev has been rewritten.
    • third_party_usb3vision.txt now contains links to the corresponding software location. See also Usage of third-party libraries.
  • Revision 18.11.18 (Oct 7, 2022):
    • The MVTec EasyParams have been implemented to deal with the most common GenICam features in a simple and user-friendly way.
    • The new parameter 'available_easyparam_names' has been added to return the list of the MVTec EasyParams.
    • The HDevelop example usb3vision_easyparams.hdev has been added to demonstrate how to handle the MVTec EasyParams.
    • On a Unix system, loading GenICam persistence files that contained Windows line endings failed. This problem has been fixed.
  • Revision 18.11.17 (Jul 1, 2022):
    • USB3 Vision specification version 1.2 is now supported. This includes GenDC streaming used e.g. by 3D devices.
    • With the previous revision, this interface could not be loaded on macOS. This problem has been fixed.
  • Revision 18.11.16 (May 11, 2022):
    • On a Unix system, loading Consumer persistence or configuration ini that was written on a Windows system failed. This problem has been fixed. Moreover, writing Consumer persistence or configuration ini files on a Windows system has been changed to use Unix line ending.
    • Connection with serial number is now possible, see Identifying and Opening a Device.
    • The underlying GenApi version has been updated to the latest official release 3.4. This fixes a crash during 'do_load_settings' when a device failed to execute the underlying command 'DeviceRegistersStreamingEnd'.
    • It is now possible to receive Feature Change Notifications on any parameter listed by 'available_param_names'.
    • A new parameter 'event_new_buffer' has been added which is only available as an event, see Feature Change Notifications and following.
    • There was a memory leak with each message delivered through the Event Message Queues mechanism. This problem has been fixed.
    • The identifier (key 'id') of the messages incoming on an event was not always unique. This problem has been fixed. The device name in the string ':' now corresponds with the 'unique_name' from info_framegrabber.
    • Retrieving GenICam XML description files from the host file system was broken. This problem has been fixed.
    • Updated underlying libusb version to 1.0.24. This resolves that on Windows, the number of USB transfers scheduled concurrently by the control, stream and event channels was limited to 64. As a result, difficulties could appear in particular in multi-camera use cases.
    • The HDevelop script usb3vision_information.hdev now saves the output data into the user's Documents folder to avoid problems with missing writing permissions. Further, the script can now deal with non-alphanumerical characters in the device unique name. Moreover, a problem related to the restoring of the original trigger settings has been fixed.
  • Revision 18.11.15 (Oct 22, 2021):
    • Packed Bayer formats as specified by the GenICam Pixel Format Naming Convention are now supported.
    • With the previous revision, devices could not be initialized on macOS. This problem has been fixed.
    • The read-write parameters of the Consumer module are streamable, i.e. they can be persisted with 'do_write_settings' or 'do_write_configuration'. However, get_framegrabber_param returned 0 for these parameters with postfix '_streamable'. This problem has been fixed.
    • The distribution package of this interface now contains files providing meta information for the HDevelop example browser.
  • Revision 18.11.14 (Feb 24, 2021):
    • The utilities libusb-1.0-usan.dll and libwdi-usan.dll again depended on Visual Studio 2013 Run-Time Libraries. This problem has been fixed.
    • The underlying GenApi version has been updated to the latest official release 3.3.
    • The assembly of an ObjectModel3D from encoder-controlled Linescan 3D devices has been accelerated significantly. To allow this acceleration, the devices must announce ChunkEncoderValue and ChunkScanLineSelector through their ValueArrayCandidates as described by GenICam Standard Feature Naming Convention 2.7 and later.
    • For open_framegrabber with a device string in the 'token:value' form, it was mandatory to contain the separator ' | '. This restriction has been removed.
    • The GenICam caching mechanism was inactive unless one of the environment variables TEMP, TMP or TMPDIR was set. Now, /tmp or HALCONROOT are used as a fallback.
    • The HDevelop example usb3vision_frame_rate.hdev has been added to measure the frame rate of an acquisition device.
    • The HDevelop example usb3vision_acquisition_events.hdev ran into a deadlock in case of very quickly incoming events. This problem has been fixed.
    • The HDevelop example usb3vision_information.hdev has been refactored and now it calls the new procedure library genicamtl_information.hdpl. Moreover, this new version switches off TriggerMode in order to test image acquisition.
    • The error handling has been improved. Additional information about the cause of an error can now be queried with the operator get_extended_error_info. For the HALCON language interfaces (C# and C++), the HALCON exception class provides methods to access the additional error information.
  • Revision 18.11.13 (Oct 27, 2020):
    • This interface couldn't be loaded from .NET Core applications on Linux and macOS. This problem has been fixed.
    • Added support for 'YCbCr411_8_CbYYCrYY', 'YCbCr422_8' and 'YCbCr422_8_CbYCrY' pixel formats.
  • Revision 13.0.12 (Sep 18, 2020):
    • Most file operations did not support UTF-8 file names. This problem has been fixed. However, some of the operations like Firmware Update are managed by GenICam GenApi which might not support them.
    • In the previous revision 'do_write_configuration' did not write the path to generated xml files into the generated ini file. This problem has been fixed.
  • Revision 13.0.11 (Aug 7, 2020):
    • 'do_write_configuration' has been extended to also generate a persistence file for the GenTL Consumer (persisting internal parameters of the HALCON USB3Vision image acquisition interface itself like 'grab_timeout'), see Parameters – Persisting Device Status.
    • It is now possible to write and load persistence files for individual GenTL Producer modules or the GenTL Consumer when the device has already been opened. This was so far only possible for the remote device. The persistence file to be written or loaded is selected with the parameter 'settings_selector'.
    • When loading persistence files with open_framegrabber, some of the persisted parameter values were overwritten. This problem has been fixed.
    • get_framegrabber_param(..., 'event_message_queue', ...) failed with HALCON versions prior to 18.05. This problem has been fixed.
    • The HDevelop example usb3vision_information.hdev has been added to gather information about the system and the camera configuration.
    • The HDevelop example usb3vision_parameter_persistence.hdev has been added to demonstrate writing parameter values to files and restoring parameter values from files.
    • The parameter 'available_event_names' was wrongly written as 'available_event_types'. This problem has been fixed.
  • Revision 13.0.10 (Dec 10, 2019):
    • Updated underlying GenApi version to latest official release v3.2. The Update includes a bug fix on persistence of user and sequencer sets and other minor bug fixes.
    • The parameter 'num_buffers' was limited to an arbitrary maximum of 1023. This limitation has been removed.
    • The utilities hAcqUSB3VisionElevate.exe, libusb-1.0-usan.dll, and libwdi-usan.dll depended on Visual Studio 2013 Run-Time Libraries. This problem has been fixed.
  • Revision 13.0.9 (Jul 22, 2019):
    • You can now query if a feature can be persisted by using the '_streamable' postfix.
    • The HDevelop example usb3vision_parameters.hdev has been extended to check if a parameter can be persisted.
    • The file third_party_usb3vision.txt has been added to the distribution package of this interface.
    • The helper utility hAcqUSB3VisionElevate was broken on the x64-linux architecture because it did not find libusb-1.0-usan.so.0. This problem has been fixed.
  • Revision 13.0.8 (May 2, 2019):
    • Added support for 'BiColorRGBG8' and 'BiColorBGRG8' pixel formats.
    • 3D object models from grab_data and grab_data_async are now generated with 2D mapping. This significantly speeds up several operators working on 3D object models.
    • The new HDevelop example usb3vision_io_control.hdev has been added to demonstrate how to control the GPIOs of a device.
  • Revision 13.0.7 (Jan 21, 2019):
    • The mechanism to generate a HALCON ObjectModel3D from 3D images has been extended for Disparity images. Such images need to include the following chunks specified in SFNC 2.4: 'ChunkScan3dFocalLength', 'ChunkScan3dBaseline', 'ChunkScan3dPrincipalPointU', 'ChunkScan3dPrincipalPointV'.
    • Image acquisition failed when the camera sent recently outdated GenCP acknowledges. This problem has been fixed.
  • Revision 13.0.6 (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 usb3vision_fileaccess.hdev.
    • GenICam's FWUpdate is now supported. See Firmware Update and the new HDevelop example usb3vision_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, one new HDevelop example has been added to show this functionality usb3vision_acquisition_events.hdev.
    • 'do_write_configuration' has been extended to store not only the current device configuration but also generate persistence files for all the USB3 Vision 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.
    • 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.
  • Revision 13.0.5 (Apr 27, 2018):
    • The driver installer included in libwdi-usan.dll had a dependency on Microsoft Visual Studio 2010. This problem has been fixed.
    • 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).
    • 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.
    • On Unix systems, HALCON crashed when ended without calling close_framegrabber. This problem has been fixed.
    • Updated underlying libusb version from 1.0.16 to 1.0.21.
  • Revision 13.0.4 (Nov 28, 2017):
    • libusb-1.0-usan.so.0 has been moved to a subdirectory on Linux systems.
    • The technical dependency from the HALCON Library has been removed.
    • Added new parameter 'event_notification_helper' which enables a helper to automatically set 'EventNotification' during set_framegrabber_callback if the callback is being registered on an SFNC-compliant event. For further information, see Event Data.
    • Added new parameters 'buffer_frameid' and 'image_pixel_format'.
    • When calling get_framegrabber_callback on a callback that was not registered, an error was returned. This problem has been fixed.
    • With some cameras, grab_image_async did not start a new acquisition in 'SingleFrame' or 'MultiFrame' mode even though 'start_async_after_grab_async' was enabled. This problem has been fixed.
    • When reaching the 16 bit boundary of the GenCP request ID by numerous changes of camera parameters, one setting failed. This problem has been fixed.
  • Revision 13.0.3 (May 3, 2017):
    • Updated underlying GenApi version to latest official release v3.0.2 which contains some minor bug fixes.
  • Revision 13.0.2 (Mar 16, 2017):
    • Erroneously, the error code H_ERR_FGWR (#5307) was returned in case of incomplete images. This problem has been fixed. Now, the incomplete image is delivered and the parameter 'buffer_is_incomplete' returns true.
    • The system requirements have been updated to libudev.so.1 or higher.
    • The interface documentation was extended and now contains a description of the strings returned by info_framegrabber(...,'info_boards',...).
    • Added new HDevelop example usb3vision_2cameras.hdev that shows how to use the USB3Vision interface with two cameras.
    • Added new HDevelop example usb3vision_do_abort_grab.hdev that shows how to abort an ongoing image acquisition.
  • Revision 13.0.1 (Oct 28, 2016):
    • HALCON 13 version of the interface.
    • Added support for GenTL 1.5. This mainly means support for 3D data acquisition, see Using 3D Devices.
      Therefore, the operators grab_data/grab_data_async have been implemented, see Acquisition – Grab Operators.
      To control the 3D data acquisition, the following parameters have been introduced: image_contents, image_source_id, image_region_id, image_purpose_id, image_raw_buffer_type, image_raw_buffer_padding_bytes, data_contents, data_source_id, data_region_id, data_purpose_id, create_objectmodel3d, coordinate_transform_mode, confidence_mode, confidence_threshold, add_objectmodel3d_overlay_attrib. The integrated producer Usan has been updated to version 1.0.7 accordingly.
  • Revision 6.7 (Jul 14, 2016):
    • Updated integrated producer Usan to version 1.0.6. Improved stream handling for cameras that are not compatible with Usan's default transfer alignment.
  • Revision 6.6 (May 13, 2016):
    • Updated underlying GenApi version to latest official release v3.0.1. With the previous version some specific cameras could not be opened and in the worst case the application also crashed when using such devices. This problem has been fixed. Please note that therefore also the genicam directory of your HALCON installation will be updated.
    • Updated integrated producer Usan to version 1.0.5 as it was not possible to use the USB3Vision interface in more than one process at the same time. This problem has been fixed.
    • Under Windows, open_framegrabber crashed if the environment variable PATH was empty. This problem has been fixed.
  • Revision 6.5 (Feb 15, 2016):
    • Updated underlying GenApi version to latest official release v3.0, which enables to open a device much faster and requires less memory. Please note that therefore also the genicam directory of your HALCON installation will be updated.
    • Added support for the 'Mono10p' and 'Mono12p' pixel formats.
    • Added limitation for OS X.
    • Added paragraph 'Using internal color conversion' to this document.
    • Updated integrated producer Usan to version 1.0.4. Reaching the full frame rate with small ROI was not possible in combination with certain devices. This problem has been fixed.
    • According to this documentation, the fourth value returned by get_framegrabber_param(..., 'AnyParameter_range', ...) was a default value. Actually, it is the current value. Thus, this documentation has been adapted accordingly.
  • Revision 6.4 (Oct 30, 2015):
    • The system requirements regarding the Visual Studio C++ Redistributable Package have been updated.
    • The error code H_ERR_FGABORTED (#5336) is returned by the grab operators when a grab has been aborted instead of the former H_ERR_FGF (#5306).
    • In case of devices which do not allow to stop acquisition, e.g. due to a lost connection, the call of the parameter 'do_abort_grab' was not able to abort the running grab. This problem has been fixed. Please note that in this case the communication with the device is somehow broken and re-initialization is strongly advised.
    • The documentation about driver requirements and usage with other interfaces or software has been updated.
    • Added support for user-defined names. Therefore, the strings returned by info_framegrabber(...'info_boards'...) and info_framegrabber(...'device'...) have been extended to include the new entries unique_name:<unique name> and user_name:<user-defined name> which corresponds to UserDeviceID. The content of the new unique_name entry is the same as the content of the former device entry. Now, the device entry contains the user-defined name if available or the unique name. open_framegrabber now also accepts user-defined names.
  • Revision 6.3 (Jun 10, 2015):
    • Under Windows, some GenICam dynamic libraries were not loaded/unloaded correctly and a low-level error was printed. This problem has been fixed.
    • do_abort_grab returned an error if called before the first grab. This problem has been fixed.
    • For 'na' (not available) parameters, neither the range nor the values property was implemented. This problem has been fixed.
    • Parameters 'grab_timeout' and 'delay_after_stop' were missing the range property. This problem has been fixed.
    • The access and visibility properties returned 'undefined' in case the parameters had no such properties. Now they return an error if they are not available.
    • 'available_param_names' returned not all implemented parameters. Now it also returns 'na' (not available) parameters in addition to 'ro' (readonly), 'wo' (writeonly) and 'rw' (readwrite) parameters, but only when the visibility is not 'invisible'. Note that the access mode of parameters might change during runtime.
    • The documentation of 'num_buffers' was not clear enough about the need of an extra buffer for internal use. The documentation has been improved.
    • Parameters 'buffer_is_incomplete', 'buffer_timestamp', 'raw_buffer_padding_bytes', 'raw_buffer_type' had fixed access mode 'ro'. In case no buffer has been grabbed yet this is wrong and should be 'na'. This problem has been fixed.
    • The HDevelop example usb3vision_parameters.hdev has been improved.
  • Revision 6.2 (Feb 26, 2015):
    • Updated underlying GenApi version to latest official release v2.4.1, including performance improvements and several minor bug fixes. Please note that therefore also the genicam directory of your HALCON installation will be updated.
    • Updated integrated producer Usan to version 1.0.3.
    • Fixed problems of driver installer under Windows: Win32 was missing files, Win64 needed debug runtime, driver installer was not signed.
    • Addressed limitations of libusbx under Windows to improve usage of multiple cameras.
    • Addressed performance issues in case the camera delivers a higher frame rate as the application can use.
    • Added new parameters and documentation for advanced streaming engine control and advanced event engine control.
    • Added GenICam troubleshooting hint.
    • Added support for buffer handling modes 'OldestFirstOverwrite' and 'NewestOnly'.
    • Added generic parameter 'device_event_handling=0' to explicitly ignore the event channel when a device is opened.
    • Made warning about unexpected parameter types more human readable.
    • Improved compatibility with other acquisition interfaces which are using libusbK.
  • Revision 6.1 (Oct 31, 2014):
    • HALCON 12 version of the interface.
    • Support more host controllers for driver installation on Windows.
    • Fixed a possible deadlock during initialization on Windows.
    • Fixed documentation of parameter 'camera_type'. The .xml extension option for the configuration file was missing.
    • Improved error information returned by set_framegrabber_param when trying to set a parameter without specifying a value.
    • Added missing descriptions of the parameters: 'buffer_reallocation_mode', 'do_load_settings' and 'do_write_settings'.
  • Revision 5.2 (Mar 20, 2014):
    • Fixed problem when using multiple image acquisition interfaces, which do not use the same GenApi version, in arbitrary order.
    • Fixed crash when using multiple GenApi-based image acquisition interfaces which use the same GenApi version. In this case, when closing the last instance of one of the interfaces, GenApi could not be used by the remaining interfaces anymore. This fix has the side effect that GenApi cannot be unloaded anymore.
    • Improved description of parameter 'clear_buffer'.
    • Added libudev system requirement for Linux.
  • Revision 5.1 (Jan 31, 2014):
    • Added Linux and Mac OS X support.
    • Fixed incorrect device speed detection that might fail on Windows 8.1.
    • Fixed crash when trying to execute GenICam commands without parameter.
    • New parameter 'register_<addr>_<len>' for direct register access.
    • Added support for PFNC pixel format namespace. Please note that no new conversion routines have been implemented.
    • Changed example programs to be more userfriendly.
  • Revision 5.0 (Oct 28, 2013):
    • First official release.
Products/MVTec Interfaces