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

The operator get_data_code_2d_results allows to access several alphanumerical results that were calculated while searching and reading the 2D data code symbols. These results describe the search process in general or one of the investigated candidates - independently of whether it could be read or not. The results are in most cases not related to the symbol with the highest resolution but depend on the pyramid level that was investigated when the reading process was aborted. To access a result, the name of the parameter (ResultNames) and the 2D data code model (DataCodeHandle) must be passed. In addition, in CandidateHandle a handle of a result or candidate structure or a string identifying a group of candidates must be passed. These handles are returned by find_data_code_2d for all successfully decoded symbols and by get_data_code_2d_results for a group of candidates. If these operators return several handles in a tuple, the individual handles can be accessed by normal tuple operations.

Most results consist of one value. Several of these results can be queried for a specific candidate in a single call. The values returned in ResultValues correspond to the appropriate parameter names in the ResultNames tuple. As an alternative, these results can also be queried for a group of candidates (see below). In this case, only one parameter can be requested per call, and ResultValues contains one value for every candidate.

Furthermore, there exists another group of results that consist of more than one value (e.g., 'bin_module_data'), which are returned as a tuple. These parameters must always be queried exclusively: one result for one specific candidate.

Apart from the candidate-specific results there are a number of results referring to the search process in general. This is indicated by passing the string 'general' in CandidateHandle instead of a candidate handle.

Candidate groups

The following candidate group names are predefined and can be passed as CandidateHandle instead of a single handle:

- 'general': This value is used for results that refer to the last find_data_code_2d call in general but not to a specific candidate.

- 'all_candidates': All candidates (including the successfully decoded symbols) that were investigated during the last call of find_data_code_2d.

- 'all_results': All symbols that were successfully decoded during the last call of find_data_code_2d.

- 'all_undecoded': All candidates of the last call of find_data_code_2d that were detected as 2D data code symbols, but could not be decoded. For these candidates the error correction detected too many errors, or there was an failure while decoding the error-corrected data because of inconsistent data.

- 'all_aborted': All candidates of the last call of find_data_code_2d that could not be identified as valid 2D data code symbols and for which the processing was aborted.

Supported results

Currently, the access to the following results, which are returned in ResultValues, is supported:

General results that do not depend on specific candidates (all data code types) - 'general':

- 'min_search_level': lowest pyramid level that is searched for symbols.

- 'max_search_level': highest pyramid level that is searched for symbols.

- 'pass_num': number of passes that were completed.

- 'result_num': number of successfully decoded symbols.

- 'candidate_num': number of all investigated candidates.

- 'undecoded_num': number of candidates that were identified as symbols but could not be read.

- 'aborted_num': number of candidates that could not be identified as valid 2D data code symbols.

Results associated with a specific candidate:

Please consider that some of the following results will not return a useful value if the investigation of the candidate was aborted.

Results that contain exactly one value and hence can be applied to a tuple of candidates:

All data code types:

- 'handle': handle to the candidate. This parameter is used to receive the handles of all candidates of the specified group.

- 'pass': number of the pass in which the candidate was generated and processed.

- 'status': indicates whether the decoding was successful or why the processing was aborted.

- 'search_level': pyramid level on which the finder pattern was found.

- 'process_level': pyramid level on which the candidate was processed and decoded.

- 'polarity': polarity of the symbol. This is the assumption about the polarity that was used for searching the candidate.

- 'mirrored': indicates whether a successfully decoded symbol is mirrored or not. For candidates that could not be read, the parameter returns the mirroring specification of the model.

- 'symbol_rows', 'symbol_cols': ECC 200 and QR Code: detected size of the symbol in modules: number of rows and columns including the finder pattern; PDF417: detected number of rows and data columns (each 17 modules wide) within the symbol (excluding the start/stop patterns and the row indicators).

- 'symbol_size': detected size of the symbol in modules.

- 'module_height', 'module_width': height and width of the modules in pixels.

- 'contrast': estimation of the symbol's contrast. This value is based on the gradient of the edge between the finder pattern and the background.

