F_VN_MatchTemplateWalshExp
Match a template image with every location in the source image (using the Walsh transform) and return the comparison results. (expert function)
Can use available TwinCAT Job Tasks for executing parallel code regions.
Can return partial results when canceled by Watchdog.
Syntax
Definition:
FUNCTION F_VN_MatchTemplateWalshExp : HRESULT
VAR_INPUT
ipSrcImage : ITcVnImage;
ipTemplateImage : ITcVnImage;
ipResultImage : Reference To ITcVnImage;
nProjections : UDINT;
eOptions : UDINT;
nRotations : UDINT;
hrPrev : HRESULT;
END_VARInputs
|
Name |
Type |
Description |
|---|---|---|
|
ipSrcImage |
Source image (USINT or SINT, 1 or 3 channels) | |
|
ipTemplateImage |
Template image (same type as ipSrcImage, smaller width and height) | |
|
ipResultImage |
Reference To ITcVnImage |
Returns the result image (REAL, normalized to [0..1], nRotations channel(s), dimensions: (ipSrcImage.width - ipTemplateImage.width + 1) x (ipSrcImage.height - ipTemplateImage.height + 1). The best match is the global minimum over all channels. The position in ipResultImage is the top-left corner of ipTemplateImage position in ipSrcImage. The rotation can be inferred from the channel the minimum is found in.) |
|
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 ETcVnMatchTemplateWalshOptions) |
|
nRotations |
UDINT |
Number of rotations to be checked. (valid values: 1 (0°), 2 (0° and 180°), and 4 (0°, 90°, 180°, and 270°; only for square images)) |
|
hrPrev |
HRESULT indicating the result of previous operations (If SUCCEEDED(hrPrev) equals false, no operation is executed.) |
Weiterführende Informationen
Die Funktion F_VN_MatchTemplateWalshExp ist die Expert-Variant von F_VN_MatchTemplateWalsh und enthält zusätzliche Parameter. Sie verwendet die Walsh-Transformation, um alle Instanzen eines Referenzbildes (Template) im Suchbild zu lokalisieren und gibt die Ähnlichkeitswerte als Ergebnisbild zurück. Im Gegensatz zur Standardvariante kann das Template dabei in mehreren Rotationsschritten geprüft werden.
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.
Ergebnisbild
Das Ergebnisbild ipResultImage ist ein einkanaliges REAL-Bild mit folgenden Dimensionen:
- Breite:
ipSrcImage.Width - ipTemplateImage.Width + 1 - Höhe:
ipSrcImage.Height - ipTemplateImage.Height + 1 - Kanäle: Ein Kanal pro geprüftem Rotationsschritt (Default: 1)
Jeder Pixelwert repräsentiert die Ähnlichkeit zwischen dem Template und dem entsprechenden Bildausschnitt im Eingangsbild. Ein kleinerer Wert bedeutet dabei eine höhere Übereinstimmung. Das globale Minimum über alle Kanäle markiert den besten Match. Die Position des Minimums im Ergebnisbild entspricht der linken oberen Ecke der Templateposition im Eingangsbild.
Zur Auswertung kann beispielsweise F_VN_MinPixelValue verwendet werden, um den minimalen Pixelwert sowie die zugehörige Position und den Kanal zu bestimmen.
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 (ETcVnMatchTemplateWalshOptions) 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_MTWO_NORMED: Normalisiert die Elemente des Ausgabebildes auf den Wertebereich[0, 1.0].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.
Anzahl an prüfenden Rotationen
Der Parameter nRotations legt die Anzahl der zu prüfenden Rotationsschritte fest und definiert damit sowohl die untersuchten Winkellagen als auch die resultierende Anzahl der Kanäle im Ergebnisbild. Der Kanal, in dem das Minimum gefunden wird, entspricht dabei dem Rotationswinkel des Matches. Gültige Werte sind:
- 1 (0°)
- 2 (0° und 180°)
- 4 (0°, 90°, 180° und 270°) — nur für quadratische Templatebilder
Verwandte Funktionen
- F_VN_FindTemplateWalsh(Exp): Sucht ein Template im Eingangsbild und gibt eine sortierte Liste gefundener Matches zurück.
- F_VN_FindTemplateWalsh(Exp)_AngleRange: Wie
F_VN_FindTemplateWalsh(Exp), jedoch mit frei definierbarem Winkelbereich und beliebiger Anzahl an Winkelschritten für gezielte Laufzeit- und Genauigkeitsoptimierung. - F_VN_MatchTemplateWalsh(Exp): Vergleicht ein Template mit jedem Ort im Eingangsbild und gibt das rohe Ergebnisbild zur applikationsspezifischen Nachverarbeitung zurück.
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 |