F_VN_FindTemplateWalsh_AngleRange

F_VN_FindTemplateWalsh_AngleRange 1:

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).
Can use available TwinCAT Job Tasks for executing parallel code regions.
Can return partial results when canceled by Watchdog.

Syntax

Definition:

FUNCTION F_VN_FindTemplateWalsh_AngleRange : HRESULT
VAR_INPUT
    ipSrcImage      : ITcVnImage;
    ipTemplateImage : ITcVnImage;
    ipMatches       : Reference To  ITcVnContainer;
    fMatchThreshold : REAL;
    nProjections    : UDINT;
    fStartAngle     : LREAL;
    fStopAngle      : LREAL;
    nAngles         : UDINT;
    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 (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

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_FindTemplateWalsh_AngleRange 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.

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