apply_sample_identifierT_apply_sample_identifierApplySampleIdentifierApplySampleIdentifier (Operator)

Name

apply_sample_identifierT_apply_sample_identifierApplySampleIdentifierApplySampleIdentifier — Identify objects with a sample identifier.

Signature

Description

apply_sample_identifierapply_sample_identifierApplySampleIdentifierApplySampleIdentifierApplySampleIdentifier identifies the object in the ImageImageImageImageimage using the given SampleIdentifierSampleIdentifierSampleIdentifierSampleIdentifiersampleIdentifier and returns the corresponding ObjectIdxObjectIdxObjectIdxObjectIdxobjectIdx.

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

The operator apply_sample_identifierapply_sample_identifierApplySampleIdentifierApplySampleIdentifierApplySampleIdentifier 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 NumResultsNumResultsNumResultsNumResultsnumResults 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 RatingThresholdRatingThresholdRatingThresholdRatingThresholdratingThreshold.

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

The following generic parameters can be used to influence the behavior of the SampleIdentifierSampleIdentifierSampleIdentifierSampleIdentifiersampleIdentifier. These parameters and their corresponding values can be specified by using GenParamNameGenParamNameGenParamNameGenParamNamegenParamName and GenParamValueGenParamValueGenParamValueGenParamValuegenParamValue, respectively. The following values for GenParamNameGenParamNameGenParamNameGenParamNamegenParamName 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 value: '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 RatingThresholdRatingThresholdRatingThresholdRatingThresholdratingThreshold 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 RatingThresholdRatingThresholdRatingThresholdRatingThresholdratingThreshold will be applied.

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

Default value: '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_paramSetSampleIdentifierParamSetSampleIdentifierParamSetSampleIdentifierParam for a description of this parameter.

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

Default value: 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_identifierCreateSampleIdentifierCreateSampleIdentifierCreateSampleIdentifier is used.

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

See set_sample_identifier_paramset_sample_identifier_paramSetSampleIdentifierParamSetSampleIdentifierParamSetSampleIdentifierParam for a description of this parameter.

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

Default value: 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_identifierCreateSampleIdentifierCreateSampleIdentifierCreateSampleIdentifier is used.

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

See create_sample_identifiercreate_sample_identifierCreateSampleIdentifierCreateSampleIdentifierCreateSampleIdentifier 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 value: 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_identifierCreateSampleIdentifierCreateSampleIdentifierCreateSampleIdentifier or set_sample_identifier_paramset_sample_identifier_paramSetSampleIdentifierParamSetSampleIdentifierParamSetSampleIdentifierParam will be used.

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

See create_sample_identifiercreate_sample_identifierCreateSampleIdentifierCreateSampleIdentifierCreateSampleIdentifier 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 value: 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_identifierCreateSampleIdentifierCreateSampleIdentifierCreateSampleIdentifier or set_sample_identifier_paramset_sample_identifier_paramSetSampleIdentifierParamSetSampleIdentifierParamSetSampleIdentifierParam 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_paramSetSampleIdentifierParamSetSampleIdentifierParamSetSampleIdentifierParam returns the value 2 (H_MSG_TRUE). If necessary an exception is raised.

Possible Predecessors

train_sample_identifiertrain_sample_identifierTrainSampleIdentifierTrainSampleIdentifierTrainSampleIdentifier, read_sample_identifierread_sample_identifierReadSampleIdentifierReadSampleIdentifierReadSampleIdentifier

Possible Successors

add_sample_identifier_training_dataadd_sample_identifier_training_dataAddSampleIdentifierTrainingDataAddSampleIdentifierTrainingDataAddSampleIdentifierTrainingData

See also

create_sample_identifiercreate_sample_identifierCreateSampleIdentifierCreateSampleIdentifierCreateSampleIdentifier, add_sample_identifier_preparation_dataadd_sample_identifier_preparation_dataAddSampleIdentifierPreparationDataAddSampleIdentifierPreparationDataAddSampleIdentifierPreparationData, prepare_sample_identifierprepare_sample_identifierPrepareSampleIdentifierPrepareSampleIdentifierPrepareSampleIdentifier, set_sample_identifier_paramset_sample_identifier_paramSetSampleIdentifierParamSetSampleIdentifierParamSetSampleIdentifierParam, get_sample_identifier_paramget_sample_identifier_paramGetSampleIdentifierParamGetSampleIdentifierParamGetSampleIdentifierParam, get_sample_identifier_object_infoget_sample_identifier_object_infoGetSampleIdentifierObjectInfoGetSampleIdentifierObjectInfoGetSampleIdentifierObjectInfo, remove_sample_identifier_preparation_dataremove_sample_identifier_preparation_dataRemoveSampleIdentifierPreparationDataRemoveSampleIdentifierPreparationDataRemoveSampleIdentifierPreparationData, remove_sample_identifier_training_dataremove_sample_identifier_training_dataRemoveSampleIdentifierTrainingDataRemoveSampleIdentifierTrainingDataRemoveSampleIdentifierTrainingData, write_sample_identifierwrite_sample_identifierWriteSampleIdentifierWriteSampleIdentifierWriteSampleIdentifier, serialize_sample_identifierserialize_sample_identifierSerializeSampleIdentifierSerializeSampleIdentifierSerializeSampleIdentifier, deserialize_sample_identifierdeserialize_sample_identifierDeserializeSampleIdentifierDeserializeSampleIdentifierDeserializeSampleIdentifier, clear_sample_identifierclear_sample_identifierClearSampleIdentifierClearSampleIdentifierClearSampleIdentifier, set_sample_identifier_object_infoset_sample_identifier_object_infoSetSampleIdentifierObjectInfoSetSampleIdentifierObjectInfoSetSampleIdentifierObjectInfo

Module

Matching