find_bar_codeT_find_bar_codeFindBarCodeFindBarCodefind_bar_code (Operator)

Name

find_bar_codeT_find_bar_codeFindBarCodeFindBarCodefind_bar_code — Suchen und Lesen von Barcode-Symbolen im Eingabebild.

Signatur

Beschreibung

Der Operator find_bar_codefind_bar_codeFindBarCodeFindBarCodeFindBarCodefind_bar_code sucht im Eingabebild (ImageImageImageImageimageimage) nach Barcode-Symbolen und dekodiert die darin enthaltenen Zeichenfolgen. In einem Bild kann eine beliebige Anzahl an Barcodes eines Typs gefunden und dekodiert werden, wobei der Typ des gesuchten Barcodes mit CodeTypeCodeTypeCodeTypeCodeTypecodeTypecode_type ausgewählt wird. Die gelesenen Zeichenfolgen werden in DecodedDataStringsDecodedDataStringsDecodedDataStringsDecodedDataStringsdecodedDataStringsdecoded_data_strings und die dazu korrespondierenden Barcode-Regionen in SymbolRegionsSymbolRegionsSymbolRegionsSymbolRegionssymbolRegionssymbol_regions zurück gegeben. Werden insgesamt n Barcodes erfolgreich gelesen, so können die Indizes von 0 bis (n-1) in den Operatoren get_bar_code_resultget_bar_code_resultGetBarCodeResultGetBarCodeResultGetBarCodeResultget_bar_code_result und get_bar_code_objectget_bar_code_objectGetBarCodeObjectGetBarCodeObjectGetBarCodeObjectget_bar_code_object verwendet werden, um die gewünschte Information eines speziellen Ergebnisse zu erhalten.

Es wird angenommen, dass die Barcodes dunkel auf einem hellen Hintergrund erscheinen. Um helle Barcodes auf einem dunklen Hintergrund lesen zu können, muss das Eingabebild vorher mit dem Operator invert_imageinvert_imageInvertImageInvertImageInvertImageinvert_image invertiert werden.

Vor dem Aufruf des Operators find_bar_codefind_bar_codeFindBarCodeFindBarCodeFindBarCodefind_bar_code muss mit Hilfe von create_bar_code_modelcreate_bar_code_modelCreateBarCodeModelCreateBarCodeModelCreateBarCodeModelcreate_bar_code_model ein Barcode-Modell erstellt und der dabei erzeugte Handle in BarCodeHandleBarCodeHandleBarCodeHandleBarCodeHandlebarCodeHandlebar_code_handle an find_bar_codefind_bar_codeFindBarCodeFindBarCodeFindBarCodefind_bar_code übergeben werden.

Der Ausgabewert DecodedDataStringsDecodedDataStringsDecodedDataStringsDecodedDataStringsdecodedDataStringsdecoded_data_strings gibt für jedes Ergebnis die dekodierte Zeichenfolge zurück. Der Inhalt dieser Zeichenfolge wird durch den Standard des entsprechenden Codetyps bestimmt. Typischerweise enthält DecodedDataStringsDecodedDataStringsDecodedDataStringsDecodedDataStringsdecodedDataStringsdecoded_data_strings nur die Zeichen mit Dateninformation. Bei Codes mit obligatorischem Prüfzeichen wird dieses nicht mit ausgegeben. Bei Codes mit optionalem Prüfzeichen, z.B. Code 39, Codabar, 2/5 Industrial oder 2/5 Interleaved, hängt das Ergebnis von der Einstellung des Parameters 'check_char'"check_char""check_char""check_char""check_char""check_char" ab, welcher in create_bar_code_modelcreate_bar_code_modelCreateBarCodeModelCreateBarCodeModelCreateBarCodeModelcreate_bar_code_model, set_bar_code_paramset_bar_code_paramSetBarCodeParamSetBarCodeParamSetBarCodeParamset_bar_code_param oder set_bar_code_param_specificset_bar_code_param_specificSetBarCodeParamSpecificSetBarCodeParamSpecificSetBarCodeParamSpecificset_bar_code_param_specific einstellbar ist: Der Standardwert von 'absent'"absent""absent""absent""absent""absent" gibt an, dass kein Prüfzeichen vorliegt. In diesem Fall wird keine Prüfung durchgeführt, und alle Zeichen werden als Daten zurückgeliefert. Ist dieser Parameter auf 'present'"present""present""present""present""present" gesetzt, so wird ein Prüfzeichen erwartet und benutzt um die Korrektheit des Barcodes zu prüfen. Ist die Prüfsumme fehlerhaft, so wird der Code als nicht lesbar eingestuft und dementsprechend auch nicht als Ergebnis in DecodedDataStringsDecodedDataStringsDecodedDataStringsDecodedDataStringsdecodedDataStringsdecoded_data_strings und SymbolRegionsSymbolRegionsSymbolRegionsSymbolRegionssymbolRegionssymbol_regions zurückgeliefert. Das Prüfzeichen selbst wird aus den Nutzdaten entfernt. Falls dies nicht erwünscht ist, kann der Parameterwert 'preserved'"preserved""preserved""preserved""preserved""preserved" eingestellt werden um das Prüfzeichen trotz Prüfung zu erhalten.

