find_bar_codeT_find_bar_codeFindBarCodeFindBarCode (Operator)

Name

find_bar_codeT_find_bar_codeFindBarCodeFindBarCode — Detect and read bar code symbols in an image.

Signature

find_bar_code(Image : SymbolRegions : BarCodeHandle, CodeType : DecodedDataStrings)

Herror T_find_bar_code(const Hobject Image, Hobject* SymbolRegions, const Htuple BarCodeHandle, const Htuple CodeType, Htuple* DecodedDataStrings)

void FindBarCode(const HObject& Image, HObject* SymbolRegions, const HTuple& BarCodeHandle, const HTuple& CodeType, HTuple* DecodedDataStrings)

HRegion HBarCode::FindBarCode(const HImage& Image, const HTuple& CodeType, HTuple* DecodedDataStrings) const

HRegion HBarCode::FindBarCode(const HImage& Image, const HString& CodeType, HString* DecodedDataStrings) const

HRegion HBarCode::FindBarCode(const HImage& Image, const char* CodeType, HString* DecodedDataStrings) const

HRegion HBarCode::FindBarCode(const HImage& Image, const wchar_t* CodeType, HString* DecodedDataStrings) const   (Windows only)

HRegion HImage::FindBarCode(const HBarCode& BarCodeHandle, const HTuple& CodeType, HTuple* DecodedDataStrings) const

HRegion HImage::FindBarCode(const HBarCode& BarCodeHandle, const HString& CodeType, HString* DecodedDataStrings) const

HRegion HImage::FindBarCode(const HBarCode& BarCodeHandle, const char* CodeType, HString* DecodedDataStrings) const

HRegion HImage::FindBarCode(const HBarCode& BarCodeHandle, const wchar_t* CodeType, HString* DecodedDataStrings) const   (Windows only)

static void HOperatorSet.FindBarCode(HObject image, out HObject symbolRegions, HTuple barCodeHandle, HTuple codeType, out HTuple decodedDataStrings)

HRegion HBarCode.FindBarCode(HImage image, HTuple codeType, out HTuple decodedDataStrings)

HRegion HBarCode.FindBarCode(HImage image, string codeType, out string decodedDataStrings)

HRegion HImage.FindBarCode(HBarCode barCodeHandle, HTuple codeType, out HTuple decodedDataStrings)

HRegion HImage.FindBarCode(HBarCode barCodeHandle, string codeType, out string decodedDataStrings)

Description

The operator find_bar_codefind_bar_codeFindBarCodeFindBarCodeFindBarCode finds and reads bar code symbols in a given image (ImageImageImageImageimage) and returns the decoded data. In one image an arbitrary number of bar codes of a single type can be read. The type of the desired bar code symbology is given by CodeTypeCodeTypeCodeTypeCodeTypecodeType. The decoded strings are returned in DecodedDataStringsDecodedDataStringsDecodedDataStringsDecodedDataStringsdecodedDataStrings and the corresponding bar code regions in SymbolRegionsSymbolRegionsSymbolRegionsSymbolRegionssymbolRegions. For a total of n successfully read bar codes, the indices from 0 to (n-1) can be used as candidate handle in the operators get_bar_code_objectget_bar_code_objectGetBarCodeObjectGetBarCodeObjectGetBarCodeObject and get_bar_code_resultget_bar_code_resultGetBarCodeResultGetBarCodeResultGetBarCodeResult in order to retrieve the desired data of one specific bar code result.

Bar codes are expected to appear dark on a light background. To read light bar codes on a dark background, invert the input image using the operator invert_imageinvert_imageInvertImageInvertImageInvertImage beforehand.

Before calling find_bar_codefind_bar_codeFindBarCodeFindBarCodeFindBarCode a bar code model must be created by calling create_bar_code_modelcreate_bar_code_modelCreateBarCodeModelCreateBarCodeModelCreateBarCodeModel. This operator returns a bar code model BarCodeHandleBarCodeHandleBarCodeHandleBarCodeHandlebarCodeHandle, which is input to find_bar_codefind_bar_codeFindBarCodeFindBarCodeFindBarCode.

