union_collinear_contours_xldunion_collinear_contours_xldUnionCollinearContoursXldUnionCollinearContoursXldunion_collinear_contours_xld (Operator)

Name

union_collinear_contours_xldunion_collinear_contours_xldUnionCollinearContoursXldUnionCollinearContoursXldunion_collinear_contours_xld — Unite approximately collinear contours.

Signature

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)

def union_collinear_contours_xld(contours: HObject, max_dist_abs: float, max_dist_rel: float, max_shift: float, max_angle: float, mode: str) -> HObject

Description

The operator union_collinear_contours_xldunion_collinear_contours_xldUnionCollinearContoursXldUnionCollinearContoursXldUnionCollinearContoursXldunion_collinear_contours_xld unites all contours of the input XLD contour array ContoursContoursContoursContourscontourscontours 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 UnionContoursUnionContoursUnionContoursUnionContoursunionContoursunion_contours.

Typical applications

union_collinear_contours_xldunion_collinear_contours_xldUnionCollinearContoursXldUnionCollinearContoursXldUnionCollinearContoursXldunion_collinear_contours_xld 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_xldUnionCollinearContoursXldUnionCollinearContoursXldUnionCollinearContoursXldunion_collinear_contours_xld is part of the process of grouping and selecting extracted edges or lines to achieve meaningful entities.

Example

The following example shows the effect of union_collinear_contours_xldunion_collinear_contours_xldUnionCollinearContoursXldUnionCollinearContoursXldUnionCollinearContoursXldunion_collinear_contours_xld. 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_xldUnionCollinearContoursXldUnionCollinearContoursXldUnionCollinearContoursXldunion_collinear_contours_xld 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.

Parameters

The parameters MaxDistAbsMaxDistAbsMaxDistAbsMaxDistAbsmaxDistAbsmax_dist_abs, MaxDistRelMaxDistRelMaxDistRelMaxDistRelmaxDistRelmax_dist_rel, MaxShiftMaxShiftMaxShiftMaxShiftmaxShiftmax_shift, and MaxAngleMaxAngleMaxAngleMaxAnglemaxAnglemax_angle are used to define the conditions for the collinearity of two contours. The parameter ModeModeModeModemodemode 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.

MaxDistAbsMaxDistAbsMaxDistAbsMaxDistAbsmaxDistAbsmax_dist_abs

The parameter MaxDistAbsMaxDistAbsMaxDistAbsMaxDistAbsmaxDistAbsmax_dist_abs 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
MaxDistRelMaxDistRelMaxDistRelMaxDistRelmaxDistRelmax_dist_rel

The parameter MaxDistRelMaxDistRelMaxDistRelMaxDistRelmaxDistRelmax_dist_rel 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 MaxDistAbsMaxDistAbsMaxDistAbsMaxDistAbsmaxDistAbsmax_dist_abs) by the length b of the reference contour.

image/svg+xml a b
MaxShiftMaxShiftMaxShiftMaxShiftmaxShiftmax_shift

The parameter MaxShiftMaxShiftMaxShiftMaxShiftmaxShiftmax_shift 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
MaxAngleMaxAngleMaxAngleMaxAnglemaxAnglemax_angle

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

image/svg+xml a
ModeModeModeModemodemode

The parameter ModeModeModeModemodemode 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_pixEdgesSubPixEdgesSubPixEdgesSubPixedges_sub_pix.

'attr_keep'"attr_keep""attr_keep""attr_keep""attr_keep""attr_keep"

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.

'attr_forget'"attr_forget""attr_forget""attr_forget""attr_forget""attr_forget"

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_xldQueryContourAttribsXldQueryContourAttribsXldQueryContourAttribsXldquery_contour_attribs_xld 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_xldUnionCollinearContoursExtXldUnionCollinearContoursExtXldUnionCollinearContoursExtXldunion_collinear_contours_ext_xld 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_xldUnionCollinearContoursExtXldUnionCollinearContoursExtXldUnionCollinearContoursExtXldunion_collinear_contours_ext_xld can be used.

Besides finding pairs of contours to be united, it is important for the behavior of union_collinear_contours_xldunion_collinear_contours_xldUnionCollinearContoursXldUnionCollinearContoursXldUnionCollinearContoursXldunion_collinear_contours_xld 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 MaxDistAbsMaxDistAbsMaxDistAbsMaxDistAbsmaxDistAbsmax_dist_abs, MaxDistRelMaxDistRelMaxDistRelMaxDistRelmaxDistRelmax_dist_rel, MaxShiftMaxShiftMaxShiftMaxShiftmaxShiftmax_shift, and MaxAngleMaxAngleMaxAngleMaxAnglemaxAnglemax_angle. 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_xldUnionCollinearContoursXldUnionCollinearContoursXldUnionCollinearContoursXldunion_collinear_contours_xld 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_xldSegmentContoursXldSegmentContoursXldSegmentContoursXldsegment_contours_xld. Note also that closed contours are not united with any other contour.

Limitations and alternatives