Die zu Grunde liegenden Referenz-Zeichen, einschließlich möglicher Start- oder Stopzeichen sowie Prüfzeichen, können mit get_bar_code_resultget_bar_code_resultGetBarCodeResultGetBarCodeResultGetBarCodeResultget_bar_code_result und 'decoded_reference'"decoded_reference""decoded_reference""decoded_reference""decoded_reference""decoded_reference" abgefragt werden.

Folgende Barcode-Symbole werden unterstützt:

Anmerkung: Da die Leserichtung beim PharmaCode nicht bestimmt werden kann, werden auch die beiden Zeichenketten für jede Leserichtung zurückgegeben. Beide Zeichenketten werden in einer Zeichenkette durch ein Komma getrennt aneinandergehängt.

Barcodes vom Typ GS1 DataBar können zusätzlich eine Composite-Code-Komponente enthalten. Um diese Komponente finden und dekodieren zu können, muss mittels des Operators set_bar_code_paramset_bar_code_paramSetBarCodeParamSetBarCodeParamSetBarCodeParamset_bar_code_param der Parameter 'composite_code'"composite_code""composite_code""composite_code""composite_code""composite_code" auf 'CC-A/B'"CC-A/B""CC-A/B""CC-A/B""CC-A/B""CC-A/B" gesetzt werden.

Es können auch Barcodes vom Typ 'Code 32' gelesen werden, indem der Operator find_bar_codefind_bar_codeFindBarCodeFindBarCodeFindBarCodefind_bar_code mit CodeTypeCodeTypeCodeTypeCodeTypecodeTypecode_type 'Code 39'"Code 39""Code 39""Code 39""Code 39""Code 39" in Kombination mit der externen Prozedur convert_decoded_string_code39_to_code32 verwendet wird.

HALCON unterstützt alle GS1 Application Identifier, die zum Zeitpunkt des Releases verfügbar waren. Um diese Liste zu aktualisieren kann der set_systemset_systemSetSystemSetSystemSetSystemset_system Parameter 'gs1_syntax_dictionary'"gs1_syntax_dictionary""gs1_syntax_dictionary""gs1_syntax_dictionary""gs1_syntax_dictionary""gs1_syntax_dictionary" verwendet werden.

Autodiskriminierung

Autodiskriminierung beschreibt das gleichzeitige Lesen mehrerer Barcode-Typen in einem Aufruf von find_bar_codefind_bar_codeFindBarCodeFindBarCodeFindBarCodefind_bar_code. Dazu wird dem Parameter CodeTypeCodeTypeCodeTypeCodeTypecodeTypecode_type ein Tupel von möglichen Barcode-Typen übergeben. Mit dem speziellen Wert 'auto'"auto""auto""auto""auto""auto" werden alle Barcode-Typen dekodiert, mit Ausnahme von 'PharmaCode'"PharmaCode""PharmaCode""PharmaCode""PharmaCode""PharmaCode" und 'MSI'"MSI""MSI""MSI""MSI""MSI", da diese zu wenige Merkmale bieten um von anderen Barcode-Typen abgegrenzt werden zu können. In dem Tupel können auch Barcode-Typen mit vorangestellter Tilde (~) angegeben werden, welche dann nicht dekodiert werden. So bezeichnet beispielsweise ['auto', '~EAN-8', '~EAN-8 Add-On 2', '~EAN-8 Add-On 5']["auto", "~EAN-8", "~EAN-8 Add-On 2", "~EAN-8 Add-On 5"]["auto", "~EAN-8", "~EAN-8 Add-On 2", "~EAN-8 Add-On 5"]["auto", "~EAN-8", "~EAN-8 Add-On 2", "~EAN-8 Add-On 5"]["auto", "~EAN-8", "~EAN-8 Add-On 2", "~EAN-8 Add-On 5"]["auto", "~EAN-8", "~EAN-8 Add-On 2", "~EAN-8 Add-On 5"] alle Barcode-Typen ohne 'PharmaCode'"PharmaCode""PharmaCode""PharmaCode""PharmaCode""PharmaCode", 'MSI'"MSI""MSI""MSI""MSI""MSI" und 'EAN-8'"EAN-8""EAN-8""EAN-8""EAN-8""EAN-8"-Arten. Zu beachten ist, dass jeder zusätzlich erlaubte Barcode-Typ die Laufzeit des Operators verlängert. Da eventuell nicht alle Barcodes definitiv voneinander unterschieden werden können nimmt ggf. die Zuverlässigkeit der Dekodierung mit jedem zusätzlichen Barcode-Typ ab. Um die Kompatibilität der Autodiskriminierung zu erhöhen sollten falls möglich immer Barcodes mit Prüfzeichen bzw. Prüfsumme verwendet werden.

