F_VN_OCRExp

Detects and recognizes characters in a binary image (white characters on black background). (expert function)
Can use available TwinCAT Job Tasks for executing parallel code regions.

Syntax

Definition:

FUNCTION F_VN_OCRExp : HRESULT
VAR_INPUT
    ipSrcImage      : ITcVnImage;
    eModel          : ULINT;
    ipCharacters    : Reference To  ITcVnContainer;
    sPattern        : STRING;
    eOcrOptions     : UDINT;
    ipBoundingBoxes : Reference To  ITcVnContainer;
    ipConfidences   : Reference To  ITcVnContainer;
    hrPrev          : HRESULT;
END_VAR
VAR_OUTPUT
    fMinConfidence  : REAL;
END_VAR

Inputs

Name	Type	Description
ipSrcImage	ITcVnImage	Source image (USINT elements, 1 or 3 channels). The required number of channels depends on the selected model type.
eModel	ULINT	Selection of OCR model types (ETcVnOcrModelType)
ipCharacters	Reference To ITcVnContainer	Returns the recognized characters (ContainerType_Vector_String_SINT)
sPattern	STRING	String pattern containing the format in which characters are presented. Pattern handling support depends on the selected model type.
eOcrOptions	UDINT	Specifies which options must be applied to the function (ETcVnOcrOptions)
ipBoundingBoxes	Reference To ITcVnContainer	Returns the corresponding bounding boxes of the recognized characters (ContainerType_Vector_TcVnRectangle_DINT, optional, set to 0 if not required). Returns an empty container when bounding boxes are not supported by the selected model type.
ipConfidences	Reference To ITcVnContainer	Returns the corresponding classification confidences of the recognized characters (ContainerType_Vector_REAL, optional, set to 0 if not required). When the novelty detector is selected, the confidence value is a combination of the classification confidence and the novelty detection confidence. If a character is identified as unknown, the total confidence equals the novelty detection confidence.
hrPrev	HRESULT	HRESULT indicating the result of previous operations (If SUCCEEDED(hrPrev) equals false, no operation is executed.)

Outputs

Name	Type	Description
fMinConfidence	REAL	Returns the minimum value of the confidences across all recognized characters. Characters rejected by the novelty detector are excluded from this minimum. Always computed, even if ipConfidences is not requested.

Return value

HRESULT

Weiterführende Informationen

Die Funktion F_VN_OCRExp ist die Expert-Variante von F_VN_OCR. Sie enthält zusätzliche Parameter.

Parameter

Eingangsbild

Das Format des Eingangsbildes, das an ipSrcImage übergeben werden muss, hängt vom verwendeten Modell ab:

Bei den Modellen, die mit TCVN_OMT_ beginnen, muss ein 1-kanaliges Binärbild übergeben werden, auf dem nur weiße Zeichen auf schwarzem Hintergrund zulässig sind.
Bei dem Modell, das mit TCVN_OMT_CNN_ beginnt, muss ein 1-kanaliges oder 3-kanaliges Bild vom Typ USINT (8 Bit) übergeben werden, das intern automatisch konvertiert wird. Das spezifische Eingangsformat und -größe des Modells ist in der Beschreibung von ETcVnOcrModelType 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 Erkennungsqualität beeinträchtigen.

Modell

Die Modell-Typen von ETcVnOcrModelType, die bei einem Funktionsaufruf zur Klassifizierung der Zeichen verwendet werden sollen, müssen an eModel übergeben werden. Um mehrere Modelle mit einem Funktionsaufruf verwenden zu können, muss ein Zeichenkettenmuster über sPattern angegeben werden. Die Modelle, die mit TCVN_OMT_ beginnen, können mit einem OR verkettet werden, eine Vermischung von klassischen und CNN Machine Learning Modellen wird nicht unterstützt.

Um die einzelnen Modelle verwenden zu können, müssen diese zuvor mit dem Baustein FB_VN_InitializeFunction initialisiert werden.

Erkannte Zeichen

Die erkannten Zeichen werden über die Referenz ipCharacters zurückgegeben. Die von einem optionalen Novelty-Detektor als unbekannt eingestuften Zeichen werden im zurückgegebenen String durch „¤“ (ASCII-Code 164, 0xA4) gekennzeichnet.

Zeichenkettenmuster

Über sPattern kann ein Zeichenkettenmuster, mit dem erwarteten Format der zu erkennenden Zeichenkette, übergeben werden.

Unterstützte Formatierungen und deren Bedeutung:

! (Ausrufezeichen) zum Ignorieren von Zeichen (gilt nicht für Leerzeichen)
. (Punkt) für ein beliebiges Zeichen (gilt nicht für Leerzeichen)
Die Verwendung des Punkts wird nur mit dem Modell TCVN_OMT_NUMBERS_SC_UCLETTERS unterstützt, ansonsten wirkt sich der Punkt wie ein Ausrufezeichen aus und es wird ein S_FALSE ausgegeben.
_ (Unterstrich) für ein Leerzeichen (unabhängig von eOcrOptions)
d (Zahl) für eine erwartete Zahl von 0-9
# (Sonderzeichen) für ein erwartetes Sonderzeichen, unterstützt werden . / - : = +
u (Großbuchstabe) für einen erwarteten Großbuchstaben von A-Z

