F_VN_LocateAxisAlignedEdgesExp

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_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).
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 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	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_LocateAxisAlignedEdgesExp is an expert version of F_VN_LocateAxisAlignedEdges. It contains additional parameters.

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.

Standard deviation

The parameter fSigma manually sets the standard deviation (sigma) of the Gaussian derivative function. If fSigma = 0 (default), a value that matches nKernelSize is automatically selected. This is sufficient for most applications and is therefore the recommended value.

If the value is set manually, it should always be chosen based on nKernelSize, e.g., fSigma = (nKernelSize - 1) / nFactor, with a nFactor in the range of 4 to 8. A smaller sigma results in a sharper, more localized edge response (more sensitive to noise), while a larger sigma smooths more effectively and is suitable for blurry or noisy edges. Sigma values that are too high smooth the intensity profile so much that edges are shifted, merged, or not detected at all.

Edge strengths

The parameter ipEdgeStrengths returns the individual edge strengths (height of the peak in the derivative profile) of the detected edges as a container of type ContainerType_Vector_REAL. The order is the same as that of ipEdgePoints. The sign indicates the direction of the edge: dark-to-light transitions (rising edges) yield positive values, while light-to-dark transitions (falling edges) yield negative values. This makes it possible to evaluate not only the position but also the strength and direction of each edge. This is useful, for example, for evaluating the quality of individual edges or for subsequent filtering. This parameter is optional and can be set to 0 if it is not required.

Derivative profile

The parameter ipDerivative returns the Gaussian derivative profile of the pixel intensities as a single-channel image of type ET_REAL with a single image line. aStartPoint is on the left and aEndPoint is on the right. This profile is the intermediate result on which the actual edge detection is performed. It is suitable for diagnostics and parameter tuning. The profile can be used to assess the height and sharpness of the peaks as well as the noise level, and based on this, fMinStrength, nKernelSize, and fSigma can be adjusted as needed. To display the image, it should first be converted to ET_USINT and scaled accordingly. To display the derivative profile, you can use the F_VN_PlotIntensityProfileExp function. This parameter is optional and can be set to 0 if it is not required.

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