Skip to content

control_image_sourceControlImageSourceControlImageSourcecontrol_image_sourceT_control_image_source🔗

Short description🔗

control_image_sourceControlImageSourceControlImageSourcecontrol_image_sourceT_control_image_source — Control actions available for an image source.

Signature🔗

control_image_source( image_source ImageSourceHandle, string Action, attribute.name GenParamName, attribute.value GenParamValue, out string Result )void ControlImageSource( const HTuple& ImageSourceHandle, const HTuple& Action, const HTuple& GenParamName, const HTuple& GenParamValue, HTuple* Result )static void HOperatorSet.ControlImageSource( HTuple imageSourceHandle, HTuple action, HTuple genParamName, HTuple genParamValue, out HTuple result )def control_image_source( image_source_handle: HHandle, action: str, gen_param_name: Sequence[str], gen_param_value: Sequence[Union[int, float, str]] ) -> Sequence[HTupleElementType]

Herror T_control_image_source( const Htuple ImageSourceHandle, const Htuple Action, const Htuple GenParamName, const Htuple GenParamValue, Htuple* Result )

HTuple HImageSource::ControlImageSource( const HString& Action, const HTuple& GenParamName, const HTuple& GenParamValue ) const

HTuple HImageSource::ControlImageSource( const char* Action, const HTuple& GenParamName, const HTuple& GenParamValue ) const

HTuple HImageSource::ControlImageSource( const wchar_t* Action, const HTuple& GenParamName, const HTuple& GenParamValue ) const (Windows only)

HTuple HImageSource.ControlImageSource( string action, HTuple genParamName, HTuple genParamValue )

Description🔗

control_image_sourceControlImageSource initiates actions for the image source specified in ImageSourceHandleimageSourceHandleimage_source_handle. If the action returns a value, it is passed back in Resultresultresult.

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

The requested action is determined in Actionactionaction. Actions can be global or targeting the individual module in the image source. Some actions depend on whether the image source is in a connected state or not. The options for Actionactionaction available for every image source are:

  • 'enumerate_groups'"enumerate_groups" Returns all parameter group names. When querying 'enumerate_groups'"enumerate_groups", the generic parameters GenParamNamegenParamNamegen_param_name and GenParamValuegenParamValuegen_param_value need to remain empty.

  • 'enumerate_params'"enumerate_params" Returns all parameters available in the group that is set in GenParamValuegenParamValuegen_param_value. This action is specific to an image source module and therefore a parameter group has to be specified using generic parameters.

    'group'"group" is the only option for GenParamNamegenParamNamegen_param_name. Specify the parameter group in GenParamValuegenParamValuegen_param_value by setting one of these options:

    • 'image_source'"image_source",

    • 'plugin'"plugin",

    • 'interface'"interface",

    • 'local_device'"local_device",

    • 'device'"device",

    • 'stream'"stream".

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

  • 'query_param_tree'"query_param_tree" Returns a nested HALCON dictionary containing all parameter categories, sub-categories, and their parameters. For each contained parameter, its parameter type is also reported.

    This action is specific to an image source module and therefore a parameter group has to be specified using generic parameters.

    'group'"group" is the only option for GenParamNamegenParamNamegen_param_name. Specify the parameter group in GenParamValuegenParamValuegen_param_value by setting one of these options:

    • 'image_source'"image_source",

    • 'plugin'"plugin",

    • 'interface'"interface",

    • 'local_device'"local_device",

    • 'device'"device",

    • 'stream'"stream".

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

  • 'write_state_string'"write_state_string" Returns a string containing information required to restore the values of all persistable parameters of the specified group. Only parameters whose parameter property 'persistable'"persistable" is 'true'"true" are included.

    This action is specific to an image source module and therefore a parameter group has to be specified using generic parameters.

    'group'"group" is the only option for GenParamNamegenParamNamegen_param_name. Specify the parameter group in GenParamValuegenParamValuegen_param_value by setting one of these options:

    • 'plugin'"plugin",

    • 'interface'"interface",

    • 'local_device'"local_device",

    • 'device'"device",

    • 'stream'"stream".

    When no generic parameters are set, GenParamNamegenParamNamegen_param_name is assumed to be 'group'"group" and GenParamValuegenParamValuegen_param_value is assumed to be 'device'"device".

    This action cannot be used for the 'image_source'"image_source" group.

  • 'read_state_string'"read_state_string" Restores all persistable parameters of the specified group from the state string passed in the generic parameter 'state_string'"state_string".

    'group'"group" and 'state_string'"state_string" are the valid options for GenParamNamegenParamNamegen_param_name.

    The generic parameter 'state_string'"state_string" is mandatory and must contain the state string, which can be obtained using the 'write_state_string'"write_state_string" action.

    This action is specific to an image source module and therefore a parameter group has to be specified using generic parameters. Specify the parameter group in GenParamValuegenParamValuegen_param_value by setting one of these options:

    • 'plugin'"plugin",

    • 'interface'"interface",

    • 'local_device'"local_device",

    • 'device'"device",

    • 'stream'"stream".

    When the generic parameter 'group'"group" is not set, the value 'device'"device" is assumed by default.

    This action cannot be used for the 'image_source'"image_source" group.

  • 'write_config_file'"write_config_file" Writes an image source configuration file, containing information required for a successful connection as well as to restore the values of all persistable parameters of all parameter groups.

    Writing the configuration file is allowed in the connected as well as in the unconnected state. If written in the unconnected state, it will not contain any information regarding the persistable parameters of the image source modules (device, plugin, …).

    This action requires a path to the file that should be written. It must be passed together with GenParamNamegenParamNamegen_param_name = 'file_name'"file_name" in the corresponding GenParamValuegenParamValuegen_param_value.

    The default HALCON file extension for the image source configuration files is '.hisc'. If no extension is specified it will be appended automatically.

    To read these configuration files (and restore image source handles from them) refer to create_image_sourceCreateImageSource.

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)HTuple (HHandle)HImageSource, HTuple (IntPtr)HHandleHtuple (handle)

Image source handle.

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

Action to be carried out.

Default: 'enumerate_params'"enumerate_params"
Suggested values: 'enumerate_params', 'enumerate_groups', 'query_param_tree', 'write_state_string', 'read_state_string', 'write_config_file'"enumerate_params", "enumerate_groups", "query_param_tree", "write_state_string", "read_state_string", "write_config_file"

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

Generic parameter name.

Default: [][]
Suggested values: 'group', 'state_string', 'file_name'"group", "state_string", "file_name"

GenParamValuegenParamValuegen_param_value (input_control) attribute.value-array → (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', 'stream'"image_source", "plugin", "interface", "local_device", "device", "stream"

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

Action result, if available.

Result🔗

If the parameter values are correct, control_image_sourceControlImageSource 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

disconnect_image_sourceDisconnectImageSource

See also

set_image_source_paramSetImageSourceParam, get_image_source_paramGetImageSourceParam

Module🔗

Foundation