ClassesClasses | | Operators

get_data_code_2d_resultsget_data_code_2d_resultsGetDataCode2dResultsGetDataCode2dResults (Operator)

Name

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

Signature

get_data_code_2d_results( : : DataCodeHandle, CandidateHandle, ResultNames : ResultValues)

Herror get_data_code_2d_results(const Hlong DataCodeHandle, const char* CandidateHandle, const char* ResultNames, char* ResultValues)

Herror T_get_data_code_2d_results(const Htuple DataCodeHandle, const Htuple CandidateHandle, const Htuple ResultNames, Htuple* ResultValues)

void GetDataCode2dResults(const HTuple& DataCodeHandle, const HTuple& CandidateHandle, const HTuple& ResultNames, HTuple* ResultValues)

HTuple HDataCode2D::GetDataCode2dResults(const HTuple& CandidateHandle, const HTuple& ResultNames) const

HTuple HDataCode2D::GetDataCode2dResults(const HString& CandidateHandle, const HString& ResultNames) const

HTuple HDataCode2D::GetDataCode2dResults(const char* CandidateHandle, const char* ResultNames) const

static void HOperatorSet.GetDataCode2dResults(HTuple dataCodeHandle, HTuple candidateHandle, HTuple resultNames, out HTuple resultValues)

HTuple HDataCode2D.GetDataCode2dResults(HTuple candidateHandle, HTuple resultNames)

HTuple HDataCode2D.GetDataCode2dResults(string candidateHandle, string resultNames)

Description

The operator get_data_code_2d_resultsget_data_code_2d_resultsGetDataCode2dResultsGetDataCode2dResultsGetDataCode2dResults 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 (ResultNamesResultNamesResultNamesResultNamesresultNames) and the 2D data code model (DataCodeHandleDataCodeHandleDataCodeHandleDataCodeHandledataCodeHandle) must be passed. In addition, in CandidateHandleCandidateHandleCandidateHandleCandidateHandlecandidateHandle 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_2dfind_data_code_2dFindDataCode2dFindDataCode2dFindDataCode2d for all successfully decoded symbols and by get_data_code_2d_resultsget_data_code_2d_resultsGetDataCode2dResultsGetDataCode2dResultsGetDataCode2dResults 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'"discard_undecoded_candidates""discard_undecoded_candidates""discard_undecoded_candidates""discard_undecoded_candidates" was set to 'yes'"yes""yes""yes""yes" with set_data_code_2d_paramset_data_code_2d_paramSetDataCode2dParamSetDataCode2dParamSetDataCode2dParam, 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 ResultValuesResultValuesResultValuesResultValuesresultValues correspond to the appropriate parameter names in the ResultNamesResultNamesResultNamesResultNamesresultNames 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 ResultValuesResultValuesResultValuesResultValuesresultValues 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'"bin_module_data""bin_module_data""bin_module_data""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'"general""general""general""general" in CandidateHandleCandidateHandleCandidateHandleCandidateHandlecandidateHandle 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_paramsquery_data_code_2d_paramsQueryDataCode2dParamsQueryDataCode2dParamsQueryDataCode2dParams with parameter 'get_result_params'"get_result_params""get_result_params""get_result_params""get_result_params".

Candidate groups

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

'general'"general""general""general""general":

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

'all_candidates'"all_candidates""all_candidates""all_candidates""all_candidates":

All candidates (including the successfully decoded symbols) that were investigated during the last call of find_data_code_2dfind_data_code_2dFindDataCode2dFindDataCode2dFindDataCode2d.

'all_results'"all_results""all_results""all_results""all_results":

All symbols that were successfully decoded during the last call of find_data_code_2dfind_data_code_2dFindDataCode2dFindDataCode2dFindDataCode2d.

'all_undecoded'"all_undecoded""all_undecoded""all_undecoded""all_undecoded":

All candidates of the last call of find_data_code_2dfind_data_code_2dFindDataCode2dFindDataCode2dFindDataCode2d 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_aborted""all_aborted""all_aborted""all_aborted":

All candidates of the last call of find_data_code_2dfind_data_code_2dFindDataCode2dFindDataCode2dFindDataCode2d 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 ResultValuesResultValuesResultValuesResultValuesresultValues, is supported:

General results that do not depend on specific candidates - 'general'"general""general""general""general":

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'"status""status""status""status").

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.

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:

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_2dfind_data_code_2dFindDataCode2dFindDataCode2dFindDataCode2d 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'"model_type""model_type""model_type""model_type" parameter of the data code model must be restricted accordingly (with set_data_code_2d_paramset_data_code_2d_paramSetDataCode2dParamSetDataCode2dParamSetDataCode2dParam).

