Skip to content

get_image_source_paramget_image_source_paramGetImageSourceParamGetImageSourceParamget_image_source_paramT_get_image_source_param🔗

Short description🔗

get_image_source_paramget_image_source_paramGetImageSourceParamGetImageSourceParamget_image_source_paramT_get_image_source_param — Return the value of an image source parameter.

Signature🔗

get_image_source_param( image_source ImageSourceHandle, string Param, attribute.name GenParamName, attribute.value GenParamValue, out string Value )get_image_source_param( : : ImageSourceHandle, Param, GenParamName, GenParamValue : Value )void GetImageSourceParam( const HTuple& ImageSourceHandle, const HTuple& Param, const HTuple& GenParamName, const HTuple& GenParamValue, HTuple* Value )static void HOperatorSet.GetImageSourceParam( HTuple imageSourceHandle, HTuple param, HTuple genParamName, HTuple genParamValue, out HTuple value )def get_image_source_param( image_source_handle: HHandle, param: str, gen_param_name: Sequence[str], gen_param_value: Sequence[Union[int, float, str]] ) -> Sequence[HTupleElementType]

Herror T_get_image_source_param( const Htuple ImageSourceHandle, const Htuple Param, const Htuple GenParamName, const Htuple GenParamValue, Htuple* Value )

HTuple HImageSource::GetImageSourceParam( const HString& Param, const HTuple& GenParamName, const HTuple& GenParamValue ) const

HTuple HImageSource::GetImageSourceParam( const char* Param, const HTuple& GenParamName, const HTuple& GenParamValue ) const

HTuple HImageSource::GetImageSourceParam( const wchar_t* Param, const HTuple& GenParamName, const HTuple& GenParamValue ) const (Windows only)

HTuple HImageSource.GetImageSourceParam( string param, HTuple genParamName, HTuple genParamValue )

Description🔗

The operator get_image_source_paramGetImageSourceParam returns the parameter values or parameter properties for an image source handle ImageSourceHandleimageSourceHandleimage_source_handle in Valuevaluevalue.

For further information about the image source concept see Image Source.

The parameter needs to be specified using Paramparamparam. 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 Paramparamparam. Use the generic parameter GenParamNamegenParamNamegen_param_name to differentiate whether you want to get the value or meta information regarding the parameter. You have the following options for GenParamNamegenParamNamegen_param_name:

  • 'group'"group" Specify the parameter group the parameter is found in with GenParamValuegenParamValuegen_param_value by setting one of these options:

    • 'image_source'"image_source",

    • 'plugin'"plugin",

    • 'interface'"interface",

    • 'local_device'"local_device",

    • 'device'"device",

    • 'easy_device'"easy_device",

    • 'stream'"stream".

    When setting no generic parameters, GenParamNamegenParamNamegen_param_name = 'group'"group" and GenParamValuegenParamValuegen_param_value = 'device'"device" are assumed by default.

    The group 'image_source'"image_source" is always available, whereas a connection is needed for the other parameter groups.

  • 'property'"property" Retrieve meta information about Paramparamparam. Specify the requested parameter property with GenParamValuegenParamValuegen_param_value by setting one of these options:

    • 'access'"access": Provides access permissions as a string.

      List of values: 'na'"na" ((currently) not available), 'ro'"ro" (read-only), 'rw'"rw" (read/write), 'wo'"wo" (write-only).

    • 'description'"description": Provides a description of the parameter as a string.

    • 'display_name'"display_name": Provides the display name of the parameter as a string.

    • 'increment'"increment": Provides the step width of the parameter as a real or integer value, depending on the data type of the parameter.

    • 'max'"max": Provides the maximum value of the parameter as a real or integer value, depending on the data type of the parameter.

    • 'min'"min": Provides the minimum value of the parameter as a real or integer value, depending on the data type of the parameter.

    • 'persistable'"persistable": Provides information about the persistence of the parameter as an integer.

      List of values: 00 (false), 11 (true).

    • 'tooltip'"tooltip": Provides a short description of the parameter.

    • 'type'"type": Provides the parameter type as a string.

      List of values: 'boolean'"boolean", 'command'"command", 'enumeration'"enumeration" (string out of a list of allowed strings), 'integer'"integer", 'real'"real", 'register'"register", 'string'"string".

    • 'values'"values": Provides a list of all allowed values for parameters of 'type'"type" = 'enumeration'"enumeration" and for some of 'type'"type" 'integer'"integer" and 'real'"real".

    • 'visibility'"visibility": Provides information about the visibility of the parameter.

      List of values: 'basic'"basic", 'advanced'"advanced", 'all'"all".

Image Source Handle Parameters🔗

Parameters of the 'image_source'"image_source" group are always available. The following table gives an overview, which of those parameters can be set using set_image_source_paramSetImageSourceParam and which can be retrieved using get_image_source_paramGetImageSourceParam. A description of the parameters can be found below the table.

