HALCON / Image Acquisition Interfaces

Image Acquisition Interface for Alkeria USB3 devices

Interface: AlkUSB3
Revision: Windows 13.0.5.0 / Linux 13.5.0
Date: January 26, 2021
HALCON Version: 13.0 - 20.11

General

This page provides the documentation about the image acquisition interface for Alkeria USB3 cameras. Registered customers can download the latest revision of this interface from Alkeria website.

System Requirements

Parameters for info_framegrabber

Parameter Value List Type Description
'bits_per_channel' []
Unsupported query.
'camera_type' ['CAMFILE:', 'ini;xml', '<path>', 'default']
Syntax for connection configuration file and default value.
'color_space' ['default', 'mono_8', 'mono_16', 'rgb_24', 'yuv_422', 'raw_8', 'raw_16'] string
 Values for color space (see color_coding parameter).
'defaults' [0, 0, 0, 0, 0, 0, 'default', -1, 'default', -1, 'false', 'default', 'default', -1, 1] mixed Default values for open_framegrabber.
'device' ['<device_model>:<serial_number>'] string List of available device IDs. The device ID is formed by the device model and serial number.
'external_trigger' []
Unsupported query.
'field' []
Unsupported query.
'general' [] string Information about the Alkeria image acquisition interface.
'generic' ['', 'video_mode=<num>'] string
 Value list for the Generic parameter (see video_mode parameter).
'horizontal_resolution' [] integer Unsupported query.
'image_height' []
Unsupported query.
'image_width' []
Unsupported query.
'info_boards' ['<device_model> s/n <serial_number>'] string A list of available devices with corresponding serial number.
'parameters' ['<parameters>'] string Pre-defined parameters of the Alkeria image acquisition interface.
'parameters_readonly' ['<parameters>'] string Pre-defined read-only parameters of the Alkeria image acquisition interface.
'parameters_writeonly' ['<parameters>'] string Pre-defined write-only parameters of the Alkeria image acquisition interface.
'port' []
Unsupported query.
'revision' '<revision>' string Revision number of the HALCON image acquisition interface.
'start_column' []
Unsupported query.
'start_row' []
Unsupported query.
'vertical_resolution' []
Unsupported query.

Parameters for open_framegrabber

Parameter Values Default Type Description
Name 'AlkUSB3'
string Name of the Alkeria image acquisition interface.
HorizontalResolution ---

Ignored.
VerticalResolution ---

Ignored.
ImageWidth --- 0
 integer
 Sets the image_width parameter. If this argument is 0, the applied image width will be max_image_width - start_column.
ImageHeight --- 0
 integer
 Sets the image_height parameter. If this argument is 0, the applied image height will be max_image_height - start_row.
StartRow --- 0
 integer
 Sets the start_row parameter.
StartColumn --- 0 integer Sets the start_col parameter.
Field ---

Ignored.
BitsPerChannel ---

Ignored.
ColorSpace 'mono_8', 'mono_16', 'rgb_24', 'yuv_422', 'raw_8', 'raw_16' 'default'
 string
 Sets the color_coding parameter.
Note: not all the color_coding values may be available in the default video_mode 0 (usually 'raw_8' and 'raw_16' are available only in video_mode 1).
Generic ---

Ignored.
ExternalTrigger ---

Ignored.
CameraType string 'default' string Path to xml configuration file. To generate this file you can use one of the Alkeria players provided by SDK and driver package (see System requirements).
Device '0', '1', '2', ..., '9', '<device_model>:<serial_number>', 'default' '0' string The index of the capture device (passed as a string). Alternatively, you can pass the name of the capture device as it is returned by info_framegrabber(..., 'device', ...).
Port ---

Ignored.
LineIn ---

Ignored.

Parameters for set_framegrabber_param

Note that most of the following parameters (and also the valid parameter values!) depend on the capabilities of the used capture device and/or connected camera.

Parameter Values Default Type Description
'grab_timeout' <number> 10000
 integer Desired timeout (milliseconds) for aborting a pending grab. If -1 is specified, the timeout is set to INFINITE.
'do_auto_white_balance' Ignored

Performs automatic white balancing. To perform a correct white balance, camera should be in live aiming to a white background. Acquired images should not be too dark and there must be no saturation in any part of them.
'do_init' Ignored

The camera is reset to factory default.
'load_config_index' <number> 0 integer Selects the index of the flash slot that will be used by do_load_config command.
'do_load_config' Ignored

Loads camera configuration and calibration parameters from device internal flash. All the parameters can be configured using Alkeria players provided by SDK and driver package (see System requirements).
'do_software_trigger' Ignored

Issues a software trigger command.
'do_abort_grab' Ignored

Aborts the current image acquisition and unlocks parameters, that might be locked when acquisition is active.
'start_async_after_grab_async' 'true', 'false' 'true'
 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.
'volatile' 'true', 'false' 'false' 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).
'brightness'
 		<number>
integer
 The brightness coefficient applies a digital offset to each pixel value.
'contrast'
 		<number>
integer The contrast coefficient modifies (increase or decrease) the difference between the image pixel values. This can make image details more distinguishable.
'sharpness'
 		<number>
