Set selected parameters of the 2D data code model.

The operator set_data_code_2d_param is used to set or change the different parameters of a 2D data code model in order to adapt the model to a particular symbol appearance. All parameters can also be set while creating a 2D data code model with create_data_code_2d_model. The current configuration of the data code model can be queried with get_data_code_2d_param. A list with the names of all parameters that can be set for the given 2D data code type is returned by query_data_code_2d_params.

The following overview lists the different generic parameters with the respective value ranges and default values in standard mode ('standard_recognition') and, if differing, in enhanced mode ('enhanced_recognition'):

Basic default settings:

All data code types:

- 'default_parameters': reset all model parameters to one of the two basic default settings standard or enhanced (see the following summary and create_data_code_2d_model). In addition to the parameter values, the training state of the model is reset. Values: 'standard_recognition', 'enhanced_recognition'

Default: 'standard_recognition'

Attention: If this parameter is set together with a list of other parameters, this parameter must be at the first position.

Size and shape of the symbol:

Data matrix ECC 200 (including the finder pattern):

- 'symbol_cols_min': minimum number of module columns in the symbol.

Value range: [10 .. 144] - even

Default: 10

- 'symbol_cols_max': maximum number of module columns in the symbol.

Value range: [10 .. 144] - even

Default: 144

- 'symbol_rows_min': minimum number of module rows in the symbol.

Value range: [8 .. 144] - even

Default: 8

- 'symbol_rows_max': maximum number of module rows in the symbol.

Value range: [8 .. 144] - even

Default: 144

- 'symbol_shape': possible restrictions on the module shape (rectangle and/or square). Attention: setting the symbol shape all previously made restrictions concerning the symbol size are lost. Since HALCON 7.1.1 the same search algorithm is used for both shapes. Thus, the parameter has no relevance for the symbol search anymore.

Values: 'rectangle', 'square', 'any'

Default: 'any'

- 'symbol_cols': set 'symbol_cols_min' and 'symbol_cols_max' to the same value.

- 'symbol_rows': set 'symbol_rows_min' and 'symbol_rows_max' to the same value.

- 'symbol_size_min': set 'symbol_cols_min' and 'symbol_rows_min' to the same value.

- 'symbol_size_max': set 'symbol_cols_max' and 'symbol_rows_max' to the same value.

- 'symbol_size': set 'symbol_cols_min', 'symbol_cols_max', 'symbol_rows_min' and 'symbol_rows_max' to the same value and 'symbol_shape' to 'square'.

QR-Code (including the finder pattern):

- 'model_type': type of the QR Code model. The old QR Code Model 1 and the newer Model 2 are supported.

Values: 1, 2, 'any'

Default: 'any'

- 'version_min': minimum symbol version. The symbol version is directly linked to the symbol size. Symbols of version 1 are 21x21 moduls in size, version 2 = 25x25 moduls, etc. up to version 40 = 177x177 moduls. The maximum size of Model 1 symbols is 73x73 = version 14.

Value range: [1 .. 40] (Model 1: [1 .. 14])

Default: 1

- 'version_max': maximum symbol version.

Value range: [1 .. 40] (Model 1: [1 .. 14])

Default: 40

- 'version': set 'version_min' and 'version_max' to the same value.

- 'symbol_size_min': minimum size of the symbol in modules. This parameter can be used as an alternative to 'version_min'.

Value range: [21 .. 177] (Model 1: [21 .. 73])

Default: 21

- 'symbol_size_max': maximum size of the symbol in modules. This parameter can be used as an alternative to 'version_max':

Value range: [21 .. 177] (Model 1: [21 .. 73])

Default: 177

- 'symbol_size': set 'symbol_size_min' and 'symbol_size_max' to the same value.

PDF417:

- 'symbol_cols_min': minimum number of data columns in the symbol in codewords, i.e., excluding the codewords of the start/stop pattern and of the two row indicators.

Value range: [1 .. 30]

Default: 1

- 'symbol_cols_max': maximum number of data columns in the symbol in codewords, i.e., excluding the two codewords of the start/stop pattern and of the two indicators.

