union_collinear_contours_ext_xldunion_collinear_contours_ext_xldUnionCollinearContoursExtXldUnionCollinearContoursExtXldunion_collinear_contours_ext_xld (Operator)

Name

union_collinear_contours_ext_xldunion_collinear_contours_ext_xldUnionCollinearContoursExtXldUnionCollinearContoursExtXldunion_collinear_contours_ext_xld — 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)

def union_collinear_contours_ext_xld(contours: HObject, max_dist_abs: float, max_dist_rel: float, max_shift: float, max_angle: float, max_overlap: float, max_regr_error: float, max_costs: float, weight_dist: float, weight_shift: float, weight_angle: float, weight_link: float, weight_regr: float, mode: str) -> HObject

Description

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

Parameters

The parameters MaxDistAbsMaxDistAbsMaxDistAbsMaxDistAbsmaxDistAbsmax_dist_abs, MaxDistRelMaxDistRelMaxDistRelMaxDistRelmaxDistRelmax_dist_rel, MaxShiftMaxShiftMaxShiftMaxShiftmaxShiftmax_shift, and MaxAngleMaxAngleMaxAngleMaxAnglemaxAnglemax_angle operate as described for the operator union_collinear_contours_xldunion_collinear_contours_xldUnionCollinearContoursXldUnionCollinearContoursXldUnionCollinearContoursXldunion_collinear_contours_xld.

MaxOverlapMaxOverlapMaxOverlapMaxOverlapmaxOverlapmax_overlap

In addition, the parameter MaxOverlapMaxOverlapMaxOverlapMaxOverlapmaxOverlapmax_overlap 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 MaxOverlapMaxOverlapMaxOverlapMaxOverlapmaxOverlapmax_overlap -- that the overlap is not bigger than a third of the length of both contours.

image/svg+xml a b
MaxRegrErrorMaxRegrErrorMaxRegrErrorMaxRegrErrormaxRegrErrormax_regr_error

The parameter MaxRegrErrorMaxRegrErrorMaxRegrErrorMaxRegrErrormaxRegrErrormax_regr_error 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).

MaxCostsMaxCostsMaxCostsMaxCostsmaxCostsmax_costs

With the help of the parameter MaxCostsMaxCostsMaxCostsMaxCostsmaxCostsmax_costs 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.

WeightDistWeightDistWeightDistWeightDistweightDistweight_dist, WeightShiftWeightShiftWeightShiftWeightShiftweightShiftweight_shift, WeightAngleWeightAngleWeightAngleWeightAngleweightAngleweight_angle, WeightLinkWeightLinkWeightLinkWeightLinkweightLinkweight_link, and WeightRegrWeightRegrWeightRegrWeightRegrweightRegrweight_regr

The influence of the different values on the total costs is adjusted by passing appropriate weights with the parameters WeightDistWeightDistWeightDistWeightDistweightDistweight_dist, WeightShiftWeightShiftWeightShiftWeightShiftweightShiftweight_shift, WeightAngleWeightAngleWeightAngleWeightAngleweightAngleweight_angle, WeightLinkWeightLinkWeightLinkWeightLinkweightLinkweight_link, WeightRegrWeightRegrWeightRegrWeightRegrweightRegrweight_regr. 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 WeightRegrWeightRegrWeightRegrWeightRegrweightRegrweight_regr is not used.

ModeModeModeModemodemode

The parameter ModeModeModeModemodemode controls -- as for union_collinear_contours_xldunion_collinear_contours_xldUnionCollinearContoursXldUnionCollinearContoursXldUnionCollinearContoursXldunion_collinear_contours_xld -- how to handle the attributes of the input contours.

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 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 max_dist_abs

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

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

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

MaxOverlapMaxOverlapMaxOverlapMaxOverlapmaxOverlapmax_overlap (input_control)  real HTuplefloatHTupleHtuple (real) (double) (double) (double)

Maximum range of the overlap.

Default value: 0.0

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

MaxRegrErrorMaxRegrErrorMaxRegrErrorMaxRegrErrormaxRegrErrormax_regr_error (input_control)  real HTuplefloatHTupleHtuple (real) (double) (double) (double)

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

Default value: -1.0

MaxCostsMaxCostsMaxCostsMaxCostsmaxCostsmax_costs (input_control)  real HTuplefloatHTupleHtuple (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 max_costs

WeightDistWeightDistWeightDistWeightDistweightDistweight_dist (input_control)  real HTuplefloatHTupleHtuple (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 weight_dist

WeightShiftWeightShiftWeightShiftWeightShiftweightShiftweight_shift (input_control)  real HTuplefloatHTupleHtuple (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 weight_shift

WeightAngleWeightAngleWeightAngleWeightAngleweightAngleweight_angle (input_control)  real HTuplefloatHTupleHtuple (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 weight_angle

WeightLinkWeightLinkWeightLinkWeightLinkweightLinkweight_link (input_control)  real HTuplefloatHTupleHtuple (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 weight_link

WeightRegrWeightRegrWeightRegrWeightRegrweightRegrweight_regr (input_control)  real HTuplefloatHTupleHtuple (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 weight_regr

ModeModeModeModemodemode (input_control)  string HTuplestrHTupleHtuple (string) (string) (HString) (char*)

Mode describing the treatment of the contours' attributes

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

split_contours_xldsplit_contours_xldSplitContoursXldSplitContoursXldSplitContoursXldsplit_contours_xld, select_contours_xldselect_contours_xldSelectContoursXldSelectContoursXldSelectContoursXldselect_contours_xld

Alternatives

union_collinear_contours_xldunion_collinear_contours_xldUnionCollinearContoursXldUnionCollinearContoursXldUnionCollinearContoursXldunion_collinear_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, union_straight_contours_xldunion_straight_contours_xldUnionStraightContoursXldUnionStraightContoursXldUnionStraightContoursXldunion_straight_contours_xld

See also

edges_sub_pixedges_sub_pixEdgesSubPixEdgesSubPixEdgesSubPixedges_sub_pix, threshold_sub_pixthreshold_sub_pixThresholdSubPixThresholdSubPixThresholdSubPixthreshold_sub_pix, gen_polygons_xldgen_polygons_xldGenPolygonsXldGenPolygonsXldGenPolygonsXldgen_polygons_xld, split_contours_xldsplit_contours_xldSplitContoursXldSplitContoursXldSplitContoursXldsplit_contours_xld, select_contours_xldselect_contours_xldSelectContoursXldSelectContoursXldSelectContoursXldselect_contours_xld, get_contour_xldget_contour_xldGetContourXldGetContourXldGetContourXldget_contour_xld, get_contour_attrib_xldget_contour_attrib_xldGetContourAttribXldGetContourAttribXldGetContourAttribXldget_contour_attrib_xld

Module

Foundation