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
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_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 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
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 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_paramSetSampleIdentifierParamSetSampleIdentifierParamset_sample_identifier_param
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_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 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_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 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_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 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_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
ImageImageImageimageimage (input_object) (multichannel-)image → objectHImageHObjectHObjectHobject (byte)
Image showing the object to be identified.
SampleIdentifierSampleIdentifierSampleIdentifiersampleIdentifiersample_identifier (input_control) sample_identifier → HSampleIdentifier, HTupleHHandleHTupleHtuple (handle) (IntPtr) (HHandle) (handle)
Handle of the sample identifier.
NumResultsNumResultsNumResultsnumResultsnum_results (input_control) integer → HTupleintHTupleHtuple (integer) (int / long) (Hlong) (Hlong)
Number of suggested object indices.
Default:
1
Suggested values:
1, 2, 3, 4, 5, 10
RatingThresholdRatingThresholdRatingThresholdratingThresholdrating_threshold (input_control) real → HTuplefloatHTupleHtuple (real) (double) (double) (double)
Rating threshold.
Default:
0.0
Suggested values:
0.05, 0.1, 0.15, 0.2
GenParamNameGenParamNameGenParamNamegenParamNamegen_param_name (input_control) attribute.name-array → HTupleSequence[str]HTupleHtuple (string) (string) (HString) (char*)
Generic parameter name.
Default:
[]
List of values:
'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_value'"image_resize_value""image_resize_value""image_resize_value""image_resize_value", '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_texture_info'"use_texture_info""use_texture_info""use_texture_info""use_texture_info"
GenParamValueGenParamValueGenParamValuegenParamValuegen_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:
[]
List of values:
'distance'"distance""distance""distance""distance", 'false'"false""false""false""false", 'score'"score""score""score""score", 'score_single'"score_single""score_single""score_single""score_single", 'true'"true""true""true""true"
ObjectIdxObjectIdxObjectIdxobjectIdxobject_idx (output_control) integer(-array) → HTupleSequence[int]HTupleHtuple (integer) (int / long) (Hlong) (Hlong)
Index of the identified object.
RatingRatingRatingratingrating (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_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