ClassesClassesClassesClasses | | | | Operators

get_2d_bar_codeT_get_2d_bar_codeGet2dBarCodeget_2d_bar_codeGet2dBarCodeGet2dBarCode (Operator)

Name

get_2d_bar_codeT_get_2d_bar_codeGet2dBarCodeget_2d_bar_codeGet2dBarCodeGet2dBarCode — Extract the values of the data elements (in ECC 200: “modules”) inside a bar code region (“Data Matrix symbol”).

Warning

get_2d_bar_codeget_2d_bar_codeGet2dBarCodeget_2d_bar_codeGet2dBarCodeGet2dBarCode is obsolete and is only provided for reasons of backward compatibility. New applications should use the functionality in the chapter Identification / Data Code for reading 2D data code symbologies instead (see create_data_code_2d_modelcreate_data_code_2d_modelCreateDataCode2dModelcreate_data_code_2d_modelCreateDataCode2dModelCreateDataCode2dModel).

Signature

get_2d_bar_code(BarCodeRegion, Image : : BarCodeDescr, CodeRegDescr, GenParamNames, GenParamValues : BarCodeDimension, BarCodeData)

Herror T_get_2d_bar_code(const Hobject BarCodeRegion, const Hobject Image, const Htuple BarCodeDescr, const Htuple CodeRegDescr, const Htuple GenParamNames, const Htuple GenParamValues, Htuple* BarCodeDimension, Htuple* BarCodeData)

Herror get_2d_bar_code(Hobject BarCodeRegion, Hobject Image, const HTuple& BarCodeDescr, const HTuple& CodeRegDescr, const HTuple& GenParamNames, const HTuple& GenParamValues, HTuple* BarCodeDimension, HTuple* BarCodeData)

HTuple HRegion::Get2dBarCode(const HImage& Image, const HTuple& BarCodeDescr, const HTuple& CodeRegDescr, const HTuple& GenParamNames, const HTuple& GenParamValues, HTuple* BarCodeData) const

HTuple HBarCode2D::Get2dBarCode(const HRegion& BarCodeRegion, const HImage& Image, const HTuple& CodeRegDescr, const HTuple& GenParamNames, const HTuple& GenParamValues, HTuple* BarCodeData) const

void Get2dBarCode(const HObject& BarCodeRegion, const HObject& Image, const HTuple& BarCodeDescr, const HTuple& CodeRegDescr, const HTuple& GenParamNames, const HTuple& GenParamValues, HTuple* BarCodeDimension, HTuple* BarCodeData)

HTuple HImage::Get2dBarCode(const HRegion& BarCodeRegion, const HTuple& BarCodeDescr, const HTuple& CodeRegDescr, const HTuple& GenParamNames, const HTuple& GenParamValues, HTuple* BarCodeData) const

HTuple HRegion::Get2dBarCode(const HImage& Image, const HTuple& BarCodeDescr, const HTuple& CodeRegDescr, const HTuple& GenParamNames, const HTuple& GenParamValues, HTuple* BarCodeData) const

void HOperatorSetX.Get2dBarCode(
[in] IHUntypedObjectX* BarCodeRegion, [in] IHUntypedObjectX* Image, [in] VARIANT BarCodeDescr, [in] VARIANT CodeRegDescr, [in] VARIANT GenParamNames, [in] VARIANT GenParamValues, [out] VARIANT* BarCodeDimension, [out] VARIANT* BarCodeData)

VARIANT HBarCode2DX.Get2dBarCode(
[in] IHRegionX* BarCodeRegion, [in] IHImageX* Image, [in] VARIANT BarCodeDescr, [in] VARIANT CodeRegDescr, [in] VARIANT GenParamNames, [in] VARIANT GenParamValues, [out] VARIANT* BarCodeData)

VARIANT HImageX.Get2dBarCode(
[in] IHRegionX* BarCodeRegion, [in] VARIANT BarCodeDescr, [in] VARIANT CodeRegDescr, [in] VARIANT GenParamNames, [in] VARIANT GenParamValues, [out] VARIANT* BarCodeData)

