union_collinear_contours_xldunion_collinear_contours_xldUnionCollinearContoursXldUnionCollinearContoursXld (Operator)


union_collinear_contours_xldunion_collinear_contours_xldUnionCollinearContoursXldUnionCollinearContoursXld — Unite approximately collinear contours.


union_collinear_contours_xld(Contours : UnionContours : MaxDistAbs, MaxDistRel, MaxShift, MaxAngle, Mode : )

Herror union_collinear_contours_xld(const Hobject Contours, Hobject* UnionContours, double MaxDistAbs, double MaxDistRel, double MaxShift, double MaxAngle, const char* Mode)

Herror T_union_collinear_contours_xld(const Hobject Contours, Hobject* UnionContours, const Htuple MaxDistAbs, const Htuple MaxDistRel, const Htuple MaxShift, const Htuple MaxAngle, const Htuple Mode)

void UnionCollinearContoursXld(const HObject& Contours, HObject* UnionContours, const HTuple& MaxDistAbs, const HTuple& MaxDistRel, const HTuple& MaxShift, const HTuple& MaxAngle, const HTuple& Mode)

HXLDCont HXLDCont::UnionCollinearContoursXld(double MaxDistAbs, double MaxDistRel, double MaxShift, double MaxAngle, const HString& Mode) const

HXLDCont HXLDCont::UnionCollinearContoursXld(double MaxDistAbs, double MaxDistRel, double MaxShift, double MaxAngle, const char* Mode) const

HXLDCont HXLDCont::UnionCollinearContoursXld(double MaxDistAbs, double MaxDistRel, double MaxShift, double MaxAngle, const wchar_t* Mode) const   (Windows only)

static void HOperatorSet.UnionCollinearContoursXld(HObject contours, out HObject unionContours, HTuple maxDistAbs, HTuple maxDistRel, HTuple maxShift, HTuple maxAngle, HTuple mode)

HXLDCont HXLDCont.UnionCollinearContoursXld(double maxDistAbs, double maxDistRel, double maxShift, double maxAngle, string mode)


The operator union_collinear_contours_xldunion_collinear_contours_xldUnionCollinearContoursXldUnionCollinearContoursXldUnionCollinearContoursXld unites all contours of the input XLD contour array ContoursContoursContoursContourscontours that are approximately collinear, i.e., which lie approximately on the same straight line. The united contours consist of the concatenation of the contour points of the respective input contours. They are returned, together with the contours that could not be united with any other contour, in the output XLD contour array UnionContoursUnionContoursUnionContoursUnionContoursunionContours.

Typical applications

union_collinear_contours_xldunion_collinear_contours_xldUnionCollinearContoursXldUnionCollinearContoursXldUnionCollinearContoursXld can be used to bridge gaps in extracted edges or lines, which may be caused, e.g., by locally low image contrast. It can also be used to unite collinear edge or line segments that are separated, e.g., because of junctions. Typically, union_collinear_contours_xldunion_collinear_contours_xldUnionCollinearContoursXldUnionCollinearContoursXldUnionCollinearContoursXld is part of the process of grouping and selecting extracted edges or lines to achieve meaningful entities.


The following example shows the effect of union_collinear_contours_xldunion_collinear_contours_xldUnionCollinearContoursXldUnionCollinearContoursXldUnionCollinearContoursXld. On the left hand side, a set of disconnected input contours is shown. The contours that lie on the same border of the rectangle are approximately collinear. On the right hand side, the result of union_collinear_contours_xldunion_collinear_contours_xldUnionCollinearContoursXldUnionCollinearContoursXldUnionCollinearContoursXld shows that the contours that were approximately collinear have been united. Note that the contours that are approximately perpendicular to each other have not been united.

(1) (2)
(1) Disconnected input contours. (2) Resulting contours, where approximately collinear contours have been united.


The parameters MaxDistAbsMaxDistAbsMaxDistAbsMaxDistAbsmaxDistAbs, MaxDistRelMaxDistRelMaxDistRelMaxDistRelmaxDistRel, MaxShiftMaxShiftMaxShiftMaxShiftmaxShift, and MaxAngleMaxAngleMaxAngleMaxAnglemaxAngle are used to define the conditions for the collinearity of two contours. The parameter ModeModeModeModemode controls the handling of the attributes of the input contours.

In principle, the measures for the first three parameters depend on the order in which each pair of contours is evaluated, i.e., which contour is used as reference contour that is to be joined with the second contour. To avoid this dependency, the respective measures are evaluated in both directions and the order of contours is chosen that results in the smaller value for these measures. Note that in the illustrations below, the contour on the left is always used as the reference contour.


The parameter MaxDistAbsMaxDistAbsMaxDistAbsMaxDistAbsmaxDistAbs defines the maximum accepted absolute distance between the two contours. The distance is measured along the regression line of the reference contour. Thus, it is the length of the projection of the gap between the two contours onto the regression line of the reference contour.

