create_sample_identifierT_create_sample_identifierCreateSampleIdentifierCreateSampleIdentifier (Operator)

Name

create_sample_identifierT_create_sample_identifierCreateSampleIdentifierCreateSampleIdentifier — Create a new sample identifier.

Signature

create_sample_identifier( : : GenParamName, GenParamValue : SampleIdentifier)

The operator create_sample_identifiercreate_sample_identifierCreateSampleIdentifierCreateSampleIdentifierCreateSampleIdentifier creates a new sample identifier. Alternatively, an already available sample identifier can be read from file with the operator read_sample_identifierread_sample_identifierReadSampleIdentifierReadSampleIdentifierReadSampleIdentifier.

For an explanation of the concept of sample-based identification see the introduction of chapter Identification / Sample-Based.

Note that if you want to use color information, you must specify this explicitly by setting the generic parameter 'add_color_info'"add_color_info""add_color_info""add_color_info""add_color_info" to 'true'"true""true""true""true".

The generic parameters can be used to influence the behavior of the sample identifier. Typically, only 'add_color_info'"add_color_info""add_color_info""add_color_info""add_color_info" must be considered. The parameters and their corresponding values can be specified by using GenParamNameGenParamNameGenParamNameGenParamNamegenParamName and GenParamValueGenParamValueGenParamValueGenParamValuegenParamValue, respectively. The following values for GenParamNameGenParamNameGenParamNameGenParamNamegenParamName are possible:

'add_color_info'"add_color_info""add_color_info""add_color_info""add_color_info":

This parameter determines if color information is used for the identification. If 'add_color_info'"add_color_info""add_color_info""add_color_info""add_color_info" is set to 'true'"true""true""true""true", color information is used. Note that in this case, all images used for the preparation and the training of the sample identifier must be RGB color images. If 'add_color_info'"add_color_info""add_color_info""add_color_info""add_color_info" is set to 'false'"false""false""false""false", no color information is used. Use color information, if the objects to be identified have different colors and if the illumination can be controlled to some degree. In this case, the use of color information makes the identification more robust.

List of values: 'true'"true""true""true""true", 'false'"false""false""false""false"

Default value: 'false'"false""false""false""false"

'add_texture_info'"add_texture_info""add_texture_info""add_texture_info""add_texture_info":

This parameter determines if texture information is used for the identification. If 'add_texture_info'"add_texture_info""add_texture_info""add_texture_info""add_texture_info" is set to 'true'"true""true""true""true", texture information is used. If 'add_texture_info'"add_texture_info""add_texture_info""add_texture_info""add_texture_info" is set to 'false'"false""false""false""false", no texture information is used. Typically, 'add_texture_info'"add_texture_info""add_texture_info""add_texture_info""add_texture_info" should be set to 'true'"true""true""true""true", because sample-based identification requires textured objects. Note that at least one of the two generic parameters 'add_color_info'"add_color_info""add_color_info""add_color_info""add_color_info" and 'add_texture_info'"add_texture_info""add_texture_info""add_texture_info""add_texture_info" must be set to 'true'"true""true""true""true".

List of values: 'true'"true""true""true""true", 'false'"false""false""false""false"

Default value: 'true'"true""true""true""true"

'image_resize_method'"image_resize_method""image_resize_method""image_resize_method""image_resize_method":

To speed up the identification process, the images are resized internally to a given size or by a given factor. If 'none'"none""none""none""none" is selected, no resizing will be done. For 'scale_factor'"scale_factor""scale_factor""scale_factor""scale_factor", a constant scale factor can be set and for 'subsampling_step'"subsampling_step""subsampling_step""subsampling_step""subsampling_step", a constant subsampling step, i.e., the inverse of the scale factor can be set. Finally, for 'image_area'"image_area""image_area""image_area""image_area", a constant size of the resized image can be specified. The corresponding values can be set with the 'image_resize_value'"image_resize_value""image_resize_value""image_resize_value""image_resize_value" (see below).