Execution Information

Parameters

DataCodeHandleDataCodeHandleDataCodeHandleDataCodeHandledataCodeHandle (input_control)  datacode_2d HDataCode2D, HTupleHTupleHtuple (integer) (IntPtr) (Hlong) (Hlong)

Handle of the 2D data code model.

CandidateHandleCandidateHandleCandidateHandleCandidateHandlecandidateHandle (input_control)  integer HTupleHTupleHtuple (string / integer) (string / int / long) (HString / Hlong) (char* / Hlong)

Handle of the 2D data code candidate or name of a group of candidates for which the data is required.

Default value: 'all_candidates' "all_candidates" "all_candidates" "all_candidates" "all_candidates"

Suggested values: 0, 1, 2, 'general'"general""general""general""general", 'all_candidates'"all_candidates""all_candidates""all_candidates""all_candidates", 'all_results'"all_results""all_results""all_results""all_results", 'all_undecoded'"all_undecoded""all_undecoded""all_undecoded""all_undecoded", 'all_aborted'"all_aborted""all_aborted""all_aborted""all_aborted"

ResultNamesResultNamesResultNamesResultNamesresultNames (input_control)  attribute.name(-array) HTupleHTupleHtuple (string) (string) (HString) (char*)

Names of the results of the 2D data code to return.

Default value: 'status' "status" "status" "status" "status"

