ClassesClassesClassesClasses | | | | Operators

union_collinear_contours_xldunion_collinear_contours_xldUnionCollinearContoursXldunion_collinear_contours_xldUnionCollinearContoursXldUnionCollinearContoursXld (Operator)

Name

union_collinear_contours_xldunion_collinear_contours_xldUnionCollinearContoursXldunion_collinear_contours_xldUnionCollinearContoursXldUnionCollinearContoursXld — Compute the union of 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)

Herror union_collinear_contours_xld(Hobject Contours, Hobject* UnionContours, const HTuple& MaxDistAbs, const HTuple& MaxDistRel, const HTuple& MaxShift, const HTuple& MaxAngle, const HTuple& Mode)

HXLDContArray HXLDContArray::UnionCollinearContoursXld(const HTuple& MaxDistAbs, const HTuple& MaxDistRel, const HTuple& MaxShift, const HTuple& MaxAngle, const HTuple& Mode) const

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

void HOperatorSetX.UnionCollinearContoursXld(
[in] IHUntypedObjectX* Contours, [out] IHUntypedObjectX*UnionContours, [in] VARIANT MaxDistAbs, [in] VARIANT MaxDistRel, [in] VARIANT MaxShift, [in] VARIANT MaxAngle, [in] VARIANT Mode)

IHXLDContX* HXLDContX.UnionCollinearContoursXld(
[in] double MaxDistAbs, [in] double MaxDistRel, [in] double MaxShift, [in] double MaxAngle, [in] BSTR Mode)

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)

Description

The operator union_collinear_contours_xldunion_collinear_contours_xldUnionCollinearContoursXldunion_collinear_contours_xldUnionCollinearContoursXldUnionCollinearContoursXld unifies all contours within the input XLD contour array (ContoursContoursContoursContoursContourscontours) that are collinear, i.e., which lie approximately on the same line. The unified contour consists of the concatenation of the contour points of the input contours. If necessary, the order of these input contour points is flipped, so that the end points of the contours that have to be connected are direct neighbors in the resulting point list. This operation is repeated until there are no more unconnected collinear contours left. As a result all the contours that are newly created by unification, as well as the input contours that could not be connected with any other contour, are returned in UnionContoursUnionContoursUnionContoursUnionContoursUnionContoursunionContours.

Two lines are said to be collinear if one of the lines can be continued on a straight line by the other one. For this it is sufficient that one line is continued by the other, i.e. it is not necessary that both lines continue each other. However, if one line is significantly longer than the other one (twice the length), the longer one must be continued by the shorter, not vice versa.

Two contours are basically collinear if the regression lines - limited by the projections of the contours' endpoints - are collinear. Before calling union_collinear_contours_xldunion_collinear_contours_xldUnionCollinearContoursXldunion_collinear_contours_xldUnionCollinearContoursXldUnionCollinearContoursXld, make sure that the input contours are straight lines. Note that closed contours are not collinear to any other contour.

The parameters MaxDistAbsMaxDistAbsMaxDistAbsMaxDistAbsMaxDistAbsmaxDistAbs, MaxDistRelMaxDistRelMaxDistRelMaxDistRelMaxDistRelmaxDistRel, MaxShiftMaxShiftMaxShiftMaxShiftMaxShiftmaxShift, and MaxAngleMaxAngleMaxAngleMaxAngleMaxAnglemaxAngle are used to define the conditions for the collinearity of two contours. The first three parameters have to be seen in relation to the line that is currently investigated for possible elongations by the other contour. MaxDistAbsMaxDistAbsMaxDistAbsMaxDistAbsMaxDistAbsmaxDistAbs describes the maximum acceptable distance between the two contours in the direction of the regression line of the investigated contour. This is equal to the distance of the projections of the neighboring end points of the contours on the first regression line. The parameter MaxDistRelMaxDistRelMaxDistRelMaxDistRelMaxDistRelmaxDistRel stands for the same distance, defining it, however, in relation to the length of the investigated line. The threshold which is actually applied for the investigated contour is the minimum of the distances defined by the two parameters.

The parameter MaxShiftMaxShiftMaxShiftMaxShiftMaxShiftmaxShift defines the maximum distance of the second contour from the regression line of the investigated contour, i.e., this distance is measured perpendicular to the regression line. The criterion here is the distance between the projections of the second contour on its own regression line and the other regression line, namely the bigger one. And finally, MaxAngleMaxAngleMaxAngleMaxAngleMaxAnglemaxAngle determines the threshold for the angle (in radians) between the two candidates' regression lines.

Two contours can not be unified unless all criteria (in relation to one of the contours defining the base line) are fullfilled, i.e., all values must be lower or equal the specified thresholds. As another precondition contours must not overlap each other significantly. A maximum overlap of 0.5 pixels is tolerated. For adjusting the overlap tolerance more precisely, the operator union_collinear_contours_ext_xldunion_collinear_contours_ext_xldUnionCollinearContoursExtXldunion_collinear_contours_ext_xldUnionCollinearContoursExtXldUnionCollinearContoursExtXld has to be used. This is an extended version of the operator union_collinear_contours_xldunion_collinear_contours_xldUnionCollinearContoursXldunion_collinear_contours_xldUnionCollinearContoursXldUnionCollinearContoursXld and gives beside several other parameters the opportunity to define an overlap range.

