apply_sample_identifierT_apply_sample_identifierApplySampleIdentifierApplySampleIdentifierapply_sample_identifier (Operator)

Name

apply_sample_identifierT_apply_sample_identifierApplySampleIdentifierApplySampleIdentifierapply_sample_identifier — Identify objects with a sample identifier.

Warning

apply_sample_identifierapply_sample_identifierApplySampleIdentifierApplySampleIdentifierapply_sample_identifier is obsolete and is only provided for reasons of backward compatibility. New applications should use the operators for Deep-Learning-based classification instead, for details see Deep Learning / Classification.

Signature

Description

apply_sample_identifierapply_sample_identifierApplySampleIdentifierApplySampleIdentifierapply_sample_identifier identifies the object in the ImageImageImageimageimage using the given SampleIdentifierSampleIdentifierSampleIdentifiersampleIdentifiersample_identifier and returns the corresponding ObjectIdxObjectIdxObjectIdxobjectIdxobject_idx.

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

The operator apply_sample_identifierapply_sample_identifierApplySampleIdentifierApplySampleIdentifierapply_sample_identifier can identify one object per query ImageImageImageimageimage. This means that the ImageImageImageimageimage, or more precisely the domain of the ImageImageImageimageimage, must not contain multiple objects. The parameter NumResultsNumResultsNumResultsnumResultsnum_results defines the number of hypotheses that are returned, ordered by their rating value. If the generic parameter 'apply_rating_threshold'"apply_rating_threshold""apply_rating_threshold""apply_rating_threshold""apply_rating_threshold" is set to 'true'"true""true""true""true" (see below), all returned hypotheses have a rating value better than the specified RatingThresholdRatingThresholdRatingThresholdratingThresholdrating_threshold.

The index of the identified object is returned in ObjectIdxObjectIdxObjectIdxobjectIdxobject_idx and its rating value is returned in RatingRatingRatingratingrating. If NumResultsNumResultsNumResultsnumResultsnum_results is set to a value larger than 1, the indices and ratings of the best rated NumResultsNumResultsNumResultsnumResultsnum_results hypotheses are returned in ObjectIdxObjectIdxObjectIdxobjectIdxobject_idx and RatingRatingRatingratingrating.

The following generic parameters can be used to influence the behavior of the SampleIdentifierSampleIdentifierSampleIdentifiersampleIdentifiersample_identifier. These parameters and their corresponding values can be specified by using GenParamNameGenParamNameGenParamNamegenParamNamegen_param_name and GenParamValueGenParamValueGenParamValuegenParamValuegen_param_value, respectively. The following values for GenParamNameGenParamNameGenParamNamegenParamNamegen_param_name are possible:

'rating_method'"rating_method""rating_method""rating_method""rating_method":

This parameter determines, which rating method is used for the identification of the objects. There are three different methods available:

'distance'"distance""distance""distance""distance"

The rating is based on the distance between the features of the image of the object to be identified and the trained sample images. The rating values lie between 0.0 and 2.0. If the images are identical, a rating value of 0.0 will be returned in RatingRatingRatingratingrating. The more different the images are, the higher the rating value will be. With this rating method, the raw internal rating is returned. This rating has the advantage that the rating value is independent of training samples other than that of the identified object.

'score'"score""score""score""score"

The rating is based on an elaborate combination of the scores for texture and color. The rating values lie between 0.0 and 1.0. Higher rating values indicate more similar images. If both texture and color are used, this rating method yields the best identification results and should therefore be used. One drawback of this rating method is that the rating value of a training image is typically far below 1.0. Furthermore, a suitable threshold must be determined for each application individually.

'score_single'"score_single""score_single""score_single""score_single"

The rating is based on a simple combination of the scores for texture and color. The rating values lie between 0.0 and 1.0. Higher rating values indicate more similar images. If both texture and color are used, the rating method 'score'"score""score""score""score" yields better results. The advantage of the rating method 'score_single'"score_single""score_single""score_single""score_single" is, that it yields a rating value of 1.0 for training images. Therefore, this rating method should be used if only texture or only color is used for the identification. For this rating method, it is much simpler to select a suitable threshold than for the rating method 'score'"score""score""score""score".

Note that the selection of the rating method influences both the identification of the objects, i.e., their discrimination, as well as the rating value that is returned in the parameter RatingRatingRatingratingrating.

List of values: 'distance'"distance""distance""distance""distance", 'score'"score""score""score""score", 'score_single'"score_single""score_single""score_single""score_single"

Default: 'score'"score""score""score""score"

'apply_rating_threshold'"apply_rating_threshold""apply_rating_threshold""apply_rating_threshold""apply_rating_threshold":

This parameter determines if the RatingThresholdRatingThresholdRatingThresholdratingThresholdrating_threshold will be applied or not. If 'apply_rating_threshold'"apply_rating_threshold""apply_rating_threshold""apply_rating_threshold""apply_rating_threshold" is set to 'true'"true""true""true""true", the rating threshold given in RatingThresholdRatingThresholdRatingThresholdratingThresholdrating_threshold will be applied.

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

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

'use_color_info'"use_color_info""use_color_info""use_color_info""use_color_info":

