Measurement

The group contains functions for the measurement of objects in images.

Functions

Edge localization

LocateCircularArc for localizing proportional circular arcs
LocateEdge for localizing linear edges
LocateEdges for localizing several linear edges
LocateEllipse for localizing complete ellipses

Geometrical features

ClosestPointsBF for calculating the closest points in two point clouds
MeasureAngleBetweenEdges for measuring the angle between two edges
MeasureEdgeDistance for measuring the average distance between two edges
MeasureMinEdgeDistance for measuring the minimum distance between two edges

Miscellaneous

F_VN_AdjustSearchWindowOrientationToLinearEdge for aligning the search field to an edge

Parameters for edge localization

The borders of an image object often don't lie exactly on the border between two pixels. Instead, they run independently of pixel grids. Therefore edge localization with sub-pixel accuracy is necessary. This not only considers the transition between two pixels, but also determines the edge position within a pixel on the basis of the overall intensity gradient of an object border.

Notice

Don't process the image before measuring

Don't process the image before calling the measurement function. Processing can lead to loss of information and lower accuracy accordingly.

This basic functionality of edge localization is used by all measurement functions. The functions differ mainly by the geometric arrangement in which they perform the edge localization (e.g. F_VN_LocateEllipse for round objects) and the properties that you calculate from them (e.g. F_VN_MeasureAngleBetweenEdges for angle measurement).

Certain parameters must be defined for each function that uses edge localization. These include:

Definition of the search area: where is the edge sought?
Definition of edge contrast: What is detected as an edge?
Definition of the measurement algorithm: How to determine the exact position of the edge.

These parameters are described below. In the case of expert parameters, standard values are specified in addition.

Search area

Parameter	Description
Position of the search lines	The position of the search lines is defined according to the feature to be localized. The position of search lines for a linear edge is defined as a single line with the start point `aStartPoint` and end point `aEndPoint`. The position of search lines for an ellipse is defined by a center point `aCenter` and a radius `fSearchRadius`. The position of search lines for angles is defined by an inner point `aInnerPoint` and two outer points `aOuterPoint1` and `aOuterPoint2`. The position of the search lines should always be set such that the search lines cut the edges to be localized orthogonally. A rectangular search area can be adjusted orthogonally to an edge with the function F_VN_AdjustSearchWindowOrientationToLinearEdge.
Number of search lines `nSearchLines : UDINT`	This specifies how many search lines are to be used for the edge localization. The simplest edge localization has one search line on which the edge must be found. Depending on the geometric feature to be determined, multiple search lines are distributed locally so that several edge transitions are localized. This can be necessary in the following cases: Not only the position, but also the gradient or the rotation of the edge are required. The geometrical feature (e.g. ellipse) necessitates several search lines. An average value is required. When localizing linear edges, the search lines are arranged symmetrically on both sides of the central search line, the central search line being included in `nSearchLines`. Thus, an odd number of search lines is always required.
Distance between the search lines `fSearchlineDist : REAL` (Expert) Default: `1`	The search lines distance defines the distance between neighboring search lines in pixels (> 0, default 1). This allows flexible balancing between accuracy and computing time.
Inversion of the search direction `bInvertSearchDirection : BOOL` (Expert) Default: `FALSE`	The localization algorithm always searches for the edge from one end of the search line to the other. e.g. searching takes place from aStartPoint to aEndPoint. If it is necessary to invert this search direction due to the image properties (i.e. to start from the other end of the search lines), this parameter helps.

Edge contrast

Parameter	Description
Edge direction `eEdgeDirection : ETcVnEdgeDirection`	The edge direction determines whether an edge transition from light to dark or from dark to light should be found. The following values are available for this: `TCVN_ED_DARK_TO_LIGHT` `TCVN_ED_LIGHT_TO_DARK`
Minimum strength `fMinStrength : LREAL`	The minimum strength defines the minimum difference in intensity required within an edge for it to be found. This makes it possible to control how much contrast an edge must have in order to be found.
Maximum thickness `nMaxThickness : UDINT` (Expert) Default: `10`	The maximum thickness specifies the number of pixels within which `fMinStrength` must be reached. This allows you to control whether only sharp edges or also very blurred edges are to be found.

Parameter

Description

Edge direction

eEdgeDirection : ETcVnEdgeDirection

The edge direction determines whether an edge transition from light to dark or from dark to light should be found. The following values are available for this:

TCVN_ED_DARK_TO_LIGHT
TCVN_ED_LIGHT_TO_DARK

Minimum strength

fMinStrength : LREAL

The minimum strength defines the minimum difference in intensity required within an edge for it to be found.

This makes it possible to control how much contrast an edge must have in order to be found.

Maximum thickness

nMaxThickness : UDINT

(Expert)

Default: 10

The maximum thickness specifies the number of pixels within which fMinStrength must be reached.

This allows you to control whether only sharp edges or also very blurred edges are to be found.

Algorithm