Besides finding possible candidate contours for the union, it is important for the behavior of this operator to determine the order that is used for connecting the contours. The reason for this is that, in general, after connecting two contours the evaluation of the resulting contour will differ from the evaluation of the parts before. So it is possible that a contour can be unified with one or the other of its neighbors, but not with both. Therefore, all contour pairs, which may be connected, are rated by union_collinear_contours_xldunion_collinear_contours_xldUnionCollinearContoursXldunion_collinear_contours_xldUnionCollinearContoursXldUnionCollinearContoursXld, which calculates the costs or a total distance value for the unification. The contour pair with the best evaluation (the lowest costs) is connected first. Then - with the resulting contour - the contour list is searched again for potential connection candidates. If there are new connectable pairs they are evaluated and entered into the candidate list. If the best evaluation is exactly the same for two (ore more) pairs of candidates, the order of connecting the contours depends on the order of the contours in XLD object array. Note that if one contour is part of several pairs, the second contour unification may become obsolete by the first one.

The costs (or total distance) of a connection are calculated from the distances which were defined above. The smaller the individual distances between two contours, the smaller the costs. If one distance is close to the appropriate threshold the portion of that specific parameter on the costs becomes maximal. An additional term for calculating the costs depends on the line segment that connects the two contours. This portion depends on the angle of the line segment against the regression line as well as of its length (i.e., the part perpendicular to the regression line).

To sum up the costs, the different parameters are normalized by the specified thresholds and weighted equally. In contrast, the operator union_collinear_contours_ext_xldunion_collinear_contours_ext_xldUnionCollinearContoursExtXldunion_collinear_contours_ext_xldUnionCollinearContoursExtXldUnionCollinearContoursExtXld gives the opportunity to control the influence of each individual parameter separately. In addition, this operator allows to set a limit for the total costs in order to avoid the connection of contours which are close to the limits of all criteria.

Finally, by the parameter ModeModeModeModeModemode it is possible to control how to handle the attributes that may come with input contours. For example, the operator edges_sub_pixedges_sub_pixEdgesSubPixedges_sub_pixEdgesSubPixEdgesSubPix attaches to every contour point attributes like the local orientation, the edge response, and the edge direction. Choosing the default value 'attr_keep'"attr_keep""attr_keep""attr_keep""attr_keep""attr_keep", all attributes are copied to the output, and - if a contour has to be flipped for connecting it with another one - they are adapted to the new orientation. With a great number of input contours, however, it may be sensible to ignore the attributes for performance reasons, especially if they are not needed for further calculations. For this the value 'attr_forget'"attr_forget""attr_forget""attr_forget""attr_forget""attr_forget" has to be passed.

Parallelization

Parameters

ContoursContoursContoursContoursContourscontours (input_object)  xld_cont-array objectHXLDContHXLDContHXLDContArrayHXLDContXHobject

Input XLD contours.

UnionContoursUnionContoursUnionContoursUnionContoursUnionContoursunionContours (output_object)  xld_cont-array objectHXLDContHXLDContHXLDContArrayHXLDContXHobject *

Output XLD contours.

MaxDistAbsMaxDistAbsMaxDistAbsMaxDistAbsMaxDistAbsmaxDistAbs (input_control)  real HTupleHTupleHTupleVARIANTHtuple (real) (double) (double) (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 maxDistAbs

MaxDistRelMaxDistRelMaxDistRelMaxDistRelMaxDistRelmaxDistRel (input_control)  real HTupleHTupleHTupleVARIANTHtuple (real) (double) (double) (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 maxDistRel

MaxShiftMaxShiftMaxShiftMaxShiftMaxShiftmaxShift (input_control)  real HTupleHTupleHTupleVARIANTHtuple (real) (double) (double) (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 maxShift

MaxAngleMaxAngleMaxAngleMaxAngleMaxAnglemaxAngle (input_control)  real HTupleHTupleHTupleVARIANTHtuple (real) (double) (double) (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 maxAngle ≤ 0.78539816339

ModeModeModeModeModemode (input_control)  string HTupleHTupleHTupleVARIANTHtuple (string) (string) (HString) (char*) (BSTR) (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_xldSplitContoursXldsplit_contours_xldSplitContoursXldSplitContoursXld, select_contours_xldselect_contours_xldSelectContoursXldselect_contours_xldSelectContoursXldSelectContoursXld

Alternatives

union_collinear_contours_ext_xldunion_collinear_contours_ext_xldUnionCollinearContoursExtXldunion_collinear_contours_ext_xldUnionCollinearContoursExtXldUnionCollinearContoursExtXld, union_cocircular_contours_xldunion_cocircular_contours_xldUnionCocircularContoursXldunion_cocircular_contours_xldUnionCocircularContoursXldUnionCocircularContoursXld, union_straight_contours_xldunion_straight_contours_xldUnionStraightContoursXldunion_straight_contours_xldUnionStraightContoursXldUnionStraightContoursXld, union_adjacent_contours_xldunion_adjacent_contours_xldUnionAdjacentContoursXldunion_adjacent_contours_xldUnionAdjacentContoursXldUnionAdjacentContoursXld, union_cotangential_contours_xldunion_cotangential_contours_xldUnionCotangentialContoursXldunion_cotangential_contours_xldUnionCotangentialContoursXldUnionCotangentialContoursXld

See also

edges_sub_pixedges_sub_pixEdgesSubPixedges_sub_pixEdgesSubPixEdgesSubPix, threshold_sub_pixthreshold_sub_pixThresholdSubPixthreshold_sub_pixThresholdSubPixThresholdSubPix, gen_polygons_xldgen_polygons_xldGenPolygonsXldgen_polygons_xldGenPolygonsXldGenPolygonsXld, get_contour_xldget_contour_xldGetContourXldget_contour_xldGetContourXldGetContourXld, get_contour_attrib_xldget_contour_attrib_xldGetContourAttribXldget_contour_attrib_xldGetContourAttribXldGetContourAttribXld

Module

Foundation


ClassesClassesClassesClasses | | | | Operators