image/svg+xml a

The parameter MaxDistRelMaxDistRelMaxDistRelMaxDistRelmaxDistRel defines the maximum accepted relative distance between the two contours. The relative distance is calculated by dividing the distance a (see the description of the parameter MaxDistAbsMaxDistAbsMaxDistAbsMaxDistAbsmaxDistAbs) by the length b of the reference contour.

image/svg+xml a b

The parameter MaxShiftMaxShiftMaxShiftMaxShiftmaxShift defines the maximum distance of the second contour from the regression line of the reference contour. This distance is measured perpendicular to the regression line of the reference contour.

image/svg+xml a

The parameter MaxAngleMaxAngleMaxAngleMaxAnglemaxAngle defines the maximum angle (in radians) between the regression lines of the two contours.

image/svg+xml a

The parameter ModeModeModeModemode controls the handling of the attributes that may be available for the input contours, e.g., if the contours have been created by edges_sub_pixedges_sub_pixEdgesSubPixEdgesSubPixEdgesSubPix.


All attributes are copied to the output contours.

Global attributes are only kept for those contours that are not united with other contours. In general, it is not possible to determine the global attributes of a united contour from the global attributes of the individual contours.


The output contours will not contain any attributes. This mode may be chosen for performance reasons if the attributes will not be required for further calculations.

To query, which attributes are available, query_contour_attribs_xldquery_contour_attribs_xldQueryContourAttribsXldQueryContourAttribsXldQueryContourAttribsXld can be used.

Implementation details

The input contours are analyzed and united pairwise. This pairwise process is repeated until there are no more unconnected collinear contours left. If necessary, the order of the input contour points is flipped, so that the end points of the contours that have been connected are direct neighbors in the resulting point list.

Two contours are united only if all criteria are fulfilled, i.e., all values must be lower than the specified thresholds. As another precondition, contours must not overlap each other significantly (see union_collinear_contours_ext_xldunion_collinear_contours_ext_xldUnionCollinearContoursExtXldUnionCollinearContoursExtXldUnionCollinearContoursExtXld for an illustration of overlap). An overlap of at most 0.5 pixels is tolerated. To allow a larger overlap, union_collinear_contours_ext_xldunion_collinear_contours_ext_xldUnionCollinearContoursExtXldUnionCollinearContoursExtXldUnionCollinearContoursExtXld can be used.

Besides finding pairs of contours to be united, it is important for the behavior of union_collinear_contours_xldunion_collinear_contours_xldUnionCollinearContoursXldUnionCollinearContoursXldUnionCollinearContoursXld to determine the order in which contours are united. For this, all contour pairs that may be united are rated by calculating costs for their unification. The costs are the sum of the measures, each normalized by the respective threshold, defined by the parameters MaxDistAbsMaxDistAbsMaxDistAbsMaxDistAbsmaxDistAbs, MaxDistRelMaxDistRelMaxDistRelMaxDistRelmaxDistRel, MaxShiftMaxShiftMaxShiftMaxShiftmaxShift, and MaxAngleMaxAngleMaxAngleMaxAnglemaxAngle. The contour pair with the lowest costs is united first. Then, the costs are updated with respect to the newly created contour and the contour list is searched for the next best pair of contours to be united.

Note that the definition of collinearity as used in union_collinear_contours_xldunion_collinear_contours_xldUnionCollinearContoursXldUnionCollinearContoursXldUnionCollinearContoursXld depends on the regression lines of the input contours. To avoid unexpected results, make sure that the input contours are approximately straight lines, e.g., by splitting them into line segments with segment_contours_xldsegment_contours_xldSegmentContoursXldSegmentContoursXldSegmentContoursXld. Note also that closed contours are not united with any other contour.

Limitations and alternatives

union_collinear_contours_xldunion_collinear_contours_xldUnionCollinearContoursXldUnionCollinearContoursXldUnionCollinearContoursXld can only be used if the contours that should be joined lie approximately on a straight line. If the contours lie approximately on a circle, union_cocircular_contours_xldunion_cocircular_contours_xldUnionCocircularContoursXldUnionCocircularContoursXldUnionCocircularContoursXld can be used instead. If the contours represent a free-form, union_cotangential_contours_xldunion_cotangential_contours_xldUnionCotangentialContoursXldUnionCotangentialContoursXldUnionCotangentialContoursXld can be used. If only very small gaps between the contours should be closed, regardless of the orientation of the contours, union_adjacent_contours_xldunion_adjacent_contours_xldUnionAdjacentContoursXldUnionAdjacentContoursXldUnionAdjacentContoursXld can be used.

