union_cotangential_contours_xld — Compute the union of cotangential contours.
The operator union_cotangential_contours_xld unifies contours of the input XLD contour array Contours according to the local curvatures at their endpoints.
How does the union work? First, endpieces for each input contour in Contours are determined. The parameter FitClippingLength specifies 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.
With the parameter FitLength the Euclidean length of the endpieces that will be examined for the union is given. At each end of a contour at least that many points are assigned to an endpiece that its length is greater or equal to FitLength. 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 endpieces. 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 endpiece. 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 endpieces.
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:
The parameter MaxTangAngle specifies the maximum angle between the tangents of two contours.
The maximum distance of two endpoints is given with the parameter MaxDist.
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.
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, MaxOverlap can become negative. Negative values denote the minimum distance of the endpoints in the direction of the tangents.
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 endpieces. 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.
Input XLD contours.
Output XLD contours.
Length of the part of a contour to skip for the determination of tangents.
Default value: 0.0
Typical range of values: 0.0 ≤ FitClippingLength
Length of the part of a contour to use for the determination of tangents.
Default value: 30.0
Suggested values: 10.0, 20.0, 30.0, 'auto'
Typical range of values: 0.0 ≤ FitLength
Maximum angle difference between two contours' tangents.
Default value: 0.78539816
Typical range of values: 0.0 ≤ MaxTangAngle ≤ 3.1415926
Maximum distance of the contours' end points.
Default value: 25.0
Suggested values: 5.0, 10.0, 25.0, 50.0
Typical range of values: 0.0 ≤ MaxDist
Maximum distance of the contours' end points perpendicular to their tangents.
Default value: 10.0
Suggested values: 2.0, 5.0, 10.0, 20.0
Typical range of values: 0.0 ≤ MaxDistPerp
Maximum overlap of two contours.
Default value: 2.0
Suggested values: 2.0, 5.0, 10.0, 20.0
Mode describing the treatment of the contours' attributes.
Default value: 'attr_forget'
List of values: 'attr_forget', 'attr_keep'
union_collinear_contours_xld, union_collinear_contours_ext_xld, union_cocircular_contours_xld, union_straight_contours_xld, union_adjacent_contours_xld
edges_sub_pix, threshold_sub_pix, gen_polygons_xld, get_contour_xld, get_contour_attrib_xld