Operator Reference
union_cotangential_contours_xld (Operator)
union_cotangential_contours_xld — Compute the union of cotangential contours.
Signature
union_cotangential_contours_xld(Contours : UnionContours : FitClippingLength, FitLength, MaxTangAngle, MaxDist, MaxDistPerp, MaxOverlap, Mode : )
Description
The operator union_cotangential_contours_xld unifies contours
of the input XLD contour array Contours according to the local
curvatures at their endpoints.
Parameters
FitClippingLength-
How does the union work? First, end pieces for each input contour in
Contoursare determined. The parameterFitClippingLengthspecifies the Euclidean length that is temporarily clipped at both ends of a contour. With this parameter, it is possible to ignore artifacts at the endings of the input contours. FitLength-
With the parameter
FitLengththe Euclidean length of the end pieces that will be examined for the union is given. At each end of a contour at least that many points are assigned to an end piece that its length is greater or equal toFitLength. The value 'auto' can be used here. The operator then tries to segment the contours into straights and arcs and takes the first and last segment as end pieces. As this is computationally intensive, it is recommended to use numerically specified values for the lengths whenever possible.
The operator tries to fit a circle into each end piece. Then, the endpoints of the input contours are determined that lie near enough to these circles (measured against the root mean square error of the circle fit). The tangents at these points correspond to the local curvature at the endings of the input contours.
If a circle fit fails, the operator tries to fit a regression line. Then, the local curvature of the endings of a contour corresponds to the direction of the regression line through the points of the end pieces.
The input contours are going to be unified according to the calculated local curvatures at their endpoints. Two contours are considered for the union if multiple thresholds are fulfilled at the same time:
MaxTangAngle-
The parameter
MaxTangAnglespecifies the maximum angle between the tangents of two contours. MaxDist-
The maximum distance of two endpoints is given with the parameter
MaxDist. MaxDistPerp-
The maximum distance perpendicular to the tangents is specified with the parameter
MaxDistPerp. This distance is the minimum of the distances of the endpoints of the contours perpendicular to the other contour. MaxOverlap-
As a last threshold, the overlap of the contours is considered. The amount of the overlap is determined by the projection of one endpoint onto the tangent of another contour and vice versa. The distances between the endpoints and their projections must be shorter than
MaxOverlap. Contrary to the other threshold values,MaxOverlapcan become negative. Negative values denote the minimum distance of the endpoints in the direction of the tangents.. In this case, and are negative. See the reference manual entry ofunion_collinear_contours_ext_xldfor an illustration with positive values for and .
It is possible, that a single contour is closed by this operator or multiple contours are merged into a single closed contour, if the criteria named above are fulfilled for the end pieces. Be aware that already closed contours are not considered for a union anymore.
If all thresholds are fulfilled between contours, a score value is calculated. The closer the calculated values for the angles and distances are to 0, the higher is the score value. The unification is then executed in the order of the score values. Thus, if there are multiple candidates for the unification, the best fitting contours are merged first.
The parameter Mode states, whether existing attributes of the
input contours should be copied to the output contours. 'attr_keep'
copies the attributes, which can have negative impacts on the performance of
the operator.
'attr_forget' causes the operator to ignore existing attributes.
For further details see the description of the parameter Mode of the
operator union_adjacent_contours_xld.
Execution Information
- Multithreading type: reentrant (runs in parallel with non-exclusive operators).
- Multithreading scope: global (may be called from any thread).
- Processed without parallelization.
Parameters
Contours (input_object) xld_cont-array → object
Input XLD contours.
UnionContours (output_object) xld_cont-array → object
Output XLD contours.
FitClippingLength (input_control) real → (real)
Length of the part of a contour to skip for the determination of tangents.
Default: 0.0
Value range:
0.0
≤
FitClippingLength
FitLength (input_control) real → (real / string)
Length of the part of a contour to use for the determination of tangents.
Default: 30.0
Suggested values: 10.0, 20.0, 30.0, 'auto'
Value range:
0.0
≤
FitLength
MaxTangAngle (input_control) angle.rad → (real)
Maximum angle difference between two contours' tangents.
Default: 0.78539816
Value range:
0.0
≤
MaxTangAngle
≤
3.1415926
MaxDist (input_control) real → (real)
Maximum distance of the contours' end points.
Default: 25.0
Suggested values: 5.0, 10.0, 25.0, 50.0
Value range:
0.0
≤
MaxDist
MaxDistPerp (input_control) real → (real)
Maximum distance of the contours' end points perpendicular to their tangents.
Default: 10.0
Suggested values: 2.0, 5.0, 10.0, 20.0
Value range:
0.0
≤
MaxDistPerp
MaxOverlap (input_control) real → (real)
Maximum overlap of two contours.
Default: 2.0
Suggested values: 2.0, 5.0, 10.0, 20.0
Mode (input_control) string → (string)
Mode describing the treatment of the contours' attributes.
Default: 'attr_forget'
List of values: 'attr_forget', 'attr_keep'
Possible Predecessors
split_contours_xld,
select_contours_xld
Alternatives
union_collinear_contours_xld,
union_collinear_contours_ext_xld,
union_cocircular_contours_xld,
union_straight_contours_xld,
union_adjacent_contours_xld
See also
edges_sub_pix,
threshold_sub_pix,
gen_polygons_xld,
get_contour_xld,
get_contour_attrib_xld
Module
Foundation