create_data_code_2d_modelT_create_data_code_2d_modelCreateDataCode2dModelCreateDataCode2dModelcreate_data_code_2d_model (Operator)

Name

create_data_code_2d_modelT_create_data_code_2d_modelCreateDataCode2dModelCreateDataCode2dModelcreate_data_code_2d_model — Create a model of a 2D data code class.

Signature

Description

The operator create_data_code_2d_modelcreate_data_code_2d_modelCreateDataCode2dModelCreateDataCode2dModelCreateDataCode2dModelcreate_data_code_2d_model creates a model for a certain class of 2D data codes. In DataCodeHandleDataCodeHandleDataCodeHandleDataCodeHandledataCodeHandledata_code_handle 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.

For an explanation of the concept of the 2D data code reader see the introduction of chapter Identification / Data Code.

Supported symbol types

The parameter SymbolTypeSymbolTypeSymbolTypeSymbolTypesymbolTypesymbol_type is used to determine the type of data codes to process. Presently, six main types are supported: 'Data Matrix ECC 200'"Data Matrix ECC 200""Data Matrix ECC 200""Data Matrix ECC 200""Data Matrix ECC 200""Data Matrix ECC 200", 'QR Code'"QR Code""QR Code""QR Code""QR Code""QR Code", 'Micro QR Code'"Micro QR Code""Micro QR Code""Micro QR Code""Micro QR Code""Micro QR Code", 'PDF417'"PDF417""PDF417""PDF417""PDF417""PDF417", 'Aztec Code'"Aztec Code""Aztec Code""Aztec Code""Aztec Code""Aztec Code", and 'DotCode'"DotCode""DotCode""DotCode""DotCode""DotCode". Additionally, four GS1 types are supported: 'GS1 DataMatrix'"GS1 DataMatrix""GS1 DataMatrix""GS1 DataMatrix""GS1 DataMatrix""GS1 DataMatrix", 'GS1 QR Code'"GS1 QR Code""GS1 QR Code""GS1 QR Code""GS1 QR Code""GS1 QR Code",'GS1 Aztec'"GS1 Aztec""GS1 Aztec""GS1 Aztec""GS1 Aztec""GS1 Aztec", and 'GS1 DotCode'"GS1 DotCode""GS1 DotCode""GS1 DotCode""GS1 DotCode""GS1 DotCode". 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'). The Aztec code can be read in compact, full-range, and rune (see Annex E of ISO/IEC 24778:2008 (E)) form. The structure of the four GS1 symbologies is basically identical to their non-GS1 counterparts - Data Matrix ECC 200, QR Code Aztec Code, and DotCode, respectively. In the following, all parameters, settings, and rules applying to any particular data code type apply to its GS1 variant as well. The GS1 symbologies enforce merely additional rules for the format of the data carried by the codes. It has to be organized in so called GS1 application element strings according to the GS1 General Specifications.

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 backslashes from the ECI sequence '\nnnnnn'"\nnnnnn""\nnnnnn""\nnnnnn""\nnnnnn""\nnnnnn".

The information whether the symbol contains ECI codes (and consequently doubled backslashes) or not is stored in the Symbology Identifier number that can be obtained for every successfully decoded symbol with the help of the operator get_data_code_2d_resultsget_data_code_2d_resultsGetDataCode2dResultsGetDataCode2dResultsGetDataCode2dResultsget_data_code_2d_results passing the generic parameter 'symbology_ident'"symbology_ident""symbology_ident""symbology_ident""symbology_ident""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 corresponding standards and the operator get_data_code_2d_resultsget_data_code_2d_resultsGetDataCode2dResultsGetDataCode2dResultsGetDataCode2dResultsget_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'"symbology_ident""symbology_ident""symbology_ident""symbology_ident""symbology_ident" number (obtained by the operator get_data_code_2d_resultsget_data_code_2d_resultsGetDataCode2dResultsGetDataCode2dResultsGetDataCode2dResultsget_data_code_2d_results with the parameter 'symbology_ident'"symbology_ident""symbology_ident""symbology_ident""symbology_ident""symbology_ident") can be added to the data stream manually together with the symbology flag and the symbol code: ']d', ']Q', ']L', ']z', or ']J' for DataMatrix codes, QR Codes, PDF417 Codes, Aztec Codes, or DotCodes, respectively. In particular, for GS1 symbologies the parameter 'symbology_ident'"symbology_ident""symbology_ident""symbology_ident""symbology_ident""symbology_ident" returns 2 for GS1 DataMatrix, 3 for GS1 QR Code, and 1 for GS1 Aztec Code and GS1 DotCode. This corresponds to symbol codes: ']d2', ']Q3', ']z1', and ']J1', 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'"default_parameters""default_parameters""default_parameters""default_parameters""default_parameters" together with the value 'standard_recognition'"standard_recognition""standard_recognition""standard_recognition""standard_recognition""standard_recognition" to the operator set_data_code_2d_paramset_data_code_2d_paramSetDataCode2dParamSetDataCode2dParamSetDataCode2dParamset_data_code_2d_param.

For some model parameters the default values depend on the chosen recognition approach. Those parameters are listed in the table below. Further parameter details and the remaining model parameters can be found in the reference of set_data_code_2d_paramset_data_code_2d_paramSetDataCode2dParamSetDataCode2dParamSetDataCode2dParamset_data_code_2d_param.

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'"default_parameters""default_parameters""default_parameters""default_parameters""default_parameters" to the value 'enhanced_recognition'"enhanced_recognition""enhanced_recognition""enhanced_recognition""enhanced_recognition""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_2dfind_data_code_2dFindDataCode2dFindDataCode2dFindDataCode2dfind_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.

