union_collinear_contours_ext_xldunion_collinear_contours_ext_xldUnionCollinearContoursExtXldUnionCollinearContoursExtXld (Operator)

Name

union_collinear_contours_ext_xldunion_collinear_contours_ext_xldUnionCollinearContoursExtXldUnionCollinearContoursExtXld — Compute the union of collinear contours (operator with extended functionality).

Signature

union_collinear_contours_ext_xld(Contours : UnionContours : MaxDistAbs, MaxDistRel, MaxShift, MaxAngle, MaxOverlap, MaxRegrError, MaxCosts, WeightDist, WeightShift, WeightAngle, WeightLink, WeightRegr, Mode : )

Herror union_collinear_contours_ext_xld(const Hobject Contours, Hobject* UnionContours, double MaxDistAbs, double MaxDistRel, double MaxShift, double MaxAngle, double MaxOverlap, double MaxRegrError, double MaxCosts, double WeightDist, double WeightShift, double WeightAngle, double WeightLink, double WeightRegr, const char* Mode)

Herror T_union_collinear_contours_ext_xld(const Hobject Contours, Hobject* UnionContours, const Htuple MaxDistAbs, const Htuple MaxDistRel, const Htuple MaxShift, const Htuple MaxAngle, const Htuple MaxOverlap, const Htuple MaxRegrError, const Htuple MaxCosts, const Htuple WeightDist, const Htuple WeightShift, const Htuple WeightAngle, const Htuple WeightLink, const Htuple WeightRegr, const Htuple Mode)

void UnionCollinearContoursExtXld(const HObject& Contours, HObject* UnionContours, const HTuple& MaxDistAbs, const HTuple& MaxDistRel, const HTuple& MaxShift, const HTuple& MaxAngle, const HTuple& MaxOverlap, const HTuple& MaxRegrError, const HTuple& MaxCosts, const HTuple& WeightDist, const HTuple& WeightShift, const HTuple& WeightAngle, const HTuple& WeightLink, const HTuple& WeightRegr, const HTuple& Mode)

HXLDCont HXLDCont::UnionCollinearContoursExtXld(double MaxDistAbs, double MaxDistRel, double MaxShift, double MaxAngle, double MaxOverlap, double MaxRegrError, double MaxCosts, double WeightDist, double WeightShift, double WeightAngle, double WeightLink, double WeightRegr, const HString& Mode) const

HXLDCont HXLDCont::UnionCollinearContoursExtXld(double MaxDistAbs, double MaxDistRel, double MaxShift, double MaxAngle, double MaxOverlap, double MaxRegrError, double MaxCosts, double WeightDist, double WeightShift, double WeightAngle, double WeightLink, double WeightRegr, const char* Mode) const

HXLDCont HXLDCont::UnionCollinearContoursExtXld(double MaxDistAbs, double MaxDistRel, double MaxShift, double MaxAngle, double MaxOverlap, double MaxRegrError, double MaxCosts, double WeightDist, double WeightShift, double WeightAngle, double WeightLink, double WeightRegr, const wchar_t* Mode) const   (Windows only)

static void HOperatorSet.UnionCollinearContoursExtXld(HObject contours, out HObject unionContours, HTuple maxDistAbs, HTuple maxDistRel, HTuple maxShift, HTuple maxAngle, HTuple maxOverlap, HTuple maxRegrError, HTuple maxCosts, HTuple weightDist, HTuple weightShift, HTuple weightAngle, HTuple weightLink, HTuple weightRegr, HTuple mode)

HXLDCont HXLDCont.UnionCollinearContoursExtXld(double maxDistAbs, double maxDistRel, double maxShift, double maxAngle, double maxOverlap, double maxRegrError, double maxCosts, double weightDist, double weightShift, double weightAngle, double weightLink, double weightRegr, string mode)

Description