Der Barcode-Leser versucht die Barcode-Typen in der folgenden Reihenfolge zu dekodieren:

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

Deshalb sollten mindestens alle nicht auftretenden Barcode-Typen ausgeschlossen werden die vor dem ersten der erwarteten Barcode-Typen dekodiert werden oder gleich nur die explizite Liste aller Barcode-Typen die erwartet werden.

Es ist zu beachten, dass 'UPC-A'"UPC-A""UPC-A""UPC-A""UPC-A""UPC-A" Codes dieselbe Struktur haben wie 'EAN-13'"EAN-13""EAN-13""EAN-13""EAN-13""EAN-13" Codes, nur dass sie immer mit einer Null beginnen. Will man explizit 'UPC-A'"UPC-A""UPC-A""UPC-A""UPC-A""UPC-A", '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 2" oder '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 5" Codes lesen, so müssen die entsprechenden EAN-13 Barcode-Typen ('EAN-13'"EAN-13""EAN-13""EAN-13""EAN-13""EAN-13" bzw. '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 2" bzw. '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 5") ausgeschlossen werden. Andernfalls werden die Ergebnisse aufgrund der Dekodierreihenfolge als EAN Codes zurückgegeben. Für UPC-A Codes mit Add-On muss neben dem entsprechenden EAN-13 Typ mit Add-On auch 'EAN-13'"EAN-13""EAN-13""EAN-13""EAN-13""EAN-13" ausgeschlossen werden.

Insbesondere für den Fall der Autodiskriminierung existiert der Operator set_bar_code_param_specificset_bar_code_param_specificSetBarCodeParamSpecificSetBarCodeParamSpecificSetBarCodeParamSpecificset_bar_code_param_specific. Einige Parameter des Barcode-Modells können damit spezifisch für verschiedene Barcode-Typen festgelegt werden.

Training

Falls sich der Barcode-Leser im Trainingsmodus befindet führt der Operator find_bar_codefind_bar_codeFindBarCodeFindBarCodeFindBarCodefind_bar_code einen Trainingslauf durch. Der Trainingsmodus ist bei dem Operator set_bar_code_paramset_bar_code_paramSetBarCodeParamSetBarCodeParamSetBarCodeParamset_bar_code_param beschrieben.

Timeout und Abbruch

Der Operator find_bar_codefind_bar_codeFindBarCodeFindBarCodeFindBarCodefind_bar_code kann sowohl mit einem Timeout sowie auch manuell abgebrochen werden. Mit dem Operator set_bar_code_paramset_bar_code_paramSetBarCodeParamSetBarCodeParamSetBarCodeParamset_bar_code_param kann man einen Timeout festlegen. Falls find_bar_codefind_bar_codeFindBarCodeFindBarCodeFindBarCodefind_bar_code in einen Timeout läuft, werden alle bis dahin erkannten Codes zurückgegeben. Zusätzlich gibt es die Möglichkeit find_bar_codefind_bar_codeFindBarCodeFindBarCodeFindBarCodefind_bar_code manuell abzubrechen, indem man set_bar_code_paramset_bar_code_paramSetBarCodeParamSetBarCodeParamSetBarCodeParamset_bar_code_param mit 'abort'"abort""abort""abort""abort""abort" von einem anderen Thread aufruft.

In beiden Fällen, kann mit get_bar_code_resultget_bar_code_resultGetBarCodeResultGetBarCodeResultGetBarCodeResultget_bar_code_result und dem Parameter 'aborted'"aborted""aborted""aborted""aborted""aborted" abgefragt werden, ob der Operator abgebrochen wurde.

