| Table of Contents / Identification / Bar Code | Operators |
get_bar_code_result — Get the alphanumerical results that were accumulated during the decoding of bar code symbols.
get_bar_code_result( : : BarCodeHandle, CandidateHandle, ResultName : BarCodeResults)
The operator get_bar_code_result allows to access alphanumeric results of the find and decode process. To access a result, first the handle of the bar code model (BarCodeHandle) and the index of the resulting symbol or candidate (CandidateHandle) must be passed. CandidateHandle refers to the results in the same order that is returned by the operator find_bar_code. CandidateHandle can take at least numbers from 0 to (n-1), where n is the total number of successfully decoded symbols, for all queries and can take numbers from 0 to (m-1), where m is the total number of candidates, if stated in the description of ResultName below. Alternatively, CandidateHandle can be set to 'all' if all results are desired. The option 'all' can be chosen only in cases where the return value of a single result is single valued.
The result returned in BarCodeResults can be selected by setting ResultName to:
returns the decoded result as a string in a human readable format. This decoded string can be returned for a single result, i.e., CandidateHandle is for example 0, or for all results simultaneously, i.e., CandidateHandle is set to 'all'. Note, that only data characters are comprised in the decoded string. Start/stop characters are excluded, but can be refered to via 'decoded_reference'. For codes with a facultative check character it depends on the settings whether the check character is returned or not. When 'check_char' is set to the default value 'absent' the decoded string takes the check character as a normal data character. When 'check_char' is set to 'present' and if the check character is correct it will be ignored in the string. If the check character is wrong the resulting string is an empty string.
returns the bar code type of the decoded result as a string. This is especially important in the context of autodiscrimination (see find_bar_code). CandidateHandle specifies the results for which the type should be returned: The code type can be returned for a single result, i.e., CandidateHandle is for example 0 when requesting the type of the first result, or CandidateHandle is set to 'all' when requesting the type of all results simultaneously.
returns the underlying decoded reference data. It comprises all original characters of the symbol, i.e., data characters, potential start or stop characters and check characters if present. For codes taking only numeric data, like, e.g., the EAN/UPC codes, the RSS-14 and RSS Limited codes, or the 2/5 codes, the decoded reference data takes the same values as the decoded string data including check characters. For codes with alphanumeric data, like for example Code 39 or Code 128 the decoded reference data are the indices of the respective decoding table. For RSS Expanded and RSS Expanded Stacked the reference values are the ASCII codes of the decoded data, where the special character FNC1 appears with value 10. Furthermore, for all codes from the RSS family the first reference value represents a linkage flag with value of 1 if the flag is set and 0 otherwise. As the decoded reference is a tuple of whole numbers it can only be called for a single result, meaning that CandidateHandle has to be the handle number of the corresponding decoded symbol.
return the decoded string or the reference data of a RSS Composite component, respectively. For further details see the description of the parameter 'composite_code' of set_bar_code_param.
returns the orientation for the specified result. The 'orientation' of a bar code is defined as the angle between its reading direction and the horizontal image axis. 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. Note that the reading direction is perpendicular to the bars of the bar code. A single angle is returned when only one result is specified, e.g., by entering 0 for CandidateHandle. Otherwise, when CandidateHandle is set to 'all', a tuple containing the angles of all results is returned.
checks whether find_bar_code was interrupted by a timeout. If a timeout occurred, 1 is returned, otherwise the result is 0.
returns a tuple with the assessment of print quality in compliance with the international standard ISO/IEC 15416. Note that the print quality of a bar code can be evaluated only if the bar code was decoded by find_bar_code in 'persistence' mode (see set_bar_code_param for further details). The first element always contains the overall print quality of the symbol; the length of the tuple and the interpretation of the remaining elements depend on whether a simple 1D bar code is evaluated (such as EAN-13, Code 128, RSS-14 etc.) or a composite bar code (such as RSS-14 CC-A, RSS Limited CC-B). 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 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, different bar code readers (of different vendors) can potentially produce slightly different results in the print quality assessment.
For simple 1D bar codes the print quality is described in a tuple with nine elements:
Overall
Decode
Symbol Contrast
Minimal Reflectance
Minimal Edge contrast
Modulation
Defects
Decodability
Additional Requirements
While overall quality is the final symbol grade to be reported, the rest of the grades give information for possible causes for poor quality of a symbol. A detailed list of frequently appearing defects and their effect on the individual grades can be found with the ISO/IEC 15416 standard. Note that the names and the order of the grades can be queried with the convenience option 'quality_isoiec15416_labels'.
The definition of the respective elements is as follows: The overall quality is the minimum of all individual grades. The decode grade is set to 4 when the reflectance profile of the symbol could be decoded according to the reference decode algorithm for the symbology and 0, otherwise. The symbol contrast is the range between the minimal and the maximal value in the reflectance profile, and a strong contrast results in a good grading. The minimal reflectance grade is set to 4 if the lowest reflectance value in the scan reflectance profile is lower or equal to 0.5 of the maximal reflectance value. Otherwise a value of 0 is assigned. Edge contrast is the contrast between any two adjacent elements, both bar-to-space or space-to-bar. The minimal edge contrast grades the minimum of the edge contrast values measured in the reflectance profile. The modulation indicates how strong the amplitudes of the bar code elements are. Big amplitudes make the assignment of the elements to bars or spaces more certain, resulting in a high modulation grade. Defects is a grading of reflectance irregularities found within elements and quiet zones. The decodability grade reflects deviations of the element widths from the nominal widths defined for the corresponding symbology. The additional requirements are bar code symbology specific requirements: mostly regarding the required quiet zones, but sometimes it can be also related to wide/narrow ratio, inter character gaps, guarding patterns or further symbology specific characteristics.
For composite bar codes the print quality is described in a tuple with 24 elements, which we organize for better clarity in three groups and one sub group:
OVERALL: COMPOSITE:
0. Overall 11. Decode
1. Overall Linear 12. Rap Overall
2. Overall Composite COMPOSITE RAP:
13. Contrast
LINEAR: 14. Minimal Reflectance
3. Decode 15. Minimal Edge Contrast
4. Symbol Contrast 16. Modulation
5. Minimal Reflectance 17. Defects
6. Minimal Edge contrast 18. Decodability
7. Modulation 19. Codeword Yield
8. Defects 20. Unused Error Correction
9. Decodability 21. Modulation
10. Additional Requirements 22. Decodability
23. Defects
Note that the names and the order of the grades can be queried with the convenience option 'quality_isoiec15416_labels'.
The overall grade in the group OVERALL is the final symbol grade to be reported. It is just the smaller of the other two in the group: overall linear and overall composite, which are the overall grades of the linear and the composite sub symbols, respectively. The other two groups, LINEAR and COMPOSITE, contain the corresponding individual grades for both sub symbols, and give information for possible causes for poor quality of the symbol. The grades in the LINEAR group correspond to those for the simple 1D bar code case, described above. The interpretation of the grades in the COMPOSITE group is directly equivalent to the one for a PDF 417 data code 2D symbol (see get_data_code_2d_results). Yet, instead of start/stop pattern, the Composite symbols have so-called Raw Address Patterns (RAP). The sub-group COMPOSITE RAP expands the individual grades for the reflectance profile of the RAP patterns and 'rap overall' is the overall grade of this sub-group. The RAP grades are consistent with the grades for the simple 1D bar code case explained above.
- 'quality_isoiec15416_values': returns a tuple with the raw values for all 'directly measurable' grades (returned by 'quality_isoiec15416'). These are the grades, whose definition in the ISO/IEC 15416 standard is a 'direct derivative' of the reflectance (i.e., the gray values) properties of the symbol or grades that are the result of a 'direct counting'.
For simple 1D bar codes the grades are:
Symbol Contrast
Modulation
Minimal Reflectance
Defects
Minimal Edge contrast
Decodability
For composite bar codes the grades are:
Symbol Contrast
Rap Contrast
Minimal Reflectance
Minimal Edge contrast
Modulation
Defects
Decodability
Rap Minimal Reflectance
Rap Minimal Edge Contrast
Rap Modulation
Rap Defects
Rap Decodability
Codeword Yield
Unused Error Correction
The returned tuple has the same order of elements as the corresponding result by 'quality_isoiec15416'. For the grades, which are excluded from these lists the operator reports 'N/A'. In the case of simple 1D bar codes Decode, Overall, Additional Requirements do not have any interpretation in the reflectance profile and the respectively returned value is 'N/A'. For composite bar codes this is the case with all Overall and Decode grades. Note that although the grades Composite Modulation, Composite Decodability, Composite Defects are grading the gray value reflectance profile of a composite symbol, 'quality_isoiec15416_values' reports 'N/A' for them as well. Since they are computed in a complicated scheme involving the symbology decoding routine and the error correction mechanism, they do not have a direct raw measurement interpretation.
All values are normalized between 0.0 and 1.0. Hence, for example, a Symbol Contrast value of 0.75 will correspond to a gray value of 191.25 (for BYTE images).
- 'quality_isoiec15416_labels': returns convenience grade labels of the elements of the tuple returned when calling get_bar_code_result with 'quality_isoiec15416'. Note, that in order to be able to discriminate the composite from the linear grading case, the operator needs a handle of a valid result to be passed in CandidateHandle.
- 'status': determines and returns additional information about scanlines of a given candidate region in a human-readable format. Here, CandidateHandle can take numbers from 0 to (m-1), where m is the total number of candidates. Note that the status of the scanlines of a bar code can be evaluated only if the operator find_bar_code or decode_bar_code_rectangle2 was called before while in 'persistence' mode (see set_bar_code_param for further details). No changes in any parameters of the bar code reader must occur between the last call of find_bar_code and this status query. Determining the status is computationally expensive and should be queried only if additional debugging information is needed.
Each candidate region contains a certain number of scanlines which depends on the type of bar code and could be changed with set_bar_code_param with the parameter 'num_scanlines'. Normally, the bar code scanner exits as soon as it has found enough scanlines that could be decoded - the default is one successfully decoded scanline, but this can be changed with set_bar_code_param with the parameter 'min_identical_scanlines'. When using 'status' in get_bar_code_result, the given candidate region is scanned again but this time all scanlines of the specified candidate region are being evaluated. Then the operator returns status information for every scanline of the candidate region in the same order as the scanlines themselves are returned by get_bar_code_object with the parameter 'scanlines_all'.
The following list shows the possible status messages grouped into stages in which the message can appear. The numbers in parentheses are the corresponding status codes returned by 'status_id' (see below).
The status of this scanline is unknown. The scanline will be ignored.
The scanline could be decoded successfully.
The number of edges in this scanline is too low for this bar code type.
The number of edges in this scanline is too low to find at least the start pattern, the stop pattern and a data character.
The number of edges in this scanline is too high for this bar code type
The symbology specific stop character could not be found.
The symbology specific start and stop characters could not be found.
Internal error.
Internal error.
For bar code types '2/5 Industrial' and '2/5 Interleaved', the number of wide bars in a single character must be two.
The encoding pattern does not correspond to a character in the symbology specific look-up table.
For bar code types 'EAN-13' and 'UPC-A', the left half of the symbol contains an invalid mix of the number sets A and B.
For example, this could happen if not enough characters ( depending on whether a check character is expected) could be found.
For bar code types 'EAN-13', 'EAN-8', and 'UPC-A' (including add-on variants) the obligatory center guard pattern could not be found.
For bar code types 'EAN-13', 'EAN-8', and 'UPC-A' (including add-on variants) either the obligatory left or right normal guard patterns could not be found. For bar code types 'UPC-E' (including add-on variants) either the left normal or right special guard patterns could not be found.
For bar code types 'EAN-13', 'EAN-8', 'UPC-A', and 'UPC-E' containing add-on symbols, the obligatory add-on guard pattern could not be found.
For bar code types of the RSS family, not enough finder patterns could be found.
For stacked bar code types no segment could be found.
The check character test failed. For bar codes with a facultative check character, it is possible to disable the check character testing with 'check_char' in set_bar_code_param.
For bar code types 'EAN-13', 'EAN-8', 'UPC-A', and 'UPC-E' containing add-on symbols, the mix of the number sets A and B does not match the implicit check digit.
For the bar code type 'UPC-A' and its add-on variants, the left half of the symbol must consist of six symbol characters of number set A, but a 'EAN-13' compatible mix of number sets A and B has been found instead. Try decoding the bar code as 'EAN-13'.
The bar code could be decoded but its symbol region intersects with the symbol region of another successfully decoded symbol.
Warning messages:
The following messages are warnings only, not errors. They can appear in combination with a status message and are then added to the status message string. These messages are returned if the bar code reader detects possible quality issues in the input image. The messages 1000 to 1003 can appear only for successfully decoded scanlines and only for the following bar code types: 'Codabar', '2/5 Industrial', '2/5 Interleaved', 'Code 39', 'Code 93', 'Code 128', 'MSI', all 'EAN'-, 'UPC-A'- and 'UPC-E'-variants. Note that in cases where scanlines were already decoded incorrectly but not recognized as invalid by the bar code reader, these warnings will be wrong and must be ignored.
The measured width of the white spaces is bigger than internally expected. This is not a decoding error, but a warning that increasing white spaces could lead to undecodable symbols.
The measured width of the white spaces is smaller than internally expected. This is not a decoding error, but a warning that decreasing white spaces could lead to undecodable symbols.
The measured width of the bars is bigger than internally expected. This is not a decoding error, but a warning that increasing the width of the bars could lead to undecodable symbols.
The measured width of the bars is smaller than internally expected. This is not a decoding error, but a warning that decreasing the width of the bars could lead to undecodable symbols.
Internal algorithms show that the white pixels in the symbol region could be saturated. This warning is not bar code type specific. This warning is returned for each scanline. For example, the combination of the status messages 1001/1004 or 1003/1004 is a hint, that the input images might be overexposured.
The linkage flag in the linear bar code component indicates that there should be a composite component, but the composite component could not be found. The decoder returned the linear component only. This warning is returned for each scanline.
returns additional information about scanlines in a numeric format that can be easily parsed. The description of this functionality and the message numbers are described with the parameter 'status' above. The numbers of the warnings can be returned together with other status numbers. The single status message and warning numbers for each scanline are returned as a string, separated by a semicolon, e.g. '1;1000;10004'.
A bar code model 'BarCodeHandle' cannot be shared between two or more user's threads. Different bar code models can be used independently and safely in different threads.
Handle of the bar code model.
Indicating the bar code results respectively candidates for which the data is required.
Default value: 'all'
Suggested values: 0, 1, 2, 'all'
Names of the resulting data to return.
Default value: 'decoded_strings'
Suggested values: 'decoded_strings', 'decoded_types', 'decoded_reference', 'orientation', 'composite_strings', 'composite_reference', 'timeout_occurred', 'quality_isoiec15416', 'quality_isoiec15416_labels', 'quality_isoiec15416_values', 'status', 'status_id'
List with the results.
The operator get_bar_code_result 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.
Bar Code
| Table of Contents / Identification / Bar Code | Operators |
| HALCON Reference Manual 10.0.2 | Copyright © 1996-2011 MVTec Software GmbH |