control_image_sourceT_control_image_sourceControlImageSourceControlImageSourcecontrol_image_source (Operator)

Name

control_image_sourceT_control_image_sourceControlImageSourceControlImageSourcecontrol_image_source — Control actions available for an image source.

Signature

control_image_source( : : ImageSourceHandle, Action, GenParamName, GenParamValue : Result)

Description

control_image_sourcecontrol_image_sourceControlImageSourceControlImageSourcecontrol_image_source initiates actions for the image source specified in ImageSourceHandleImageSourceHandleImageSourceHandleimageSourceHandleimage_source_handle. If the action returns a value, it is passed back in ResultResultResultresultresult.

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

The requested action is determined in ActionActionActionactionaction. 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 ActionActionActionactionaction available for every image source are:

'enumerate_groups'"enumerate_groups""enumerate_groups""enumerate_groups""enumerate_groups"

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

'enumerate_params'"enumerate_params""enumerate_params""enumerate_params""enumerate_params"

Returns all parameters available in the group that is set in GenParamValueGenParamValueGenParamValuegenParamValuegen_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""group""group""group" is the only option for GenParamNameGenParamNameGenParamNamegenParamNamegen_param_name. Specify the parameter group in GenParamValueGenParamValueGenParamValuegenParamValuegen_param_value by setting one of these options:

'image_source'"image_source""image_source""image_source""image_source",
'plugin'"plugin""plugin""plugin""plugin",
'interface'"interface""interface""interface""interface",
'local_device'"local_device""local_device""local_device""local_device",
'device'"device""device""device""device",
'stream'"stream""stream""stream""stream".

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

'query_param_tree'"query_param_tree""query_param_tree""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.

'image_source'"image_source""image_source""image_source""image_source",
'plugin'"plugin""plugin""plugin""plugin",
'interface'"interface""interface""interface""interface",
'local_device'"local_device""local_device""local_device""local_device",
'device'"device""device""device""device",
'stream'"stream""stream""stream""stream".

'write_state_string'"write_state_string""write_state_string""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""persistable""persistable""persistable" is 'true'"true""true""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.

'plugin'"plugin""plugin""plugin""plugin",
'interface'"interface""interface""interface""interface",
'local_device'"local_device""local_device""local_device""local_device",
'device'"device""device""device""device",
'stream'"stream""stream""stream""stream".

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

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

'read_state_string'"read_state_string""read_state_string""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""state_string""state_string""state_string".

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

The generic parameter 'state_string'"state_string""state_string""state_string""state_string" is mandatory and must contain the state string, which can be obtained using the 'write_state_string'"write_state_string""write_state_string""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 GenParamValueGenParamValueGenParamValuegenParamValuegen_param_value by setting one of these options:

'plugin'"plugin""plugin""plugin""plugin",
'interface'"interface""interface""interface""interface",
'local_device'"local_device""local_device""local_device""local_device",
'device'"device""device""device""device",
'stream'"stream""stream""stream""stream".

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

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

'write_config_file'"write_config_file""write_config_file""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 GenParamNameGenParamNameGenParamNamegenParamNamegen_param_name = 'file_name'"file_name""file_name""file_name""file_name" in the corresponding GenParamValueGenParamValueGenParamValuegenParamValuegen_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_sourcecreate_image_sourceCreateImageSourceCreateImageSourcecreate_image_source.

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

ImageSourceHandleImageSourceHandleImageSourceHandleimageSourceHandleimage_source_handle (input_control) image_source → (handle)

Image source handle.

ActionActionActionactionaction (input_control) string → (string)

Action to be carried out.

Default: 'enumerate_params' "enumerate_params" "enumerate_params" "enumerate_params" "enumerate_params"

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

GenParamNameGenParamNameGenParamNamegenParamNamegen_param_name (input_control) attribute.name-array → (string)

Generic parameter name.

Default: []

Suggested values: 'group'"group""group""group""group", 'state_string'"state_string""state_string""state_string""state_string", 'file_name'"file_name""file_name""file_name""file_name"

GenParamValueGenParamValueGenParamValuegenParamValuegen_param_value (input_control) attribute.value-array → (integer / real / string)

Generic parameter value.

Default: []

Suggested values: 'image_source'"image_source""image_source""image_source""image_source", 'plugin'"plugin""plugin""plugin""plugin", 'interface'"interface""interface""interface""interface", 'local_device'"local_device""local_device""local_device""local_device", 'device'"device""device""device""device", 'stream'"stream""stream""stream""stream"

ResultResultResultresultresult (output_control) string-array → (string / real / integer / handle)

Action result, if available.

Result

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