integer Image sharpness correction.
'white_balance_vr'
 		<number>
integer This property changes the tint of the white color by modifying the R over G gain ratio. Note that the property is available only if the connected camera is a color one and supports white balance control.
'white_balance_ub'
 		<number>
integer This property changes the tint of the white color by modifying the B over G gain ratio. Note that the property is available only if the connected camera is a color one and supports white balance control.
'hue'
 		<number>
integer Hue correction control.
'saturation'
 		<number>
integer Color saturation correction value.
'gamma'
 		<number>
integer The gamma correction modifies an image by applying standard, nonlinear gamma curves to the intensity scale. Increasing the gamma value will lighten the video and increase the contrast in its darker areas.
'gamma_on'
 		'true', 'false'
string Switches the gamma control on or off.
'shutter'
 		<number>
integer This control represents the integration time of the camera sensor.
'shutter_on'
 		'true', 'false'
string Switches the shutter control on or off (enable or disable sensor exposition).
'gain'
 		<number>
integer This control represents an analog gain that is usually applied directly by the image sensor.
'auto_exposure_on'
 		'true', 'false'
string Switches the auto-exposure control on or off.
'auto_exposure_limit'
 		<number>
integer Represents the maximum shutter value allowed while auto-exposure mechanism is active.
'auto_exposure_ref'
 		<number>
integer Represents the auto-exposure target value.
'lut_index'
 		<number>
integer Represents the current LUT index.
'digital_gain'
 		<number>
integer Represents an additional ditial gain that is applied to each pixel value.
'cds_gain'
 		<number>
integer Represents a property that is usually mapped to an analog gain applied directly by the image sensor.
'max_full_well_capacity'
 		<number>
integer Max full well capacity setting. See camera manual for details on this feature.
'color_correction_matrix_enabled'
 'true', 'false'
string
 Enables or disables the color correction matrix. This control applies a matrix transformation and an offset to all the RGB pixel values of the frames.

See color_correction_matrix and color_correction_offset.

When this control is enabled, the following controls will be disabled: brightness, contrast, hue, saturation.
'color_correction_matrix'
 [<number>, <number>, ...]
vector
 A 9-element vector (or matrix) representing the multiplication matrix of a linear transformation in the RGB space that is applied to each pixel of the frame.
'color_correction_offset'
 [<number>, <number>, ...]
vector
 A 3-element vector (or matrix) representing the offset vector of a linear transformation in the RGB space that is applied to each pixel of the frame.
'bandwidth_limit'
 		<number>
integer Set a limit for the whole bandwidth used by the device on each USB port.
'use_bulk_endpoint'
 		'true', 'false'
string If true (recommended), the bulk endpoint is selected for data transmition instead of isochronous endpoint.
'disable_idle_states'
 		'true', 'false'
string If true (recommended), CPU idle states are disabled during image acquisition. This option is available only on Windows platform.
'video_mode'
 		<number>
integer Sets the current video mode. This is a concept inherited from DCAM (1394-based Digital Camera Specification) standard and represents a specific mode of functioning. Different video modes may have different color_coding options and different frame resolutions.
'color_coding'
 		'mono_8', 'mono_16', 'rgb_24', 'yuv_422', 'raw_8', 'raw_16'
string Controls how camera image colors (or grey shades) are represented in the video stream. Changing this property means changing the amount of bytes needed to represent a single pixel of camera images. This may change the minimum bandwidth requirements for the image stream.

Please note that the available color codings depends on camera model and selected video_mode.
'adc_resolution'
 		<number>
integer This affects the resolution for the main analog to digital conversion operation that is usually performed by the image sensor.
'image_width'
 		<number>
integer Sets the desired width of the received portion of the sensor scanned area (partial scan region of interest, shortly ROI).
'image_height'
 		<number>
integer Sets the desired height of the received portion of the sensor scanned area (partial scan region of interest, shortly ROI).
'start_row'
 		<number>
integer Sets the desired top offset of the received portion of the sensor scanned area (partial scan region of interest, shortly ROI).
'start_column'
 		<number>
integer Sets the desired left offset of the received portion of the sensor scanned area (partial scan region of interest, shortly ROI).
'frame_combiner_size'
 		<number>
integer When this property value is greater than 1, a set of multiple acquired frames are stacked vertically and combined into a single one.
'frame_combiner_timeout'
 		<number>
integer Sets a timeout period [ms] for the frame combiner device. When the timeout has elapsed the current partial combined frame is flushed.
'frame_combiner_external_flush_enabled'
 		'true', 'false'
string Enabling external frame combiner flush allows flushing partial combined frames driven by an external signal.
'frame_combiner_external_flush_port'
 		<number>
integer When frame_combiner_external_flush_enabled is true, this property selects the index of the external port used to detect flush commands.
'frame_combiner_invert_external_flush'
 		'rising', 'falling'
string When frame_combiner_external_flush_enabled is true, this property controls the polarity of the external flush signal.
'do_frame_combiner_flush'
 		Ignored

Manually flushes the frame combiner image combination.
'packet_size'
 		<number>
