union_cotangential_contours_xldunion_cotangential_contours_xldUnionCotangentialContoursXldUnionCotangentialContoursXld (Operator)

Name

union_cotangential_contours_xldunion_cotangential_contours_xldUnionCotangentialContoursXldUnionCotangentialContoursXld — Compute the union of cotangential contours.

Signature

union_cotangential_contours_xld(Contours : UnionContours : FitClippingLength, FitLength, MaxTangAngle, MaxDist, MaxDistPerp, MaxOverlap, Mode : )

Herror union_cotangential_contours_xld(const Hobject Contours, Hobject* UnionContours, double FitClippingLength, double FitLength, double MaxTangAngle, double MaxDist, double MaxDistPerp, double MaxOverlap, const char* Mode)

Herror T_union_cotangential_contours_xld(const Hobject Contours, Hobject* UnionContours, const Htuple FitClippingLength, const Htuple FitLength, const Htuple MaxTangAngle, const Htuple MaxDist, const Htuple MaxDistPerp, const Htuple MaxOverlap, const Htuple Mode)

void UnionCotangentialContoursXld(const HObject& Contours, HObject* UnionContours, const HTuple& FitClippingLength, const HTuple& FitLength, const HTuple& MaxTangAngle, const HTuple& MaxDist, const HTuple& MaxDistPerp, const HTuple& MaxOverlap, const HTuple& Mode)

HXLDCont HXLDCont::UnionCotangentialContoursXld(double FitClippingLength, const HTuple& FitLength, double MaxTangAngle, double MaxDist, double MaxDistPerp, double MaxOverlap, const HString& Mode) const

HXLDCont HXLDCont::UnionCotangentialContoursXld(double FitClippingLength, double FitLength, double MaxTangAngle, double MaxDist, double MaxDistPerp, double MaxOverlap, const HString& Mode) const

HXLDCont HXLDCont::UnionCotangentialContoursXld(double FitClippingLength, double FitLength, double MaxTangAngle, double MaxDist, double MaxDistPerp, double MaxOverlap, const char* Mode) const

HXLDCont HXLDCont::UnionCotangentialContoursXld(double FitClippingLength, double FitLength, double MaxTangAngle, double MaxDist, double MaxDistPerp, double MaxOverlap, const wchar_t* Mode) const   (Windows only)

static void HOperatorSet.UnionCotangentialContoursXld(HObject contours, out HObject unionContours, HTuple fitClippingLength, HTuple fitLength, HTuple maxTangAngle, HTuple maxDist, HTuple maxDistPerp, HTuple maxOverlap, HTuple mode)

HXLDCont HXLDCont.UnionCotangentialContoursXld(double fitClippingLength, HTuple fitLength, double maxTangAngle, double maxDist, double maxDistPerp, double maxOverlap, string mode)

HXLDCont HXLDCont.UnionCotangentialContoursXld(double fitClippingLength, double fitLength, double maxTangAngle, double maxDist, double maxDistPerp, double maxOverlap, string mode)

Description

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

Parameters

FitClippingLengthFitClippingLengthFitClippingLengthFitClippingLengthfitClippingLength

How does the union work? First, endpieces for each input contour in ContoursContoursContoursContourscontours are determined. The parameter FitClippingLengthFitClippingLengthFitClippingLengthFitClippingLengthfitClippingLength 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.

FitLengthFitLengthFitLengthFitLengthfitLength

With the parameter FitLengthFitLengthFitLengthFitLengthfitLength 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 FitLengthFitLengthFitLengthFitLengthfitLength. The value 'auto'"auto""auto""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 endpieces. As this is computationally intensive, it is recommended to use numerically specified values for the lengths whenever possible.

image/svg+xml a a

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.

image/svg+xml

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:

MaxTangAngleMaxTangAngleMaxTangAngleMaxTangAnglemaxTangAngle

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

image/svg+xml a
MaxDistMaxDistMaxDistMaxDistmaxDist

The maximum distance of two endpoints is given with the parameter MaxDistMaxDistMaxDistMaxDistmaxDist.

image/svg+xml a
MaxDistPerpMaxDistPerpMaxDistPerpMaxDistPerpmaxDistPerp

The maximum distance perpendicular to the tangents is specified with the parameter MaxDistPerpMaxDistPerpMaxDistPerpMaxDistPerpmaxDistPerp. This distance is the minimum of the distances of the endpoints of the contours perpendicular to the other contour.

image/svg+xml a b
MaxOverlapMaxOverlapMaxOverlapMaxOverlapmaxOverlap

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 MaxOverlapMaxOverlapMaxOverlapMaxOverlapmaxOverlap. Contrary to the other threshold values, MaxOverlapMaxOverlapMaxOverlapMaxOverlapmaxOverlap can become negative. Negative values denote the minimum distance of the endpoints in the direction of the tangents.

