F_VN_FindTemplateWalshExp

Syntax

Definition:

FUNCTION F_VN_FindTemplateWalshExp : HRESULT
VAR_INPUT
    ipSrcImage         : ITcVnImage;
    ipTemplateImage    : ITcVnImage;
    ipMatches          : Reference To  ITcVnContainer;
    fMatchThreshold    : REAL;
    nProjections       : UDINT;
    eOptions           : UDINT;
    nRotations         : UDINT;
    fScaleFactor       : REAL;
    eInterpolationType : ETcVnInterpolationType;
    ipMatchValues      : Reference To  ITcVnContainer;
    hrPrev             : HRESULT;
END_VAR

Inputs

Name	Type	Description
ipSrcImage	ITcVnImage	Source image (USINT or SINT, 1 or 3 channels)
ipTemplateImage	ITcVnImage	Template image (same type as ipSrcImage, smaller width and height)
ipMatches	Reference To ITcVnContainer	Returns the matching positions (container type depends on eOptions; ContainerType_Vector_TcVnRotatedRectangle or ContainerType_Vector_TcVnVector4_REAL, where each element contains the center (x, y), the rotation angle in degrees, and the matching value of ipTemplateImage in ipSrcImage; container elements sorted by relevance (best match first))
fMatchThreshold	REAL	Threshold to separate relevant from irrelevant matches (0..1, 1.0 would be a perfect match.)
nProjections	UDINT	Number of Walsh projections to be used. The higher nProjections the more details are considered for matching. As the most relevant information is captured by the first Walsh projections, a small number (e.g., 5, 10, 25, or 50) is sufficient for many use cases. Each projection requires additional computation time. Therefore, it is advantageous to choose a low number of Walsh projections as long as the matching requirements are fulfilled. The allowed maximum of nProjections is determined by the width and the height of the template image.
eOptions	UDINT	Flags controlling the matching process. (see ETcVnFindTemplateWalshOptions; default: TCVN_FTWO_NONE)
nRotations	UDINT	Number of rotations to be checked. (valid values: 1 (0°), 2 (0° and 180°), 4 (0°, 90°, 180°, and 270°), 8 (0°, 45°, ..., 315°), 16 (0°, 22.5°, ..., 337.5°), and 32 (0°, 11.25°, ..., 348.75°); default: 1)
fScaleFactor	REAL	Factor (0..1] to reduce source and template image width and height for better performance (but less accuracy!)
eInterpolationType	ETcVnInterpolationType	Image resize interpolation type (only used if fScaleFactor != 1, TCVN_IT_BILINEAR recommended for most cases)
ipMatchValues	Reference To ITcVnContainer	Optionally returns the matching values (ContainerType_Vector_REAL, same size and sort order as ipMatches. Set to 0 if not required.)
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_FindTemplateWalshExp ist die Expert-Variante von F_VN_FindTemplateWalsh und enthält zusätzliche Parameter. Sie verwendet die Walsh-Transformation, um alle Instanzen eines Referenzbildes (Template) im Suchbild zu lokalisieren. Die Orientierung der gefundenen Objekte kann dabei mit einer festen Schrittweite überprüft werden, die sich aus der Anzahl der zu prüfenden Rotationen im Bereich von 0° bis 360° ergibt.

Parameter

Eingangsbild

Das Eingangsbild ipSrcImage muss ein 1- oder 3-kanaliges Bild vom Typ USINT oder SINT sein. Bei einem 3-kanaligen Bild wird das Matching gemeinsam in allen drei Kanälen durchgeführt, was auch zu mehr Rechenzeit führt.

Templatebild

Das Templatebild ipTemplateImage muss vom gleichen Typ wie ipSrcImage sein und kleinere Dimensionen (Höhe und Breite) aufweisen als das Eingangsbild.

Liste an gefundenen Match-Positionen

Alle im Eingangsbild gefundenen Matches werden nach ihrem Match-Value sortiert (bestes Match zuerst) und im Container ipMatches vom Typ ContainerType_Vector_TcVnVector4_REAL zurückgegeben. Jeder TcVnVector4_REAL enthält die Koordinaten des Zentrums, die Rotation in Grad und den Match-Value (fX, fY, fAngleDeg, fMatchValue).

Match-Schwellwert