By setting the generic parameter 'default_parameters'"default_parameters""default_parameters""default_parameters""default_parameters""default_parameters" to the value 'maximum_recognition'"maximum_recognition""maximum_recognition""maximum_recognition""maximum_recognition""maximum_recognition" the model is further extended in comparison to 'enhanced_recognition'"enhanced_recognition""enhanced_recognition""enhanced_recognition""enhanced_recognition""enhanced_recognition", so that data codes with very small module sizes can be decoded more robustly (see 'small_modules_robustness'"small_modules_robustness""small_modules_robustness""small_modules_robustness""small_modules_robustness""small_modules_robustness"). For the Data Matrix ECC 200, the mode 'maximum_recognition'"maximum_recognition""maximum_recognition""maximum_recognition""maximum_recognition""maximum_recognition" differs from the mode 'enhanced_recognition'"enhanced_recognition""enhanced_recognition""enhanced_recognition""enhanced_recognition""enhanced_recognition" in a way that even symbols with defect or partially occluded finder patterns can be read (see 'finder_pattern_tolerance'"finder_pattern_tolerance""finder_pattern_tolerance""finder_pattern_tolerance""finder_pattern_tolerance""finder_pattern_tolerance"). Using this mode may lead to a further increased run-time and memory usage of the operator find_data_code_2dfind_data_code_2dFindDataCode2dFindDataCode2dFindDataCode2dfind_data_code_2d during symbol search and decoding.

For these reasons, 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_paramset_data_code_2d_paramSetDataCode2dParamSetDataCode2dParamSetDataCode2dParamset_data_code_2d_param. Both operators provide the generic parameters GenParamNameGenParamNameGenParamNameGenParamNamegenParamNamegen_param_name and GenParamValueGenParamValueGenParamValueGenParamValuegenParamValuegen_param_value for this purpose. For the Data Matrix ECC 200, for example, the symbol size should be specified as exactly as possible if the mode 'maximum_recognition'"maximum_recognition""maximum_recognition""maximum_recognition""maximum_recognition""maximum_recognition" was chosen. A detailed description of all supported generic parameters can be found with the operator set_data_code_2d_paramset_data_code_2d_paramSetDataCode2dParamSetDataCode2dParamSetDataCode2dParamset_data_code_2d_param.

Another way for adapting the model is to train it based on sample images. Passing the parameter 'train'"train""train""train""train""train" to the operator find_data_code_2dfind_data_code_2dFindDataCode2dFindDataCode2dFindDataCode2dfind_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_2dfind_data_code_2dFindDataCode2dFindDataCode2dFindDataCode2dfind_data_code_2d.

It is possible to query the model parameters with the operator get_data_code_2d_paramget_data_code_2d_paramGetDataCode2dParamGetDataCode2dParamGetDataCode2dParamget_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_paramsquery_data_code_2d_paramsQueryDataCode2dParamsQueryDataCode2dParamsQueryDataCode2dParamsquery_data_code_2d_params.

Execution Information

• Multithreading type: reentrant (runs in parallel with non-exclusive operators).
• Multithreading scope: global (may be called from any thread).
• Processed without parallelization.

This operator returns a handle. Note that the state of an instance of this handle type may be changed by specific operators even though the handle is used as an input parameter by those operators.

Parameters

Example (HDevelop)

* 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)

Result

The operator create_data_code_2d_modelcreate_data_code_2d_modelCreateDataCode2dModelCreateDataCode2dModelCreateDataCode2dModelcreate_data_code_2d_model returns the value TRUE if the given parameters are correct. Otherwise, an exception is raised.

Possible Successors

set_data_code_2d_paramset_data_code_2d_paramSetDataCode2dParamSetDataCode2dParamSetDataCode2dParamset_data_code_2d_param, find_data_code_2dfind_data_code_2dFindDataCode2dFindDataCode2dFindDataCode2dfind_data_code_2d

Alternatives

read_data_code_2d_modelread_data_code_2d_modelReadDataCode2dModelReadDataCode2dModelReadDataCode2dModelread_data_code_2d_model

See also

clear_data_code_2d_modelclear_data_code_2d_modelClearDataCode2dModelClearDataCode2dModelClearDataCode2dModelclear_data_code_2d_model

References

International Standard ISO/IEC 16022: “Information technology - Automatic identification and data capture techniques - Data Matrix bar code symbology specification”; Reference number ISO/IEC 16022:2006 (E); ISO/IEC 2006.

International Standard ISO/IEC 15438: “Information technology - Automatic identification and data capture techniques - PDF417 bar code symbology specification”; Reference number ISO/IEC 15438:2006 (E); ISO/IEC 2006.

International Standard ISO/IEC 18004: “Information technology - Automatic identification and data capture techniques - QR Code 2005 bar code symbology specification”; Reference number ISO/IEC 18004:2006 (E); ISO/IEC 2006.

International Standard ISO/IEC 24778: “Information technology - Automatic identification and data capture techniques - Aztec Code bar code symbology specification”; Reference number ISO/IEC 24778:2008 (E); ISO/IEC 2008.

GS1 General Specifications; Version 12; Issue 1, Jan-2012; GS1.

Module

Data Code