Create a model of a 2D data code class.

The operator create_data_code_2d_model creates a model for a certain class of 2D data codes. In DataCodeHandle the operator returns a handle to the 2D data code model, which is used for all further operations on the data code, like modifying the model, reading a symbol, or accessing the results of the symbol search.

Supported symbol types

The parameter SymbolType is used to determine the type of data codes to process. Presently, three types are supported: 'Data Matrix ECC 200', 'QR Code', and 'PDF417'. Data matrix codes of type ECC 000-140 are not supported. For the QR Code the older Model 1 as well as the new Model 2 can be read. The PDF417 can be read in its conventional as well as in its compact form ('Compact/Truncated PDF417').

For all symbol types, the data code reader supports the Extended Channel Interpretation (ECI) protocol. If the symbol contains an ECI code, all characters with ASCII code 92 (backslash, '\') that occur in the normal data stream are, in compliance with the standard, doubled ('\\') for the output. This is necessary in order to distinguish data backslashs from the ECI sequence '\nnnnnn'.

The information whether the symbol contains ECI codes (and consequently doubled backslashs) or not is stored in the Symbology Identifier number that can be obtained for every succesfully decoded symbol with the help of the operator get_data_code_2d_results passing the generic parameter 'symbology_ident'. How the code number encodes additional information about the symbology and the data code reader, like the ECI support, is defined in the different symbology specifications. For more information see the appropriate standards and the operator get_data_code_2d_results.

The Symbology Indentifier code will not be preceded by the data code reader to the output data, even if the symbol contains an ECI code. If this is needed, e.g., by a subsequent processing unit, the 'symbology_ident' number (obtained by the operator get_data_code_2d_results with parameter 'symbology_ident') can be added to the data stream manually together with the symbology flag and the symbol code: ']d', ']Q', or ']L' for DataMatrix codes, QR codes, or PDF417 codes, respectively.

Standard default settings of the data code model

The default settings of the model were chosen to read a wide range of common symbols within a reasonable amount of time. However, for run-time reasons some restrictions apply to the symbol (see the following table). If the model was modified (as described later), it is at any time possible to reset it to these default settings by passing the generic parameter 'default_parameters' together with the value 'standard_recognition' to the operator set_data_code_2d_param.

Model parameter               'standard_recognition'       'enhanced_recognition'
------------------------------------------------------------------------------------
Polarity:                     dark symbols on a light      in addition, light symbols on
                              background                   a dark background
Minimum contrast:             30                           10
Module size:
  - ECC 200, QR Code:         6 .. 20 pixels               >= 4 pixels
                                                           (for sharp images >= 2)
  - PDF417:
      Width:                  3 .. 15 pixels               >= 3 Pixel
                                                           (for sharp images >= 2)
      Aspect ratio:           1 .. 4                       1.0 .. 10
Module shape:                 no or small gap between      bigger gaps are also possible 
                              adjacent modules             (up to 50% of the module size)
                              (< 10% of the module size)   (only for ECC 200, QR Code)
ECC200: Maximum slant:        10 degrees (0.1745)          30 degrees (0.5235)
ECC200: Module grid:          fixed                        any (fixed or variable)
For QR Code: Number of
position detection patterns,
that are necessary for
generating a new candidate   3                            2

Modify the data code model

If it is known that the symbol does not or may not comply with all of these restrictions (e.g., the symbol is brighter than the background or the contrast is very low), or if first tests show that some of the symbols cannot be read with the default settings, it is possible to adapt single model parameters - while others are kept to the default - or the whole model can be extended in a single step by setting the generic parameter 'default_parameters' to the value 'enhanced_recognition'. This will lead to a more general model that covers a wider range of 2D data code symbols. However, the symbol search with such a general model is more extensive, hence the run-time of the operator find_data_code_2d may increase significantly. This is true especially in the following cases: no readable data code is detected, the symbol is printed light on dark, or the modules are very small.

For this reason, the model should always be specified as exactly as possible by setting all known parameters. The model parameters can be set directly during the creation of the model or later with the help of the operator set_data_code_2d_param. Both operators provide the generic parameters GenParamNames and GenParamValues for this purpose. A detailed description of all supported generic parameters can be found with the operator set_data_code_2d_param.

Another way for adapting the model is to train it based on sample images. Passing the parameter 'train' to the operator find_data_code_2d will cause the find operator to look for a symbol, determine its parameters, and modify the model accordingly. More details can be found with the description of the operator find_data_code_2d.

It is possible to query the model parameters with the operator get_data_code_2d_param. The names of all supported parameters for setting or querying the model are returned by the operator query_data_code_2d_params.

Store the data code model

Furthermore, the operator write_data_code_2d_model allows to write the model into a file that can be used later to create (e.g., in a different application) an identical copy of the model. Such a model copy is created directly by read_data_code_2d_model (without calling create_data_code_2d_model).

Free the data code model

Since memory is allocated during create_data_code_2d_model and the following operations, the model should be freed explicitly by the operator clear_data_code_2d_model if it is no longer used.

* Two simple examples that show the use of create_data_code_2d_model
* to detect a Data matrix ECC 200 code and a QR Code.

* (1) Create a model for reading simple QR Codes
*     (only dark symbols on a light background will be read)
create_data_code_2d_model ('QR Code', [], [], DataCodeHandle)
* Read an image
read_image (Image, 'datacode/qrcode/qr_workpiece_01')
* Read the symbol in the image
find_data_code_2d (Image, SymbolXLDs, DataCodeHandle, [], [],
                   ResultHandles, DecodedDataStrings)
* Clear the model
clear_data_code_2d_model (DataCodeHandle)

* (2) Create a model for reading a wide range of Data matrix ECC 200 codes
*     (this model will also read light symbols on dark background)
create_data_code_2d_model ('Data Matrix ECC 200', 'default_parameters',
                           'enhanced_recognition', DataCodeHandle)
* 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)
* Clear the model
clear_data_code_2d_model (DataCodeHandle)

The operator create_data_code_2d_model returns the value 2 (H_MSG_TRUE) if the given parameters are correct. Otherwise, an exception will be raised.

create_data_code_2d_model is processed completely exclusively without parallelization.

set_data_code_2d_param, find_data_code_2d

read_data_code_2d_model

clear_data_code_2d_model, clear_all_data_code_2d_models

Data Code