Operator Reference

Data Code

This chapter contains operators for reading 2D data codes.

Concept of reading 2D data codes

2D data code symbols are a special kind of two-dimensional patterns that encode text and numbers. HALCON is able to read the most popular 2D data codes: Data Matrix ECC 200, QR Code, Micro QR Code, Aztec Code, PDF417, and DotCode. Except for DotCodes all these codes contain a finder pattern and a data pattern. The finder pattern is used to locate the pattern of the symbol and get basic information about the geometric properties, e.g., the orientation of the symbol. The data pattern contains the code itself and consists of multiple dots, bars, or small squares, the so-called modules. Because of the special design of the codes, they can be decoded even if some parts are disturbed.

Reading a 2D data code of type PDF417. This image is from the example program 2d_data_codes_default_settings.hdev.

In the following, the steps that are required to read 2D data codes are described briefly.

Create 2D data code model:

First, a 2D data code model must be created using

create_data_code_2d_modelcreate_data_code_2d_modelCreateDataCode2dModelCreateDataCode2dModelcreate_data_code_2d_model.

This model provides the reader with all necessary information about the structure of the code. For normal printed codes only the name needs to be provided and HALCON will select suitable default parameters. For special cases, you can modify the model parameters either when creating the 2D data code model or in a later step to adapt the model to a particular symbol appearance.

Modify the model parameters for non-standard codes:

Using the default parameters, the 2D data code reader is able to read a wide range of codes. For non-standard codes the parameters can be modified using

set_data_code_2d_paramset_data_code_2d_paramSetDataCode2dParamSetDataCode2dParamset_data_code_2d_param.

Here, you can either select an enhanced set of default parameters using the generic parameter 'default_parameters'"default_parameters""default_parameters""default_parameters""default_parameters", e.g., with the value 'enhanced_recognition'"enhanced_recognition""enhanced_recognition""enhanced_recognition""enhanced_recognition", or you specify the parameter values separately to adapt the model optimally to the conditions of the used print style. Note that query_data_code_2d_paramsquery_data_code_2d_paramsQueryDataCode2dParamsQueryDataCode2dParamsquery_data_code_2d_params can be used to query the parameters that are valid for the specific data code type. To obtain the currently set values of parameters, get_data_code_2d_paramget_data_code_2d_paramGetDataCode2dParamGetDataCode2dParamget_data_code_2d_param can be used.

Instead of modifying the model parameters manually, you can also let HALCON train the model using

find_data_code_2dfind_data_code_2dFindDataCode2dFindDataCode2dfind_data_code_2d

with the generic parameter 'train'"train""train""train""train". Then, HALCON will search for the best parameters needed to extract the given code. It is recommended to apply this to multiple example images to ensure that all variations are covered.

Read 2D data code:

The 2D data code is located and its content is decoded using

find_data_code_2dfind_data_code_2dFindDataCode2dFindDataCode2dfind_data_code_2d.

The operator returns for every successfully decoded symbol the surrounding XLD contour, a handle to a result structure, which contains additional information about the symbol as well as about the search and decoding process, and the string that is encoded in the symbol. With the result handles and the operators get_data_code_2d_resultsget_data_code_2d_resultsGetDataCode2dResultsGetDataCode2dResultsget_data_code_2d_results and get_data_code_2d_objectsget_data_code_2d_objectsGetDataCode2dObjectsGetDataCode2dObjectsget_data_code_2d_objects, additional data about the extraction process can be accessed that can be used both for process analysis and for displaying. In particular, get_data_code_2d_resultsget_data_code_2d_resultsGetDataCode2dResultsGetDataCode2dResultsget_data_code_2d_results allows to access several alphanumerical results that were calculated while searching and reading the symbols and get_data_code_2d_objectsget_data_code_2d_objectsGetDataCode2dObjectsGetDataCode2dObjectsget_data_code_2d_objects allows to access iconic objects that were created during the last call of find_data_code_2dfind_data_code_2dFindDataCode2dFindDataCode2dfind_data_code_2d.

Further operators

