F_VN_DetectCodesNeuralNetwork

Detect various code types, such as barcodes, QR codes, Data Matrix codes and DotCodes within the provided image using a trained neural network model based on eModelType. The detected code regions and types (if supported) are sorted by their model confidence, from highest to lowest.
Can use available TwinCAT Job Tasks for executing parallel code regions.

Syntax

Definition:

FUNCTION F_VN_DetectCodesNeuralNetwork : HRESULT
VAR_INPUT
    ipSrcImage    : ITcVnImage;
    ipCodeRegions : Reference To  ITcVnContainer;
    ipCodeTypes   : Reference To  ITcVnContainer;
    eModelType    : ETcVnCodeDetectionModel;
    nCodeType     : ULINT;
    hrPrev        : HRESULT;
END_VAR

Inputs

Name	Type	Description
ipSrcImage	ITcVnImage	Source image (USINT elements, 1 or 3 channels)
ipCodeRegions	Reference To ITcVnContainer	Returns the code positions as upright rectangles or rotated rectangles based on eModelType (ContainerType_Vector_TcVnRectangle_DINT or ContainerType_Vector_TcVnRotatedRectangle; Non-zero interface pointers are reused.)
ipCodeTypes	Reference To ITcVnContainer	Returns the code type (ETcVnCodeType) of each detected code (ContainerType_Vector_ULINT; Non-zero interface pointers are reused), set to 0 if not required.
eModelType	ETcVnCodeDetectionModel	Type of the neural network model for code detection. Different neural network models are available, including models specialized for 1D codes, 2D codes, or all code types.
nCodeType	ULINT	Specifies the code type(s) to detect. Multiple values from the ETcVnCodeType enumeration can be combined by performing a bitwise OR operation.
hrPrev	HRESULT	HRESULT indicating the result of previous operations (If SUCCEEDED(hrPrev) equals false, no operation is executed.)

Return value

HRESULT

Weiterführende Informationen

Die Funktion F_VN_DetectCodesNeuralNetwork verwendet neuronale Netzwerke, um 1D- und 2D-Codes im Eingangsbild zu lokalisieren und deren Typ zu klassifizieren. Im Gegensatz zu den klassischen Code Reading-Funktionen findet hierbei keine Dekodierung des Code-Inhalts statt. Die F_VN_DetectCodesNeuralNetwork wird zur Vorlokalisierung verwendet, wobei die neuronalen Netzwerkmodelle probabilistische Detektionsergebnisse in Form von Bounding Boxen und den Codetypen liefern.

Diese Code-Regionen können im nächsten Schritt mit den entsprechenden Code Reading Funktionen dekodiert werden. Aufgrund der vorgegeben Region reduziert sich die Ausführungszeit, da die Lokalisierung des Codes auf einen kleinen Bildbereich beschränkt wird. Dies ermöglich auch die direkte Verwendung der Code-Reading Funktionen, die eine vorgegebene ROI benötigen.

Parameter

ipSrcImage

Das Eingangsbild ipSrcImage muss ein 1-kanaliges oder 3-kanaliges Bild vom Typ USINT (8 Bit) sein.

Abhängig vom gewählten Modell wird das Bild intern automatisch konvertiert. Das spezifische Eingangsformat und -größe der Modelle ist in der Beschreibung von ETcVnCodeDetectionModel aufgeführt. Um die internen Konvertierungsschritte zu reduzieren und damit auch die benötigte Rechenzeit, empfiehlt es sich das Bild mit der gleichen Anzahl an Kanälen zu übergeben, falls es vor dem Aufruf in der Form schon vorhanden ist.

Generell sollte beachtet werden, dass das Seitenverhältnis des Eingangsbildes dem des Modells möglichst ähnlich ist. Andernfalls kann es bei der internen Skalierung zu Verzerrungen kommen, welche die Detektionsqualität beeinträchtigen.

ipCodeRegions

Der Parameter ipCodeRegions gibt die im Eingangsbild lokalisierten Code-Regionen als Container vom Typ ContainerType_Vector_TcVnRectangle_DINT oder ContainerType_Vector_TcVnRotatedRectangle zurück. Welcher Containertyp verwendet wird, hängt vom übergebenen eModelType ab. Die Einträge in der Liste sind absteigend nach ihrer Konfidenz sortiert, beginnend mit der höchsten Wahrscheinlichkeit.

ipCodeTypes