List of values: 'aborted'"aborted""aborted""aborted""aborted", 'aborted_num'"aborted_num""aborted_num""aborted_num""aborted_num", 'bin_module_data'"bin_module_data""bin_module_data""bin_module_data""bin_module_data", 'candidate_num'"candidate_num""candidate_num""candidate_num""candidate_num", 'codeword_num'"codeword_num""codeword_num""codeword_num""codeword_num", 'contrast'"contrast""contrast""contrast""contrast", 'contrast_tolerance'"contrast_tolerance""contrast_tolerance""contrast_tolerance""contrast_tolerance", 'corr_coded_data'"corr_coded_data""corr_coded_data""corr_coded_data""corr_coded_data", 'decoded_data'"decoded_data""decoded_data""decoded_data""decoded_data", 'decoded_string'"decoded_string""decoded_string""decoded_string""decoded_string", 'decoding_error'"decoding_error""decoding_error""decoding_error""decoding_error", 'error_correction_level'"error_correction_level""error_correction_level""error_correction_level""error_correction_level", 'finder_pattern_tolerance'"finder_pattern_tolerance""finder_pattern_tolerance""finder_pattern_tolerance""finder_pattern_tolerance", 'format'"format""format""format""format", 'handle'"handle""handle""handle""handle", 'layer_num'"layer_num""layer_num""layer_num""layer_num", 'macro_checksum'"macro_checksum""macro_checksum""macro_checksum""macro_checksum", 'macro_exist'"macro_exist""macro_exist""macro_exist""macro_exist", 'macro_file_id'"macro_file_id""macro_file_id""macro_file_id""macro_file_id", 'macro_last_symbol'"macro_last_symbol""macro_last_symbol""macro_last_symbol""macro_last_symbol", 'macro_segment_count'"macro_segment_count""macro_segment_count""macro_segment_count""macro_segment_count", 'macro_segment_index'"macro_segment_index""macro_segment_index""macro_segment_index""macro_segment_index", 'macro_time_stamp'"macro_time_stamp""macro_time_stamp""macro_time_stamp""macro_time_stamp", 'mask_pattern_ref'"mask_pattern_ref""mask_pattern_ref""mask_pattern_ref""mask_pattern_ref", 'max_search_level'"max_search_level""max_search_level""max_search_level""max_search_level", 'min_search_level'"min_search_level""min_search_level""min_search_level""min_search_level", 'mirrored'"mirrored""mirrored""mirrored""mirrored", 'model_type'"model_type""model_type""model_type""model_type", 'module_aspect'"module_aspect""module_aspect""module_aspect""module_aspect", 'module_gap'"module_gap""module_gap""module_gap""module_gap", 'module_grid'"module_grid""module_grid""module_grid""module_grid", 'module_height'"module_height""module_height""module_height""module_height", 'module_width'"module_width""module_width""module_width""module_width", 'orientation'"orientation""orientation""orientation""orientation", 'pass'"pass""pass""pass""pass", 'pass_num'"pass_num""pass_num""pass_num""pass_num", 'polarity'"polarity""polarity""polarity""polarity", 'process_level'"process_level""process_level""process_level""process_level", 'quality_aimdpm_1_2006'"quality_aimdpm_1_2006""quality_aimdpm_1_2006""quality_aimdpm_1_2006""quality_aimdpm_1_2006", 'quality_aimdpm_1_2006_cols'"quality_aimdpm_1_2006_cols""quality_aimdpm_1_2006_cols""quality_aimdpm_1_2006_cols""quality_aimdpm_1_2006_cols", 'quality_aimdpm_1_2006_intermediate'"quality_aimdpm_1_2006_intermediate""quality_aimdpm_1_2006_intermediate""quality_aimdpm_1_2006_intermediate""quality_aimdpm_1_2006_intermediate", 'quality_aimdpm_1_2006_intermediate_labels'"quality_aimdpm_1_2006_intermediate_labels""quality_aimdpm_1_2006_intermediate_labels""quality_aimdpm_1_2006_intermediate_labels""quality_aimdpm_1_2006_intermediate_labels", 'quality_aimdpm_1_2006_intermediate_values'"quality_aimdpm_1_2006_intermediate_values""quality_aimdpm_1_2006_intermediate_values""quality_aimdpm_1_2006_intermediate_values""quality_aimdpm_1_2006_intermediate_values", 'quality_aimdpm_1_2006_labels'"quality_aimdpm_1_2006_labels""quality_aimdpm_1_2006_labels""quality_aimdpm_1_2006_labels""quality_aimdpm_1_2006_labels", 'quality_aimdpm_1_2006_reflectance_margin_module_grades'"quality_aimdpm_1_2006_reflectance_margin_module_grades""quality_aimdpm_1_2006_reflectance_margin_module_grades""quality_aimdpm_1_2006_reflectance_margin_module_grades""quality_aimdpm_1_2006_reflectance_margin_module_grades", 'quality_aimdpm_1_2006_rows'"quality_aimdpm_1_2006_rows""quality_aimdpm_1_2006_rows""quality_aimdpm_1_2006_rows""quality_aimdpm_1_2006_rows", 'quality_aimdpm_1_2006_values'"quality_aimdpm_1_2006_values""quality_aimdpm_1_2006_values""quality_aimdpm_1_2006_values""quality_aimdpm_1_2006_values", 'quality_isoiec15415'"quality_isoiec15415""quality_isoiec15415""quality_isoiec15415""quality_isoiec15415", 'quality_isoiec15415_cols'"quality_isoiec15415_cols""quality_isoiec15415_cols""quality_isoiec15415_cols""quality_isoiec15415_cols", 'quality_isoiec15415_intermediate'"quality_isoiec15415_intermediate""quality_isoiec15415_intermediate""quality_isoiec15415_intermediate""quality_isoiec15415_intermediate", 'quality_isoiec15415_intermediate_labels'"quality_isoiec15415_intermediate_labels""quality_isoiec15415_intermediate_labels""quality_isoiec15415_intermediate_labels""quality_isoiec15415_intermediate_labels", 'quality_isoiec15415_intermediate_values'"quality_isoiec15415_intermediate_values""quality_isoiec15415_intermediate_values""quality_isoiec15415_intermediate_values""quality_isoiec15415_intermediate_values", 'quality_isoiec15415_labels'"quality_isoiec15415_labels""quality_isoiec15415_labels""quality_isoiec15415_labels""quality_isoiec15415_labels", 'quality_isoiec15415_reflectance_margin_module_grades'"quality_isoiec15415_reflectance_margin_module_grades""quality_isoiec15415_reflectance_margin_module_grades""quality_isoiec15415_reflectance_margin_module_grades""quality_isoiec15415_reflectance_margin_module_grades", 'quality_isoiec15415_rows'"quality_isoiec15415_rows""quality_isoiec15415_rows""quality_isoiec15415_rows""quality_isoiec15415_rows", 'quality_isoiec15415_values'"quality_isoiec15415_values""quality_isoiec15415_values""quality_isoiec15415_values""quality_isoiec15415_values", 'quality_isoiec_tr_29158'"quality_isoiec_tr_29158""quality_isoiec_tr_29158""quality_isoiec_tr_29158""quality_isoiec_tr_29158", 'quality_isoiec_tr_29158_cols'"quality_isoiec_tr_29158_cols""quality_isoiec_tr_29158_cols""quality_isoiec_tr_29158_cols""quality_isoiec_tr_29158_cols", 'quality_isoiec_tr_29158_intermediate'"quality_isoiec_tr_29158_intermediate""quality_isoiec_tr_29158_intermediate""quality_isoiec_tr_29158_intermediate""quality_isoiec_tr_29158_intermediate", 'quality_isoiec_tr_29158_intermediate_labels'"quality_isoiec_tr_29158_intermediate_labels""quality_isoiec_tr_29158_intermediate_labels""quality_isoiec_tr_29158_intermediate_labels""quality_isoiec_tr_29158_intermediate_labels", 'quality_isoiec_tr_29158_intermediate_values'"quality_isoiec_tr_29158_intermediate_values""quality_isoiec_tr_29158_intermediate_values""quality_isoiec_tr_29158_intermediate_values""quality_isoiec_tr_29158_intermediate_values", 'quality_isoiec_tr_29158_labels'"quality_isoiec_tr_29158_labels""quality_isoiec_tr_29158_labels""quality_isoiec_tr_29158_labels""quality_isoiec_tr_29158_labels", 'quality_isoiec_tr_29158_reflectance_margin_module_grades'"quality_isoiec_tr_29158_reflectance_margin_module_grades""quality_isoiec_tr_29158_reflectance_margin_module_grades""quality_isoiec_tr_29158_reflectance_margin_module_grades""quality_isoiec_tr_29158_reflectance_margin_module_grades", 'quality_isoiec_tr_29158_rows'"quality_isoiec_tr_29158_rows""quality_isoiec_tr_29158_rows""quality_isoiec_tr_29158_rows""quality_isoiec_tr_29158_rows", 'quality_isoiec_tr_29158_values'"quality_isoiec_tr_29158_values""quality_isoiec_tr_29158_values""quality_isoiec_tr_29158_values""quality_isoiec_tr_29158_values", 'quality_semi_t10_labels'"quality_semi_t10_labels""quality_semi_t10_labels""quality_semi_t10_labels""quality_semi_t10_labels", 'quality_semi_t10_values'"quality_semi_t10_values""quality_semi_t10_values""quality_semi_t10_values""quality_semi_t10_values", 'raw_coded_data'"raw_coded_data""raw_coded_data""raw_coded_data""raw_coded_data", 'reader_programming'"reader_programming""reader_programming""reader_programming""reader_programming", 'result_num'"result_num""result_num""result_num""result_num", 'search_level'"search_level""search_level""search_level""search_level", 'slant'"slant""slant""slant""slant", 'small_modules_robustness'"small_modules_robustness""small_modules_robustness""small_modules_robustness""small_modules_robustness", 'status'"status""status""status""status", 'structured_append'"structured_append""structured_append""structured_append""structured_append", 'symbol_cols'"symbol_cols""symbol_cols""symbol_cols""symbol_cols", 'symbol_rows'"symbol_rows""symbol_rows""symbol_rows""symbol_rows", 'symbol_size'"symbol_size""symbol_size""symbol_size""symbol_size", 'symbology_ident'"symbology_ident""symbology_ident""symbology_ident""symbology_ident", 'undecoded_num'"undecoded_num""undecoded_num""undecoded_num""undecoded_num", 'version'"version""version""version""version"