VARIANT HRegionX.Get2dBarCode(
[in] IHImageX* Image, [in] VARIANT BarCodeDescr, [in] VARIANT CodeRegDescr, [in] VARIANT GenParamNames, [in] VARIANT GenParamValues, [out] VARIANT* BarCodeData)

static void HOperatorSet.Get2dBarCode(HObject barCodeRegion, HObject image, HTuple barCodeDescr, HTuple codeRegDescr, HTuple genParamNames, HTuple genParamValues, out HTuple barCodeDimension, out HTuple barCodeData)

HTuple HImage.Get2dBarCode(HRegion barCodeRegion, HTuple barCodeDescr, HTuple codeRegDescr, HTuple genParamNames, HTuple genParamValues, out HTuple barCodeData)

HTuple HRegion.Get2dBarCode(HImage image, HTuple barCodeDescr, HTuple codeRegDescr, HTuple genParamNames, HTuple genParamValues, out HTuple barCodeData)

Description

get_2d_bar_codeget_2d_bar_codeGet2dBarCodeget_2d_bar_codeGet2dBarCodeGet2dBarCode extracts the 2D bar code from a candidate symbol region given in BarCodeRegionBarCodeRegionBarCodeRegionBarCodeRegionBarCodeRegionbarCodeRegion and the corresponding image given in ImageImageImageImageImageimage. BarCodeDescrBarCodeDescrBarCodeDescrBarCodeDescrBarCodeDescrbarCodeDescr contains a descriptor of the expected bar code class, which is created with the help of the operator gen_2d_bar_code_descrgen_2d_bar_code_descrGen2dBarCodeDescrgen_2d_bar_code_descrGen2dBarCodeDescrGen2dBarCodeDescr. CodeRegDescrCodeRegDescrCodeRegDescrCodeRegDescrCodeRegDescrcodeRegDescr contains further information regarding the candidate region. This descriptor is created by the operator find_2d_bar_codefind_2d_bar_codeFind2dBarCodefind_2d_bar_codeFind2dBarCodeFind2dBarCode.

If BarCodeRegionBarCodeRegionBarCodeRegionBarCodeRegionBarCodeRegionbarCodeRegion contains a 2D bar code, its data, i.e. the bits of the matrix, are written line by line into a tuple and returned in the parameter BarCodeDataBarCodeDataBarCodeDataBarCodeDataBarCodeDatabarCodeData. Positive values stand for a logical one, negative values for a logical zero. A value of zero signals that the data element could not be classified unambiguously.

The size of the data field is returned in the parameter BarCodeDimensionBarCodeDimensionBarCodeDimensionBarCodeDimensionBarCodeDimensionbarCodeDimension. The first two entries specify the width and the height of the data field, the third contains a so-called symbol index which also describes its size. The size of the data field is not to be confused with the size of the symbol which in turn encompasses additional finder and alignment patterns.

If no 2D bar code could be extracted the operator returns a corresponding error code.

In difficult cases, the user can influence image processing with the help of the (optional) generic parameters GenParamNamesGenParamNamesGenParamNamesGenParamNamesGenParamNamesgenParamNames and GenParamValuesGenParamValuesGenParamValuesGenParamValuesGenParamValuesgenParamValues. The width of a module in pixels ('module_width'"module_width""module_width""module_width""module_width""module_width") does not need to be specified, it is part of the region descriptor CodeRegDescrCodeRegDescrCodeRegDescrCodeRegDescrCodeRegDescrcodeRegDescr. As in the case of the operator find_2d_bar_codefind_2d_bar_codeFind2dBarCodefind_2d_bar_codeFind2dBarCodeFind2dBarCode, for the different printing methods different image processing steps are applied, leading to different parameters.

As a short overview, image processing falls into the following parts: First, the region BarCodeRegionBarCodeRegionBarCodeRegionBarCodeRegionBarCodeRegionbarCodeRegion is divided into a dark and a light region by applying a thresholding operator. Because there must be a “silent” area around each 2D bar code, this area can be examined to determine whether the bar code is printed black-on-white or vice versa. With this information, the dark and the light region can be assigned to the logical data values. Next, BarCodeRegionBarCodeRegionBarCodeRegionBarCodeRegionBarCodeRegionbarCodeRegion is approximated by a rectangle. Then, the special finder patterns that each each symbol must contain are searched for in the border areas of the rectangle. From the finder pattern, the size of the data matrix and the size and the position of the modules (data elements) can be determined. Finally, the value of the modules is determined.