integer Controls the size in KiB of the desired USB3 packet.

This is the amount of data that is transmitted by the device to the PC every 125 microseconds. This time period is called a microframe and is defined in the USB3 specification. For USB 3.0 and 3.1 the maximum amount of data that can be transferred during a single microframe is 48 KiB. When a value smaller than 48 KiB is selected, the bandwidth used is reduced and the device may not be able to reach its maximum performances.

For devices with multiple USB3 connectors, this property represents the total amount of data transmitted through all the available USB3 ports and may assume values greater than 48 KiB.
'frame_rate'
 		<number>
integer The desired frame rate expressed in Hz. Some other camera settings (e.g. exposure time) may have such values that prevent the camera from reaching the desired frame rate. In these cases the actual frame rate may be lower than the desired one.
'line_period'
 		<number>
integer For line sensors only, controls the desired period between consecutive exposures. For time units, please refer to the software or camera manual.
'preserve_rates'
 		'true', 'false'
string If false, the device tries to always reach maximum performances in term of 'frame_rate' upon any change in video settings.

Video settings are not independent from each others. When the user modifies the ROI size, the adc_resolution or one of other video settings, the maximum frame_rate, the
minimum line_period and the minimum required packet_size may change. As a consequence, the maximum performance that the device can reach may change as the user configures it.

In order to always reach the maximum performances in terms of image acquisition rate, after a change in video_mode, color_coding, adc_resolution or image_width, the device may try to reconfigure itself to reach maximum acquisition rate. For instance, it may set packet_size, frame_rate and line_period values that let the device acquiring images at the maximum allowed rate.

If you want to avoid such behavior, you can set this property to true.
'disable_overlap'
 		'true', 'false'
string Disables the frame exposure / download overlap.

With some sensors, disabling the time overlap between frame exposure and download can increase the
precision of the actual sensor integration time, with respect to the shutter time requested by the user.

Setting this option to true will reduce the maximum frame_rate.
'line_delay'
 		'true', 'false'
string The line delay feature can improve image quality in color line scan cameras that feature two adjacent lines sensitive to color components according to the Bayer filter; for a proper color reconstruction, the delay between the exposure of the two rows should equal the time for the target projection onto the sensor to move from one row to the adjacent one.

The line delay control delays the exposure between the two sensor lines by the currently-set line_period.
'line_delay_direction'
 		'forward', 'reverse'
string The direction of the line_delay feature.
'horizontal_binning'
 		<number>
integer This is the horizontal binning factor. When this property has a value greater than 1, the total image_width is reduced by this factor.
'vertical_binning'
 		<number>
integer This is the vertical binning factor. When this property has a value greater than 1, the total image_height is reduced by this factor.
'acquisition_burst_length'
 		<number>
integer Sets the number of frames that will be acquired upon the issue of acquisition_start_trigger, when this module is enabled.
'trigger_selector'
 		'acquisition_start', 'frame_start', 'line_start', 'exposure_end'
string Selects one of the four available trigger modules (this will affect all the subsequent accesses to all the properties that start with 'trigger_').
'trigger_source'
 		'external', 'software', 'pll', 'encoder', 'encoder_once'
string Sets the trigger source for the module selected by trigger_selector.
'trigger_enabled'
 		<number>
integer Enables or disables the module selected by trigger_selector.
'trigger_external_port'
 		<number>
integer When 'external' is selected as trigger_source, this property selects the index of the external port used to detect triggering conditions for the module selected by trigger_selector.
'trigger_detect_external_port_edge'
 		'true', 'false'
string If true, the trigger module selected by trigger_selector is sensible to external input edges instead of signal level.
'trigger_invert_external_port_polarity'
 		'true', 'false'
string If true, the external input signal is inverted before being evaluated (i.e. rising edges becomes falling and high levels becomes low) by the module selected by trigger_selector.
'trigger_delay'
 		<number>
integer This is the time interval between the trigger detection and the actual frame exposition. If the delay time is greater than 0, this property can be used to delay the start of exposition with respect to a trigger source.

Please refer to the camera manual for the delay time units. The property applies to the module selected by trigger_selector.
'trigger_encoder_interval'
 		<number>
integer When 'encoder_position' is selected as trigger_source, this property controls the number of encoder steps that generates a trigger event in the module selected by trigger_selector.
'trigger_encoder_delay'
 		<number>
integer The trigger delay for the module selected as trigger_source, expressed as number of encoder steps.
This is the number of encoder steps that the triggering module waits before issuing the trigger, once the triggering condition is true.
'encoder_ignore_direction'
 		'true', 'false'
string If true the encoder rotation direction is ignored and the internal position register is incremented regardless of the direction.
'encoder_invert_direction'
 		'true', 'false'
string Inverts the encoder expected rotaion direction.
'encoder_input_a'
 		<number>
integer Select the external pin to use as encoder phase input signal.
'encoder_input_b'
 		<number>
integer Selects the external pin to use as encoder quadrature input signal.
'do_encoder_reset'
 		Ignored

When the encoder_reset_source is set to 'software', this method resets encoder_position to 0.
'encoder_reset_source'
 		'external', 'software'