Der Parameter ipCodeTypes gibt die klassifizierten Typen der erkannten Codes in der gleichen Reihenfolge wie ipCodeRegions zurück. Der Rückgabe-Container ist vom Typ ContainerType_Vector_ULINT und enthält Werte des Enums ETcVnCodeType. Welche Codetypen zurückgegeben werden hängt vom Erkennungsumfang des verwendeten Modells ab.

eModelType

Der Parameter eModelType vom Typ ETcVnCodeDetectionModel gibt das neuronale Netzwerkmodell für die Code-Erkennung vor. Die Wahl des Modells erfolgt in zwei Dimensionen: dem Erkennungsumfang (welche Code-Typen unterstützt werden) und der Eingangsauflösung (Genauigkeit vs. Geschwindigkeit).

Modelltyp	Erkennungsumfang
TCVN_CDM_DETECT_1_x	1D- und 2D-Codes mit Klassifizierung: `TCVN_CT_1D` `TCVN_CT_2D` `TCVN_CT_QR` `TCVN_CT_DATAMATRIX` `TCVN_CT_DOTCODE`
TCVN_CDM_DETECT_2_x	Nur 1D-Codes (`TCVN_CT_1D`)
TCVN_CDM_DETECT_3_x	Nur 2D-Codes (`TCVN_CT_2D`)

Jede der oben genannten Modeltypen ist in drei Auflösungsstufen verfügbar. Das Suffix (_1, _2, _3) definiert die Größe, auf die das Bild intern skaliert wird:

..._1: kleine Bildgröße (schnellste Verarbeitung, für Anwendungen mit großen Codes oder hohen Performance-Anforderungen)
..._2: mittlere Bildgröße (Ausgewogenes Verhältnis zwischen Geschwindigkeit und Genauigkeit. Empfohlen für die meisten Anwendungen)
..._3: große Bildgröße (Höchste Auflösung, beste Erkennung kleiner oder weit entfernter Codes, höchste Verarbeitungszeit)

Die Wahl des Modells beeinflusst sowohl die Detektionsgeschwindigkeit als auch die Genauigkeit. Die Modelle mit reduziertem Erkennungsumfang, wie die für nur 1D- oder 2D-Codes, bieten eine höhere Performance.

nCodeType

Der Parameter nCodeType dient als Filter, um die Detektion auf bestimmte Code-Typen (ETcVnCodeType) einzuschränken. Um alle vom Modell unterstützten Codes zu detektieren, kann der Wert TCVN_CT_ANY verwendet werden. Alternativ lassen sich spezifische Typen durch eine OR-Verknüpfung kombinieren (z. B. TCVN_CT_QR_CODE OR TCVN_CT_DATAMATRIX). Es ist zu beachten, dass dieser Filter sich nur auf den Erkennungsumfang des gewählten Modells eModelType bezieht. Wenn der Filter nicht zum Erkennungsumfang passt, wird ein 0x70E HRESULT zurückgegeben.

Anwendung

Voraussetzung für die Ausführung ist die einmalige Initialisierung der zu verwendenden Modelle mithilfe des Funktionsbausteins FB_VN_InitializeFunction.

Der folgende Code-Ausschnitt demonstriert den Aufruf der Funktion F_VN_DetectCodesNeuralNetwork zur gleichzeitigen Detektion von 1D- und 2D-Codes:

hr := F_VN_DetectCodesNeuralNetwork(
        ipSrcImage      := ipImageIn,
        ipCodeRegions   := ipCodeRegions,
        ipCodeTypes     := ipCodeTypeResult,
        eModelType      := TCVN_CDM_DETECT_1_2,
        nCodeType       := ,
        hrPrev          := hr);

Die detektierten Regionen können im Anschluss als ROI gesetzt und durch eine passende Code Reading-Funktion dekodiert werden. Um eine robuste Dekodierung zu gewährleisten, wird empfohlen, die gefundenen Bereiche vorab mit F_VN_ResizeRegion_TcVnRectangle_DINT zu vergrößern. Dies stellt sicher, dass die für die Dekodierung erforderlichen Ruhezonen im Bildausschnitt enthalten sind.

	Hinweise zur Performance Die Ausführung der Modelle profitiert erheblich von CPU-Parallelisierung. Es wird daher empfohlen, den PLC-Code auf isolierten CPU-Kernen auszuführen und diese dedizierten Job Tasks zuzuweisen.

Beispiele

Required License

TC3 Vision Code Reading

System Requirements

Development environment	Target platform	PLC libraries to include
TwinCAT V3.1.4026 or later	PC or CX (x64) with min. PL50, e.g. Intel 4-core Atom CPU	Tc3_Vision