ResultValuesResultValuesResultValuesResultValuesresultValues (output_control)  attribute.value(-array) HTupleHTupleHtuple (string / integer / real) (string / int / long / double) (HString / Hlong / double) (char* / Hlong / double)

List with the results.

Example (HDevelop)

* 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)

Result

The operator get_data_code_2d_resultsget_data_code_2d_resultsGetDataCode2dResultsGetDataCode2dResultsGetDataCode2dResults 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.

Possible Predecessors

find_data_code_2dfind_data_code_2dFindDataCode2dFindDataCode2dFindDataCode2d, query_data_code_2d_paramsquery_data_code_2d_paramsQueryDataCode2dParamsQueryDataCode2dParamsQueryDataCode2dParams

Possible Successors

get_data_code_2d_objectsget_data_code_2d_objectsGetDataCode2dObjectsGetDataCode2dObjectsGetDataCode2dObjects

See also

query_data_code_2d_paramsquery_data_code_2d_paramsQueryDataCode2dParamsQueryDataCode2dParamsQueryDataCode2dParams, get_data_code_2d_objectsget_data_code_2d_objectsGetDataCode2dObjectsGetDataCode2dObjectsGetDataCode2dObjects, get_data_code_2d_paramget_data_code_2d_paramGetDataCode2dParamGetDataCode2dParamGetDataCode2dParam, set_data_code_2d_paramset_data_code_2d_paramSetDataCode2dParamSetDataCode2dParamSetDataCode2dParam

References

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.

Module

Data Code


ClassesClasses | | Operators