F_VN_LocateCircularArcExp
Locate a circular arc. (expert function)
Can use available TwinCAT Job Tasks for executing parallel code regions.
Can return partial results when canceled by Watchdog.
Syntax
Definition:
FUNCTION F_VN_LocateCircularArcExp : HRESULT
VAR_INPUT
ipSrcImage : ITcVnImage;
END_VAR
VAR_IN_OUT
stCircularArc : TcVnCircularArc;
aCenter : TcVnPoint2_REAL;
END_VAR
VAR_INPUT
fSearchRadius : REAL;
fArcDirectionRad : LREAL;
eEdgeDirection : ETcVnEdgeDirection;
fMinStrength : REAL;
fAngleStepRad : LREAL;
nMaxThickness : UDINT;
bInvertSearchDirection : BOOL;
nSubpixelsIterations : UDINT;
fApproxPrecision : REAL;
eAlgorithm : ETcVnEdgeDetectionAlgorithm;
ipContourPoints : Reference To ITcVnContainer;
hrPrev : HRESULT;
END_VAR
Inputs
|
Name |
Type |
Description |
|---|---|---|
|
ipSrcImage |
Source image (1 channel) | |
|
fSearchRadius |
REAL |
Input search radius (starting from aCenter, should be greater than the actual circle radius but aCenter + fSearchRadius should be within the image borders) |
|
fArcDirectionRad |
LREAL |
Input search starting direction in radian. Valid range is [-pi, +pi], where right is 0 rad, top is -pi/2 rad and bottom +pi/2 rad. The circular arc should at least be valid in range fArcDirectionRad +- 4 * fAngleStepRad) |
|
eEdgeDirection |
Specification of the edge direction to search for | |
|
fMinStrength |
REAL |
Specification of the minimum strength (intensity difference) of the edge to search for |
|
fAngleStepRad |
LREAL |
Search step in rad (should be chosen so that about 20 - 60 steps are available for the whole arc. In most cases 0.1 rad (5.7 deg) is a good value) |
|
nMaxThickness |
UDINT |
Specification of the maximum thickness of the edge to search for, which means fMinStrength must be reached within nMaxThickness pixels |
|
bInvertSearchDirection |
BOOL |
If true, the search starts from outside the circular arc in direction of the center |
|
nSubpixelsIterations |
UDINT |
Specifies the number of subpixels (for INTERPOLATION, 10 - 20 usually is sufficient) or maximum number of iterations for optimizing the parameters (for APPROX_ERF and APPROX_GAUSSIAN, 50 - 100 usually is sufficient) |
|
fApproxPrecision |
REAL |
Specifies the approximation precision for APPROX_ERF and APPROX_GAUSSIAN (0.001 usually is sufficient, unused for INTERPOLATION) |
|
eAlgorithm |
Selection of the edge detection algorithm | |
|
ipContourPoints |
Reference To ITcVnContainer |
Returns the subpixel accurate contour (optional, set to 0 if not required; ContainerType_Vector_TcVnPoint2_REAL; Non-zero interface pointers are reused.) |
|
hrPrev |
HRESULT indicating the result of previous operations (If SUCCEEDED(hrPrev) equals false, no operation is executed.) |
In/Outputs
|
Name |
Type |
Description |
|---|---|---|
|
stCircularArc |
Returns the circular arc parameters | |
|
aCenter |
Input estimated circle center (only used as a starting point to search for the circle contour, not used for the circle center estimation) |
Return valueFurther information
The function F_VN_LocateCircularArcExp is the expert version of F_VN_LocateCircularArc. It contains additional parameters.
Parameter
Input image
The input image ipSrcImage must be a 1-channel grayscale image.
Circular arc (Return value)
The parameter stCircularArc returns the localized circular arc as a structure of the type TcVnCircularArc.
Estimated center point
The estimated center point aCenter of the circular arc must be specified in order to define the position of the search lines.
If the position of the center point of the circle is unknown, it may need to be determined beforehand by means of an object detection.
Search radius
The search radius fSearchRadius defines the length of the search lines from the center point of the circle in pixels. The search radius should be defined somewhat larger than the actual radius of the circle so that the edge localization can be carried out unambiguously.
Search direction
The search direction fArcDirectionRad specifies the circular direction in which the edge search should begin (starting from the center point of the circle). The value is to be specified in radians and has a value range of [-π, π]. Right corresponds to 0, top with –π/2 and bottom with π/2. Starting from fArcDirectionRad, the circular arc must be present at least in the range of +- 0.4 in order to be detected. It is recommended to aim for the center of the circular arc.
Radial search line distance (Expert)
The radial search line distance fAngleStepRad defines how large the angle steps between the search lines are. It is specified in radians. The distance should be selected so that the complete circular arc is divided into about 20 – 60 steps. In most cases 0.1 rad (5.7°) is a suitable value.
Search direction inversion (Expert)
The search direction can be inverted with the Boolean bInvertSearchDirection. In this case, that means the following:
FALSE: Search from the center point of the circle to outside the circular arc.TRUE: Search from outside the circular arc to the center point of the circle
Contour points (Expert, return value)
The container ipContourPoints returns the edge points of the circular arc found and is therefore of the type ContainerType_Vector_TcVnPoint2_REAL. The container contains one point for each search line successfully found.
The parameter can be set to 0 if the return of the edge points is not required.
 | Circular arc stCircularArc The circular arc stCircularArc is approximated from the set of these points. |
Parameters for edge localization
The remaining parameters are explained in detail in the chapter Edge localization.
Application
The localization of a circular arc with expert parameters looks like this, for example:
hr := F_VN_LocateCircularArc(
ipSrcImage := ipImageIn,
stCircularArc := stArc,
aCenterPoint := aCenter,
fSearchRadius := 270,
fArcDirectionRad := 2.1,
eEdgeDirection := TCVN_ED_LIGHT_TO_DARK,
fMinStrength := 100,
fAngleStepRad := 40,
nMaxThickness := 10,
bInvertSearchDirection := FALSE,
nSubpixelsIterations := 100,
fApproxPrecision := 0.0001,
eAlgorithm := TCVN_EDA_APPROX_ERF,
ipContourPoints := ipEllipseContour,
hrPrev := hr
);
The localized points can be visualized with the function F_VN_DrawContours.
hr := F_VN_DrawContours(ipEllipseContour, -1, ipImageRes, aColorGreen, 5, hr);
Samples
Related functions
- LocateCircularArc for localizing proportional circular arcs
- LocateEdge for localizing linear edges
- LocateEdges for localizing several linear edges
- LocateEllipse for localizing complete ellipses
Required License
TC3 Vision Metrology 2D
System Requirements
Development environment | Target platform | PLC libraries to include |
|---|---|---|
TwinCAT V3.1.4024.54 or later | PC or CX (x64) with PL50, e.g. Intel 4-core Atom CPU | Tc3_Vision |