set_bar_code_param — Setzen ausgewählter Parameter des Barcode-Modells.
set_bar_code_param( : : BarCodeHandle, GenParamName, GenParamValue : )
Der Operator set_bar_code_param erlaubt es, Parameter,
welche Eigenschaften des Barcodes beschreiben oder das Verhalten
des Modells bei der Symbolsuche steuern, zu verändern.
Damit kann auf Besonderheiten des Barcodes oder dessen Abbildung
durch den Bildsensor eingegangen werden.
Alle Parameter können auch direkt beim Anlegen des Modells
mit create_bar_code_model übergeben werden.
Die aktuelle Konfiguration kann mit Hilfe von
get_bar_code_param ausgelesen werden.
Es folgt eine Übersicht über die verschiedenen generischen Parameter mit den jeweiligen Wertebereichen und Defaultwerten:
Größe der Barcode Elemente:
Die beiden ersten Parameter, 'element_size_min' und 'element_size_max', beeinflussen die Suche nach Kandidatenregionen und die Dekodierung der Barcodes. Sie werden aber nicht strikt als Grenzen für die Größe der Elemente gefundener Barcodes verwendet. D.h. es können auch Barcodes gefunden werden, deren Elemente schmaler als 'element_size_min' oder breiter als 'element_size_max' sind.
Achtung: Beim Ändern der Größe über den Operator
set_bar_code_param, werden die Parameterwerte
'element_size_min' und 'element_size_max' auf Konsistenz
überprüft. Die beiden Parameter sollten im gleichen Aufruf gesetzt werden.
Die minimale Größe eines Basiselements (auch als 'Modul' oder 'narrow bar'
bezeichnet, je nach Barcodetyp), d.h. die minimale Dicke der schmalsten
Striche und Zwischenräume des speziellen Barcodetyps. Der Wert dieses
Parameters ist in Pixel definiert. Für Barcodes mit niedriger Auflösung
sollte der Wert auf 1.5 reduziert werden, ggf. sogar auf bis zu
0.6. Falls der Wert unter 2.0 gesetzt wird, wird ein
zusätzlicher Dekodierversuch unternommen, der im Abschnitt über
'small_elements_robustness' des Operators
set_bar_code_param beschrieben wird. Für sehr große Barcodes
kann der Wert entsprechend vergrößert werden, was
kürzere Laufzeiten mit sich bringt.
Typischer Wertebereich: [1.2, .., 10.0]
Wertebereich: [0.6, .., 64]
Standardwert: 2.0
Die maximale Größe eines Basiselements (auch als 'Modul' oder 'narrow bar' bezeichnet, je nach Barcodetyp), d.h. die maximale Dicke der schmalsten Striche und Zwischenräume des speziellen Barcodetyps. Der Wert dieses Parameters ist in Pixel definiert. Er sollte groß genug sein, damit für das komplette Symbol die Kandidatenregion gefunden wird. Anderseits darf er nicht so groß gewählt werden, dass zwei benachbarte Barcodes zu einem einzelnen Kandidaten verschmelzen.
Typischer Wertebereich: [4.0, .., 60.0]
Wertebereich: [1, .., 256]
Standardwert: 8.0
In manchen Barcodeaufnahmen variiert die Breite des kleinsten Elements über den Bereich des Barcodes. Diese Veränderungen entstehen durch perspektivische Projektion oder durch Deformation der Oberfläche, auf welcher der Barcode gedruckt ist (z.B. eine Tonnenverzerrung auf einer Flasche). Standardmäßig kann der Barcodeleser solche Verzerrungen nicht ausgleichen. Sollte die Einstellung 'element_size_variable' auf 'true' gesetzt sein, wird versucht, solche Deformationen lokal bei der Dekodierung auszugleichen. Dies kann dazu führen, dass Barcodes auch unter solchen Bedingungen gelesen werden können. Man beachte, dass nicht alle Deformationen ausgeglichen werden können.
Der Parameter 'element_size_variable' ist nur für folgende Barcodetypen implementiert:
GS1 DataBar Limited
GS1 DataBar Expanded
GS1 DataBar Expanded Stacked
Bei anderen Barcodetypen hat dieser Parameter keinen Effekt.
Werte: ['false', 'true']
Standardwert: 'false'
Die minimale Höhe des Barcodes. Der Wert dieses Parameters ist in Pixel definiert. Die Voreinstellung mit -1 bedeutet, dass intern die Höhe des Barcodes automatisch entsprechend den anderen Einstellung gewählt wird. Bei sehr flachen Barcodes mit einer Höhe von weniger als 16 Pixeln ist es sinnvoll die Höhe manuell einzustellen, damit der Barcode gefunden und gelesen werden kann. Die minimale Höhe beträgt 8 Pixel. Bei sehr hohen Barcodes, z.B. mit 70 Pixeln und mehr, kann das manuelle Setzen auf die entsprechende Höhe zu einer Beschleunigung beim Lesen führen.
Typischer Wertebereich: [-1, 8, .., 64]
Standardwert: -1
Die minimale Breite des Barcodes im Bild. Der Wert dieses Parameters ist in Pixel definiert. Die Breite eines Barcodes hängt von mehreren Faktoren ab:
Auflösung der Kamera
Entfernung zwischen Barcode und Kamera
Barcode-Typ
Anzahl kodierter Zeichen
Falls diese Eigenschaften in einer Anwendung nahezu unverändert bleiben, sollte dieser Parameter gesetzt werden, um die Geschwindigkeit und Robustheit des Barcode-Lesers zu erhöhen. Der Standardwert von -1 bedeutet, dass der Barcode-Leser einen geeigneten Minimalwert anhand der gesuchten Barcode-Typen und des Parameters 'element_size_min' schätzt.
Typischer Wertebereich: [-1, 40, 50, 60, ...]
Standardwert: -1
Die maximale Breite des Barcodes im Bild. Der Wert dieses Parameters ist in Pixel definiert. Die Breite eines Barcodes hängt von mehreren Faktoren ab:
Auflösung der Kamera
Entfernung zwischen Barcode und Kamera
Barcode-Typ
Anzahl kodierter Zeichen
Dieser Parameter kann die Robustheit bei bekannter maximaler Breite der zu lesenden Barcodes erhöhen. Insbesondere kann das Verschmelzen von nahe beieinanderliegenden Barcodes zuverlässig vermieden werden. Im Allgemeinen sollte das Setzen dieses Parameters nur in Ausnahmefällen notwendig sein. Für den Standardwert von -1 wird die maximale Barcode Breite nicht eingeschränkt.
Typischer Wertebereich: [-1, 300, 400, 500, ...]
Standardwert: -1
Scanparameter:
Die maximale Anzahl von Scanlinien, die während des Scannens eines
(Kandidat-)Symbols benutzt werden.
Wenn 'num_scanlines' nicht gesetzt
ist (der Parameter hat einen Wert von 0), wird die Anzahl
der Scanlinien nach einer internen Regel bestimmt: 10 für
alle einzeiligen Barcodes, 20 für GS1 DataBar Stacked
beziehungsweise GS1 DataBar Stacked Omnidirectional und 55
für GS1 DataBar Expanded Stacked.
Durch diesen Parameter kann die Geschwindigkeit in zwei Fällen
gesteigert werden. Im ersten Fall beinhaltet das Bild viele
falsche Kandidaten. Während der Barcode selbst normalerweise
nach ein oder zwei Scanvorgängen dekodiert werden kann (außer
gestapelte Barcodes, siehe unten), wird ein falscher
Kandidat mit dem Defaultwert von 10 Scanlinien gescannt, was die
Laufzeit unnötig verlängert. Folglich kann die Geschwindigkeit durch
eine reduzierte Anzahl der Scanlinien erhöht werden. Generell lässt
sich sagen, dass Bilder höherer Qualität weniger Scanlinien benötigen
als Bilder von niedrigerer Qualität. Für ein durchschnittliches Bild
sollte ein Wert zwischen 2 und 5 ausreichend sein. Sollte ein Barcode
jedoch nach Verringerung der Scanlinien nicht mehr gefunden werden, so
muss die Anzahl der Scanlinien wieder erhöht werden.
Der zweite Fall betrifft gestapelte Barcodes (derzeit GS1 DataBar
Stacked, GS1 DataBar Stacked Omnidirectional und GS1 DataBar Expanded
Stacked). Hier werden alle Scanlinien bewertet - im Gegensatz zu
einzeiligen Barcodes (z.B. Code 128, EAN 13 oder GS1 DataBar Limited),
wo das Scannen nach erfolgreicher Dekodierung des Codes beendet wird.
Der Scanvorgang ist eine der zeitaufwändigsten Phasen des Operators
find_bar_code. Deswegen kann die Anpassung des Parameters
'num_scanlines' große Geschwindigkeitsvorteile bringen.
Das gilt insbesondere für GS1 DataBar Expanded Stacked. Ein GS1 DataBar
Expanded Stacked Symbol kann in der Regel aus bis zu 11 Zeilen bestehen.
Damit jede Zeile robust von jeweils 5 Scanlinien gelesen wird, sind
im Operator 55 Scanlinien für den allgemeinen Fall vorgesehen.
Wenn nur Symbole mit geringer Zeilenanzahl zu erwarten sind, sollte
'num_scanlines' auf 1.5 bis 5 Scanlinien pro erwartete Zeile
reduziert werden.
Falls dieser Parameter auf einen Wert gesetzt wird, der kleiner ist als die Einstellung für den Parameter 'min_identical_scanlines', so wird der Wert für 'min_identical_scanlines' automatisch auf den Wert von 'num_scanlines' reduziert.
Dieser Parameter kann mit dem Operator
set_bar_code_param_specific spezifisch für unterschiedliche
Barcodetypen gesetzt werden.
Typische Werte: [0, 5, 10, 20, ...]
Standardwert: 0
Mit diesem Parameter lässt sich die Wahrscheinlichkeit verringern, dass Barcodes falsch gelesen werden oder an Stellen gefunden werden, die keine Barcodes darstellen. Der Parameter legt die minimale Anzahl von Scanlinien fest, welche identische Ergebnisse liefern müssen, damit die Dekodierung eines Symbols akzeptiert wird.
Wenn 'min_identical_scanlines' auf den Wert 0 gesetzt ist (welches der Standardwert für alle Barcodetypen außer '2/5 Industrial' und '2/5 Interleaved' ist), wird der Barcode dekodiert, sobald eine Scanlinie erfolgreich dekodiert wurde. Falls die Einstellung 'majority_voting' aktiviert ist, wird ein anderes Verfahren angewandt (siehe Abschnitt über 'majority_voting'). Analog hierzu reicht bei gestapelten Barcodes eine erfolgreich dekodierte Scanlinie pro Barcodezeile. Dieser Parameter kann auf 2 oder höher gesetzt werden, um zu verhindern, dass Barcodes unbeabsichtigt gefunden werden. Dies kann insbesondere dann hilfreich sein, wenn schlechte Bildqualität oder verrauschte Bildregionen dazu führen, dass eine Scanlinie falsche Strichkanten findet. Dieser Parameter kann auch die Anzahl falsch gefundener Barcodes in Bildern verringern, in welchen Symbole unterschiedlichen Barcodetyps gleichzeitig erscheinen.
Man beachte, dass der Standardwert für diesen Parameter für die meisten Barcodetypen 0 ist. Lediglich ist der Standardwert 2 für die Barcodetypen '2/5 Industrial' und '2/5 Interleaved'. Der Grund dafür ist, dass diese Barcodetypen leicht fälschlicher Weise in Text und anderen Störmustern erkannt werden, wenn der Parameter 'min_identical_scanlines' auf 0 oder 1 gesetzt ist.
Dieser Parameter kann mit dem Operator
set_bar_code_param_specific spezifisch für unterschiedliche
Barcodetypen gesetzt werden.
Wenn vereinigte Scanlinien (siehe 'merge_scanlines')verwendet
werden, drückt 'min_identical_scanlines' aus, in wie vielen
Scanlinien eine Kante erfolgreich erkannt werden muss (siehe
get_bar_code_object, 'scanlines_merged_edges').
Typische Werte: [0, 2, 3, ...]
Standardwert:| Barcodetyp | min_identical_scanlines |
|---|---|
| 2/5 Industrial | 2 |
| 2/5 Interleaved | 2 |
| alle Anderen | 0 |
Dieser Parameter steuert das Verhalten bei der Auswahl unterschiedlicher Dekodierergebnisse pro Scanlinie. Falls der Parameter auf 'false' gesetzt ist, wird ein erfolgreiches Dekodierergebnis zurückgegeben, sobald eine minimale Anzahl an identisch dekodierten Scanlinien gefunden wurde (siehe Abschnitt über 'min_identical_scanlines' für weitere Details). Setzt man diesen Parameter auf 'true', so wird ein Mehrheitsvotum unter Einbeziehung aller Scanlinien durchgeführt. Das zurückgegebene Endergebnis wird dann jenes sein, welches von den meisten Scanlinien dekodiert wurde. Man beachte, dass die Einstellung 'true' zu leicht erhöhten Laufzeiten führt, denn es müssen fast alle Scanlinien ausgewertet werden anstatt nur die minimal identischen Scanlinien.
Um die Robustheit gegenüber falschen Dekodierungen zu erhöhen, sollte dieser Parameter auf 'true' gesetzt werden.
Dieser Parameter wird nur für Barcodetypen unterstützt, die nicht gestapelt sind.
Werte: ['false', 'true']
Standardwert: 'false'
Anzahl erfolgreich dekodierter Barcodes nach der die Dekodierung angehalten wird. Falls dieser Parameter nicht gesetzt ist (der Parameter hat einen Wert von 0), wird versucht alle Kandidaten zu dekodieren. Dieser Parameter wird typischerweise gesetzt, wenn die erwartete Anzahl von Barcodes im Voraus bekannt ist. Dann kann der Barcode-Leser die weitere Dekodierung von Kandidaten abbrechen und die Gesamtdekodierzeit wird reduziert.
Dieser Parameter kann mit dem Operator
set_bar_code_param_specific spezifisch für unterschiedliche
Barcodetypen gesetzt werden.
Typische Werte: [0, 1, 2, ...]
Standardwert: 0
Erwarteter Barcode Orientierungswinkel.
Ein potentieller (Kandidat-) Barcode hat Striche ähnlicher
Orientierung. Man kann die Parameter 'orientation' und
'orientation_tol' anpassen, um den Wertebereich
['orientation'-'orientation_tol',
'orientation'+'orientation_tol'] zu definieren.
find_bar_code bearbeitet nur Kandidatenregionen, deren Striche
einen durchschnittlichen Orientierungswinkel haben, der in dem obigen
Wertebereich liegt. Falls die Barcodes nur mit einer bestimmter
Orientierung in den bearbeiteten Bildern erscheinen, so kann man den
Wertebereich entsprechend reduzieren, sodass falsche Kandidaten früher
erkannt werden und sich so die Ausführungszeit des Operator verkürzt.
Diese Strategie bringt vor allem dann Vorteile, wenn die bearbeiteten
Bilder viel
Hintergrundtextur mit falsch orientierten Kandidaten enthalten.
Ausführlichere Informationen zu dem Orientierungswinkel können beim
Operator get_bar_code_result(...,'orientation',...)
nachgelesen werden. Im Gegensatz zu get_bar_code_result, wird
hier die eigentliche Leserichtung nicht berücksichtigt, und es sind
deswegen nur Winkel in dem Wertebereich [-90.0 ...
90.0] von Interesse. Die einzige Ausnahme dazu sind
Barcodes vom Typ PharmaCode, welche keine eindeutige Leserichtung haben
und somit auch in der Regel zwei dekodierte Ergebnisse zurückliefern:
mit einem Wertebereich von [-180.0 ...
180.0] kann eine spezielle Leserichtung und damit auch ein
einzelnes Ergebnis gewählt werden.
Dieser Parameter kann mit dem Operator
set_bar_code_param_specific spezifisch für unterschiedliche
Barcodetypen gesetzt werden.
Typischer Wertebereich: [-90.0, ..., 90.0]
Standardwert: 0.0
Toleranz der Orientierung. Siehe 'orientation' für weitere Erklärungen. Wie bereits erklärt wurde, ist nur der Wertebereich [-90.0 ... 90.0] berücksichtigt, was mit einem 'orientation_tol' von 90.0 ganz abgedeckt wird. Deswegen sind die Werte von 'orientation_tol' auf den Wertebereich [0.0 ... 90.0] eingeschränkt. Dabei stellt ein Wert von 90.0 die Orientierungsbeschränkung grundsätzlich aus.
Dieser Parameter kann mit dem Operator
set_bar_code_param_specific spezifisch für unterschiedliche
Barcodetypen gesetzt werden.
Typischer Wertebereich: [0.0, ..., 90.0]
Standardwert: 90.0
Steuert die Verifikation der Ruhezonen eines Barcodesymbols. Wenn diese eingeschaltet ist, werden Scanlinien verworfen, falls unerwartete Striche in den Ruhezonen gefunden werden.
Mögliche Werte:
'false': Die Verifikation ist ausgeschaltet.
'true': Die Ruhezonen müssen mindestens so breit sein, wie in der entsprechenden Barcode-Norm festgesetzt ist. Diese Werte (in X-Einheiten, wobei X eine "Modulbreite" bezeichnet, d.h. die Breite des schmalsten Striches aus der Strichsequenz des Barcodes) können von der folgenden Tabelle entnommen werden:
| Barcodetyp | Linke RZ | Rechte RZ | Barcodetyp | Linke RZ | Rechte RZ |
|---|---|---|---|---|---|
| 2/5 Industrial | 10 | 10 | UPC-A | 9 | 9 |
| 2/5 Interleaved | 10 | 10 | UPC-A Add-On 2 | 9 | 5 |
| Codabar | 10 | 10 | UPC-A Add-On 5 | 9 | 5 |
| Code 39 | 10 | 10 | UPC-E | 9 | 7 |
| Code 93 | 10 | 10 | UPC-E Add-On 2 | 9 | 5 |
| Code 128 | 10 | 10 | UPC-E Add-On 5 | 9 | 5 |
| MSI | 10 | 10 | GS1-128 | 10 | 10 |
| PharmaCode | 5 | 5 | GS1 DataBar Omnidir | 1 | 1 |
| EAN-8 | 7 | 7 | GS1 DataBar Truncated | 1 | 1 |
| EAN-8 Add-On 2 | 7 | 5 | GS1 DataBar Stacked | 1 | 1 |
| EAN-8 Add-On 5 | 7 | 5 | GS1 DataBar Stacked Omnidir | 1 | 1 |
| EAN-13 | 11 | 7 | GS1 DataBar Limited | 1 | 5 |
| EAN-13 Add-On 2 | 11 | 5 | GS1 DataBar Expanded | 1 | 1 |
| EAN-13 Add-On 5 | 11 | 5 | GS1 DataBar Expanded Stacked | 1 | 1 |
Ganzzahl (>= 1): Die Ruhezonen müssen mindestens 'quiet_zone' x X breit sein.
'tolerant': Eine beschränkte Anzahl an Kanten in der Ruhezone ist erlaubt, aber höchstens eine pro vier Modulbreiten. Das Ziel ist zu verhindern, nur einen Teil von einem Barcode zu erkennen, aber dennoch Codes mit einer einfachen Verletzung der Ruhezone noch lesen zu können.
Zu beachten: Auch für Codetypen mit einer vorgeschriebenen Ruhezone von weniger als vier Modulbreiten werden die Kanten innerhalb eines Bereichs von vier Modulbreiten um den Code überprüft. In diesem Fall kann dieses Kriterium also strenger sein als die Überprüfung mit 'quiet_zone'='true'.
Die Verifikation der Ruhezonen ist insbesondere für das Lesen von Barcodes im 'auto'-Modus wichtig. Sie verhindert, dass einfache Barcodes innerhalb einer Strichsequenz eines längeren und/oder komplexeren Barcodes gefunden werden. Normalerweise liefern Werte zwischen 2 und 4 optimale Ergebnisse, weil dadurch falsche Barcodes unterdrückt werden, während kleine Störungen wie Text, Etikettenkanten, etc. immer noch toleriert werden.
Dieser Parameter kann mit dem Operator
set_bar_code_param_specific spezifisch für unterschiedliche
Barcodetypen gesetzt werden.
Zu beachten: Die Ruhezonen dienen zur Überprüfung, dass innerhalb dieser Zone keine anderen Striche findbar sind, es ist jedoch nicht notwendig, dass sie als Ganzes auf dem Bild gefunden werden müssen. Dies bedeutet, falls eine gesetzte Ruhezone nicht als Ganzes auf dem Bild enthalten ist, wird nur der Teil im Bild überprüft während der Teil außerhalb des Bildes als störungsfrei angenommen wird.
Werte: 'false', 'true', 'tolerant', 1, ..., 100
Standardwert: 'false'
Fordert ein tolerantes ('high') oder ein strenges ('low') Matchingkriterium bei der Suche nach Start-, bzw. Stoppmuster in einer Scanlinie. Ein tolerantes Kriterium erhöht die allgemeine Leserate, insbesondere in Bildern mit schlechtem Kontrast. Anderseits kann diese Einstellung zu ungültigen Dekodierungen in verrauschten Bildern, oder in Bildern mit Symbolen anderer Barcodetyps führen. Ein strenges Kriterium erhöht die Robustheit gegenüber falscher Dekodierung, kann aber auch die allgemeine Leserate mindern. Es ist zu beachten, dass momentan zwei unterschiedliche Kriterien nur für Code 128 und GS1-128 implementiert sind.
Dieser Parameter kann mit dem Operator
set_bar_code_param_specific spezifisch für unterschiedliche
Barcodetypen gesetzt werden. Obwohl man diesen Parameter für alle
Barcodetypen setzen kann, hat er derzeit, wie bereits erwähnt,
nur Wirkung auf Code 128 und GS1-128.
Werte: ['high', 'low']
Standardwert: 'high'
Minimale Anzahl dekodierter Zeichen. Falls ein Barcode gefunden wird,
dessen Länge geringer ist als der Wert der für den Parameter
'min_code_length' angegeben ist, so wird das Resultat verworfen
und nicht von find_bar_code oder
decode_bar_code_rectangle2 zurückgegeben. Dieser Parameter ist
hilfreich um falsches Dekodieren in Anwendungen zu vermeiden in denen die
minimale Anzahl zu dekodierender Zeichen im Voraus bekannt ist.
Man beachte, dass der Standardwert für diesen Parameter für die meisten Barcodetypen 0 ist. Lediglich für die Barcodetypen '2/5 Industrial' und '2/5 Interleaved' ist der Standardwert 3. Der Grund dafür ist, dass diese Barcodetypen leicht fälschlicher Weise in Text und anderen Störmustern mit einer Länge von 2 Zeichen erkannt werden.
Wertevorschläge: [0, 1, 2, ...]
Standardwert:| Barcodetyp | min_code_length |
|---|---|
| 2/5 Industrial | 3 |
| 2/5 Interleaved | 3 |
| alle Anderen | 0 |
Wenn nicht genug Scanlinien (siehe 'min_identical_scanlines') erfolgreich dekodiert werden können, beispielsweise weil der Barcode teilweise verdeckt oder beschädigt ist, wird versucht, die vorhandenen Scanlinien zu vereinigen. Anschließend wird versucht, die vereinigten Scanlinien zu dekodieren. Dieser zusätzliche Dekodierschritt wird nur für Barcodetypen durchgeführt, die nicht gestapelt sind und kann für eine verbesserte Geschwindigkeit ausgeschaltet werden.
Werte: ['true', 'false']
Standardwert: 'true'
Wenn nicht genug Scanlinien (siehe 'min_identical_scanlines') erfolgreich dekodiert werden können, beispielsweise weil der Barcode eine geringe Auflösung hat (kleiner als 2.0 Pixel Elementgröße) wird ein zusätzlicher Dekodierversuch unternommen.
Dieser zusätzliche Dekodierschritt wird nur für Barcodetypen durchgeführt, die nicht gestapelt sind und falls der Parameter 'element_size_min' kleiner als 2.0 Pixel gesetzt ist.
Zusätzliche Informationen zu diesem Dekodierversuch können über den
Operator get_bar_code_result abgefragt werden, indem
'status_small_elements_robustness' für den Parameter
ResultName gesetzt wird.
Für Anwendungsfälle mit sehr kleinen Elementen (kleiner als 1.3 Pixel) ist es von Vorteil, wenn der Kamerasensor in Bezug auf den Barcode leicht rotiert ist (z.B. um 7 Grad). In dieser niedrigen Auflösung sind wichtige Informationen über den Barcode nur dann über die Zeilen oder Spalten des Sensors verteilt, wenn er rotiert ist. Die beiden folgenden Abbildungen zeigen diesen Zusammenhang.
Ein weiterer wichtiger Hinweis ist, dass die Unschärfe durch das optische System möglichst gering gehalten werden muss.
Das Eingabebild sollte nicht vorverarbeitet werden (z.B. über Operatoren
wie emphasize, zoom_image_size oder mean_image), da
sonst wichtige Informationen verloren gehen würden.
Man beachte, dass es unter optimalen Bedingungen (wenig Unschärfe und leichte Rotation des Sensors) möglich ist, Barcodes mit bis zu 0.6 Pixel Elementgröße zu dekodieren.
Der zusätzliche Dekodierversuch ist nur kompatibel mit Byte-Bildern als Eingabe und kann für eine verbesserte Geschwindigkeit ausgeschaltet werden.
Werte: ['true', 'false']
Standardwert: 'true'
Erscheinungsbild der Module im Bild:
Innerhalb einer Scanlinie werden Kanten mit Hilfe eines Schwellenwerts gefunden. 'meas_thresh' bestimmt, wie dieser Schwellenwert relativ zum Dynamikbereich der Grauwerte entlang der Scanlinie berechnet wird. Liegen in dem Barcode Störungen vor oder ist das Rauschen groß, so sollte 'meas_thresh' auf größere Werte gesetzt werden.
Typischer Wertebereich: [0.05 .. 0.2]
Werte: (0.0, .., 1.0] - ohne 0.0
Standardwert: 0.05
Der Parameter 'meas_thresh_abs' wird benutzt, um die falsche Kantendetektion zu verhindern. Sollte eine Scanlinie in eine Bildregion mit zu kleinem Dynamikbereich geraten (z.B. eine überwiegend weiße Region mit Grauwerten nahe 255), wird der Schwellenwert zum Kantendetektion unangemessen klein berechnet. Das führt des Öfteren zur Detektion großer Mengen falscher Kanten. Falls der Schwellenwert, der auf dem Parameter 'meas_thresh' basiert, kleiner als der Wert des Parameters 'meas_thresh_abs' wird, wird der letztere Wert als Schwellenwert genommen. Standardmäßig ist 'meas_thresh_abs' auf 5.0 gesetzt. Sollten Bilder mit höherem Rauschpegel behandelt werden, könnte ein Erhöhen des Parameterwertes nützlich sein. Anderseits, wenn rauschfreie Bilder mit niedrigem Kontrast behandelt werden, könnte dieser Parameter die Detektion richtiger Kanten stören. In solchen Fällen ist es empfehlenswert, den Parameterwert zu mindern oder den Parameter sogar zu deaktivieren (auf 0.0 setzen).
Typischer Wertebereich: [0.0, .., 10.0]
Werte: [0.0, .., 65535]
Standardwert: 5.0
Minimaler Kontrast zwischen dem Vorder- und Hintergrund der
Barcode-Elemente. Wird dieser Parameter auf Werte über 5 gesetzt,
optimiert der Operator find_bar_code die Kandidatensuche auf den
Kontrastbereich oberhalb des 'contrast_min' Wertes.
find_bar_code wird dann alle Kandidaten verwerfen, die einen
Kontrast unterhalb des Schwellenwertes 'contrast_min' besitzen.
Hohe 'contrast_min' Werte führen daher in der Regel zu einer
verbesserten Laufzeit des Operators find_bar_code. Es ist zu
beachten, dass Barcodes mit einem geringeren Kontrast als dem
Schwellenwert 'contrast_min' nicht gefunden werden. Aus
Effizienzgründen ist der berechnete Kontrast eines Kandidaten nur eine
Approximation. Es sollte ein niedrigeren Schwellenwert verwendet werden, falls
ein Barcode verworfen wird und dieser einen Kontrast besitzt, der nahe an
dem gewählten Schwellenwert 'contrast_min' liegt.
Typische Werte: [0, 40, 90, 120, ... ]
Standardwert: 0
Druckqualität spezifische Größen:
Die Reflektanzwerte, die zur Berechnung der Qualitätswerte Symbol Contrast, Minimal Reflectance und Minimal Edge Contrast verwendet werden, werden mit einem Referenzgrauwert für die Reflektanz normiert. Dieser kann unter anderem durch die Aufnahme eines Bariumsulfat oder Magnesiumoxid Musters bestimmt werden, siehe ISO/IEC 15416:2016 Abschnitt 5.2. Wertebereich: [1 .. 255]
Standardwert: 255
Symbol spezifische Größen:
Barcodes mit optionalem Prüfzeichen werden anhand dieses Parameters interpretiert. Darunter fallen z.B. Code 39, Codabar, 2/5 Industrial und 2/5 Interleaved. 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 korrekt, so wird das Prüfzeichen aus den Nutzdaten entfernt. Falls dieses Entfernen nicht erwünscht ist, kann der Parameterwert 'preserved' eingestellt werden um das Prüfzeichen trotz Prüfung zu erhalten. Ist die Prüfsumme jedoch fehlerhaft, so wird der entsprechende Barcode nicht als Ergebnis zurückgeliefert.
Barcodetypen mit obligatorischem Prüfzeichen haben den Parameter 'check_char' stets auf 'present' gesetzt. Ob das Prüfzeichen aus den Nutzdaten entfernt wird oder erhalten bleibt, hängt jedoch vom Standard des jeweiligen Codetypen ab. Beispiele für solche Codetypen sind Code 128, EAN-8, EAN-13 und UPC-A.
Dieser Parameter kann mit dem Operator
set_bar_code_param_specific spezifisch für unterschiedliche
Barcodetypen gesetzt werden.
Werte: ['absent', 'present', 'preserved']
Standardwert: 'absent'
An den meisten GS1-tauglichen Barcodes kann eine 2D GS1-Composite Code
Komponente angehängt sein. Wenn 'composite_code' auf
'CC-A/B' gesetzt ist, wird die Composite-Komponente lokalisiert
und dekodiert. Standardmäßig, ist 'composite_code' auf
'none' gesetzt und so wird der Composite-Komponente neben dem
Barcode ignoriert. Besitzt ein Barcode des gesuchten Typs keine Composite
Komponente, so wird beim Aufruf von find_bar_code nur das
Ergebnis des Barcodes zurückgeliefert. Zur Zeit werden GS1 Composite Codes
nur zusammen mit einem Barcode der Familie GS1 DataBar unterstützt.
Dieser Parameter kann mit dem Operator
set_bar_code_param_specific spezifisch für unterschiedliche
Barcodetypen gesetzt werden.
Werte: ['none', 'CC-A/B']
Standardwert: 'none'
UPC-E-Barcodes können in verschiedenen Ausgabeformaten zurückgegeben werden. Standardmäßig ist 'upce_encodation' auf 'ucc-12' gesetzt und der dekodierte String wird im UCC-12-Format (bestehend aus 12 Ziffern) zurückgegeben. Wird 'upce_encodation' auf 'zero-suppressed' gesetzt, so wird das Ergebnis im Zero-Suppressed-Format (also mit unterdrückten Nullen an definierten Stellen) zurückgegeben. Dieses Format besteht aus führender Null, sechs kodierten Ziffern und einem implizit kodiertem Prüfzeichen. Dies entspricht dem Format, das von ISO/IEC 15420:2009 gefordert wird.
Dieser Parameter kann mit dem Operator
set_bar_code_param_specific spezifisch für den Barcodetype UPC-E
gesetzt werden.
Werte: ['ucc-12', 'zero-suppressed']
Standardwert: 'ucc-12'
Training:
Neben dem manuellen Setzen der Modellparameter mit dem Operator
set_bar_code_param ist es auch möglich, das Modell mit
Hilfe von find_bar_code anhand eines oder mehrerer
Beispielbilder zu trainieren.
Dazu muss zuerst ein Barcode-Modell im Trainings-Modus erstellt werden,
oder ein bestehendes Barcode-Modell muss in den Trainings-Modus versetzt
werden, indem man in set_bar_code_param als generischen Parameter
GenParamName 'train' übergibt.
Der entsprechende Wert bei GenParamValue bestimmt, welche
Parameter gelernt werden sollen.
Im einzelnen können die folgenden Werte gesetzt werden:
Es werden alle trainierbaren Parameter gelernt.
Minimale Größe eines Basiselements. Diese Einstellung trainiert den Parameter 'element_size_min'.
Maximale Größe eines Basiselements. Diese Einstellung trainiert den Parameter 'element_size_max'.
Minimale Barcode Breite. Diese Einstellung trainiert den Parameter 'barcode_width_min'.
Maximale Barcode Breite. Diese Einstellung trainiert den Parameter 'barcode_width_max'.
Relativer Schwellenwert zur Kantenbestimmung in Scanlinien. Diese Einstellung trainiert den Parameter 'meas_thresh'.
Absoluter Schwellenwert zur Kantenbestimmung in Scanlinien. Diese Einstellung trainiert den Parameter 'meas_thresh_abs'.
Orientierung des Barcodes. Diese Einstellung trainiert die Parameter 'orientation' und 'orientation_tol'. Nach Abschluss des Trainings sollte der Wert für 'orientation_tol' noch um einen Toleranzwert erhöht werden um auch Barcodes zu finden deren Orientierung sich leicht außerhalb des trainierten Bereichs befindet.
Es können mehrere Parameter in einem Aufruf von
find_bar_code gemeinsam trainiert werden, indem 'train' in
set_bar_code_param in einem Tupel
mehrfach mit den entsprechenden Werten übergeben wird:
z.B. GenParamName = ['train','train'] und
GenParamValue = ['element_size_min','element_size_max'].
Weiterhin können - im Zusammenhang mit 'train' =
'all' - einzelne Parameter explizit vom Training
ausgeschlossen werden, indem zusätzlich 'train' mit den
entsprechenden Parametern und einem vorangestellten
'~' gesetzt wird:
z.B. GenParamName = ['train','train'] und
GenParamValue =
['all','~orientation']
trainiert alle Parameter außer 'orientation'.
Anschließend muss für jedes zu trainierende Bild der Operator
find_bar_code aufgerufen werden.
Die folgenden Hinweise sollten im Zusammenhang mit dem Training beachtet werden:
Zusätzlich nötige, nicht zu trainierende Parameter (beispielsweise 'check_char') müssen vor dem Training manuell festgelegt werden.
Soll über mehrere Bilder trainiert werden, ist der
Operator find_bar_code mehrfach nacheinander aufzurufen.
Pro Bild können mehrere Barcodes des gewählten Typs sichtbar sein. Alle dekodierten Barcodes werden als Trainings-Beispiele behandelt.
Bitte prüfen Sie die Ausgabe von find_bar_code im
Trainings-Modus. Während des Trainings sollten nur tatsächlich korrekte
Dekodierungen auftreten. Stellen Sie fest, dass eine falsche
Dekodierung erfolgt ist, sollten Sie dieses Trainingsbild entweder verwerfen
oder entsprechende Parameter zuvor setzen (z.B. können Sie in einem solchen
Fall versuchen, den Wert des Parameters 'min_identical_scanlines'
zu erhöhen).
Befinden sich im Trainingsbild mehrere Barcodes und
soll aber nur über einen bestimmten Barcode trainiert werden, ist
der Definitionsbereich des Bildes mit reduce_domain
entsprechend einzuschränken.
Sind in einer Anwendung alle Bilder sehr ähnlich, reicht i.d.R. ein Trainingsbild für die Parameter 'element_size_min', 'element_size_max', 'meas_thresh' und 'meas_thresh_abs'.
Kann die Elementgröße variieren, sollten nach Möglichkeit im Training auch Bilder mit den kleinsten und den größten vorkommenden Elementen verwendet werden. Sollte dies nicht sichergestellt werden können, müssen die Grenzen für die Elementgröße nach dem Training von Hand gesetzt bzw. entsprechend modifiziert werden, oder die Elementgrößen werden vom Training ganz ausgenommen.
Die Modellparameter werden beim ersten Training auf die Modelleigenschaften des im Bild gefundenen Barcodes eingeschränkt. Bei jedem weiteren Training werden sie, falls notwendig, so erweitert, dass neben den bisher trainierten Barcodes auch der neue Barcode vom Modell abgedeckt wird.
Wurden genügend Bilder trainiert, so kann das Training beendet werden.
Zuvor sollten jedoch die trainierten Parameter ausgelesen werden.
Mit query_bar_code_params können die Namen der trainierten
Parameter - aufgeteilt in spezifische und allgemeine Parameter -
bestimmt werden und anschließend entsprechend mit
get_bar_code_param_specific und get_bar_code_param
ausgelesen werden.
Zum Beenden des Trainings werden alle trainierten Parameter durch
einen Aufruf des Operators set_bar_code_param
mit den Parametern GenParamName = 'train' und
GenParamValue = '~all'
aus dem Training genommen.
Alternativ kann auch einfach das existierende Barcode-Modell durch
den Operator clear_bar_code_model geschlossen werden.
Während des Trainings sollte der Wert eines Trainingsparameters nicht
durch einen Aufruf von set_bar_code_param oder
set_bar_code_param_specific explizit gesetzt werden. Falls
das gemacht wird, werden die gesamten internen Trainingsdaten
zurückgesetzt und das Training startet mit dem nächsten
Aufruf von find_bar_code von vorne.
Kann der zu trainierende Barcode nicht gelesen werden, erzeugt dies keine gesonderte Fehlermeldung, sondern es sind lediglich die Ergebnislisten (DecodedDataStrings, SymbolRegions) leer. Die Modellparameter (insbesondere die trainierten Parameter) werden in diesem Fall nicht modifiziert.
Timeouts sind während des Trainings deaktiviert.
Sonstiges:
Mit Hilfe dieses Parameters ist es möglich, dass find_bar_code
nach einer definierten Zeit (in ms) abbricht. Dies ist vor allem dann
nützlich, wenn maximale Zykluszeiten eingehalten werden müssen.
Alle bis zu diesem Abbruch gewonnenen Ergebnisse sind anschließend
verfügbar und können mit get_bar_code_result abgerufen werden.
Werden Werte kleiner oder gleich Null übergeben, wird der Timeout
deaktiviert (Default).
Die zeitliche Genauigkeit des Timeouts liegt bei ca. 10 ms. Sie hängt
von vielen Faktoren ab, u.a. von der Geschwindigkeit des Rechners
und dem 'timer_mode', der über set_system gesetzt wurde.
find_bar_code wirft keinen Fehler, falls ein Timeout auftritt.
Um zu prüfen, ob find_bar_code abgebrochen wurde, kann der
Parameter 'aborted' mit get_bar_code_result
abgefragt werden.
Im Trainingsmodus von find_bar_code wird der Timeout ignoriert.
Typische Werte: ['false', -1, 20, .., 100]
Standardwert: 'false'
Mit dieser Option ist es möglich find_bar_code von einem anderen
Thread aus abzubrechen. Wenn set_bar_code_param mit
'abort' aufgerufen wird, wird einer Instanz von
find_bar_code mit dem Model BarCodeHandle in einem
anderen Thread signalisiert abzubrechen. Falls es keine solche
find_bar_code Instanz mit diesem Model gibt, passiert nichts.
Es ist möglich, dass der Operator find_bar_code nicht sofort
abbricht. Er muss zunächst einen interner Abbruchpunkt erreichen, an dem
ein sauberes Verlassen des Operators möglich ist. Dies hängt von
Rahmenbedingungen wie Rechnerleistung ab und kann ungefähr bis zu 10ms
benötigen. Im Trainingsmodus von find_bar_code wird der Parameter
ignoriert.
Hinweis: Dies ist die einzige Aktion mit Barcode Handles, die von unterschiedlichen Threads genutzt werden kann, ohne dass zusätzliche Synchronisierung nötig ist.
Standardwert: 'true' (Der Wert wird nicht ausgewertet.)
Steuert, ob bestimmte Zwischenergebnisse bei der Symbolsuche mit
find_bar_code temporär oder persistent im Modell gespeichert
werden sollen. Zur Zeit ist es erforderlich 'persistence'
einzuschalten ('persistence' = 1), wenn die Barcode
Druckqualität bewertet werden muss (get_bar_code_result
mit Parameter 'quality_isoiec15416') oder die Dekodierungs-
Scanlinien inspiziert werden müssen (get_bar_code_object mit
Parameter 'scanlines_all' oder 'scanlines_valid').
Mit Einschalten von 'persistence' steigt der Speicherbedarf
für den Barcode-Leser allerdings auch.
Werte: [0, 1]
Standardwert: 0
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.
BarCodeHandle (input_control, Zustand wird modifiziert) barcode → (handle)
Handle des zu verwendenden Barcode-Modells.
GenParamName (input_control) attribute.name(-array) → (string)
Namen der generischen Parameter, die für den Barcode eingestellt werden sollen.
Defaultwert: 'element_size_min'
Werteliste: 'abort', 'barcode_height_min', 'barcode_width_max', 'barcode_width_min', 'check_char', 'composite_code', 'contrast_min', 'element_size_max', 'element_size_min', 'element_size_variable', 'majority_voting', 'meas_thresh', 'meas_thresh_abs', 'merge_scanlines', 'min_code_length', 'min_identical_scanlines', 'num_scanlines', 'orientation', 'orientation_tol', 'persistence', 'quality_isoiec15416_reflectance_reference', 'quiet_zone', 'small_elements_robustness', 'start_stop_tolerance', 'stop_after_result_num', 'timeout', 'train', 'upce_encodation'
GenParamValue (input_control) attribute.value(-array) → (real / integer / string)
Werte der generischen Parameter, die für den Barcode eingestellt werden sollen.
Defaultwert: 8
Wertevorschläge: 0, 0.1, 1, 1.5, 2, 8, 32, 45, 'true', 'false', 'present', 'absent', 'none', 'CC-A/B', 'auto', 'high', 'low', 'ucc-12', 'zero-suppressed'
set_bar_code_param liefert den Wert 2 (H_MSG_TRUE), falls die
übergebenen Parameter korrekt sind.
Ansonsten wird eine Fehlerbehandlung durchgeführt.
Bar Code