| Table of Contents / Identification / Data Code | Operators |
find_data_code_2d — Detect and read 2D data code symbols in an image or train the 2D data code model.
find_data_code_2d(Image : SymbolXLDs : DataCodeHandle, GenParamNames, GenParamValues : ResultHandles, DecodedDataStrings)
The operator find_data_code_2d detects 2D data code symbols in the input image (Image) and reads the data that is coded in the symbol. Before calling find_data_code_2d, a model of a class of 2D data codes that matches the symbols in the images must be created with create_data_code_2d_model or read_data_code_2d_model. The handle returned by these operators is passed to find_data_code_2d in DataCodeHandle. To look for more than one symbol in an image, the generic parameter 'stop_after_result_num' can be passed to GenParamNames together with the number of requested symbols as GenParamValues.
As a result the operator returns for every successfully decoded symbol the surrounding XLD contour (SymbolXLDs), a result handle, which refers to a candidate structure that stores additional information about the symbol as well as the search and decoding process (ResultHandles), and the string that is encoded in the symbol (DecodedDataStrings). If the string is longer than 1024 characters it is shortened to 1020 characters followed by '...'. In this case, accessing the complete string is only possible with the operator get_data_code_2d_results. Passing the candidate handle from ResultHandles together with the generic parameter 'decoded_data' get_data_code_2d_results returns a tuple with the ASCII code of all characters of the string.
Adjusting the model
If there is a symbol in the image that cannot be read, it should be verified, whether the properties of the symbol fit the model parameters. Special attention should be paid to the correct polarity ('polarity', light-on-dark or dark-on-light), the symbol size ('symbol_size' for ECC 200, 'version' for QR Code, 'symbol_rows' and 'symbol_cols' for PDF417), the module size ('module_size' for ECC 200 and QR Code, 'module_width' and 'module_aspect' for PDF417), the possibility of a mirroring of the symbol ('mirrored'), and the specified minimum contrast ('contrast_min'). Further relevant parameters are the gap between neighboring foreground modules and, for ECC 200, the maximum slant of the L-shaped finder pattern ('slant_max'). The current settings for these parameters are returned by the operator get_data_code_2d_param. If necessary, the appropriate model parameters can be adjusted with set_data_code_2d_param.
It is recommended to adjust the model as well as possible to the symbols in the images also for run-time reasons. In general, the run-time of find_data_code_2d is higher for a more general model than for a more specific model. One should take into account that a general model leads to a high run-time especially if no valid data code can be found.
Train the model
Besides setting the model parameters manually with set_data_code_2d_param, the model can also be trained with find_data_code_2d based on one or several sample images. For this the generic parameter 'train' must be passed in GenParamNames. The corresponding value passed in GenParamValues determines the model parameters that should be learned. The following values are possible:
All data code types:
All model parameters that can be trained,
Symbol size and for ECC 200 also the symbol shape (rectangle or square); for QR Code it is also possible to pass 'version'.
Size of the modules; for PDF417 this includes the module width and the module aspect ratio.
Robustness of the decoding of data codes with very small module sizes.
Polarity of the symbols: they may appear dark on a light background or light on a dark background.
Whether the symbols in the image are mirrored or not.
Minimum contrast for detecting the symbols.
ECC 200 and QR Code only:
Shape of the modules, especially whether there is a gap between neighboring foreground modules or whether they are connected.
ECC 200 only:
The allowed tolerance of the symbol search with respect to a disturbed or missing finder pattern.
Algorithm for calculating the module positions (fixed or variable grid).
Adjusting different internal image processing parameters; until now, only the maximum slant of the L-shaped finder pattern of the ECC 200 symbols is set; more parameters may follow in future.
QR Code only:
Whether the QR Code symbols follow the Model 1 or Model 2 specification.
It is possible to train several of these parameters in one call of find_data_code_2d by passing the generic parameter 'train' in a tuple more than once in conjunction with the appropriate parameters: e.g., GenParamNames = ['train','train'] and GenParamValues = ['polarity','module_size']. Furthermore, in conjunction with 'train' = 'all' it is possible to exclude single parameters from training explicitly again by passing 'train' more than once. The names of the parameters to exclude, however, must be prefixed by '~': GenParamNames = ['train','train'] and GenParamValues = ['all','~contrast'], e.g., trains all parameters except the minimum contrast.
For training the model, the following aspects should be considered:
To use several images for the training, the operator find_data_code_2d must be called with the parameter 'train' once for every sample image.
It is also possible to train the model with several symbols in one image. Here, the generic parameter 'stop_after_result_num' must be passed as a tuple to GenParamNames together with 'train'. The number of symbols in the image is passed in GenParamValues together with the training parameters.
If the training image contains more symbols than the one that shall be used for the training the domain of the image should be reduced to the symbol of interest with reduce_domain.
In an application with very similar images, one image for training may be sufficient if the following assumptions are true: The symbol size (in modules) is the same for all symbols used in the application, foreground and background modules are of the same size and there is no gap between neighboring foreground modules, the background has no distinct texture; and the contrast of all images is almost the same. Otherwise, several images should be used for training.
In applications where the symbol size (in modules) is not fixed, the smallest as well as the biggest symbols should be used for the training. If this can not be guaranteed, the limits for the symbol size should be adapted manually after the training, or the symbol size should entirely be excluded from the training.
During the first call of find_data_code_2d in the training mode, the trained model parameters are restricted to the properties of the detected symbol. Any successive training call will, where necessary, extend the parameter range to cover the already trained symbols as well as the new symbols. Resetting the model with set_data_code_2d_param to one of its default settings ('default_parameters' = 'standard_recognition', 'enhanced_recognition', or 'maximum_recognition') will also reset the training state of the model.
If find_data_code_2d is not able to read the symbol in the training image, this will produce no error or exception handling. This can simply be tested in the program by checking the results of find_data_code_2d: SymbolXLDs, ResultHandles, DecodedDataStrings. These tuples will be empty, and the model will not be modified.
Functionality of the symbol search
Depending on the current settings of the 2D data code model (see set_data_code_2d_param), the operator find_data_code_2d performs several passes for searching the data code symbols. The search starts at the highest pyramid level, where - according to the maximum module size defined in the data code model - the modules can be separated. In addition, in every pyramid level the preprocessing can vary depending on the presets for the module gap. If the data code model enables dark symbols on a light background as well as light symbols on a dark background, within the current pyramid level the dark symbols are searched first. Then the passes for searching light symbols follow. A pass consists of two phases: The search phase is used to look for the finder patterns and to generate a symbol candidate for every detected finder pattern, and the evaluation phase, where in a lower pyramid level all candidates are investigated and - if possible - read.
The operator call is either terminated due to a timeout (see set_data_code_2d_param) or after that pass in which the requested number of 2D data code symbols was successfully decoded. The required number of symbols can be specified with the generic parameter GenParamNames = 'stop_after_result_num'. The appropriate value is passed in GenParamValues; the default is 1.
While searching for more than one symbol in the image, it may happen that not all symbols are detected in the same pass. In this case find_data_code_2d automatically continues the search until all symbols are found or until the last pass was performed. Otherwise, if the input image contains several symbols but not all have to be read, it is possible (especially if the symbols look similar) that more than the requested number of symbols are returned as a result.
Query results of the symbol search
With the result handles and the operators get_data_code_2d_results and get_data_code_2d_objects, additional data can be requested about the search process, e.g., the number of internal search passes or the number of investigated candidates, and - together with the ResultHandles - about the symbols, like the symbol and module size, the contrast, or the raw data coded in the symbol. In addition, these operators provide information about all investigated candidates that could not be read. In particular, this helps to determine if a candidate was actually generated at the symbol's position during the preprocessing and - by the value of a status variable - why the search or reading was aborted. Further information about the parameters can be found with the operators get_data_code_2d_results and get_data_code_2d_objects.
Input image.
XLD contours that surround the successfully decoded data code symbols.
Handle of the 2D data code model.
Names of (optional) parameters for controlling the behavior of the operator.
Default value: []
List of values: 'train', 'stop_after_result_num'
Values of the optional generic parameters.
Default value: []
Suggested values: 'all', 'model_type', 'symbol_size', 'version', 'module_size', 'small_modules_robustness', 'module_shape', 'polarity', 'mirrored', 'contrast', 'module_grid', 'finder_pattern_tolerance', 'image_proc', 1, 2, 3
Handles of all successfully decoded 2D data code symbols.
Decoded data strings of all detected 2D data code symbols in the image.
* Examples showing the use of find_data_code_2d.
* First, the operator is used to train the model, afterwards it is used to
* read the symbol in another image.
* Create a model for reading Data matrix ECC 200 codes
create_data_code_2d_model ('QR Code', [], [], DataCodeHandle)
* Read a training image
read_image (Image, 'datacode/ecc200/ecc200_cpu_008')
* Train the model with the symbol in the image
find_data_code_2d (Image, SymbolXLDs, DataCodeHandle, 'train', 'all', \
ResultHandles, DecodedDataStrings)
*
* End of training / begin of normal application
*
* Read an image
read_image (Image, 'datacode/ecc200/ecc200_cpu_010')
* Read the symbol in the image
find_data_code_2d (Image, SymbolXLDs, DataCodeHandle, [], [], \
ResultHandles, DecodedDataStrings)
* Display all symbols, the strings encoded in them, and the module size
dev_set_color ('green')
for i := 0 to |ResultHandles| - 1 by 1
select_obj (SymbolXLDs, SymbolXLD, i+1)
dev_display (SymbolXLD)
get_contour_xld (SymbolXLD, Row, Col)
set_tposition (WindowHandle, max(Row), min(Col))
write_string (WindowHandle, DecodedDataStrings[i])
get_data_code_2d_results (DataCodeHandle, ResultHandles[i], \
['module_height','module_width'], ModuleSize)
new_line (WindowHandle)
write_string (WindowHandle, 'module size = ' + ModuleSize[0] + 'x' + \
ModuleSize[1])
endfor
* Clear the model
clear_data_code_2d_model (DataCodeHandle)
The operator find_data_code_2d returns the value 2 (H_MSG_TRUE) if the given parameters are correct. Otherwise, an exception will be raised.
create_data_code_2d_model, read_data_code_2d_model, set_data_code_2d_param
get_data_code_2d_results, get_data_code_2d_objects, write_data_code_2d_model
create_data_code_2d_model, set_data_code_2d_param, get_data_code_2d_results, get_data_code_2d_objects
Data Code
| Table of Contents / Identification / Data Code | Operators |
| HALCON Reference Manual 10.0.2 | Copyright © 1996-2011 MVTec Software GmbH |