Name
create_sample_identifierT_create_sample_identifierCreateSampleIdentifiercreate_sample_identifierCreateSampleIdentifierCreateSampleIdentifier — Create a new sample identifier.
The operator create_sample_identifiercreate_sample_identifierCreateSampleIdentifiercreate_sample_identifierCreateSampleIdentifierCreateSampleIdentifier creates a new sample
identifier. Alternatively, an already available sample identifier can be
read from file with the operator read_sample_identifierread_sample_identifierReadSampleIdentifierread_sample_identifierReadSampleIdentifierReadSampleIdentifier. See below
for a description of the concept of sample-based identification.
Note that if you want to use color information, you must specify this
explicitly by setting the generic parameter 'add_color_info'"add_color_info""add_color_info""add_color_info""add_color_info""add_color_info" to
'true'"true""true""true""true""true".
The generic parameters can be used to influence the behavior of the sample
identifier. Typically, only 'add_color_info'"add_color_info""add_color_info""add_color_info""add_color_info""add_color_info" must be considered.
The parameters and their corresponding values can be specified by using
ParamNameParamNameParamNameParamNameParamNameparamName and ParamValueParamValueParamValueParamValueParamValueparamValue, respectively. The following
values for ParamNameParamNameParamNameParamNameParamNameparamName are possible:
- 'add_color_info'"add_color_info""add_color_info""add_color_info""add_color_info""add_color_info":
-
This parameter determines if color
information is used for the identification. If 'add_color_info'"add_color_info""add_color_info""add_color_info""add_color_info""add_color_info"
is set to 'true'"true""true""true""true""true", color information is used. Note that in this
case, all images used for the preparation and the training of the sample
identifier must be RGB color images. If 'add_color_info'"add_color_info""add_color_info""add_color_info""add_color_info""add_color_info" is set
to 'false'"false""false""false""false""false", no color information is used. Use color information,
if the objects to be identified have different colors and if the
illumination can be controlled to some degree. In this case, the use of
color information makes the identification more robust.
List of values: 'true'"true""true""true""true""true", 'false'"false""false""false""false""false"
Default value: 'false'"false""false""false""false""false"
- 'add_texture_info'"add_texture_info""add_texture_info""add_texture_info""add_texture_info""add_texture_info":
-
This parameter determines if texture
information is used for the identification. If 'add_texture_info'"add_texture_info""add_texture_info""add_texture_info""add_texture_info""add_texture_info"
is set to 'true'"true""true""true""true""true", texture information is used. If
'add_texture_info'"add_texture_info""add_texture_info""add_texture_info""add_texture_info""add_texture_info" is set to 'false'"false""false""false""false""false", no texture
information is used. Typically, 'add_texture_info'"add_texture_info""add_texture_info""add_texture_info""add_texture_info""add_texture_info" should be set
to 'true'"true""true""true""true""true", because sample-based identification requires textured
objects. Note that at least one of the two generic parameters
'add_color_info'"add_color_info""add_color_info""add_color_info""add_color_info""add_color_info" and 'add_texture_info'"add_texture_info""add_texture_info""add_texture_info""add_texture_info""add_texture_info" must be set to
'true'"true""true""true""true""true".
List of values: 'true'"true""true""true""true""true", 'false'"false""false""false""false""false"
Default value: 'true'"true""true""true""true""true"
- 'image_resize_method'"image_resize_method""image_resize_method""image_resize_method""image_resize_method""image_resize_method":
-
To speed up the identification
process, the images are resized internally to a given size or by a given
factor. If 'none'"none""none""none""none""none" is selected, no resizing will be done. For
'scale_factor'"scale_factor""scale_factor""scale_factor""scale_factor""scale_factor", a constant scale factor can be set and for
'subsampling_step'"subsampling_step""subsampling_step""subsampling_step""subsampling_step""subsampling_step", a constant subsampling step, i.e., the
inverse of the scale factor can be set. Finally, for
'image_area'"image_area""image_area""image_area""image_area""image_area", a constant size of the resized image can be
specified. The corresponding values can be set with the
'image_resize_value'"image_resize_value""image_resize_value""image_resize_value""image_resize_value""image_resize_value" (see below).
To make the identification process faster, choose parameters that lead to
a smaller internal image, i.e., use smaller scale factors or image sizes
or a larger subsampling step. If the objects to be identified show
high-frequency texture, the identification result may become better, if a
larger internal image size is used, because otherwise the texture may be
eliminated in the resized images.
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: 'image_area'"image_area""image_area""image_area""image_area""image_area"
- 'image_resize_value'"image_resize_value""image_resize_value""image_resize_value""image_resize_value""image_resize_value":
-
With this parameter, the selected
'image_resize_method'"image_resize_method""image_resize_method""image_resize_method""image_resize_method""image_resize_method" can be parameterized. If
'image_resize_method'"image_resize_method""image_resize_method""image_resize_method""image_resize_method""image_resize_method" is set to 'scale_factor'"scale_factor""scale_factor""scale_factor""scale_factor""scale_factor", the
value of 'image_resize_value'"image_resize_value""image_resize_value""image_resize_value""image_resize_value""image_resize_value" defines the scale factor to be
used. If 'image_resize_method'"image_resize_method""image_resize_method""image_resize_method""image_resize_method""image_resize_method" is set to
'subsampling_step'"subsampling_step""subsampling_step""subsampling_step""subsampling_step""subsampling_step", the value of 'image_resize_value'"image_resize_value""image_resize_value""image_resize_value""image_resize_value""image_resize_value"
defines the subsampling step, i.e., the inverse of the scale factor. If
'image_resize_method'"image_resize_method""image_resize_method""image_resize_method""image_resize_method""image_resize_method" is set to 'image_area'"image_area""image_area""image_area""image_area""image_area", the value
of 'image_resize_value'"image_resize_value""image_resize_value""image_resize_value""image_resize_value""image_resize_value" defines the area of the resized image
given in megapixels, i.e., in million pixels.
Suggested values: 0.25, 0.5, 1.0,
2, 3, 4
Default value: The default value depends on the selected
'image_resize_method'"image_resize_method""image_resize_method""image_resize_method""image_resize_method""image_resize_method". It is
-
0.5 for 'scale_factor'"scale_factor""scale_factor""scale_factor""scale_factor""scale_factor",
-
2.0 for 'subsampling_step'"subsampling_step""subsampling_step""subsampling_step""subsampling_step""subsampling_step", and
-
0.5 for 'image_area'"image_area""image_area""image_area""image_area""image_area".
Concept of sample-based identification
With sample-based identification, trained objects can be identified based on
characteristic features like texture or color. This allows you to identify
objects that do not carry bar codes or data codes. Sample-based
identification is capable of differentiating a large number of objects. The
identification is robust against rotation, scale, and illumination changes
as well as against occlusions, clutter, and moderate perspective
distortions. Furthermore, the identification is robust against moderate
deformations of the object and, within certain limits, it even allows
to identify products stored in bulk. On the other hand, this means,
that objects cannot be distinguished, if they appear identical except
for one of the characteristics the identification is robust against.
Note that sample-based identification works only with textured
objects.
Sample-based identification can identify only one object at the same time.
This means that each query image, or more precisely the domain of each query
image, must not contain multiple objects.
In the following, the steps that are required to use sample-based
identification are described briefly.
First, a sample identifier must be provided by creating and preparing a new
sample identifier with create_sample_identifiercreate_sample_identifierCreateSampleIdentifiercreate_sample_identifierCreateSampleIdentifierCreateSampleIdentifier,
add_sample_identifier_preparation_dataadd_sample_identifier_preparation_dataAddSampleIdentifierPreparationDataadd_sample_identifier_preparation_dataAddSampleIdentifierPreparationDataAddSampleIdentifierPreparationData, and
prepare_sample_identifierprepare_sample_identifierPrepareSampleIdentifierprepare_sample_identifierPrepareSampleIdentifierPrepareSampleIdentifier. The preparation is essential to adapt
the internal data structure of the sample identifier to the kind of objects
to be identified. Alternatively, an already prepared sample identifier can
be read from file with read_sample_identifierread_sample_identifierReadSampleIdentifierread_sample_identifierReadSampleIdentifierReadSampleIdentifier. A prepared sample
identifier can be thought of as a warehouse, optimized to handle a specific
group of objects.
Then, the prepared sample identifier has to be trained with samples of the
individual objects to be identified. For this, the operators
add_sample_identifier_training_dataadd_sample_identifier_training_dataAddSampleIdentifierTrainingDataadd_sample_identifier_training_dataAddSampleIdentifierTrainingDataAddSampleIdentifierTrainingData and
train_sample_identifiertrain_sample_identifierTrainSampleIdentifiertrain_sample_identifierTrainSampleIdentifierTrainSampleIdentifier are used. Note that it is possible to
retrain the sample identifier at any time. For this, samples can be removed
from the sample identifier with the operator
remove_sample_identifier_training_dataremove_sample_identifier_training_dataRemoveSampleIdentifierTrainingDataremove_sample_identifier_training_dataRemoveSampleIdentifierTrainingDataRemoveSampleIdentifierTrainingData and new samples can be added
to the sample identifier with the operator
add_sample_identifier_training_dataadd_sample_identifier_training_dataAddSampleIdentifierTrainingDataadd_sample_identifier_training_dataAddSampleIdentifierTrainingDataAddSampleIdentifierTrainingData. If the kind of the objects to
be identified does not change too much, it is not necessary to repeat the
preparation of the sample identifier. To use the picture from above, the
training corresponds to filling the warehouse.
Finally, the trained sample identifier can be applied to identify objects
with apply_sample_identifierapply_sample_identifierApplySampleIdentifierapply_sample_identifierApplySampleIdentifierApplySampleIdentifier.
Further operators to administrate and control sample identifiers
In addition to the operators mentioned above, the following operators can be
used to administrate the sample identifier. With
remove_sample_identifier_preparation_dataremove_sample_identifier_preparation_dataRemoveSampleIdentifierPreparationDataremove_sample_identifier_preparation_dataRemoveSampleIdentifierPreparationDataRemoveSampleIdentifierPreparationData and
remove_sample_identifier_training_dataremove_sample_identifier_training_dataRemoveSampleIdentifierTrainingDataremove_sample_identifier_training_dataRemoveSampleIdentifierTrainingDataRemoveSampleIdentifierTrainingData, the data that were added to
the sample identifier can be removed in order to exclude them from being
used for preparation or training. The operators
set_sample_identifier_object_infoset_sample_identifier_object_infoSetSampleIdentifierObjectInfoset_sample_identifier_object_infoSetSampleIdentifierObjectInfoSetSampleIdentifierObjectInfo and
get_sample_identifier_object_infoget_sample_identifier_object_infoGetSampleIdentifierObjectInfoget_sample_identifier_object_infoGetSampleIdentifierObjectInfoGetSampleIdentifierObjectInfo can be used to assign and query
labels, i.e, names, to the individual objects. Furthermore, some additional
information about the number of objects available for preparation and
training can be determined with get_sample_identifier_object_infoget_sample_identifier_object_infoGetSampleIdentifierObjectInfoget_sample_identifier_object_infoGetSampleIdentifierObjectInfoGetSampleIdentifierObjectInfo.
Finally, the operators set_sample_identifier_paramset_sample_identifier_paramSetSampleIdentifierParamset_sample_identifier_paramSetSampleIdentifierParamSetSampleIdentifierParam and
get_sample_identifier_paramget_sample_identifier_paramGetSampleIdentifierParamget_sample_identifier_paramGetSampleIdentifierParamGetSampleIdentifierParam can be used to set and retrieve control
parameters of the sample identifier.
Glossary
In the following, the most important terms that are used in the context of
sample-based identification are described:
- object
-
An object to be identified by sample-based identification.
- object index
-
The index of an object. This index can be seen as a
label of the object, which is set while adding preparation data or training
data to the SampleIdentifierSampleIdentifierSampleIdentifierSampleIdentifierSampleIdentifiersampleIdentifier. The object index is the most
important result of the operator apply_sample_identifierapply_sample_identifierApplySampleIdentifierapply_sample_identifierApplySampleIdentifierApplySampleIdentifier. With the
operator set_sample_identifier_object_infoset_sample_identifier_object_infoSetSampleIdentifierObjectInfoset_sample_identifier_object_infoSetSampleIdentifierObjectInfoSetSampleIdentifierObjectInfo, a descriptive name can
be set for each object, which eases the interpretation of the identification
results.
- object sample
-
One sample or view of an object. Sometimes, also the
term “sample image” is used to refer to object samples.
- sample image
-
This term is used as a synonym for “object sample”, if
the emphasis lies on the image.
- object sample index
-
The index of an object sample. Note that for each
object, this index is set individually starting with 0. Therefore,
the object sample index is unambiguous only together with the respective
object index.
- preparation
-
The adaptation of the internal data structure of the
sample identifier to the features of a typical set of object samples that
may appear during the identification process.
- preparation object
-
An object that has been added to the sample
identifier with add_sample_identifier_preparation_dataadd_sample_identifier_preparation_dataAddSampleIdentifierPreparationDataadd_sample_identifier_preparation_dataAddSampleIdentifierPreparationDataAddSampleIdentifierPreparationData.
- preparation sample
-
An object sample of a preparation object. The
preparation is typically done based on multiple preparation samples per
object.
- preparation data
-
The collection of all preparation samples.
- training
-
The training of the sample identifier. In this step, the
sample identifier learns to differentiate all given objects.
- training object
-
An object that has been added to the sample
identifier with add_sample_identifier_training_dataadd_sample_identifier_training_dataAddSampleIdentifierTrainingDataadd_sample_identifier_training_dataAddSampleIdentifierTrainingDataAddSampleIdentifierTrainingData or which is the
result of reusing preparation data as training data. In contrast to
preparation objects, all training objects are labeled with a unique object
index.
- training sample
-
An object sample of a training object. The training
is typically done based on multiple training samples per object.
- training data
-
The collection of all training samples.
- query image
-
An image, in which an object is visible that should be
identified with sample-based identification.
- Multithreading type: reentrant (runs in parallel with non-exclusive operators).
- Multithreading scope: global (may be called from any thread).
- Processed without parallelization.
Parameter name.
Default value: []
List of values: 'add_color_info'"add_color_info""add_color_info""add_color_info""add_color_info""add_color_info", 'add_texture_info'"add_texture_info""add_texture_info""add_texture_info""add_texture_info""add_texture_info", '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"
Parameter value.
Default value: []
List of values: 0.25, 0.5, 0.75, 1.0, 2, 3, 4, 'false'"false""false""false""false""false", 'image_area'"image_area""image_area""image_area""image_area""image_area", '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", 'true'"true""true""true""true""true"
Handle of the sample identifier.
If the parameters are valid, the operator create_sample_identifiercreate_sample_identifierCreateSampleIdentifiercreate_sample_identifierCreateSampleIdentifierCreateSampleIdentifier
returns the value 2 (H_MSG_TRUE). If necessary an exception is raised.
add_sample_identifier_preparation_dataadd_sample_identifier_preparation_dataAddSampleIdentifierPreparationDataadd_sample_identifier_preparation_dataAddSampleIdentifierPreparationDataAddSampleIdentifierPreparationData,
set_sample_identifier_paramset_sample_identifier_paramSetSampleIdentifierParamset_sample_identifier_paramSetSampleIdentifierParamSetSampleIdentifierParam
read_sample_identifierread_sample_identifierReadSampleIdentifierread_sample_identifierReadSampleIdentifierReadSampleIdentifier
prepare_sample_identifierprepare_sample_identifierPrepareSampleIdentifierprepare_sample_identifierPrepareSampleIdentifierPrepareSampleIdentifier,
add_sample_identifier_training_dataadd_sample_identifier_training_dataAddSampleIdentifierTrainingDataadd_sample_identifier_training_dataAddSampleIdentifierTrainingDataAddSampleIdentifierTrainingData,
train_sample_identifiertrain_sample_identifierTrainSampleIdentifiertrain_sample_identifierTrainSampleIdentifierTrainSampleIdentifier,
apply_sample_identifierapply_sample_identifierApplySampleIdentifierapply_sample_identifierApplySampleIdentifierApplySampleIdentifier,
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,
clear_all_sample_identifiersclear_all_sample_identifiersClearAllSampleIdentifiersclear_all_sample_identifiersClearAllSampleIdentifiersClearAllSampleIdentifiers,
set_sample_identifier_object_infoset_sample_identifier_object_infoSetSampleIdentifierObjectInfoset_sample_identifier_object_infoSetSampleIdentifierObjectInfoSetSampleIdentifierObjectInfo
Matching