string The encoder reset source (resetting the encoder sets encoder_position to 0).
'encoder_reset_external_port'
 		<number>
integer When 'external' is selected as encoder_reset_source, this property selects the index of the external port used.
'encoder_reset_detect_external_port_edge'
 		'true', 'false'
string If true, the encoder reset module is sensible to external input edges instead of signal level.
'encoder_reset_invert_external_port_polarity'
 		'true', 'false'
string If true, the external reset input signal is inverted before being evaluated (i.e. rising edges becomes falling and high levels becomes low).
'pll_multiplier'
 		<number>
integer The PLL frequency multiplier.
'pll_divisor'
 		<number>
integer The PLL frequency divisor.
'pll_source'
 		'external', 'encoder_tick'
string The PLL source.
'pll_external_port'
 		<number>
integer When 'external' is selected as pll_source, this property selects the index of the external port used to detect triggering conditions.
'strobe_start'
 		<number>
integer Strobe start delay time. The strobe signal goes high when this period of time has elapsed since exposure began.
'strobe_end'
 		<number>
integer Strobe end delay time. The strobe signal goes low when this period of time has elapsed since exposure began.
'pio_selector'
 		<number>
integer Selects one of the available programmable IO ports (this will affect all the subsequent accesses to all the properties that start with 'pio_').
'pio_direction'
 		'output', 'input'
string If the port selected by pio_selector is a bidirectional port, this properties controls port direction.
'pio_termination'
 		'true', 'false'
string If the port selected by pio_selector is in input mode, this property enables or disables input termination.
'pio_invert_output'
 		'true', 'false'
string If the port selected by pio_selector is in output mode, this property enables or disables output signal inversion.
'pio_output_source'
 		'manual', 'acquisition_start_trigger', 'frame_start_trigger', 'line_start_trigger', 'exposure', 'strobe', 'sensor_readout', 'acquisition_start_trigger_ready', 'frame_start_trigger_ready', 'line_start_trigger_ready', 'exposure_end_trigger', 'exposure_end_trigger_ready', 'uart_tx', 'burst_active'
string If the port selected by pio_selector is in output mode, this property select the signal to be routed to the output pin.
'pio_debounce_time'
 		<number>
integer If the port selected by pio_selector is in input mode, this property controls input debounce time.
'pio_value'
 		'true', 'false'
string If the port selected by pio_selector is in output mode and has pio_output_source as 'manual', this property directly controls the logic value on the output pin.
'pio_slow_mode'
 		'true', 'false'
string If true, the slew rate of the port selected by pio_selector is limited (please refer to the camera manual for more details).
'pio_open_collector_mode'
 		'true', 'false'
string If true, the port selected by pio_selector is set in open-collector mode (please refer to the camera manual for more details).
'pio_power_off_port'
 		'true', 'false'
string If true, the port selected by pio_selector is powered off.
'pio_high_threshold'
 		'true', 'false'
string If true, the high alternate threshold value is enabled for all the input ports (please refer to the camera manual for more details).
'pio_high_voltage_out'
 		'true', 'false'
string If true, the high alternate output value is enabled for all the input ports (please refer to the camera manual for more details).
'pio_shut_down'
 		'true', 'false'
string If true, all the PIO ports are disabled (power save mode).
'sequencer_page'
 		<number>
integer This is the currently selected sequencer page (0 based).
'sequencer_first_page'
 		<number>
integer The number of the first page of the sequence.

If sequencer is enabled, the page number is set to this value at acquisition start or whenever a reset signal is received.
'sequencer_last_page'
 		<number>
integer The number of the last page of the sequence.
'sequencer_loop_enable'
 		'true', 'false'
string When true, the sequencer applies values from first_page to last_page and then it starts back from the beginning. When false, it stops on last_page until a reset signal is received.
'sequencer_enable'
 		'true', 'false'
string Enables or disables the sequencer module.
'sequencer_reset_source'
 		'external', 'software'
string The source of the sequence reset signal.
'sequencer_reset_external_port'
 		<number>
integer When the external input is selected as sequencer_reset_source, this property selects the index of the external port used to detect reset conditions.
'sequencer_detect_reset_external_port_edge'
 		'true', 'false'
string If true, the sequencer module is sensible to external input edges instead of signal level. This is valid only for reset signal.
'sequencer_invert_reset_external_port'
 		'true', 'false'
string If true, the external input signal is inverted before being evaluated (i.e. rising edges becomes falling and high levels becomes low). This is valid only for reset signal.
'do_sequencer_page_reset'
 		Ignored

When the sequencer_reset_source is set to software and the sequencer is enabled, this method resets the sequence page.
'sequencer_increment_source'
 		'external', 'software', 'frame_start'
string The source of the sequence increment signal.
'sequencer_increment_external_port'
 		<number>
integer When the external input is selected as sequencer_increment_source, this property selects the index of the external port used to detect reset conditions.
'sequencer_detect_increment_external_port_edge'
 		'true', 'false'
string If true, the sequencer module is sensible to external input edges instead of signal level. This is valid only for page-increment signal.
'sequencer_invert_increment_external_port'
 		'true', 'false'
