union_cocircular_contours_xldunion_cocircular_contours_xldUnionCocircularContoursXldUnionCocircularContoursXldunion_cocircular_contours_xld (Operator)
union_cocircular_contours_xldunion_cocircular_contours_xldUnionCocircularContoursXldUnionCocircularContoursXldunion_cocircular_contours_xld — Compute the union of contours that belong to the same circle.
Signature
Herror union_cocircular_contours_xld(const Hobject Contours, Hobject* UnionContours, double MaxArcAngleDiff, double MaxArcOverlap, double MaxTangentAngle, double MaxDist, double MaxRadiusDiff, double MaxCenterDist, const char* MergeSmallContours, const Hlong Iterations)
Herror T_union_cocircular_contours_xld(const Hobject Contours, Hobject* UnionContours, const Htuple MaxArcAngleDiff, const Htuple MaxArcOverlap, const Htuple MaxTangentAngle, const Htuple MaxDist, const Htuple MaxRadiusDiff, const Htuple MaxCenterDist, const Htuple MergeSmallContours, const Htuple Iterations)
void UnionCocircularContoursXld(const HObject& Contours, HObject* UnionContours, const HTuple& MaxArcAngleDiff, const HTuple& MaxArcOverlap, const HTuple& MaxTangentAngle, const HTuple& MaxDist, const HTuple& MaxRadiusDiff, const HTuple& MaxCenterDist, const HTuple& MergeSmallContours, const HTuple& Iterations)
HXLDCont HXLDCont::UnionCocircularContoursXld(const HTuple& MaxArcAngleDiff, const HTuple& MaxArcOverlap, const HTuple& MaxTangentAngle, const HTuple& MaxDist, const HTuple& MaxRadiusDiff, const HTuple& MaxCenterDist, const HString& MergeSmallContours, Hlong Iterations) const
HXLDCont HXLDCont::UnionCocircularContoursXld(double MaxArcAngleDiff, double MaxArcOverlap, double MaxTangentAngle, double MaxDist, double MaxRadiusDiff, double MaxCenterDist, const HString& MergeSmallContours, Hlong Iterations) const
HXLDCont HXLDCont::UnionCocircularContoursXld(double MaxArcAngleDiff, double MaxArcOverlap, double MaxTangentAngle, double MaxDist, double MaxRadiusDiff, double MaxCenterDist, const char* MergeSmallContours, Hlong Iterations) const
HXLDCont HXLDCont::UnionCocircularContoursXld(double MaxArcAngleDiff, double MaxArcOverlap, double MaxTangentAngle, double MaxDist, double MaxRadiusDiff, double MaxCenterDist, const wchar_t* MergeSmallContours, Hlong Iterations) const
(
Windows only)
static void HOperatorSet.UnionCocircularContoursXld(HObject contours, out HObject unionContours, HTuple maxArcAngleDiff, HTuple maxArcOverlap, HTuple maxTangentAngle, HTuple maxDist, HTuple maxRadiusDiff, HTuple maxCenterDist, HTuple mergeSmallContours, HTuple iterations)
HXLDCont HXLDCont.UnionCocircularContoursXld(HTuple maxArcAngleDiff, HTuple maxArcOverlap, HTuple maxTangentAngle, HTuple maxDist, HTuple maxRadiusDiff, HTuple maxCenterDist, string mergeSmallContours, int iterations)
HXLDCont HXLDCont.UnionCocircularContoursXld(double maxArcAngleDiff, double maxArcOverlap, double maxTangentAngle, double maxDist, double maxRadiusDiff, double maxCenterDist, string mergeSmallContours, int iterations)
def union_cocircular_contours_xld(contours: HObject, max_arc_angle_diff: Union[int, float], max_arc_overlap: Union[int, float], max_tangent_angle: Union[int, float], max_dist: Union[int, float], max_radius_diff: Union[int, float], max_center_dist: Union[int, float], merge_small_contours: str, iterations: int) -> HObject
Description
The operator union_cocircular_contours_xldunion_cocircular_contours_xldUnionCocircularContoursXldUnionCocircularContoursXldunion_cocircular_contours_xld merges all
contours that belong to the same circle. The result is a set of
contours in which contours on the same circle are connected.
The algorithm tries to merge contours by first fitting circles to
each contour and then examining the result by means of radius, circle
center, and gap on the circular arc. The list of contours is processed
in sequence of increasing radii. Contours to which no circle could be
fitted are optionally merged in a second pass.
The threshold parameters are used to define whether contours belong
to the same circle. All thresholds must be fulfilled simultaneously
for two contours to be merged.
Parameters
MaxArcAngleDiffMaxArcAngleDiffMaxArcAngleDiffmaxArcAngleDiffmax_arc_angle_diff-
The parameter MaxArcAngleDiffMaxArcAngleDiffMaxArcAngleDiffmaxArcAngleDiffmax_arc_angle_diff defines the maximum angular distance
in radians between the end point of one contour and the start point of
a second contour on a circle.
MaxArcOverlapMaxArcOverlapMaxArcOverlapmaxArcOverlapmax_arc_overlap-
MaxArcOverlapMaxArcOverlapMaxArcOverlapmaxArcOverlapmax_arc_overlap denotes the maximum angle by which
contours may overlap.
MaxTangentAngleMaxTangentAngleMaxTangentAnglemaxTangentAnglemax_tangent_angle-
MaxTangentAngleMaxTangentAngleMaxTangentAnglemaxTangentAnglemax_tangent_angle describes the maximum
angle between circle tangents and the connecting line of two
contours.
MaxDistMaxDistMaxDistmaxDistmax_dist-
MaxDistMaxDistMaxDistmaxDistmax_dist denotes the maximum absolute distance in
pixels of the end and start points of two
contours.
MaxRadiusDiffMaxRadiusDiffMaxRadiusDiffmaxRadiusDiffmax_radius_diff-
MaxRadiusDiffMaxRadiusDiffMaxRadiusDiffmaxRadiusDiffmax_radius_diff is the maximum
absolute difference of the radii of circles fitted to the
contours.
MaxCenterDistMaxCenterDistMaxCenterDistmaxCenterDistmax_center_dist-
MaxCenterDistMaxCenterDistMaxCenterDistmaxCenterDistmax_center_dist is the limit of the Euclidean
distance of the circle centers.
MergeSmallContoursMergeSmallContoursMergeSmallContoursmergeSmallContoursmerge_small_contours-
If the parameter MergeSmallContoursMergeSmallContoursMergeSmallContoursmergeSmallContoursmerge_small_contours is set to
'true'"true""true""true""true", contours without fitted circles are also merged.
For a small contour to match, each point of the contour needs to
have a distance to the circle center which differs from the radius
by not more then MaxRadiusDiffMaxRadiusDiffMaxRadiusDiffmaxRadiusDiffmax_radius_diff. The angle between a line
between two consecutive points on the contour and the circle tangent
must be within MaxTangentAngleMaxTangentAngleMaxTangentAnglemaxTangentAnglemax_tangent_angle. Additionally, the condition
for MaxDistMaxDistMaxDistmaxDistmax_dist must be fulfilled for two contours to be merged.
IterationsIterationsIterationsiterationsiterations-
Merging of contours leads to new circle parameters. Therefore, an
iteration can lead to further merges. The parameter
IterationsIterationsIterationsiterationsiterations controls the number of iterations. More than two
iterations are seldom needed.
For each possible merge of two contours a cost is calculated by
summing up the distances corresponding to the different threshold
values. For comparability, the distances are scaled by the
thresholds to a value between 0.0 and 1.0. If two or more
contour start points match to the same end point of another contour,
the contour with the lower cost is merged.
You should make sure that the input contours can be approximated by
lines and circular arcs, for example by preprocessing them with
split_contours_xldsplit_contours_xldSplitContoursXldSplitContoursXldsplit_contours_xld.
Attention
Note that already closed contours are not considered for a union
anymore. That is, even if a contour and the already closed contour share the
same circle, they are returned as separate contours.
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
ContoursContoursContourscontourscontours (input_object) xld_cont-array → objectHXLDContHObjectHObjectHobject
Contours to be merged.
UnionContoursUnionContoursUnionContoursunionContoursunion_contours (output_object) xld_cont-array → objectHXLDContHObjectHObjectHobject *
Merged contours.
MaxArcAngleDiffMaxArcAngleDiffMaxArcAngleDiffmaxArcAngleDiffmax_arc_angle_diff (input_control) angle.rad → HTupleUnion[int, float]HTupleHtuple (real / integer) (double / int / long) (double / Hlong) (double / Hlong)
Maximum angular distance of two circular arcs.
Default:
0.5
Suggested values:
0.25, 0.5, 0.75, 1.0
MaxArcOverlapMaxArcOverlapMaxArcOverlapmaxArcOverlapmax_arc_overlap (input_control) angle.rad → HTupleUnion[int, float]HTupleHtuple (real / integer) (double / int / long) (double / Hlong) (double / Hlong)
Maximum overlap of two circular arcs.
Default:
0.1
Suggested values:
0.0, 0.1, 0.2
MaxTangentAngleMaxTangentAngleMaxTangentAnglemaxTangentAnglemax_tangent_angle (input_control) angle.rad → HTupleUnion[int, float]HTupleHtuple (real / integer) (double / int / long) (double / Hlong) (double / Hlong)
Maximum angle between the connecting line and the
tangents of circular arcs.
Default:
0.2
Suggested values:
0.1, 0.2, 0.3, 0.4, 0.5
MaxDistMaxDistMaxDistmaxDistmax_dist (input_control) number → HTupleUnion[int, float]HTupleHtuple (real / integer) (double / int / long) (double / Hlong) (double / Hlong)
Maximum length of the gap between two circular
arcs in pixels.
Default:
30
Suggested values:
10, 30, 50, 70
MaxRadiusDiffMaxRadiusDiffMaxRadiusDiffmaxRadiusDiffmax_radius_diff (input_control) number → HTupleUnion[int, float]HTupleHtuple (real / integer) (double / int / long) (double / Hlong) (double / Hlong)
Maximum radius difference of the circles fitted
to two arcs.
Default:
10
Suggested values:
10, 20, 30
MaxCenterDistMaxCenterDistMaxCenterDistmaxCenterDistmax_center_dist (input_control) number → HTupleUnion[int, float]HTupleHtuple (real / integer) (double / int / long) (double / Hlong) (double / Hlong)
Maximum center distance of the circles fitted
to two arcs.
Default:
10
Suggested values:
10, 20, 30
MergeSmallContoursMergeSmallContoursMergeSmallContoursmergeSmallContoursmerge_small_contours (input_control) string → HTuplestrHTupleHtuple (string) (string) (HString) (char*)
Determine whether small contours without fitted
circles should also be merged.
Default:
'true'
"true"
"true"
"true"
"true"
List of values:
'false'"false""false""false""false", 'true'"true""true""true""true"
IterationsIterationsIterationsiterationsiterations (input_control) integer → HTupleintHTupleHtuple (integer) (int / long) (Hlong) (Hlong)
Number of iterations.
Default:
1
Suggested values:
1, 2
Complexity
O(n^2) for n contours.
Result
union_cocircular_contours_xldunion_cocircular_contours_xldUnionCocircularContoursXldUnionCocircularContoursXldunion_cocircular_contours_xld returns 2 (
H_MSG_TRUE)
if all
parameters are correct.
Possible Predecessors
split_contours_xldsplit_contours_xldSplitContoursXldSplitContoursXldsplit_contours_xld,
select_contours_xldselect_contours_xldSelectContoursXldSelectContoursXldselect_contours_xld
Alternatives
union_collinear_contours_xldunion_collinear_contours_xldUnionCollinearContoursXldUnionCollinearContoursXldunion_collinear_contours_xld,
union_cotangential_contours_xldunion_cotangential_contours_xldUnionCotangentialContoursXldUnionCotangentialContoursXldunion_cotangential_contours_xld,
union_straight_contours_xldunion_straight_contours_xldUnionStraightContoursXldUnionStraightContoursXldunion_straight_contours_xld,
union_adjacent_contours_xldunion_adjacent_contours_xldUnionAdjacentContoursXldUnionAdjacentContoursXldunion_adjacent_contours_xld,
union_collinear_contours_ext_xldunion_collinear_contours_ext_xldUnionCollinearContoursExtXldUnionCollinearContoursExtXldunion_collinear_contours_ext_xld
Module
Foundation