To make the identification process faster, choose parameters that lead to a smaller internal image, i.e., use smaller scale factors or image sizes or a larger subsampling step. If the objects to be identified show high-frequency texture, the identification result may become better, if a larger internal image size is used, because otherwise the texture may be eliminated in the resized images.

List of values: 'none'"none""none""none""none", 'scale_factor'"scale_factor""scale_factor""scale_factor""scale_factor", 'subsampling_step'"subsampling_step""subsampling_step""subsampling_step""subsampling_step", 'image_area'"image_area""image_area""image_area""image_area"

Default value: 'image_area'"image_area""image_area""image_area""image_area"

'image_resize_value'"image_resize_value""image_resize_value""image_resize_value""image_resize_value":

With this parameter, the selected 'image_resize_method'"image_resize_method""image_resize_method""image_resize_method""image_resize_method" can be parameterized. If 'image_resize_method'"image_resize_method""image_resize_method""image_resize_method""image_resize_method" is set to 'scale_factor'"scale_factor""scale_factor""scale_factor""scale_factor", the value of 'image_resize_value'"image_resize_value""image_resize_value""image_resize_value""image_resize_value" defines the scale factor to be used. If 'image_resize_method'"image_resize_method""image_resize_method""image_resize_method""image_resize_method" is set to 'subsampling_step'"subsampling_step""subsampling_step""subsampling_step""subsampling_step", the value of 'image_resize_value'"image_resize_value""image_resize_value""image_resize_value""image_resize_value" defines the subsampling step, i.e., the inverse of the scale factor. If 'image_resize_method'"image_resize_method""image_resize_method""image_resize_method""image_resize_method" is set to 'image_area'"image_area""image_area""image_area""image_area", the value of 'image_resize_value'"image_resize_value""image_resize_value""image_resize_value""image_resize_value" defines the area of the resized image given in megapixels, i.e., in million pixels.

Suggested values: 0.25, 0.5, 1.0, 2, 3, 4

Default value: The default value depends on the selected 'image_resize_method'"image_resize_method""image_resize_method""image_resize_method""image_resize_method". It is

0.5 for 'scale_factor'"scale_factor""scale_factor""scale_factor""scale_factor",

2.0 for 'subsampling_step'"subsampling_step""subsampling_step""subsampling_step""subsampling_step", and

0.5 for 'image_area'"image_area""image_area""image_area""image_area".

Execution Information

Multithreading type: reentrant (runs in parallel with non-exclusive operators).
Multithreading scope: global (may be called from any thread).
Processed without parallelization.

This operator returns a handle. Note that the state of an instance of this handle type may be changed by specific operators even though the handle is used as an input parameter by those operators.

Parameters

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

Parameter name.

Default value: []

List of values: 'add_color_info'"add_color_info""add_color_info""add_color_info""add_color_info", 'add_texture_info'"add_texture_info""add_texture_info""add_texture_info""add_texture_info", 'image_resize_method'"image_resize_method""image_resize_method""image_resize_method""image_resize_method", 'image_resize_value'"image_resize_value""image_resize_value""image_resize_value""image_resize_value"

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

Parameter value.

Default value: []

Suggested values: 'none'"none""none""none""none", 'scale_factor'"scale_factor""scale_factor""scale_factor""scale_factor", 'subsampling_step'"subsampling_step""subsampling_step""subsampling_step""subsampling_step", 'image_area'"image_area""image_area""image_area""image_area", 0.25, 0.5, 0.75, 1.0, 2, 3, 4, 'true'"true""true""true""true", 'false'"false""false""false""false"

SampleIdentifierSampleIdentifierSampleIdentifierSampleIdentifiersampleIdentifier (output_control) sample_identifier → (integer)

Handle of the sample identifier.

Result

If the parameters are valid, the operator create_sample_identifiercreate_sample_identifierCreateSampleIdentifierCreateSampleIdentifierCreateSampleIdentifier returns the value 2 (H_MSG_TRUE). If necessary an exception is raised.