Parameter	Description
Algorithm `eAlgorithm : ETcVnEdgeDetectionAlgorithm` (Expert) Default: `TCVN_EDA_INTERPOLATION`	This parameter defines the localization algorithm used. The available options are: `TCVN_EDA_INTERPOLATION` `TCVN_EDA_APPROX_ERF` `TCVN_EDA_APPROX_GAUSSIAN` `TCVN_EDA_APPROX_ERF` and `TCVN_EDA_APPROX_GAUSSIAN` are slower than the standard algorithm `TCVN_EDA_INTERPOLATION`, but can achieve higher accuracy. The prerequisite for this, however, is that the intensity gradient of the edge also corresponds as well as possible to the specified model. The error function `erf` or the Gaussian function is used as a model. The `erf` function is well suited for edges if the transition from bright to dark extends over several pixels and remains approximately constant on both sides of the light or dark area respectively. A Gaussian function is well suited for lines, i.e. a dark-light-dark transition or vice versa. However, the brightness plateau may only be a few pixels wide, otherwise the erf function should be used.
Subpixels / Iterations `nSubpixelsIterations : UDINT` (Expert) Default: 10	The meaning of this parameter depends on the localization algorithm used. At `TCVN_EDA_INTERPOLATION`: the number of subpixels considered defines the fine granularity with which the search line evaluates the underlying pixel intensities. A value of 10, for example, specifies that 10 measured values are taken over a length of 1 pixel. Recommended: `5` - `10` At `TCVN_EDA_APPROX_ERF` and `TCVN_EDA_APPROX_GAUSSIAN`: the number of iterations is an abort criterion that defines the maximum number of iterations with which the edge model is to be approximated for the pixel intensities. More iterations increase the runtime; if this is too high the interpolation method should be used. Recommended: `50` - `100`
Approximation accuracy `fApproxPrecision : REAL` (Expert) Default: `0.001`	The approximation accuracy is a further abort criterion of the edge localization. It is only observed if the localization algorithm is `TCVN_EDA_APPROX_ERF` or `TCVN_EDA_APPROX_GAUSSIAN`. The approximation of the edge or line is aborted if either the number of iterations of `nSubPixelIterations` is reached or the relative deviation in pixels is less than `fApproximationPrecision` for two consecutive iterations. Recommended: `0.01` - `0.0001`

Parameter

Description

Algorithm

eAlgorithm : ETcVnEdgeDetectionAlgorithm

(Expert)

Default: TCVN_EDA_INTERPOLATION

This parameter defines the localization algorithm used. The available options are:

TCVN_EDA_INTERPOLATION
TCVN_EDA_APPROX_ERF
TCVN_EDA_APPROX_GAUSSIAN

TCVN_EDA_APPROX_ERF and TCVN_EDA_APPROX_GAUSSIAN are slower than the standard algorithm TCVN_EDA_INTERPOLATION, but can achieve higher accuracy. The prerequisite for this, however, is that the intensity gradient of the edge also corresponds as well as possible to the specified model. The error function erf or the Gaussian function is used as a model.

The erf function is well suited for edges if the transition from bright to dark extends over several pixels and remains approximately constant on both sides of the light or dark area respectively.

Measurement 1:

A Gaussian function is well suited for lines, i.e. a dark-light-dark transition or vice versa. However, the brightness plateau may only be a few pixels wide, otherwise the erf function should be used.

Measurement 2:

Subpixels / Iterations

nSubpixelsIterations : UDINT

(Expert)

Default: 10

The meaning of this parameter depends on the localization algorithm used.

At TCVN_EDA_INTERPOLATION:

the number of subpixels considered defines the fine granularity with which the search line evaluates the underlying pixel intensities. A value of 10, for example, specifies that 10 measured values are taken over a length of 1 pixel.

Recommended: 5 - 10

At TCVN_EDA_APPROX_ERF and TCVN_EDA_APPROX_GAUSSIAN:

the number of iterations is an abort criterion that defines the maximum number of iterations with which the edge model is to be approximated for the pixel intensities. More iterations increase the runtime; if this is too high the interpolation method should be used.

Recommended: 50 - 100

Approximation accuracy

fApproxPrecision : REAL

(Expert)

Default: 0.001

The approximation accuracy is a further abort criterion of the edge localization. It is only observed if the localization algorithm is TCVN_EDA_APPROX_ERF or TCVN_EDA_APPROX_GAUSSIAN.

The approximation of the edge or line is aborted if either the number of iterations of nSubPixelIterations is reached or the relative deviation in pixels is less than fApproximationPrecision for two consecutive iterations.

Recommended: 0.01 - 0.0001

Interpretation of the HRESULT

The HRESULT return values have the following meaning:

Code	Name	Description
16#000	S_OK	Function was successfully executed and an edge was located on all search lines.
16#001	S_FALSE	Function was successfully executed, but edges were not located on each search line.
16#256	S_WATCHDOGTIMEOUT	Function was aborted by the watchdog. In this case, all measurement functions can return partial results.
16#70C	NOTFOUND	Function was executed successfully, but no edge could be found on any search line. It is assumed that a measurement function is only called if it is ensured that the image contains an object with the parameterized edge properties. If none of the search lines are found, this indicates incorrect parameterization or an unsuitable call of the function. Therefore, an error code is output in this case.
16#7xx	All error codes except NOTFOUND	Function was not executed successfully. See also: ADS Return Codes

The following query, for example, can be used for the processing of the return value:

IF SUCCEEDED(hr) THEN
    // Process results
    IF hr <> S_OK THEN
        // Emit warning that not all search lines were found
    END_IF
ELSIF hr = Tc2_System.E_HRESULTAdsErr.NOTFOUND THEN
    // Emit warning for wrong parametrization or missing piece
ELSE
    // Error handling
END_IF

Reducing execution time

The execution time for a fixed search window varies slightly depending on the position of the component in the image. If the edge that is found is closer to the starting point, the execution time is shorter than for an edge further away.

A larger fluctuation can occur with the two approximation algorithms, since these require different iterations in order to approximate the model parameters using the surrounding pixel intensities.

In general, fewer iterations are required if the search lines of the search window hit the edge as orthogonally as possible. If the position and orientation of the objects in the image are subject to little or no fluctuation, the search window can be adjusted accordingly to achieve shorter execution times. In addition, the maximum time required can be reduced by reducing the maximum number of iterations, but this may lead to less accurate results.

In addition, the time can be limited with an external watchdog, which terminates the execution of the function if necessary and returns the existing partial results.

Samples

Measurement

Further Information