F_VN_LocateAxisAlignedEdges

Syntax

Definition:

FUNCTION F_VN_LocateAxisAlignedEdges : 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;
    hrPrev              : HRESULT;
END_VAR
VAR_OUTPUT
    fAvgStrength        : REAL;
END_VAR

Inputs

Name	Type	Description
ipSrcImage	ITcVnImage	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). A suitable sigma parameter for the Gaussian derivative function is automatically chosen.
nNumEdges	UDINT	The (maximum) number of edges to search for
eEdgeSelection	ETcVnEdgeSelection	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 output.
hrPrev	HRESULT	HRESULT indicating the result of previous operations (If SUCCEEDED(hrPrev) equals false, no operation is executed.)

In/Outputs

Name	Type	Description
aStartPoint	TcVnPoint2_DINT	Position from which to start the search process (in the direction of aEndPoint)
aEndPoint	TcVnPoint2_DINT	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

Return value

HRESULT

Further information

The function F_VN_LocateAxisAlignedEdges locates the positions of one or more edges within a defined search window. The edges must be straight and parallel to one of the two image axes. Localization is performed using the first Gaussian derivative of the pixel intensities. At each edge transition, a distinct peak appears in the derivative profile, and its position is determined with subpixel accuracy through interpolation.

The search follows the line from aStartPoint to aEndPoint, either vertically or horizontally. The width of the search window is defined by the distance between the start and end points; the height (nSearchWindowHeight) is centered around this midline. Depending on the search direction, the pixels in this area are averaged to form an image row or column.

Edges are then detected on this averaged 1D intensity profile. Averaging offers several advantages: image noise is significantly reduced, and local imperfections such as scratches, material texture, or individual defective pixels become less noticeable, since they usually affect only a few pixels. In addition, the execution time is reduced because only a single averaged profile is analyzed, rather than determining the edge positions individually along multiple search lines using other calculation methods. However, this requires the specified condition to be met over the entire height of the window. Otherwise, the edge will be “smeared” by the averaging process, and the measurement result will lose accuracy or detection will fail.

This function is designed for edges that are parallel to the axis. If the edges are rotated or freely oriented in the image, there are two options: Either a preprocessing step is used to create an ROI aligned with an image axis, or a different measurement function is used for freely oriented search lines (e.g., F_VN_LocateEdges).

Parameter

Input image

The input image ipSrcImage must be a 1-channel grayscale image of type ET_USINT, ET_UINT, ET_INT, or ET_REAL.

Localized edge points

The return value ipEdgePoints returns the localized edge points as a container of type ContainerType_Vector_TcVnPoint2_REAL. The number of edges actually found may be less than nNumEdges.

Search window

The parameters aStartPoint and aEndPoint define the start and end points of the search line and, therefore, the width of the search window. Since the search direction must be parallel to the axis, either the x-coordinate must be the same (vertical search) or the y-coordinate must be the same (horizontal search). The order of the returned edges corresponds to the search direction, so the direction from the start point to the end point can also be used to specifically arrange the sequence of edges (and thus, for example, ascending/descending transitions).

The parameter nSearchWindowHeight specifies the height of the search window perpendicular to the search direction, that is, the number of rows (for a horizontal search) or columns (for a vertical search) to be averaged. The window is centered symmetrically around the line between aStartPoint and aEndPoint.

Filter size

The parameter nKernelSize determines the size of the Gaussian derivative kernel used for edge localization. The value must be odd and greater than or equal to 3. For sharp edges, 5 or 7 is usually a good choice. A small kernel responds sensitively to fine, sharp edges, but also more sensitively to noise; a larger kernel smooths more effectively and is better suited for blurry or noisy edges, but may cause closely spaced edges to merge. A suitable sigma value for the Gaussian derivative is automatically derived from nKernelSize.

Number of edges

The parameter nNumEdges specifies the maximum number of edges to search for. The edges (peaks in the derivative profile) that satisfy the criterion fMinStrength are returned until the specified number is reached. If there are fewer matching edges, correspondingly fewer points will be returned.

Edge direction

The parameter eEdgeSelection, of type ETcVnEdgeSelection, specifies which edge directions are searched for:

TCVN_ES_RISING: Only ascending edges, i.e., transitions from dark to light.
TCVN_ES_FALLING: Only falling edges, i.e., transitions from light to dark.
TCVN_ES_ANY: Any edge direction, i.e., rising or falling edges.

Minimum strength

The parameter fMinStrength specifies the minimum edge strength, i.e., the absolute peak height in the Gaussian derivative profile of the pixel intensities. The value depends on the sharpness of the edge and on nKernelSize, but is typically less than or equal to the intensity difference of the edge. Sharp edges produce higher peaks than blurred ones. In practice, it is recommended to start with a relatively small value (e.g., 30) and gradually increase it based on the return value of fAvgStrength until only the relevant edges are reliably detected and unwanted edges are reliably suppressed.

Edge strength

The return value fAvgStrength returns the average strength of the detected edges. It is primarily used as a diagnostics and configuration tool for fMinStrength. A significant difference between fAvgStrength and fMinStrength indicates robust, clearly measurable edges.

Expert parameters

The Expert version, F_VN_LocateAxisAlignedEdgesExp, includes additional parameters.

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