apply_sample_identifierT_apply_sample_identifierApplySampleIdentifierApplySampleIdentifierapply_sample_identifier (Operator)

Name

apply_sample_identifierT_apply_sample_identifierApplySampleIdentifierApplySampleIdentifierapply_sample_identifier — Identify objects with a sample identifier.

Signature

apply_sample_identifier(Image : : SampleIdentifier, NumResults, RatingThreshold, GenParamName, GenParamValue : ObjectIdx, Rating)

Herror T_apply_sample_identifier(const Hobject Image, const Htuple SampleIdentifier, const Htuple NumResults, const Htuple RatingThreshold, const Htuple GenParamName, const Htuple GenParamValue, Htuple* ObjectIdx, Htuple* Rating)

void ApplySampleIdentifier(const HObject& Image, const HTuple& SampleIdentifier, const HTuple& NumResults, const HTuple& RatingThreshold, const HTuple& GenParamName, const HTuple& GenParamValue, HTuple* ObjectIdx, HTuple* Rating)

HTuple HImage::ApplySampleIdentifier(const HSampleIdentifier& SampleIdentifier, Hlong NumResults, double RatingThreshold, const HTuple& GenParamName, const HTuple& GenParamValue, HTuple* Rating) const

Hlong HImage::ApplySampleIdentifier(const HSampleIdentifier& SampleIdentifier, Hlong NumResults, double RatingThreshold, const HTuple& GenParamName, const HTuple& GenParamValue, double* Rating) const

HTuple HSampleIdentifier::ApplySampleIdentifier(const HImage& Image, Hlong NumResults, double RatingThreshold, const HTuple& GenParamName, const HTuple& GenParamValue, HTuple* Rating) const

Hlong HSampleIdentifier::ApplySampleIdentifier(const HImage& Image, Hlong NumResults, double RatingThreshold, const HTuple& GenParamName, const HTuple& GenParamValue, double* Rating) const

static void HOperatorSet.ApplySampleIdentifier(HObject image, HTuple sampleIdentifier, HTuple numResults, HTuple ratingThreshold, HTuple genParamName, HTuple genParamValue, out HTuple objectIdx, out HTuple rating)

HTuple HImage.ApplySampleIdentifier(HSampleIdentifier sampleIdentifier, int numResults, double ratingThreshold, HTuple genParamName, HTuple genParamValue, out HTuple rating)

int HImage.ApplySampleIdentifier(HSampleIdentifier sampleIdentifier, int numResults, double ratingThreshold, HTuple genParamName, HTuple genParamValue, out double rating)

HTuple HSampleIdentifier.ApplySampleIdentifier(HImage image, int numResults, double ratingThreshold, HTuple genParamName, HTuple genParamValue, out HTuple rating)

int HSampleIdentifier.ApplySampleIdentifier(HImage image, int numResults, double ratingThreshold, HTuple genParamName, HTuple genParamValue, out double rating)

def apply_sample_identifier(image: HObject, sample_identifier: HHandle, num_results: int, rating_threshold: float, gen_param_name: Sequence[str], gen_param_value: Sequence[Union[str, int, float]]) -> Tuple[Sequence[int], Sequence[float]]

def apply_sample_identifier_s(image: HObject, sample_identifier: HHandle, num_results: int, rating_threshold: float, gen_param_name: Sequence[str], gen_param_value: Sequence[Union[str, int, float]]) -> Tuple[int, float]

Description

apply_sample_identifierapply_sample_identifierApplySampleIdentifierApplySampleIdentifierApplySampleIdentifierapply_sample_identifier identifies the object in the ImageImageImageImageimageimage using the given SampleIdentifierSampleIdentifierSampleIdentifierSampleIdentifiersampleIdentifiersample_identifier and returns the corresponding ObjectIdxObjectIdxObjectIdxObjectIdxobjectIdxobject_idx.

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

The operator apply_sample_identifierapply_sample_identifierApplySampleIdentifierApplySampleIdentifierApplySampleIdentifierapply_sample_identifier can identify one object per query ImageImageImageImageimageimage. This means that the ImageImageImageImageimageimage, or more precisely the domain of the ImageImageImageImageimageimage, must not contain multiple objects. The parameter NumResultsNumResultsNumResultsNumResultsnumResultsnum_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""apply_rating_threshold" is set to 'true'"true""true""true""true""true" (see below), all returned hypotheses have a rating value better than the specified RatingThresholdRatingThresholdRatingThresholdRatingThresholdratingThresholdrating_threshold.

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

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

