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,
GS1 Aztec Code und GS1 DotCode der Struktur von Data Matrix ECC 200, QR Code,
Aztec Code, bzw. DotCode identisch ist. Deswegen gelten alle typspezifischen Parameter,
Einstellungen und Regeln, die Data Matrix ECC 200, QR Code, Aztec Code oder DotCode
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).
Werteliste: 'square', 'rectangle', 'any'.
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])
Micro QR Code:
Kleinste zu lesende Symbol-Version: [1..4]
Größte zu lesende Symbol-Version: [1..4]
Kleinste zu lesende Symbolgröße in Modulen (dieser Wert korrespondiert direkt mit 'version_min'): [11..17]
Größte zu lesende Symbolgröße in Modulen (dieser Wert korrespondiert direkt mit 'version_max'): [11..17]
PDF417:
Mindestanzahl der Datenspalten des Symbols in Codewords (je 17 Module), d.h. exklusive der Codewords der Start/Stopp-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/Stopp-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]
DotCode:
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.
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'.
Alle 2D-Datacode-Modelle bis auf Data Matrix ECC 200 und DotCode:
Mindestkontrast zwischen Vorder- und Hintergrund des Symbols im Bild (angegeben in Grauwerten). Dieses Maß korrespondiert mit dem Anstieg der Kanten zwischen Vorder- und Hintergrund.
Data Matrix ECC 200, Micro QR Code und QR Code:
Toleranz der Suche beim Auftreten starker lokaler Kontrastvariationen (z.B. bei Reflexionen 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.
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' (Bei DotCode sind nur 'no' und 'small' möglich):
minimale Lücke.
maximale Lücke.
Alle 2D-Datacode-Modelle bis auf DotCode:
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')
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.
Toleranz der Suche gegenüber einer Variation der Modulbreiten
entlang der beiden Seiten des alternierenden Finder-Patterns. Die
Analyse dieser alternierenden Seiten spielt eine entscheidende
Rolle, falls 'finder_pattern_tolerance' auf
'low' (oder 'any', was 'low'
miteinschließt) gesetzt worden ist. Es ist jedoch zu
beachten, dass dieser Parameter keinen Einfluss hat, wenn
'finder_pattern_tolerance' auf 'high'
gesetzt worden ist.
Insgesamt sind drei unterschiedliche Werte für diesen
Parameter erlaubt, wobei eine höhere Einstellung stets die
niedrigeren Werte miteinschließt: 'low' erlaubt nur
eine kleine Variation der Modulbreiten entlang der alternierenden
Seiten. 'medium' versucht zunächst die strengen
Anforderungen von 'low' zu erfüllen und wenn
dies scheitern sollte wird eine größere Variation der
Modulbreiten entlang der alternierenden Seiten zugelassen.
Schließlich schließt 'high' alles ein, was
'medium' zugelassen hat, und erweitert zusätzlich
den Parameterraum für die Symbolaußengrenzen durch weitere Versuche.
Außerdem wird die Beziehung zwischen der Anzahl der erkannten
Kanten und des verwendeten Symboltyps für die anschließende
Dekodierung etwas aufgeweicht. Die größere Robustheit in
schwierigen Fällen hat den Nachteil, dass insbesondere
'high' zu einem deutlichen Laufzeitanstieg
führen kann. Um dem entgegenzuwirken, sollte der Parameterraum
insgesamt verkleinert werden, z.B. indem die zu erwartenden
Symbolgrößen mit Hilfe von set_data_code_2d_param
so eng wie möglich vorgegeben werden.
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.
QR Code und Micro QR Code:
Anzahl von Position-Detection-Patterns, die im Bild gut sichtbar sein müssen, damit ein Symbolkandidat generiert wird.
QR Code
Toleranz der Suche gegenüber einem deformierten QR Code. Abhängig von
diesem Parameter wird für die Suche in find_data_code_2d
ein Algorithmus zur Kompensation von Krümmungen verwendet ('curved')
oder nicht ('low').
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). Es ist zu beachten, dass für DotCode-Symbole die
Modellvorgaben bzgl. der Modulgröße ('module_size_min'
und 'module_size_max') auch dann nicht überprüft werden,
wenn 'strict_model' auf 'yes' gesetzt ist.
Gibt die erwartete Zeichencodierung des im Symbol kodierten Strings: 'utf8', 'locale', 'latin1', 'shiftjis' 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.
Alle 2D-Datacode-Modelle bis auf Aztec Code:
Steuert das Verhalten von find_data_code_2d bei
der Detektion von lesbaren Symbolen deren Ruhezone Defekte aufweist.
Mögliche Werte:
Symbole mit schlechten Bewertungen für ihre Ruhezone werden verworfen und somit nicht als Resultat zurückgegeben. Die Ruhezonen werden ähnlich der Druckbildkontrolle ausgewertet, dabei jedoch nur als ein Modul groß betrachtet. Verworfene Symbole erhalten als 'status' den Wert 'quiet zone is missing'.
Alle lesbaren Symbole werden als Ergebnis zurückgegeben.
Alle 2D-Datacode-Modelle bis auf DotCode:
Definiert die simulierte Blendenöffnung für die Druckqualitätsprüfung nach ISO/IEC 15415:2024 als Anteil an der Modulgröße. (Siehe ISO/IEC 15415:2024 Abschnitt 5.6.2 und 7.3.1).
Definiert den Referenzgrauwert für die Druckqualitätsprüfung nach ISO/IEC 15415:2024. (Siehe ISO/IEC 15415:2024 Abschnitt 5.6.1).
Definiert die Modulgröße für die Bestimmung der synthetischen Apertur
für die Druckqualitätsprüfung nach ISO/IEC 15415:2024.
(Siehe ISO/IEC 15415:2024 Abschnitt 7.3.1).
Das kann entweder ein fixer Wert in Pixel sein oder 'adaptive'.
Mit 'adaptive' wird die gemittelte Modulgröße, die in
find_data_code_2d bestimmt wurde, verwendet.
Data Matrix ECC 200:
Steuert das Verhalten von find_data_code_2d bei der Detektion
von lesbaren Symbolen mit einer niedrigen Anzahl an Zeilen ( 12)
und Spalten ( 18). Diese Symbole sind aufgrund ihrer niedrigen
Fehlerkorrekturkapazität besonders gefährdet zu falsch-positiven Ergebnissen
zu führen. Mögliche Werte:
Alle erfolgreich dekodierten Symbole, welche die oben beschriebenen Kriterien erfüllen, werden kontrolliert. Symbole mit einem gestörten äußeren Finder-Pattern, oder mit einer gestörten Ruhezone können dabei verworfen werden beruhend auf den Klassifizierungsergebnissen der entsprechenden Modulpositionen. Verworfene Ergebnisse werden nicht als Resultat zurückgegeben. Sie erhalten als 'status' Werte beginnend mit 'strict_fp_and_qz: ...'. Nach dem Doppelpunkt folgt eine detailliertere Information bzgl. des gescheiterten Tests.
In diesem Modus durchlaufen nur Symbole der angegebenen Größe die zusätzlichen Checks, die eine erhöhte Wahrscheinlichkeit aufweisen tatsächlich ein falsch-positives Ergebnis darzustellen.
Die zusätzlichen Überprüfungen werden vollständig deaktiviert.
Siehe auch set_data_code_2d_param für weitere Informationen.
Data Matrix ECC 200, DotCode, Micro QR Code und QR Code:
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. Wird dieser Parameter auf 'all' gesetzt, werden alle möglichen Kandidaten genutzt. Wenn 'candidate_selection' auf 'default' gesetzt ist, werden weniger Kandidatenregionen verwendet.
DotCode:
Bestimmt die maximal zulässige Fehlerkorrektur. Aufgrund der hohen Fehlerkorrekturkapazität, ist es möglich 'false positive' DotCode Kandidaten erfolgreich zu dekodieren. Besonders Kandidaten, die nur einen kleinen Teil eines echten DotCode-Symbols bedecken, werden aufgrund der Fehlerkorrektur eventuell erfolgreich dekodiert. Der Grund dafür ist, dass DotCode-Symbole so gut wie jede Größe annehmen können. Das macht es schwieriger falsche Kandidaten auszusortieren. Um diesem Problem entgegenzuwirken, kann der Parameter 'max_allowed_error_correction' verwendet werden, um anzugeben wie viel Prozent der Fehlerkorrekturkapazität genutzt werden dürfen. Standardmäßig ist der Wert auf 0.9, also 90% gesetzt. Diese Wahl hilft dabei die Anzahl an falsch dekodierten Kandidaten zu reduzieren, während die Anzahl an richtig dekodierten Kandidaten nur minimal beeinflusst wird. Wird der Wert z.B. auf 0.5 herabgesetzt, werden nur noch die Kandidaten als erfolgreich dekodierte Ergebnisse zurückgegeben, die mit maximal 50% genutzter Fehlerkorrektur dekodiert werden konnten.
Wertebereich: [0.0 .. 1.0]
Default: '0.9'
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.
Default: 'polarity'
Werteliste: 'additional_levels', 'alternating_pattern_tolerance', 'candidate_selection', 'contrast_min', 'contrast_tolerance', 'decoding_scheme', 'deformation_tolerance', 'discard_undecoded_candidates', 'finder_pattern_tolerance', 'format', 'max_allowed_error_correction', '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', 'quality_isoiec15415_decode_algorithm', 'quality_isoiec15415_reflectance_reference', 'quality_isoiec15415_smallest_module_size', 'slant_max', 'small_modules_robustness', 'strict_fp_and_qz', '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