In addition to the operators mentioned above, write_data_code_2d_modelwrite_data_code_2d_modelWriteDataCode2dModelWriteDataCode2dModelwrite_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_modelread_data_code_2d_modelReadDataCode2dModelReadDataCode2dModelread_data_code_2d_model (without calling create_data_code_2d_modelcreate_data_code_2d_modelCreateDataCode2dModelCreateDataCode2dModelcreate_data_code_2d_model). Furthermore, you can use serialize_data_code_2d_modelserialize_data_code_2d_modelSerializeDataCode2dModelSerializeDataCode2dModelserialize_data_code_2d_model and deserialize_data_code_2d_modeldeserialize_data_code_2d_modelDeserializeDataCode2dModelDeserializeDataCode2dModeldeserialize_data_code_2d_model to serialize and deserialize the 2D data code model.

Glossary

2D data code symbol: Two-dimensional graphical symbol that encodes characters and numbers. It is constructed by dark and light dots, bars, or small squares that are called modules. There are different types of 2D data codes. Two common types are the so-called stacked codes and the so-called matrix codes.
stacked code: Type of 2D data code symbol that contains a stack of 1D bar codes arranged in rows and columns. To ensure that the complete stack of 1D bar codes is processed, the symbol contains a start and a stop pattern. Additionally, the symbol is framed by a quiet zone.
matrix code: Type of 2D data code symbol that uses graphical patterns consisting of dark and light modules arranged in two dimensions. The symbol consists of three components: a finder pattern, a data pattern, and a quiet zone.
modules: Dark and light dots, bars, or small squares that are used to build a 2D data code symbol.
quiet zone: Homogeneous frame around the symbol's border that makes the symbol better distinguishable from the background or from other objects in the image.
finder pattern: Pattern that is used to find the symbol and its orientation in the image. The pattern differs depending on the used data code type.

Further Information

See also the “Solution Guide Basics” and the “Solution Guide on 2D Data Codes” for further details about 2D data codes.

List of Operators

clear_data_code_2d_modelClearDataCode2dModelclear_data_code_2d_modelClearDataCode2dModelclear_data_code_2d_model: Delete a 2D data code model and free the allocated memory.

create_data_code_2d_modelCreateDataCode2dModelcreate_data_code_2d_modelCreateDataCode2dModelcreate_data_code_2d_model: Create a model of a 2D data code class.

deserialize_data_code_2d_modelDeserializeDataCode2dModeldeserialize_data_code_2d_modelDeserializeDataCode2dModeldeserialize_data_code_2d_model: Deserialize a serialized 2D data code model.

find_data_code_2dFindDataCode2dfind_data_code_2dFindDataCode2dfind_data_code_2d: Detect and read 2D data code symbols in an image or train the 2D data code model.

get_data_code_2d_objectsGetDataCode2dObjectsget_data_code_2d_objectsGetDataCode2dObjectsget_data_code_2d_objects: Access iconic objects that were created during the search for 2D data code symbols.

get_data_code_2d_paramGetDataCode2dParamget_data_code_2d_paramGetDataCode2dParamget_data_code_2d_param: Get one or several parameters that describe the 2D data code model.

get_data_code_2d_resultsGetDataCode2dResultsget_data_code_2d_resultsGetDataCode2dResultsget_data_code_2d_results: Get the alphanumerical results that were accumulated during the search for 2D data code symbols.

query_data_code_2d_paramsQueryDataCode2dParamsquery_data_code_2d_paramsQueryDataCode2dParamsquery_data_code_2d_params: Get for a given 2D data code model the names of the generic parameters or objects that can be used in the other 2D data code operators.

read_data_code_2d_modelReadDataCode2dModelread_data_code_2d_modelReadDataCode2dModelread_data_code_2d_model: Read a 2D data code model from a file and create a new model.

serialize_data_code_2d_modelSerializeDataCode2dModelserialize_data_code_2d_modelSerializeDataCode2dModelserialize_data_code_2d_model: Serialize a 2D data code model.

set_data_code_2d_paramSetDataCode2dParamset_data_code_2d_paramSetDataCode2dParamset_data_code_2d_param: Set selected parameters of the 2D data code model.

write_data_code_2d_modelWriteDataCode2dModelwrite_data_code_2d_modelWriteDataCode2dModelwrite_data_code_2d_model: Writes a 2D data code model into a file.

Operators