'rating_method'"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""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 RatingRatingRatingRatingratingrating. 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""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""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""score" yields better results. The advantage of the rating method 'score_single'"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""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 RatingRatingRatingRatingratingrating.

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

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

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

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

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

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

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

See set_sample_identifier_paramset_sample_identifier_paramSetSampleIdentifierParamSetSampleIdentifierParamSetSampleIdentifierParamset_sample_identifier_param for a description of this parameter.

List of values: 'true'"true""true""true""true""true", 'false'"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""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""add_color_info" in create_sample_identifiercreate_sample_identifierCreateSampleIdentifierCreateSampleIdentifierCreateSampleIdentifiercreate_sample_identifier is used.

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

See set_sample_identifier_paramset_sample_identifier_paramSetSampleIdentifierParamSetSampleIdentifierParamSetSampleIdentifierParamset_sample_identifier_param for a description of this parameter.

List of values: 'true'"true""true""true""true""true", 'false'"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""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""add_texture_info" in create_sample_identifiercreate_sample_identifierCreateSampleIdentifierCreateSampleIdentifierCreateSampleIdentifiercreate_sample_identifier is used.

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

See create_sample_identifiercreate_sample_identifierCreateSampleIdentifierCreateSampleIdentifierCreateSampleIdentifiercreate_sample_identifier for a description of this parameter.

List of values: 'none'"none""none""none""none""none", 'scale_factor'"scale_factor""scale_factor""scale_factor""scale_factor""scale_factor", 'subsampling_step'"subsampling_step""subsampling_step""subsampling_step""subsampling_step""subsampling_step", 'image_area'"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""image_resize_method" is not set explicitly by this operator, the value that has been set with create_sample_identifiercreate_sample_identifierCreateSampleIdentifierCreateSampleIdentifierCreateSampleIdentifiercreate_sample_identifier or set_sample_identifier_paramset_sample_identifier_paramSetSampleIdentifierParamSetSampleIdentifierParamSetSampleIdentifierParamset_sample_identifier_param will be used.

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

See create_sample_identifiercreate_sample_identifierCreateSampleIdentifierCreateSampleIdentifierCreateSampleIdentifiercreate_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 value: If the 'image_resize_value'"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_identifierCreateSampleIdentifierCreateSampleIdentifierCreateSampleIdentifiercreate_sample_identifier or set_sample_identifier_paramset_sample_identifier_paramSetSampleIdentifierParamSetSampleIdentifierParamSetSampleIdentifierParamset_sample_identifier_param will be used.

Execution Information

Parameters

ImageImageImageImageimageimage (input_object)  (multichannel-)image objectHImageHObjectHImageHobject (byte)

Image showing the object to be identified.

SampleIdentifierSampleIdentifierSampleIdentifierSampleIdentifiersampleIdentifiersample_identifier (input_control)  sample_identifier HSampleIdentifier, HTupleHHandleHTupleHtuple (handle) (IntPtr) (HHandle) (handle)

Handle of the sample identifier.

NumResultsNumResultsNumResultsNumResultsnumResultsnum_results (input_control)  integer HTupleintHTupleHtuple (integer) (int / long) (Hlong) (Hlong)

Number of suggested object indices.

Default value: 1

Suggested values: 1, 2, 3, 4, 5, 10

RatingThresholdRatingThresholdRatingThresholdRatingThresholdratingThresholdrating_threshold (input_control)  real HTuplefloatHTupleHtuple (real) (double) (double) (double)

Rating threshold.

Default value: 0.0

Suggested values: 0.05, 0.1, 0.15, 0.2

GenParamNameGenParamNameGenParamNameGenParamNamegenParamNamegen_param_name (input_control)  attribute.name-array HTupleSequence[str]HTupleHtuple (string) (string) (HString) (char*)

Generic parameter name.

Default value: []

List of values: 'apply_rating_threshold'"apply_rating_threshold""apply_rating_threshold""apply_rating_threshold""apply_rating_threshold""apply_rating_threshold", 'image_resize_method'"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""image_resize_value", 'rating_method'"rating_method""rating_method""rating_method""rating_method""rating_method", 'use_color_info'"use_color_info""use_color_info""use_color_info""use_color_info""use_color_info", 'use_texture_info'"use_texture_info""use_texture_info""use_texture_info""use_texture_info""use_texture_info"

