Dokumentation
Image Acquisition Interface for GenICam GenTL compliant cameras
Interface: | GenICamTL |
Revision: | 5.13 |
Date: | 2016-05-13 |
HALCON Version: | 11.0 |
- General
- System Requirements
- Environment Variables
- Features
- Limitations
- GenICam GenApi
- GenICam GenTL
- Identifying and Opening a Device
- Selection of GenICam Feature Description File(s)
- Parameters – Naming Conventions
- Parameters – GenICam Data Types
- Parameters – Persisting Device Status
- Acquisition – Overview, Device Control
- Acquisition – Buffer Handling
- Acquisition – Image Format Handling
- Raw Output Format – Custom Pixel Formats, Non-image Buffers
- Chunk Data
- Feature Change Notifications (Callbacks)
- Event Data
- Using HDevelop Image Acquisition Assistant
- Using internal color conversion
- Parameters for info_framegrabber
- Parameters for open_framegrabber
- Parameters for set_framegrabber_param
- Parameters for get_framegrabber_param
- Operator set_framegrabber_lut
- Operator get_framegrabber_lut
- Operator set_framegrabber_callback
- Operator get_framegrabber_callback
- Operator grab_image_start
- Operator grab_image
- Operator grab_image_async
- Operator grab_data
- Operator grab_data_async
- Operator close_framegrabber
- HDevelop Examples
- Troubleshooting
- Release Notes
General
System Requirements
- Intel compatible PC with Windows XP SP1/Vista/7/8, Windows XP/Vista/7/8 x64, also WoW64 (using 32-bit HALCON on 64-bit Windows), Linux with kernel 2.6 (or higher) , or OS X.
- Windows: Visual Studio C++ 2005 SP1 Redistributable Runtime
Package, particularly msvcp80.dll and msvcr80.dll.
If this package is not installed please download and install it from
the Microsoft Download Center for Windows x86
or Windows x64. In addition it might be necessary
to install the
Microsoft Visual C++ 2005 Service Pack 1 Redistributable Package ATL
Security Update and the
Microsoft Visual C++ 2005 Service Pack 1 Redistributable Package MFC
Security Update for your system.
Note: It is not sufficient to copy the missing files! - Successfully installed GenICam GenTL Producer. The corresponding .cti file must be located in one of the directories specified by the environment variable GENICAM_GENTL32_PATH or GENICAM_GENTL64_PATH, respectively. Otherwise, the full path to the GenTL Producer has to be specified when opening the device.
- Depending on the used transport layer make sure that you have access
to the device. Follow all requirements and recommendations specified
by the respective GenTL Producer(s) to guarantee flawless and effective
access to the device(s). Especially for (Gigabit) Ethernet the following
points have to be checked:
- It is recommended to use a PCIe network adapter which supports jumbo frames. Please configure the network adapter accordingly, e.g., to a MTU value of 9000. Furthermore, the camera should be connected directly to the network adapter to avoid interference with other network traffic. Please be aware that networking equipment like switches not necessarily supports Jumbo frames.
- If you are using a firewall please make sure that your firewall settings allow communication with the camera for discovery, control and streaming, depending on your used transport layer. For Windows the easiest way to do this is to allow the application (i.e. HDevelop, or your compiled application) at the firewall.
- GenICam version 2.3.1 . The corresponding files are part of the HALCON runtime installation and are located in the directory genicam within the HALCON base directory %HALCONROOT%. Since the HALCON GenICamTL interface sets all necessary environment variables on its own, no environment variables like GENICAM_ROOT_V2_x, PATH, LD_LIBRARY_PATH must be set or modified. Old variables referencing GenICam V1.1, V2.0 or V2.1 are not used anymore and should be deleted if not needed by other software. See section GenICam GenApi for more details.
- Windows:
HALCON image acquisition interface hAcqGenICamTL.dll or
hAcqGenICamTLxl.dll, respectively.
If you have properly installed the interface, all these DLLs should
reside in bin\%HALCONARCH% within the HALCON base directory
%HALCONROOT% you have chosen during the installation of HALCON.
Linux: HALCON image acquisition interface hAcqGenICamTL.so or hAcqGenICamTLxl.so, respectively. If you have properly installed the interface, the shared objects should reside in lib/$HALCONARCH within the HALCON base directory $HALCONROOT you have chosen during the installation of HALCON.
OS X: HALCON image acquisition interface hAcqGenICamTL.dylib or hAcqGenICamTLxl.dylib, respectively. If you have properly installed the interface, the shared objects should reside in the HALCON framework /Library/Frameworks/HALCON.framework or the HALCON XL framework /Library/Frameworks/HALCONxl.framework in the Libraries subdirectory. - The default acquisition mode assumes the computer is fast enough to process all buffers from the camera. If this is not the case, they are silently discarded (by the GenTL Producer).
Environment Variables
- GENICAM_GENTL32_PATH, GENICAM_GENTL64_PATH are standard GenTL variables holding the list of directories where individual GenTL Producers are installed. The installer of a GenTL producer usually adapts these variables automatically. Alternatively you can specify the full path to the producer when opening the device.
- HALCON_ACQUIRED_FILE_PAYLOAD_DIR is used to specify the directory where non-image payload types (usually files or 'raw' data) are stored using the filename given by the device or GenTL Producer.
- When specifying a directory with HALCON_GENICAM_WRITE_XMLFILE and/or HALCON_GENICAM_WRITE_RAW_XMLFILE, the GenICam description files (in XML and/or raw format) will be stored there while working with HALCON. These files can also be stored by setting the interface parameter 'do_write_configuration'.
- If you want to use an already installed GenApi version instead of the one supplied with HALCON, you must set the environment variable HALCON_USE_EXTERNAL_GENAPI. Additionally, all environment variables which are necessary for GenApi must also be set in this case. This is only for experts, see also section GenICam GenApi.
Features
- Implementation of a GenICam GenTL consumer.
- Grabbing from multiple cameras.
- Flexible device lookup and connection options.
- Synchronous and asynchronous grabbing.
- Software control of all generic camera parameters using GenApi.
- Software control of all generic GenTL Producer parameters using GenApi.
- Support of various pixel formats and flexible color transformation.
- Support of 'Continuous', 'MultiFrame' and 'SingleFrame' acquisition modes.
- Support of GenICam chunk data.
- Support of GenICam event data.
- Support of callbacks for feature change notifications.
- Support of non-streamable devices.
Limitations
- No support of BayerXXPacked, BGRXXPlanar, and RGBXXPlanar pixel formats yet.
- Simultaneous acquisition from multiple data streams of the same device is currently not possible.
- No support of acquisition from devices with read-only access mode
- Limited support for devices with multiple ROI functionality.
GenICam GenApi
- This interface uses GenApi version 2.3.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 GenICamTL interface sets all necessary environment
variables on its own and ignores other installed GenICam
packages by default.
If you want to use another GenICam package, you need to set the environment variable HALCON_USE_EXTERNAL_GENAPI. This skips the step of setting all necessary variables and paths internally, so you have to make sure they are set correctly. Please note that it might not be possible to use different GenApi versions with different interfaces at the same time and that you must use the required GenApi version for this interface. - The caching of device XML files is activated to speed up processing, Windows uses %TEMP% and Linux/OS X use $TMP or /tmp if $TMP is not set for cached XML files.
GenICam GenTL
- GenTL is part of the GenICam standard and allows generic communication between a GenTL consumer like the HALCON GenICamTL acquisition interface which is independent of specific transport layers and hardware, and one or more GenTL producers which implement access to the specific device hardware (usually a camera).
- GenTL producers are usually provided by the device manufacturer. They implement the communication with the device regarding control and data streaming (images) and present it in a uniform way to a GenTL consumer. The consumer uses GenApi to access and control the device features.
- The available GenICam GenTL Producers are searched within the path set by the environment variable GENICAM_GENTL32_PATH or GENICAM_GENTL64_PATH, respectively. If none of these variables is set, the full path to the GenTL producer has to be specified (see Identifying and opening a device).
Identifying and Opening a Device
- 'producer' - the name of the GenTL Producer which is used to access the device.
- 'interface' - the name of the (logical) interface where the device is connected. For example an Ethernet based GenTL Producer running on a system with multiple network cards might present the IP or MAC address of the network card where the device is connected as interface name.
- 'device' - the name of the device (typically camera). Note that a device might be accessible through multiple producers or interfaces and might therefore also be shown with different (hopefully similar) names.
- 'stream' - the name of each data stream of the device. Currently only devices with no stream (peripherals) or a single (image) data stream are fully supported, therefore this is not yet used.
The result of info_framegrabber can be passed directly to open_framegrabber. Alternatively you can specify the device directly. For this one or more of the entries can be omitted (or specified as 'default') - which is like using wildcards, meaning that the particular ID for that entity should not be considered (any ID would match). The HALCON acquisition interface will walk the GenTL device tree (producer -> interface -> device -> stream), until it finds an exact match for all non-default entries.
The values for the individual entries are evaluated as follows for open_framegrabber:
- 'producer': The value is interpreted as filename of the GenTL Producer (always a file with .cti extension). If it is specified using the full path, it's opened directly. If only a filename without path is specified, the GenTL installation directories (specified via GENICAM_GENTL32_PATH respectively GENICAM_GENTL64_PATH) are searched. If the entry is 'default' or omitted, any GenTL Producer found within the GenTL installation directories would match.
- 'interface': The value is interpreted as GenTL interface ID (string identifier assigned to the interface by GenTL producer). When 'default' or omitted, any interface would match.
- 'device': GenTL device ID (string identifier assigned by GenTL producer). When 'default' or omitted, any device would match, but only a device that is currently reported as accessible by the GenTL producer, non-accessible devices are skipped.
- 'stream': GenTL data stream ID. When 'default' or omitted, the first data stream reported for given device is used.
Alternative IDs:
- In addition to the GenTL device ID, devices can be opened by their user-defined name ('DeviceUserID') if the device supports it. If set, the string obtained by info_framegrabber will contain the entry 'user_name:<user-defined name>'. To make it easier for the user, the 'device' entry reflects the user-defined name if it is unique. If the same user-defined name is assigned to more than one device, only the first one will use it, all others will use the unique name instead.
- Some devices might (optionally) allow identifying the interfaces and/or devices using other strings than the GenTL IDs. This might be for example the device's MAC or IP address, serial number or similar. If a GenTL producer supports this, alternative IDs can be used also when opening devices.
- The GenICamTL interface has to maintain reference counting of the opened producers, interfaces and devices. This is based on GenTL IDs; if using alternative IDs it might be possible that the reference counting does not work properly. We therefore recommend to use either always GenTL IDs or always alternative IDs.
Selection of GenICam Feature Description File(s)
- Features of the connected device (in GenTL terminology "remote device"), typically a camera, are usually loaded directly from the connected device.
- Features of the GenTL Producer, potentially one for each
(so called) GenTL module which corresponds to a node in the GenTL device
tree to the connected device:
- The "system", in GenTL terminology representing the overall behavior of the GenTL Producer itself.
- The "interface" which is used to connect (logically) the device to the system.
- The "device" (also "local device") which is a kind of proxy device, controlling the GenTL producer's view of the device.
- The "data stream" used for the acquisition (if the device provides any data streams).
RemoteFile=%PATH_TO_GENICAM_FILE_OF_THE_DEVICE% SystemFile=%PATH_TO_GENICAM_FILE_OF_GENTL_SYSTEM_MODULE% InterfaceFile=%PATH_TO_GENICAM_FILE_OF_GENTL_INTERFACE_MODULE% DeviceFile=%PATH_TO_GENICAM_FILE_OF_GENTL_DEVICE_MODULE% StreamFile=%PATH_TO_GENICAM_FILE_OF_GENTL_STREAM_MODULE%The same ini-file format can be reused to force the HALCON acquisition interface to load an alternative XML file for one or more of these entities. This can be useful, e.g., for updates or troubleshooting. The files listed in the ini file will be used for the given entity instead of the original ones. For the entities excluded from the ini file, the GenICam description file will be searched and loaded the usual way. To apply the ini file, pass its full path to open_framegrabber in the 'CameraType' parameter.
Parameters – Naming Conventions
- Internal parameters of the HALCON GenICamTL image acquisition interface itself. These are named following the "underscore" naming style, e.g., color_space, and are all lowercase.
- GenICam-based parameters of the (remote) device, usually a camera, use by convention the "CamelCase" style, e.g., ExposureTime.
- GenICam-based parameters of the individual GenTL Producer
modules (system, interface, device and data stream) use by convention
the same style but are prefixed with the module name in square brackets.
Beware that the system and interface modules might potentially be shared by
multiple opened devices, so changing their configuration might have side
effects on other connections as well. The following prefixes are used:
- "[System]", e.g., [System]TLVendorName.
- "[Interface]", e.g., [Interface]InterfaceType.
- "[Device]", e.g., [Device]DeviceID.
- "[Stream]", e.g., [Stream]StreamBufferHandlingMode.
Parameters – GenICam Data Types
- integer – signed integer, 64-bit on 64-bit platforms, 32-bit on 32-bit ones
- real – floating point type
- string – classical string
- IInteger – integer value, mapped directly to HALCON's integer parameter type. It will also accept real parameters and when the GenICam feature in question is identified to be an IP or MAC address, the string representation of the address will also be accepted. It should be highlighted that a problem can occur when running HALCON on a 32-bit platform (where integer parameters are 32-bit wide) and accessing a GenICam feature that is naturally 64-bit. In such cases the full range of the feature will not be available to the application and its value might be truncated. Also the sign of the parameter might be misinterpreted. To solve this problem, the parameter 'split_param_values_into_dwords' can be used. This maps the 64-bit IInteger value into two 32-bit integer values and vice versa.
- IFloat – floating point value, mapped directly to HALCON's real parameter type. It will also accept integer parameters.
- IString – string value, mapped directly to HALCON's string parameter type.
- IBoolean – boolean type is handled through HALCON's integer parameters, a value of 0 (zero) means logical false, other values mean logical true.
- IEnumeration – enumeration is a type that allows selecting from a set of values that are primarily identified by their name (the values are called 'enum entries'). Enumerations are interfaced through HALCON's string parameter type, while the enum entry names are used as the parameter values.
- ICommand – The command type allows to "execute" actions. To execute a command, use set_framegrabber_param with an integer parameter of any value (the value is ignored). Some commands' execution might take longer time and the command provides feedback when it is done. To query the status, use get_framegrabber_param for that command. It will return an integer value of 1 if it "is done" (command execution has finished), 0 if it has not finished yet. Note that if some other features are designed to be dependent on the command, querying the "is done" status might be essential to get the depending features invalidated (and updated with new values) as soon as the command execution finishes.
- IRegister – The register data type is used for plain memory blobs that cannot be mapped to any other data type. They are interfaced through HALCON's string parameter type, the register value is the hexadecimal string representation of the register's memory.
Parameters – Persisting Device Status
Note that while the format of the file is intentionally human readable and the file can be hand-modified if desired, such modifications should be done with care by someone familiar with the GenICam persistence functionality internals and given device. Improper modifications of the file can lead to errors when using it.
It is important to know that while performed by the software, the feature settings persistence is actually a camera-side function. If the persistence support is implemented incorrectly or incompletely by the device, it will not work as expected – in such a case the camera manufacturer could provide additional information or help.
The same persistence file can be applied to the entire set of devices of the same type and firmware version. Applying the persistence file to a device of another type or using even different firmware version will probably lead to inconsistencies or will even fail completely – the corresponding device manufacturer should provide guidelines for such use cases.
Apart from the 'do_write_settings', the feature persistence file will also be written together with the ini file documented in the section Selection of GenICam Feature Description File(s). The persistence file entry in the ini file will have the format RemotePersistence=%PATH_TO_PERSISTENCE_FILE_OF_THE_DEVICE%
If the persistence functionality is not supported properly (or at all) by a given device, use the GenICam features UserSetSave/UserSetLoad, if supported by the device. These features will allow to store/load the device settings in the device's non-volatile memory.
Acquisition – Overview, Device Control
The interface fully configures and controls the acquisition process on the camera and GenTL producer. Note that some of the camera or producer features might be locked by GenICam when an acquisition is active.
With synchronous grab (grab_image), 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 calls, all acquisition related features remain unlocked.
With asynchronous grabbing, started explicitly by grab_image_start or implicitly by grab_image_async, the interface keeps the acquisition running internally, collecting further images to be delivered through future grab_image_async calls. The acquisition related features are locked, until the acquisition is stopped using set_framegrabber_param(..., 'do_abort_grab', ...).
Note that the interface properly recognizes the 'Continuous', 'SingleFrame' and 'MultiFrame' acquisition modes configured on the device and adjusts the acquisition control logic accordingly.
Note that the HALCON acquisition interface itself takes over exclusive access to several remote device features essential for the acquisition control (AcquisitionStart, AcquisitionStop, AcquisitionAbort, TLParamsLocked). The user application has no direct way to control these features.
Acquisition – Buffer Handling
Whenever a new image is acquired successfully and passed to the application as a HALCON image, the interface keeps the buffer locked (not returning it to the acquisition engine) until a new grab-related operator is called by the application or the acquisition is aborted using set_framegrabber_param(..., 'do_abort_grab', ...). During this period, it is fully safe to query information about this "last acquired" buffer – for example query buffer properties through get_framegrabber_param parameters such as 'buffer_timestamp', 'buffer_is_incomplete', 'image_width' and 'image_height'. 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.
Acquisition – Image Format Handling
The HALCON GenICamTL image acquisition interface fully supports these use cases. It checks the image format and other important properties of every single buffer and generates HALCON images corresponding to both the acquired image format and eventual user configured output format parameters such as 'color_space' and 'bits_per_channel'. Only if the necessary information about the buffer are missing (i.e., the GenTL Producer does not support it) , the current settings are used as a fallback.
Raw Output Format – Custom Pixel Formats, Non-image Buffers
To offer a basic support of custom pixel formats (i.e., pixel formats not defined by SFNC or not supported by HALCON), the ColorSpace value 'raw' can be used. In this case the image acquisition interface delivers the buffer to the application without any format conversions.
Note that the same principle is applied whenever a buffer containing other than image data is acquired. Examples of such buffers can be files (e.g., compressed images) or raw data (results of smart camera processing). Such buffers are not real "images", but can still be delivered to the application as 'raw' HALCON images. It is the responsibility of the application to know how to interpret such data.
Last but not least, the 'raw' color space can also be used if the user explicitly wishes to receive raw input data without any conversions. For example when acquiring Bayer encoded images, specifying 'raw' means that the interface should not attempt to decode them to RGB or monochrome format, but deliver the data directly to the application.
It is important to know that when the interface does not have full information about the image format (dimensions and pixel format), it has to choose an artificial one. In such a case it delivers always an 8-bit image with dimensions matching the buffer size (square root of the image size). Eventually an unused tail of the HALCON image (if such an artificial image is bigger than the source buffer) will be padded with zeroes. The fact whether the last acquired buffer contained an image of known properties or a blob of other data (so that the artificial HALCON image size had to be used) as well as the size of the eventual tail padding can be queried using 'raw_buffer_type' and 'raw_buffer_padding_bytes' parameters.
Chunk Data
The decoding of the chunk data and matching them to the corresponding camera features is performed transparently by the interface.
The actual values might be read through the regular parameter reading mechanism, i.e., get_framegrabber_param. The choice of the meta-data to be delivered is device-specific. The names of the chunk related features usually start by convention with a prefix 'Chunk' (examples might be 'ChunkExposureTime' or 'ChunkGain'), however, the camera documentation should contain all the information about supported chunks and their corresponding feature names.
It is important to remember, that the chunk data related features will provide only meaningful values if the "last acquired buffer" is valid, i.e., between delivery of the last image and next call to any grab-related operator (refer to section Acquisition – Buffer Handling).
Feature Change Notifications (Callbacks)
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.
The notification callbacks can be registered for individual features using set_framegrabber_callback - see corresponding operator documentation.
Event Data
The decoding of the event data and matching them to the corresponding features, including eventual notifications, 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 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, 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 notifications just for one of them and read all the data during the callback.
Using HDevelop Image Acquisition Assistant
- Some parameters depend on special conditions, e.g., a valid buffer or another parameter activated. After opening the camera these conditions may not yet be fulfilled, so the depending parameters are not shown. By using the 'Refresh' button, all parameters are read again and the depending parameters should appear if the conditions are fulfilled then.
- There are also some parameters regarding the image size and the payload size, which can only be changed if no acquisition takes place. The safest way to ensure this is to apply the action parameter 'do_abort_grab'. Please note that 'Update Image' has to be disabled first.
- The behavior of allowing changes to parameters while streaming is active depends on the capabilities of the device. It is possible that some cameras give you control over, e.g., the exposure time, while streaming and others do not.
Using internal color conversion
The formula to convert Bayer to RGB is this:
R G1 => R,G',B R,G',B
G2 B R,G',B R,G',B
where G' = (G1 + G2) / 2.
R = Y' + 1.4020 * (Cr'- 128)
G = Y' - 0.34414 * (Cb'- 128) -0.71414 * (Cr'- 128)
B = Y' + 1.7720 * (Cb' - 128)
Y' = 0.299 * R + 0.587 * G + 0.114 * B
Cb' = -0.16874 * R - 0.33126 * G + 0.5 * B + 128
Cr' = 0.5 * R + 0.41869 * G + 0.08131 * B + 128
To convert RGB to gray the same formula as converting RGB to YUV is used, but only Y' will be calculated.
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:<cti file including path>'] | string | dynamic | List of GenTL devices discovered in the system with information about their device ID, unique name, user-defined name, interface ID and path to the GenTL Producer file. See the full description in section about device opening. Only devices that are currently available for opening are listed. |
'external_trigger' | [] | Ignored. | ||
'field' | [] | Unused. | ||
'general' | [] | string | pre-defined | Information about the HALCON GenICamTL interface. |
'generic' | ['', 'num_buffers=<num>', 'device_access=<mode>', 'direct_connection=<mode>', 'streaming_mode=0', 'device_event_handling=0', 'workarounds=<list>'] | string | pre-defined | Value list for the Generic parameter. |
'horizontal_resolution' | [0, 1] | integer | pre-defined | Value list for horizontal resolution. |
'image_height' | [] | Unsupported query. | ||
'image_width' | [] | Unsupported query. | ||
'info_boards' | [' | device:<device id> | unique_name:<unique name> | user_name:<user-defined name> | interface:<interface id> | producer:<cti file including path> | vendor:<device vendor> | model:<device model> | status:<device status>'] | string | dynamic | List of GenTL devices discovered in the system with information about their device ID, unique name, user-defined name, interface ID, path to the GenTL Producer file, device vendor and model name and device status ('available', 'read-only', 'busy', 'unknown'). Even devices that are currently not available for opening are listed. |
'parameters' | ['<parameters>'] | string | pre-defined | Pre-defined parameters of the HALCON interface. |
'parameters_readonly' | ['<parameters>'] | string | pre-defined | Pre-defined read-only parameters of the HALCON interface. |
'parameters_writeonly' | ['<parameters>'] | string | pre-defined | Pre-defined write-only parameters of the HALCON interface. |
'port' | [] | Unused. | ||
'revision' | '<revision>' | string | pre-defined | Revision number of the GenICamTL interface. |
'start_column' | [] | Unsupported query. | ||
'start_row' | [] | Unsupported query. | ||
'vertical_resolution' | [0, 1] | integer | pre-defined | Value list for vertical resolution. |
Parameters for open_framegrabber
Parameter | Values | Default | Type | Description |
---|---|---|---|---|
Name | 'GenICamTL' | string | Name of the HALCON interface. | |
HorizontalResolution | 0, 1, resolution | 1 | integer | Set the desired horizontal resolution of the camera image:
|
VerticalResolution | 0, 1, resolution | 1 | integer | Set the desired vertical resolution of the camera image:
|
ImageWidth | --- | 0 | Ignored. | |
ImageHeight | --- | 0 | Ignored. | |
StartRow | --- | 0 | Ignored. Configure the image size through device parameters. | |
StartColumn | --- | 0 | Ignored. Configure the image size through device parameters. | |
Field | --- | Ignored. | ||
BitsPerChannel | -1, 8, 10, 12, 14, 16 | -1 | integer | Number of bits per channel of the resulting HALCON image. In case of -1 the bit depth of each respective acquired buffer is used. By specifying a value greater than 8 the grabbed images are delivered as uint2 images. |
ColorSpace | 'default', 'gray', 'raw', 'rgb', 'yuv' | 'default' | string | Specify the desired color space and thus the number of image channels of the resulting HALCON image. In case of 'default' for Mono pixel formats, ColorSpace is set to 'gray', otherwise to 'rgb' (and for unknown pixel formats to 'raw'). |
Generic | '', ['num_buffers=<num>', 'device_access=<mode>', 'direct_connection=<mode>', 'streaming_mode=0', 'device_event_handling=0', 'workarounds=<list>'], -1 | -1 | mixed | With the Generic parameter some important values can be set before the camera is initialized. Note that the parameter names including the values
must be strings, e.g., 'num_buffers=5' sets the number of buffers to 5. The following parameters are available:
|
ExternalTrigger | --- | Ignored. To configure the trigger mode please use set_framegrabber_param with the generic (SFNC) trigger parameters of the camera. | ||
CameraType | 'default', <ini/xml filename> | 'default' | string | Full path to the configuration file with the specification of alternative GenICam description files to be loaded for the device and GenTL Producer, see detailed description in section about device opening. |
Device | ' | device:<device id> | unique_name:<unique name> | user_name:<user-defined name> | interface:<interface id> | producer:<cti file (including path)> | stream:<stream id>', '<device id>' | string | To open a camera, the device name as shown in info_framegrabber(...'device'...) or info_framegrabber(...'info_boards'...) can be used. Some of the string entries might be skipped or set as 'default'. To open a specific camera, either device or unique_name has to be set. Additionally, the ID of the device's data stream to be used for acquisition might be specified. As a shortcut, only the device ID or user-defined name might be specified or the string 'default' can be used. See full description in section about device opening. | |
Port | --- | Unused. | ||
LineIn | --- | Ignored. |
Parameters for set_framegrabber_param
To set e.g. the current gain of the camera AcqHandle refers to (after calling open_framegrabber), the user can call set_framegrabber_param(AcqHandle, 'Gain', 6.0).
Please note that the interface sets the value of a parameter only if the value is valid. Integer and float values not matching the allowed range for given feature are aligned to the closest valid value. Invalid values of other feature types are refused.
Additionally to the GenICam parameters of the camera and of the GenTL Producer, the following HALCON interface parameters are supported by set_framegrabber_param:
Parameter | Values | Default | Type | Description |
---|---|---|---|---|
'bits_per_channel' | -1, 8, 10, 12, 14, 16 | integer | Number of bits per channel of the resulting HALCON image. In case of -1 the bit depth of each respective acquired buffer is used. By specifying a value greater than 8 the grabbed images are delivered as uint2 images. | |
'buffer_reallocation_mode' | 'only_increase_size', 'follow_payloadsize' | 'only_increase_size' | string | Defines the strategy to follow when reallocating the buffers for a new acquisition. In case of 'only_increase_size', the buffers will be only reallocated when the payload size increases. In case of 'follow_payloadsize', the buffers will be reallocated every time the payload size changes. |
'clear_buffer' | 'disable', 'enable' | 'disable' | string | If enabled, each buffer content is cleared before re-queueing (all bytes set to 0xF0 regardless the expected pixel format), so you can see which parts of an image are missing, in case e.g. the transfer of some image packets failed. This parameter adds of course an runtime overhead to write the 0xF0 data every time a buffer is queued. It is mainly useful for debugging in combination with transport layers which do not guarantee the transfer of complete images. Please note, that this parameter does not modify the buffer queue, only the content of a buffer will be set to a defined state. |
'color_space' | 'default', 'gray', 'raw', 'rgb', 'yuv' | string | Specify the desired color space and thus the number of image channels of the resulting HALCON image. In case of 'default' for Mono pixel formats, ColorSpace is set to 'gray', otherwise to 'rgb' (and for unknown pixel formats to 'raw'). | |
'delay_after_stop' | <milliseconds> | 0 | integer | The time to wait (in milliseconds) between stopping the acquisition on the device (AcquisitionStop command) and GenTL Producer. The optimal value depends on the speed of the used device and extra safety required by the GenTL Producer. With a robust GenTL Producer, no delay should be needed. |
'do_abort_grab' | --- | Aborts the current image acquisition and unlocks parameters, that might be locked when acquisition is active. See acquisition overview. | ||
'do_load_settings' | <input_file> | string | Restores the previously stored settings of the opened device. See detailed description in section Parameters - Persisting Device Status. | |
'do_write_configuration' | <output_directory> | string | Writes a configuration (ini) file specified with full path through the string parameter value. Writes also GenICam description files of the remote device and each GenTL Producer module associated with currently opened device. The GenICam description files are written to the same directory as the ini file itself. The written ini file contains in particular paths to the written GenICam description files and can be reused through the 'CameraType' parameter of open_framegrabber operator, see detailed description in section about device opening. Instead of specifying the path of the output ini file, 'default' or an empty string can be used. In this case the files will be written to the %TEMP% directory and the filename of the configuration file will be halcon_gentl_config.ini. Note that this default option will apply also when using the Image Acquisition Assistant. | |
'do_write_settings' | <output_directory> | string | Writes the current settings of the opened device to be able to restore the settings later. See detailed description in section Parameters - Persisting Device Status. | |
'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. Caution: This is a dangerous function intended for debugging and special cases. Usually only features in the XML should be used. | ||
'split_param_values_into_dwords' | 'disable', 'enable' | 'disable' | string | Enables a special mode allowing the treatment of integer parameters as tuple of two 32-bit integers. For compatibility with the single-parameter mode, the first tuple element carries always the low 32-bit part of the value, second element carries the high 32-bit part. It is user's responsibility to combine the two parts correctly. This mode is intended especially to help to overcome the problem of 32-bit HALCON featuring only 32-bit integer parameters but having to face up to 64-bit wide GenICam features. In this mode, the get_framegrabber_param returns always a tuple of two integers, set_framegrabber_param accepts both a single parameter or a tuple. Note that this mode affects only integer parameters and only the GenICam based ones, not the internal parameters of HALCON GenICamTL image acquisition interface - with one exception, the 'buffer_timestamp' internal parameter. |
'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
- '_access': These parameters provide the access permissions of the corresponding parameter as a string. Possible values are 'ro' (read-only), 'wo' (write-only), and 'rw' (read/write).
- '_category': These parameters provide the category of the corresponding parameter as a string.
- '_description': These parameters provide the tool-tip of the corresponding parameter as a string.
- '_displayname': These parameters provide the displayname of the corresponding parameter as a string.
- '_longdescription': These parameters provide the description of the corresponding parameter as a string.
- '_range': These parameters provide the minimum, maximum, step width, and current values for the corresponding integer or float parameter as a tuple with 4 elements, e.g., get_framegrabber_param(.., 'Shutter_range', ..) will return the output tuple [min, max, step, current].
- '_type': These parameters provide the type of the corresponding parameter as string.
- '_values': These parameters provide the valid value list for the corresponding parameter as a tuple, e.g., get_framegrabber_param(.., 'volatile_values', ..) will return the output tuple ['enable', 'disable'].
- '_visibility': These parameters provide the visibility of the corresponding parameter as a string. Possible values are 'beginner', 'expert', and 'guru'.
All these postfixed parameter names are not returned when calling info_framegrabber(.., 'parameters', ..) and are used to enable the easy parameterization via a generic graphical user interface, particularly the HDevelop Image Acquisition Assistant.
Parameter | Values | Default | Type | Kind | Description |
---|---|---|---|---|---|
'available_callback_types' | ['<callback_types>'] | string | dynamic | Returns a list containing all parameters, for which a callback can be registered. This includes all parameters published by the device and GenTL Producer via the GenICam interface, including those temporarily unavailable, because availability change might be coupled with the callback. | |
'available_param_names' | ['<names>'] | string | dynamic | Returns a list containing all available parameters, i.e. those used by the HALCON GenICamTL image acquisition interface and those published by the device and GenTL Producer via the GenICam interface (see parameter naming conventions). Note that availability of some parameters might depend on acquisition status, values of other parameters or other conditions, so the list dynamically changes during runtime. | |
'bits_per_channel' | -1, 8, 10, 12, 14, 16 | -1 | integer | pre-defined | Number of bits per channel of the resulting HALCON image. In case of -1 the bit depth of each respective acquired buffer is used. By specifying a value greater than 8 the grabbed images are delivered as uint2 images. |
'buffer_is_incomplete' | 0, 1 | integer | dynamic | Shows if the last grabbed image is incomplete (e.g. due to lost packets). See acquisition buffer handling. DSGetBufferInfo -> BUFFER_INFO_IS_INCOMPLETE | |
'buffer_reallocation_mode' | 'only_increase_size', 'follow_payloadsize' | 'only_increase_size' | string | pre-defined | Defines the strategy to follow when reallocating the buffers for a new acquisition. In case of 'only_increase_size', the buffers will be only reallocated when the payload size increases. In case of 'follow_payloadsize', the buffers will be reallocated every time the payload size changes. |
'buffer_timestamp' | <timestamp> | integer | dynamic | Timestamp attached to the last grabbed (image) buffer by the device (or GenTL Producer). The unit and actual meaning of the timestamp (when it is generated) is device specific. Note that on 32-bit systems only the lower 32-bit part of up to 64-bit timestamp is delivered (unless 'split_param_values_into_dwords' parameter is enabled). See acquisition buffer handling. DSGetBufferInfo -> BUFFER_INFO_TIMESTAMP | |
'camera_type' | 'default', <ini/xml filename> | 'default' | string | pre-defined | Returns the path to the configuration file used for the CameraType parameter in open_framegrabber. |
'clear_buffer' | 'disable', 'enable' | 'disable' | string | pre-defined | If enabled, each buffer content is cleared before re-queueing (all bytes set to 0xF0 regardless the expected pixel format), so you can see which parts of an image are missing, in case e.g. the transfer of some image packets failed. This parameter adds of course an runtime overhead to write the 0xF0 data every time a buffer is queued. It is mainly useful for debugging in combination with transport layers which do not guarantee the transfer of complete images. Please note, that this parameter does not modify the buffer queue, only the content of a buffer will be set to a defined state. |
'color_space' | 'default', 'gray', 'raw', 'rgb', 'yuv' | 'default' | string | pre-defined | Returns the current color space. |
'delay_after_stop' | <milliseconds> | 0 | integer | pre-defined | The time to wait (in milliseconds) between stopping the acquisition on the device (AcquisitionStop command) and GenTL Producer. The optimal value depends on the speed of the used device and extra safety required by the GenTL Producer. With a robust GenTL Producer, no delay should be needed. |
'device' | ' | device:<device id> | unique_name:<unique name> | user_name:<user-defined name> | interface:<interface id> | producer:<cti file (including path)> | stream:<stream id>', '<device id>' | string | dynamic | Returns the Device parameter string used when opening the device (open_framegrabber). | |
'device_access' | 'exclusive', 'control', 'read-only' | 'exclusive' | string | pre-defined | Value of the device_access generic parameter specified in open_framegrabber. |
'device_event_handling' | 0, 1 | 1 | integer | pre-defined | Value of the device_event_handling generic parameter specified in open_framegrabber. The device_event_handling is by default switched on for devices with event delivery (message channel) support and off for devices without the event capability. The generic parameter device_event_handling explicitly allows switching the event handling functionality off even for devices with event support. |
'direct_connection' | 'disable', 'enable' | 'disable' | string | pre-defined | Value of the direct_connection generic parameter specified in open_framegrabber. |
'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. |
'generic' | '', ['num_buffers=<num>', 'device_access=<mode>', 'direct_connection=<mode>', 'streaming_mode=0', 'device_event_handling=0', 'workarounds=<list>'], -1 | -1 | mixed | pre-defined | Values of the Generic parameter. |
'grab_timeout' | <milliseconds> | 5000 | integer | pre-defined | Current grab timeout in milliseconds. |
'horizontal_resolution' | 0, 1, resolution | 1 | integer | pre-defined | Current value of horizontal resolution. |
'image_available' | 0, 1 | integer | dynamic | Shows if there is currently an image waiting for delivery by the GenTL Producer. DSGetStreamInfo -> STREAM_INFO_NUM_AWAIT_DELIVERY | |
'image_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_width' | <width> | 0 | integer | pre-defined | Width of the last acquired image. See acquisition buffer handling. If there is no valid last buffer available, the last queried value of the 'Width' parameter of the remote device is returned. |
'line_in' | <default> | 0 | integer | pre-defined | The value is not used, so a default value is returned. |
'name' | 'GenICamTL' | string | pre-defined | Name of the HALCON interface. | |
'num_buffers' | <number> | 4 | integer | pre-defined | Number of buffers used for the image acquisition. |
'num_buffers_await_delivery' | <number> | integer | dynamic | Number of (image) buffers waiting for delivery by the GenTL Producer. DSGetStreamInfo -> STREAM_INFO_NUM_AWAIT_DELIVERY | |
'num_buffers_underrun' | <number> | integer | dynamic | Number of lost buffers due to buffer queue underrun since opening the device. Queue underrun occurs when the GenTL Producer has a new image data available, but it has no free buffer to store them. DSGetStreamInfo -> STREAM_INFO_NUM_UNDERRUN | |
'port' | <port> | -1 | integer | pre-defined | The value is not used, so a default value is returned. |
'raw_buffer_padding_bytes' | 0 | integer | pre-defined | For raw buffers of type 'blob' (see 'raw_buffer_type') reports the size of unused padding bytes at the end of such grabbed HALCON image. Because artificial dimensions need to be chosen for the resulting HALCON image in this case, the size of such image might not exactly equal the size of the buffer data and thus the padding might be needed. Zero is reported for buffers of type 'image'. Applies only in case of the 'raw' color format. See raw output format chapter. | |
'raw_buffer_type' | 'image', 'blob' | 0 | string | pre-defined | Shows whether the last grabbed HALCON image is created from buffer containing real image data with known properties (in particular image size and pixel format) or if it is created from a blob of other data (non-image data or image data of unknown format). Note that in case of the blob data the dimensions of the HALCON image are meaningless. Applies mainly in case of the 'raw' color format. Possible values are 'image' and 'blob'. See raw output format chapter. |
'register_<addr>_<len>' | integer | pre-defined | Direct register access for reading and writing integers. Caution: This is a dangerous function intended for debugging and special cases. Usually only features in the XML should be used. | ||
'revision' | '<revision>' | string | pre-defined | Revision number of the GenICamTL interface. | |
'split_param_values_into_dwords' | 'disable', 'enable' | 'disable' | string | pre-defined | Enables a special mode allowing the treatment of integer parameters as tuple of two 32-bit integers. For compatibility with the single-parameter mode, the first tuple element carries always the low 32-bit part of the value, second element carries the high 32-bit part. It is user's responsibility to combine the two parts correctly. This mode is intended especially to help to overcome the problem of 32-bit HALCON featuring only 32-bit integer parameters but having to face up to 64-bit wide GenICam features. In this mode, the get_framegrabber_param returns always a tuple of two integers, set_framegrabber_param accepts both a single parameter or a tuple. Note that this mode affects only integer parameters and only the GenICam based ones, not the internal parameters of HALCON GenICamTL image acquisition interface - with one exception, the 'buffer_timestamp' internal parameter. |
'start_async_after_grab_async' | 'disable', 'enable' | 'enable' | string | pre-defined | Status of 'start_async_after_grab_async'. |
'start_column' | <column> | 0 | integer | pre-defined | Unsupported, returns always 0. |
'start_row' | <row> | 0 | integer | pre-defined | Unsupported, returns always 0. |
'streaming_mode' | 0, 1 | 1 | integer | pre-defined | Value of the streaming_mode generic parameter specified in open_framegrabber. The streaming_mode is by default switched on for devices with streaming support and off for peripheral devices (devices without any data streams). The generic parameter streaming_mode explicitly allows switching the streaming functionality off, even for devices with streaming support. |
'tl_displayname' | '<name>' | string | dynamic | Human-readable name of the used GenTL Producer. TLGetInfo -> TL_INFO_DISPLAYNAME | |
'tl_filename' | '<file name>' | string | pre-defined | File name of the used GenTL Producer. TLGetInfo -> TL_INFO_NAME | |
'tl_id' | '<id>' | string | dynamic | Unique identifier of the used GenTL Producer. TLGetInfo -> TL_INFO_ID | |
'tl_model' | '<model name>' | string | dynamic | Name of the used GenTL Producer to distinguish different kinds of GenTL Producer implementations from one vendor. TLGetInfo -> TL_INFO_MODEL | |
'tl_pathname' | '<path name>' | string | pre-defined | Full path of the used GenTL Producer. TLGetInfo -> TL_INFO_PATHNAME | |
'vertical_resolution' | 0, 1, resolution | 1 | integer | pre-defined | Current value of vertical resolution. |
'volatile' | 'disable', 'enable' | 'disable' | string | pre-defined | Current value of the volatile mode. |
'workarounds' | ['', 'enable_range_validation' , 'buffer_alloc_by_consumer' , 'ignore_buffer_pixelformat' ] | '' | string | pre-defined | List of workarounds enabled by the 'workarounds' generic parameter in open_framegrabber. Individual workaround names are separated by spaces. |
Operator set_framegrabber_lut
Operator get_framegrabber_lut
Operator set_framegrabber_callback
The callback can be registered for any GenICam based features, i.e., features published by the device and GenTL Producer through the GenICam description files. The list of supported callback targets can be queried by calling get_framegrabber_param(..., 'available_callback_types', ...).
One of the important use cases for feature change callbacks is the device event delivery mechanism, see details in event data and feature notifications sections. The 'CallbackType' parameter of set_framegrabber_callback defines the feature for which the callback is registered. It is the same plain feature name as used with set_framegrabber_param, including a possible prefix, such as '[Device]' (refer to the parameter naming convention).
The registered callback function would be called whenever a given feature is potentially changed (including its other properties such as range or access mode). Note that it does not necessarily always mean that the feature actually has a new value. If the callback function is set to NULL, the corresponding callback will be unregistered. Note that the interface keeps just a single registration for every feature, if you attempt to register a new callback for a feature that already had a callback registered, the previous registration will be replaced with the new one.
The signature of the callback function is Herror (__stdcall *HAcqCallback)(void *AcqHandle, void *Context, void *UserContext) and uses the following parameters:
- AcqHandle: Acquisition handle of the corresponding image acquisition instance.
- Context: Optional context data of the specific callback. Up to now, this parameter is not used, i.e., Context is set to NULL.
- UserContext: Optional context data of the specific callback. Up to now, this parameter is not used, i.e., UserContext is set to NULL.
Note that the execution time of a user-specific callback function must always be as short as possible since during the execution of a callback function the handling of further internal callbacks might be blocked. This can be achieved by removing the current processing from the user-specific callback function to a separate thread that is controlled via signals or events. The callback function is executed in the context of the underlying interface or driver.
Operator get_framegrabber_callback
Operator grab_image_start
Operator grab_image
Operator grab_image_async
The 'MaxDelay' parameter of the grab_image_async operator is ignored by the HALCON GenICamTL acquisition interface, because there is no way to support it reliably across all GenTL producers . If needed, the application needs to implement alternative functionality on its own.
Operator grab_data
Operator grab_data_async
Operator close_framegrabber
HDevelop Examples
- genicamtl.hdev - Benchmark.
- genicamtl_parameters.hdev - Lists all parameters of a device.
- genicamtl_simple.hdev - A simple example to show the usage of the interface.
- genicamtl_areascan3d_objectmodel3d.hdev - Example for the usage of the VRmagic AreaScan3D calibrated 3D area sensor.
- genicamtl_gocator_objectmodel3d.hdev - Example for the usage of the LMI Gocator calibrated 3D sensor.
Troubleshooting
General:
- Check if the latest revision of the HALCON GenICamTL interface is used.
- Check the System Requirements.
- Check for a newer version of the used GenICam GenTL Producer.
- Check if the device has the latest firmware.
- Enable low-level error messages in HALCON to query more information about the problem (and check the output console in HDevelop if applicable). 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.
The following information is needed for your support request to avoid unnecessary inquiries.
- Used HALCON and acquisition interface versions.
- Used HALCON architecture (especially 32 or 64 bit).
- Low-level error messages if there are any.
- Camera manufacturer, model and firmware version.
- Details about the used GenICam GenTL Producer (at least name and version).
- Details about computer system, like operating system, RAM and CPU.
- Minimal sample code (e.g. HDevelop script) to reproduce the issue.
- Description of observed and expected behavior.
Release Notes
- Revision 5.13 (May 13, 2016):
- Under Windows, open_framegrabber crashed if the environment variable PATH was empty. This problem has been fixed.
- Improved support for linescan cameras by querying the delivered image height for buffers first (if it is available). This also enables the use of producers for linescan cameras which do not properly update the buffer height.
- Revision 5.12 (Feb 15, 2016):
- Added support for the 'Mono10p' and 'Mono12p' pixel formats.
- Added paragraph 'Using internal color conversion' to this document.
- 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 5.11 (Oct 30, 2015):
- 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.
- 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 5.10 (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 genicamtl_parameters.hdev has been improved.
- The HDevelop example genicamtl_gocator_objectmodel3d.hdev has been adapted to Gocator GenTL Driver version 4.x. Now X-Y-Z offset and X-Y-Z resolution are in nanometer. Moreover the TransformationZOffset is now correctly interpreted.
- Revision 5.9 (Feb 26, 2015):
- Aligned consumer with GenTL v1.4 specification.
- Added support for buffer handling modes 'OldestFirstOverwrite' and 'NewestOnly', this needs to be supported by the producer.
- 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.
- 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.8 (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'.
- Revision 5.7 (Jan 31, 2014):
- Fixed crash when trying to execute GenICam commands without parameter.
- Fixed crash when trying to use volatile mode.
- Improved robustness by guarding more calls with exception handling.
- Added support for PFNC pixel format namespace. Please note that no additional conversion routines have been implemented.
- New parameter 'register_<addr>_<len>' for direct register access.
- Added parameters 'do_write_settings' and 'do_load_settings' to write and load GenICam persistence settings. The parameters 'do_write_configuration' and 'do_load_configuration' also support GenICam persistence now.
- Switching of 'color_space' parameter values now has immediate effect.
- Extended documentation of 'streaming_mode' and 'clear_buffer' parameters.
- Renamed environment variables:
HALCON_GENTL_WRITE_XMLFILE -> HALCON_GENICAM_WRITE_XMLFILE
HALCON_GENTL_WRITE_RAW_XMLFILE -> HALCON_GENICAM_WRITE_RAW_XMLFILE
HALCON_GENTL_FILE_PAYLOAD_DIR -> HALCON_ACQUIRED_FILE_PAYLOAD_DIR
- Revision 5.6 (May 24, 2013):
- The generic parameter 'streaming_mode=0' can now be used with devices which do not provide AcquisitionStart/Stop/Mode features.
- The internal event handling is now more robust regarding a potential race condition when killing events.
- Fixed a crash when info_framegrabber(..., 'info_boards', ...) or info_framegrabber(..., 'device', ...) is called and no device is detected.
- Revision 5.5 (Mar 25, 2013):
- Completely revised the entire interface implementation. Note that backward compatibility is not fully maintained in all cases, in particular some of the parameters are no more supported.
- Improved producer and device detection and added more flexible device opening options.
- Supports parallel open connections to devices from same and/or different GenTL producers.
- Extensive GenICam support including advanced features and parameter types like IRegister. GenICam 64 Bit integers are now supported also on 32 Bit systems.
- Support of GenICam chunk data through get_framegrabber_param, removed grab_data(_async) which provided limited support for chunks in the past. The new implementation keeps the grabbed buffer at runtime until the next grab.
- Support of GenICam events and GenICam event data through callbacks.
- Support of GenICam feature change notifications through callbacks.
- Added 'do_write_configuration' parameter.
- Removed 'callback_timeout' parameter.
- Support of devices changing basic image properties at runtime as well as GenTL producers modifying the image.
- Support of non-image payload types.
- Improved support of unknown image formats as raw data.
- Improved support for reading and writing of GenICam configuration (XML) files.
- Support of devices with known problems with callbacks.
- Adapted documentation.
- Improved LMI Gocator example genicamtl_gocator_objectmodel3d.hdev. Now the Z coordinate is correctly converted to the HALCON camera coordinate system and the example shows how to load a configuration file.
- Fixed documentation of the 'generic' parameter.
- Revision 5.4 (Nov 16, 2012):
- Removed all dependencies on HALCONROOT environment variable.
- Fixed XML loading so devices can be opened even when no manifest is available.
- Revision 5.3 (Oct 22, 2012):
- Use XML with highest schema and version number from manifest.
- Fixed handling of CLProtocol URLs.
- Fixed wrong data size for some DSInfo calls to producer.
- Fixed cancel_mutex locking in case of errors.
- Removed warning messages while registering internal GenApi callbacks.
- Added new example genicamtl_gocator_objectmodel3d.hdev for the usage of the LMI Gocator calibrated 3D sensor.
- Revision 5.2 (Sep 28, 2012):
- Fixed a bug which can lead to a crash when opening some devices while parsing parameters.
- Revision 5.1 (July 11, 2012):
- Updated GenApi to v2.3.1. Please note that therefore also the genicam directory of your HALCON installation will be updated.
- Fixed a problem with the automatic update of the parameters Width, Height, PayloadSize and AcquisitionMode due to incorrect handling of internal GenApi callbacks.
- Added HDevelop example program for the usage of the VRmagic AreaScan3D calibrated 3D area sensor.
- Revision 5.0 (May 15, 2012):
- HALCON 11 version of the interface (included in HALCON 11 DVD).
- Added support for multiple producers at once.
- Added caching for access mode of ports.
- Fixed URL parsing.
- Added missing error checks but also relaxed too strict checks.
- Added more warning messages and revised texts.
- Relaxed GenApi callback registration code.
- Added support for Mac OS X 10.7.
- Use of GenApi v2.3.
- Revision 4.4 (Nov 21, 2011):
- Fixed wrong return value in parameter 'buffer_timestamp' and changed type from integer to string.
- Fixed adding GenICam path to PATH environment variable each time open_framegrabber was called.
- Fixed problem when using more than one device with the same name, but different interfaces.
- Fixed problem with starting the stream each time grab_image or grab_image_async was called.
- Added support of chunk data via the operators grab_data and grab_data_async. Also in this document a section has been added.
- Added functionality to get notified in case of any available device-specific event via user-specific callbacks.
- Added mutex protection for grabbing images.
- Added parameters 'available_callback_types' and 'callback_timeout'.
- Added parameters 'clear_buffer' and 'verify_value'.
- Added generic parameters 'device_access' and 'streaming_mode'.
- Changed info_framegrabber(..'general'..) to static list.
- Changed behavior of grab_image if AcquisitionMode of the device is 'Continuous'. Now always a new image should be returned.
- Changed behavior of parameter 'do_write_xml_file'. Now not only the XML file of the remote device but also the XML files of the GenTL Producer's modules are written (including the name of the used GenTL Producer).
- Changed internal color conversion to rely on the information which is provided by the current buffer. Currently, the interface uses the PixelFormat of the device, if the BUFFER_INFO_PIXELFORMAT_NAMESPACE or the BUFFER_INFO_PIXELFORMAT returns unsupported values. In this case a low-level error message will be returned.
- Removed setting of external trigger from open_framegrabber.
- Revision 4.3 (Dec 13, 2010):
- Changed default setting for horizontal/vertical resolution in open_framegrabber from 1 to 0.
- Fixed parsing problems of the XML files under Linux, when opening a camera several times.
- Fixed timeout when the image size has been changed and software trigger is used.
- Fixed problem with setting module parameters, which in some cases led to an error.
- Fixed error if more than one GenTL Producer was found, but one of them could not be loaded. Now the broken one is skipped and all others can be loaded correctly.
- Improved color conversion for YUV pixel formats.
- Added support of representation tags to show hexadecimal numbers correctly.
- Added low-level error messages to improve error handling.
- Added helper function to correct a value which exceeds the valid boundaries of a parameter.
- Revision 4.2 (Sep 30, 2010):
- Changed order of starting the acquisition: Now the acquisition of the remote device is started after starting the acquisition of the GenTL Producer.
- Fixed error when calling info_framegrabber with parameters 'info_boards', 'device' or 'general' more than once after each other.
- Revision 4.1 (Sep 10, 2010):
- Fixed bug to prevent HDevelop crash if info_framegrabber(..., 'info_boards', ...) was called while a device was already open.
- Fixed bug to prevent double calls of 'StartAcquisition' which led to problems with some devices.
- Enabled use of multiple devices simultaneously.
- Fixed memory leak.
- Fixed bug to enable opening a device even if there exist no module parameters in the used GenTL Producer.
- Module parameter names now start with the prefix of the corresponding module layer to ensure the uniqueness of all parameter names. Without the prefix the returned values and categories of these parameters could have been wrong.
- If the environment variables for GenICam were not set correctly, the interface failed with H_ERR_DLOPEN. Now the delayed loading of the GenICam libraries is enabled, so that the environment variables can be set automatically.
- Added parameters 'buffer_is_incomplete', 'buffer_timestamp', 'do_write_xml_file', 'num_buffers_await_delivery', 'num_buffers_underrun', 'tl_displayname', 'tl_filename', tl_id', 'tl_model', and 'tl_pathname'.
- Added paragraphs 'GenICam GenTL' and 'Parameter Naming' in this documentation.
- HALCON 10 version of the interface (included in HALCON 10 DVD).
- Revision 4.0 (Jul 30, 2010):
- First official release.