See set_sample_identifier_paramset_sample_identifier_paramSetSampleIdentifierParamSetSampleIdentifierParamset_sample_identifier_param for a description of this parameter.

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

Default: As long as 'use_color_info'"use_color_info""use_color_info""use_color_info""use_color_info" has not been set, the value set with 'add_color_info'"add_color_info""add_color_info""add_color_info""add_color_info" in create_sample_identifiercreate_sample_identifierCreateSampleIdentifierCreateSampleIdentifiercreate_sample_identifier is used.

'use_texture_info'"use_texture_info""use_texture_info""use_texture_info""use_texture_info":

See set_sample_identifier_paramset_sample_identifier_paramSetSampleIdentifierParamSetSampleIdentifierParamset_sample_identifier_param for a description of this parameter.

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

Default: As long as 'use_texture_info'"use_texture_info""use_texture_info""use_texture_info""use_texture_info" has not been set, the value set with 'add_texture_info'"add_texture_info""add_texture_info""add_texture_info""add_texture_info" in create_sample_identifiercreate_sample_identifierCreateSampleIdentifierCreateSampleIdentifiercreate_sample_identifier is used.

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

See create_sample_identifiercreate_sample_identifierCreateSampleIdentifierCreateSampleIdentifiercreate_sample_identifier for a description of this parameter.

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: If the 'image_resize_method'"image_resize_method""image_resize_method""image_resize_method""image_resize_method" is not set explicitly by this operator, the value that has been set with create_sample_identifiercreate_sample_identifierCreateSampleIdentifierCreateSampleIdentifiercreate_sample_identifier or set_sample_identifier_paramset_sample_identifier_paramSetSampleIdentifierParamSetSampleIdentifierParamset_sample_identifier_param will be used.

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

See create_sample_identifiercreate_sample_identifierCreateSampleIdentifierCreateSampleIdentifiercreate_sample_identifier for a description of this parameter. Note the objects to be identified should appear approximately in the same scale in the sample images as well as in the query images.

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

Default: If the 'image_resize_value'"image_resize_value""image_resize_value""image_resize_value""image_resize_value" is not set explicitly by this operator, the value that has been set with create_sample_identifiercreate_sample_identifierCreateSampleIdentifierCreateSampleIdentifiercreate_sample_identifier or set_sample_identifier_paramset_sample_identifier_paramSetSampleIdentifierParamSetSampleIdentifierParamset_sample_identifier_param will be used.

Execution Information

• Multithreading type: reentrant (runs in parallel with non-exclusive operators).
• Multithreading scope: global (may be called from any thread).
• Automatically parallelized on internal data level.

Parameters

Result

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

Possible Predecessors

train_sample_identifiertrain_sample_identifierTrainSampleIdentifierTrainSampleIdentifiertrain_sample_identifier, read_sample_identifierread_sample_identifierReadSampleIdentifierReadSampleIdentifierread_sample_identifier

Possible Successors

add_sample_identifier_training_dataadd_sample_identifier_training_dataAddSampleIdentifierTrainingDataAddSampleIdentifierTrainingDataadd_sample_identifier_training_data

See also

create_sample_identifiercreate_sample_identifierCreateSampleIdentifierCreateSampleIdentifiercreate_sample_identifier, add_sample_identifier_preparation_dataadd_sample_identifier_preparation_dataAddSampleIdentifierPreparationDataAddSampleIdentifierPreparationDataadd_sample_identifier_preparation_data, prepare_sample_identifierprepare_sample_identifierPrepareSampleIdentifierPrepareSampleIdentifierprepare_sample_identifier, set_sample_identifier_paramset_sample_identifier_paramSetSampleIdentifierParamSetSampleIdentifierParamset_sample_identifier_param, get_sample_identifier_paramget_sample_identifier_paramGetSampleIdentifierParamGetSampleIdentifierParamget_sample_identifier_param, get_sample_identifier_object_infoget_sample_identifier_object_infoGetSampleIdentifierObjectInfoGetSampleIdentifierObjectInfoget_sample_identifier_object_info, remove_sample_identifier_preparation_dataremove_sample_identifier_preparation_dataRemoveSampleIdentifierPreparationDataRemoveSampleIdentifierPreparationDataremove_sample_identifier_preparation_data, remove_sample_identifier_training_dataremove_sample_identifier_training_dataRemoveSampleIdentifierTrainingDataRemoveSampleIdentifierTrainingDataremove_sample_identifier_training_data, write_sample_identifierwrite_sample_identifierWriteSampleIdentifierWriteSampleIdentifierwrite_sample_identifier, serialize_sample_identifierserialize_sample_identifierSerializeSampleIdentifierSerializeSampleIdentifierserialize_sample_identifier, deserialize_sample_identifierdeserialize_sample_identifierDeserializeSampleIdentifierDeserializeSampleIdentifierdeserialize_sample_identifier, clear_sample_identifierclear_sample_identifierClearSampleIdentifierClearSampleIdentifierclear_sample_identifier, set_sample_identifier_object_infoset_sample_identifier_object_infoSetSampleIdentifierObjectInfoSetSampleIdentifierObjectInfoset_sample_identifier_object_info

Module

Matching