Wenn ein optionaler Novelty-Detektor verwendet wird und der ein unbekanntes Zeichen erkennt, wird immer ein S_FALSE ausgegeben.

Das TCVN_OMT_CNN_NUMBERS_SC_LETTERS Modell unterstützt die Verwendung von sPattern nicht.

Optionen

Mit eOcrOptions können Optionen (ETcVnOcrOptions) angegeben werden, die die Funktionsweise und Ergebnisausgabe beeinflussen. Die Optionen können mit einem OR verknüpft werden. Allerdings darf pro Funktionsgruppe, wie zum Beispiel dem Novelty-Level, jeweils nur eine Option ausgewählt werden. Wenn keine Optionen benötigt werden, muss eine 0 oder TCVN_OO_NONE übergeben werden.

TCVN_OO_WITHBLANKS: Gibt an, dass gefundene Leerzeichen im Ergebnis mit ipCharacters ausgegeben werden sollen. Standardmäßig sind keine Leerzeichen im Ergebnis enthalten.
TCVN_OO_NOVELTY_LEVEL1: Der Novelty-Detektor arbeitet mit hoher Empfindlichkeit gegenüber Neuheiten. Er filtert die meisten unbekannten Zeichen heraus, kann jedoch auch gültige Zeichen ablehnen.
TCVN_OO_NOVELTY_LEVEL2: Der Novelty-Detektor arbeitet mit einer ausgewogenen Empfindlichkeit gegenüber Neuheiten. Er filtert viele unbekannte Zeichen heraus, während nur wenige gültige Zeichen zurückgewiesen werden.
TCVN_OO_NOVELTY_LEVEL3: Der Novelty-Detektor wird mit verringerter Empfindlichkeit gegenüber Neuheiten eingesetzt. Er filtert eindeutig unbekannte Zeichen heraus und lehnt gültige Zeichen so gut wie nie ab.

Die Novelty-Detektor Option wird nur von den Modellen, die mit TCVN_OMT_ beginnen, unterstützt.

Bounding Boxes

Über die Referenz ipBoundingBoxes können optional die entsprechenden Bounding Boxes der erkannten Zeichen zurückgegeben werden. Wenn keine Bounding Boxes benötigt werden, kann der Wert 0 übergeben werden.

Das TCVN_OMT_CNN_NUMBERS_SC_LETTERS Modell unterstützt die Verwendung von ipBoundingBoxes nicht.

Konfidenzen

Über die Referenz ipConfidences können optional die entsprechenden Klassifizierungskonfidenzen der erkannten Zeichen zurückgegeben werden. Ist die Option zur Kennzeichnung unbekannter Zeichen ausgewählt, setzt sich der Konfidenzwert aus der Klassifizierungskonfidenz und der Konfidenz des Novelty-Detektors zusammen. Wird ein Zeichen als unbekannt eingestuft, entspricht die Konfidenz dem des Novelty-Detektors. Wenn keine Konfidenzen benötigt werden, kann der Wert 0 übergeben werden.

Minimale Konfidenz

Der optionale Rückgabewert fMinConfidence gibt den minimalen Konfidenz-Wert aller gefundenen Zeichen zurück.

Anwendung

Ein Aufruf der OCRExp-Funktion, mit zwei Modellen zur Erkennung von Zahlen und Großbuchstaben, mit anschließendem String-Export sieht z.B. so aus:

sPattern := 'dd!uuu!dddd'; // e.g. 02-FEB-2024

hr := F_VN_OCRExp(
    ipSrcImage      := ipBinaryImage,
    eModel          := TCVN_OMT_NUMBERS OR TCVN_OMT_UCLETTERS,
    ipCharacters    := ipCharactersResults,
    sPattern        := sPattern,
    eOcrOptions     := eOcrOptions,
    ipBoundingBoxes := ipBoundingBoxes,
    ipConfidences   := ipConfidences,
    hrPrev          := hr,
    fMinConfidence  => fMinConfidence);

// Export character to string
hr := F_VN_ExportSubContainer_String(ipCharactersResults, 0, sText, 255, hr);

// Get the bounding box of the first element
hr := F_VN_GetAt_TcVnRectangle_DINT(ipBoundingBoxes, stRectangle, 0, hr); 

// Get the Confidence value of the first element
hr := F_VN_GetAt_REAL(ipConfidences, fConfidence, 0, hr);

Zur Auswertung der Konfidenz-Werte oder zum Zeichnen von Bounding Boxen kann über GetAt auf einzelne Elemente der Container zugegriffen werden. Wenn man jedoch auf mehrere oder alle Elemente eines Containers zugreifen möchte, empfiehlt es sich, eine Schleife zu programmieren oder den ipConfidences Container komplett als Array zu exportieren.

Beispiele:

OCR

Required License

TC3 Vision OCR

System Requirements

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