ClassesClassesClassesClasses | | | | Operators

apply_sample_identifierT_apply_sample_identifierApplySampleIdentifierapply_sample_identifierApplySampleIdentifierApplySampleIdentifier (Operator)

Name

apply_sample_identifierT_apply_sample_identifierApplySampleIdentifierapply_sample_identifierApplySampleIdentifierApplySampleIdentifier — 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)

Herror apply_sample_identifier(Hobject Image, const HTuple& SampleIdentifier, const HTuple& NumResults, const HTuple& RatingThreshold, const HTuple& GenParamName, const HTuple& GenParamValue, Hlong* ObjectIdx, double* Rating)

Herror apply_sample_identifier(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, const HTuple& NumResults, const HTuple& RatingThreshold, const HTuple& GenParamName, const HTuple& GenParamValue, HTuple* Rating) const

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

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

void HOperatorSetX.ApplySampleIdentifier(
[in] IHUntypedObjectX* Image, [in] VARIANT SampleIdentifier, [in] VARIANT NumResults, [in] VARIANT RatingThreshold, [in] VARIANT GenParamName, [in] VARIANT GenParamValue, [out] VARIANT* ObjectIdx, [out] VARIANT* Rating)

VARIANT HImageX.ApplySampleIdentifier(
[in] IHSampleIdentifierX* SampleIdentifier, [in] Hlong NumResults, [in] double RatingThreshold, [in] VARIANT GenParamName, [in] VARIANT GenParamValue, [out] VARIANT* Rating)

VARIANT HSampleIdentifierX.ApplySampleIdentifier(
[in] IHImageX* Image, [in] Hlong NumResults, [in] double RatingThreshold, [in] VARIANT GenParamName, [in] VARIANT GenParamValue, [out] VARIANT* Rating)

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)

Description

apply_sample_identifierapply_sample_identifierApplySampleIdentifierapply_sample_identifierApplySampleIdentifierApplySampleIdentifier identifies the object in the ImageImageImageImageImageimage using the given SampleIdentifierSampleIdentifierSampleIdentifierSampleIdentifierSampleIdentifiersampleIdentifier and returns the corresponding ObjectIdxObjectIdxObjectIdxObjectIdxObjectIdxobjectIdx.

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

The operator apply_sample_identifierapply_sample_identifierApplySampleIdentifierapply_sample_identifierApplySampleIdentifierApplySampleIdentifier 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 NumResultsNumResultsNumResultsNumResultsNumResultsnumResults 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 RatingThresholdRatingThresholdRatingThresholdRatingThresholdRatingThresholdratingThreshold.

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

The following generic parameters can be used to influence the behavior of the SampleIdentifierSampleIdentifierSampleIdentifierSampleIdentifierSampleIdentifiersampleIdentifier. These parameters and their corresponding values can be specified by using GenParamNameGenParamNameGenParamNameGenParamNameGenParamNamegenParamName and GenParamValueGenParamValueGenParamValueGenParamValueGenParamValuegenParamValue, respectively. The following values for GenParamNameGenParamNameGenParamNameGenParamNameGenParamNamegenParamName 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 RatingThresholdRatingThresholdRatingThresholdRatingThresholdRatingThresholdratingThreshold 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 RatingThresholdRatingThresholdRatingThresholdRatingThresholdRatingThresholdratingThreshold 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_paramSetSampleIdentifierParamset_sample_identifier_paramSetSampleIdentifierParamSetSampleIdentifierParam 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_identifierCreateSampleIdentifiercreate_sample_identifierCreateSampleIdentifierCreateSampleIdentifier 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_paramSetSampleIdentifierParamset_sample_identifier_paramSetSampleIdentifierParamSetSampleIdentifierParam 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_identifierCreateSampleIdentifiercreate_sample_identifierCreateSampleIdentifierCreateSampleIdentifier 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_identifierCreateSampleIdentifiercreate_sample_identifierCreateSampleIdentifierCreateSampleIdentifier 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_identifierCreateSampleIdentifiercreate_sample_identifierCreateSampleIdentifierCreateSampleIdentifier or set_sample_identifier_paramset_sample_identifier_paramSetSampleIdentifierParamset_sample_identifier_paramSetSampleIdentifierParamSetSampleIdentifierParam 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_identifierCreateSampleIdentifiercreate_sample_identifierCreateSampleIdentifierCreateSampleIdentifier 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_identifierCreateSampleIdentifiercreate_sample_identifierCreateSampleIdentifierCreateSampleIdentifier or set_sample_identifier_paramset_sample_identifier_paramSetSampleIdentifierParamset_sample_identifier_paramSetSampleIdentifierParamSetSampleIdentifierParam will be used.

Parallelization

Parameters

ImageImageImageImageImageimage (input_object)  (multichannel-)image objectHImageHImageHImageHImageXHobject (byte)

Image showing the object to be identified.

