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.

Warning

prepare_sample_identifierprepare_sample_identifierPrepareSampleIdentifierPrepareSampleIdentifierprepare_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

prepare_sample_identifier( : : SampleIdentifier, RemovePreparationData, GenParamName, GenParamValue : )

Description

prepare_sample_identifierprepare_sample_identifierPrepareSampleIdentifierPrepareSampleIdentifierprepare_sample_identifier prepares the given SampleIdentifierSampleIdentifierSampleIdentifiersampleIdentifiersample_identifier using the preparation data, which have been set with add_sample_identifier_preparation_dataadd_sample_identifier_preparation_dataAddSampleIdentifierPreparationDataAddSampleIdentifierPreparationDataadd_sample_identifier_preparation_data.

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

In order to achieve the maximum identification rate, the internal data structure of the SampleIdentifierSampleIdentifierSampleIdentifiersampleIdentifiersample_identifier must be adapted to the kind of objects to be identified.

To prepare the SampleIdentifierSampleIdentifierSampleIdentifiersampleIdentifiersample_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_dataAddSampleIdentifierPreparationDataAddSampleIdentifierPreparationDataadd_sample_identifier_preparation_data. Then, with the call of prepare_sample_identifierprepare_sample_identifierPrepareSampleIdentifierPrepareSampleIdentifierprepare_sample_identifier, the internal data structure of the SampleIdentifierSampleIdentifierSampleIdentifiersampleIdentifiersample_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 RemovePreparationDataRemovePreparationDataRemovePreparationDataremovePreparationDataremove_preparation_data to '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_identifierReadSampleIdentifierReadSampleIdentifierread_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_dataAddSampleIdentifierTrainingDataAddSampleIdentifierTrainingDataadd_sample_identifier_training_data (see train_sample_identifiertrain_sample_identifierTrainSampleIdentifierTrainSampleIdentifiertrain_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' is set to '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_dataAddSampleIdentifierPreparationDataAddSampleIdentifierPreparationDataadd_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_dataAddSampleIdentifierPreparationDataAddSampleIdentifierPreparationDataadd_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

SampleIdentifierSampleIdentifierSampleIdentifiersampleIdentifiersample_identifier (input_control) sample_identifier → (handle)

Handle of the sample identifier.

RemovePreparationDataRemovePreparationDataRemovePreparationDataremovePreparationDataremove_preparation_data (input_control) string → (string)

Indicates if the preparation data should be removed.

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

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

GenParamNameGenParamNameGenParamNamegenParamNamegen_param_name (input_control) attribute.name-array → (string)

Generic parameter name.

Default: []

List of values: 'copy_preparation_data_to_training_data'

GenParamValueGenParamValueGenParamValuegenParamValuegen_param_value (input_control) attribute.value-array → (string / integer / real)

Generic parameter value.

Default: []

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

Result

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