Des Weiteren kann der Operator find_bar_codefind_bar_codeFindBarCodeFindBarCodeFindBarCodefind_bar_code mittels set_operator_timeoutset_operator_timeoutSetOperatorTimeoutSetOperatorTimeoutSetOperatorTimeoutset_operator_timeout oder interrupt_operatorinterrupt_operatorInterruptOperatorInterruptOperatorInterruptOperatorinterrupt_operator abgebrochen werden. Dabei werden keine Ergebnisse, aber eine Fehlermeldung zurückgegeben. Wenn find_bar_codefind_bar_codeFindBarCodeFindBarCodeFindBarCodefind_bar_code mit interrupt_operatorinterrupt_operatorInterruptOperatorInterruptOperatorInterruptOperatorinterrupt_operator abgebrochen wurde, wird H_ERR_CANCEL (22) zurückgegeben. Wenn find_bar_codefind_bar_codeFindBarCodeFindBarCodeFindBarCodefind_bar_code mit set_operator_timeoutset_operator_timeoutSetOperatorTimeoutSetOperatorTimeoutSetOperatorTimeoutset_operator_timeout abgebrochen wurde, wird H_ERR_TIMEOUT (9400) zurückgegeben. Das Abbrechen durch einen dieser Operatoren wird nur im 'cancel'"cancel""cancel""cancel""cancel""cancel"-Modus unterstützt.

Hinweise zur Verwendung von niedrig aufgelösten Bildern

Dieser Hinweis betrifft Barcode-Anwendungen, in denen niedrig aufgelöste Bilder verwendet werden, d.h. Bilder in denen ein einzelner Strich des Barcodes nur zwischen 0.6 und 2 Pixeln breit ist.

In diesen Fällen sollte man bei der Bildaufnahme darauf achten, dass die Bilder möglichst scharf sind und gleichzeitig möglichst wenig Rauschen enthalten, da diese Fehler zu Problemen bei der Dekodierung von niedrig aufgelösten Barcodes führen können. Im Abschnitt 'small_elements_robustness'"small_elements_robustness""small_elements_robustness""small_elements_robustness""small_elements_robustness""small_elements_robustness" des Operators set_bar_code_paramset_bar_code_paramSetBarCodeParamSetBarCodeParamSetBarCodeParamset_bar_code_param finden sich weitere wichtige Hinweise.

Ausführungsinformationen

• Multithreading-Typ: reentrant (läuft parallel zu nicht-exklusiven Operatoren).
• Multithreading-Bereich: global (kann von jedem Thread aufgerufen werden).
• Automatisch parallelisiert auf interner Datenebene.

Dieser Operator unterstützt Cancel-Timeouts und Interrupts.

Dieser Operator modifiziert den Zustand des folgenden Eingabeparameters:

• BarCodeHandleBarCodeHandleBarCodeHandleBarCodeHandlebarCodeHandlebar_code_handle

Während der Ausführung dieses Operators muss der Zugriff auf den Wert dieses Parameters synchronisiert werden, wenn er über mehrere Threads hinweg verwendet wird.

Parameter

Beispiel (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)

Ergebnis

find_bar_codefind_bar_codeFindBarCodeFindBarCodeFindBarCodefind_bar_code liefert den Wert 2 (H_MSG_TRUE), falls die übergebenen Parameter korrekt sind. Ansonsten wird eine Fehlerbehandlung durchgeführt.

Vorgänger

create_bar_code_modelcreate_bar_code_modelCreateBarCodeModelCreateBarCodeModelCreateBarCodeModelcreate_bar_code_model, set_bar_code_paramset_bar_code_paramSetBarCodeParamSetBarCodeParamSetBarCodeParamset_bar_code_param

Nachfolger

get_bar_code_resultget_bar_code_resultGetBarCodeResultGetBarCodeResultGetBarCodeResultget_bar_code_result, get_bar_code_objectget_bar_code_objectGetBarCodeObjectGetBarCodeObjectGetBarCodeObjectget_bar_code_object, clear_bar_code_modelclear_bar_code_modelClearBarCodeModelClearBarCodeModelClearBarCodeModelclear_bar_code_model

Alternativen

decode_bar_code_rectangle2decode_bar_code_rectangle2DecodeBarCodeRectangle2DecodeBarCodeRectangle2DecodeBarCodeRectangle2decode_bar_code_rectangle2

Modul

Bar Code