SampleIdentifierSampleIdentifierSampleIdentifierSampleIdentifierSampleIdentifiersampleIdentifier (input_control)  sample_identifier HSampleIdentifier, HTupleHTupleHSampleIdentifier, HTupleHSampleIdentifierX, VARIANTHtuple (integer) (IntPtr) (Hlong) (Hlong) (Hlong) (Hlong)

Handle of the sample identifier.

NumResultsNumResultsNumResultsNumResultsNumResultsnumResults (input_control)  integer HTupleHTupleHTupleVARIANTHtuple (integer) (int / long) (Hlong) (Hlong) (Hlong) (Hlong)

Number of suggested object indices.

Default value: 1

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

RatingThresholdRatingThresholdRatingThresholdRatingThresholdRatingThresholdratingThreshold (input_control)  real HTupleHTupleHTupleVARIANTHtuple (real) (double) (double) (double) (double) (double)

Rating threshold.

Default value: 0.0

Suggested values: 0.05, 0.1, 0.15, 0.2

GenParamNameGenParamNameGenParamNameGenParamNameGenParamNamegenParamName (input_control)  attribute.name-array HTupleHTupleHTupleVARIANTHtuple (string) (string) (HString) (char*) (BSTR) (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"

GenParamValueGenParamValueGenParamValueGenParamValueGenParamValuegenParamValue (input_control)  attribute.value-array HTupleHTupleHTupleVARIANTHtuple (real / string / integer) (double / string / int / long) (double / HString / Hlong) (double / char* / Hlong) (double / BSTR / 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"

ObjectIdxObjectIdxObjectIdxObjectIdxObjectIdxobjectIdx (output_control)  integer(-array) HTupleHTupleHTupleVARIANTHtuple (integer) (int / long) (Hlong) (Hlong) (Hlong) (Hlong)

Index of the identified object.

RatingRatingRatingRatingRatingrating (output_control)  real(-array) HTupleHTupleHTupleVARIANTHtuple (real) (double) (double) (double) (double) (double)

Rating value of the identified object.

Result

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

Possible Predecessors

train_sample_identifiertrain_sample_identifierTrainSampleIdentifiertrain_sample_identifierTrainSampleIdentifierTrainSampleIdentifier, read_sample_identifierread_sample_identifierReadSampleIdentifierread_sample_identifierReadSampleIdentifierReadSampleIdentifier

Possible Successors

add_sample_identifier_training_dataadd_sample_identifier_training_dataAddSampleIdentifierTrainingDataadd_sample_identifier_training_dataAddSampleIdentifierTrainingDataAddSampleIdentifierTrainingData

See also

create_sample_identifiercreate_sample_identifierCreateSampleIdentifiercreate_sample_identifierCreateSampleIdentifierCreateSampleIdentifier, add_sample_identifier_preparation_dataadd_sample_identifier_preparation_dataAddSampleIdentifierPreparationDataadd_sample_identifier_preparation_dataAddSampleIdentifierPreparationDataAddSampleIdentifierPreparationData, prepare_sample_identifierprepare_sample_identifierPrepareSampleIdentifierprepare_sample_identifierPrepareSampleIdentifierPrepareSampleIdentifier, set_sample_identifier_paramset_sample_identifier_paramSetSampleIdentifierParamset_sample_identifier_paramSetSampleIdentifierParamSetSampleIdentifierParam, get_sample_identifier_paramget_sample_identifier_paramGetSampleIdentifierParamget_sample_identifier_paramGetSampleIdentifierParamGetSampleIdentifierParam, get_sample_identifier_object_infoget_sample_identifier_object_infoGetSampleIdentifierObjectInfoget_sample_identifier_object_infoGetSampleIdentifierObjectInfoGetSampleIdentifierObjectInfo, remove_sample_identifier_preparation_dataremove_sample_identifier_preparation_dataRemoveSampleIdentifierPreparationDataremove_sample_identifier_preparation_dataRemoveSampleIdentifierPreparationDataRemoveSampleIdentifierPreparationData, remove_sample_identifier_training_dataremove_sample_identifier_training_dataRemoveSampleIdentifierTrainingDataremove_sample_identifier_training_dataRemoveSampleIdentifierTrainingDataRemoveSampleIdentifierTrainingData, write_sample_identifierwrite_sample_identifierWriteSampleIdentifierwrite_sample_identifierWriteSampleIdentifierWriteSampleIdentifier, serialize_sample_identifierserialize_sample_identifierSerializeSampleIdentifierserialize_sample_identifierSerializeSampleIdentifierSerializeSampleIdentifier, deserialize_sample_identifierdeserialize_sample_identifierDeserializeSampleIdentifierdeserialize_sample_identifierDeserializeSampleIdentifierDeserializeSampleIdentifier, clear_sample_identifierclear_sample_identifierClearSampleIdentifierclear_sample_identifierClearSampleIdentifierClearSampleIdentifier, set_sample_identifier_object_infoset_sample_identifier_object_infoSetSampleIdentifierObjectInfoset_sample_identifier_object_infoSetSampleIdentifierObjectInfoSetSampleIdentifierObjectInfo

Module

Matching


ClassesClassesClassesClasses | | | | Operators