The output value DecodedDataStringsDecodedDataStringsDecodedDataStringsDecodedDataStringsdecodedDataStrings contains the decoded string of the symbol for each bar code result. The contents of the strings are conform to the appropriate standard of the symbology. Typically, DecodedDataStringsDecodedDataStringsDecodedDataStringsDecodedDataStringsdecodedDataStrings contains only data characters. For bar codes with a mandatory check character the check character is not included in the string. For bar codes with an optional check character, like for example Code 39, Codabar, 2/5 Industrial or 2/5 Interleaved, the result depends on the value of the 'check_char'"check_char""check_char""check_char""check_char" parameter, which can be set in create_bar_code_modelcreate_bar_code_modelCreateBarCodeModelCreateBarCodeModelCreateBarCodeModel, set_bar_code_paramset_bar_code_paramSetBarCodeParamSetBarCodeParamSetBarCodeParam or set_bar_code_param_specificset_bar_code_param_specificSetBarCodeParamSpecificSetBarCodeParamSpecificSetBarCodeParamSpecific: The default setting of 'absent'"absent""absent""absent""absent" assumes that no check character is present. In this case, no check is performed and all characters are returned as data. When set to 'present'"present""present""present""present", a check character is expected and used to verify the correctness of the bar code. The bar code is graded as unreadable if the check sum does not match. Accordingly, the symbol region and the decoded string do not appear in the list of resulting strings (DecodedDataStringsDecodedDataStringsDecodedDataStringsDecodedDataStringsdecodedDataStrings) and in the list of resulting regions (SymbolRegionsSymbolRegionsSymbolRegionsSymbolRegionssymbolRegions). The check character itself is stripped from the data. If this stripping is undesired, the mode 'preserved'"preserved""preserved""preserved""preserved" allows to verify the bar code while still keeping the check character in the data.

The underlying decoded reference data, including start/stop and check characters, can be queried by using the get_bar_code_resultget_bar_code_resultGetBarCodeResultGetBarCodeResultGetBarCodeResult operator with the option 'decoded_reference'"decoded_reference""decoded_reference""decoded_reference""decoded_reference".

Following bar code symbologies are supported:

2/5 Industrial EAN-8 GS1-128
2/5 Interleaved EAN-8 Add-On 2 GS1 DataBar Omnidirectional
Codabar EAN-8 Add-On 5 GS1 DataBar Truncated
Code 39 EAN-13 GS1 DataBar Stacked
Code 32 (converted from Code 39) EAN-13 Add-On 2 GS1 DataBar Stacked Omnidirectional
Code 93 EAN-13 Add-On 5 GS1 DataBar Limited
Code 128 UPC-A GS1 DataBar Expanded
MSI UPC-A Add-On 2 GS1 DataBar Expanded Stacked
PharmaCode UPC-A Add-On 5
UPC-E
UPC-E Add-On 2
UPC-E Add-On 5

Note that the PharmaCode can be read in forward and backward direction, both yielding a valid result. Therefore, both strings are returned and concatenated into a single string in DecodedDataStringsDecodedDataStringsDecodedDataStringsDecodedDataStringsdecodedDataStrings by a separating comma.

Note that the GS1 DataBar bar codes may contain an additional composite code component. To find and decode this component, set the parameter 'composite_code'"composite_code""composite_code""composite_code""composite_code" to 'CC-A/B'"CC-A/B""CC-A/B""CC-A/B""CC-A/B" using the operator set_bar_code_paramset_bar_code_paramSetBarCodeParamSetBarCodeParamSetBarCodeParam.

Note that also a barcode of type 'Code 32' can be read by using find_bar_codefind_bar_codeFindBarCodeFindBarCodeFindBarCode with CodeTypeCodeTypeCodeTypeCodeTypecodeType set to 'Code 39'"Code 39""Code 39""Code 39""Code 39" in combination with the external procedure convert_decoded_string_code39_to_code32.

Autodiscrimination

Autodiscrimination describes the simultaneous decoding of multiple bar code types in one call of find_bar_codefind_bar_codeFindBarCodeFindBarCodeFindBarCode. For this purpose a tuple of bar code types is specified for the parameter CodeTypeCodeTypeCodeTypeCodeTypecodeType. Using the generic value 'auto'"auto""auto""auto""auto" all known bar code types are decoded - except 'PharmaCode'"PharmaCode""PharmaCode""PharmaCode""PharmaCode" and 'MSI'"MSI""MSI""MSI""MSI" because these codes don't have enough features to be reliably separated from other bar code types. The tuple can also contain bar code types with the tilde prefix (~) which won't be decoded. For example ['auto'"auto""auto""auto""auto", '~EAN-8'"~EAN-8""~EAN-8""~EAN-8""~EAN-8", '~EAN-8 Add-On 2'"~EAN-8 Add-On 2""~EAN-8 Add-On 2""~EAN-8 Add-On 2""~EAN-8 Add-On 2", '~EAN-8 Add-On 5'"~EAN-8 Add-On 5""~EAN-8 Add-On 5""~EAN-8 Add-On 5""~EAN-8 Add-On 5"] describes all bar code types without 'PharmaCode'"PharmaCode""PharmaCode""PharmaCode""PharmaCode", 'MSI'"MSI""MSI""MSI""MSI" and all kinds of 'EAN-8'"EAN-8""EAN-8""EAN-8""EAN-8". Please note that each additionally allowed bar code type increases the run-time of the operator. Using too many bar code types the reliability of the decoding could decrease because not all bar code types can be discriminated reliably. To improve autodiscrimination compatibility bar codes with a check character or check sum should be used.

