Operator Reference
get_data_code_2d_objects (Operator)
get_data_code_2d_objects — Access iconic objects that were created during the search for
2D data code symbols.
Signature
get_data_code_2d_objects( : DataCodeObjects : DataCodeHandle, CandidateHandle, ObjectName : )
Description
The operator get_data_code_2d_objects facilitates to access
iconic objects that were created during the last call of
find_data_code_2d while searching and reading the 2D data
code symbols.
Besides the name of the object (ObjectName), the 2D data
code model (DataCodeHandle) must be passed to
get_data_code_2d_objects.
In addition, in CandidateHandle a handle of a result
or candidate structure or a string identifying a group of candidates
(see get_data_code_2d_results) 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.
Some objects are not accessible without setting the model parameter
'persistence' to 1 (see
set_data_code_2d_param).
The persistence must be set before calling
find_data_code_2d, either while creating the model with
create_data_code_2d_model or with
set_data_code_2d_param.
Currently, the following iconic objects can be retrieved:
Regions of the modules
-
All data code types:
- 'module_1_rois':
-
All modules that were classified as foreground (set).
-
All data code types except DotCode:
- 'module_0_rois':
-
All modules that were classified as background (not set).
These region arrays correspond to the areas that were used for the
classification.
The returned object is a region array.
Hence it cannot be requested for a group of candidates.
Therefore, a single result handle must be passed in
CandidateHandle.
The model persistence must be 1 for this object.
In addition, requesting the module ROIs makes sense only for symbols
that were detected as valid symbols.
For other candidates, whose processing was aborted earlier, the
module ROIs are not available.
XLD contour
- 'candidate_xld':
-
An XLD contour that surrounds the candidate or decoded symbol.
This object can be requested for any group of results or for any single candidate or symbol handle. The persistence setting is of no relevance.
Pyramid images
- 'search_image':
-
Pyramid image, in which the candidate was found.
- 'process_image':
-
Pyramid image, in which the candidate was investigated more closely.
The persistence setting is also not relevant here.
Execution Information
- Multithreading type: reentrant (runs in parallel with non-exclusive operators).
- Multithreading scope: global (may be called from any thread).
- Processed without parallelization.
Parameters
DataCodeObjects (output_object) object(-array) → object
Objects that are created as intermediate results during the detection or evaluation of 2D data codes.
DataCodeHandle (input_control) datacode_2d → (handle)
Handle of the 2D data code model.
CandidateHandle (input_control) integer → (integer / string)
Handle of the 2D data code candidate. Either an integer
(usually the ResultHandle of find_data_code_2d) or
a string representing a group of candidates.
Default: 'all_candidates'
Suggested values: 0, 1, 2, 'all_candidates', 'all_results', 'all_undecoded', 'all_aborted'
ObjectName (input_control) string → (string)
Name of the iconic object to return.
Default: 'candidate_xld'
List of values: 'candidate_xld', 'module_0_rois', 'module_1_rois', 'process_image', 'search_image'
Example (HDevelop)
* Example demonstrating how to access the iconic objects 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)
set_data_code_2d_param (DataCodeHandle, 'default_parameters', \
'maximum_recognition')
set_data_code_2d_param (DataCodeHandle, 'persistence', 1)
* Read an image
read_image (Image, 'datacode/ecc200/ecc200_disturbed_012')
* Read the symbol in the image
find_data_code_2d (Image, SymbolXLDs, DataCodeHandle, [], [], \
ResultHandles, DecodedDataStrings)
* 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 and the classified
* module regions
for I := 0 to |HandlesUndecoded| - 1 by 1
* Display image.
dev_display (Image)
dev_set_draw ('margin')
* Get the contour of the symbol.
dev_set_color ('blue')
get_data_code_2d_objects (SymbolXLD, DataCodeHandle, \
HandlesUndecoded[I], 'candidate_xld')
dev_display (SymbolXLD)
* Get the module regions of the foreground modules
dev_set_color ('green')
get_data_code_2d_objects (ModuleFG, DataCodeHandle, \
HandlesUndecoded[I], 'module_1_rois')
dev_display (ModuleFG)
* Get the module regions of the background modules
dev_set_color ('red')
get_data_code_2d_objects (ModuleBG, DataCodeHandle, \
HandlesUndecoded[I], 'module_0_rois')
dev_display (ModuleBG)
* Stop for inspecting the image.
stop ()
endfor
* Clear the model
clear_data_code_2d_model (DataCodeHandle)
Result
The operator get_data_code_2d_objects returns the value 2 (
H_MSG_TRUE)
if the given parameters are correct and the requested objects are
available for the last symbol search.
Otherwise, an exception is raised.
Possible Predecessors
find_data_code_2d,
query_data_code_2d_params
Possible Successors
See also
query_data_code_2d_params,
get_data_code_2d_results,
get_data_code_2d_param,
set_data_code_2d_param
Module
Data Code