GenParamValueGenParamValueGenParamValueGenParamValuegenParamValuegen_param_value (input_control)  attribute.value-array HTupleSequence[Union[str, int, float]]HTupleHtuple (real / string / integer) (double / string / int / long) (double / HString / Hlong) (double / char* / Hlong)

Generic parameter value.

Default value: []

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

ObjectIdxObjectIdxObjectIdxObjectIdxobjectIdxobject_idx (output_control)  integer(-array) HTupleSequence[int]HTupleHtuple (integer) (int / long) (Hlong) (Hlong)

Index of the identified object.

RatingRatingRatingRatingratingrating (output_control)  real(-array) HTupleSequence[float]HTupleHtuple (real) (double) (double) (double)

Rating value of the identified object.

Result

If the parameters are valid, the operator set_sample_identifier_paramset_sample_identifier_paramSetSampleIdentifierParamSetSampleIdentifierParamSetSampleIdentifierParamset_sample_identifier_param returns the value TRUE. If necessary an exception is raised.

Possible Predecessors

train_sample_identifiertrain_sample_identifierTrainSampleIdentifierTrainSampleIdentifierTrainSampleIdentifiertrain_sample_identifier, read_sample_identifierread_sample_identifierReadSampleIdentifierReadSampleIdentifierReadSampleIdentifierread_sample_identifier

Possible Successors

add_sample_identifier_training_dataadd_sample_identifier_training_dataAddSampleIdentifierTrainingDataAddSampleIdentifierTrainingDataAddSampleIdentifierTrainingDataadd_sample_identifier_training_data

See also

create_sample_identifiercreate_sample_identifierCreateSampleIdentifierCreateSampleIdentifierCreateSampleIdentifiercreate_sample_identifier, add_sample_identifier_preparation_dataadd_sample_identifier_preparation_dataAddSampleIdentifierPreparationDataAddSampleIdentifierPreparationDataAddSampleIdentifierPreparationDataadd_sample_identifier_preparation_data, prepare_sample_identifierprepare_sample_identifierPrepareSampleIdentifierPrepareSampleIdentifierPrepareSampleIdentifierprepare_sample_identifier, set_sample_identifier_paramset_sample_identifier_paramSetSampleIdentifierParamSetSampleIdentifierParamSetSampleIdentifierParamset_sample_identifier_param, get_sample_identifier_paramget_sample_identifier_paramGetSampleIdentifierParamGetSampleIdentifierParamGetSampleIdentifierParamget_sample_identifier_param, get_sample_identifier_object_infoget_sample_identifier_object_infoGetSampleIdentifierObjectInfoGetSampleIdentifierObjectInfoGetSampleIdentifierObjectInfoget_sample_identifier_object_info, remove_sample_identifier_preparation_dataremove_sample_identifier_preparation_dataRemoveSampleIdentifierPreparationDataRemoveSampleIdentifierPreparationDataRemoveSampleIdentifierPreparationDataremove_sample_identifier_preparation_data, remove_sample_identifier_training_dataremove_sample_identifier_training_dataRemoveSampleIdentifierTrainingDataRemoveSampleIdentifierTrainingDataRemoveSampleIdentifierTrainingDataremove_sample_identifier_training_data, write_sample_identifierwrite_sample_identifierWriteSampleIdentifierWriteSampleIdentifierWriteSampleIdentifierwrite_sample_identifier, serialize_sample_identifierserialize_sample_identifierSerializeSampleIdentifierSerializeSampleIdentifierSerializeSampleIdentifierserialize_sample_identifier, deserialize_sample_identifierdeserialize_sample_identifierDeserializeSampleIdentifierDeserializeSampleIdentifierDeserializeSampleIdentifierdeserialize_sample_identifier, clear_sample_identifierclear_sample_identifierClearSampleIdentifierClearSampleIdentifierClearSampleIdentifierclear_sample_identifier, set_sample_identifier_object_infoset_sample_identifier_object_infoSetSampleIdentifierObjectInfoSetSampleIdentifierObjectInfoSetSampleIdentifierObjectInfoset_sample_identifier_object_info

Module

Matching