| Interface: | GigEVision2 |
| Revision: | 13.0.3 |
| Date: | 2018-10-30 |
Note that the current version of the interface supports only single-stream devices and the first available stream is always open. If support for devices with multiple image streams will be added in future, the format to open the device might be extended with the stream entry.
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.
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.
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:
|
||||||||||||||
|
G = (G1 + G2) / 2
.
R = Y' + 1.4020 * (Cr- M)
G = Y' - 0.34414 * (Cb- M) -0.71414 * (Cr- M)
B = Y' + 1.7720 * (Cb - M)
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
Y' = 0.299 * R + 0.587 * G + 0.114 * B
M = 128
for 8 bit raw data, and M = 32768
for 16 bit raw data.| 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:Esen'] | string | dynamic | List of GigE 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 GigEVision2 interface. |
| 'generic' | ['', 'num_buffers=<num>', 'direct_connection=<mode>', 'force_ip=<interface_ip/device_mac/force_device_ip/force_device_mask[/force_device_gateway/force_command_timeout]>', 'force_sockdrv=1', '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:Esen | vendor:<device_vendor> | model:<device_model> | device_ip:<device_ip> | interface_ip:<interface_ip> | status:<device_status> | suggestion:<generic_param>'] | string | dynamic | List of GigE 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 having an IP of a wrong subnet)
a corresponding generic parameter to resolve the problem is suggested.
|
| '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 GigEVision2 interface. |
| 'start_column' | [] | Unsupported query. | ||
| 'start_row' | [] | Unsupported query. | ||
| 'vertical_resolution' | [0, 1] | integer | pre-defined | Value list for vertical resolution. |
| Parameter | Values | Default | Type | Description |
|---|---|---|---|---|
| Name | 'GigEVision2' | 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>', 'direct_connection=<mode>', 'force_ip=<interface_ip/device_mac/force_device_ip/force_device_mask[/force_device_gateway/force_command_timeout]>', 'force_sockdrv=1', '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 GigE Vision 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:Esen', '<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. 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. |
| Parameter | Values | Default | Type | Description |
|---|---|---|---|---|
| '[Device]DeviceEventsThreadApplyPriority' | --- | integer | Applies the thread priority and scheduling policy (if applicable on given operating system) configured through the '[Device]DeviceEventsThreadPriority'
and '[Device]DeviceEventsThreadSchedulingPolicy' parameters to the event
processing thread.
If the thread is running, the values are directly applied. If the thread is
not running in the moment, the values are stored and will be applied as soon
as the thread is started again.
It is responsibility of the application to ensure that the calling process
has sufficient privileges. The feature is not available for devices not supporting device events or if the event handling was disabled using the 'device_event_handling=0' generic parameter. BEWARE: Setting this parameter can lead to an unusable or poorly performing system, use with care. |
|
| '[Device]DeviceEventsThreadPriority' | <thread_priority> | integer | OS-specific thread priority value to be used for the internal event processing thread. The actual values are directly the priority identifiers
of the operating system, e.g. THREAD_PRIORITY_HIGHEST under Windows
or a real-time priority value under Linux. The actual priority is applied only after executing the '[Device]DeviceEventsThreadApplyPriority' command parameter, possibly together with the '[Device]DeviceEventsThreadSchedulingPolicy' value if applicable on given system. It is the responsibility of the application to ensure that the calling process has sufficient privileges to apply the priority change and that the value written to the parameter is a valid priority identifier. After applying '[Device]DeviceEventsThreadApplyPriority', the application can read back the priority value to verify if it was properly applied. Note that when opening the device, the GigE 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]DeviceLinkHeartbeatMode' | 'Off', 'On' | 'Off' | string | Allows to disable the heartbeat control on the device. The parameter will be only present if supported by given device. It is usually only good idea to disable the heartbeat if debugging the application (to prevent loosing the device connection when hitting a breakpoint). When disabling and not re-enabling the device and if the application fails to properly close the connection (such as during crash or hard debugger stop), the device will never assume the connection has expired and will have to be rebooted. fails to maintain the heartbeat protocol. In most cases leaving the default value intact is the best solution. A possible exception can be to significantly prolong the timeout while debugging, if given device does not support heartbeat disabling. |
| '[Device]DeviceLinkHeartbeatTimeout' | <timeout> | integer | Heartbeat timeout (in usec) after which the device disconnects if the application fails to maintain the heartbeat protocol. In most cases leaving the default value intact is the best solution. A possible exception can be to significantly prolong the timeout while debugging, if given device does not support heartbeat disabling. | |
| '[Device]DeviceMessageChannelKeepAliveTimeout' | 30000 | float | Interval (in milliseconds) between keep-alive packets sent while listening for device events to the device's message channel port to simulate the events traffic is outbound rather than inbound, thus helping to receive the events reliably in presence of a firewall. The actual required interval might be specific to the actual firewall in use. Zero means no keep-alive packets are sent at all. | |
| '[Device]EventNotification' | 'Off', 'On' | 'Off' | string | Enables/disables delivery of GigE Vision Producer device module event selected in '[Device]EventSelector'. |
| '[Device]EventSelector' | 'DeviceLost' | string | Selects a GigE Vision Producer device module event to be enabled/disabled using '[Device]EventNotification'. | |
| '[Device]LinkCommandRetryCount' | 3 | integer | Specifies number of times the HALCON GigEVision2 should attempt to retry sending a given control command to the device when not receiving corresponding command acknowledge from the device (assuming the command got lost). Works together with '[Device]LinkCommandTimeout' and usually should stay intact. | |
| '[Device]LinkCommandTimeout' | 200000 | integer | Specifies the timeout (in usec) the HALCON GigEVision2 should wait for device acknowledge for individual control commands before assuming the command got lost and trying to send it again. Works together with '[Device]LinkCommandRetryCount' and usually should stay intact. | |
| '[Interface]GevDeviceForceGateway' | <gateway> | integer | Default gateway to be forced (together with IP address) into the device selected in '[Interface]DeviceSelector'. This parameter is only used to prepare the desired
IP configuration values for the device (together with '[Interface]GevDeviceForceIPAddress'
and '[Interface]GevDeviceForceSubnetMask', the settings are actually applied together using
'[Interface]GevDeviceForceIP'. Use with care, using configuration not matching the interface the device is connected to may render the device unreachable. Intended to fix exactly these kinds of situations. Applicable only on devices that are not currently open. Note that the 'force_ip' generic parameter in open_framegrabber can serve similar purpose. |
|
| '[Interface]GevDeviceForceIP' | --- | integer | Sends request to change current IP settings (IP address, subnet mask and default gateway) to the device selected in '[Interface]DeviceSelector'. The requested new settings are those
previously stored into parameters '[Interface]GevDeviceForceIPAddress',
'[Interface]GevDeviceForceSubnetMask' and '[Interface]GevDeviceForceGateway'.
Use with care, using configuration not matching the interface the device is connected to
may render the device unreachable. Intended to fix exactly these kinds of situations.
Applicable only on devices that are not currently open, opened devices will ignore the request.
The settings will not persist the device's power cycle. Note that the 'force_ip' generic parameter in open_framegrabber can serve similar purpose. |
|
| '[Interface]GevDeviceForceIPAddress' | <ip_address> | integer | IP address to be forced (together with subnet mask and gateway) into the device selected in '[Interface]DeviceSelector'. This parameter is only used to prepare the desired
IP configuration values for the device (together with '[Interface]GevDeviceForceSubnetMask'
and '[Interface]GevDeviceForceGateway', the settings are actually applied together using
'[Interface]GevDeviceForceIP'. Use with care, using configuration not matching the interface the device is connected to may render the device unreachable. Intended to fix exactly these kinds of situations. Applicable only on devices that are not currently open. Use '[Interface]GevDeviceProposeIP' to fill this parameter automatically with suitable value. Note that the 'force_ip' generic parameter in open_framegrabber can serve similar purpose. |
|
| '[Interface]GevDeviceForceSubnetMask' | <subnet_mask> | integer | Subnet mask to be forced (together with IP address) into the device selected in '[Interface]DeviceSelector'. This parameter is only used to prepare the desired
IP configuration values for the device (together with '[Interface]GevDeviceForceIPAddress'
and '[Interface]GevDeviceForceGateway', the settings are actually applied together using
'[Interface]GevDeviceForceIP'. Use with care, using configuration not matching the interface the device is connected to may render the device unreachable. Intended to fix exactly these kinds of situations. Applicable only on devices that are not currently open. Note that the 'force_ip' generic parameter in open_framegrabber can serve similar purpose. |
|
| '[Interface]GevDeviceProposeIP' | --- | integer | Generates proposal for suitable IP settings (IP address, subnet mask and default gateway) to the device selected in '[Interface]DeviceSelector'. The settings are proposed to match
the subnet of the interface where the device is connected, so that the device would be directly
reachable. The proposed settings are stored into parameters '[Interface]GevDeviceForceIPAddress', '[Interface]GevDeviceForceSubnetMask' and '[Interface]GevDeviceForceGateway' and can be applied to the device using '[Interface]GevDeviceForceIP'. |
|
| '[Stream]DeviceStreamChannelKeepAliveTimeout' | 30000 | float | Interval (in milliseconds) between keep-alive packets sent during active streaming to the device's stream channel port to simulate the stream traffic is outbound rather than inbound, thus helping to stream reliably in presence of a firewall. The actual required interval might be specific to the actual firewall in use. Zero means no keep-alive packets are sent at all. | |
| '[Stream]DeviceStreamChannelNegotiatePacketSize' | --- | integer | Starts negotiation for the optimal packet size considering the remote device, host and their connection path. The negotiation result is applied on the device and reflected in
'[Stream]DeviceStreamChannelPacketSize'. If the negotiation fails, the algorithm attempts to revert
the configuration to the initial packet size value. Note that the negotiation is applied automatically when opening the device. |
|
| '[Stream]DeviceStreamChannelPacketSize' | <packet_size> | integer | Packet size configured for the device stream channel (similar feature might appear also in feature set of the remote device itself). Configures both the remote device and GigE Vision Producer. | |
| '[Stream]DeviceStreamChannelPacketSizeInc' | --- | integer | Controls desired increment of the packet size feature to be used for the stream channel. Affects both the direct control of the packet size ('[Stream]DeviceStreamChannelPacketSize') as well as
the negotiation algorithm ('[Stream]DeviceStreamChannelNegotiatePacketSize'). The limit should be usually set in sync with actual limits imposed by the device itself, unless there are reasons to apply stricter limits. When the device limits are unknown, the initial value is set to 4. |
|
| '[Stream]DeviceStreamChannelPacketSizeMax' | --- | integer | Controls desired maximum of the packet size feature to be used for the stream channel. Affects both the direct control of the packet size ('[Stream]DeviceStreamChannelPacketSize') as well as
the negotiation algorithm ('[Stream]DeviceStreamChannelNegotiatePacketSize'). The limit should be usually set in sync with actual limits imposed by the device itself, unless there are reasons to apply stricter limits. When the device limits are unknown, the initial value is set to the MTU size accepted by the network interface the device is connected to. |
|
| '[Stream]DeviceStreamChannelPacketSizeMin' | --- | integer | Controls desired minimum of the packet size feature to be used for the stream channel. Affects both the direct control of the packet size ('[Stream]DeviceStreamChannelPacketSize') as well as
the negotiation algorithm ('[Stream]DeviceStreamChannelNegotiatePacketSize'). The limit should be usually set in sync with actual limits imposed by the device itself, unless there are reasons to apply stricter limits. When the device limits are unknown, the initial value is set to 46. |
|
| '[Stream]EventNotification' | 'Off', 'On' | 'Off' | string | Enables/disables delivery of GigE Vision Producer data stream module event selected in '[Stream]EventSelector'. |
| '[Stream]EventSelector' | 'TransferEnd' | string | Selects a GigE Vision Producer data stream module event to be enabled/disabled using '[Stream]EventNotification'. | |
| '[Stream]GevStreamDeliverIncompleteBlocks' | 0, 1 | 1 | integer | Flag indicating if incomplete buffers (with one or more missing packets) should be delivered or discarded. Note that if the leader or trailer of a block is missing it will be discarded anyway. |
| '[Stream]GevStreamFullBlockTerminatesPrev' | 0, 1 | 0 | integer | Flag indicating whether receiving a complete buffer immediately terminates any previous ones in the acquisition queue, no matter if resend is still pending for them, thus avoiding blocking the full one. |
| '[Stream]GevStreamMaxBlockDuration' | 0 | float | Maximal duration ('on the wire') of a block in microseconds. When it expires, the engine will assume the block trailer
(block trailing control packet) should be already
received - and if packet resend is supported, it will ask to resend it. Zero means no limit, which is suitable for example for line scan devices with sparse line triggers. Note: for filter driver this is rounded to milliseconds. If it expires the oldest block is checked if it can be delivered. If this is not the case resends for the oldest block are requested. This block is also marked for delivery if more packets than the trailing ones are missing. When the timer expires a second time marked blocks are either discarded or delivered. |
|
| '[Stream]GevStreamMaxPacketGaps' | 30 | integer | Socket driver: Maximal number of packet gaps in a block. Affects the amount of resources allocated for the resend mechanism.
Filter driver: Percentage of allowed missing packets for an incomplete block. Consequently this is also the maximum number of resend requests sent out per block. When exceeded, the engine will give up trying to finish this block and will discard it. |
|
| '[Stream]GevStreamPacketOrderDelay' | 10 | float | Control how long to wait for packets arriving out of order before requesting resends. For the socket driver this is a time period in microseconds, for the filter driver it is the number of packets to wait before checking for missing packets and eventually triggering a resend. The main purpose is to avoid resend request too early in situations when out of order packets are expectable (such as with link aggregation based connections or cameras which send packets out of order e.g. due to improper usage of multiple sensor tabs). | |
| '[Stream]StreamBufferHandlingMode' | 'OldestFirst', 'OldestFirstOverwrite', 'NewestOnly' | 'OldestFirst' | string | Selects the mode the streaming engine uses to handle newly acquired data, in particular when the camera runs faster than the application processing.
The parameter is writeable only if no acquisition is active.
Supported values are:
|
| '[Stream]StreamThreadApplyPriority' | --- | integer | Applies the thread priority and scheduling policy (if applicable on the given operating system) configured through
'[Stream]StreamThreadPriority' and '[Stream]StreamThreadSchedulingPolicy'
parameters to the stream processing thread.
If the thread is running (acquisition started), the values are directly
applied. If the thread is not running in the moment, the values are
stored and will be applied as soon as the thread is started again.
It is the responsibility of the application to ensure that the calling
process has sufficient privileges. BEWARE: Setting this parameter can lead to an unusable or poorly performing system, use with care. |
|
| '[Stream]StreamThreadPriority' | <thread_priority> | integer | OS-specific thread priority value to be used for the internal stream processing thread. The actual values are directly the priority identifiers
of the operating system, e.g. THREAD_PRIORITY_HIGHEST under Windows
or a real-time priority value under Linux. The actual priority is applied only after executing the '[Stream]StreamThreadApplyPriority' command parameter, possibly together with the '[Stream]StreamThreadSchedulingPolicy' value if applicable on given system. It is the responsibility of the application to ensure that the calling process has sufficient privileges to apply the priority change and that the value written to the parameter is a valid priority identifier. After applying '[Stream]StreamThreadApplyPriority', the application can read back the priority value to verify if it was properly applied. Note that when opening the device, the GigE 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 an runtime overhead to write the 0xF0 data every time a buffer is queued. It is mainly useful for debugging in combination with transport layers which do not guarantee the transfer of complete images. Please note, that this parameter does not modify the buffer queue, only the content of a buffer will be set to a defined state. |
| 'color_space' | 'default', 'gray', 'raw', 'rgb', 'yuv' | string | Specify the desired color space and thus the number of image channels of the resulting HALCON image. In case of 'default' for Mono pixel formats, ColorSpace is set to 'gray', otherwise to 'rgb' (and for unknown pixel formats to 'raw'). | |
| 'confidence_mode' | 'off', 'object_model_3d' | 'off' | string | Controls if (and how) the information about pixel confidence level is used by the acquisition interface. Applicable only for devices and use cases where the confidence information is delivered (per-pixel)
together with the actual pixel data. The threshold to distinguish between valid and invalid pixels is controlled using the 'confidence_threshold' parameter. Note that in some use cases there might be other criteria how to mark given pixel invalid, for example if the device uses "invalid pixel value" for a 3D coordinate. These cases are not covered by the 'confidence_mode' parameter and such invalid pixels are always rejected from the 3D object model. Possible values are:
|
| '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:
|
| '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 GigE 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. 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 GigE Vision Producer module
associated with currently opened device. The GenICam description
files are written to the same directory as the ini file itself.
The written ini file contains in particular paths to the written
GenICam description files and can be reused through the 'CameraType'
parameter of open_framegrabber operator, see
detailed description in section about device opening.
Additionally, it writes also persistence files with current
configuration of the device and all GigE Vision Producer modules
that can be loaded back when next time opening the device
using the same 'CameraType' parameter of open_framegrabber
described above.
Instead of specifying the path of the output ini file, 'default'
or an empty string can be used. In this case the files will be
written to the %TEMP% directory and the filename of the configuration
file will be halcon_gentl_config.ini. Note that this default option
will apply also when using the Image Acquisition Assistant.
See also related sections Selection of GenICam Feature Description File(s) and Parameters – Persisting Device Status. |
|
| 'do_write_settings' | <output_file> | string | Writes the current settings of the opened device to be able to restore the settings later. See detailed description in section Parameters - Persisting Device Status. | |
| 'event_data' | '<genicam_feature>' | string | Selects GenICam features to be added to the message queue specified by 'event_message_queue' and 'event_selector'. Features can be added individually or as a tuple. To remove individual features, prepend them with a '~'. To clear all currently added features, call set_framegrabber_param(..., 'event_data', []). Read more about the usage of this mechanism at Event Message Queues. | |
| 'event_message_queue' | 0, '<queue_handle>' | handle | Selects a message queue to which the acquisition interface should send Feature Change Notifications. The corresponding GenICam feature needs to be previously specified by 'event_selector'. Read more about the usage of this mechanism at Event Message Queues. | |
| 'event_notification_helper' | 'disable', 'enable' | 'disable' | string | Controls if the acquisition interface should attempt to automatically (un)set 'EventNotification' during set_framegrabber_callback if the callback is being (un)registered on an SFNC-compliant event. Note that this will only work if the callback is being registered on the actual event feature (e.g. 'EventExposureEnd'), not on one of the event data features (e.g. 'EventExposureEndTimestamp'). For further information on events, see Event Data. |
| 'event_selector' | '<genicam_feature>' | string | Selects a GenICam feature for which the acquisition interface should send Feature Change Notifications. They are sent to the message queue specified by 'event_message_queue'. Read more about the usage of this mechanism at Event Message Queues. | |
| 'fileaccess_file_path' | '<file_path>' | string | Specifies full path to a local file (in host filesystem) that should be used for file exchange operations between host and the device,
'do_fileaccess_download', or 'do_fileaccess_upload'. The current user/process must have sufficient rights to access the file. Note that all file access related parameters are available only if given device supports the GenICam file access functionality. |
|
| 'fileaccess_remote_name' | '<file_name>' | string | Selects a file on the device that should be subject to one of the file access handling operations, 'do_fileaccess_download', 'do_fileaccess_upload',
or 'do_fileaccess_delete'. The name must be one of the files implemented by the device - the set of valid names can be queried using 'fileaccess_remote_name_values'. Note that all file access related parameters are available only if given device supports the GenICam file access functionality. |
|
| 'fwupdate_file_path' | '<file_name>' | string | Path to the file carrying GenICam compatible firmware update (guf-file). When set, the file will be validated and included firmware updates enumerated.
When invalid or when no updates matching the current device will be found,
error will be raised. If successful, the set of matching updates can be queried
using 'fwupdate_update_selector_values' and the actual update to apply selected
using 'fwupdate_update_selector'. Finally, the selected update can be applied
using 'do_fwupdate_apply'. Note that all firmware update related parameters are available only in the dedicated "safe mode", see Firmware Update. |
|
| 'fwupdate_update_selector' | '<firmware_update_label>' | string | Selects firmware update that can be applied through 'do_fwupdate_apply'. The selector will become available after selecting a valid firmware update
file in 'fwupdate_file_path'. The options (labels describing the matching
firmware updates found in that file) can be queried using
'fwupdate_update_selector_values'. Note that all firmware update related parameters are available only in the dedicated "safe mode", see Firmware Update. |
|
| 'fwupdate_wait_after_reset' | '<timeout>' | integer | Additional timeout (in ms) applied before device re-discovery if a device reset is required during the firmware update procedure. The timeout is added to corresponding timeout
specified in the firmware update file itself. Intended to resolve system-specific
problems when the device cannot be safely re-discovered using the original timeout. Note that all firmware update related parameters are available only in the dedicated "safe mode", see Firmware Update. |
|
| 'grab_timeout' | <milliseconds> | 5000 | integer | Desired timeout (milliseconds) for aborting a pending grab. If -1 is specified, the timeout is set to INFINITE. |
| 'image_height' | --- | 0 | Unsupported (read-only parameter). | |
| 'image_width' | --- | 0 | Unsupported (read-only parameter). | |
| 'register_<addr>_<len>' | integer | Direct register access for reading and writing integers. The value has to be hexadecimal, e.g. 0x0938. Note that only 4 or 8 Byte length values are accepted. Caution: This is a dangerous function intended for debugging and special cases. Usually only features in the XML should be used. | ||
| 'split_param_values_into_dwords' | 'disable', 'enable' | 'disable' | string | Enables a special mode allowing the treatment of integer parameters as tuple of two 32-bit integers. For compatibility with the single-parameter mode, the first tuple element carries always the low 32-bit part of the value, second element carries the high 32-bit part. It is user's responsibility to combine the two parts correctly. This mode is intended especially to help to overcome the problem of 32-bit HALCON featuring only 32-bit integer parameters but having to face up to 64-bit wide GenICam features. In this mode, the get_framegrabber_param returns always a tuple of two integers, set_framegrabber_param accepts both a single parameter or a tuple. Note that this mode affects only integer parameters and only the GenICam based ones, not the internal parameters of HALCON GigEVision2 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. |
All these postfixed parameter names are not returned when calling info_framegrabber(.., 'parameters', ..) and are used to enable the easy parameterization via a generic graphical user interface, particularly the HDevelop Image Acquisition Assistant.
| Parameter | Values | Default | Type | Kind | Description |
|---|---|---|---|---|---|
| '[Device]DeviceEventsThreadPriority' | <thread_priority> | integer | pre-defined | OS-specific thread priority value to be used for the internal event processing thread. The actual values are directly the priority identifiers
of the operating system, e.g. THREAD_PRIORITY_HIGHEST under Windows
or a real-time priority value under Linux. The actual priority is applied only after executing the '[Device]DeviceEventsThreadApplyPriority' command parameter, possibly together with the '[Device]DeviceEventsThreadSchedulingPolicy' value if applicable on given system. It is the responsibility of the application to ensure that the calling process has sufficient privileges to apply the priority change and that the value written to the parameter is a valid priority identifier. After applying '[Device]DeviceEventsThreadApplyPriority', the application can read back the priority value to verify if it was properly applied. Note that when opening the device, the GigE 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]DeviceLinkHeartbeatMode' | 'Off', 'On' | 'Off' | string | pre-defined | Allows to disable the heartbeat control on the device. The parameter will be only present if supported by given device. It is usually only good idea to disable the heartbeat if debugging the application (to prevent loosing the device connection when hitting a breakpoint). When disabling and not re-enabling the device and if the application fails to properly close the connection (such as during crash or hard debugger stop), the device will never assume the connection has expired and will have to be rebooted. fails to maintain the heartbeat protocol. In most cases leaving the default value intact is the best solution. A possible exception can be to significantly prolong the timeout while debugging, if given device does not support heartbeat disabling. |
| '[Device]DeviceLinkHeartbeatTimeout' | <timeout> | integer | pre-defined | Heartbeat timeout (in usec) after which the device disconnects if the application fails to maintain the heartbeat protocol. In most cases leaving the default value intact is the best solution. A possible exception can be to significantly prolong the timeout while debugging, if given device does not support heartbeat disabling. | |
| '[Device]DeviceMessageChannelKeepAliveTimeout' | 30000 | float | pre-defined | Interval (in milliseconds) between keep-alive packets sent while listening for device events to the device's message channel port to simulate the events traffic is outbound rather than inbound, thus helping to receive the events reliably in presence of a firewall. The actual required interval might be specific to the actual firewall in use. Zero means no keep-alive packets are sent at all. | |
| '[Device]EventDeviceLost' | integer | pre-defined | Delivers notification about "device lost" event (losing connection with the device). To receive such notification, it is necessary to register 'DeviceLost' event delivery using '[Device]EventSelector' and '[Device]EventNotification' and register notification callback for this feature ('[Device]EventDeviceLost') as described in Feature Change Notifications. When receiving the notification, it is recommended to try to read the value of [Device]EventDeviceLost. If readable, the connection to the device was actually lost (note that the actually read value of this parameter is insignificant). After losing connection to the device, the device handle is no more usable and should be closed. | ||
| '[Device]EventNotification' | 'Off', 'On' | 'Off' | string | pre-defined | Enables/disables delivery of GigE Vision Producer device module event selected in '[Device]EventSelector'. |
| '[Device]EventSelector' | 'DeviceLost' | string | pre-defined | Selects a GigE Vision Producer device module event to be enabled/disabled using '[Device]EventNotification'. | |
| '[Device]GevDeviceGateway' | <gateway> | integer | pre-defined | Default gateway address of the device, in integer format. | |
| '[Device]GevDeviceIPAddress' | <ip_address> | integer | pre-defined | IP address of the device, in integer format. | |
| '[Device]GevDeviceMACAddress' | <mac_address> | integer | pre-defined | MAC address of the device, in integer format. | |
| '[Device]GevDeviceSubnetMask' | <subnet_mask> | integer | pre-defined | Subnet mask of the device, in integer format. | |
| '[Device]LinkCommandRetryCount' | 3 | integer | pre-defined | Specifies number of times the HALCON GigEVision2 should attempt to retry sending a given control command to the device when not receiving corresponding command acknowledge from the device (assuming the command got lost). Works together with '[Device]LinkCommandTimeout' and usually should stay intact. | |
| '[Device]LinkCommandTimeout' | 200000 | integer | pre-defined | Specifies the timeout (in usec) the HALCON GigEVision2 should wait for device acknowledge for individual control commands before assuming the command got lost and trying to send it again. Works together with '[Device]LinkCommandRetryCount' and usually should stay intact. | |
| '[Interface]GevDeviceForceGateway' | <gateway> | integer | pre-defined | Default gateway to be forced (together with IP address) into the device selected in '[Interface]DeviceSelector'. This parameter is only used to prepare the desired
IP configuration values for the device (together with '[Interface]GevDeviceForceIPAddress'
and '[Interface]GevDeviceForceSubnetMask', the settings are actually applied together using
'[Interface]GevDeviceForceIP'. Use with care, using configuration not matching the interface the device is connected to may render the device unreachable. Intended to fix exactly these kinds of situations. Applicable only on devices that are not currently open. Note that the 'force_ip' generic parameter in open_framegrabber can serve similar purpose. |
|
| '[Interface]GevDeviceForceIPAddress' | <ip_address> | integer | pre-defined | IP address to be forced (together with subnet mask and gateway) into the device selected in '[Interface]DeviceSelector'. This parameter is only used to prepare the desired
IP configuration values for the device (together with '[Interface]GevDeviceForceSubnetMask'
and '[Interface]GevDeviceForceGateway', the settings are actually applied together using
'[Interface]GevDeviceForceIP'. Use with care, using configuration not matching the interface the device is connected to may render the device unreachable. Intended to fix exactly these kinds of situations. Applicable only on devices that are not currently open. Use '[Interface]GevDeviceProposeIP' to fill this parameter automatically with suitable value. Note that the 'force_ip' generic parameter in open_framegrabber can serve similar purpose. |
|
| '[Interface]GevDeviceForceSubnetMask' | <subnet_mask> | integer | pre-defined | Subnet mask to be forced (together with IP address) into the device selected in '[Interface]DeviceSelector'. This parameter is only used to prepare the desired
IP configuration values for the device (together with '[Interface]GevDeviceForceIPAddress'
and '[Interface]GevDeviceForceGateway', the settings are actually applied together using
'[Interface]GevDeviceForceIP'. Use with care, using configuration not matching the interface the device is connected to may render the device unreachable. Intended to fix exactly these kinds of situations. Applicable only on devices that are not currently open. Note that the 'force_ip' generic parameter in open_framegrabber can serve similar purpose. |
|
| '[Interface]GevInterfaceMACAddress' | <mac_address> | integer | pre-defined | MAC address of the host's network interface the device is connected to, in integer format. | |
| '[Interface]GevInterfaceMTU' | <timeout> | integer | pre-defined | Maximum tramsmission unit (MTU) currently accepted by the host's network interface the device is connected to. | |
| '[Interface]GevInterfaceSubnetIPAddress' | <ip_address> | integer | pre-defined | IP address of the host's network interface the device is connected to, in integer format. | |
| '[Interface]GevInterfaceSubnetMask' | <subnet_mask> | integer | pre-defined | Subnet mask of the host's network interface the device is connected to, in integer format. | |
| '[Stream]DeviceStreamChannelKeepAliveTimeout' | 30000 | float | pre-defined | Interval (in milliseconds) between keep-alive packets sent during active streaming to the device's stream channel port to simulate the stream traffic is outbound rather than inbound, thus helping to stream reliably in presence of a firewall. The actual required interval might be specific to the actual firewall in use. Zero means no keep-alive packets are sent at all. | |
| '[Stream]DeviceStreamChannelPacketSize' | <packet_size> | integer | pre-defined | Packet size configured for the device stream channel (similar feature might appear also in feature set of the remote device itself). Configures both the remote device and GigE Vision Producer. | |
| '[Stream]DeviceStreamChannelPacketSizeInc' | --- | integer | pre-defined | Controls desired increment of the packet size feature to be used for the stream channel. Affects both the direct control of the packet size ('[Stream]DeviceStreamChannelPacketSize') as well as
the negotiation algorithm ('[Stream]DeviceStreamChannelNegotiatePacketSize'). The limit should be usually set in sync with actual limits imposed by the device itself, unless there are reasons to apply stricter limits. When the device limits are unknown, the initial value is set to 4. |
|
| '[Stream]DeviceStreamChannelPacketSizeMax' | --- | integer | pre-defined | Controls desired maximum of the packet size feature to be used for the stream channel. Affects both the direct control of the packet size ('[Stream]DeviceStreamChannelPacketSize') as well as
the negotiation algorithm ('[Stream]DeviceStreamChannelNegotiatePacketSize'). The limit should be usually set in sync with actual limits imposed by the device itself, unless there are reasons to apply stricter limits. When the device limits are unknown, the initial value is set to the MTU size accepted by the network interface the device is connected to. |
|
| '[Stream]DeviceStreamChannelPacketSizeMin' | --- | integer | pre-defined | Controls desired minimum of the packet size feature to be used for the stream channel. Affects both the direct control of the packet size ('[Stream]DeviceStreamChannelPacketSize') as well as
the negotiation algorithm ('[Stream]DeviceStreamChannelNegotiatePacketSize'). The limit should be usually set in sync with actual limits imposed by the device itself, unless there are reasons to apply stricter limits. When the device limits are unknown, the initial value is set to 46. |
|
| '[Stream]EventNotification' | 'Off', 'On' | 'Off' | string | pre-defined | Enables/disables delivery of GigE Vision Producer data stream module event selected in '[Stream]EventSelector'. |
| '[Stream]EventSelector' | 'TransferEnd' | string | pre-defined | Selects a GigE Vision Producer data stream module event to be enabled/disabled using '[Stream]EventNotification'. | |
| '[Stream]EventTransferEnd' | integer | pre-defined | Delivers notification about "transfer end" event (finishing transfer of a buffer within the streaming engine).
To receive such notification, it is necessary to register 'TransferEnd' event delivery
using '[Stream]EventSelector' and '[Stream]EventNotification' and register notification
callback for this feature ('[Stream]EventTransferEnd') as described in
Feature Change Notifications.
The actual value read from this parameter is insignificant.
Additional information about the event can be obtained using
'[Stream]EventTransferEndFrameID' and '[Stream]EventTransferEndBufferUndeliverable'. IMPORTANT: there is no 1:1 mapping between generated transfer end events and actually delivered buffers. Corrupted/undeliverable buffers will be discarded by the streaming engine. Even valid buffers can still be dropped within the output queue based on the queue state and '[Stream]StreamBufferHandlingMode' parameter. Note: this notification is currently not generated if filter driver is active. |
||
| '[Stream]EventTransferEndBufferUndeliverable' | 0, 1 | integer | pre-defined | Flag indicating whether the last buffer for which the transfer end event was signalled through '[Stream]EventTransferEnd' was deliverable (valid).
Corrupted/undeliverable buffers will be discarded by the streaming
engine. Even valid buffers can still be dropped within the output queue based on
the queue state and '[Stream]StreamBufferHandlingMode' parameter. |
|
| '[Stream]EventTransferEndFrameID' | integer | pre-defined | Frame ID of the last buffer for which the transfer end event was signalled through '[Stream]EventTransferEnd'. | ||
| '[Stream]GevStreamActiveEngine' | 'SocketDriver', 'FilterDriver' | string | pre-defined | Informs which stream engine (socket or filter driver is currently active). Available only on Windows systems (on other systems always socket driver is used). | |
| '[Stream]GevStreamDeliveredPacketCount' | 0 | integer | pre-defined | All packets successfully received in the delivered blocks. The packets from undelivered (skipped or discarded) blocks are not counted.
Note: this information is currently not provided if filter driver is active. |
|
| '[Stream]GevStreamDeliverIncompleteBlocks' | 0, 1 | 1 | integer | pre-defined | Flag indicating if incomplete buffers (with one or more missing packets) should be delivered or discarded. Note that if the leader or trailer of a block is missing it will be discarded anyway. |
| '[Stream]GevStreamDiscardedBlockCount' | 0 | integer | pre-defined | Number of blocks that were discarded for any reason including corruption, too many missing packets (according to the selected input parameters) or missing leader and/or trailer. | |
| '[Stream]GevStreamDuplicatePacketCount' | 0 | integer | pre-defined | Packets that were received twice (typically because the resend request arrived too early).
Note: this information is currently not provided if filter driver is active. |
|
| '[Stream]GevStreamEngineUnderrunCount' | 0 | integer | pre-defined | Number of blocks that were discarded because no buffers were scheduled into the acq engine when given block arrived. | |
| '[Stream]GevStreamFullBlockTerminatesPrev' | 0, 1 | 0 | integer | pre-defined | Flag indicating whether receiving a complete buffer immediately terminates any previous ones in the acquisition queue, no matter if resend is still pending for them, thus avoiding blocking the full one. |
| '[Stream]GevStreamIncompleteBlockCount' | 0 | integer | pre-defined | Number of blocks that were delivered incomplete (with one or more missing packets in them). | |
| '[Stream]GevStreamLostPacketCount' | 0 | integer | pre-defined | All packets missing (even after resends) in the delivered blocks. The packets from undelivered (skipped or discarded) blocks are not counted.
Note: this information is currently not provided if filter driver is active. |
|
| '[Stream]GevStreamMaxBlockDuration' | 0 | float | pre-defined | Maximal duration ('on the wire') of a block in microseconds. When it expires, the engine will assume the block trailer
(block trailing control packet) should be already
received - and if packet resend is supported, it will ask to resend it. Zero means no limit, which is suitable for example for line scan devices with sparse line triggers. Note: for filter driver this is rounded to milliseconds. If it expires the oldest block is checked if it can be delivered. If this is not the case resends for the oldest block are requested. This block is also marked for delivery if more packets than the trailing ones are missing. When the timer expires a second time marked blocks are either discarded or delivered. |
|
| '[Stream]GevStreamMaxPacketGaps' | 30 | integer | pre-defined | Socket driver: Maximal number of packet gaps in a block. Affects the amount of resources allocated for the resend mechanism.
Filter driver: Percentage of allowed missing packets for an incomplete block. Consequently this is also the maximum number of resend requests sent out per block. When exceeded, the engine will give up trying to finish this block and will discard it. |
|
| '[Stream]GevStreamOversizedBlockCount' | 0 | integer | pre-defined | Number of blocks that were detected as oversized, ie. one or more packets did not fit into the allocated buffer. Counted no matter if the buffer
was actually delivered or not.
Note: this information is currently not provided if filter driver is active. |
|
| '[Stream]GevStreamPacketOrderDelay' | 10 | float | pre-defined | Control how long to wait for packets arriving out of order before requesting resends. For the socket driver this is a time period in microseconds, for the filter driver it is the number of packets to wait before checking for missing packets and eventually triggering a resend. The main purpose is to avoid resend request too early in situations when out of order packets are expectable (such as with link aggregation based connections or cameras which send packets out of order e.g. due to improper usage of multiple sensor tabs). | |
| '[Stream]GevStreamResendCommandCount' | 0 | integer | pre-defined | Number of resend requests (no matter if single or multi-packet ones). Each resend is counted, even if sent multiple times for the same packet.
Even those belonging to buffers which never get delivered are counted.
Note: this information is currently not provided if filter driver is active. |
|
| '[Stream]GevStreamResendPacketCount' | 0 | integer | pre-defined | Number of resend-requested packets. Each resend is counted, even if sent multiple times for the same packet. Even those belonging to buffers which never get delivered are counted. When asking for resend of buffer tail (with unknown number of packets in it) only a single packet is counted. | |
| '[Stream]GevStreamSeenPacketCount' | 0 | integer | pre-defined | All packets (even invalid or duplicates) seen by the stream. | |
| '[Stream]GevStreamSkippedBlockCount' | 0 | integer | pre-defined | Number of blocks that were skipped somewhere (we have never seen any valid packet belonging to them).
Note: this information is currently not provided if filter driver is active. |
|
| '[Stream]GevStreamUnavailablePacketCount' | 0 | integer | pre-defined | All packets explicitly announced as unavailable (after resend) by the device (contrary to those that were simply silently not resent). This typically means the resend request came too late. | |
| '[Stream]StreamBufferHandlingMode' | 'OldestFirst', 'OldestFirstOverwrite', 'NewestOnly' | 'OldestFirst' | string | pre-defined | Selects the mode the streaming engine uses to handle newly acquired data, in particular when the camera runs faster than the application processing.
The parameter is writeable only if no acquisition is active.
Supported values are:
|
| '[Stream]StreamThreadPriority' | <thread_priority> | integer | pre-defined | OS-specific thread priority value to be used for the internal stream processing thread. The actual values are directly the priority identifiers
of the operating system, e.g. THREAD_PRIORITY_HIGHEST under Windows
or a real-time priority value under Linux. The actual priority is applied only after executing the '[Stream]StreamThreadApplyPriority' command parameter, possibly together with the '[Stream]StreamThreadSchedulingPolicy' value if applicable on given system. It is the responsibility of the application to ensure that the calling process has sufficient privileges to apply the priority change and that the value written to the parameter is a valid priority identifier. After applying '[Stream]StreamThreadApplyPriority', the application can read back the priority value to verify if it was properly applied. Note that when opening the device, the GigE 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. |
|
| '[System]GevTLSubsystemInfo' | '<subsystem_info>' | string | pre-defined | Information about the subsystems in GigE Vision Producer implementation. Intended primarily for troubleshooting and support. | |
| '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 GigE Vision 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 GigEVision2 image acquisition interface and those published by the device and GigE Vision Producer via the GenICam interface (see parameter naming conventions). Note that availability of some parameters might depend on acquisition status, values of other parameters or other conditions, so the list dynamically changes during runtime. | |
| 'bits_per_channel' | -1, 8, 10, 12, 14, 16 | -1 | integer | pre-defined | Number of bits per channel of the resulting HALCON image. In case of -1 the bit depth of each respective acquired buffer is used. By specifying a value greater than 8 the grabbed images are delivered as uint2 images. |
| 'buffer_frameid' | <frame_id> | integer | dynamic | Frame ID attached to the last grabbed (image) buffer by the device (or GigE 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 GigE 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 GigE 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 GigE 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 an runtime overhead to write the 0xF0 data every time a buffer is queued. It is mainly useful for debugging in combination with transport layers which do not guarantee the transfer of complete images. Please note, that this parameter does not modify the buffer queue, only the content of a buffer will be set to a defined state. |
| 'color_space' | 'default', 'gray', 'raw', 'rgb', 'yuv' | 'default' | string | pre-defined | Returns the current color space. |
| 'confidence_mode' | 'off', 'object_model_3d' | 'off' | string | pre-defined | Controls if (and how) the information about pixel confidence level is used by the acquisition interface. Applicable only for devices and use cases where the confidence information is delivered (per-pixel)
together with the actual pixel data. The threshold to distinguish between valid and invalid pixels is controlled using the 'confidence_threshold' parameter. Note that in some use cases there might be other criteria how to mark given pixel invalid, for example if the device uses "invalid pixel value" for a 3D coordinate. These cases are not covered by the 'confidence_mode' parameter and such invalid pixels are always rejected from the 3D object model. Possible values are:
|
| '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:
|
| 'create_objectmodel3d' | 'disable', 'enable' | 'disable' | string | pre-defined | Controls whether the acquisition interface should attempt to generate HALCON 3D object model(s) when encountering 3D coordinates within the acquired data. To obtain a 3D object model, the application has to use the grab_data/grab_data_async operators which can return the handles to the generated models through the control data outputs. The grab_image/grab_image_async operators cannot return the 3D object models. IMPORTANT: the parameter is disabled by default. When enabling, the application is responsible for releasing the generated object models and associated resources using the clear_object_model_3d operator once it does not need given model(s) any more. It should do so by tracking which of the control data outputs of every single grab_data/grab_data_async calls carry 3D object model handle(s). This can be done using the 'data_contents' parameter. When generating the 3D object model, the acquisition interface processes the 3D coordinates found in the acquired data and builds the point cloud with help of the information about the actual 3D configuration reported by the device. Refer to Using 3D Devices for more details. |
| 'data_contents' | 'unknown', 'object_model_3d', 'text_report' | 0 | string | pre-defined | Tuple describing logical type of the control data outputs returned by the last grab operator. Not applicable if last successful grab was performed through grab_image/grab_image_async.
In case of grab_data/grab_data_async it returns tuple of the size
corresponding to the number of control data values returned through those operators.
Possible values are:
|
| 'data_purpose_id' | --- | 0xFFFFFFFFFFFFFFFF | integer | pre-defined | Tuple of integer values allowing to track data purpose IDs associated to individual control data outputs returned by the last grab operator. Intended for advanced use cases when the data should be matched with the device configuration. The use of the parameter is application specific and requires knowledge of the GenICam SFNC data model and specific device. Not applicable if last successful grab was performed through grab_image/grab_image_async. In case of grab_data/grab_data_async it returns tuple of the size corresponding to the number of control data values returned through those operators. If the ID could not be identified (eg. because the underlying communication protocol does not provide such information), invalid value will be returned (max value of given integer range). |
| 'data_region_id' | --- | 0xFFFFFFFFFFFFFFFF | integer | pre-defined | Tuple of integer values allowing to track region IDs associated to individual control data outputs returned by the last grab operator. Intended for advanced use cases when the data should be matched with the device configuration. The use of the parameter is application specific and requires knowledge of the GenICam SFNC data model and specific device. Not applicable if last successful grab was performed through grab_image/grab_image_async. In case of grab_data/grab_data_async it returns tuple of the size corresponding to the number of control data values returned through those operators. If the ID could not be identified (eg. because the underlying communication protocol does not provide such information), invalid value will be returned (max value of given integer range). |
| 'data_source_id' | --- | 0xFFFFFFFFFFFFFFFF | integer | pre-defined | Tuple of integer values allowing to track source IDs associated to individual control data outputs returned by the last grab operator. Intended for advanced use cases when the data should be matched with the device configuration. The use of the parameter is application specific and requires knowledge of the GenICam SFNC data model and specific device. Not applicable if last successful grab was performed through grab_image/grab_image_async. In case of grab_data/grab_data_async it returns tuple of the size corresponding to the number of control data values returned through those operators. If the ID could not be identified (eg. because the underlying communication protocol does not provide such information), invalid value will be returned (max value of given integer range). |
| 'delay_after_stop' | <milliseconds> | 0 | integer | pre-defined | The time to wait (in milliseconds) between stopping the acquisition on the device (AcquisitionStop command) and GigE Vision Producer. |
| 'device' | ' | device:<device id> | unique_name:<unique name> | user_name:<user-defined name> | interface:<interface id> | producer:Esen', '<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' | '<genicam_feature>' | string | pre-defined | Selects GenICam features to be added to the message queue specified by 'event_message_queue' and 'event_selector'. Features can be added individually or as a tuple. To remove individual features, prepend them with a '~'. To clear all currently added features, call set_framegrabber_param(..., 'event_data', []). Read more about the usage of this mechanism at Event Message Queues. | |
| 'event_message_queue' | 0, '<queue_handle>' | handle | pre-defined | Selects a message queue to which the acquisition interface should send Feature Change Notifications. The corresponding GenICam feature needs to be previously specified by 'event_selector'. Read more about the usage of this mechanism at Event Message Queues. | |
| 'event_notification_helper' | 'disable', 'enable' | 'disable' | string | pre-defined | Controls if the acquisition interface should attempt to automatically (un)set 'EventNotification' during set_framegrabber_callback if the callback is being (un)registered on an SFNC-compliant event. Note that this will only work if the callback is being registered on the actual event feature (e.g. 'EventExposureEnd'), not on one of the event data features (e.g. 'EventExposureEndTimestamp'). For further information on events, see Event Data. |
| 'event_selector' | '<genicam_feature>' | string | pre-defined | Selects a GenICam feature for which the acquisition interface should send Feature Change Notifications. They are sent to the message queue specified by 'event_message_queue'. Read more about the usage of this mechanism at Event Message Queues. | |
| 'external_trigger' | <default> | 'false' | string | pre-defined | The value is not used, so a default value is returned. |
| 'field' | '<default>' | 'progressive' | string | pre-defined | The value is not used, so a default value is returned. |
| 'fileaccess_file_path' | '<file_path>' | string | pre-defined | Specifies full path to a local file (in host filesystem) that should be used for file exchange operations between host and the device,
'do_fileaccess_download', or 'do_fileaccess_upload'. The current user/process must have sufficient rights to access the file. Note that all file access related parameters are available only if given device supports the GenICam file access functionality. |
|
| 'fileaccess_remote_name' | '<file_name>' | string | pre-defined | Selects a file on the device that should be subject to one of the file access handling operations, 'do_fileaccess_download', 'do_fileaccess_upload',
or 'do_fileaccess_delete'. The name must be one of the files implemented by the device - the set of valid names can be queried using 'fileaccess_remote_name_values'. Note that all file access related parameters are available only if given device supports the GenICam file access functionality. |
|
| 'fwupdate_file_path' | '<file_name>' | string | pre-defined | Path to the file carrying GenICam compatible firmware update (guf-file). When set, the file will be validated and included firmware updates enumerated.
When invalid or when no updates matching the current device will be found,
error will be raised. If successful, the set of matching updates can be queried
using 'fwupdate_update_selector_values' and the actual update to apply selected
using 'fwupdate_update_selector'. Finally, the selected update can be applied
using 'do_fwupdate_apply'. Note that all firmware update related parameters are available only in the dedicated "safe mode", see Firmware Update. |
|
| 'fwupdate_update_selector' | '<firmware_update_label>' | string | pre-defined | Selects firmware update that can be applied through 'do_fwupdate_apply'. The selector will become available after selecting a valid firmware update
file in 'fwupdate_file_path'. The options (labels describing the matching
firmware updates found in that file) can be queried using
'fwupdate_update_selector_values'. Note that all firmware update related parameters are available only in the dedicated "safe mode", see Firmware Update. |
|
| 'fwupdate_wait_after_reset' | '<timeout>' | integer | pre-defined | Additional timeout (in ms) applied before device re-discovery if a device reset is required during the firmware update procedure. The timeout is added to corresponding timeout
specified in the firmware update file itself. Intended to resolve system-specific
problems when the device cannot be safely re-discovered using the original timeout. Note that all firmware update related parameters are available only in the dedicated "safe mode", see Firmware Update. |
|
| 'generic' | '', ['num_buffers=<num>', '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 GigE Vision Producer. | |
| 'image_contents' | 'unknown', 'image', 'coord_a', 'coord_b', 'coord_c', 'coord_mixed', 'confidence' | 0 | string | pre-defined | Tuple describing logical type of the image data returned by the last grab operator. If the last successful grab was performed through grab_image/grab_image_async, the parameter
returns always single value. In case of grab_data/grab_data_async it returns tuple of the size
corresponding to the number of images returned through those operators.
Possible values are:
|
| 'image_height' | <height> | 0 | integer | pre-defined | Height of the last acquired image. See acquisition buffer handling. If there is no valid last buffer available, the last queried value of the 'Height' parameter of the remote device is returned. |
| 'image_pixel_format' | --- | 0 | integer | pre-defined | Tuple of integer values representing the ID of the original pixel formats of the source data used to generate individual image outputs. This is typically the PFNC 32-bit ID of given pixel format - if unknown or if the data used to generate given image output is not naturally an image, zero will be reported. If the source data is a multi-component image (such as RGB or multi-component 3D coordinate format), the original multi-component pixel format is reported, no matter if all of the components were used to generate given image output (such as an RGB image) or if the image output reflects only one of the components (such as individual 3D coordinate planes, output as separate HALCON images). The original multi-component pixel format might be planar format or not. Note that the color space and bit depth of the actual HALCON image might significantly differ from the source format if the user requests color space conversion through the 'bits_per_channel' and 'color_space' parameters. |
| 'image_purpose_id' | --- | 0xFFFFFFFFFFFFFFFF | integer | pre-defined | Tuple of integer values allowing to track data purpose IDs associated to individual image outputs returned by the last grab operator. Intended for advanced use cases when the data should be matched with the device configuration. The use of the parameter is application specific and requires knowledge of the GenICam SFNC data model and specific device. If the last successful grab was performed through grab_image/grab_image_async, the parameter returns always single value. In case of grab_data/grab_data_async it returns tuple of the size corresponding to the number of images returned through those operators. If the ID could not be identified (eg. because the underlying communication protocol does not provide such information), invalid value will be returned (max value of given integer range). |
| 'image_raw_buffer_padding_bytes' | --- | 0 | integer | pre-defined | Tuple of integers reporting for raw buffers of type 'blob' (see 'image_raw_buffer_type') the size of unused padding bytes at the end of such grabbed HALCON image. Because artificial dimensions need to be chosen for the resulting HALCON image in this case, the size of such image might not exactly equal the size of the buffer data and thus the padding might be needed. Zero is reported for buffers of type 'image'. Applies only in case of the 'raw' color format. See raw output format chapter. If the last successful grab was performed through grab_image/grab_image_async, the parameter returns always single value. In case of grab_data/grab_data_async it returns tuple of the size corresponding to the number of images returned through those operators. |
| 'image_raw_buffer_type' | 'image', 'blob' | 0 | string | pre-defined | Tuple of strings showing whether the last grabbed HALCON image(s) is created from buffer containing real image data with known properties (in particular image size and pixel format) or if it is created from a blob of other data (non-image data or image data of unknown format). Note that in case of the blob data the dimensions of the HALCON image are meaningless. Applies mainly in case of the 'raw' color format. Possible values are 'image' and 'blob'. See raw output format chapter. If the last successful grab was performed through grab_image/grab_image_async, the parameter returns always single value. In case of grab_data/grab_data_async it returns tuple of the size corresponding to the number of images returned through those operators. |
| 'image_region_id' | --- | 0xFFFFFFFFFFFFFFFF | integer | pre-defined | Tuple of integer values allowing to track region IDs associated to individual image outputs returned by the last grab operator. Intended for advanced use cases when the data should be matched with the device configuration. The use of the parameter is application specific and requires knowledge of the GenICam SFNC data model and specific device. If the last successful grab was performed through grab_image/grab_image_async, the parameter returns always single value. In case of grab_data/grab_data_async it returns tuple of the size corresponding to the number of images returned through those operators. If the ID could not be identified (eg. because the underlying communication protocol does not provide such information), invalid value will be returned (max value of given integer range). |
| 'image_source_id' | --- | 0xFFFFFFFFFFFFFFFF | integer | pre-defined | Tuple of integer values allowing to track source IDs associated to individual image outputs returned by the last grab operator. Intended for advanced use cases when the data should be matched with the device configuration. The use of the parameter is application specific and requires knowledge of the GenICam SFNC data model and specific device. If the last successful grab was performed through grab_image/grab_image_async, the parameter returns always single value. In case of grab_data/grab_data_async it returns tuple of the size corresponding to the number of images returned through those operators. If the ID could not be identified (eg. because the underlying communication protocol does not provide such information), invalid value will be returned (max value of given integer range). |
| 'image_width' | <width> | 0 | integer | pre-defined | Width of the last acquired image. See acquisition buffer handling. If there is no valid last buffer available, the last queried value of the 'Width' parameter of the remote device is returned. |
| 'line_in' | <default> | 0 | integer | pre-defined | The value is not used, so a default value is returned. |
| 'name' | 'GigEVision2' | 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 GigE 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 GigE 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. |
| 'raw_buffer_padding_bytes' | 0 | integer | pre-defined | Deprecated, prefer 'image_raw_buffer_padding_byptes' which supports also grab_data. For raw buffers of type 'blob' (see 'raw_buffer_type') reports the size of unused padding bytes at the end of such grabbed HALCON image. Because artificial dimensions need to be chosen for the resulting HALCON image in this case, the size of such image might not exactly equal the size of the buffer data and thus the padding might be needed. Zero is reported for buffers of type 'image'. Applies only in case of the 'raw' color format. See raw output format chapter. | |
| 'raw_buffer_type' | 'image', 'blob' | 0 | string | pre-defined | Deprecated, prefer 'image_raw_buffer_type' which supports also grab_data. Shows whether the last grabbed HALCON image is created from buffer containing real image data with known properties (in particular image size and pixel format) or if it is created from a blob of other data (non-image data or image data of unknown format). Note that in case of the blob data the dimensions of the HALCON image are meaningless. Applies mainly in case of the 'raw' color format. Possible values are 'image' and 'blob'. See raw output format chapter. |
| 'register_<addr>_<len>' | integer | pre-defined | Direct register access for reading and writing integers. The value has to be hexadecimal, e.g. 0x0938. Note that only 4 or 8 Byte length values are accepted. Caution: This is a dangerous function intended for debugging and special cases. Usually only features in the XML should be used. | ||
| 'revision' | '<revision>' | string | pre-defined | Revision number of the GigEVision2 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 GigEVision2 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. |
| 'workarounds' | ['', 'enable_range_validation' ] | '' | string | pre-defined | List of workarounds enabled by the 'workarounds' generic parameter in open_framegrabber. Individual workaround names are separated by spaces. |
The signature of the callback function is Herror (__stdcall *HAcqCallback)(void *AcqHandle, void *Context, void *UserContext) and uses the following parameters:
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.