- 'decoded_string': result string that is encoded in the symbol - this query is useful only for successfully decoded strings. It returns the same string as find_data_code_2d and is subjected to the same restrictions concerning the maximum length of 1024 characters. If the result string is longer, the parameter 'decoded_data' can be used to get a tuple with all ASCII characters of the decoded string.

- 'decoding_error': decoding error - for successfully decoded symbols this is the number of errors that were detected and corrected by the error correction. The number of errors corresponds here to the number of code words that lead to errors when trying to read them. If the error correction failed, a negative error code is returned.

- 'symbology_ident': The Symbology Identifier is used to indicate that the data code contains the FNC1 and/or ECI characters.

FNC1 (Function 1 Character) is used if the data formating conforms to specific predefined industry standards.

The ECI protocol (Extended Channel Interpretation) is used to change the default interpretation of the encoded data. A 6-digit code number after the ECI character switches the interpretation of the following characters from the default to a specific code page like an international character set. In the output stream the ECI switch is coded as '\nnnnnn'. Therefore all backslashs ('\', ASCII code 92), that occur in the normal output stream have to be doubled.

The 'symbology_ident' parameter returns only the actual identifier value m (0 <= m <= 6) according to the specification of Data matrix, QR Codes, and PDF417 but not the identifier prefixes ']d', ']Q', and ']L' for Data matrix, QR Codes, and PDF417 respectively. If required, this Symbology Identifier composed of the prefix and the value m has to be preceded the decoded string (normally only if m > 1) manually. Symbols that contain ECI codes (and hence doubled backslashs) can be recognised by the following identifier values: ECC 200: 4, 5, and 6, QR Code: 2, 4, and 6, PDF417: 1.

Data matrix ECC200 and QR Code:

- 'module_gap': assumption about the module gap that was used for searching the candidate.

Data Matrix ECC200:

- 'slant': slant of the L-shaped finder pattern in radians. This is the difference between the angle of the 'L' and the right angle.

- 'module_grid': For symbols that could be decoded, this parameter informs about the algorithm that was used for calculating the module grid: If a variable grid was used it returns 'variable', and otherwise 'fixed'. For symbols that could not be decoded, it returns the method that was used during the last decoding trial or, if the candidate was rejected before the decoding, the corresponding model setting.

QR Codes:

- 'version': version number that corresponds to the size of the symbol (version 1 = 21 x 21, version 2 = 25 x 25, ..., version 40 = 177 x 177).

- 'model_type': Type of the QR Code Model. In HALCON the older, original specification for QR Codes Model 1 as well as the newer, enhanced form Model 2 are supported.

- 'mask_pattern_ref', 'error_correction_level': If a candidate is recognized as an QR Code the first step is to read the format information encoded in the symbol. This includes a code for the pattern that was used for masking the data modules (0 <= 'mask_pattern_ref' <= 7) and the level of the error correction ('error_correction_level' element of ['L', 'M', 'Q', 'H']).

PDF417:

- 'module_aspect': module aspect ratio; this corresponds to the ratio of 'module_height' to 'module_width'.

- 'error_correction_level': If a candidate is recognized as a PDF417 the first step is to read the format information encoded in the symbol. This includes the error correction level, which was used during encoding ('error_correction_level' within the interval [0, 8]).

Results that return a tuple of values and hence can be requested only separately and only for a single candidate:

All data code types:

- 'bin_module_data': binary symbol data that is read from the modules row by row - a value of 0 means that the module was classified as background and 100 indicates that the module belongs to the foreground. Values between 0 and 100 can be interpreted as foreground or background.

- 'raw_coded_data': data obtained by mapping the binary data to data words according to the particular coding scheme. Single bits may still be erroneous, and the words that are used for the error correction are still included.

- 'corr_coded_data': data obtained after applying the error correction: erroneous bits are corrected and all redundant words are removed, but the words are still encoded according to the coding scheme that is specific for the data code type

- 'decoded_data': tuple with the decoded data words (= characters of the decoded data string) as ASCII code or - for QR Code - as JIS8 and Shift JIS characters. In contrast to the decoded data string, there is no restriction concerning the maximum length of 1024 characters.

Data Matrix ECC200 and QR Code:

- 'structured_append': if the symbol is part of a group of symbols (``Structured Append''), this parameter contains (1) the index of the symbol in the group, (2) the number of symbols that belong to the group, and (3) a number that serves as a group identifier.

PDF417:

- 'macro_exist': symbols that are part of a group of symbols are called "Macro PDF417" symbols. These symbols contain additional information within a control block. For macro symbols 'macro_exist' returns the value 1 while for conventional symbols 0 is returned.

- 'macro_segment_index': returns the index of the symbol in the group. For macro symbols this information is obligatory.

- 'macro_file_id': returns the group identifier as a string. For macro symbols this information is obligatory.

- 'macro_segment_count': returns the number of symbols that belong to the group. For macro symbols this information is optional.

- 'macro_time_stamp': returns the time stamp on the source file expressed as the elapsed time in seconds since 1970:01:01:00:00:00 GMT as a string. For macro symbols this information is optional.

- 'macro_checksum': returns the CRC checksum computed over the entire source file using the CCITT-16 polynomial. For macro symbols this information is optional.

- 'macro_last_symbol': returns 1 if the symbol is the last one within the group of symbols. Otherwise 0 is returned. For macro symbols this information is optional.

Status message

The status parameter that can be queried for all candidates reveals why and where in the evaluation phase a candidate was discarded. The following list shows the most important status messages in the order of their generation during the evaluation phase:

Data matrix ECC 200:

- 'aborted: too close to image border' - The symbol candidate is too close to the border. Only symbols that are completely within the image can be read.

- 'aborted adjusting: ...' - It is not possible to determine the exact position of the finder pattern in the processing image.

- 'aborted finder pattern: ...' - It is not possible to determine the width of one of the two legs of the L-shaped finder pattern.

- 'aborted leg widths: widths of the finder pattern legs differ too much' - The widths of the two legs of the L-shaped finder pattern differ too much.

- 'aborted alternating side: ...' - For one dimension of the candidate, two opposite borders were found during the symbol search phase. However, it is not possible to determine which is the alternating and which the solid side of the finder pattern.

- 'aborted border search: ...' - For one dimension of the candidate, only the border that belongs to the solid side of the finder patten was found during the symbol search phase. Searching the opposite (the alternating) side failed.

- 'aborted symbol: invalid size' - The number of rows and columns of the symbol that was deduced from the alternating pattern does not yield in a valid ECC 200 code.

- 'aborted symbol: size does not fit strict model definition' - Although the deduced symbol size is a valid ECC 200 size, it is not inside the range predefined by the model.

- 'aborted symbol: rectangular symbol does not fit strict mirror definition of model' - The symbol was identified as a rectangular ECC 200 code. In conjunction with the mirroring parameter of the model, however, the symbol's rows and columns are swapped such that no valid ECC 200 code is achieved. This test is of course not possible for square symbols. There, a wrong mirroring specification will effect the reading of the symbol data and, in general, lead to the following error:

- 'error correction failed' - The error correction failed because there are too many modules that couldn't be interpreted correctly. Normally, this indicates that the print and/or image quality is too bad, but it may also be provoked by a wrong mirroring specification in the model.

- 'decoding failed: special decoding reader requested' - The decoded data contains a message for programming the data code reader. This feature is not supported.

- 'decoding failed: inconsistent data' - The data coded in the symbol is not consistent and therefore cannot be read.

QR Code:

- 'aborted: too close to image border' - The symbol candidate is too close to the border. Only symbols that are completely within the image can be read.

- 'aborted adjusting: finder patterns' - It is not possible to determine the exact position of the finder pattern in the processing image.

- 'aborted symbol: different number of rows and columns' - It is not possible to determine for both dimensions a consistent symbol size by the size and the position of the detected finder pattern. When reading Model 2 symbols, this error may occur only with small symbols (< version 7 or 45 x 45 modules). For bigger symbols the size is coded within the symbol in the version information region. The estimated size is used only as a hint for finding the version information region.

- 'aborted symbol: invalid size' - The size determined by the size and the position of the detected finder pattern is too small or (only Model 1) too big.

- 'decoding of version information failed' - While processing a Model 2 symbol, the symbol version as determined by the finder pattern is at least 7 (>= 45 x 45 modules). However, reading the version from the appropriate region in the symbol failed.

- 'aborted symbol: size does not fit strict model definition' - Although the deduced symbol size is valid, it is not inside the range predefined by the model.

- 'decoding of format information failed' - Reading the format information (mask pattern and error correction level) from the appropriate region in the symbol failed.

- 'error correction failed' - The error correction failed because there are too many modules that couldn't be interpreted correctly. Normally, this indicates that the print and/or image quality is too bad, but it may also be provoked by a wrong mirroring specification in the model.

- 'decoding failed: inconsistent data' - The data coded in the symbol is not consistent and therefore cannot be read.

PDF417:

- 'aborted: too close to image border' - The symbol candidate is too close to the border. Only symbols that are completely within the image can be read.

- 'aborted symbol: size does not fit strict model definition' - Although the deduced symbol size is valid, it is not inside the range predefined by the model.

- 'error correction failed' - The error correction failed because there are too many modules that couldn't be interpreted correctly. Normally, this indicates that the print and/or image quality is too bad, but it may also be provoked by a wrong mirroring specification in the model.

- 'decoding failed: special decoding reader requested' - The decoded data contains a message for programming the data code reader. This feature is not supported.

- 'decoding failed: inconsistent data' - The data coded in the symbol is not consistent and therefore cannot be read.

While processing a candidate, it is possible that internally several iterations for reading the symbol are performed. If all attempts fail, normally the last abortion state is stored in the candidate structure. E.g., if the QR Code model enables symbols with Model 1 and Model 2 specification, find_data_code_2d tries first to interpret the symbol as Model 2 type. If this fails, Model 1 interpretation is performed. If this also fails, the status variable is set to the latest failure state of the Model 1 interpretation. In order to get the error state of the Model 2 branch, the 'model_type' parameter of the data code model must be restricted accordingly (with set_data_code_2d_param).

* Example demonstrating how to access the results of the data code search.

* Create a model for reading Data matrix ECC 200 codes
create_data_code_2d_model ('Data Matrix ECC 200', [], [], 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)

* Get the number of passes
get_data_code_2d_results (DataCodeHandle, 'general', 'pass_num', Passes)

* Get a tuple with the status of all candidates
get_data_code_2d_results (DataCodeHandle, 'all_candidates', 'status',
                          AllStatus)
* Get the handles of all candidates that were detected as a symbol but 
* could not be read
get_data_code_2d_results (DataCodeHandle, 'all_undecoded', 'handle',
                          HandlesUndecoded)

* For every undecoded symbol, get the contour, the symbol size, and
* the binary module data
dev_set_color ('red')
for i := 0 to |HandlesUndecoded| - 1 by 1
    * Get the contour of the symbol
    get_data_code_2d_objects (SymbolXLD, DataCodeHandle, HandlesUndecoded[i],
                              'candidate_xld')
    * Get the symbol size
    get_data_code_2d_results (DataCodeHandle, HandlesUndecoded[i],
                              ['symbol_rows','symbol_cols'], SymbolSize)
    * Get the binary module data (has to be queried exclusively)
    get_data_code_2d_results (DataCodeHandle, HandlesUndecoded[i],
                              'bin_module_data', BinModuleData)
    * Stop for inspecting the data
    stop ()
endfor

* Clear the model
clear_data_code_2d_model (DataCodeHandle)

The operator get_data_code_2d_results returns the value 2 (H_MSG_TRUE) if the given parameters are correct and the requested results are available for the last symbol search. Otherwise, an exception will be raised.

get_data_code_2d_results is reentrant and processed without parallelization.

find_data_code_2d, query_data_code_2d_params

get_data_code_2d_objects

query_data_code_2d_params, get_data_code_2d_objects, get_data_code_2d_param, set_data_code_2d_param

Data Code