Attention

The operator get_2d_bar_codeget_2d_bar_codeGet2dBarCodeget_2d_bar_codeGet2dBarCodeGet2dBarCode returns error codes to signal that the candidate region did not contain a valid 2D bar code. As the region candidates extracted by the operator find_2d_bar_codefind_2d_bar_codeFind2dBarCodefind_2d_bar_codeFind2dBarCodeFind2dBarCode can perfectly well encompass regions without a bar code, every call to get_2d_bar_codeget_2d_bar_codeGet2dBarCodeget_2d_bar_codeGet2dBarCodeGet2dBarCode should be surrounded by error handling code (see example).

Parallelization

Parameters

BarCodeRegionBarCodeRegionBarCodeRegionBarCodeRegionBarCodeRegionbarCodeRegion (input_object)  region objectHRegionHRegionHRegionHRegionXHobject

Region that might contain a 2D bar code.

ImageImageImageImageImageimage (input_object)  singlechannelimage objectHImageHImageHImageHImageXHobject (byte)

Corresponding image.

BarCodeDescrBarCodeDescrBarCodeDescrBarCodeDescrBarCodeDescrbarCodeDescr (input_control)  barcode_2d HTupleHTupleHBarCode2D, HTupleHBarCode2DX, VARIANTHtuple (string / integer / real) (string / int / long / double) (HString / Hlong / double) (char* / Hlong / double) (BSTR / Hlong / double) (char* / Hlong / double)

Description of the bar code class.

CodeRegDescrCodeRegDescrCodeRegDescrCodeRegDescrCodeRegDescrcodeRegDescr (input_control)  string-array HTupleHTupleHTupleVARIANTHtuple (string / integer / real) (string / int / long / double) (HString / Hlong / double) (char* / Hlong / double) (BSTR / Hlong / double) (char* / Hlong / double)

Additional parameters describing the bar code region. They can be used for extracting the data

GenParamNamesGenParamNamesGenParamNamesGenParamNamesGenParamNamesgenParamNames (input_control)  attribute.name-array HTupleHTupleHTupleVARIANTHtuple (string) (string) (HString) (char*) (BSTR) (char*)

List of names of (optional) generic control parameters.

Default value: []

List of values: 'border_width'"border_width""border_width""border_width""border_width""border_width", 'border_width_max'"border_width_max""border_width_max""border_width_max""border_width_max""border_width_max", 'border_width_min'"border_width_min""border_width_min""border_width_min""border_width_min""border_width_min", 'enlarge_region_rad'"enlarge_region_rad""enlarge_region_rad""enlarge_region_rad""enlarge_region_rad""enlarge_region_rad", 'gray_erosion_size'"gray_erosion_size""gray_erosion_size""gray_erosion_size""gray_erosion_size""gray_erosion_size", 'max_line_dist1'"max_line_dist1""max_line_dist1""max_line_dist1""max_line_dist1""max_line_dist1", 'max_line_dist2'"max_line_dist2""max_line_dist2""max_line_dist2""max_line_dist2""max_line_dist2", 'measure_sigma'"measure_sigma""measure_sigma""measure_sigma""measure_sigma""measure_sigma", 'measure_thresh'"measure_thresh""measure_thresh""measure_thresh""measure_thresh""measure_thresh", 'median_mask_rad'"median_mask_rad""median_mask_rad""median_mask_rad""median_mask_rad""median_mask_rad", 'min_cont_len'"min_cont_len""min_cont_len""min_cont_len""min_cont_len""min_cont_len", 'module_rad_ratio'"module_rad_ratio""module_rad_ratio""module_rad_ratio""module_rad_ratio""module_rad_ratio", 'smooth_cont'"smooth_cont""smooth_cont""smooth_cont""smooth_cont""smooth_cont", 'thresh_percent'"thresh_percent""thresh_percent""thresh_percent""thresh_percent""thresh_percent", 'thresh_step_width'"thresh_step_width""thresh_step_width""thresh_step_width""thresh_step_width""thresh_step_width", 'use_grayval_max'"use_grayval_max""use_grayval_max""use_grayval_max""use_grayval_max""use_grayval_max", 'use_grayval_min'"use_grayval_min""use_grayval_min""use_grayval_min""use_grayval_min""use_grayval_min", 'use_grayval_range'"use_grayval_range""use_grayval_range""use_grayval_range""use_grayval_range""use_grayval_range", 'use_grayvals'"use_grayvals""use_grayvals""use_grayvals""use_grayvals""use_grayvals"

