From 1d62c37822b2b13ef0368754a39a52094334fbef Mon Sep 17 00:00:00 2001 From: Efi Fogel Date: Sun, 7 Sep 2025 00:28:11 +0300 Subject: [PATCH] Added some notes to indicate that inexact constructions are tolerated for do_intersect() when applied to (linear) polygons --- .../Boolean_set_operations_2.txt | 30 ++++++--- .../CGAL/Boolean_set_operations_2.h | 66 +++++++++++++++++++ 2 files changed, 88 insertions(+), 8 deletions(-) diff --git a/Boolean_set_operations_2/doc/Boolean_set_operations_2/Boolean_set_operations_2.txt b/Boolean_set_operations_2/doc/Boolean_set_operations_2/Boolean_set_operations_2.txt index 2a3b938bf2f..d1560584843 100644 --- a/Boolean_set_operations_2/doc/Boolean_set_operations_2/Boolean_set_operations_2.txt +++ b/Boolean_set_operations_2/doc/Boolean_set_operations_2/Boolean_set_operations_2.txt @@ -700,15 +700,29 @@ swap its source and target points). The traits classes `Arr_segment_traits_2`, `Arr_non_caching_segment_traits_2`, `Arr_circle_segment_traits_2`, `Arr_conic_traits_2` and `Arr_rational_function_traits_2`, which are -bundled in the `Arrangement_2` package and distributed with \cgal, -are all models of the refined concept -`AosDirectionalXMonotoneTraits_2`.\cgalFootnote{The \cgalFootnoteCode{Arr_polyline_traits_2} class is not a model of the, \cgalFootnoteCode{AosDirectionalXMonotoneTraits_2} concept, as the \f$ x\f$-monotone curve it defines is always directed from left to right. Thus, an opposite curve cannot be constructed. However, it is not very useful to construct a polygon whose edges are polylines, as an ordinary polygon with linear edges can represent the same entity.} +bundled in the `Arrangement_2` package and distributed with \cgal, are +all models of the refined concept +`AosDirectionalXMonotoneTraits_2`.\cgalFootnote{The +\cgalFootnoteCode{Arr_polyline_traits_2} class is not a model +of the, \cgalFootnoteCode{AosDirectionalXMonotoneTraits_2} concept, as +the \f$ x\f$-monotone curve it defines is always directed from left to +right. Thus, an opposite curve cannot be constructed. However, it is +not very useful to construct a polygon whose edges are polylines, as +an ordinary polygon with linear edges can represent the same entity.} -Just as with the case of computations using models of the -`AosXMonotoneTraits_2` concept, operations are robust only -when exact arithmetic is used. When inexact arithmetic is used, -(nearly) degenerate configurations may result in abnormal termination -of the program or even incorrect results. +Operations on polygons (or general polygons) are guaranteed to be +robust only if the operations of the geometry traits used to carry out +the high-level operations are robust. Most operations on polygons use +geometry traits constructors, as they generate new polygons; such +constructors are guaranteed to be robust only if the kernel in use +supports exact constructions, such as the EPEC (Exact Predicate Exact +Construction) kernel. The `do_intersect()` overloaded predicates that +operate on (linear) polygons are exceptions, as they only use geometry +traits predicates; such predicates are guaranteed to be robust only if +the kernel in use supports exact predicates, such as the EPIC (Exact +Predicate Inexact Construction) kernel. When inexact arithmetic is +used, (nearly) degenerate configurations may result in abnormal +termination of the program or even incorrect results. \subsection bso_sseccirc_seg Operating on Polygons with Circular Arcs diff --git a/Boolean_set_operations_2/doc/Boolean_set_operations_2/CGAL/Boolean_set_operations_2.h b/Boolean_set_operations_2/doc/Boolean_set_operations_2/CGAL/Boolean_set_operations_2.h index 2ba7708f501..e4079111c1b 100644 --- a/Boolean_set_operations_2/doc/Boolean_set_operations_2/CGAL/Boolean_set_operations_2.h +++ b/Boolean_set_operations_2/doc/Boolean_set_operations_2/CGAL/Boolean_set_operations_2.h @@ -723,6 +723,11 @@ namespace CGAL { //////// Traits-less /*! determines whether two polygons intersect in their interior. + * + * The kernel used to instantiate the type of the input polygons must support + * exact predicates to guarantee correct results; however, inexact constructions + * are tolerated. + * * \param pgn1 the 1st input polygon. * \param pgn2 the 2nd input polygon. * \return `true` if `pgn1` and `pgn2` intersect in their interior and `false` @@ -733,6 +738,11 @@ bool do_intersect(const Polygon_2& pgn1, const Polygon_2& pgn2); /*! determines whether two polygons intersect in their interior. + * + * The kernel used to instantiate the type of the input polygons must support + * exact predicates to guarantee correct results; however, inexact constructions + * are tolerated. + * * \param pgn1 the 1st input polygon. * \param pgn2 the 2nd input polygon. * \return `true` if `pgn1` and `pgn2` intersect in their interior and `false` @@ -743,6 +753,11 @@ bool do_intersect(const Polygon_2& pgn1, const Polygon_with_holes_2& pgn2); /*! determines whether two polygons intersect in their interior. + * + * The kernel used to instantiate the type of the input polygons must support + * exact predicates to guarantee correct results; however, inexact constructions + * are tolerated. + * * \param pgn1 the 1st input polygon. * \param pgn2 the 2nd input polygon. * \return `true` if `pgn1` and `pgn2` intersect in their interior and `false` @@ -753,6 +768,11 @@ bool do_intersect(const Polygon_with_holes_2& pgn1, const Polygon_2& pgn2); /*! determines whether two polygons with holes intersect in their interior. + * + * The kernel used to instantiate the type of the input polygons must support + * exact predicates to guarantee correct results; however, inexact constructions + * are tolerated. + * * \param pgn1 the 1st input polygon. * \param pgn2 the 2nd input polygon. * \return `true` if `pgn1` and `pgn2` intersect in their interior and `false` @@ -814,6 +834,13 @@ bool do_intersect(const General_polygon_with_holes_2& pgn1, * of general polygons or a range of general polygons with holes) determines * whether the open polygons (respectively general polygons) in the range have a common * point. + * + * When the operation is applied to linear polygons (that is, the value type of + * the input iterator is either `Polygon_2` or `Polygon_with_holes_2`), the + * kernel used to instantiate the type of the input polygons must support exact + * predicates to guarantee correct results; however, inexact constructions are + * tolerated. + * * \param begin the first iterator of the input range. Its value type is * either `Polygon_2` (respectively `General_polygon_2`) or * `Polygon_with_holes_2` (respectively `General_polygon_with_holes_2`). @@ -830,6 +857,13 @@ bool do_intersect(InputIterator begin, InputIterator end); /*! Given a range of polygons (respectively general polygons) and a range of polygons * with holes (respectively general polygons with holes) determines whether the open * polygons (respectively general polygons) in the two ranges have a common point. + * + * When the operation is applied to linear polygons (that is, the value type of + * any input iterator is either `Polygon_2` or `Polygon_with_holes_2`), the + * kernel used to instantiate the type of the input polygons must support exact + * predicates to guarantee correct results; however, inexact constructions are + * tolerated. + * * \param begin1 the first iterator of the 1st input range. Its value type is * `Polygon_2` (respectively `General_polygon_2`). * \param end1 the past-the-end iterator of the 1st input range. Its value @@ -850,6 +884,11 @@ bool do_intersect(InputIterator1 begin1, InputIterator1 end1, //////// With Traits /*! determines whether two polygons intersect in their interior. + * + * The kernel used to instantiate the type of the input polygons must support + * exact predicates to guarantee correct results; however, inexact constructions + * are tolerated. + * * \param pgn1 the 1st input polygon. * \param pgn2 the 2nd input polygon. * \param traits a traits object. @@ -863,6 +902,11 @@ bool do_intersect(const Polygon_2& pgn1, const GpsTraits& traits); /*! determines whether two polygons intersect in their interior. + * + * The kernel used to instantiate the type of the input polygons must support + * exact predicates to guarantee correct results; however, inexact constructions + * are tolerated. + * * \param pgn1 the 1st input polygon. * \param pgn2 the 2nd input polygon. * \param traits a traits object. @@ -876,6 +920,11 @@ bool do_intersect(const Polygon_2& pgn1, const GpsTraits& traits); /*! determines whether two polygons intersect in their interior. + * + * The kernel used to instantiate the type of the input polygons must support + * exact predicates to guarantee correct results; however, inexact constructions + * are tolerated. + * * \param pgn1 the 1st input polygon. * \param pgn2 the 2nd input polygon. * \param traits a traits object. @@ -889,6 +938,11 @@ bool do_intersect(const Polygon_with_holes_2& pgn1, const GpsTraits& traits); /*! determines whether two polygons with holes intersect in their interior. + * + * The kernel used to instantiate the type of the input polygons must support + * exact predicates to guarantee correct results; however, inexact constructions + * are tolerated. + * * \param pgn1 the 1st input polygon. * \param pgn2 the 2nd input polygon. * \param traits a traits object. @@ -967,6 +1021,12 @@ bool do_intersect(const General_polygon_with_holes_2& pgn1, * of general polygons or a range of general polygons with holes) determines * whether the open polygons (respectively general polygons) in the range have a common * point. + * + * When the operation is applied to linear polygons (that is, the value type of + * the input iterator is either `Polygon_2` or `Polygon_with_holes_2`), the + * traits parameter `GpsTraits` must support exact predicates to guarantee + * correct results; however, inexact constructions are tolerated. + * * \param begin the first iterator of the input range. Its value type is * either `Polygon_2` (respectively `General_polygon_2`) or * `Polygon_with_holes_2` (respectively `General_polygon_with_holes_2`). @@ -986,6 +1046,12 @@ bool do_intersect(InputIterator begin, InputIterator end, /*! Given a range of polygons (respectively general polygons) and a range of polygons * with holes (respectively general polygons with holes) determines whether the open * polygons (respectively general polygons) in the two ranges have a common point. + * + * When the operation is applied to linear polygons (that is, the value type of + * any input iterator is either `Polygon_2` or `Polygon_with_holes_2`), the + * traits parameter `GpsTraits` must support exact predicates to guarantee + * correct results; however, inexact constructions are tolerated. + * * \param begin1 the first iterator of the 1st input range. Its value type is * `Polygon_2` (respectively `General_polygon_2`). * \param end1 the past-the-end iterator of the 1st input range. Its value