The bar code reader tries to decode the bar code types in the following order:

'GS1 DataBar Omnidir'"GS1 DataBar Omnidir""GS1 DataBar Omnidir""GS1 DataBar Omnidir""GS1 DataBar Omnidir", 'GS1 DataBar Truncated'"GS1 DataBar Truncated""GS1 DataBar Truncated""GS1 DataBar Truncated""GS1 DataBar Truncated", 'GS1 DataBar Stacked'"GS1 DataBar Stacked""GS1 DataBar Stacked""GS1 DataBar Stacked""GS1 DataBar Stacked", 'GS1 DataBar Stacked Omnidir'"GS1 DataBar Stacked Omnidir""GS1 DataBar Stacked Omnidir""GS1 DataBar Stacked Omnidir""GS1 DataBar Stacked Omnidir", 'GS1 DataBar Limited'"GS1 DataBar Limited""GS1 DataBar Limited""GS1 DataBar Limited""GS1 DataBar Limited", 'GS1 DataBar Expanded'"GS1 DataBar Expanded""GS1 DataBar Expanded""GS1 DataBar Expanded""GS1 DataBar Expanded", 'GS1 DataBar Expanded Stacked'"GS1 DataBar Expanded Stacked""GS1 DataBar Expanded Stacked""GS1 DataBar Expanded Stacked""GS1 DataBar Expanded Stacked", 'GS1-128'"GS1-128""GS1-128""GS1-128""GS1-128", 'Code 128'"Code 128""Code 128""Code 128""Code 128", 'EAN-13 Add-On 5'"EAN-13 Add-On 5""EAN-13 Add-On 5""EAN-13 Add-On 5""EAN-13 Add-On 5", 'EAN-13 Add-On 2'"EAN-13 Add-On 2""EAN-13 Add-On 2""EAN-13 Add-On 2""EAN-13 Add-On 2", 'EAN-13'"EAN-13""EAN-13""EAN-13""EAN-13", 'UPC-A Add-On 5'"UPC-A Add-On 5""UPC-A Add-On 5""UPC-A Add-On 5""UPC-A Add-On 5", 'UPC-A Add-On 2'"UPC-A Add-On 2""UPC-A Add-On 2""UPC-A Add-On 2""UPC-A Add-On 2", 'UPC-A'"UPC-A""UPC-A""UPC-A""UPC-A", 'EAN-8 Add-On 5'"EAN-8 Add-On 5""EAN-8 Add-On 5""EAN-8 Add-On 5""EAN-8 Add-On 5", 'EAN-8 Add-On 2'"EAN-8 Add-On 2""EAN-8 Add-On 2""EAN-8 Add-On 2""EAN-8 Add-On 2", 'EAN-8'"EAN-8""EAN-8""EAN-8""EAN-8", 'UPC-E Add-On 5'"UPC-E Add-On 5""UPC-E Add-On 5""UPC-E Add-On 5""UPC-E Add-On 5", 'UPC-E Add-On 2'"UPC-E Add-On 2""UPC-E Add-On 2""UPC-E Add-On 2""UPC-E Add-On 2", 'UPC-E'"UPC-E""UPC-E""UPC-E""UPC-E", 'Code 93'"Code 93""Code 93""Code 93""Code 93", 'Code 39'"Code 39""Code 39""Code 39""Code 39", 'Codabar'"Codabar""Codabar""Codabar""Codabar", '2/5 Interleaved'"2/5 Interleaved""2/5 Interleaved""2/5 Interleaved""2/5 Interleaved", '2/5 Industrial'"2/5 Industrial""2/5 Industrial""2/5 Industrial""2/5 Industrial"

Therefore you should exclude at least all definitely not occurring bar code types that are scanned before the first of the bar code types you expect to find or, better, just scan for the explicit list of bar code types you expect.

