union_straight_contours_xldUnionStraightContoursXldUnionStraightContoursXldunion_straight_contours_xldunion_straight_contours_xld🔗

Short description🔗

union_straight_contours_xldUnionStraightContoursXldUnionStraightContoursXldunion_straight_contours_xldunion_straight_contours_xld — Compute the union of neighboring straight contours that have a similar direction.

Signature🔗

union_straight_contours_xld( xld_cont Contours, out xld_cont UnionContours, real MaxDist, angle.rad MaxDiff, real Percent, string Mode, string Iterations )

Description🔗

union_straight_contours_xldUnionStraightContoursXld merges neighboring XLD contours Contourscontourscontours if certain criteria are fulfilled. At each iteration, at most two contours that fulfill the given criteria are merged. The parameter Iterationsiterationsiterations controls how often this step is executed.

Two contours are merged if the shortest distance between their end points (end points are the projections of the contours’ first and last points onto its regression line) is smaller than MaxDistmaxDistmax_dist, and if the difference in direction (i.e., the regression lines’ direction) is smaller than MaxDiffmaxDiffmax_diff (radians).

\(a \leq \textrm{MaxDist}\)

\(a \leq \textrm{MaxDiff}\)

If only one of the criteria is fulfilled, the decision on merging can be influenced by the weighting factor Percentpercentpercent, which allows the exceeding of one limit to be balanced by the other value remaining below the limit by the same amount. The end point distance is weighted by Percentpercentpercent, while the directional difference is weighted by 100 - Percent.

This means that two contours are merged if they fulfill the following condition:

\[\begin{eqnarray*} \frac{shortest~distance}{\textrm{MaxDist}}\cdot\textrm{Percent} + \frac{direction~difference}{\textrm{MaxDiff}}\cdot(100-\textrm{Percent}) \le 100\end{eqnarray*}\]

If, for example, two contours have an end point distance of 5.0 and a directional difference of 0.5 (with the limits chosen being MaxDistmaxDistmax_dist = 4.04.0 and MaxDiffmaxDiffmax_diff = 0.6250.625), both values differ from the limits by 25%. By choosing Percentpercentpercent = 6060%, the larger end point distance is weighted more than the smaller directional difference, and thus the contours are not merged. Contrary, if Percentpercentpercent = 4040% is chosen, the contours are merged.

For Percentpercentpercent = 100100%, only the end point distance is taken into account, while for Percentpercentpercent = 00% only the difference of direction is used. If Percentpercentpercent = 5050% both criteria are equally valid.

In case there are parallel contours, there is a danger of merging neighboring contours. If this is to be avoided, Modemodemode = 'noparallel'"noparallel" has to be chosen, while otherwise Modemodemode = 'paralleltoo'"paralleltoo" suffices. For Modemodemode = 'every'"every", contours are merged unconditionally. All other parameters have no influence in this case.

The parameters of the regression line are calculated anew for merged contours.

Attention🔗

Before contours can be united by union_straight_contours_xldUnionStraightContoursXld, the parameters of the regression lines to the contours must be calculated by calling regress_contours_xldRegressContoursXld.

Furthermore, note that union_straight_contours_xldUnionStraightContoursXld can not compute the union of contours with different contour point attributes. This can be the case if different operators are used for the contour extraction (e.g., lines_gaussLinesGauss and lines_facetLinesFacet). For information on the contour attributes and when they are defined, see the respective operator reference. You can query the point attributes of your contour using query_contour_attribs_xldQueryContourAttribsXld.

Execution information🔗

Execution information

Multithreading type: reentrant (runs in parallel with non-exclusive operators).
Multithreading scope: global (may be called from any thread).
Processed without parallelization.

Parameters🔗

Contourscontourscontours (input_object) xld_cont-array → objectHObjectHXLDContHObjectHobject

Input XLD contours.

UnionContoursunionContoursunion_contours (output_object) xld_cont-array → objectHObjectHXLDContHObjectHobject *

Output XLD contours.

MaxDistmaxDistmax_dist (input_control) real → (real)HTuple (double)HTuple (double)floatHtuple (double)

Maximum distance of the contours’ endpoints.

Default: 5.05.0

MaxDiffmaxDiffmax_diff (input_control) angle.rad → (real)HTuple (double)HTuple (double)floatHtuple (double)

Maximum difference in direction.

Default: 0.50.5

Percentpercentpercent (input_control) real → (real)HTuple (double)HTuple (double)floatHtuple (double)

Weighting factor for the two selection criteria.

Default: 50.050.0

Modemodemode (input_control) string → (string)HTuple (HString)HTuple (string)strHtuple (char*)

Should parallel contours be taken into account?

Default: 'noparallel'"noparallel"
List of values: 'every', 'noparallel', 'paralleltoo'"every", "noparallel", "paralleltoo"

Iterationsiterationsiterations (input_control) string → (string / integer)HTuple (HString / Hlong)HTuple (string / int / long)Union[int, str]Htuple (char* / Hlong)

Number of iterations or ‘maximum’.

Default: 'maximum'"maximum"
Suggested values: 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 'maximum'
Value range: 1 ≤ Iterations ≤ 500 (lin)
Minimum increment: 1
Recommended increment: 1

Combinations with other operators🔗

Combinations

Possible predecessors

regress_contours_xldRegressContoursXld

Alternatives

union_collinear_contours_xldUnionCollinearContoursXld, union_collinear_contours_ext_xldUnionCollinearContoursExtXld, union_cocircular_contours_xldUnionCocircularContoursXld, union_cotangential_contours_xldUnionCotangentialContoursXld, union_adjacent_contours_xldUnionAdjacentContoursXld

Module🔗

Foundation