F_VN_LocateAxisAlignedEdgesExp
Locate the position of multiple occurring edges inside a specified search window. The edges inside the search window must be straight and aligned to one of the image axes. They are located by interpolating the peaks of the first Gaussian derivative of the pixel intensities. (expert function)
Syntax
Definition:
FUNCTION F_VN_LocateAxisAlignedEdgesExp : HRESULT
VAR_INPUT
ipSrcImage : ITcVnImage;
ipEdgePoints : Reference To ITcVnContainer;
END_VAR
VAR_IN_OUT
aStartPoint : TcVnPoint2_DINT;
aEndPoint : TcVnPoint2_DINT;
END_VAR
VAR_INPUT
nSearchWindowHeight : UDINT;
nKernelSize : UDINT;
nNumEdges : UDINT;
eEdgeSelection : ETcVnEdgeSelection;
fMinStrength : REAL;
fSigma : REAL;
ipEdgeStrengths : Reference To ITcVnContainer;
ipDerivative : Reference To ITcVnImage;
hrPrev : HRESULT;
END_VAR
VAR_OUTPUT
fAvgStrength : REAL;
END_VARInputs
|
Name |
Type |
Description |
|---|---|---|
|
ipSrcImage |
Source image (1 channel of type ET_USINT, ET_UINT, ET_INT or ET_REAL) | |
|
ipEdgePoints |
Reference To ITcVnContainer |
Returns the detected edge points (ContainerType_Vector_TcVnPoint2_REAL) |
|
nSearchWindowHeight |
UDINT |
Specifies the height of the search window, i.e. the number of rows for horizontal or columns for vertical search directions, centered around the line between aStartPoint and aEndPoint. Depending on the orientation, the rows or columns inside that window are averaged and the edges are located on that averaged row or column. Therefore it is important that the edges inside the defined search window are straight and perpendicular to the search direction. |
|
nKernelSize |
UDINT |
The size of the Gaussian derivative kernel, that is used to locate the edges. The size must be odd and >= 3 (5 or 7 are usually a good choice for sharp edges). |
|
nNumEdges |
UDINT |
The (maximum) number of edges to search for |
|
eEdgeSelection |
Selects the edge directions to search for | |
|
fMinStrength |
REAL |
Specification of the minimum strength (absolute peak height of the Gaussian derivative of the pixel intensities) of the edge to search for. This value depends on the edge sharpness and nKernelSize, but is generally smaller or equal to the difference of the pixel intensities of the edge. Sharp edges have a higher peak than unsharp ones. Initially, you might choose a relatively small value (e.g. 30) and then increase it depending on the fAvgStrength and ipEdgeStrengths output. |
|
fSigma |
REAL |
The sigma parameter for the Gaussian derivative function. If set to 0, a suitable value is automatically chosen depending on nKernelSize. For manually defined sigma, the value should always be chosen depending on nKernelSize (e.g. fSigma = (nKernelSize - 1) / factor, with factor in a range of 4 to 8). |
|
ipEdgeStrengths |
Reference To ITcVnContainer |
Returns the individual edge strengths, where dark to light edge strengths are positive and light to dark edge strengths are negative (optional, set to 0 if not required; ContainerType_Vector_REAL). |
|
ipDerivative |
Reference To ITcVnImage |
Returns the Gaussian derivative of the pixel intensities on the search line between aStartPoint and aEndPoint as a single image row, where aStartPoint would be on the left and aEndPoint on the right (optional, set to 0 if not required; 1 channel, ET_REAL). |
|
hrPrev |
HRESULT indicating the result of previous operations (If SUCCEEDED(hrPrev) equals false, no operation is executed.) |
In/Outputs
|
Name |
Type |
Description |
|---|---|---|
|
aStartPoint |
Position from which to start the search process (in the direction of aEndPoint) | |
|
aEndPoint |
Position where the search process ends. As the search direction must be parallel to one of the images axes, aEndPoint must have the same x- or y-coordinate as aStartPoint. |
Outputs
|
Name |
Type |
Description |
|---|---|---|
|
fAvgStrength |
REAL |
Returns the average strength of the detected edges |
Weiterführende Informationen
Die Funktion F_VN_LocateAxisAlignedEdgesExp ist eine Expert-Variante von F_VN_LocateAxisAlignedEdges. Sie enthält zusätzliche Parameter.
Parameter
Eingangsbild
Das Eingangsbild ipSrcImage muss ein 1-kanaliges Grauwertbild vom Typ ET_USINT, ET_UINT, ET_INT oder ET_REAL sein.
Lokalisierte Kantenpunkte
Der Rückgabewert ipEdgePoints gibt die lokalisierten Kantenpunkte als Container vom Typ ContainerType_Vector_TcVnPoint2_REAL zurück. Die Anzahl der tatsächlich gefundenen Kanten kann kleiner als nNumEdges sein.
Suchfenster
Die Parameter aStartPoint und aEndPoint legen Start- und Endpunkt der Suchlinie und damit die Breite des Suchfensters fest. Da die Suchrichtung achsparallel sein muss, gilt zwingend entweder gleiche x-Koordinate (vertikale Suche) oder gleiche y-Koordinate (horizontale Suche). Die Reihenfolge der zurückgegebenen Kanten entspricht der Suchrichtung, sodass sich die Richtung von Start- nach Endpunkt auch dazu nutzen lässt, die Kantenabfolge (und damit z. B. steigende/fallende Übergänge) gezielt zu ordnen.
Der Parameter nSearchWindowHeight legt die Höhe des Suchfensters senkrecht zur Suchrichtung fest, also die Anzahl der zu mittelnden Zeilen (bei horizontaler Suche) bzw. Spalten (bei vertikaler Suche). Das Fenster ist symmetrisch um die Linie zwischen aStartPoint und aEndPoint zentriert.
Filter-Größe
Der Parameter nKernelSize bestimmt die Größe des Gauß-Ableitungskerns zur Kantenlokalisierung. Der Wert muss ungerade und >= 3 sein. Für scharfe Kanten sind 5 oder 7 in der Regel eine gute Wahl. Ein kleiner Kern reagiert empfindlich auf feine, scharfe Kanten, aber auch stärker auf Rauschen; ein größerer Kern glättet stärker und eignet sich besser für unscharfe oder verrauschte Kanten, kann jedoch dicht beieinanderliegende Kanten verschmelzen. Ein passender Sigma-Wert der Gauß-Ableitung wird automatisch aus nKernelSize abgeleitet.
Anzahl Kanten
Der Parameter nNumEdges gibt die maximale Anzahl der zu suchenden Kanten an. Es werden die Kanten (Peaks im Ableitungsprofil) zurückgegeben, die das Kriterium fMinStrength erfüllen, bis die angegebene Anzahl erreicht ist. Sind weniger passende Kanten vorhanden, werden entsprechend weniger Punkte geliefert.
Kantenrichtung
Der Parameter eEdgeSelection vom Typ ETcVnEdgeSelection legt fest, welche Kantenrichtungen gesucht werden:
TCVN_ES_RISING: Nur steigende Kanten, d. h. Übergänge von dunkel nach hell.TCVN_ES_FALLING: Nur fallende Kanten, d. h. Übergänge von hell nach dunkel.TCVN_ES_ANY: Beliebige Kantenrichtung, d. h. steigende oder fallende Kanten.
Minimalstärke
Der Parameter fMinStrength gibt die minimale Kantenstärke an, also die absolute Peak-Höhe im Gauß-Ableitungsprofil der Pixelintensitäten. Der Wert hängt von der Kantenschärfe und von nKernelSize ab, liegt aber typischerweise unter oder gleich der Intensitätsdifferenz der Kante. Scharfe Kanten erzeugen höhere Peaks als unscharfe. In der Praxis empfiehlt es sich, mit einem eher kleinen Wert zu beginnen (z. B. 30) und ihn anhand des Rückgabewerts fAvgStrength schrittweise anzuheben, bis nur noch die relevanten Kanten sicher detektiert und Störkanten zuverlässig unterdrückt werden.
Kantenstärke
Der Rückgabewert fAvgStrength gibt die mittlere Stärke der detektierten Kanten zurück. Er dient vor allem als Diagnose- und Einstellhilfe für fMinStrength. Ein deutlicher Abstand zwischen fAvgStrength und fMinStrength weist auf robuste, klar messbare Kanten hin.
Standardabweichung
Der Parameter fSigma legt die Standardabweichung Sigma der Gauß-Ableitungsfunktion manuell fest. Bei fSigma = 0 (Standard) wird automatisch ein zu nKernelSize passender Wert gewählt. Dies ist für die meisten Anwendungen ausreichend und daher der empfohlene Wert.
Wird der Wert manuell vorgegeben, sollte er stets in Abhängigkeit von nKernelSize gewählt werden, z. B. fSigma = (nKernelSize - 1) / nFactor, mit einem nFactor im Bereich von 4 bis 8. Ein kleineres Sigma führt zu einer schärferen, lokaleren Kantenantwort (empfindlicher gegenüber Rauschen), ein größeres Sigma glättet stärker und eignet sich für unscharfe oder verrauschte Kanten. Zu große Sigma-Werte glätten das Intensitätsprofil so stark, dass Kanten verschoben, verschmolzen oder gar nicht mehr detektiert werden.
Kantenstärken
Der Parameter ipEdgeStrengths gibt die individuellen Kantenstärken (Höhe des Peaks im Ableitungsprofil) der detektierten Kanten als Container vom Typ ContainerType_Vector_REAL zurück. Die Reihenfolge entspricht der von ipEdgePoints. Das Vorzeichen kodiert die Kantenrichtung: Dunkel-nach-Hell-Übergänge (steigende Kanten) liefern positive Werte, Hell-nach-Dunkel-Übergänge (fallende Kanten) negative Werte. Dies ermöglicht, pro Kante nicht nur die Position, sondern auch Stärke und Richtung auszuwerten. Dies ist hilfreich z. B. zur Qualitätsbewertung einzelner Kanten oder zur nachträglichen Filterung. Dieser Parameter ist optional und kann auf 0 gesetzt werden, wenn er nicht benötigt wird.
Ableitungsprofil
Der Parameter ipDerivative gibt das Gauß-Ableitungsprofil der Pixelintensitäten als 1-kanaliges Bild vom Typ ET_REAL mit einer einzelnen Bildzeile zurück. Dabei liegt aStartPoint links und aEndPoint rechts. Dieses Profil ist das Zwischenergebnis, auf dem die eigentliche Kantendetektion erfolgt. Es eignet sich zur Diagnose und zum Parameter-Tuning. Anhand des Profils lassen sich Höhe und Schärfe der Peaks sowie das Rauschniveau beurteilen und darauf aufbauend fMinStrength, nKernelSize und fSigma gezielt einstellen. Zur Anzeige des Bildes sollte es zunächst nach ET_USINT konvertiert und entsprechend skaliert werden. Zur Anzeige des Ableitungsprofils kann dann die F_VN_PlotIntensityProfileExp verwendet werden. Dieser Parameter ist optional und kann auf 0 gesetzt werden, wenn er nicht benötigt wird.
Required License
TC3 Vision Metrology 2D
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 |