Value range: [1 .. 30]

Default: 20 (enhanced: 30)

- 'symbol_rows_min': minimum number of module rows in the symbol.

Value range: [3 .. 90]

Default: 5 (enhanced: 3)

- 'symbol_rows_max': maximum number of module rows in the symbol.

Value range: [3 .. 90]

Default: 45 (enhanced: 90)

- 'symbol_cols': set 'symbol_cols_min' and 'symbol_cols_max' to the same value.

- 'symbol_rows': set 'symbol_rows_min' and 'symbol_rows_max' to the same value.

Appearance of the modules in the image:

All data code types:

- 'polarity': describes the polarity of the symbol in the image, i.e., the parameter determines if the symbol appears light on a dark background or dark on a light background.

Values: 'dark_on_light', 'light_on_dark, 'any'.

Default: 'dark_on_light' (enhanced: 'any')

- 'mirrored': describes whether the symbol is or may be mirrored (which is equivalent to swapping rows and columns of the symbol).

Values: 'no', 'yes', 'any'

Default: 'any'

- 'contrast_min': minimum contrast between the foreground and the background of the symbol (this measure corresponds with the minimum gradient between the symbol's foreground and the background).

Values: [1 .. 100]

Default: 30 (enhanced: 10)

Datamatrix ECC 200 und QR-Code:

- 'module_size_min': minimum size of the modules in the image in pixels.

Values: [2 .. 100]

Default: 6 (enhanced: 2)

- 'module_size_max': maximum size of the modules in the image in pixels.

Values: [2 .. 100]

Default: 20 (enhanced: 100)

- 'module_size': set 'module_size_min' and 'module_size_max' to the same value.

It is possible to specify whether neighboring foreground modules are connected or whether there is or may be a gap between them. If the foreground modules are connected and fill the module space completely the gap parameter can be set to 'no'. The parameter is set to 'small' if there is a very small gap between two modules; it can be set to 'big' if the gap is slightly bigger. The last two settings may also be useful if the foreground modules - although being connected - appear thinner as their entitled space (e.g., as a result of blooming caused by a bright illuminant). If the foreground modules appear only as very small dots (in relation to the module size: < 50%), in general, an appropriate preprocessing of the image for detecting or enlarging the modules will be necessary (e.g., by gray_erosion_shape or gray_dilation_shape):

- 'module_gap_col_min': minimum gap in direction of the symbol columns.

Values: 'no', 'small', 'big'

Default: 'no'

- 'module_gap_col_max': maximum gap in direction of the symbol columns.

Values: 'no', 'small', 'big'

Default: 'small' (enhanced: 'big')

- 'module_gap_row_min': minimum gap in direction of the symbol rows.

Values: 'no', 'small', 'big'

Default: 'no'

- 'module_gap_row_max': maximum gap in direction of the symbol rows.

Values: 'no', 'small', 'big'

Default: 'small' (enhanced: 'big')

- 'module_gap_col': set 'module_gap_col_min' and 'module_gap_col_max' to the same value.

- 'module_gap_row': set 'module_gap_row_min' and 'module_gap_row_max' to the same value.

- 'module_gap_min': set 'module_gap_col_min' and 'module_gap_row_min' to the same value.

- 'module_gap_max': set 'module_gap_col_max' and 'module_gap_row_max' to the same value.

- 'module_gap': set 'module_gap_col_min', 'module_gap_col_max', 'module_gap_row_min', and 'module_gap_row_max' to the same value.

PDF417:

- 'module_width_min': minimum module width in the image in pixels.

Values: [2 .. 100]

Default: 3 (enhanced: 2)

- 'module_width_max': maximum module width in the image in pixels.

Values: [2 .. 100]

Default: 15 (enhanced: 100)

- 'module_width': set 'module_width_min' and 'module_width_max' to the same value.

- 'module_aspect_min': minimum module aspect ratio (module height to module width).

Values: [0.5 .. 20.0]

Default: 1.0

- 'module_aspect_max': maximum module aspect ratio (module height to module width).

Values: [0.5 .. 20.0]

Default: 4.0 (enhanced: 10.0)

- 'module_aspect': set 'module_aspect_min' and 'module_aspect_max' to the same value.

Data matrix ECC 200:

- 'slant_max': maximum deviation of the angle of the L-shaped finder pattern from the (ideal) right angle (the angle is specified in radians and corresponds to the distortion that occurs when the symbol is printed or during the image acquisition).

Value range: [0.0 .. 0.5235]

Default: 0.1745 = 10 degrees (enhanced: 0.5235 = 30 degrees)

- 'module_grid': describes whether the size of the modules may vary (in a specific range) or not. Dependent on this parameter different algorithms are used for calculating the module's center positions. If it is set to 'fixed', an equidistant grid is used. Allowing a variable module size ('variable'), the grid is aligned only to the alternating side of the finder pattern. With 'any' both approaches are tested one after the other.

Values: 'fixed', 'variable', 'any'

Default: 'fixed' (enhanced: 'any')

QR Code:

- 'position_pattern_min': Number of position detection patterns that have to be visible for generating a new symbol candidate.

Value range: [2, 3]

Default: 3 (enhanced: 2)

General model behavior:

All data code types:

- 'persistence': controls whether certain intermediate results of the symbol search with find_data_code_2d are stored temporarily or persistently in the model. The memory requirements of find_data_code_2d are significantly smaller if the data is stored temporarily (default). On the other hand, by using the persistent storage it is possible to access some of the data for debugging reasons after searching for symbols, e.g., to investigate why a symbol could not be read.

Values: 0 (temporary), 1 (persistent)

Default: 0

- 'strict_model': controls the behavior of find_data_code_2d while detecting symbols that could be read but that do not fit the model restrictions on the size of the symbols. They can be rejected (strict model, set to 'yes') or returned as a result independent of their size and the size specified in the model (lax model, set to 'no').

Values: 'yes' (strict), 'no' (not strict)

Default: 'yes'

When setting the model parameters, attention should be payed especially to the following issues:

Symbols whose size does not comply with the size restrictions made in the model (with the generic parameters 'symbol_rows*', 'symbol_cols*', 'symbol_size*', or 'version*') will not be read if 'strict_model' is set to 'yes', which is the default. This behavior is useful if symbols of a specific size have to be detected while other symbols should be ignored. On the other hand, neglecting this parameter can lead to problems, e.g., if one symbol of an image sequence is used to adjust the model (including the symbol size), but later in the application the symbol size varies, which is quite common in practice.

The run-time of find_data_code_2d depends mostly on the following model parameters, namely in cases where the requested number of symbols cannot be found in the image: 'polarity', 'module_size_min' (ECC 200 and QR Code) and 'module_size_min' together with 'module_aspect_min' (PDF417), and if the minimum module size is very small also the parameters 'module_gap_*' (ECC 200 and QR Code), for QR Code also 'position_pattern_min'.

* This examples shows how a model can be adapted to a specific symbol if
* the symbol parameters are known

* Create a model for reading Data matrix ECC 200 codes
create_data_code_2d_model ('Data Matrix ECC 200', [], [], DataCodeHandle)
* Restrict the model by setting the module size
set_data_code_2d_param (DataCodeHandle,
                        ['module_size_min','module_size_max'], [4,7])
* Change the polarity setting of the model from 'dark_on_light' to 
* 'light_on_dark' and, at the same time, specify a new minimum contrast
set_data_code_2d_param (DataCodeHandle, ['polarity','contrast_min'],
                        ['light_on_dark',10])

* 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 set_data_code_2d_param returns the value 2 (H_MSG_TRUE) if the given parameters are correct. Otherwise, an exception will be raised.

set_data_code_2d_param is reentrant and processed without parallelization.

create_data_code_2d_model, read_data_code_2d_model

get_data_code_2d_param, find_data_code_2d, write_data_code_2d_model

read_data_code_2d_model

query_data_code_2d_params, get_data_code_2d_param, get_data_code_2d_results, get_data_code_2d_objects

Data Code