prepare_sample_identifierT_prepare_sample_identifierPrepareSampleIdentifierPrepareSampleIdentifierprepare_sample_identifier (Operator)
Name
prepare_sample_identifierT_prepare_sample_identifierPrepareSampleIdentifierPrepareSampleIdentifierprepare_sample_identifier — Adapt the internal data structure of a sample identifier to the objects to
be identified.
Signature
Description
prepare_sample_identifierprepare_sample_identifierPrepareSampleIdentifierPrepareSampleIdentifierPrepareSampleIdentifierprepare_sample_identifier prepares the given
SampleIdentifierSampleIdentifierSampleIdentifierSampleIdentifiersampleIdentifiersample_identifier using the preparation data, which have been set
with add_sample_identifier_preparation_dataadd_sample_identifier_preparation_dataAddSampleIdentifierPreparationDataAddSampleIdentifierPreparationDataAddSampleIdentifierPreparationDataadd_sample_identifier_preparation_data.
For an explanation of the concept of sample-based identification
see the introduction of chapter Identification / Sample-Based.
In order to achieve the maximum identification rate, the internal data
structure of the SampleIdentifierSampleIdentifierSampleIdentifierSampleIdentifiersampleIdentifiersample_identifier must be adapted to the kind of
objects to be identified.
To prepare the SampleIdentifierSampleIdentifierSampleIdentifierSampleIdentifiersampleIdentifiersample_identifier, first, all the relevant sample
images of the objects to be identified must be added with
add_sample_identifier_preparation_dataadd_sample_identifier_preparation_dataAddSampleIdentifierPreparationDataAddSampleIdentifierPreparationDataAddSampleIdentifierPreparationDataadd_sample_identifier_preparation_data. Then, with the call of
prepare_sample_identifierprepare_sample_identifierPrepareSampleIdentifierPrepareSampleIdentifierPrepareSampleIdentifierprepare_sample_identifier, the internal data structure of the
SampleIdentifierSampleIdentifierSampleIdentifierSampleIdentifiersampleIdentifiersample_identifier is adapted to the features of the provided sample
images.
This process needs a lot of resources. Both, memory consumption and runtime
are fairly high. E.g., if 100 sample images are used to prepare the sample
identifier, approximately 300 MB of memory are required and the runtime will
be in the range of a few minutes. If 1000 sample images are used, expect a
memory consumption of about 2 GB and a runtime in the range of an hour.
Especially the preparation data requires a lot of memory. Typically, this
data is no longer needed after the preparation of the sample identifier.
Therefore, it can be removed by setting the parameter
RemovePreparationDataRemovePreparationDataRemovePreparationDataRemovePreparationDataremovePreparationDataremove_preparation_data to 'true'"true""true""true""true""true".
As an alternative to the preparation, e.g., if you are not able to spend
this much memory and/or time, and if you are fine with a slightly higher
misidentification rate, you can just read a sample identifier that
was previously prepared with samples of similar object kinds from file (see
read_sample_identifierread_sample_identifierReadSampleIdentifierReadSampleIdentifierReadSampleIdentifierread_sample_identifier).
To reuse the preparation data for the training, you can derive training data
from the preparation data. This saves the effort to add training data
separately with add_sample_identifier_training_dataadd_sample_identifier_training_dataAddSampleIdentifierTrainingDataAddSampleIdentifierTrainingDataAddSampleIdentifierTrainingDataadd_sample_identifier_training_data (see
train_sample_identifiertrain_sample_identifierTrainSampleIdentifierTrainSampleIdentifierTrainSampleIdentifiertrain_sample_identifier for a description of the training of the
sample identifier). Note that the training data require far less memory than
the preparation data. If the generic parameter
'copy_preparation_data_to_training_data'"copy_preparation_data_to_training_data""copy_preparation_data_to_training_data""copy_preparation_data_to_training_data""copy_preparation_data_to_training_data""copy_preparation_data_to_training_data" is set to 'true'"true""true""true""true""true"
(which is the default), for all sample images that have been added with
add_sample_identifier_preparation_dataadd_sample_identifier_preparation_dataAddSampleIdentifierPreparationDataAddSampleIdentifierPreparationDataAddSampleIdentifierPreparationDataadd_sample_identifier_preparation_data and for which the object
index has been set, training data is automatically derived. The object index
that has been set with add_sample_identifier_preparation_dataadd_sample_identifier_preparation_dataAddSampleIdentifierPreparationDataAddSampleIdentifierPreparationDataAddSampleIdentifierPreparationDataadd_sample_identifier_preparation_data is
taken unchanged. But note that the object sample index may be changed,
because it is renumbered consecutively, starting with zero.
Execution Information
- Multithreading type: reentrant (runs in parallel with non-exclusive operators).
- Multithreading scope: global (may be called from any thread).
- Processed without parallelization.
Parameters
SampleIdentifierSampleIdentifierSampleIdentifierSampleIdentifiersampleIdentifiersample_identifier (input_control) sample_identifier → HSampleIdentifier, HTupleHHandleHTupleHtuple (handle) (IntPtr) (HHandle) (handle)
Handle of the sample identifier.
RemovePreparationDataRemovePreparationDataRemovePreparationDataRemovePreparationDataremovePreparationDataremove_preparation_data (input_control) string → HTuplestrHTupleHtuple (string) (string) (HString) (char*)
Indicates if the preparation data should be removed.
Default value:
'true'
"true"
"true"
"true"
"true"
"true"
List of values: 'false'"false""false""false""false""false", 'true'"true""true""true""true""true"
GenParamNameGenParamNameGenParamNameGenParamNamegenParamNamegen_param_name (input_control) attribute.name-array → HTupleSequence[str]HTupleHtuple (string) (string) (HString) (char*)
Generic parameter name.
Default value: []
List of values: 'copy_preparation_data_to_training_data'"copy_preparation_data_to_training_data""copy_preparation_data_to_training_data""copy_preparation_data_to_training_data""copy_preparation_data_to_training_data""copy_preparation_data_to_training_data"
GenParamValueGenParamValueGenParamValueGenParamValuegenParamValuegen_param_value (input_control) attribute.value-array → HTupleSequence[Union[str, int, float]]HTupleHtuple (string / integer / real) (string / int / long / double) (HString / Hlong / double) (char* / Hlong / double)
Generic parameter value.
Default value: []
List of values: 'false'"false""false""false""false""false", 'true'"true""true""true""true""true"
Result
If the parameters are valid, the operator prepare_sample_identifierprepare_sample_identifierPrepareSampleIdentifierPrepareSampleIdentifierPrepareSampleIdentifierprepare_sample_identifier
returns the value 2 (H_MSG_TRUE). If necessary an exception is raised.
Possible Predecessors
add_sample_identifier_preparation_dataadd_sample_identifier_preparation_dataAddSampleIdentifierPreparationDataAddSampleIdentifierPreparationDataAddSampleIdentifierPreparationDataadd_sample_identifier_preparation_data
Possible Successors
write_sample_identifierwrite_sample_identifierWriteSampleIdentifierWriteSampleIdentifierWriteSampleIdentifierwrite_sample_identifier,
add_sample_identifier_training_dataadd_sample_identifier_training_dataAddSampleIdentifierTrainingDataAddSampleIdentifierTrainingDataAddSampleIdentifierTrainingDataadd_sample_identifier_training_data,
train_sample_identifiertrain_sample_identifierTrainSampleIdentifierTrainSampleIdentifierTrainSampleIdentifiertrain_sample_identifier
Alternatives
read_sample_identifierread_sample_identifierReadSampleIdentifierReadSampleIdentifierReadSampleIdentifierread_sample_identifier
See also
create_sample_identifiercreate_sample_identifierCreateSampleIdentifierCreateSampleIdentifierCreateSampleIdentifiercreate_sample_identifier,
apply_sample_identifierapply_sample_identifierApplySampleIdentifierApplySampleIdentifierApplySampleIdentifierapply_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