Especially for the autodiscrimination there is the operator set_bar_code_param_specificset_bar_code_param_specificSetBarCodeParamSpecificSetBarCodeParamSpecificSetBarCodeParamSpecific. With it some parameters of the bar code model can be set specifically for certain bar code types.

Training

If the bar code reader is in training mode, the operator find_bar_codefind_bar_codeFindBarCodeFindBarCodeFindBarCode executes a training cycle. The training mode is described with the operator set_bar_code_paramset_bar_code_paramSetBarCodeParamSetBarCodeParamSetBarCodeParam.

Timeout and Abort

The operator find_bar_codefind_bar_codeFindBarCodeFindBarCodeFindBarCode can be aborted by a timeout and dynamically. With the operator set_bar_code_paramset_bar_code_paramSetBarCodeParamSetBarCodeParamSetBarCodeParam you can specify a timeout. If find_bar_codefind_bar_codeFindBarCodeFindBarCodeFindBarCode reaches this timeout, it returns all codes decoded so far. Alternatively, you can call set_bar_code_paramset_bar_code_paramSetBarCodeParamSetBarCodeParamSetBarCodeParam with 'abort' from another thread to abort find_bar_codefind_bar_codeFindBarCodeFindBarCodeFindBarCode dynamically.

The information whether the operator was aborted or not can be queried by calling get_bar_code_resultget_bar_code_resultGetBarCodeResultGetBarCodeResultGetBarCodeResult with the parameter 'aborted'"aborted""aborted""aborted""aborted".

Advice on low resolution bar code imaging systems

This advice applies to bar code applications that use low resolution images, i.e., images in which a single bar is between one and two pixels wide.

In these cases, one should optimize the bar code imaging system in order to eliminate noise and focal blur because a combination of these optical distortions lead to problems in the decodability of low resolution bar codes.

Execution Information

This operator modifies the state of the following input parameter:

During execution of this operator, access to the value of this parameter must be synchronized if it is used across multiple threads.

Parameters

ImageImageImageImageimage (input_object)  singlechannelimage objectHImageHImageHobject (byte / uint2)

Input image. If the image has a reduced domain, the barcode search is reduced to that domain. This usually reduces the runtime of the operator. However, if the barcode is not fully inside the domain, the barcode cannot be decoded correctly.

SymbolRegionsSymbolRegionsSymbolRegionsSymbolRegionssymbolRegions (output_object)  region(-array) objectHRegionHRegionHobject *

Regions of the successfully decoded bar code symbols.

BarCodeHandleBarCodeHandleBarCodeHandleBarCodeHandlebarCodeHandle (input_control, state is modified)  barcode HBarCode, HTupleHTupleHtuple (handle) (IntPtr) (HHandle) (handle)

Handle of the bar code model.

CodeTypeCodeTypeCodeTypeCodeTypecodeType (input_control)  string(-array) HTupleHTupleHtuple (string) (string) (HString) (char*)

Type of the searched bar code.

Default value: 'auto' "auto" "auto" "auto" "auto"

