get_image_source_param — Return the value of an image source parameter.
get_image_source_param( : : ImageSourceHandle, Param, GenParamName, GenParamValue : Value)
The operator get_image_source_param returns the parameter
values or parameter properties for an image source handle
ImageSourceHandle in Value.
For further information about the image source concept see Image Source.
The parameter needs to be specified using Param.
It depends on the image source and its state, which parameters are
available. Device parameters are specific to the hardware or software
manufacturer.
The parameter group can be specified using the generic parameters.
There are two types of information to be retrieved from the parameter
Param. Use the generic parameter GenParamName to
differentiate whether you want to get the value or meta information
regarding the parameter.
You have the following options for GenParamName:
Specify the parameter group the parameter is found in with
GenParamValue by setting one of these options:
'image_source',
'plugin',
'interface',
'local_device',
'device',
'easy_device',
'stream'.
When setting no generic parameters, GenParamName = 'group'
and GenParamValue = 'device' are assumed by default.
The group 'image_source' is always available, whereas a connection is needed for the other parameter groups.
Retrieve meta information about Param.
Specify the requested parameter property with GenParamValue
by setting one of these options:
'access': Provides access permissions as a string.
List of values: 'na' ((currently) not available), 'ro' (read-only), 'rw' (read/write), 'wo' (write-only).
'description': Provides a description of the parameter as a string.
'display_name': Provides the display name of the parameter as a string.
'increment': Provides the step width of the parameter as a real or integer value, depending on the data type of the parameter.
'max': Provides the maximum value of the parameter as a real or integer value, depending on the data type of the parameter.
'min': Provides the minimum value of the parameter as a real or integer value, depending on the data type of the parameter.
'persistable': Provides information about the persistence of the parameter as an integer.
List of values: 0 (false), 1 (true).
'tooltip': Provides a short description of the parameter.
'type': Provides the parameter type as a string.
List of values: 'boolean', 'command', 'enumeration' (string out of a list of allowed strings), 'integer', 'real', 'register', 'string'.
'values': Provides a list of all allowed values for parameters of 'type' = 'enumeration' and for some of 'type' 'integer' and 'real'.
'visibility': Provides information about the visibility of the parameter.
List of values: 'basic', 'advanced', 'all'.
Parameters of the 'image_source' group are always available.
The following table gives an overview, which
of those parameters can be set using set_image_source_param and
which can be retrieved using get_image_source_param.
A description of the parameters can be found below the table.
GenParamName |
set |
get |
|---|---|---|
| 'device_access_flags' | x |
x |
| 'device_access_status' | x |
|
| 'device_connect_mode' | x |
|
| 'device_id' | x |
x |
| 'device_is_connected' | x |
|
| 'device_query_timeout' | x |
x |
| 'device_user_name' | x |
x |
| 'device_serial_number' | x |
x |
| 'fetch_timeout' | x |
x |
| 'interface_connect_mode' | x |
|
| 'interface_display_name' | x |
|
| 'interface_id' | x |
x |
| 'interface_is_connected' | x |
|
| 'interface_query_timeout' | x |
x |
| 'num_buffers' | x |
x |
| 'plugin_connect_mode' | x |
|
| 'plugin_is_connected' | x |
|
| 'plugin_name' | x |
x |
| 'plugin_path' | x |
x |
| 'stream_connect_mode' | x |
|
| 'stream_id' | x |
x |
| 'stream_is_connected' | x |
|
| 'stream_state' | x |
|
| 'version' | x
|
GenTL access flags used when attempting to connect to the device.
'control': Open the device in a way that other hosts/processes can have read-only access to the device. Device access level is read/write for this process.
'exclusive': Open the device in a way that only this host/process can have access to the device. Device access level is read/write for this process.
'none': Either the device is not open because it was not opened before or the access to it was denied.
'read_only': Open the device read-only. All port functions can only read from the device.
'unknown': Not used in a command. Can be used to initialize a variable to query that information.
Current GenTL access status of the device.
'busy': Device has already been opened in 'exclusive' mode by another process/host.
'open_read_only': Device has already been opened by this process. Connection is set up in read-only mode, a different application has the 'control' mode (see 'device_access_flags').
'open_read_write': Device has already been opened by this process and handled in 'exclusive' or 'control' mode (see 'device_access_flags').
'no_access': Device is not accessible (no connection possible).
'read_only': Device is available for read-only access.
'read_write': Device is available for read/write access (see 'device_access_flags').
'unknown': Device accessibility is not known.
Connect mode for the device module.
'automatic': No identifier is provided, the required module will be automatically found and connected.
'exact': A module identifier has been indicated for the module connection.
'none': Module connection not needed.
ID of the device as a string. It can be
used to specify the device module to open during
connect_image_source.
Connection status of the device as an integer.
List of values: 0 (unconnected), 1 (connected).
Desired timeout [ms] for aborting a pending device query. Is used as the device discovery timeout in GigEVision transport layers. If -1 is specified, the timeout is set to infinite.
Default: 1100
Serial number of the device as a string. It can be used to specify which device to connect to when preferring not to use 'device_id'.
User name of the device as a string. It can be used to specify which device to connect to when preferring not to use 'device_id'.
Desired timeout [ms] for aborting a pending grab. If -1 is specified, the timeout is set to infinite.
Default: 5000
Connect mode for the interface module.
'automatic': No identifier is provided, the required module will be automatically found and connected.
'exact': A module identifier has been indicated for the module connection.
'none': Module connection not needed.
Provides a human-readable secondary identifier for the interface module as a string.
ID of the interface as a string. It can be
used to specify the interface module to open during
connect_image_source.
Connection status of the interface as an integer.
List of values: 0 (unconnected), 1 (connected).
Desired timeout [ms] for aborting a pending interface query. If -1 is specified, the timeout is set to infinite.
Default: 1100
Number of buffers that will be prepared
by start_image_source for receiving images.
A larger number of buffers can help preventing image loss in short
peak loads of the host system.
The number of buffers can only be changed before starting the acquisition
with start_image_source.
Default: 4
Connect mode for the plugin module.
'automatic': No identifier is provided, the required module will be automatically found and connected.
'exact': A module identifier has been indicated for the module connection.
'none': Module connection not needed.
Connection status of the plugin as an integer.
List of values: 0 (unconnected), 1 (connected).
Name of the plugin as a string.
Path to the .cti plugin file.
Can be used to specify the plugin file even when the GenTL environment
variables to detect plugins do not contain the location of the desired
plugin file.
Connect mode for the stream module.
'automatic': No identifier is provided, the required module will be automatically found and connected.
'exact': A module identifier has been indicated for the module connection.
'none': Module connection not needed.
ID of the stream as a string. Can be
used to specify the stream module to open during
connect_image_source.
Connection status of the stream as an integer.
List of values: 0 (unconnected), 1 (connected).
Current state of the stream.
'initialized': Stream is initialized but not running.
'running': Stream is currently running. This means resources like threads and buffers are allocated in order to receive images. Depending on the device configuration, images are constantly transmitted in the background in this state.
Version of the image source library.
Parameters of the 'easy_device' group become available after
successfully connecting to a device using connect_image_source.
While the following parameters are implemented, the availability of
individual parameters in this group depends on the connected device.
Specifies the exposure time. Higher exposure time makes the image brighter, but slows down the capture. The value is usually given in microseconds but some devices might deviate from this standard. This parameter is only writable if 'exposure_auto' is set to 'Off'.
Specifies if the exposure time is set manually by the user or automatically by the device.
'Off': The exposure time is set manually by the user.
'Once': The exposure time is automatically estimated by the device once, based on the first successfully captured image. This value might not be implemented on your device.
'Continuous': The exposure time is automatically and continuously updated by the device with every acquired image. This value might not be implemented on your device.
Allows to increase the image brightness by applying an amplification factor. Higher gain makes the image brighter without slowing down the capture, but introduces more noise. This parameter is only writable if 'gain_auto' is set to 'Off'.
Specifies if the gain is set manually by the user or automatically by the device.
'Off': The gain is set manually by the user.
'Once': The gain is automatically estimated by the device once, based on the first successfully captured image. This value might not be implemented on your device.
'Continuous': The gain is automatically and continuously updated by the camera with every acquired image. This value might not be implemented on your device.
Specifies the mode in which the image acquisition is being triggered.
'Off': Any trigger is deactivated and the device operates in free run mode, acquiring images continuously.
'Software': The software trigger is activated and 'trigger_software' can be used to trigger the acquisition on demand.
'Line<X>': The hardware trigger is activated and the specified physical input line is configured as source for the trigger signal.
Specifies the activation mode of the trigger. If supported by the device, this parameter is available when using a hardware trigger (i.e. 'trigger' is set to 'Line<X>'.
'RisingEdge': The acquisition is triggered on the rising edge of the input signal.
'FallingEdge': The acquisition is triggered on the falling edge of the input signal.
'AnyEdge': The acquisition is triggered on any level-change of the input signal.
'LevelHigh': The acquisition is triggered continuously as long as the level of the input signal is high.
'LevelLow': The acquisition is triggered continuously as long as the level of the input signal is low.
Specifies a delay the device applies after the trigger signal, before activating the image acquisition. The value is usually given in microseconds but some devices might deviate from this standard.
Triggers the acquisition on demand. This command parameter becomes available when 'trigger' is set to 'Software'.
For plugins provided by MVTec, the MVTec Interfaces Reference Documentation describes all plugin-specific parameters.
For further parameters, check the documentation of the respective software or hardware manufacturer.
ImageSourceHandle (input_control) image_source → (handle)
Image source handle.
Param (input_control) string → (string)
Parameter to be retrieved.
GenParamName (input_control) attribute.name-array → (string)
Generic parameter name.
Default: []
Suggested values: 'group', 'property'
GenParamValue (input_control) attribute.value-array → (integer / real / string)
Generic parameter value.
Default: []
Suggested values: 'image_source', 'plugin', 'interface', 'local_device', 'device', 'easy_device', 'stream', 'tooltip', 'description', 'display_name', 'visibility', 'access', 'type', 'persistable', 'min', 'max', 'increment', 'values'
Value (output_control) string-array → (string / real / integer / handle)
Retrieved value.
* Get current selected pixel format (notice per default 'group'='device'). get_image_source_param (ImageSourceHandle, 'PixelFormat', [], [], PixelFormat) * Get list of supported pixel formats by the device. get_image_source_param (ImageSourceHandle, 'PixelFormat', 'property', 'values', AvailablePixelFormats) * Get the version information of the plugin. get_image_source_param (ImageSourceHandle, 'TLVersion', 'group', 'plugin', Version)
If the parameter values are correct, get_image_source_param
returns the value 2 (
H_MSG_TRUE)
. Otherwise an exception is raised.
query_image_sources,
create_image_source,
connect_image_source
set_image_source_param,
disconnect_image_source
Foundation