image/svg+xml a b
. In this case, 'a'"a""a""a""a" and 'b'"b""b""b""b" are negative. See the reference manual entry of union_collinear_contours_ext_xldunion_collinear_contours_ext_xldUnionCollinearContoursExtXldUnionCollinearContoursExtXldUnionCollinearContoursExtXld for an illustration with positive values for 'a'"a""a""a""a" and 'b'"b""b""b""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 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 ModeModeModeModemode states, whether existing attributes of the input contours should be copied to the output contours. 'attr_keep'"attr_keep""attr_keep""attr_keep""attr_keep" copies the attributes, which can have negative impacts on the performance of the operator. 'attr_forget'"attr_forget""attr_forget""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_xldunion_adjacent_contours_xldUnionAdjacentContoursXldUnionAdjacentContoursXldUnionAdjacentContoursXld.

Execution Information

Parameters

ContoursContoursContoursContourscontours (input_object)  xld_cont-array objectHXLDContHXLDContHobject

Input XLD contours.

UnionContoursUnionContoursUnionContoursUnionContoursunionContours (output_object)  xld_cont-array objectHXLDContHXLDContHobject *

Output XLD contours.

FitClippingLengthFitClippingLengthFitClippingLengthFitClippingLengthfitClippingLength (input_control)  real HTupleHTupleHtuple (real) (double) (double) (double)

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 FitClippingLength FitClippingLength FitClippingLength fitClippingLength

FitLengthFitLengthFitLengthFitLengthfitLength (input_control)  real HTupleHTupleHtuple (real / string) (double / string) (double / HString) (double / char*)

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'"auto""auto""auto""auto"

Typical range of values: 0.0 ≤ FitLength FitLength FitLength FitLength fitLength

MaxTangAngleMaxTangAngleMaxTangAngleMaxTangAnglemaxTangAngle (input_control)  angle.rad HTupleHTupleHtuple (real) (double) (double) (double)

Maximum angle difference between two contours' tangents.

Default value: 0.78539816

Typical range of values: 0.0 ≤ MaxTangAngle MaxTangAngle MaxTangAngle MaxTangAngle maxTangAngle ≤ 3.1415926

MaxDistMaxDistMaxDistMaxDistmaxDist (input_control)  real HTupleHTupleHtuple (real) (double) (double) (double)

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 MaxDist MaxDist MaxDist maxDist

MaxDistPerpMaxDistPerpMaxDistPerpMaxDistPerpmaxDistPerp (input_control)  real HTupleHTupleHtuple (real) (double) (double) (double)

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 MaxDistPerp MaxDistPerp MaxDistPerp maxDistPerp

MaxOverlapMaxOverlapMaxOverlapMaxOverlapmaxOverlap (input_control)  real HTupleHTupleHtuple (real) (double) (double) (double)

Maximum overlap of two contours.

Default value: 2.0

Suggested values: 2.0, 5.0, 10.0, 20.0

ModeModeModeModemode (input_control)  string HTupleHTupleHtuple (string) (string) (HString) (char*)

Mode describing the treatment of the contours' attributes.

Default value: 'attr_forget' "attr_forget" "attr_forget" "attr_forget" "attr_forget"

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

Possible Predecessors

split_contours_xldsplit_contours_xldSplitContoursXldSplitContoursXldSplitContoursXld, select_contours_xldselect_contours_xldSelectContoursXldSelectContoursXldSelectContoursXld

Alternatives

union_collinear_contours_xldunion_collinear_contours_xldUnionCollinearContoursXldUnionCollinearContoursXldUnionCollinearContoursXld, union_collinear_contours_ext_xldunion_collinear_contours_ext_xldUnionCollinearContoursExtXldUnionCollinearContoursExtXldUnionCollinearContoursExtXld, union_cocircular_contours_xldunion_cocircular_contours_xldUnionCocircularContoursXldUnionCocircularContoursXldUnionCocircularContoursXld, union_straight_contours_xldunion_straight_contours_xldUnionStraightContoursXldUnionStraightContoursXldUnionStraightContoursXld, union_adjacent_contours_xldunion_adjacent_contours_xldUnionAdjacentContoursXldUnionAdjacentContoursXldUnionAdjacentContoursXld

See also

edges_sub_pixedges_sub_pixEdgesSubPixEdgesSubPixEdgesSubPix, threshold_sub_pixthreshold_sub_pixThresholdSubPixThresholdSubPixThresholdSubPix, gen_polygons_xldgen_polygons_xldGenPolygonsXldGenPolygonsXldGenPolygonsXld, get_contour_xldget_contour_xldGetContourXldGetContourXldGetContourXld, get_contour_attrib_xldget_contour_attrib_xldGetContourAttribXldGetContourAttribXldGetContourAttribXld

Module

Foundation