GenParamNamegenParamNamegen_param_name set get
'device_access_flags'"device_access_flags" x x
'device_access_status'"device_access_status" x
'device_connect_mode'"device_connect_mode" x
'device_id'"device_id" x x
'device_is_connected'"device_is_connected" x
'device_query_timeout'"device_query_timeout" x x
'device_user_name'"device_user_name" x x
'device_serial_number'"device_serial_number" x x
'fetch_timeout'"fetch_timeout" x x
'interface_connect_mode'"interface_connect_mode" x
'interface_display_name'"interface_display_name" x
'interface_id'"interface_id" x x
'interface_is_connected'"interface_is_connected" x
'interface_query_timeout'"interface_query_timeout" x x
'num_buffers'"num_buffers" x x
'plugin_connect_mode'"plugin_connect_mode" x
'plugin_is_connected'"plugin_is_connected" x
'plugin_name'"plugin_name" x x
'plugin_path'"plugin_path" x x
'stream_connect_mode'"stream_connect_mode" x
'stream_id'"stream_id" x x
'stream_is_connected'"stream_is_connected" x
'stream_state'"stream_state" x
'version'"version" x
  • 'device_access_flags'"device_access_flags" GenTL access flags used when attempting to connect to the device.

    • 'control'"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'"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'"none": Either the device is not open because it was not opened before or the access to it was denied.

    • 'read_only'"read_only": Open the device read-only. All port functions can only read from the device.

    • 'unknown'"unknown": Not used in a command. Can be used to initialize a variable to query that information.

  • 'device_access_status'"device_access_status" Current GenTL access status of the device.

    • 'busy'"busy": Device has already been opened in 'exclusive'"exclusive" mode by another process/host.

    • 'open_read_only'"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'"control" mode (see 'device_access_flags'"device_access_flags").

    • 'open_read_write'"open_read_write": Device has already been opened by this process and handled in 'exclusive'"exclusive" or 'control'"control" mode (see 'device_access_flags'"device_access_flags").

    • 'no_access'"no_access": Device is not accessible (no connection possible).

    • 'read_only'"read_only": Device is available for read-only access.

    • 'read_write'"read_write": Device is available for read/write access (see 'device_access_flags'"device_access_flags").

    • 'unknown'"unknown": Device accessibility is not known.

  • 'device_connect_mode'"device_connect_mode" Connect mode for the device module.

    • 'automatic'"automatic": No identifier is provided, the required module will be automatically found and connected.

    • 'exact'"exact": A module identifier has been indicated for the module connection.

    • 'none'"none": Module connection not needed.

  • 'device_id'"device_id" ID of the device as a string. It can be used to specify the device module to open during connect_image_sourceConnectImageSource.

  • 'device_is_connected'"device_is_connected" Connection status of the device as an integer.

    List of values: 00 (unconnected), 11 (connected).

  • 'device_query_timeout'"device_query_timeout" Desired timeout [ms] for aborting a pending device query. Is used as the device discovery timeout in GigEVision transport layers. If -1-1 is specified, the timeout is set to infinite.

    Default: 11001100

  • 'device_serial_number'"device_serial_number" 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'"device_id".

  • 'device_user_name'"device_user_name" 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'"device_id".

  • 'fetch_timeout'"fetch_timeout" Desired timeout [ms] for aborting a pending grab. If -1-1 is specified, the timeout is set to infinite.

    Default: 50005000

  • 'interface_connect_mode'"interface_connect_mode" Connect mode for the interface module.

    • 'automatic'"automatic": No identifier is provided, the required module will be automatically found and connected.

    • 'exact'"exact": A module identifier has been indicated for the module connection.

    • 'none'"none": Module connection not needed.

  • 'interface_display_name'"interface_display_name" Provides a human-readable secondary identifier for the interface module as a string.

  • 'interface_id'"interface_id" ID of the interface as a string. It can be used to specify the interface module to open during connect_image_sourceConnectImageSource.

  • 'interface_is_connected'"interface_is_connected" Connection status of the interface as an integer.

    List of values: 00 (unconnected), 11 (connected).

  • 'interface_query_timeout'"interface_query_timeout" Desired timeout [ms] for aborting a pending interface query. If -1-1 is specified, the timeout is set to infinite.

    Default: 11001100

  • 'num_buffers'"num_buffers" Number of buffers that will be prepared by start_image_sourceStartImageSource 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_sourceStartImageSource.

    Default: 44

  • 'plugin_connect_mode'"plugin_connect_mode" Connect mode for the plugin module.

    • 'automatic'"automatic": No identifier is provided, the required module will be automatically found and connected.

    • 'exact'"exact": A module identifier has been indicated for the module connection.

    • 'none'"none": Module connection not needed.

  • 'plugin_is_connected'"plugin_is_connected" Connection status of the plugin as an integer.

    List of values: 00 (unconnected), 11 (connected).

  • 'plugin_name'"plugin_name" Name of the plugin as a string.

  • 'plugin_path'"plugin_path" 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.

  • 'stream_connect_mode'"stream_connect_mode" Connect mode for the stream module.

    • 'automatic'"automatic": No identifier is provided, the required module will be automatically found and connected.

    • 'exact'"exact": A module identifier has been indicated for the module connection.

    • 'none'"none": Module connection not needed.

  • 'stream_id'"stream_id" ID of the stream as a string. Can be used to specify the stream module to open during connect_image_sourceConnectImageSource.

  • 'stream_is_connected'"stream_is_connected" Connection status of the stream as an integer.

    List of values: 00 (unconnected), 11 (connected).

  • 'stream_state'"stream_state" Current state of the stream.

    • 'initialized'"initialized": Stream is initialized but not running.

    • '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'"version" Version of the image source library.

