| Operators |
get_data_code_2d_results — Get the alphanumerical results that were accumulated during the search for 2D data code symbols.
get_data_code_2d_results( : : DataCodeHandle, CandidateHandle, ResultNames : ResultValues)
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.
For an explanation of the concept of the 2D data code reader see the introduction of chapter Identification / Data Code.
If 'discard_undecoded_candidates' was set to 'yes' with set_data_code_2d_param, only results of successfully decoded candidates can be accessed.
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.
Note that the symbol structure of GS1 DataMatrix, GS1 QR Code, and GS1 Aztec is identical to the structure of ECC 200, QR Code, or Aztec Code, respectively. Therefore, all type specific results for ECC 200, QR Code, and Aztec Code can be queried for their corresponding GS1 variant as well. In the following, the explicit enumeration of the type specific results for any particular GS1 code is omitted for sake of readability. Instead, the relevant result names are to be inferred from the result names for the corresponding non-GS1 code type and or be explicitly queried by query_data_code_2d_params with parameter 'get_result_params'.
Candidate groups
The following candidate group names are predefined and can be passed as CandidateHandle instead of a single handle:
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 (including the successfully decoded symbols) that were investigated during the last call of find_data_code_2d.
All symbols that were successfully decoded during the last call of find_data_code_2d.
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 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 - 'general':
All data code types:
Lowest pyramid level that is searched for symbols. A pyramid level of 0 corresponds to the original image.
Highest pyramid level that is searched for symbols. A pyramid level of 0 corresponds to the original image.
Number of passes that were completed, see also find_data_code_2d (Functionality of the symbol search).
Number of successfully decoded symbols.
Number of all investigated candidates.
Number of candidates that were identified as symbols but could not be read.
Number of candidates that could not be identified as valid 2D data code symbols.
Labels of grades for all tuple elements returned when calling get_data_code_2d_results with 'quality_isoiec15415'. The labels are different depending on the type of the evaluated data code symbol.
returns whether find_data_code_2d was aborted. This might be caused by a timeout (see 'timeout' in set_data_code_2d_param) or an explicit abort (see 'abort' in set_data_code_2d_param).
| Value | Description |
|---|---|
| 0 | find_data_code_2d completed |
| 1 | find_data_code_2d was aborted by a timeout |
| 2 | find_data_code_2d was aborted using set_data_code_2d_param with 'abort' |
Data Matrix ECC 200, Aztec, QR Code and Micro QR Code:
Labels of grades for all tuple elements returned when calling get_data_code_2d_results with 'quality_isoiec_tr_29158' or 'quality_aimdpm_1_2006'.
Data Matrix ECC 200:
Convenience value labels of the elements of the tuple returned when calling get_data_code_2d_results with 'quality_semi_t10_values'.
Results associated with a specific candidate - one value results:
Results that contain exactly one value and hence can be applied to a candidate group or a specific candidate. Please consider that some of the following results will only be meaningful if the candidate could be successfully decoded (see 'status').
All data code types:
Handle to the candidate. This parameter is used to receive the handles of all candidates of the specified group.
Number of the pass in which the candidate was generated and processed, see also find_data_code_2d (Functionality of the symbol search).
Indicates whether the decoding was successful or why the processing was aborted.
Pyramid level on which the finder pattern was found.
Pyramid level on which the candidate was processed and decoded.
Polarity of the symbol. This is the assumption about the polarity that was used for searching the candidate.
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.
Indicates the orientation of a successfully decoded symbol. The orientation is an angle relative to the orientation described in the figure below. The angle is positive in counter clockwise direction and is given in degrees. It can be in the range of [-180.0 .. 180.0] degrees.
| (1) | (2) | (3) | (4) |
ECC 200, QR Code, Micro QR Code, and Aztec 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).
Height and width of the modules in pixels.
Robustness of the decoding of data codes with very small module sizes. For 'low' the data code was decoded with a method that has only a small robustness regarding very small module sizes. For 'high' the data code was decoded with a method that has a high robustness in this regard.
Estimation of the symbol's contrast. This value is based on the gradient of the edge between the finder pattern and the background.
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.
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. For PDF417 this number includes erasures, i.e. errors with known locations. If the error correction failed, a negative error code is returned.
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 backslashes ('\', 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 () according to the specification of Data matrix, QR Codes, Aztec Code, and PDF417 but not the identifier prefixes ']d', ']Q', ']z', and ']L' for Data matrix, QR Codes, Aztec 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 (for Aztec Codes, the values 10, 11, and 12 have to be converted to A, B, and C respectively).
GS1 symbologies have the following indentifiers: ']d2' for GS1 DataMatrix, ']Q3' for GS1 QR Code, and ']z1' for GS1 Aztec Code. Therefore, the 'symbology_ident' parameter returns the values 2, 3, and 1, respectively.
Symbols that contain ECI codes (and hence doubled backslashes) can be recognized by the following identifier values: ECC 200: 4, 5, and 6, QR Code: 2, 4, and 6, PDF417: 1, Aztec Code: 3, 4, 5, 9, 10, and 11.
Data matrix ECC 200, Aztec, QR Code, and Micro QR Code:
Assumption about the module gap that was used for searching the candidate.
Data Matrix ECC 200:
Slant of the L-shaped finder pattern in radians. This is the difference between the angle of the 'L' and the right angle.
This parameter informs about the algorithm that found the symbol. For 'low' the symbol was found with the algorithm that has only a small tolerance with respect to a defect or partially occluded finder pattern. For 'high' the symbol was found with the algorithm that has a high tolerance in this regard. Please note that when using both algorithms simultaneously it may happen that symbols with an undisturbed finder pattern are found from the algorithm of high tolerance.
This parameter informs about the algorithm that was used to correct local contrast variations in the symbol search. For 'high' the symbol was found using an algorithm to correct strong local contrast variations. For 'low' the symbol was found with the faster algorithm, which however is less robust with respect to local contrast variations.
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.
If the symbol contains a Reader Programming character that indicates that the symbol encodes a message used to program the reader system, this parameter returns 'yes', otherwise this parameter returns 'no'. The decoded message does not contain the Reader Programming character.
QR Codes:
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).
Detected size of the symbol in modules.
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.
If a candidate is recognized as a QR Code, the first step is to read the format information encoded in the symbol. This includes the level of error correction ('error_correction_level' ['L' (Low), 'M' (Medium), 'Q' (Quartile), 'H' (High)]).
Additionally, the format information encoded in the symbol include a code for the pattern that was used for masking the data modules (0 'mask_pattern_ref' 7).
Micro QR Codes:
Version number that corresponds to the size of the symbol (version M1 = 11 x 11, version M2 = 13 x 13, version M3 = 15 x 15, version M4 = 17 x 17 ).
Detected size of the symbol in modules.
If a candidate is recognized as a Micro QR Code, the first step is to read the format information encoded in the symbol. This includes the level of error correction ('error_correction_level' ['N' (None), 'L' (Low), 'M' (Medium), 'Q' (Quartile)]).
Additionally, the format information encoded in the symbol include a code for the pattern that was used for masking the data modules (0 'mask_pattern_ref' 7).
PDF417:
Module aspect ratio; this corresponds to the ratio of 'module_height' to 'module_width'.
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' [0, 8]).
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.
Returns the index of the symbol in the group. For macro symbols this information is obligatory.
Returns the group identifier as a string. For macro symbols this information is obligatory.
Returns the number of symbols that belong to the group. For macro symbols this information is optional.
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.
Returns the CRC checksum computed over the entire source file using the CCITT-16 polynomial. For macro symbols this information is optional.
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.
Aztec Codes:
String that corresponds to the format of the decoded symbol: 'compact', 'full_range', or 'rune'.
Detected size of the symbol in modules.
The number of layers as encoded in the mode message of the symbol.
The number of codewords as encoded in the mode message of the symbol.
Results associated with a specific candidate - tuple of values results:
Results that return a tuple of values and hence can be requested only separately and only for a single candidate. Please consider that some of the following results will not return a useful value if the investigation of the candidate was aborted.
All data code types:
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. The model persistence must be 1 for this result (see set_data_code_2d_param).
Data obtained by mapping the binary data to data words according to the particular coding scheme of the symbol type. Single bits may still be erroneous, and the words that are used for the error correction are still included.
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.
Tuple with the decoded data words (= characters of the decoded data string) as ASCII code (see also Tuple / String Operations) or - for QR Code and Micro QR Code - as JIS8 and Shift JIS characters or - for QR Code as GB2312 characters.
Tuple with the assessment of print quality in compliance with the international standard ISO/IEC 15415. The first element always contains the overall print quality of the symbol; the length of the tuple and the denotation of the remaining elements depend on the specific data code type. According to the standard, the grades are whole numbers from 0 to 4, where 0 is the lowest and 4 the highest grade. It is important to note what, even though the implementation is strictly based on the standard, the computation of the print quality grades depends on the preceding decoding algorithm. Thus, different data code readers (of different vendors) can potentially produce slightly different results in the print quality assessment.
Using these values requires a thorough understanding of the underlying algorithms, and we recommend to read ISO/IEC 15415:2011 along with this documentation.
We recommend to use high quality images without artefacts like defocus, noise, overexposure, or inhomogeneous illumination. Such artefacts influence the result of the print quality grading. Further, to obtain robust grading results, an effective resolution of at least ten pixels per module in width and height is required (see ISO/IEC 15415, Chapter 7.3.3). The quality grades are only computed when the symbol region including the quietzone is fully in the image, elsewise -1 is returned for the quality grades.
For the 2D data codes ECC 200, Aztec Code, QR Code, and Micro QR Code the print quality is described in a tuple with twelve elements:(overall quality, contrast, modulation, fixed pattern damage, decode, axial nonuniformity, grid nonuniformity, unused error correction, reflectance margin, print growth, contrast uniformity, aperture). For QR Code and Micro QR Code also the format information and version information are returned as additional grading parameters.
The definition of the respective elements is as follows: The overall quality is the minimum of all individual grades. The contrast is the range between the minimal and the maximal pixel intensity in the data code domain, and a strong contrast results in a good grading. The modulation indicates how strong the amplitudes of the data code modules are. Big amplitudes make the assignment of the modules to black or white more certain, resulting in a high modulation grade. It is to note that the computation of the modulation grade is influenced by the specific level of error correction capacity, meaning that the modulation degrades less for codes with higher error correction capacity. The contrast uniformity is the minimum modulation value found in any module. This value is no grade, therefore, it can have real values. It does not affect the overall quality. According to ISO/IEC15415, the print growth is no grade and is therefore not used for calculating the overall quality. Instead, it can be used as an additional information to find out, if the graphical features comprising the symbol have not shrunk or grown from their nominal size. This means that the print growth gives some indication to which extent the dark and light modules fill out their module boundaries. The calculation of the print growth does not follow the scheme as specified by ISO/IEC 15415, but instead it considers the specifications as stated by the ISO/IEC standard of the 2D data code to be examined. This means that the computation of the print growth for Aztec Codes is implemented as described in ISO/IEC 24778:2008. For ECC 200 the corresponding standard is ANSI/AIM International Specification Data Matrix and for QR Codes as well as for Micro QR Codes the implementation follows ISO/IEC 18004:2006. For all 2D data codes described above, the print growth is calculated in horizontal and vertical direction. The reported grade is the lower rated of the pair.
The reflectance margin also indicates (like the modulation) how strong the amplitudes of the data code modules are. The difference to modulation is that reflectance margin assessed the correct classification of the modules. The fixed pattern of both ECC 200, Aztec Code, QR Code, and Micro QR Code is of high importance for detecting and decoding the codes. Degradation or damage of the fixed pattern, or the respective quiet zones, is assessed with the fixed pattern damage quality, which is based on the modulation values.
The decode quality is graded 4 when the code could be decoded according to the reference decode algorithm defined in the standard, and 0, otherwise. Note that HALCON's decode algorithm differs from the reference decode algorithm. Thus, in many cases HALCON can decode the symbol although the decode grade according to the standard is 0.
Originally, data codes have squared modules, i.e., the width and height of the modules are the same. Due to a potentially oblique view of the camera onto the data code or a defective fabrication of the data code itself, the width to height ratio can be distorted. This deterioration results in a degraded axial nonuniformity. If apart from an affine distortion the data code is subject to perspective or any other distortions too this degrades the grid nonuniformity quality. As data codes are redundant codes, errors in the modules or codewords can be corrected. The amount of error correcting capacities which is not already used by the present data code symbol is expressed in the unused error correction quality. In a way, this grade reflects the reliability of the decoding process. Note, that even codes with an unused error correction grading of 0, which could possibly mean a false decoding result, can be decoded by the find_data_code_2d operator in a reliable way, because the implemented decoding functionality is more sophisticated and robust compared to the reference decode algorithm proposed by the standard.
For QR Codes and Micro QR Codes the additional grading parameters format information and version information are graded in a similar way to fixed pattern damage. If no version information exists, 'N/A' is returned.
For the 2D stacked code PDF417 the print quality is described in a tuple with eight elements: (overall quality, start/stop pattern, codeword yield, unused error correction, modulation, decodability, defects, aperture).
The definition of the respective elements is as follows: The overall quality is the minimum of all individual grades. As the PDF417 data code is a stacked code, which can be read by line scan devices as well, print quality assessment is mainly based on techniques for linear bar codes: a set of scan reflectance profiles is generated across the symbol followed by the evaluation of the respective print qualities within each scan, which are finally subsumed as overall print qualities. For more details, the user is referred to the standard for linear symbols ISO/IEC 15416. In start/stop pattern, the start and stop patterns are assessed concerning the quality of the reflectance profile and the correctness of the bar and space sequence. The grade codeword yield counts and evaluates the relative number of correct decoded words acquired by the set of scan profiles. For the grade unused error correction, the relative number of false decoded words within the error correction blocks are counted. As for 2D data codes, the modulation grade indicates how strong the amplitudes, i.e., the extremal intensities, of the bars and spaces are. The grade decodability measures the deviation of the nominal length of bars and spaces with respect to their reference length. And finally, the grade defects refers to a measurement of how perfect the reflectance profiles of bars and spaces are.
The aperture is the size of the synthesized aperture in units of the module size of the symbol. This aperture is used to obtain the reference gray scale image during the grading procedure. It is defined in ISO/IEC 15415, Chapter 7.3.3.
To be able to compute the quality values, it is necessary that the parameter 'persistence' (see set_data_code_2d_param) is set to a value greater than or equal to 0.
returns a tuple with the raw values for all 'directly measurable' grades (reported by 'quality_isoiec15415'). These are grades, whose definition in the ISO/IEC 15415 standard is a 'direct derivative' of the reflectance (i.e., the gray values) or of geometrical properties of the symbol, or grades that are the result of a 'direct counting'.
The returned tuple has the same order of elements as the corresponding result with 'quality_isoiec15415'. For the grades, which are excluded from these lists, the operator reports 'N/A'. For the 2D data codes ECC 200, Aztec Code, QR Code, and Micro QR Code the excluded grades are overall quality, modulation, fixed pattern damage, decode and reflectance margin. For the 2D stacked code PDF417 the excluded grades are overall quality, start/stop pattern, modulation, decodability, defects.
Although the grades modulation (for ECC 200, QR Code, and Micro QR Code) and modulation, decodability, defects (for PDF417) generally are grading the reflectance properties of the symbol, the standard procedures for their computation involve the symbology decoding routine and error correction mechanism. Therefore there is no 'direct' raw measurement underlying these grades. The grade start/stop pattern (for PDF417) is excluded because it is a complex grade, which does not correspond to a single raw measurement value.
All values except the print growth are normalized between 0.0 and 1.0. Hence, for example, a contrast value of 0.75 will correspond to a gray value of 191.25 (for BYTE images). For the print growth, values between approximately -0.9 and 0.9 are possible as an output. A negative value corresponds to a print shrinkage whereas a positive value reflects a print growth. The values can be interpreted as the percentage share that a dark module occupies too little (print shrinkage) or too much (print growth) of its nominal module size. A value of -0.50 indicates for example that a dark module is 50% smaller as the nominal module size. If the print growth could not be calculated, the value is set to 'N/A'.
To be able to compute the quality values, it is necessary that the parameter 'persistence' (see set_data_code_2d_param) is set to a value greater than or equal to 0.
Data Matrix ECC 200:
Tuple with intermediate results that are determined during the assessment of print quality for ECC 200 codes in compliance with the international standard ISO/IEC 15415:2011 and ISO/IEC 16022:2006. Using these values requires a thorough understanding of the underlying algorithms, and we strongly recommend to read ISO/IEC 15415:2011 and ISO/IEC 16022:2006 along with this documentation.
A description of the intermediate results is given below. The returned intermediate grades ('quality_isoiec15415_intermediate') and values ('quality_isoiec15415_intermediate_values') are the minimal grades and values for the code under inspection. The names of the available intermediate results can be queried with 'quality_isoiec15415_intermediate_labels'.
'Rmin' and 'Rmax': The minimum and maximum reflectance value in the sample area of the symbol (see Chapter 7.6, ISO/IEC 15415:2011). There are no corresponding grades for these values.
'L1' and 'L2': The grades of the vertical and horizontal portions of the outside L of the fixed pattern as defined in Chapter M.1.2, ISO/IEC 16022:2006. The corresponding number of damaged modules is returned as value.
'QZL1' and 'QZL2': The grades of the vertical and horizontal portions of the quiet zone adjacent to L1 and L2, respectively (see Chapter M.1.2, ISO/IEC 16022:2006). The corresponding number of damaged modules is returned as value.
'Transition Ratio': The grade for the transition ratio test described in Chapter M.1.3 b), ISO/IEC 16022:2006. The transition ratio TR is returned as value. It measures the ratio between the number of transitions on the clock track and the associated solid area.
'Clock track regularity': The grade for the clock track regularity test as described in Chapter M.1.3 e), ISO/IEC 16022:2006. If for any group of five adjacent modules more than two modules are considered as errors, this grade is 0, otherwise its 4. There is no corresponding value.
'Clock track damage': The grade for the clock track damage (see Chapter M.1.3 f), ISO/IEC 16022:2006). The corresponding number of damaged modules is returned as value.
'Solid fix pattern': The grade for the solid fixed pattern (see Chapter M.1.3 g), ISO/IEC 16022:2006). The corresponding number of damaged modules is returned as value.
'Clock track and adjacent solid pattern': The overall grade for the clock track and adjacent solid pattern (see Chapter M.1.3 k), ISO/IEC 16022:2006). There is no corresponding value.
'Average grade': The average grade for the for the fixed pattern. It is based on the grades for the L1, L2, QZL1, QZL2, and the overall grade for the clock track and adjacent solid pattern (see Chapter M.1.4, ISO/IEC 16022:2006). There is no corresponding value.
The grade for fixed pattern damage for the symbol is given by the minimum of the grades for 'L1', 'L2', 'QZL1', 'QZL2', 'Clock track and adjacent solid pattern' and 'Average grade' (see Chapter M1.4, ISO/IEC 16022:2006).
Tuple with the assessment of the print quality in compliance with the international standard SEMI T10-0701.
We recommend to use high quality images without artefacts like defocus, noise, overexposure, or inhomogeneous illumination. Such artefacts influence the result of the print quality grading. Further, to obtain robust grading results, an effective resolution of at least ten pixels per module in width and height is required. The quality grades are only computed when the symbol is fully in the image, elsewise -1 is returned for the quality grades.
The direct mark quality is described in a tuple with 21 elements: [P1 Row, P1 Column, P2 Row, P2 Column, P3 Row, P3 Column, P4 Row, P4 Column, Rows, Columns, Symbol Contrast, Symbol Contrast SNR, Horizontal Mark Growth, Vertical Mark Growth, Data Matrix Cell Width, Data Matrix Cell Height, Horizontal Mark Misplacement, Vertical Mark Misplacement, Cell Defects, Finder Pattern Defects, Unused Error Correction]. Note that the Unused Error Correction is returned for each Reed-Solomon block. Therefore, the actual length of the returned tuple depends on the number of Reed-Solomon blocks.
The definition of the respective elements is as follows: The first eight entries contain the coordinates of the four corners. The first corner is located at the vertical finder pattern. The remaining corners follow contour clockwise (for non mirrored codes). With Rows and Columns the numbers of rows and columns of the code are reported.
The value for Symbol Contrast reports the contrast between light and dark classified symbol pixels with respect to the full gray value range (255 for byte images) in percent. Symbol Contrast SNR is the corresponding signal-to-noise ratio. If the value is infinite, 'N/A' is returned.
The values for Horizontal Mark Growth and Vertical Mark Growth represent the width and height, respectively, of marked modules with respect to the sum of the width and height, respectively, of a marked module and a space module in percent. A value of 50% is optimal. If some parts of the alternating pattern are hidden, 'N/A' is returned.
The values for Data Matrix Cell Width and Data Matrix Cell Height report the average module width and height. They are computed from the four corner points and the number of rows and columns of the code.
The values for Horizontal Mark Misplacement and Vertical Mark Misplacement report the displacement of the alternating pattern marks' centers in horizontal and vertical direction, respectively. These values are given in percent with respect to Data Matrix Cell Width and Data Matrix Cell Height, respectively. If some parts of the alternating pattern are hidden, 'N/A' is returned.
The value for Cell Defects reports the percentage of incorrectly classified symbol pixels.
The value for Finder pattern Defects reports the percentage of finder pattern pixels that would be classified incorrectly.
The value for Unused Error Correction reports the error correction capacities that are not already used by each Reed-Solomon block.
To be able to compute the quality values, it is necessary that the parameter 'persistence' (see set_data_code_2d_param) is set to a value greater than or equal to 0.
Convenience value labels of the elements of the tuple returned when calling get_data_code_2d_results with 'quality_semi_t10_values'. If the ECC 200 code has more than one Reed-Solomon block, the label tuple is extended by the corresponding values.
Tuple with the reflectance margin module grades that are determined during the assessment of print quality according to the ISO/IEC 15415 standard Chapter 7.8.4.3. This includes the finder pattern modules and the 4 quiet zones adjacent to the symbol (2 horizontal and 2 vertical).
If the symbol size is , the tuple size is as the 4 quiet zones are included. The tuple is sorted row by row, where the first row is the upper quiet zone and the last row is the bottom one (or QZL2 as described in ISO/IEC 16022:2006 Annex M.1.2, Figure M.1).
The computed grades for each module will be in the range 0 to 4. For unused data modules the module grade is not computed, in this case the corresponding tuple value will be -1.
Tuple with the image row coordinates of the points within the symbol modules for which the module grades are computed with the parameter 'quality_isoiec15415_reflectance_margin_module_grades'.
The returned tuple has the same number and order of elements as the corresponding result with 'quality_isoiec15415_reflectance_margin_module_grades'.
Tuple with the image column coordinates of the points within the symbol modules for which the module grades are computed with the parameter 'quality_isoiec15415_reflectance_margin_module_grades'.
The returned tuple has the same number and order of elements as the corresponding result with 'quality_isoiec15415_reflectance_margin_module_grades'.
Similar to 'quality_isoiec15415_reflectance_margin_module_grades' but in compliance with the ISO/IEC TR 29158 (AIM DPM-1-2006) print quality standard.
See the entry for 'quality_isoiec_tr_29158_reflectance_margin_module_grades'.
Similar to 'quality_isoiec15415_rows' but related to 'quality_isoiec_tr_29158_reflectance_margin_module_grades' and 'quality_aimdpm_1_2006_reflectance_margin_module_grades'.
Similar to 'quality_isoiec15415_cols' but related to 'quality_isoiec_tr_29158_reflectance_margin_module_grades' and 'quality_aimdpm_1_2006_reflectance_margin_module_grades'.
Data Matrix ECC 200, Aztec, QR Code and Micro QR Code:
Tuple with the assessment of print quality in compliance with ISO/IEC TR 29158. This standard was previously established by the Automatic Identification Manufacturers as AIM DPM-1-2006. ISO/IEC TR 29158 is an extension to ISO/IEC 15415 standard, which defines certain requirements for the gray-scale properties of the data code image and in doing so improves the reproducibility of the grading results among different vendors.
Using these values requires a thorough understanding of the underlying algorithms, and we recommend to read ISO/IEC TR 29158 (AIM DPM-1-2006) and ISO/IEC 15415:2011 along with this documentation.
It is very important to note that an ISO/IEC TR 29158 (AIM DPM-1-2006) standard conforming print quality assessment requires interactive image acquisition! No images of a data code symbol should be regarded if there is no information for the camera-lighting setup used to acquire these images. In most cases this implies that the user should set up and use her/his own camera-lighting configuration. Refer to ISO/IEC TR 29158 (AIM DPM-1-2006) for some prescribed camera-lighting configurations and general configuration principles that are relevant for the standard. Note also that, even though the implementation is strictly based on the standard, the computation of the print quality grades depends on the decoding algorithm used. Thus, the print quality inspection results are relevant only for the 2D data code reader implemented with HALCON.
Calling get_data_code_2d_results with argument 'quality_isoiec_tr_29158' or 'quality_aimdpm_1_2006' assumes that the image being processed fulfills the two criteria explained in detail below. The returned tuple represents the 13 print quality elements: [overall quality, cell contrast, cell modulation, fixed pattern damage, decode, axial nonuniformity, grid nonuniformity, unused error correction, mean light, reflectance margin, print growth, contrast uniformity, aperture]. The first eight as well as the last four grades have the same meaning as the ISO/IEC 15415 grades with two exceptions: contrast and modulation are renamed to cell contrast and cell modulation, respectively, to reflect differences in the methods specified with both standards for estimating those values. The value of mean light is not a grade specified with ISO/IEC TR 29158 (AIM DPM-1-2006) standard. It is an estimation for the quality of the processed image computed as the mean gray-scale value of the centers of the light data code modules. It is a value between 0.0 and 1.0, corresponding to 0% to 100% of the maximum gray-scale value (255 for byte images).
The essence of the standard is a procedure for the adjustment of the camera system response (SR): exposure time, gain and/or another specific setting of the user's camera-lighting setup. The goal is to obtain an image of the inspected data code symbol with optimal gray-scale properties. In the image processing context, which is in the main focus of the standard, this is also the key to reproducibility of the grading results. An image has the required gray-scale properties when its 'mean light' value is between 70% and 86% (0.70 and 0.86, respectively). Trying to achieve this condition for images of physically low-contrast data code symbols results usually in very high SR levels. Therefore, the standard defines additionally a calibration routine, which identifies for comparison purposes the normal (calibrated) system response settings (SRcal) by evaluating images of an object with well-known reflectance properties (such as NIST traceable calibrated conformance test card). Finally, the two image acquisition criteria for an image read: first, the image must have a 'mean light' value between 70% and 86% (0.70 and 0.86, respectively); second, it has to be obtained with system response (SR) settings fulfilling: SR/SRcal16. If no image of the data code symbol can be obtained to fulfill both criteria, the symbol must be graded with 0.
As neither the adjustment of the system response nor the verification of the SR criterion can be carried out from within a HALCON operator, the assessment of the AIM DPM-1-2006 quality grades should be performed in an appropriate program setup. The user is referred to two example programs provided with her/his installation of HALCON (calibration_aimdpm_1_2006.hdev and print_quality_aimdpm_1_2006.hdev in the directory HALCONEXAMPLES/hdevelop/Identification/Data-Code), which demonstrate the calibration and the grade evaluation routines, respectively. Both image criteria, as well as further details regarding the general camera setup and image acquisition are also explained and demonstrated there. Everyone who intends to use the AIM DPM-1-2006 grading standard can use the programs as a starting point and adapt them for her/his own camera-lighting setup.
The aperture is the size of the synthesized aperture in units of the module size of the symbol. This aperture is used to obtain the reference gray scale image during the grading procedure and selected by the procedure described in ISO/IEC TR 29158 (AIM DPM-1-2006), Chapter 7.3.
To be able to compute the quality values, it is necessary that the parameter 'persistence' (see set_data_code_2d_param) is set to a value greater than or equal to 0.
Similar to 'quality_isoiec15415_values', the raw values for all 'directly measurable' grades are reported but in compliance with the ISO/IEC TR 29158 (AIM DPM-1-2006) print quality standard. The list of the reported and the excluded raw measurement values is the same as with 'quality_isoiec15415_values'. The auxiliary ISO(IEC TR 29158 (AIM DPM-1-2006) grade mean light is reported in the same format (between 0.0 and 1.0) both by 'quality_isoiec_tr_29158' and 'quality_isoiec_tr_29158_values' ('quality_aimdpm_1_2006' and 'quality_aimdpm_1_2006_values').
To be able to compute the quality values, it is necessary that the parameter 'persistence' (see set_data_code_2d_param) is set to a value greater than or equal to 0.
Data Matrix ECC 200:
Tuple with intermediate results that are determined during the assessment of print quality of ECC 200 codes in compliance with the international standards ISO/IEC TR 29158 (or AIM DPM-1-2006), ISO/IEC 15415:2011 and ISO/IEC 16022:2006. Using these values requires a thorough understanding of the underlying algorithms, and we strongly recommend to read ISO/IEC TR 29158 (AIM DPM-1-2006), ISO/IEC 15415:2011 and ISO/IEC 16022:2006 along with this documentation.
A description of the intermediate results is given below. The returned intermediate grades ('quality_isoiec_tr_29158_intermediate' or 'quality_aimdpm_1_2006_intermediate') and values ('quality_isoiec_tr_29158_intermediate_values' or 'quality_aimdpm_1_2006_intermediate_values') are the minimal grades and values for the code under inspection. The names of the available intermediate results can be queried with 'quality_isoiec_tr_29158_intermediate_labels' or 'quality_aimdpm_1_2006_intermediate_labels'.
'T2': The threshold created using the histogram of the reference gray-scale image pixel values at each intersection point of the grid using the method defined in Annex A, ISO/IEC TR 29158 (AIM DPM-1-2006).
'MD': The value for MeanDark corresponding to T2, which is determined using the method defined in Annex A, ISO/IEC TR 29158 (AIM DPM-1-2006).
'MLtarget': The value for MeanLight corresponding to T2, which is determined using the method defined in Annex A, ISO/IEC TR 29158 (AIM DPM-1-2006).
'L1' and 'L2': The grades of the vertical and horizontal portions of the outside L of the fixed pattern as defined in Chapter M.1.2, ISO/IEC 16022:2006. The corresponding number of damaged modules is returned as value.
'QZL1' and 'QZL2': The grades of the vertical and horizontal portions of the quiet zone adjacent to L1 and L2, respectively (see Chapter M.1.2, ISO/IEC 16022:2006). The corresponding number of damaged modules is returned as value.
'Transition Ratio': The grade for the transition ratio test described in Chapter M.1.3 b), ISO/IEC 16022:2006. The transition ratio TR is returned as value. It measures the ratio between the number of transitions on the clock track and the associated solid area.
'Clock track regularity': The grade for the clock track regularity test as described in Chapter M.1.3 e), ISO/IEC 16022:2006. If for any group of five adjacent modules more than two modules are considered as errors, this grade is 0, otherwise its 4. There is no corresponding value.
'Clock track damage': The grade for the clock track damage (see Chapter M.1.3 f), ISO/IEC 16022:2006). The corresponding number of damaged modules is returned as value.
'Solid fix pattern': The grade for the solid fixed pattern (see Chapter M.1.3 g), ISO/IEC 16022:2006). The corresponding number of damaged modules is returned as value.
'Clock track and adjacent solid pattern': The overall grade for the clock track and adjacent solid pattern (see Chapter M.1.3 k), ISO/IEC 16022:2006). There is no corresponding value.
'Distributed damage grade': The average grade for the for the fixed pattern. It is based on the grades for the L1, L2, QZL1, QZL2, and the overall grade for the clock track and adjacent solid pattern (see Chapter M.1.4, ISO/IEC 16022:2006, and Chapter 9.4, ISO/IEC TR 29158 (AIM DPM-1-2006)). There is no corresponding value.
The grade for fixed pattern damage for the symbol is given by the minimum of the grades for 'L1', 'L2', 'QZL1', 'QZL2', 'Clock track and adjacent solid pattern' and 'Distributed damage grade' (see Chapter M1.4, ISO/IEC 16022:2006).
Data Matrix ECC 200, QR Code, and Aztec Code:
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. For Aztec Codes the group identifier is a string.
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:
The symbol candidate is too close to the border. Only symbols that are completely within the image can be read.
It is not possible to determine the exact position of the finder pattern in the processing image.
It is not possible to determine the width of one of the two legs of the L-shaped finder pattern.
The widths of the two legs of the L-shaped finder pattern differ too much.
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.
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.
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.
Although the deduced symbol size is a valid ECC 200 size, it is not inside the range predefined by the 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 affect the reading of the symbol data and, in general, lead to the following error:
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.
The decoded data contains a message for programming the data code reader. This feature is not supported.
The data coded in the symbol is not consistent and therefore cannot be read.
The data encoded in the symbol is not conform to the GS1 General Specifications. This indicates an attempt to read a non-GS1 symbol with a data code model created as GS1 reader.
The quiet zone of this candidate is missing or shows severe defects.
The candidate could be decoded, but was discarded as possible false positive, because the finder pattern or quiet zone could not be found. This additional check is performed for symbols of size 10x10, 12x12 and 8x18, as these codes have little error correction and false positives may easily be found in unrelated texture.
Data matrix ECC 200 (if a high finder pattern tolerance is chosen, the following messages may occur additionally):
No regular module grid structure could be found within the candidate region. Therefore, the candidate is assumed to be no ECC 200 symbol.
The current candidate overlaps with a previously found result. Therefore, the search for a valid border was aborted.
No consistent border that leads to a symbol size that is within the range of valid symbol sizes leads to a successful decoding.
The candidate could be decoded. However, because the symbol size was small and the code had too many decoding errors, the result is very likely to be random, and hence was rejected. This heuristic is applied for symbols of size 10 x 10 with at least 1 decoding error and for symbols of size 12 x 12 or 8 x 18 with more than 1 decoding error.
QR Code:
The symbol candidate is too close to the border. Only symbols that are completely within the image can be read.
It is not possible to determine the exact position of the finder pattern in the processing image.
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.
The size determined by the size and the position of the detected finder pattern is too small or (only Model 1) too big.
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.
Although the deduced symbol size is valid, it is not inside the range predefined by the model.
Reading the format information (mask pattern and error correction level) from the appropriate region in the symbol 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.
The data coded in the symbol is not consistent and therefore cannot be read.
The data encoded in the symbol is not conform to the GS1 General Specifications. This indicates an attempt to read a non-GS1 symbol with a data code model created as GS1 reader.
Aztec Code:
The symbol candidate is too close to the border or even partially outside the image.
The mode message of this candidate could not be decoded because there are too many modules that could not be interpreted correctly.
The expansion of the candidate failed. Most likely because of too heavy perspective distortions.
Although the deduced symbol size is valid, it is not inside the range predefined by the model. Adapt the model (set_data_code_2d_param) to include this candidate in the final results.
Although this candidate is valid, it does not fit the mirroring constraint predefined by the model. Adapt the model (set_data_code_2d_param) to include this candidate in the final results.
Although this candidate is valid, it does not fit the format predefined by the model. Adapt the model (set_data_code_2d_param) to include this candidate in the final results.
The error correction failed because there are too many modules that could not 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.
The data encoded in the symbol is not conform to the GS1 General Specifications. This indicates an attempt to read a non-GS1 symbol with a data code model created as GS1 reader.
PDF417:
The symbol candidate is too close to the border. Only symbols that are completely within the image can be read.
Although the deduced symbol size is valid, it is not inside the range predefined by the model.
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.
The decoded data contains a message for programming the data code reader. This feature is not supported.
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).
Handle of the 2D data code model.
Handle of the 2D data code candidate or name of a group of candidates for which the data is required.
Default value: 'all_candidates'
Suggested values: 0, 1, 2, 'general', 'all_candidates', 'all_results', 'all_undecoded', 'all_aborted'
Names of the results of the 2D data code to return.
Default value: 'status'
List of values: 'aborted', 'aborted_num', 'bin_module_data', 'candidate_num', 'codeword_num', 'contrast', 'contrast_tolerance', 'corr_coded_data', 'decoded_data', 'decoded_string', 'decoding_error', 'error_correction_level', 'finder_pattern_tolerance', 'format', 'handle', 'layer_num', 'macro_checksum', 'macro_exist', 'macro_file_id', 'macro_last_symbol', 'macro_segment_count', 'macro_segment_index', 'macro_time_stamp', 'mask_pattern_ref', 'max_search_level', 'min_search_level', 'mirrored', 'model_type', 'module_aspect', 'module_gap', 'module_grid', 'module_height', 'module_width', 'orientation', 'pass', 'pass_num', 'polarity', 'process_level', 'quality_aimdpm_1_2006', 'quality_aimdpm_1_2006_cols', 'quality_aimdpm_1_2006_intermediate', 'quality_aimdpm_1_2006_intermediate_labels', 'quality_aimdpm_1_2006_intermediate_values', 'quality_aimdpm_1_2006_labels', 'quality_aimdpm_1_2006_reflectance_margin_module_grades', 'quality_aimdpm_1_2006_rows', 'quality_aimdpm_1_2006_values', 'quality_isoiec15415', 'quality_isoiec15415_cols', 'quality_isoiec15415_intermediate', 'quality_isoiec15415_intermediate_labels', 'quality_isoiec15415_intermediate_values', 'quality_isoiec15415_labels', 'quality_isoiec15415_reflectance_margin_module_grades', 'quality_isoiec15415_rows', 'quality_isoiec15415_values', 'quality_isoiec_tr_29158', 'quality_isoiec_tr_29158_cols', 'quality_isoiec_tr_29158_intermediate', 'quality_isoiec_tr_29158_intermediate_labels', 'quality_isoiec_tr_29158_intermediate_values', 'quality_isoiec_tr_29158_labels', 'quality_isoiec_tr_29158_reflectance_margin_module_grades', 'quality_isoiec_tr_29158_rows', 'quality_isoiec_tr_29158_values', 'quality_semi_t10_labels', 'quality_semi_t10_values', 'raw_coded_data', 'reader_programming', 'result_num', 'search_level', 'slant', 'small_modules_robustness', 'status', 'structured_append', 'symbol_cols', 'symbol_rows', 'symbol_size', 'symbology_ident', 'undecoded_num', 'version'
List with the results.
* 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 is raised.
find_data_code_2d, query_data_code_2d_params
query_data_code_2d_params, get_data_code_2d_objects, get_data_code_2d_param, set_data_code_2d_param
AIM Global Document: AIM DPM-1-2006: “Direct Part Mark (DPM) Quality Guideline”;
Document Type: AIM Bar Code Guideline;
Document Version: 1.0, 2006-12-12.
International Standard ISO/IEC 15415: “Information technology -
Automatic identification and data capture techniques -
Bar code symbol print quality test specification - Two-dimensional symbols”;
Reference number ISO/IEC 15415:2011 (E);
ISO/IEC 2011.
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.
Technical Report ISO/IEC TR 29158: “Information technology -
Automatic identification and data capture techniques -
Direct Part Mark (DPM) Quality Guideline”;
Reference number ISO/IEC TR 29158:2011 (E);
ISO/IEC 2011.
GS1 General Specifications; Version 12; Issue 1, Jan-2012; GS1.
Data Code
| Operators |