create_sample_identifier — Create a new sample identifier.
The operator create_sample_identifier creates a new sample identifier. Alternatively, an already available sample identifier can be read from file with the operator read_sample_identifier. 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' to 'true'.
The generic parameters can be used to influence the behavior of the sample identifier. Typically, only 'add_color_info' must be considered. The parameters and their corresponding values can be specified by using ParamName and ParamValue, respectively. The following values for ParamName are possible:
This parameter determines if color information is used for the identification. If 'add_color_info' is set to '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' is set to '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', 'false'
Default value: 'false'
This parameter determines if texture information is used for the identification. If 'add_texture_info' is set to 'true', texture information is used. If 'add_texture_info' is set to 'false', no texture information is used. Typically, 'add_texture_info' should be set to 'true', because sample-based identification requires textured objects. Note that at least one of the two generic parameters 'add_color_info' and 'add_texture_info' must be set to 'true'.
List of values: 'true', 'false'
Default value: 'true'
To speed up the identification process, the images are resized internally to a given size or by a given factor. If 'none' is selected, no resizing will be done. For 'scale_factor', a constant scale factor can be set and for 'subsampling_step', a constant subsampling step, i.e., the inverse of the scale factor can be set. Finally, for 'image_area', a constant size of the resized image can be specified. The corresponding values can be set with the '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', 'scale_factor', 'subsampling_step', 'image_area'
Default value: 'image_area'
With this parameter, the selected 'image_resize_method' can be parameterized. If 'image_resize_method' is set to 'scale_factor', the value of 'image_resize_value' defines the scale factor to be used. If 'image_resize_method' is set to 'subsampling_step', the value of 'image_resize_value' defines the subsampling step, i.e., the inverse of the scale factor. If 'image_resize_method' is set to 'image_area', the value of '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'. It is
0.5 for 'scale_factor',
2.0 for 'subsampling_step', and
0.5 for 'image_area'.
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_identifier, add_sample_identifier_preparation_data, and prepare_sample_identifier. 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_identifier. 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_data and train_sample_identifier 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_data and new samples can be added to the sample identifier with the operator add_sample_identifier_training_data. 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_identifier.
In addition to the operators mentioned above, the following operators can be used to administrate the sample identifier. With remove_sample_identifier_preparation_data and remove_sample_identifier_training_data, 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_info and get_sample_identifier_object_info 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_info. Finally, the operators set_sample_identifier_param and get_sample_identifier_param can be used to set and retrieve control parameters of the sample identifier.
In the following, the most important terms that are used in the context of sample-based identification are described:
An object to be identified by sample-based identification.
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 SampleIdentifier. The object index is the most important result of the operator apply_sample_identifier. With the operator set_sample_identifier_object_info, a descriptive name can be set for each object, which eases the interpretation of the identification results.
One sample or view of an object. Sometimes, also the term “sample image” is used to refer to object samples.
This term is used as a synonym for “object sample”, if the emphasis lies on the image.
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.
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.
An object that has been added to the sample identifier with add_sample_identifier_preparation_data.
An object sample of a preparation object. The preparation is typically done based on multiple preparation samples per object.
The collection of all preparation samples.
The training of the sample identifier. In this step, the sample identifier learns to differentiate all given objects.
An object that has been added to the sample identifier with add_sample_identifier_training_data 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.
An object sample of a training object. The training is typically done based on multiple training samples per object.
The collection of all training samples.
An image, in which an object is visible that should be identified with sample-based identification.
Default value: 
List of values: 'add_color_info', 'add_texture_info', 'image_resize_method', 'image_resize_value'
Default value: 
List of values: 0.25, 0.5, 0.75, 1.0, 2, 3, 4, 'false', 'image_area', 'none', 'scale_factor', 'subsampling_step', 'true'
Handle of the sample identifier.
If the parameters are valid, the operator create_sample_identifier returns the value 2 (H_MSG_TRUE). If necessary an exception is raised.
prepare_sample_identifier, add_sample_identifier_training_data, train_sample_identifier, apply_sample_identifier, get_sample_identifier_param, get_sample_identifier_object_info, remove_sample_identifier_preparation_data, remove_sample_identifier_training_data, write_sample_identifier, serialize_sample_identifier, deserialize_sample_identifier, clear_sample_identifier, clear_all_sample_identifiers, set_sample_identifier_object_info