union_collinear_contours_xldunion_collinear_contours_xldUnionCollinearContoursXldUnionCollinearContoursXldUnionCollinearContoursXldunion_collinear_contours_xld 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_xldUnionCocircularContoursXldUnionCocircularContoursXldUnionCocircularContoursXldunion_cocircular_contours_xld can be used instead. If the contours represent a free-form, union_cotangential_contours_xldunion_cotangential_contours_xldUnionCotangentialContoursXldUnionCotangentialContoursXldUnionCotangentialContoursXldunion_cotangential_contours_xld 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_xldUnionAdjacentContoursXldUnionAdjacentContoursXldUnionAdjacentContoursXldunion_adjacent_contours_xld can be used.

If the parameter adjustments available with union_collinear_contours_xldunion_collinear_contours_xldUnionCollinearContoursXldUnionCollinearContoursXldUnionCollinearContoursXldunion_collinear_contours_xld are not sufficient, union_collinear_contours_ext_xldunion_collinear_contours_ext_xldUnionCollinearContoursExtXldUnionCollinearContoursExtXldUnionCollinearContoursExtXldunion_collinear_contours_ext_xld can be used to define the criteria for the unification more specifically. Among others, union_collinear_contours_ext_xldunion_collinear_contours_ext_xldUnionCollinearContoursExtXldUnionCollinearContoursExtXldUnionCollinearContoursExtXldunion_collinear_contours_ext_xld 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

Parameters

ContoursContoursContoursContourscontourscontours (input_object)  xld_cont-array objectHXLDContHObjectHXLDContHobject

Input XLD contours.

UnionContoursUnionContoursUnionContoursUnionContoursunionContoursunion_contours (output_object)  xld_cont-array objectHXLDContHObjectHXLDContHobject *

Output XLD contours.

MaxDistAbsMaxDistAbsMaxDistAbsMaxDistAbsmaxDistAbsmax_dist_abs (input_control)  real HTuplefloatHTupleHtuple (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 max_dist_abs

MaxDistRelMaxDistRelMaxDistRelMaxDistRelmaxDistRelmax_dist_rel (input_control)  real HTuplefloatHTupleHtuple (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 max_dist_rel

MaxShiftMaxShiftMaxShiftMaxShiftmaxShiftmax_shift (input_control)  real HTuplefloatHTupleHtuple (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 max_shift

MaxAngleMaxAngleMaxAngleMaxAnglemaxAnglemax_angle (input_control)  real HTuplefloatHTupleHtuple (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 max_angle ≤ 0.78539816339

ModeModeModeModemodemode (input_control)  string HTuplestrHTupleHtuple (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" "attr_keep"

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

Possible Predecessors

edges_sub_pixedges_sub_pixEdgesSubPixEdgesSubPixEdgesSubPixedges_sub_pix, lines_gausslines_gaussLinesGaussLinesGaussLinesGausslines_gauss, segment_contours_xldsegment_contours_xldSegmentContoursXldSegmentContoursXldSegmentContoursXldsegment_contours_xld, select_contours_xldselect_contours_xldSelectContoursXldSelectContoursXldSelectContoursXldselect_contours_xld, select_shape_xldselect_shape_xldSelectShapeXldSelectShapeXldSelectShapeXldselect_shape_xld, split_contours_xldsplit_contours_xldSplitContoursXldSplitContoursXldSplitContoursXldsplit_contours_xld, threshold_sub_pixthreshold_sub_pixThresholdSubPixThresholdSubPixThresholdSubPixthreshold_sub_pix

Possible Successors

fit_line_contour_xldfit_line_contour_xldFitLineContourXldFitLineContourXldFitLineContourXldfit_line_contour_xld, select_contours_xldselect_contours_xldSelectContoursXldSelectContoursXldSelectContoursXldselect_contours_xld, select_shape_xldselect_shape_xldSelectShapeXldSelectShapeXldSelectShapeXldselect_shape_xld

Alternatives

union_collinear_contours_ext_xldunion_collinear_contours_ext_xldUnionCollinearContoursExtXldUnionCollinearContoursExtXldUnionCollinearContoursExtXldunion_collinear_contours_ext_xld, union_straight_contours_xldunion_straight_contours_xldUnionStraightContoursXldUnionStraightContoursXldUnionStraightContoursXldunion_straight_contours_xld, union_cocircular_contours_xldunion_cocircular_contours_xldUnionCocircularContoursXldUnionCocircularContoursXldUnionCocircularContoursXldunion_cocircular_contours_xld, union_cotangential_contours_xldunion_cotangential_contours_xldUnionCotangentialContoursXldUnionCotangentialContoursXldUnionCotangentialContoursXldunion_cotangential_contours_xld, union_adjacent_contours_xldunion_adjacent_contours_xldUnionAdjacentContoursXldUnionAdjacentContoursXldUnionAdjacentContoursXldunion_adjacent_contours_xld

See also

get_contour_xldget_contour_xldGetContourXldGetContourXldGetContourXldget_contour_xld, get_contour_attrib_xldget_contour_attrib_xldGetContourAttribXldGetContourAttribXldGetContourAttribXldget_contour_attrib_xld, query_contour_attribs_xldquery_contour_attribs_xldQueryContourAttribsXldQueryContourAttribsXldQueryContourAttribsXldquery_contour_attribs_xld

Module

Foundation