Like union_collinear_contours_xldunion_collinear_contours_xldUnionCollinearContoursXldUnionCollinearContoursXldUnionCollinearContoursXld, the operator union_collinear_contours_ext_xldunion_collinear_contours_ext_xldUnionCollinearContoursExtXldUnionCollinearContoursExtXldUnionCollinearContoursExtXld detects all the collinear contours within the input array containing straight contours (ContoursContoursContoursContourscontours) and returns the results in UnionContoursUnionContoursUnionContoursUnionContoursunionContours. The basic behavior is identical to the operator union_collinear_contours_xldunion_collinear_contours_xldUnionCollinearContoursXldUnionCollinearContoursXldUnionCollinearContoursXld and is described there. union_collinear_contours_ext_xldunion_collinear_contours_ext_xldUnionCollinearContoursExtXldUnionCollinearContoursExtXldUnionCollinearContoursExtXld, however, provides several additional parameters to control the process of contour unification more precisely.

Parameters

The parameters MaxDistAbsMaxDistAbsMaxDistAbsMaxDistAbsmaxDistAbs, MaxDistRelMaxDistRelMaxDistRelMaxDistRelmaxDistRel, MaxShiftMaxShiftMaxShiftMaxShiftmaxShift, and MaxAngleMaxAngleMaxAngleMaxAnglemaxAngle operate as described for the operator union_collinear_contours_xldunion_collinear_contours_xldUnionCollinearContoursXldUnionCollinearContoursXldUnionCollinearContoursXld.

MaxOverlapMaxOverlapMaxOverlapMaxOverlapmaxOverlap

In addition, the parameter MaxOverlapMaxOverlapMaxOverlapMaxOverlapmaxOverlap allows to define an overlap between two contours, in order to connect contours which slightly overlap. Internally, the operator assures -- irrespective of the passed value for MaxOverlapMaxOverlapMaxOverlapMaxOverlapmaxOverlap -- that the overlap is not bigger than a third of the length of both contours.

image/svg+xml a b
MaxRegrErrorMaxRegrErrorMaxRegrErrorMaxRegrErrormaxRegrError

The parameter MaxRegrErrorMaxRegrErrorMaxRegrErrorMaxRegrErrormaxRegrError is not used at the moment. Its aim is to assure that after the unification of two contours, the resulting contour does not deviate too much from its regression line. This parameter is by default switched off (-1), because of its high time consumption and because of the fact that it is normally not necessary. In some cases, however, result contours may be created with points diverging to much from the regression line (winding input contours, shift and angle differences close to the -- quite high adjusted -- thresholds, recursive unification of a lot of small contours).

MaxCostsMaxCostsMaxCostsMaxCostsmaxCosts

With the help of the parameter MaxCostsMaxCostsMaxCostsMaxCostsmaxCosts it is possible to limit the maximum costs for connecting two contours. So, not only contour pairs with one value beyond a certain threshold may be excluded from unification, but also contour pairs where all values are quite close to the limits. The costs are always normalized at a value between 0 and 1, where 1 means that all values exactly meet the threshold.

WeightDistWeightDistWeightDistWeightDistweightDist, WeightShiftWeightShiftWeightShiftWeightShiftweightShift, WeightAngleWeightAngleWeightAngleWeightAngleweightAngle, WeightLinkWeightLinkWeightLinkWeightLinkweightLink, and WeightRegrWeightRegrWeightRegrWeightRegrweightRegr

The influence of the different values on the total costs is adjusted by passing appropriate weights with the parameters WeightDistWeightDistWeightDistWeightDistweightDist, WeightShiftWeightShiftWeightShiftWeightShiftweightShift, WeightAngleWeightAngleWeightAngleWeightAngleweightAngle, WeightLinkWeightLinkWeightLinkWeightLinkweightLink, WeightRegrWeightRegrWeightRegrWeightRegrweightRegr. Any positive number can be chosen for these weights, the resulting costs are always automatically normalized to fit the range from 0 to 1. The parameter WeightRegrWeightRegrWeightRegrWeightRegrweightRegr is not used.

ModeModeModeModemode

The parameter ModeModeModeModemode controls -- as for union_collinear_contours_xldunion_collinear_contours_xldUnionCollinearContoursXldUnionCollinearContoursXldUnionCollinearContoursXld -- how to handle the attributes of the input contours.

Execution Information

Parameters

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 distance of the contours' end points in the direction of the reference regression line.

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 distance of the contours' end points in the direction of the reference regression line in relation to the length of the contour which is to be elongated.

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 contour from the reference regression line (i.e., perpendicular to the line).

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 difference between the two contours.

Default value: 0.1

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

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

Maximum range of the overlap.