List of values: '2/5 Industrial'"2/5 Industrial""2/5 Industrial""2/5 Industrial""2/5 Industrial", '2/5 Interleaved'"2/5 Interleaved""2/5 Interleaved""2/5 Interleaved""2/5 Interleaved", 'Codabar'"Codabar""Codabar""Codabar""Codabar", 'Code 128'"Code 128""Code 128""Code 128""Code 128", 'Code 39'"Code 39""Code 39""Code 39""Code 39", 'Code 93'"Code 93""Code 93""Code 93""Code 93", 'EAN-13 Add-On 2'"EAN-13 Add-On 2""EAN-13 Add-On 2""EAN-13 Add-On 2""EAN-13 Add-On 2", 'EAN-13 Add-On 5'"EAN-13 Add-On 5""EAN-13 Add-On 5""EAN-13 Add-On 5""EAN-13 Add-On 5", 'EAN-13'"EAN-13""EAN-13""EAN-13""EAN-13", 'EAN-8 Add-On 2'"EAN-8 Add-On 2""EAN-8 Add-On 2""EAN-8 Add-On 2""EAN-8 Add-On 2", 'EAN-8 Add-On 5'"EAN-8 Add-On 5""EAN-8 Add-On 5""EAN-8 Add-On 5""EAN-8 Add-On 5", 'EAN-8'"EAN-8""EAN-8""EAN-8""EAN-8", 'GS1 DataBar Expanded Stacked'"GS1 DataBar Expanded Stacked""GS1 DataBar Expanded Stacked""GS1 DataBar Expanded Stacked""GS1 DataBar Expanded Stacked", 'GS1 DataBar Expanded'"GS1 DataBar Expanded""GS1 DataBar Expanded""GS1 DataBar Expanded""GS1 DataBar Expanded", 'GS1 DataBar Limited'"GS1 DataBar Limited""GS1 DataBar Limited""GS1 DataBar Limited""GS1 DataBar Limited", 'GS1 DataBar Omnidir'"GS1 DataBar Omnidir""GS1 DataBar Omnidir""GS1 DataBar Omnidir""GS1 DataBar Omnidir", 'GS1 DataBar Stacked Omnidir'"GS1 DataBar Stacked Omnidir""GS1 DataBar Stacked Omnidir""GS1 DataBar Stacked Omnidir""GS1 DataBar Stacked Omnidir", 'GS1 DataBar Stacked'"GS1 DataBar Stacked""GS1 DataBar Stacked""GS1 DataBar Stacked""GS1 DataBar Stacked", 'GS1 DataBar Truncated'"GS1 DataBar Truncated""GS1 DataBar Truncated""GS1 DataBar Truncated""GS1 DataBar Truncated", 'GS1-128'"GS1-128""GS1-128""GS1-128""GS1-128", 'MSI'"MSI""MSI""MSI""MSI", 'PharmaCode'"PharmaCode""PharmaCode""PharmaCode""PharmaCode", 'UPC-A Add-On 2'"UPC-A Add-On 2""UPC-A Add-On 2""UPC-A Add-On 2""UPC-A Add-On 2", 'UPC-A Add-On 5'"UPC-A Add-On 5""UPC-A Add-On 5""UPC-A Add-On 5""UPC-A Add-On 5", 'UPC-A'"UPC-A""UPC-A""UPC-A""UPC-A", 'UPC-E Add-On 2'"UPC-E Add-On 2""UPC-E Add-On 2""UPC-E Add-On 2""UPC-E Add-On 2", 'UPC-E Add-On 5'"UPC-E Add-On 5""UPC-E Add-On 5""UPC-E Add-On 5""UPC-E Add-On 5", 'UPC-E'"UPC-E""UPC-E""UPC-E""UPC-E", 'auto'"auto""auto""auto""auto"

DecodedDataStringsDecodedDataStringsDecodedDataStringsDecodedDataStringsdecodedDataStrings (output_control)  string(-array) HTupleHTupleHtuple (string) (string) (HString) (char*)

Data strings of all successfully decoded bar codes.

Example (HDevelop)

* Small example for aborting bar code search:
read_image (Image, 'barcode/ean13/tea_box_10.png')

* Decode normally:
create_bar_code_model ([], [], BarCodeHandle)
find_bar_code (Image, SymbolRegions, BarCodeHandle, 'auto', \
    DecodedDataStrings)
stop ()

* Start bar code search in separate thread.
par_start<ThreadID>: find_bar_code (Image, SymbolRegions1, BarCodeHandle, \
    'auto', DecodedDataStrings1)

* Let some time pass.
wait_seconds (0.002)

* Abort the data code search.
set_bar_code_param (BarCodeHandle, 'abort', 'true')

* Wait for the thread, it should finish very fast.
par_join(ThreadID)

* We can determine that the search in fact was aborted.
get_bar_code_result (BarCodeHandle, 'all', 'aborted', Aborted)

Result

The operator find_bar_codefind_bar_codeFindBarCodeFindBarCodeFindBarCode returns the value 2 (H_MSG_TRUE) if the given parameters are correct. Otherwise, an exception will be raised.

Possible Predecessors

create_bar_code_modelcreate_bar_code_modelCreateBarCodeModelCreateBarCodeModelCreateBarCodeModel, set_bar_code_paramset_bar_code_paramSetBarCodeParamSetBarCodeParamSetBarCodeParam

Possible Successors

get_bar_code_resultget_bar_code_resultGetBarCodeResultGetBarCodeResultGetBarCodeResult, get_bar_code_objectget_bar_code_objectGetBarCodeObjectGetBarCodeObjectGetBarCodeObject, clear_bar_code_modelclear_bar_code_modelClearBarCodeModelClearBarCodeModelClearBarCodeModel

Alternatives

decode_bar_code_rectangle2decode_bar_code_rectangle2DecodeBarCodeRectangle2DecodeBarCodeRectangle2DecodeBarCodeRectangle2

Module

Bar Code