string If true, the external input signal is inverted before being evaluated (i.e. rising edges becomes falling and high levels becomes low). This is valid only for page-increment signal.
'do_sequencer_page_increment'
 		Ignored

When the sequencer_increment_source is set to software and the sequencer is enabled, this method resets the sequence page.
'event_selector'
 		'transfer_end'
string
 Selects an event for wich a message queue will be registered (see Events).
'event_message_queue'
 		<queue_handle>
handle Selects a message queue to which the acquisition interface should send event notifications for the event selected by event_selector.
'white_balance_blue'
 		<number>
integer This property changes the tint of the white color by modifying the Blue gain.
This function has effect only if enable_white_balance is set to 'false'.
Note that the function is available only if the connected camera is a color camera and supports white balance control.
'white_balance_green'
 		<number>
integer This property changes the tint of the white color by modifying the Green gain.
This function has effect only if enable_white_balance is set to 'false'.
Note that the function is available only if the connected camera is a color camera and supports white balance control.
'white_balance_red'
 		<number>
integer This property changes the tint of the white color by modifying the Red gain.
This function has effect only if enable_white_balance is set to 'false'.
Note that the function is available only if the connected camera is a color camera and supports white balance control.
'enable_white_balance'
 		'true', 'false'
string Switches the white balance control on or off.

Parameters for get_framegrabber_param

There may exist additional read-only parameters with the following postfixes:

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 Description
'available_callback_types' ['<callback_types>']
string Returns a list containing all the events for which a callback can be registered (see set_framegrabber_callback).
'available_param_names'


Returns a list of all the available parameters for set_framegrabber_param or get_framegrabber_param.
'grab_timeout' <milliseconds> 10000 integer Current grab timeout in milliseconds.
'load_config_index' <number> 0 integer Selects the index of the flash slot that will be used by do_load_config command.
'start_async_after_grab_async' 'true', 'false' 'true' string Current value of start_async_after_grab_async parameter.
'volatile' 'true', 'false' 'false' mixed Current value of volatile parameter.
'brightness'
 		<number>
integer
 The brightness coefficient applies a digital offset to each pixel value.
'contrast'
 		<number>
integer The contrast coefficient modifies (increase or decrease) the difference between the image pixel values. This can make image details more distinguishable.
'sharpness'
 		<number>
integer Image sharpness correction.
'white_balance_vr'
 		<number>
integer This property changes the tint of the white color by modifying the R over G gain ratio. Note that the property is available only if the connected camera is a color one and supports white balance control.
'white_balance_ub'
 		<number>
integer This property changes the tint of the white color by modifying the B over G gain ratio. Note that the property is available only if the connected camera is a color one and supports white balance control.
'hue'
 		<number>
integer Hue correction control.
'saturation'
 		<number>
integer Color saturation correction value.
'gamma'
 		<number>
integer The gamma correction modifies an image by applying standard, nonlinear gamma curves to the intensity scale. Increasing the gamma value will lighten the video and increase the contrast in its darker areas.
'gamma_on'
 		'true', 'false'
string Switches the gamma control on or off.
'shutter'
 		<number>
integer This control represents the integration time of the camera sensor.
'shutter_on'
 		'true', 'false'
string Switches the shutter control on or off (enable or disable sensor exposition).
'gain'
 		<number>
integer This control represents an analog gain that is usually applied directly by the image sensor.
'auto_exposure_on'
 		'true', 'false'
string Switches the auto-exposure control on or off.
'auto_exposure_limit'
 		<number>
integer Represents the maximum shutter value allowed while auto-exposure mechanism is active.
'auto_exposure_ref'
 		<number>
integer Represents the auto-exposure target value.
'lut_index'
 		<number>
integer Represents the current LUT index.
'digital_gain'
 		<number>
integer Represents an additional ditial gain that is applied to each pixel value.
'cds_gain'
 		<number>
integer Represents a property that is usually mapped to an analog gain applied directly by the image sensor.
'max_full_well_capacity'
 		<number>
integer Max full well capacity setting. See camera manual for details on this feature.
'color_correction_matrix_enabled'
 'true', 'false'
string
 Enables or disables the color correction matrix. This control applies a matrix transformation and an offset to all the RGB pixel values of the frames.

See color_correction_matrix and color_correction_offset.

When this control is enabled, the following controls will be disabled: brightness, contrast, hue, saturation.
'color_correction_matrix'
 [<number>, <number>, ...]
vector
 A 9-element vector (or matrix) representing the multiplication matrix of a linear transformation in the RGB space that is applied to each pixel of the frame.
'color_correction_offset'
 [<number>, <number>, ...]
vector
 A 3-element vector (or matrix) representing the offset vector of a linear transformation in the RGB space that is applied to each pixel of the frame.
'bandwidth_limit'
 		<number>
integer Set a limit for the whole bandwidth used by the device on each USB port.
'use_bulk_endpoint'
 		'true', 'false'
string If true (recommended), the bulk endpoint is selected for data transmition instead of isochronous endpoint.
'disable_idle_states'
 		'true', 'false'