Default value: 0.0

Typical range of values: 0.0 ≤ MaxOverlap MaxOverlap MaxOverlap MaxOverlap maxOverlap

MaxRegrErrorMaxRegrErrorMaxRegrErrorMaxRegrErrormaxRegrError (input_control)  real HTupleHTupleHtuple (real) (double) (double) (double)

Maximum regression error of the resulting contours (NOT USED).

Default value: -1.0

MaxCostsMaxCostsMaxCostsMaxCostsmaxCosts (input_control)  real HTupleHTupleHtuple (real) (double) (double) (double)

Threshold for reducing the total costs of unification.

Default value: 1.0

Typical range of values: 0.0 ≤ MaxCosts MaxCosts MaxCosts MaxCosts maxCosts

WeightDistWeightDistWeightDistWeightDistweightDist (input_control)  real HTupleHTupleHtuple (real) (double) (double) (double)

Influence of the distance in the line direction on the total costs.

Default value: 1.0

Typical range of values: 0.0 ≤ WeightDist WeightDist WeightDist WeightDist weightDist

WeightShiftWeightShiftWeightShiftWeightShiftweightShift (input_control)  real HTupleHTupleHtuple (real) (double) (double) (double)

Influence of the distance from the regression line on the total costs.

Default value: 1.0

Typical range of values: 0.0 ≤ WeightShift WeightShift WeightShift WeightShift weightShift

WeightAngleWeightAngleWeightAngleWeightAngleweightAngle (input_control)  real HTupleHTupleHtuple (real) (double) (double) (double)

Influence of the angle difference on the total costs.

Default value: 1.0

Typical range of values: 0.0 ≤ WeightAngle WeightAngle WeightAngle WeightAngle weightAngle

WeightLinkWeightLinkWeightLinkWeightLinkweightLink (input_control)  real HTupleHTupleHtuple (real) (double) (double) (double)

Influence of the line disturbance by the linking segment (overlap and angle difference) on the total costs.

Default value: 1.0

Typical range of values: 0.0 ≤ WeightLink WeightLink WeightLink WeightLink weightLink

WeightRegrWeightRegrWeightRegrWeightRegrweightRegr (input_control)  real HTupleHTupleHtuple (real) (double) (double) (double)

Influence of the regression error on the total costs (NOT USED).

Default value: 0.0

Typical range of values: 0.0 ≤ WeightRegr WeightRegr WeightRegr WeightRegr weightRegr

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

Mode describing the treatment of the contours' attributes

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

split_contours_xldsplit_contours_xldSplitContoursXldSplitContoursXldSplitContoursXld, select_contours_xldselect_contours_xldSelectContoursXldSelectContoursXldSelectContoursXld

Alternatives

union_collinear_contours_xldunion_collinear_contours_xldUnionCollinearContoursXldUnionCollinearContoursXldUnionCollinearContoursXld, union_cocircular_contours_xldunion_cocircular_contours_xldUnionCocircularContoursXldUnionCocircularContoursXldUnionCocircularContoursXld, union_cotangential_contours_xldunion_cotangential_contours_xldUnionCotangentialContoursXldUnionCotangentialContoursXldUnionCotangentialContoursXld, union_adjacent_contours_xldunion_adjacent_contours_xldUnionAdjacentContoursXldUnionAdjacentContoursXldUnionAdjacentContoursXld, union_straight_contours_xldunion_straight_contours_xldUnionStraightContoursXldUnionStraightContoursXldUnionStraightContoursXld

See also

edges_sub_pixedges_sub_pixEdgesSubPixEdgesSubPixEdgesSubPix, threshold_sub_pixthreshold_sub_pixThresholdSubPixThresholdSubPixThresholdSubPix, gen_polygons_xldgen_polygons_xldGenPolygonsXldGenPolygonsXldGenPolygonsXld, split_contours_xldsplit_contours_xldSplitContoursXldSplitContoursXldSplitContoursXld, select_contours_xldselect_contours_xldSelectContoursXldSelectContoursXldSelectContoursXld, get_contour_xldget_contour_xldGetContourXldGetContourXldGetContourXld, get_contour_attrib_xldget_contour_attrib_xldGetContourAttribXldGetContourAttribXldGetContourAttribXld

Module

Foundation