F_VN_FindTemplateWalshExp_AngleRange
Match a template image with every location in the source image (using the Walsh transform) and evaluate the comparison results. Returns a sorted list of possible matches (best match first). (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_FindTemplateWalshExp_AngleRange : HRESULT
VAR_INPUT
ipSrcImage : ITcVnImage;
ipTemplateImage : ITcVnImage;
ipMatches : Reference To ITcVnContainer;
fMatchThreshold : REAL;
nProjections : UDINT;
fStartAngle : LREAL;
fStopAngle : LREAL;
nAngles : UDINT;
eOptions : UDINT;
fScaleFactor : REAL;
eInterpolationType : ETcVnInterpolationType;
ipMatchValues : Reference To ITcVnContainer;
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) | |
|
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. |
|
fStartAngle |
LREAL |
First search angle |
|
fStopAngle |
LREAL |
Last search angle |
|
nAngles |
UDINT |
Number of different search angles to be used |
|
eOptions |
UDINT |
Flags controlling the matching process. (see ETcVnFindTemplateWalshOptions; default: TCVN_FTWO_NONE) |
|
fScaleFactor |
REAL |
Factor (0..1] to reduce source and template image width and height for better performance (but less accuracy!) |
|
eInterpolationType |
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 indicating the result of previous operations (If SUCCEEDED(hrPrev) equals false, no operation is executed.) |
Weiterführende Informationen
Die Funktion F_VN_FindTemplateWalshExp_AngleRange ist die Expert-Variante von F_VN_FindTemplateWalsh_AngleRange und enthält zusätzliche Parameter. Sie verwendet die Walsh-Transformation, um alle Instanzen eines Referenzbildes (Template) im Suchbild zu lokalisieren. Sie beschränkt den Suchbereich für die Objektrotation auf einen frei definierbaren Winkelbereich mit variabler Schrittweite. Dadurch können Winkelgenauigkeit und Laufzeit gezielt optimiert werden. Falls der Winkelbereich des gesuchten Objekts nicht bekannt oder nicht einschränkbar ist, sollte F_VN_FindTemplateWalsh verwendet 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.
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.
Winkelbereich
Der Suchbereich für die Objektrotation wird durch fStartAngle und fStopAngle als LREAL-Werte in Grad definiert. Beide Parameter geben die äußeren Grenzen des geprüften Winkelbereichs an. Wird der Suchbereich zu gering gewählt, besteht das Risiko, dass tatsächlich vorhandene Objekte außerhalb des Bereichs nicht erkannt werden. Es empfiehlt sich, einen ausreichenden Toleranzpuffer einzukalkulieren.
Anzahl der Winkelschritte
Der Parameter nAngles bestimmt die Anzahl der gleichmäßig verteilten Suchwinkel innerhalb des definierten Winkelbereichs. Im Gegensatz zu F_VN_FindTemplateWalsh kann hier eine beliebige Anzahl gewählt werden. Dies ermöglicht eine feinere Winkelauflösung in einem definierten Bereich.
Beispiel: Mit fStartAngle = -30°, fStopAngle = 30° und nAngles = 13 werden die Winkel −30°, −25°, −20°, …, +25°, +30° geprüft.
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 alsContainerType_Vector_TcVnRotatedRectanglezurück. Die zugehörigen Match-Werte können separat überipMatchValuesausgelesen 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.
TCVN_FTWO_MATCH_OPPOSITE_RANGE: Führt das Matching zusätzlich mit den entgegengesetzten Winkeln (um 180° gedreht) durch. Diese Option ist nützlich, wenn nicht sicher ist, ob ein Objekt um 180° gedreht vorliegen kann. Sie verdoppelt effektiv den geprüften Winkelbereich, ohne den gesamten 360°-Bereich durchsuchen zu müssen.
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.
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 |