string If true (recommended), CPU idle states are disabled during image acquisition. This option is available only on Windows platform.
'video_mode'
 		<number>
integer Sets the current video mode. This is a concept inherited from DCAM (1394-based Digital Camera Specification) standard and represents a specific mode of functioning. Different video modes may have different color_coding options and different frame resolutions.
'color_coding'
 		'mono_8', 'mono_16', 'rgb_24', 'yuv_422', 'raw_8', 'raw_16'
string Controls how camera image colors (or grey shades) are represented in the video stream. Changing this property means changing the amount of bytes needed to represent a single pixel of camera images. This may change the minimum bandwidth requirements for the image stream.
'adc_resolution'
 		<number>
integer This affects the resolution for the main analog to digital conversion operation that is usually performed by the image sensor.
'image_width'
 		<number>
integer Gets the desired width of the received portion of the sensor scanned area (partial scan region of interest, shortly ROI).
'image_height'
 		<number>
integer Gets the desired height of the received portion of the sensor scanned area (partial scan region of interest, shortly ROI).
'start_row'
 		<number>
integer Sets the desired top offset of the received portion of the sensor scanned area (partial scan region of interest, shortly ROI).
'start_column'
 		<number>
integer Sets the desired left offset of the received portion of the sensor scanned area (partial scan region of interest, shortly ROI).
'frame_combiner_size'
 		<number>
integer When this property value is greater than 1, a set of multiple acquired frames are stacked vertically and combined into a single one.
'frame_combiner_timeout'
 		<number>
integer Sets a timeout period [ms] for the frame combiner device. When the timeout has elapsed the current partial combined frame is flushed.
'frame_combiner_external_flush_enabled'
 		'true', 'false'
string Enabling external frame combiner flush allows flushing partial combined frames driven by an external signal.
'frame_combiner_external_flush_port'
 		<number>
integer When frame_combiner_external_flush_enabled is true, this property selects the index of the external port used to detect flush commands.
'frame_combiner_invert_external_flush'
 		'true', 'false'
string When frame_combiner_external_flush_enabled is true, this property controls the polarity of the external flush signal.
'packet_size'
 		<number>
integer Controls the size in KiB of the desired USB3 packet.

This is the amount of data that is transmitted by the device to the PC every 125 microseconds. This time period is called a microframe and is defined in the USB3 specification. For USB 3.0 and 3.1 the maximum amount of data that can be transferred during a single microframe is 48 KiB. When a value smaller than 48 KiB is selected, the bandwidth used is reduced and the device may not be able to reach its maximum performances.

For devices with multiple USB3 connectors, this property represents the total amount of data transmitted through all the available USB3 ports and may assume values greater than 48 KiB.
'frame_rate'
 		<number>
integer The desired frame rate expressed in Hz. Some other camera settings (e.g. exposure time) may have such values that prevent the camera from reaching the desired frame rate. In these cases the actual frame rate may be lower than the desired one.
'line_period'
 		<number>
integer For line sensors only, controls the desired period between consecutive exposures. For time units, please refer to the software or camera manual.
'preserve_rates'
 		'true', 'false'
string If false, the device tries to always reach maximum performances in term of 'frame_rate' upon any change in video settings.

Video settings are not independent from each others. When the user modifies the ROI size, the adc_resolution or one of other video settings, the maximum frame_rate, the
minimum line_period and the minimum required packet_size may change. As a consequence, the maximum performance that the device can reach may change as the user configures it.

In order to always reach the maximum performances in terms of image acquisition rate, after a change in video_mode, color_coding, adc_resolution or image_width, the device may try to reconfigure itself to reach maximum acquisition rate. For instance, it may set packet_size, frame_rate and line_period values that let the device acquiring images at the maximum allowed rate.

If you want to avoid such behavior, you can set this property to true.
'disable_overlap'
 		'true', 'false'
string Disables the frame exposure / download overlap.

With some sensors, disabling the time overlap between frame exposure and download can increase the
precision of the actual sensor integration time, with respect to the shutter time requested by the user.

Setting this option to true will reduce the maximum frame_rate.
'line_delay'
 		'true', 'false'
string The line delay feature can improve image quality in color line scan cameras that feature two adjacent lines sensitive to color components according to the Bayer filter; for a proper color reconstruction, the delay between the exposure of the two rows should equal the time for the target projection onto the sensor to move from one row to the adjacent one.

The line delay control delays the exposure between the two sensor lines by the currently-set line_period.
'line_delay_direction'
 		'forward', 'reverse'
string The direction of the line_delay feature.
'horizontal_binning'
 		<number>
integer This is the horizontal binning factor. When this property has a value greater than 1, the total image_width is reduced by this factor.
'vertical_binning'
 		<number>
integer This is the vertical binning factor. When this property has a value greater than 1, the total image_height is reduced by this factor.
'acquisition_burst_length'
 		<number>
integer Gets the number of frames that will be acquired upon the issue of acquisition_start_trigger, when this module is enabled.
'trigger_selector'
 		'acquisition_start', 'frame_start', 'line_start', 'exposure_end'
