find_bar_code — Suchen und Lesen von Barcode-Symbolen im Eingabebild.
find_bar_code(Image : SymbolRegions : BarCodeHandle, CodeType : DecodedDataStrings)
Der Operator find_bar_code sucht im Eingabebild (Image)
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
CodeType ausgewählt wird. Die gelesenen Zeichenfolgen werden
in DecodedDataStrings und die dazu korrespondierenden
Barcode-Regionen in SymbolRegions 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_result und
get_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_image
invertiert werden.
Vor dem Aufruf des Operators find_bar_code muss mit Hilfe von
create_bar_code_model ein Barcode-Modell erstellt und der dabei
erzeugte Handle in BarCodeHandle an find_bar_code
übergeben werden.
Der Ausgabewert DecodedDataStrings 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
DecodedDataStrings 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' ab, welcher in
create_bar_code_model, set_bar_code_param oder
set_bar_code_param_specific einstellbar ist:
Der Standardwert von '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' 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
DecodedDataStrings und SymbolRegions zurückgeliefert.
Das Prüfzeichen selbst wird aus den Nutzdaten entfernt. Falls dies nicht
erwünscht ist, kann der Parameterwert '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_result
und 'decoded_reference' abgefragt werden.
Folgende Barcode-Symbole werden unterstützt:
| 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 |
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_param der Parameter
'composite_code' auf 'CC-A/B' gesetzt werden.
Es können auch Barcodes vom Typ 'Code 32' gelesen werden, indem der
Operator find_bar_code mit CodeType 'Code 39'
in Kombination mit der externen Prozedur
convert_decoded_string_code39_to_code32 verwendet wird.
Autodiskriminierung
Autodiskriminierung beschreibt das gleichzeitige Lesen mehrerer
Barcode-Typen in einem Aufruf von find_bar_code. Dazu wird dem
Parameter CodeType ein Tupel von möglichen Barcode-Typen übergeben.
Mit dem speziellen Wert 'auto' werden alle Barcode-Typen dekodiert,
mit Ausnahme von 'PharmaCode' und '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']
alle Barcode-Typen ohne 'PharmaCode', 'MSI' und
'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 Truncated', 'GS1 DataBar Stacked', 'GS1 DataBar Stacked Omnidir', 'GS1 DataBar Limited', 'GS1 DataBar Expanded', 'GS1 DataBar Expanded Stacked', 'GS1-128', 'Code 128', 'EAN-13 Add-On 5', 'EAN-13 Add-On 2', 'EAN-13', 'UPC-A Add-On 5', 'UPC-A Add-On 2', 'UPC-A', 'EAN-8 Add-On 5', 'EAN-8 Add-On 2', 'EAN-8', 'UPC-E Add-On 5', 'UPC-E Add-On 2', 'UPC-E', 'Code 93', 'Code 39', 'Codabar', '2/5 Interleaved', '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.
Insbesondere für den Fall der Autodiskriminierung existiert der Operator
set_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_code einen Trainingslauf durch. Der Trainingmodus
ist bei dem Operator set_bar_code_param beschrieben.
Timeout und Abbruch
Der Operator find_bar_code kann sowohl mit einem Timeout sowie auch
manuell abgebrochen werden. Mit dem Operator set_bar_code_param kann
man einen Timeout festlegen. Falls find_bar_code in einen Timeout läuft,
werden alle bis dahin erkannten Codes zurückgegeben. Zusätzlich gibt es die
Möglichkeit find_bar_code manuell abzubrechen, indem man
set_bar_code_param mit 'abort' von einem anderen Thread aufruft.
In beiden Fällen, kann mit get_bar_code_result und dem Parameter
'aborted' abgefragt werden, ob der Operator abgebrochen wurde.
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 ein und zwei 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.
Dieser Operator modifiziert den Zustand des folgenden Eingabeparameters:
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.
Image (input_object) singlechannelimage → object (byte / uint2)
Eingabebild. Falls das Bild eine reduzierte Domäne besitzen sollte, so wird der Bereich eingeschränkt in dem nach Barcodes gesucht wird. In der Regel führt dies zu einer Verbesserung der Laufzeit. Allerdings sollte man beachten, dass ein Barcode nicht mehr gefunden wird könnte, wenn er nicht vollständig in der Domäne des Bildes liegt.
SymbolRegions (output_object) region(-array) → object
Regionen der erfolgreich dekodierten Barcode-Symbole.
BarCodeHandle (input_control, Zustand wird modifiziert) barcode → (handle)
Handle des zu verwendenden Barcode-Modells.
CodeType (input_control) string(-array) → (string)
Typ des zu findenden Barcodes.
Defaultwert: 'auto'
Werteliste: '2/5 Industrial', '2/5 Interleaved', 'Codabar', 'Code 128', 'Code 39', 'Code 93', 'EAN-13 Add-On 2', 'EAN-13 Add-On 5', 'EAN-13', 'EAN-8 Add-On 2', 'EAN-8 Add-On 5', 'EAN-8', 'GS1 DataBar Expanded Stacked', 'GS1 DataBar Expanded', 'GS1 DataBar Limited', 'GS1 DataBar Omnidir', 'GS1 DataBar Stacked Omnidir', 'GS1 DataBar Stacked', 'GS1 DataBar Truncated', 'GS1-128', 'MSI', 'PharmaCode', 'UPC-A Add-On 2', 'UPC-A Add-On 5', 'UPC-A', 'UPC-E Add-On 2', 'UPC-E Add-On 5', 'UPC-E', 'auto'
DecodedDataStrings (output_control) string(-array) → (string)
Die Datenstrings der erfolgreich dekodierten Barcodes.
* 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)
find_bar_code liefert den Wert 2 (H_MSG_TRUE), falls die
übergebenen Parameter korrekt sind.
Ansonsten wird eine Fehlerbehandlung durchgeführt.
create_bar_code_model,
set_bar_code_param
get_bar_code_result,
get_bar_code_object,
clear_bar_code_model
Bar Code