union_cotangential_contours_xldUnionCotangentialContoursXldUnionCotangentialContoursXldunion_cotangential_contours_xldunion_cotangential_contours_xld🔗

Short description🔗

union_cotangential_contours_xldUnionCotangentialContoursXldUnionCotangentialContoursXldunion_cotangential_contours_xldunion_cotangential_contours_xld — Compute the union of cotangential contours.

Signature🔗

union_cotangential_contours_xld( xld_cont Contours, out xld_cont UnionContours, real FitClippingLength, real FitLength, angle.rad MaxTangAngle, real MaxDist, real MaxDistPerp, real MaxOverlap, string Mode )

Description🔗

The operator union_cotangential_contours_xldUnionCotangentialContoursXld unifies contours of the input XLD contour array Contourscontourscontours according to the local curvatures at their endpoints.

Parameters

FitClippingLengthfitClippingLengthfit_clipping_length How does the union work? First, end pieces for each input contour in Contourscontourscontours are determined. The parameter FitClippingLengthfitClippingLengthfit_clipping_length 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.

\(a \leq \textrm{FitClippingLength}\)
FitLengthfitLengthfit_length With the parameter FitLengthfitLengthfit_length the 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 to FitLengthfitLengthfit_length. The value 'auto'"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.

\(a \leq \textrm{FitLength}\)

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:

MaxTangAnglemaxTangAnglemax_tang_angle The parameter MaxTangAnglemaxTangAnglemax_tang_angle specifies the maximum angle between the tangents of two contours.

\(a \leq \textrm{MaxTangAngle}\)
MaxDistmaxDistmax_dist The maximum distance of two endpoints is given with the parameter MaxDistmaxDistmax_dist.

\(a \leq \textrm{MaxDist}\)
MaxDistPerpmaxDistPerpmax_dist_perp The maximum distance perpendicular to the tangents is specified with the parameter MaxDistPerpmaxDistPerpmax_dist_perp. This distance is the minimum of the distances of the endpoints of the contours perpendicular to the other contour.

\(min(a,b) \leq \textrm{MaxDistPerp}\)
MaxOverlapmaxOverlapmax_overlap 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 MaxOverlapmaxOverlapmax_overlap. Contrary to the other threshold values, MaxOverlapmaxOverlapmax_overlap can become negative. Negative values denote the minimum distance of the endpoints in the direction of the tangents.

\(min(a,b) \leq \textrm{MaxOverlap}\). In this case, \(a\) and \(b\) are negative. See the reference manual entry of union_collinear_contours_ext_xldUnionCollinearContoursExtXld for an illustration with positive values for \(a\) and \(b\).

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 Modemodemode states, whether existing attributes of the input contours should be copied to the output contours. 'attr_keep'"attr_keep" copies the attributes, which can have negative impacts on the performance of the operator. 'attr_forget'"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_xldUnionAdjacentContoursXld.

Execution information🔗

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🔗

Contourscontourscontours (input_object) xld_cont-array → objectHObjectHXLDContHObjectHobject

Input XLD contours.

UnionContoursunionContoursunion_contours (output_object) xld_cont-array → objectHObjectHXLDContHObjectHobject *

Output XLD contours.

FitClippingLengthfitClippingLengthfit_clipping_length (input_control) real → (real)HTuple (double)HTuple (double)floatHtuple (double)

Length of the part of a contour to skip for the determination of tangents.

Default: 0.00.0
Value range: 0.0 ≤ FitClippingLength

FitLengthfitLengthfit_length (input_control) real → (real / string)HTuple (double / HString)HTuple (double / string)Union[float, str]Htuple (double / char*)

Length of the part of a contour to use for the determination of tangents.

Default: 30.030.0
Suggested values: 10.0, 20.0, 30.0, 'auto'10.0, 20.0, 30.0, "auto"
Value range: 0.0 ≤ FitLength

MaxTangAnglemaxTangAnglemax_tang_angle (input_control) angle.rad → (real)HTuple (double)HTuple (double)floatHtuple (double)

Maximum angle difference between two contours’ tangents.

Default: 0.785398160.78539816
Value range: 0.0 ≤ MaxTangAngle ≤ 3.1415926

MaxDistmaxDistmax_dist (input_control) real → (real)HTuple (double)HTuple (double)floatHtuple (double)

Maximum distance of the contours’ end points.

Default: 25.025.0
Suggested values: 5.0, 10.0, 25.0, 50.05.0, 10.0, 25.0, 50.0
Value range: 0.0 ≤ MaxDist

MaxDistPerpmaxDistPerpmax_dist_perp (input_control) real → (real)HTuple (double)HTuple (double)floatHtuple (double)

Maximum distance of the contours’ end points perpendicular to their tangents.

Default: 10.010.0
Suggested values: 2.0, 5.0, 10.0, 20.02.0, 5.0, 10.0, 20.0
Value range: 0.0 ≤ MaxDistPerp

MaxOverlapmaxOverlapmax_overlap (input_control) real → (real)HTuple (double)HTuple (double)floatHtuple (double)

Maximum overlap of two contours.

Default: 2.02.0
Suggested values: 2.0, 5.0, 10.0, 20.02.0, 5.0, 10.0, 20.0

Modemodemode (input_control) string → (string)HTuple (HString)HTuple (string)strHtuple (char*)

Mode describing the treatment of the contours’ attributes.

Default: 'attr_forget'"attr_forget"
List of values: 'attr_forget', 'attr_keep'"attr_forget", "attr_keep"

Combinations with other operators🔗

Combinations

Possible predecessors

split_contours_xldSplitContoursXld, select_contours_xldSelectContoursXld

Alternatives

union_collinear_contours_xldUnionCollinearContoursXld, union_collinear_contours_ext_xldUnionCollinearContoursExtXld, union_cocircular_contours_xldUnionCocircularContoursXld, union_straight_contours_xldUnionStraightContoursXld, union_adjacent_contours_xldUnionAdjacentContoursXld

Module🔗

Foundation