Mit dem Schwellwert fMatchThreshold (0 bis 1.0) lassen sich irrelevante von relevanten Matches trennen, wobei 1.0 einem perfekten Match entspricht. Der Wert ist abhängig von der Beschaffenheit des Eingangsbildes sowie den gewählten Parametern und muss entsprechend angepasst werden.

Anzahl an Walsh Projektionen

Der Parameter nProjections legt fest, wie viele Walsh-Projektionen für das Matching verwendet werden. Niedrige Projektionszahlen erfassen vor allem grobe Bildstrukturen, höhere Projektionszahlen bilden zunehmend feinere Details ab, erhöhen jedoch die Rechenzeit. Daher sollte nProjections so niedrig wie möglich, aber so hoch wie nötig gewählt werden. In vielen Anwendungen sind 5–50 Projektionen ausreichend. Die zulässige Obergrenze von nProjections ist durch die Breite und Höhe des Template-Bildes begrenzt.

Optionen

Mit eOptions können Optionen (ETcVnFindTemplateWalshOptions) angegeben werden, die die Funktionsweise und Ergebnisausgabe beeinflussen. Mehrere Optionen lassen sich per OR-Verknüpfung kombinieren. Folgende Optionen stehen zur Verfügung:

TCVN_FTWO_NONE: Keine speziellen Optionen.
TCVN_FTWO_FUSE_MATCHES: Fasst Treffer ähnlicher Position und Rotation zusammen. Das Setzen dieser Option wird empfohlen. Für die Entwicklung und Parametrierung kann eine Deaktivierung nützlich sein, um alle Rohdetektionen einzusehen.
TCVN_FTWO_ROTATED_RECTANGLE: Gibt Ergebnisse direkt als ContainerType_Vector_TcVnRotatedRectangle zurück. Die zugehörigen Match-Werte können separat über ipMatchValues ausgelesen werden.
TCVN_FTWO_SKIP_DC: Überspringt die DC-Komponente bei der Ähnlichkeitsberechnung, was die Robustheit gegenüber Beleuchtungsänderungen verbessern kann. Erfordert in der Regel eine höhere Anzahl an Projektionen.
TCVN_FTWO_WD_STOP_CORRECTION: Passt den Match-Schwellwert heuristisch an, wenn die Verarbeitung durch einen Watchdog-Abbruch unterbrochen wurde.

Anzahl an prüfenden Rotationen

Die Anzahl der zu prüfenden Rotationsschritte nNumRotations bestimmt die Winkelauflösung beim Matching. Gültige Werte sind:

1 (0°)
2 (0° und 180°)
4 (0°, 90°, 180° und 270°)
8 (0°, 45°, ..., 315°)
16 (0°, 22.5°, ..., 337.5°)
32 (0°, 11.25°, ..., 348.75°)

Der ausgegebene Rotationswinkel des finalen Matches kann auch zwischen den definierten Rotationsschritten liegen. Werden bei mehreren Winkelschritten Matches gefunden und ist die Option TCVN_FTWO_FUSE_MATCHES gesetzt, wird der endgültige Winkel durch Interpolation ermittelt.

Skalierungsfaktor

Der Faktor fScaleFactor (0 bis 1.0) dient zur Reduzierung der Auflösung von Eingangs- und Templatebild. Eine Verringerung der Bildgröße verbessert die Performance, verringert jedoch die Genauigkeit des Matchings.

Interpolationstyp

Der Parameter eInterpolationType bestimmt das Verfahren für die Bildskalierung (wird nur ausgewertet, wenn fScaleFactor ungleich 1 ist). Für die meisten Anwendungsfälle wird TCVN_IT_BILINEAR empfohlen.

Rückgabe der Match-Werte

Der Parameter ipMatchValues ist ein optionaler Rückgabe-Container (ContainerType_Vector_REAL) für die reinen Match-Werte. Er weist die gleiche Länge und Sortierung wie ipMatches auf. Wird die Option TCVN_FTWO_ROTATED_RECTANGLE nicht verwendet, sind diese Werte redundant, da sie bereits in den Rückgabestrukturen von ipMatches enthalten sind. Ist die separate Ausgabe nicht erforderlich, sollte der Parameter auf 0 gesetzt werden.

Beispiele

Walsh Template Matching mit Rotation

Required License

TC3 Vision Matching

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