| Operatoren |
find_data_code_2d — Suchen und Lesen von 2D-Datacode-Symbolen im Eingabebild sowie Training des 2D-Datacode-Modells.
find_data_code_2d(Image : SymbolXLDs : DataCodeHandle, GenParamNames, GenParamValues : ResultHandles, DecodedDataStrings)
Der Operator find_data_code_2d sucht im Eingabebild (Image) nach 2D-Datacode-Symbolen und liest den darin kodierten String aus. Dafür muss zuvor mit Hilfe von create_data_code_2d_model oder read_data_code_2d_model ein Modell für eine Klasse von 2D-Datacodes erstellt und der dabei erzeugte Handle in DataCodeHandle an find_data_code_2d übergeben werden. Um in einem Bild gezielt nach mehr als einem Symbol zu suchen, kann in dem generischen Parameter GenParamNames = 'stop_after_result_num' die Anzahl der gesuchten Datacodes übergeben werden (GenParamValues).
Als Ergebnis liefert der Operator für jedes erfolgreich detektierte Symbol eine XLD-Kontur mit dem umschließenden Viereck (SymbolXLDs), einen Kandidaten-Handle, der auf eine Ergebnisstruktur verweist, in der zusätzliche Informationen über das Symbol und den Such- und Leseprozess abgespeichert wurden (ResultHandles), sowie den String, der in dem Datacode-Symbol kodiert ist (DecodedDataStrings). Ist der String länger als 1024 Zeichen, wird er auf 1020 Zeichen gefolgt von '...' gekürzt. Der Zugriff auf den kompletten String kann in diesem Fall nur mit Hilfe des ResultHandles und dem Operator get_data_code_2d_results mit dem Parameter 'decoded_data' erfolgen, wobei die einzelnen Zeichen des Strings in einem Tupel zurückgegeben werden.
Die Symbolstruktur von GS1 DataMatrix, GS1 QR Code und GS1 Aztec Code ist identisch der Struktur von ECC 200, QR Code, bzw. Aztec Code. Deswegen gelten alle typspezifischen Parameter, Einstellungen und Regel, die ECC 200, QR Code oder Aztec betreffen, auch für ihre entsprechende GS1-Variante. Die GS1 Symbologien haben lediglich zusätzliche Vorgaben bezüglich des Formats der im jeweiligen Symbol kodierten Daten. Die Daten müssen in sogenannten "GS1 Application Element Strings" organisiert werden, welche in den allgemeinen GS1 Specifikationen definiert sind. Wenn zum Beispiel DataCodeHandle als GS1 DataMatrix erstellt wurde, dann liest find_data_code_2d ein Symbol nur wenn das Symbol ein gültiges ECC 200 Symbol ist und nur wenn seine Daten nach den GS1 Regeln formatiert sind. Von den "GS1 Application Element Strings" wird nur überprüft, ob die gelesenen Application Identifier im Standard "GS1 General Specifications" existieren. Wenn stattdessen ein ECC 200 Symbol nur allgemeine Daten enthält, wird er vom Operator find_data_code_2d nicht gelesen. Dasselbe stimmt auch für GS1 QR Code und GS1 Aztec Code.
Anpassen des Modells
Sollte ein im Bild sichtbarer 2D-Datacode nicht erkannt werden, ist zu überprüfen, ob das Symbol die im Modell beschriebenen Eigenschaften besitzt. Dabei ist insbesondere auf
die richtige Polarität ('polarity', hell auf dunkel oder dunkel auf hell),
die Symbolgröße ('symbol_size' beim ECC 200 und beim Aztec Code,
'version' beim QR-Code,
'format' beim Aztec Code,
die Modulgröße ('module_size' beim ECC 200, QR Code und Aztec Code, 'module_width' und 'module_aspect' beim PDF417),
eine mögliche Spiegelung des Symbols ('mirrored'),
sowie den eingestellten Mindestkontrast ('contrast_min')
zu achten. Weitere relevante Größen sind beim ECC 200, beim QR Code und beim Aztec Code der Zwischenraum zwischen benachbarten Vordergrundmodulen ('module_gap') und beim ECC 200 der maximal erlaubte Winkel des Finderpatterns ('slant_max'). Die aktuellen Einstellungen für diese Werte lassen sich mit dem Operator get_data_code_2d_param abfragen. Gegebenenfalls können die entsprechenden Parameter mit Hilfe des Operators set_data_code_2d_param an das 2D-Datacode-Symbol im Bild angepasst werden.
Eine möglichst genaue Anpassung des Modells an die gesuchte Datacode-Klasse empfielt sich darüber hinaus auch aus Laufzeitgründen. Im Allgemeinen gilt, dass die Laufzeit von find_data_code_2d umso höher ist, je allgemeiner das Modell definiert wurde. Zu beachten ist dabei, dass sich das ungünstige Laufzeitverhalten auf Grund eines zu allgemeinen Modells vor allem dann negativ auswirkt, wenn im Bild kein gültiger 2D-Datacode gefunden werden kann.
Trainieren des Modells
Neben dem manuellen Setzen der Modellparameter mit dem Operator set_data_code_2d_param ist es auch möglich, das Modell mit Hilfe von find_data_code_2d anhand eines oder mehrerer Beispielbilder zu trainieren. Dazu muss als generischer Parameter GenParamNames 'train' übergeben werden. Der entsprechende Wert bei GenParamValues bestimmt, welche Parameter aus dem aktuellen Bild gelernt werden sollen. Im einzelnen können die folgenden Werte gesetzt werden:
Alle 2D-Datacode-Modelle:
Es werden alle trainierbaren Parameter gelernt.
Symbolgröße und beim ECC 200 auch die Symbolform (Rechteck oder Quadrat). Beim QR-Code kann alternativ als Wert auch 'version' übergeben werden.
Größe der Module; beim PDF417 umfasst dies die Modulbreite sowie das Modul-Seitenverhältnis.
Robustheit der Dekodierung gegenüber Datacodes mit sehr kleiner Modulgröße.
Polarität der Symbole: sind die Symbole heller oder dunkler als der Hintergrund.
Sind die Symbole im Bild gespiegelt oder nicht.
Minimaler Kontrast, der eingestellt werden muss, um die Symbole detektieren zu können.
nur ECC 200, QR-Code und Aztec Code:
Form der Module, insbesondere das Vorhandensein von Lücken zwischen benachbarten Vordergrundmodulen.
nur ECC 200 und Aztec Code:
Die verwendete Toleranz der Suche gegenüber einem gestörten oder teilweise fehlenden Finderpattern.
nur ECC 200:
Die verwendete Toleranz bezüglich lokaler Kontrastvariationen.
Algorithmus zur Berechnung der Modulpositionen (festes oder variables Gitter).
Anpassen verschiedener Bildverarbeitungsparameter; im Moment wird hier lediglich der maximale Slant beim ECC 200 eingestellt, in Zukunft können aber weitere Parameter folgen.
nur QR-Code:
Modelltyp 1 oder 2.
nur Aztec Code:
Die Anzahl zusätzlich zu untersuchender Pyramidenebenen bei der Suche.
Es können mehrere zu trainierende Parameter kombiniert und gemeinsam übergeben werden, indem 'train' in einem Tupel mehrfach mit den entsprechenden Werten übergeben wird: z.B. GenParamNames = ['train','train'] und GenParamValues = ['polarity','module_size']. 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. GenParamNames = ['train','train'] und GenParamValues = ['all','~contrast'].
Die folgenden Hinweise sollten im Zusammenhang mit dem Training beachtet werden:
Soll über mehrere Bilder trainiert werden, ist der Operator find_data_code_2d mehrfach nacheinander mit dem gesetzten 'train'-Parameter und den verschiedenen Trainingsbildern aufzurufen.
Es kann auch über mehrere Symbole in einem Bild trainiert werden. Dazu ist in GenParamNames zusätzlich zu 'train' der generische Parameter 'stop_after_result_num' zu übergeben. In GenParamValues wird neben den zu trainierenden Parametern die Anzahl der Symbole, die sich im Bild befinden, übergeben.
Befinden sich im Trainingsbild mehrere Symbole und soll aber nur über ein bestimmtes Symbol 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, wenn die Symbolgröße (in Modulen) bei allen Bildern identisch ist, die Vorder- und Hintergrundmodule gleich groß sind (d.h. auch keine Lücken zwischen benachbarten Vordergrundmodulen auftreten), der Hintergrund weitestgehend untexturiert ist und der Kontrast in allen Bildern etwa gleich groß ist. In allen anderen Fällen sollten mehrere Bilder zum Training herangezogen werden.
Kann die Symbolgröße variieren, sollten nach Möglichkeit im Training auch Bilder mit den kleinsten und den größten vorkommenden Symbolen verwendet werden. Sollte dies nicht sichergestellt werden können, müssen die Grenzen für die Symbolgröße nach dem Training von Hand gesetzt bzw. entsprechend modifiziert werden, oder die Symbolgröße wird vom Training ganz ausgenommen.
Die Modellparameter werden beim ersten Training auf die Modelleigenschaften des im Bild gefundenen Symbols eingeschränkt. Bei jedem weiteren Training werden sie, falls notwendig, so erweitert, dass neben den bisher trainierten Symbolen auch der neue Datacode vom Modell abgedeckt wird. Durch ein Zurücksetzen des Modells mit set_data_code_2d_param auf eine der Standardeinstellung ('default_parameters' = 'standard_recognition', 'enhanced_recognition' oder 'maximum_recognition') wird neben den Modellparametern auch der Trainingsstatus des Modells in den Grundzustand zurückgesetzt.
Kann das zu trainierende Symbol nicht gelesen werden, erzeugt dies keine gesonderte Fehlermeldung, sondern es sind lediglich die Ergebnislisten (SymbolXLDs, ResultHandles, DecodedDataStrings) leer. Das Modell wird in diesem Fall nicht modifiziert.
Es ist zu beachten, dass möglicherweise gesetzte Zeitschranken im Trainingsmodus nicht beachtet werden (siehe 'timeout' in set_data_code_2d_param).
Übersicht über die Funktionsweise der Symbolsuche
Abhängig von den Einstellungen im 2D-Datacode-Modell (vgl. set_data_code_2d_param) absolviert find_data_code_2d intern i.d.R. mehrere Durchläufe bei der Suche nach 2D-Datacode-Symbolen. Begonnen wird die Suche auf der höchsten Pyramidenstufe, auf der die einzelnen Module (entsprechend der vorgegebenen maximalen Modulgröße) noch zu unterscheiden sein müssten. Außerdem kann in jeder Pyramidenstufe die Vorverarbeitung entsprechend der eingestellten Modulform variiert werden. Erlaubt das Modell sowohl helle Symbole vor dunklem Hintergrund als auch dunkle Symbole vor hellem Hintergrund ('polarity = any'), werden in der jeweiligen Pyramidenstufe zuerst die Durchläufe zum Finden von dunklen Symbolen abgearbeitet, danach wird nach hellen Symbolen gesucht. Ein solcher Durchlauf besteht immer aus zwei Phasen: der Suche, bei der i.d.R. eine Reihe von Symbolkandidaten anhand des Finderpatterns detektiert werden, und der Auswertephase, in der in einer niedrigeren Pyramidenstufe der Reihe nach alle neu gefundenen Kandidaten auf ihre Lesbarkeit hin untersucht werden. In der Suchphase können in einem entsprechend strukturierten Bild auch eine Reihe von Kandidaten an Stellen generiert werden, die keine Symbole enthalten. Die Bearbeitung dieser Kandidaten wird allerdings in der anschließenden Auswertephase i.d.R. sehr früh abgebrochen.
Der gesamte Operatoraufruf wird schließlich beendet, wenn entweder die geforderte Anzahl an 2D-Datacode-Symbolen gefunden wurde, alle Suchdurchläufe abgearbeitet wurden oder eine Zeitüberschreitung (siehe set_data_code_2d_param) eingetreten ist. Die Anzahl der zu lesenden Symbole, kann mit dem generischen Parameter GenParamNames = 'stop_after_result_num' gesteuert werden. Der entsprechende Wert ist in GenParamValues zu übergeben. Wird nichts übergeben, wird gestoppt, sobald ein Symbol erfolgreich dekodiert werden konnte.
Abfrage von Ergebnissen der Symbolsuche
Die Operatoren get_data_code_2d_results und get_data_code_2d_objects erlauben den Zugriff auf zahlreiche Informationen zur Symbolsuche im Allgemeinen wie z.B. die Anzahl der Durchläufe und der untersuchten Kandidaten, und - zusammen mit den ResultHandles - über die Symbolkandidaten im einzelnen, wie die Symbol- und Modulgröße, den Kontrast oder die im Symbol kodierten Rohdaten. Diese Operatoren ermöglichen dabei auch den Zugriff auf all jene Symbolkandidaten, die zwar untersucht aber letztendlich nicht gelesen werden konnten. Insbesondere lässt sich so ermitteln, ob die Vorverarbeitung für ein abgebildetes aber nicht gelesenes 2D-Datacode-Symbol überhaupt einen Kandidaten generiert hat und - anhand einer Statusvariablen - warum dessen Bearbeitung schließlich abgebrochen wurde. Nähere Information finden sich bei den Operatoren get_data_code_2d_results und get_data_code_2d_objects.
Timeout
Mit dem Operator set_data_code_2d_param kann man einen Timeout für find_data_code_2d festlegen. Falls find_data_code_2d in einen Timeout läuft, werden alle bis dahin erkannten Codes zurückgegeben. Ob ein Timeout vorlag oder nicht, kann mit get_data_code_2d_results und dem Parameter 'timeout_occurred' abgefragt werden.
Chinesische Zeichen
Enthält ein QR Code chinesische Zeichen, die nach dem chinesischen nationalen Standard GBT 18284-2000 codiert sind, gibt find_data_code_2d diese Zeichen UTF-8 codiert in DecodedDataStrings zurück, sofern der Systemparameter 'filename_encoding' auf 'utf8' gesetzt ist. Der Inhalt von 'decoded_data', welcher mit get_data_code_2d_results abgefragt werden kann, wird nicht nach UTF-8 konvertiert.
Eingabebild. Falls das Bild eine reduzierte Domäne besitzen sollte, so wird der Bereich eingeschränkt in dem nach Datacodes gesucht wird. In der Regel führt dies zu einer Verbesserung der Laufzeit. Allerdings sollte man beachten, dass ein Datacode nicht mehr gefunden werden könnte, wenn er nicht vollständig in der Domäne des Bildes liegt.
XLD-Konturen, die die erfolgreich dekodierten Datacode-Symbole umschließen.
Handle des zu verwendenden 2D-Datacode-Modells.
Namen von (optionalen) Parametern für die Steuerung des Verhaltens des Operators.
Defaultwert: []
Werteliste: 'stop_after_result_num', 'train'
Die zu den optionalen generischen Parametern gehörenden Werte.
Defaultwert: []
Wertevorschläge: 'all', 'model_type', 'symbol_size', 'version', 'module_size', 'small_modules_robustness', 'module_shape', 'polarity', 'mirrored', 'contrast', 'module_grid', 'finder_pattern_tolerance', 'contrast_tolerance', 'image_proc', 1, 2, 3
Handles der erfolgreich dekodierten 2D-Datacode-Symbole.
Die dekodierten Datenstrings aller im Bild detektierten 2D-Datacode-Symbole.
* Examples showing the use of find_data_code_2d.
* First, the operator is used to train the model, afterwards it is used to
* read the symbol in another image.
* Create a model for reading Data matrix ECC 200 codes
create_data_code_2d_model ('Data Matrix ECC 200', [], [], DataCodeHandle)
* Read a training image
read_image (Image, 'datacode/ecc200/ecc200_cpu_008')
* Train the model with the symbol in the image
find_data_code_2d (Image, SymbolXLDs, DataCodeHandle, 'train', 'all', \
ResultHandles, DecodedDataStrings)
*
* End of training / begin of normal application
*
* Read an image
read_image (Image, 'datacode/ecc200/ecc200_cpu_010')
* Read the symbol in the image
find_data_code_2d (Image, SymbolXLDs, DataCodeHandle, [], [], \
ResultHandles, DecodedDataStrings)
* Display all symbols, the strings encoded in them, and the module size
dev_set_color ('green')
for i := 0 to |ResultHandles| - 1 by 1
select_obj (SymbolXLDs, SymbolXLD, i+1)
dev_display (SymbolXLD)
get_contour_xld (SymbolXLD, Row, Col)
set_tposition (WindowHandle, max(Row), min(Col))
write_string (WindowHandle, DecodedDataStrings[i])
get_data_code_2d_results (DataCodeHandle, ResultHandles[i], \
['module_height','module_width'], ModuleSize)
new_line (WindowHandle)
write_string (WindowHandle, 'module size = ' + ModuleSize[0] + 'x' + \
ModuleSize[1])
endfor
* Clear the model
clear_data_code_2d_model (DataCodeHandle)
find_data_code_2d liefert den Wert 2 (H_MSG_TRUE), falls die übergebenen Parameter korrekt sind. Ansonsten wird eine Fehlerbehandlung durchgeführt.
create_data_code_2d_model, read_data_code_2d_model, set_data_code_2d_param
get_data_code_2d_results, get_data_code_2d_objects, write_data_code_2d_model
create_data_code_2d_model, set_data_code_2d_param, get_data_code_2d_results, get_data_code_2d_objects
GS1 General Specifications; Version 12; Issue 1, Jan-2012; GS1.
Data Code
| Operatoren |