string Selects one of the four available trigger modules (this will affect all the subsequent accesses to all the properties that start with 'trigger_').
'trigger_source'
 		'external', 'software', 'pll', 'encoder', 'encoder_once'
string Gets the trigger source for the module selected by trigger_selector.
'trigger_enabled'
 		<number>
integer Enables or disables the module selected by trigger_selector.
'trigger_external_port'
 		<number>
integer When 'external' is selected as trigger_source, this property selects the index of the external port used to detect triggering conditions for the module selected by trigger_selector.
'trigger_detect_external_port_edge'
 		'true', 'false'
string If true, the trigger module selected by trigger_selector is sensible to external input edges instead of signal level.
'trigger_invert_external_port_polarity'
 		'true', 'false'
string If true, the external input signal is inverted before being evaluated (i.e. rising edges becomes falling and high levels becomes low) by the module selected by trigger_selector.
'trigger_delay'
 		<number>
integer This is the time interval between the trigger detection and the actual frame exposition. If the delay time is greater than 0, this property can be used to delay the start of exposition with respect to a trigger source.

Please refer to the camera manual for the delay time units. The property applies to the module selected by trigger_selector.
'trigger_encoder_interval'
 		<number>
integer When 'encoder_position' is selected as trigger_source, this property controls the number of encoder steps that generates a trigger event in the module selected by trigger_selector.
'trigger_encoder_delay'
 		<number>
integer The trigger delay for the module selected as trigger_source, expressed as number of encoder steps.
This is the number of encoder steps that the triggering module waits before issuing the trigger, once the triggering condition is true.
'encoder_ignore_direction'
 		'true', 'false'
string If true the encoder rotation direction is ignored and the internal position register is incremented regardless of the direction.
'encoder_invert_direction'
 		'true', 'false'
string Inverts the encoder expected rotaion direction.
'encoder_input_a'
 		<number>
integer Select the external pin to use as encoder phase input signal.
'encoder_input_b'
 		<number>
integer Selects the external pin to use as encoder quadrature input signal.
'encoder_position'
 		<number>
integer Reads the current encoder position.
'encoder_reget_source'
 		'external', 'software'
string The encoder reset source (resetting the encoder sets the encoder_position to 0).
'encoder_reget_external_port'
 		<number>
integer When 'external' is selected as encoder_reget_source, this property selects the index of the external port used.
'encoder_reget_detect_external_port_edge'
 		'true', 'false'
string If true, the encoder reset module is sensible to external input edges instead of signal level.
'encoder_reget_invert_external_port_polarity'
 		'true', 'false'
string If true, the external reset input signal is inverted before being evaluated (i.e. rising edges becomes falling and high levels becomes low).
'pll_multiplier'
 		<number>
integer The PLL frequency multiplier.
'pll_divisor'
 		<number>
integer The PLL frequency divisor.
'pll_source'
 		'external', 'encoder_tick'
string The PLL source.
'pll_external_port'
 		<number>
integer When 'external' is selected as pll_source, this property selects the index of the external port used to detect triggering conditions.
'strobe_start'
 		<number>
integer Strobe start delay time. The strobe signal goes high when this period of time has elapsed since exposure began.
'strobe_end'
 		<number>
integer Strobe end delay time. The strobe signal goes low when this period of time has elapsed since exposure began.
'pio_selector'
 		<number>
integer Selects one of the available programmable IO ports (this will affect all the subsequent accesses to all the properties that start with 'pio_').
'pio_direction'
 		'output', 'input'
string If the port selected by pio_selector is a bidirectional port, this properties controls port direction.
'pio_termination'
 		'true', 'false'
string If the port selected by pio_selector is in input mode, this property enables or disables input termination.
'pio_invert_output'
 		'true', 'false'
string If the port selected by pio_selector is in output mode, this property enables or disables output signal inversion.
'pio_output_source'
 		'manual', 'acquisition_start_trigger', 'frame_start_trigger', 'line_start_trigger', 'exposure', 'strobe', 'sensor_readout', 'acquisition_start_trigger_ready', 'frame_start_trigger_ready', 'line_start_trigger_ready', 'exposure_end_trigger', 'exposure_end_trigger_ready', 'uart_tx', 'burst_active'
string If the port selected by pio_selector is in output mode, this property select the signal to be routed to the output pin.
'pio_debounce_time'
 		<number>
integer If the port selected by pio_selector is in input mode, this property controls input debounce time.
'pio_value'
 		'true', 'false'
string If the port selected by pio_selector is in output mode and has pio_output_source as 'manual', this property directly controls the logic value on the output pin.

If the port is in input mode, this property reads back the logic value detected on the pin.
'pio_slow_mode'
 		'true', 'false'
string If true, the slew rate of the port selected by pio_selector is limited (please refer to the camera manual for more details).
'pio_open_collector_mode'
 		'true', 'false'
string If true, the port selected by pio_selector is set in open-collector mode (please refer to the camera manual for more details).
'pio_power_off_port'
 		'true', 'false'
string If true, the port selected by pio_selector is powered off.
'pio_high_threshold'
 		'true', 'false'