Image Source Easy Device Parameters🔗

Parameters of the 'easy_device'"easy_device" group become available after successfully connecting to a device using connect_image_sourceConnectImageSource. While the following parameters are implemented, the availability of individual parameters in this group depends on the connected device.

  • 'exposure'"exposure" 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'"exposure_auto" is set to 'Off'"Off".

  • 'exposure_auto'"exposure_auto" Specifies if the exposure time is set manually by the user or automatically by the device.

    • 'Off'"Off": The exposure time is set manually by the user.

    • 'Once'"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'"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.

  • 'gain'"gain" 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'"gain_auto" is set to 'Off'"Off".

  • 'gain_auto'"gain_auto" Specifies if the gain is set manually by the user or automatically by the device.

    • 'Off'"Off": The gain is set manually by the user.

    • 'Once'"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'"Continuous": The gain is automatically and continuously updated by the camera with every acquired image. This value might not be implemented on your device.

  • 'trigger'"trigger" Specifies the mode in which the image acquisition is being triggered.

    • 'Off'"Off": Any trigger is deactivated and the device operates in free run mode, acquiring images continuously.

    • 'Software'"Software": The software trigger is activated and 'trigger_software'"trigger_software" can be used to trigger the acquisition on demand.

    • 'Line<X>'"Line<X>": The hardware trigger is activated and the specified physical input line is configured as source for the trigger signal.

  • 'trigger_activation'"trigger_activation" Specifies the activation mode of the trigger. If supported by the device, this parameter is available when using a hardware trigger (i.e. 'trigger'"trigger" is set to 'Line<X>'"Line<X>".

    • 'RisingEdge'"RisingEdge": The acquisition is triggered on the rising edge of the input signal.

    • 'FallingEdge'"FallingEdge": The acquisition is triggered on the falling edge of the input signal.

    • 'AnyEdge'"AnyEdge": The acquisition is triggered on any level-change of the input signal.

    • 'LevelHigh'"LevelHigh": The acquisition is triggered continuously as long as the level of the input signal is high.

    • 'LevelLow'"LevelLow": The acquisition is triggered continuously as long as the level of the input signal is low.

  • 'trigger_delay'"trigger_delay" 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.

  • 'trigger_software'"trigger_software" Triggers the acquisition on demand. This command parameter becomes available when 'trigger'"trigger" is set to 'Software'"Software".

Additional Documentation Sources🔗

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.

Execution information🔗

Execution information
  • Multithreading type: reentrant (runs in parallel with non-exclusive operators).

  • Multithreading scope: global (may be called from any thread).

  • Processed without parallelization.

Parameters🔗

ImageSourceHandleimageSourceHandleimage_source_handle (input_control) image_source → (handle)(handle)HTuple (HHandle)HImageSource, HTuple (IntPtr)HHandleHtuple (handle)

Image source handle.

Paramparamparam (input_control) string → (string)(string)HTuple (HString)HTuple (string)strHtuple (char*)

Parameter to be retrieved.

GenParamNamegenParamNamegen_param_name (input_control) attribute.name-array → (string)(string)HTuple (HString)HTuple (string)Sequence[str]Htuple (char*)

Generic parameter name.

Default: [][]
Suggested values: 'group', 'property'"group", "property"

GenParamValuegenParamValuegen_param_value (input_control) attribute.value-array → (integer / real / string)(integer / real / string)HTuple (Hlong / double / HString)HTuple (int / long / double / string)Sequence[Union[int, float, str]]Htuple (Hlong / double / char*)

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'"image_source", "plugin", "interface", "local_device", "device", "easy_device", "stream", "tooltip", "description", "display_name", "visibility", "access", "type", "persistable", "min", "max", "increment", "values"

Valuevaluevalue (output_control) string-array → (string / real / integer / handle)(string / real / integer / handle)HTuple (HString / double / Hlong / HHandle)HTuple (string / double / int / long / HHandle)Sequence[HTupleElementType]Htuple (char* / double / Hlong / handle)

Retrieved value.

Example🔗

(HDevelop)


* 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)

Result🔗

If the parameter values are correct, get_image_source_paramGetImageSourceParam returns the value 2 (H_MSG_TRUE). Otherwise an exception is raised.

Combinations with other operators🔗

Combinations

Possible predecessors

query_image_sourcesQueryImageSources, create_image_sourceCreateImageSource, connect_image_sourceConnectImageSource

Possible successors

set_image_source_paramSetImageSourceParam, disconnect_image_sourceDisconnectImageSource

See also

set_image_source_paramSetImageSourceParam

Module🔗

Foundation