If the parameter adjustments available with union_collinear_contours_xldunion_collinear_contours_xldUnionCollinearContoursXldUnionCollinearContoursXldUnionCollinearContoursXld are not sufficient, union_collinear_contours_ext_xldunion_collinear_contours_ext_xldUnionCollinearContoursExtXldUnionCollinearContoursExtXldUnionCollinearContoursExtXld can be used to define the criteria for the unification more specifically. Among others, union_collinear_contours_ext_xldunion_collinear_contours_ext_xldUnionCollinearContoursExtXldUnionCollinearContoursExtXldUnionCollinearContoursExtXld allows to set the tolerance for the overlap of contours as well as a limit for the total costs to avoid the connection of contours that are close to the limits of all criteria.

Execution Information


ContoursContoursContoursContourscontours (input_object)  xld_cont-array objectHXLDContHXLDContHobject

Input XLD contours.

UnionContoursUnionContoursUnionContoursUnionContoursunionContours (output_object)  xld_cont-array objectHXLDContHXLDContHobject *

Output XLD contours.

MaxDistAbsMaxDistAbsMaxDistAbsMaxDistAbsmaxDistAbs (input_control)  real HTupleHTupleHtuple (real) (double) (double) (double)

Maximum length of the gap between two contours, measured along the regression line of the reference contour.

Default value: 10.0

Typical range of values: 0.0 ≤ MaxDistAbs MaxDistAbs MaxDistAbs MaxDistAbs maxDistAbs

MaxDistRelMaxDistRelMaxDistRelMaxDistRelmaxDistRel (input_control)  real HTupleHTupleHtuple (real) (double) (double) (double)

Maximum length of the gap between two contours, relative to the length of the reference contour, both measured along the regression line of the reference contour.

Default value: 1.0

Typical range of values: 0.0 ≤ MaxDistRel MaxDistRel MaxDistRel MaxDistRel maxDistRel

MaxShiftMaxShiftMaxShiftMaxShiftmaxShift (input_control)  real HTupleHTupleHtuple (real) (double) (double) (double)

Maximum distance of the second contour from the regression line of the reference contour.

Default value: 2.0

Typical range of values: 0.0 ≤ MaxShift MaxShift MaxShift MaxShift maxShift

MaxAngleMaxAngleMaxAngleMaxAnglemaxAngle (input_control)  real HTupleHTupleHtuple (real) (double) (double) (double)

Maximum angle between the regression lines of two contours.

Default value: 0.1

Typical range of values: 0.0 ≤ MaxAngle MaxAngle MaxAngle MaxAngle maxAngle ≤ 0.78539816339

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

Mode that defines the treatment of contour attributes, i.e., if the contour attributes are kept or discarded.

Default value: 'attr_keep' "attr_keep" "attr_keep" "attr_keep" "attr_keep"

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

edges_sub_pixedges_sub_pixEdgesSubPixEdgesSubPixEdgesSubPix, lines_gausslines_gaussLinesGaussLinesGaussLinesGauss, segment_contours_xldsegment_contours_xldSegmentContoursXldSegmentContoursXldSegmentContoursXld, select_contours_xldselect_contours_xldSelectContoursXldSelectContoursXldSelectContoursXld, select_shape_xldselect_shape_xldSelectShapeXldSelectShapeXldSelectShapeXld, split_contours_xldsplit_contours_xldSplitContoursXldSplitContoursXldSplitContoursXld, threshold_sub_pixthreshold_sub_pixThresholdSubPixThresholdSubPixThresholdSubPix

Possible Successors

fit_line_contour_xldfit_line_contour_xldFitLineContourXldFitLineContourXldFitLineContourXld, select_contours_xldselect_contours_xldSelectContoursXldSelectContoursXldSelectContoursXld, select_shape_xldselect_shape_xldSelectShapeXldSelectShapeXldSelectShapeXld


union_collinear_contours_ext_xldunion_collinear_contours_ext_xldUnionCollinearContoursExtXldUnionCollinearContoursExtXldUnionCollinearContoursExtXld, union_straight_contours_xldunion_straight_contours_xldUnionStraightContoursXldUnionStraightContoursXldUnionStraightContoursXld, union_cocircular_contours_xldunion_cocircular_contours_xldUnionCocircularContoursXldUnionCocircularContoursXldUnionCocircularContoursXld, union_cotangential_contours_xldunion_cotangential_contours_xldUnionCotangentialContoursXldUnionCotangentialContoursXldUnionCotangentialContoursXld, union_adjacent_contours_xldunion_adjacent_contours_xldUnionAdjacentContoursXldUnionAdjacentContoursXldUnionAdjacentContoursXld

See also

get_contour_xldget_contour_xldGetContourXldGetContourXldGetContourXld, get_contour_attrib_xldget_contour_attrib_xldGetContourAttribXldGetContourAttribXldGetContourAttribXld, query_contour_attribs_xldquery_contour_attribs_xldQueryContourAttribsXldQueryContourAttribsXldQueryContourAttribsXld