get_data_code_2d_param — Abfrage von einem oder mehreren Parametern, die das 2D-Datacode-Modell
beschreiben.
get_data_code_2d_param( : : DataCodeHandle, GenParamName : GenParamValue)
Mit Hilfe des Operators get_data_code_2d_param lassen sich
die Parameter, durch die das 2D-Datacode-Modell beschrieben wird, abfragen.
Die Namen der Parameter, die abgefragt werden sollen, werden in
GenParamName übergeben, die korrespondierenden Werte werden
in GenParamValue zurückgeliefert.
Sämtliche Parameter können mit set_data_code_2d_param
gesetzt und jederzeit verändert werden.
Eine Liste der Parameternamen, die für den ausgewählten
2D-Datacode-Type abgefragt werden können, liefert der Operator
query_data_code_2d_params.
Das Konzept des 2D-Datacode-Lesers ist bei der Einleitung zu Kapitel Identifizierung / Datacode beschrieben.
Es ist zu beachten, dass die Symbolstruktur von GS1 DataMatrix, GS1 QR Code
und GS1 Aztec Code der Struktur von Data Matrix ECC 200, QR Code, bzw.
Aztec Code identisch ist. Deswegen gelten alle typspezifischen Parameter,
Einstellungen und Regeln, die Data Matrix ECC 200, QR Code oder Aztec Code
betreffen, auch für ihre entsprechende GS1-Variante.
Im Folgenden wird das ausführliche Auflisten
typspezifischer Parameter einzelner GS1-Typen ausgelassen, um die Lesbarkeit
der Dokumentation zu erleichtern. Stattdessen können die relevante Parameter
eines GS1-Datacodetyps entweder von den Parametern von dessen
nicht-GS1-Variante hergeleitet werden oder explizit durch
query_data_code_2d_params mit dem Parameter
'get_model_params' abgefragt werden.
Im Einzelnen kann auf die folgenden Parameter - gruppiert nach verschiedenen Kategorien und Datacode-Typen - zugegriffen werden:
Größe und Form des Symbols:
Data Matrix ECC 200 (inklusive Finder-Pattern):
Mindestanzahl der Spalten des Symbols in Modulen.
Höchstanzahl der Spalten des Symbols in Modulen.
Mindestanzahl der Zeilen des Symbols in Modulen.
Höchstanzahl der Zeilen des Symbols in Modulen.
Mögliche Einschränkungen hinsichtlich der Form des Symbols (Rechteck und/oder Quadrat): 'square', 'rectangle' oder 'any'. Seit HALCON 7.1.1 werden bei der Symbolsuche beide Formen gleich behandelt.
QR-Code (inklusive Finder-Pattern):
Typ des QR-Code-Modells: 1, 2, 0 (für 'any')
Kleinste zu lesende Symbol-Version: [1..40] (Modelltyp 1: [1..14])
Größte zu lesende Symbol-Version: [1..40] (Modelltyp 1: [1..14])
Kleinste zu lesende Symbolgröße in Modulen (dieser Wert korrespondiert direkt mit 'version_min'): [21..177] (Modelltyp 1: [21..73])
Größte zu lesende Symbolgröße in Modulen (dieser Wert korrespondiert direkt mit 'version_max'): [21..177] (Modelltyp 1: [21..73])
PDF417:
Mindestanzahl der Datenspalten des Symbols in Codewords (je 17 Module), d.h. exklusive der Codewords der Start/Stop-Patterns sowie der beiden Codewords der Row-Indicators.
Höchstanzahl der Datenspalten des Symbols in Codewords (je 17 Module), d.h. exklusive der Codewords der Start/Stop-Patterns sowie der beiden Codewords der Row-Indicators.
Mindestanzahl der Zeilen des Symbols in Modulen.
Höchstanzahl der Zeilen des Symbols in Modulen.
Aztec Code (inklusive Finder-Pattern):
Format des Aztec Codes: Durch Leerzeichen getrennte Liste mit den Werten 'compact', 'full_range' oder 'rune'.
Kleinste zu lesende Symbolgröße in Modulen: [11..151]
Größte zu lesende Symbolgröße in Modulen: [11..151]
Erscheinungsbild der Module im Bild:
Alle 2D-Datacode-Modelle:
Mögliche Einschränkungen hinsichtlich der Polarität der Module, d.h. ob diese im Bild dunkel vor hellem Hintergrund oder hell vor dunklem Hintergrund erscheinen: 'dark_on_light', 'light_on_dark' oder 'any'.
Steuert, ob Kandidaten, die nicht erfolgreich dekodiert werden konnten, beim Modell gespeichert werden: 'yes', 'no'.
Angabe über eine mögliche Spiegelung des Symbols (entspricht einem Vertauschen von Spalten und Zeilen): 'yes', 'no' oder 'any'.
Robustheit der Dekodierung gegenüber Datacodes mit sehr kleiner
Modulgröße. Wird der Parameter 'small_modules_robustness'
auf 'high' gesetzt, so erhöht sich die Wahrscheinlichkeit,
dass Datacodes mit sehr kleinen Modulen dekodiert werden können.
Zusätzlich sollte in diesem Fall auch die minimale Modulgröße
entsprechend angepasst werden, d.h. 'module_size_min' bzw.
'module_width_min' (PDF417)
sollte auf die angenommene minimale Modulgröße bzw. Modulbreite
gesetzt werden. Ist 'small_modules_robustness' auf
'high' gesetzt, so kann sich der interne Speicherbedarf von
find_data_code_2d deutlich erhöhen. Folglich sollte
'small_modules_robustness' im Normalfall auf 'low'
gesetzt werden.
Werteliste: 'low', 'high'
Default: 'low' (enhanced: 'low', maximum: 'high')
Alle 2D-Datacode-Modelle bis auf Data Matrix ECC 200:
Mindestkontrast zwischen Vorder- und Hintergrund des Symbols im Bild (dieses Maß korrespondiert mit dem Anstieg der Kanten zwischen Vorder- und Hintergrund).
Alle 2D-Datacode-Modelle bis auf PDF417:
Minimale Größe der Module im Bild in Pixel.
Maximale Größe der Module im Bild in Pixel.
Es kann in drei Stufen angegeben werden, ob benachbarte Vordergrundmodule direkt aneinanderstoßen, oder ob es zwischen ihnen eine Lücke geben kann - 'no' (keine Lücke) < 'small' < 'big':
minimale Lücke.
maximale Lücke.
PDF417:
Minimale Breite der Module im Bild in Pixel.
Maximale Breite der Module im Bild in Pixel.
Minimales Seitenverhältnis der Module im Bild (Höhe zu Breite).
Maximales Seitenverhältnis der Module im Bild (Höhe zu Breite).
Aztec Code:
Toleranz der Suche gegenüber einem gestörten oder teilweise
fehlenden Finder-Pattern.
Abhängig von diesem Parameter werden verschiedene Algorithmen
für die Suche in find_data_code_2d verwendet. Für
'low' wird angenommen, dass alle Ringe des Finder-Patterns
extrahiert werden können. Für 'high' wird angenommen, dass
mindestens einer der Ringe des Finder-Patterns extrahiert werden
kann.
Um die Robustheit des Aztec Code Lesers zu erhöhen, kann die Anzahl der Pyramidenebenen, die zusätzlich zu den durch die minimale und maximale Modulgröße bedingten Ebenen untersucht werden sollen, angegeben werden. [0..2]
Data Matrix ECC 200:
Maximale Abweichung des Winkels im L-förmigen Finder-Pattern vom (idealerweise) rechten Winkel (die Angabe erfolgt im Bogenmaß und korrespondiert mit der möglichen Verzerrung, die beim Druck des Symbols oder bei der Bildaufnahme auftreten kann).
Toleranz der Suche gegenüber einem gestörten oder teilweise
fehlenden Finder-Pattern. Das Finder-Pattern umschließt
sowohl die L-förmige als auch die gegenüberliegende
alternierende Seite. In Abhängigkeit von diesem Parameter
werden verschiedene Algorithmen für die Suche in
find_data_code_2d verwendet. In einem Fall
('low') wird davon ausgegangen, dass das
Finder-Pattern zum großen Teil vorhanden ist und kaum
Störungen aufweist. Im anderen Fall ('high') kann
das Finder-Pattern gestört oder teilweise fehlend sein,
ohne dass die Erkennung beeinträchtigt wird. Zu beachten
ist allerdings, dass bei dieser Variante die Parameter für
die Symbolsuche möglichst stark mit
set_data_code_2d_param eingeschränkt werden
sollten, da ansonsten eine erhöhte Rechenzeit für
find_data_code_2d zu erwarten ist. Zu beachten ist
außerdem, dass sich beide Algorithmen leicht in ihrer
Robustheit voneinander unterscheiden. Dies kann dazu
führen, dass es selbst bei Symbolen mit intaktem
Finder-Pattern in Abhängigkeit von
'finder_pattern_tolerance' zu unterschiedlichen
Ergebnissen kommt. Wenn 'high' ausgewählt wird,
können z.B. nur Symbole mit festem Gitter gefunden werden
(siehe unten), wodurch die Robustheit gegenüber
perspektivischen Verzerrungen abnimmt. Im Fall
'any' werden beide Algorithmen ausgeführt.
Angabe darüber, ob die Größe der Module in einem gewissen Rahmen variieren darf oder nicht. In Abhängigkeit von diesem Parameter werden verschiedene Algorithmen für die Berechnung der Modulpositionen verwendet. In einem Fall ('fixed') wird ein festes Gitter, bei dem die Abstände zwischen den Modulmittelpunkten alle gleich sind, verwendet. Im anderen Fall ('variable') wird das Gitter an der alternierenden Seite des Finder-Patterns ausgerichtet. Bei 'any' werden beide Varianten für das Gitter nacheinander ausprobiert. Zu beachten ist, dass der Wert von 'module_grid' ignoriert wird, wenn 'finder_pattern_tolerance' auf 'high' gesetzt ist. In diesem Fall wird immer von einem festen Gitter ausgegangen.
Toleranz der Suche beim Auftreten starker lokaler Kontrastvariationen (z.B. bei Reflektionen oder Überbelichtung). Abhängig von diesem Parameter wird zwischen zwei Algorithmen gewählt. Im Falle von 'high' ist die Robustheit gegenüber starken lokalen Kontrastvariationen erhöht. Für 'low' wird ein Algorithmus gewählt, der zwar etwas weniger robust bei lokalen Kontrastvariationen ist, dafür aber schneller. Unter normalen Umständen ist daher 'low' zu bevorzugen. Setzt man den Parameter auf 'any', so werden beide Varianten ausgeführt.
QR Code:
Anzahl von Position-Detection-Patterns, die im Bild gut sichtbar sein müssen, damit ein Symbolkandidat generiert wird.
Allgemeines Modellverhalten:
Alle 2D-Datacode-Modelle:
Steuert, ob bestimmte Zwischenergebnisse bei der
Symbolsuche mit find_data_code_2d temporär oder
persistent im Modell gespeichert werden sollen: 0
(temporär) oder 1 (persistent).
Steuert das Verhalten von find_data_code_2d bei
der Detektion von Symbolen, die hinsichtlich der
Symbolgröße nicht den Modellvorgaben entsprechen:
'yes' (strikt: entsprechende Symbole werden
verworfen) oder 'no' (nicht strikt: Symbole
werden, wenn sie gelesen werden können, als Ergebnis
zurückgeliefert).
Gibt die erwartete Zeichencodierung des im Symbol kodierten Strings: 'utf8', 'locale' oder 'raw'.
Gibt den beim Erzeugen mit create_data_code_2d_model
angegebenen Datacode-Typ zurück.
Mit Hilfe dieses Parameters ist es möglich, dass
find_data_code_2d nach einer definierten Zeit in ms
abbricht: 'false', -1,
20 .. 100.
Definiert die simulierte Blendenöffnung für die Druckqualitätsprüfung nach ISO/IEC 15415:2011 als Anteil an der Modulgröße. (Siehe ISO/IEC 15415:2011 Abschnitt 7.3.3).
Alle 2D-Datacode-Modelle bis auf Aztec Code:
Steuert das Verhalten von find_data_code_2d bei
der Detektion von Symbolen deren Ruhezone fehlt oder starke
Defekte aufweist:
'yes' (Symbole mit fehlender oder defekter Ruhezone
werden verworfen) oder 'no' (Symbole
werden, wenn sie gelesen werden können, als Ergebnis
zurückgeliefert). Der 'status' von Ergebnissen, die
verworfen wurden ist 'quiet zone is missing'.
Data Matrix ECC 200:
Bestimmt die Auswahl der Kandidatenregionen, die verwendet werden, um Symbole im Bild zu finden. Wird dieser Parameter auf 'extensive' gesetzt, so erhöht sich die Anzahl der generierten Kandidatenregionen und damit die Wahrscheinlichkeit einen Code zu finden. Wenn 'candidate_selection' auf 'default' gesetzt ist, werden weniger Kandidatenregionen verwendet.
Es ist möglich, in einem Operatoraufruf obige Parameter beliebig zu
kombinieren und gemeinsam in einem Tupel an GenParamName
zu übergeben.
Als Ergebnis wird in GenParamValue ein Tupel gleicher
Länge zurückgeliefert, dessen Werte mit den entsprechenden
Parameternamen korrespondieren.
DataCodeHandle (input_control) datacode_2d → (handle)
Handle des zu verwendenden 2D-Datacode-Modells.
GenParamName (input_control) attribute.name(-array) → (string)
Namen der generischen Parameter, die für das 2D-Datacode-Modell abgefragt werden sollen.
Defaultwert: 'polarity'
Werteliste: 'additional_levels', 'candidate_selection', 'contrast_min', 'contrast_tolerance', 'decoding_scheme', 'discard_undecoded_candidates', 'finder_pattern_tolerance', 'format', 'mirrored', 'model_type', 'module_aspect_max', 'module_aspect_min', 'module_gap_max', 'module_gap_min', 'module_grid', 'module_size_max', 'module_size_min', 'module_width_max', 'module_width_min', 'persistence', 'polarity', 'position_pattern_min', 'quality_isoiec15415_aperture_size', 'slant_max', 'small_modules_robustness', 'strict_model', 'strict_quiet_zone', 'string_encoding', 'symbol_cols_max', 'symbol_cols_min', 'symbol_rows_max', 'symbol_rows_min', 'symbol_shape', 'symbol_size_max', 'symbol_size_min', 'symbol_type', 'timeout', 'version_max', 'version_min'
GenParamValue (output_control) attribute.value(-array) → (string / integer / real)
Werte der generischen Parameter.
get_data_code_2d_param liefert den Wert 2 (H_MSG_TRUE), falls die
übergebenen Parameter korrekt sind.
Ansonsten wird eine Fehlerbehandlung durchgeführt.
query_data_code_2d_params,
set_data_code_2d_param,
find_data_code_2d
find_data_code_2d,
write_data_code_2d_model
query_data_code_2d_params,
set_data_code_2d_param,
get_data_code_2d_results,
get_data_code_2d_objects,
find_data_code_2d
Data Code