GenParamValuesGenParamValuesGenParamValuesGenParamValuesGenParamValuesgenParamValues (input_control)  attribute.value-array HTupleHTupleHTupleVARIANTHtuple (real / integer / string) (double / int / long / string) (double / Hlong / HString) (double / Hlong / char*) (double / Hlong / BSTR) (double / Hlong / char*)

List of values of the generic parameters.

Default value: []

Suggested values: 0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9, 1.0, 'yes'"yes""yes""yes""yes""yes", 'no'"no""no""no""no""no", -1, 1.5, 2.5, 3.5, 4.5, 5.5, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 20, 30, 40, 50

BarCodeDimensionBarCodeDimensionBarCodeDimensionBarCodeDimensionBarCodeDimensionbarCodeDimension (output_control)  integer-array HTupleHTupleHTupleVARIANTHtuple (integer) (int / long) (Hlong) (Hlong) (Hlong) (Hlong)

Tuple with the dimension of the extracted symbol. In the case of ECC 200: data field width, height, symbol index.

BarCodeDataBarCodeDataBarCodeDataBarCodeDataBarCodeDatabarCodeData (output_control)  integer-array HTupleHTupleHTupleVARIANTHtuple (integer) (int / long) (Hlong) (Hlong) (Hlong) (Hlong)

Tuple with the data values of the extracted symbol. value > 0: logical 1, value < 0: logical 0, value = 0: module could not be classified.

Example (HDevelop)

dev_error_var (ErrorCode, 1)
gen_2d_bar_code_descr ('Data Matrix ECC 200', ['mode'], ['printed'], \
                       BarCodeDescr)
read_image (Image, 'bar2d.tif')
find_2d_bar_code (Image, CodeRegion, BarCodeDescr, \
                  ['module_width'], [10], CodeRegDescr)
count_obj (CodeRegion, SymbolNum)
for i := 1 to SymbolNum by 1
  select_obj (CodeRegion, ObjectSelected, i)
  dev_set_check ('~give_error')
  get_2d_bar_code (ObjectSelected, Image, BarCodeDescr, CodeRegDescr, \
                   [], [], BarCodeDimension, BarCodeData)
  err := ErrorCode
  dev_set_check ('give_error')
  if (err = 2)
    decode_2d_bar_code (BarCodeDescr, BarCodeDimension, BarCodeData, \
                        SymbolCharacters, CorrSymbolData, DecodedData, \
                        DecodingError, StructuredAppend)
    if (|DecodedData|)
      tuple_chrt (DecodedData, String)
    endif
  endif
endfor

Result

The return value can signal incorrect parameters as well as the failure to extract a 2D bar code. Such a failure can be due to different causes: If no surrounding rectangle was found, the operator returns the error code 8808. Error code 8807 signals that the rectangle does not lie completely inside the image. If no finder pattern was detected inside the border search area, the error code 8810 is returned. If the two continuous lines forming the 'L' of the finder pattern could not be found, the error code 8809 is returned. In the case of the printing method 'engraved_darkfield'"engraved_darkfield""engraved_darkfield""engraved_darkfield""engraved_darkfield""engraved_darkfield", the error code 8811 signals that none of the gray value features can separate the test regions, i.e. that modules cannot be classified.

Module

Data Code


ClassesClassesClassesClasses | | | | Operators