string If true, the high alternate threshold value is enabled for all the input ports (please refer to the camera manual for more details).
'pio_high_voltage_out'
 		'true', 'false'
string If true, the high alternate output value is enabled for all the input ports (please refer to the camera manual for more details).
'pio_shut_down'
 		'true', 'false'
string If true, all the PIO ports are disabled (power save mode).
'sequencer_page'
 		<number>
integer This is the currently selected sequencer page (0 based).
'sequencer_first_page'
 		<number>
integer The number of the first page of the sequence.

If sequencer is enabled, the page number is set to this value at acquisition start or whenever a reset signal is received.
'sequencer_last_page'
 		<number>
integer The number of the last page of the sequence.
'sequencer_loop_enable'
 		'true', 'false'
string When true, the sequencer applies values from first_page to last_page and then it starts back from the beginning. When false, it stops on last_page until a reset signal is received.
'sequencer_enable'
 		'true', 'false'
string Enables or disables the sequencer module.
'sequencer_reset_source'
 		'external', 'software'
string The source of the sequence reset signal.
'sequencer_reset_external_port'
 		<number>
integer When the external input is selected as sequencer_reset_source, this property selects the index of the external port used to detect reset conditions.
'sequencer_detect_reset_external_port_edge'
 		'true', 'false'
string If true, the sequencer module is sensible to external input edges instead of signal level. This is valid only for reset signal.
'sequencer_invert_reset_external_port'
 		'true', 'false'
string If true, the external input signal is inverted before being evaluated (i.e. rising edges becomes falling and high levels becomes low). This is valid only for reset signal.
'sequencer_increment_source'
 		'external', 'software', 'frame_start'
string The source of the sequence increment signal.
'sequencer_increment_external_port'
 		<number>
integer When the external input is selected as sequencer_increment_source, this property selects the index of the external port used to detect reset conditions.
'sequencer_detect_increment_external_port_edge'
 		'true', 'false'
string If true, the sequencer module is sensible to external input edges instead of signal level. This is valid only for page-increment signal.
'sequencer_invert_increment_external_port'
 		'true', 'false'
string If true, the external input signal is inverted before being evaluated (i.e. rising edges becomes falling and high levels becomes low). This is valid only for page-increment signal.
'event_selector'
 		'transfer_end'
string
 Selects an event for wich a message queue will be registered (see Events).
'white_balance_blue'
 		<number>
integer This property changes the tint of the white color by modifying the Blue gain.
This function has effect only if enable_white_balance is set to 'false'.
Note that the function is available only if the connected camera is a color camera and supports white balance control.
'white_balance_green'
 		<number>
integer This property changes the tint of the white color by modifying the Green gain.
This function has effect only if enable_white_balance is set to 'false'.
Note that the function is available only if the connected camera is a color camera and supports white balance control.
'white_balance_red'
 		<number>
integer This property changes the tint of the white color by modifying the Red gain.
This function has effect only if enable_white_balance is set to 'false'.
Note that the function is available only if the connected camera is a color camera and supports white balance control.
'enable_white_balance'
 		'true', 'false'
string Switches the white balance control on or off.

Operator set_framegrabber_lut

Not supported by this interface.

Operator get_framegrabber_lut

Not supported by this interface.

Operator set_framegrabber_callback

Set a callback function that will be executed when the selected event happens.

The following events are supported:
See set_framegrabber_callback for more details about the signature of the callback function.

Operator get_framegrabber_callback

Get the current callback set for the selected event (if any). See get_framegrabber_callback for more details.

Operator grab_image_start

Starts a new asynchronous grab. See also grab_image_start.

Operator grab_image

grab_image starts a new synchronous grab. See also grab_image.

Operator grab_image_async

grab_image_async returns an image and, if start_async_after_grab_async is true, starts the next asynchronous grab. See also grab_image_async.

Operator grab_data

Not supported by this interface.

Operator grab_data_async

Not supported by this interface.

Operator close_framegrabber

This operator closes the device. See also close_framegrabber.

Events

This interface supports events via message queues. You can select the desired event with set_framegrabber_param(..., 'event_selector', ...) and then connect a queue that will receive event notifications with set_framegrabber_param(..., 'event_message_queue', ...).

The following events are supported:

Note that the interface keeps just a single registration for every event, if you attempt to register a new message queue for a feature that already had a message queue registered, the previous registration will be replaced with the new one.

The messages incoming on an event can be retrieved with dequeue_message and will contain at least two tuples. The first tuple (key 'device') is a unique identifier of the acquisition instance the event is coming from. It is a string composed as 'AlkUSB3:<device_model>:<serial_number>' (see info_framegrabber(..., 'device', ...). The second tuple (key 'event_name') is the name of the corresponding event previously specified by event_selector.

HDevelop Examples

For this interface the following examples are available in %HALCONROOT%\examples\hdevelop\Image\Acquisition:

Release Notes

Copyright notes: © Copyright Alkeria Srl. All rights reserved. Unless otherwise stated, the copyright and similar rights in the contents of this page, including but not limited to all text, designs and images appearing herein, are copyrighted works owned by Alkeria Srl.