Fixed documentation

This commit is contained in:
Efi Fogel 2021-02-24 18:59:43 +02:00
parent fb1d6dea5a
commit 391c1a22ff
2 changed files with 634 additions and 456 deletions

View File

@ -109,7 +109,9 @@ general polygons, where the edges of a general polygon may be
general \f$ x\f$-monotone curves, rather than being simple line segments.
</UL>
<!----------------------------------------------------------------------------->
\subsection bso_ssecpolygon_validation Conditions for Valid Polygons
<!----------------------------------------------------------------------------->
In our context, a polygon must uphold the following conditions:
@ -119,7 +121,10 @@ In our context, a polygon must uphold the following conditions:
<LI><I>Orientation</I> - the polygon's outer boundary must be <I>counter-clockwise oriented</I>.
</OL>
\subsection bso_ssecpolygon_with_holes_validation Conditions for Valid Polygons with Holes
<!----------------------------------------------------------------------------->
\subsection bso_ssecpolygon_with_holes_validation Conditions for Valid
Polygons with Holes
<!----------------------------------------------------------------------------->
In our context, a polygon with holes must uphold the following conditions:
@ -174,7 +179,9 @@ that accept two `Polygon_2` objects as their input. We explain how
these functions should be used through several examples in the
following sections.
<!----------------------------------------------------------------------------->
\subsection Boolean_set_operations_2ASimpleExample A Simple Example
<!----------------------------------------------------------------------------->
\image html triangles.png
\image latex triangles.png
@ -193,7 +200,9 @@ which is located in the header file `print_utils.h`.
\cgalExample{Boolean_set_operations_2/do_intersect.cpp}
<!----------------------------------------------------------------------------->
\subsection bso_ssecpolygons_with_holes Polygons with Holes
<!----------------------------------------------------------------------------->
\cgalFigureBegin{figsimple,simple.png}
Operations on simple polygons. (a) The union of two polygons, resulting in a point set whose outer boundary is defined by a simple polygon and contains a polygonal hole in its interior. (b) The intersection (darkly shaded) of two polygons (lightly shaded), resulting in two disjoint polygons. (c) The complement (darkly shaded) of a simple polygon (lightly shaded).
@ -309,7 +318,9 @@ of several disconnected components, they all accept an output iterator
output polygons to its associated container.
</UL>
\subsection bso_sssecex_simple_bops Example - Joining and Intersecting Simple Polygons
<!----------------------------------------------------------------------------->
\subsection bso_sssecex_simple_bops Joining and Intersecting Simple Polygons
<!----------------------------------------------------------------------------->
The following example demonstrates the usage of the free functions
`join()` and `intersection()` for computing the union and the
@ -320,16 +331,21 @@ the header file `print_utils.h` under the examples folder.
\cgalExample{Boolean_set_operations_2/simple_join_intersect.cpp}
<!----------------------------------------------------------------------------->
\subsection bso_sssecpwh_bops Operations on Polygons with Holes
<!----------------------------------------------------------------------------->
We have demonstrated that free functions that perform boolean set operations on simple polygons may output polygons with holes. In addition to these functions, the Boolean set-operations package provides the following overridden free functions that accept
`General_polygon_with_holes_2` objects as their input -
`complement()`, `intersection()`, `join()`, `difference()`,
`symmetric_difference()` and `do_intersect()` The prototypes of
most functions is the same as of their simpler counterparts that operate
on simple polygons. The only exception is `complement(P, oi)`, which
outputs a range of polygons with holes that represents the complement
of the polygon with holes \f$ P\f$.
We have demonstrated that free functions that perform Boolean set
operations on simple polygons may output polygons with holes. In
addition to these functions, the Boolean set-operations package
provides the following overridden free functions that accept
`General_polygon_with_holes_2` objects as their input: `complement()`,
`intersection()`, `join()`, `difference()`, `symmetric_difference()`,
and `do_intersect()` The prototypes of most functions are the same as
of their simpler counterparts that operate on simple polygons. The
only exception is `complement(P, oi)`, which outputs a range of
polygons with holes that represents the complement of the polygon with
holes \f$ P\f$.
\image html symm_diff.png
\image latex symm_diff.png
@ -354,61 +370,71 @@ vertical walls).
\cgalExample{Boolean_set_operations_2/connect_polygon.cpp}
<!----------------------------------------------------------------------------->
\subsection bso_ssecmain_component Operating on Polygon Sets
<!----------------------------------------------------------------------------->
We argue that the result of a regularized operations on two polygons
(or polygons with holes) \f$ P\f$ and \f$ Q\f$ is typically a collection of
several disconnected polygons with holes. It is only natural to
represent such a collection in terms of a class, making it possible to
operate on the set resulting from computing, for example, \f$ P \setminus
Q\f$.
The result of a regularized operation on two polygons (or polygons
with holes) \f$ P\f$ and \f$ Q\f$ is typically a collection of several
disconnected polygons with holes. It is only natural to represent such
a collection in terms of a class, making it possible to operate on the
set resulting from computing, for example, \f$ P \setminus Q\f$.
A central component in the Boolean set-operations package is the
`Polygon_set_2<Kernel, Container, Dcel>` class-template. An instance of
this class represents a point set formed by the collection of several
disconnected polygons with holes. It employs the `Arrangement_2` class
to represent this point set in the plane as a planar arrangement; see
Chapter \ref chapterArrangement_on_surface_2 "2D Arrangements". The instantiated `Dcel`
type is used to represent the underlying internal arrangement. It must model
the concept `GeneralPolygonSetDcel`, and defaults to `Gps_default_dcel`.
You can override this default, with a different <span class="textsc">Dcel</span> class, typically
an extension of the default. Overriding the default is necessary only if
you intend to obtain the underlying internal arrangement and process it further.
`Polygon_set_2<Kernel, Container, Dcel>` class-template. An instance
of this class represents a point set formed by the collection of
several disconnected polygons with holes. It employs the
`Arrangement_2` class to represent this point set in the plane as a
planar arrangement; see Chapter \ref chapterArrangement_on_surface_2
"2D Arrangements". The instantiated `Dcel` type is used to represent
the underlying internal arrangement. It must model the concept
`GeneralPolygonSetDcel`, and defaults to `Gps_default_dcel`. You can
override this default, with a different <span
class="textsc">Dcel</span> class, typically an extension of the
default. Overriding the default is necessary only if you intend to
obtain the underlying internal arrangement and process it further.
An instance \f$ S\f$ of a `Polygon_set_2` class usually represents
the result of a sequence of operations that were applied on some input
polygons. The representation of \f$ S\f$ is unique, regardless of the particular
sequence of operations that were applied in order to arrive at it.
An instance \f$ S\f$ of a `Polygon_set_2` class usually represents the
result of a sequence of operations that were applied on some input
polygons. The representation of \f$ S\f$ is unique, regardless of the
particular sequence of operations that were applied in order to arrive
at it.
In addition, a polygon-set object can be constructed from a single
polygon object or from a polygon-with-holes object. Once constructed,
it is possible to insert new polygons (or polygons with holes)
into the set using the `insert()` method, as long as the inserted
polygons and the existing polygons in the set are disjoint.
The `Polygon_set_2` class also provides access functions for
accessing the polygons with holes it contains, and a few queries. The
most important query is `S.oriented_side(q)`, which determined
whether the query point \f$ q\f$ is contained in the interior of the set
\f$ S\f$, lies on the boundary of the set, or neither.
it is possible to insert new polygons (or polygons with holes) into
the set using the `insert()` method, as long as the inserted polygons
and the existing polygons in the set are disjoint. The
`Polygon_set_2` class also provides access functions for obtaining the
polygons with holes it contains, and a few queries. An important query
is `S.oriented_side(q)`, which determined whether the query point \f$
q\f$ is contained in the interior of the set \f$ S\f$, lies on the
boundary of the set, or neither.
The `General_polygon_set_2` class defines the predicate
`do_intersect()` and the methods `complement()`, `intersection()`,
`join()`, `difference()` and `symmetric_difference()` as member
functions. The operands to these functions may be simple polygons
(`Polygon_2` object), polygons with holes
(`General_polygon_with_holes_2` objects), or polygon sets
(`General_polygon_set_2` objects). Thus, each of the function
mentioned above is actually realized by a set overriding member
functions.
Similar to the `Polygon_set_2` class template, which applies to linear
polygons (or polygons with holes), the `General_polygon_set_2` class
applies to general polygons (or general polygons with holes). Each of
these class templates defines the predicate `do_intersect()` and the
methods `complement()`, `intersection()`, `join()`, `difference()` and
`symmetric_difference()` as member functions. The operands to these
functions may be simple polygons (`Polygon_2` or `General_polygon_2`
objects), polygons with holes (`Polygon_with_holes_2` or
`General_polygon_with_holes_2` objects), or polygon sets
(`cpolygon_set_2` or `General_polygon_set_2` objects). Each of the
aforementioned free functions is actually realized by a set overriding
member function.
Member functions of the `General_polygon_set_2` that perform
Boolean set-operations come in two flavors: for example, `S.join(P, Q)`
computes the union of \f$ P\f$ and \f$ Q\f$ and assigned the result to \f$ S\f$, while
member functions of the `Polygon_set_2`
(resp. `General_polygon_set_2`) that perform Boolean set-operations
come in two flavors: for example, `S.join(P, Q)` computes the union of
\f$ P\f$ and \f$ Q\f$ and assigned the result to \f$ S\f$, while
`S.join(P)` performs the operation \f$ S \longleftarrow S \cup P\f$.
Similarly, `S.complement(P)` sets \f$ S\f$ to be the complement of \f$ P\f$,
while `S.complement()` simply negates the set \f$ S\f$.
Similarly, `S.complement(P)` sets \f$ S\f$ to be the complement of \f$
P\f$, while `S.complement()` assigns \f$ S\f$ with its complement.
<!----------------------------------------------------------------------------->
\subsection bso_sssecsequence A Sequence of Set Operations
<!----------------------------------------------------------------------------->
The free functions reviewed in Section \ref bso_ssecpolygons_with_holes
serve as a wrapper for the polygon-set class, and are only provided for
@ -437,7 +463,9 @@ interior of this hole.
\cgalExample{Boolean_set_operations_2/sequence.cpp}
<!----------------------------------------------------------------------------->
\subsection bso_ssecinsert_ni Inserting Non Intersecting Polygons
<!----------------------------------------------------------------------------->
If you want to compute the union of a polygon \f$ P\f$ (\f$ P\f$ may be a simple
polygon or a polygon-with-holes object) with a general-polygon set
@ -470,7 +498,9 @@ range of polygons. When a range of polygons are inserted into a
polygon set \f$ S\f$, all the polygons in the range and the polygons represented
by \f$ S\f$ must be pairwise disjoint in their interiors.
<!----------------------------------------------------------------------------->
\subsection bso_ssecagg_ops Performing Aggregated Operations
<!----------------------------------------------------------------------------->
There are a few options to compute the union of a set of polygons
\f$ P_1, \ldots P_m\f$. You can do it incrementally as follows. At each step
@ -500,11 +530,11 @@ arrangement. Similarly, it is also possible to aggregately compute the
intersection \f$ \bigcap_{i=1}^{m}{P_i}\f$ of a set of input polygons.
Our package provides the free overloaded functions `join()` and
`intersection()` that aggregately compute the union and the intersection
of a range of input polygons. There is no restriction on the polygons in the
range - naturally, they may intersect each other.
The package provides the overloaded free function
\ref do_intersect "do_intersect(begin, end)" that determines whether the polygons in the
`intersection()` that aggregately compute the union and the
intersection of a range of input polygons. There is no restriction on
the polygons in the range; naturally, they may intersect each other.
The package provides the overloaded free function \ref do_intersect
"do_intersect(begin, end)" that determines whether the polygons in the
range defined by the two input iterators `[begin, end)` intersect.
The class `General_polygon_set_2` also provides equivalent member
@ -518,49 +548,90 @@ Polygon_set_2 S;
S.join (begin, end);
\endcode
<!----------------------------------------------------------------------------->
\subsection bso_ssectraits_sel Traits Selection
<!----------------------------------------------------------------------------->
When calling boolean set operations on `Polygon_2` or
`Polygon_with_holes_2` objects, a `General_polygon_set_2` is
instantiated internally. This polygon set is templated by a traits
class that is automatically deduced from the polygon type and that can
either be based on:
All the free function-templates that apply Boolean set operations
accept an optional traits argument; see next Section for more
information. If a traits class is not provided, a default one that can
handle the type of the curves that comprise the boundaries of the
input polygons is selected. You somwhow can influence this selection
using a template parameter as described below.
- `Arr_polyline_traits_2`: in that case, the polygon is first
decomposed into a set of \f$ x\f$-monotone polylines. This is the
default behavior.
The set of free function-templates that handle (linear) polygons
include overloaded versions that are parameterized by the template
parameter `UsePolylines`. For each such function template the
`UsePolylines` template parameter determmines whether to treat the
boundary of each input (linear) polygon as a cyclic sequence of single
(\f$x\f$-monotone) segments or as a cyclic sequence of
(\f$x\f$-monotone) polylines. By default, `UsePolylines` is set to
`CGAL::Tag_true`, which implies that the boundary of the each input
(linear) polygon is treated as a cyclic sequence of (\f$x\f$-monotone)
polylines. In most cases this behaviour is superior (that is, less
time-consuming) because the number of events handled as part of the
execution of the plane-sweep algorithm is reduced. In cases where the
boundaries of the input polygons frequently intersect, treating them
as polylines may become less efficient. In these cases substitute the
`UsePolylines` template parameter with `CGAL::Tag_false` to restore
the original behaviour (where the boundary of each input linear
polygon is treated as a cyclic sequence of single \f$x\f$-monotone
segments).
- `Arr_segment_traits_2`: in that case, every edge of the polygon is
considered as a single \f$ x\f$-monotone curve.
\cgalAdvancedBegin
The traits are selected via a template parameter `UsePolylineTraits`
which is `CGAL::Tag_true` by default: the polyline version is
generally significantly faster than the segment version as considering
\f$ x\f$-monotone polylines reduces the number of events of the
sweep-line algorithm.
A Boolean set operation can be apppplied on general polygons (or
general polygons with holes) directly using an instance of the class
template `General_polygon_set_2` or by using a free function, which
internally uses an instance of the class template
`General_polygon_set_2`. Similarly, a Boolean set operation can be
apppplied on linear polygons (or linear polygons with holes) directly
using an instance of the class template `Polygon_set_2` or by using a
free function, which internally uses an instance of the class template
`Polygon_set_2` by default. An instance of the `Polygon_set_2` class
template treats every edge of the polygon as a single
(\f$x\f$-monotone) segment, as it utilizes, in turn, the
`Arr_segment_traits_2` class template; see Section \ref
arr_ssectr_segs in the 2D Arrangements package.
Nevertheless, in some specific cases, users can find the segment
version to be faster: if a \f$ x\f$-monotone polyline from an input
polygon intersects many times another \f$ x\f$-monotone polyline from
another input polygon, then it becomes counter-productive to consider
polylines instead of segments. In that case, users can fallback to the
segment variant by using `CGAL::Tag_false` for the `UsePolylineTraits`
template parameter.
If the `UsePolylines` template parameter is substitited with
`CGAL::Tag_true` the following occurs:
<ol>
<li>Instead of using an instance of the `Polygon_set_2` class
template, as described above, an instance of the
`General_polygon_set_2` class template is used, which utilzes the
`Arr_polyline_traits_2` class template; see Section \ref
arr_ssectr_polylines in the 2D Arrangements package.
<li>Each input linear polygon (resp. linear polygon with holes) is
converted into a general polygon (resp. general polygon with holes)
bounded by \f$x\f$-monotone polylines. Then, the resulting generl
polygons, which are also bounded by \f$x\f$-monotone polylines, are
converted back to standard polygons.
</ol>
\cgalAdvancedEnd
<!--=========================================================================-->
\section bso_secbso_gen Boolean Set-Operations on General Polygons
<!--=========================================================================-->
\image html general_polygon.png
\image latex general_polygon.png
In previous sections only ordinary (linear) polygons were dealt with. Namely, closed
point sets bounded by piecewise linear curves. The Boolean
set-operations package allows a more general geometric mapping of the
polygon edges. The operations provided by the package operate on point
sets bounded by \f$ x\f$-monotone segments of general curves (e.g., conic
arcs and segments of polynomial functions). For example, the point set
depicted on the right is a general polygon bounded by two \f$ x\f$-monotone
circular arcs that correspond to the lower half and the upper half of
a circle, respectively.
In previous sections only ordinary (linear) polygons were dealt
with. Namely, closed point sets bounded by piecewise linear
curves. The Boolean set-operations package allows a more general
geometric mapping of the polygon edges. The operations provided by the
package operate on point sets bounded by \f$ x\f$-monotone segments of
general curves (e.g., conic arcs and segments of polynomial
functions). For example, the point set depicted on the right is a
general polygon bounded by two \f$ x\f$-monotone circular arcs that
correspond to the lower half and the upper half of a circle,
respectively.
Using the topological terminology, a general polygon can represent any
simply-connected point set whose boundary is a strictly simple curve.
@ -600,18 +671,20 @@ concepts.
The central class-template `General_polygon_set_2<Traits,Dcel>` is
used to represent point sets that are comprised of a finite number of
pairwise disjoint general polygons with holes, and provides various
Boolean set-operations on such sets. It is parameterized by a <I>traits</I>
class and a <span class="textsc">Dcel</span> class. The former defines the type of points used
to represent polygon vertices and the type of \f$ x\f$-monotone curves that
represent the polygon edges. The traits class also provides primitive
geometric operations that operate on objects of these types.
The <span class="textsc">Dcel</span> class is used to represent the underlying internal
`Arrangement_2` data structure. The instantiated `Dcel` type is
used to represent the underlying internal arrangement. It must model the
concept `GeneralPolygonSetDcel`, and defaults to `Gps_default_dcel`.
You can override this default, with a different <span class="textsc">Dcel</span> class, typically
an extension of the default. Overriding the default is necessary only if
you intend to obtain the underlying internal arrangement and process it further.
Boolean set-operations on such sets. It is parameterized by a
<I>traits</I> class and a <span class="textsc">Dcel</span> class. The
former defines the type of points used to represent polygon vertices
and the type of \f$ x\f$-monotone curves that represent the polygon
edges. The traits class also provides primitive geometric operations
that operate on objects of these types. The <span
class="textsc">Dcel</span> class is used to represent the underlying
internal `Arrangement_2` data structure. The instantiated `Dcel` type
is used to represent the underlying internal arrangement. It must
model the concept `GeneralPolygonSetDcel`, and defaults to
`Gps_default_dcel`. You can override this default, with a different
<span class="textsc">Dcel</span> class, typically an extension of the
default. Overriding the default is necessary only if you intend to
obtain the underlying internal arrangement and process it further.
An instantiated
`General_polygon_set_2` class defines the nested types
@ -620,7 +693,9 @@ An instantiated
the concepts `GeneralPolygon_2` and
`GeneralPolygonWithHoles_2` respectively.
<!----------------------------------------------------------------------------->
\subsection bso_ssectraits_concepts The Traits-Class Concepts
<!----------------------------------------------------------------------------->
The traits class used to instantiate the `General_polygon_set_2`
class template must model the concept `GeneralPolygonSetTraits_2`,
@ -630,7 +705,7 @@ and is tailored to handle a specific family of curves. The concept
The concept `ArrangementDirectionalXMonotoneTraits_2` refines the
concept `ArrangementXMonotoneTraits_2` (see
Section \ref arr_sssecinsert_x_mon in the 2D Arrangements chapter).
Section \ref arr_sssecinsert_x_mon in the 2D Arrangements package).
Thus, a model of this concept must define the type `X_monotone_curve_2`,
which represents an \f$ x\f$-monotone curve, and the type `Point_2`,
with represents a planar point. Such a point may be an endpoint of an
@ -667,7 +742,9 @@ 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.
<!----------------------------------------------------------------------------->
\subsection bso_sseccirc_seg Operating on Polygons with Circular Arcs
<!----------------------------------------------------------------------------->
Two traits classes are distributed with \cgal. The first one is named
`Gps_segment_traits_2`, and it is used to perform Boolean
@ -701,7 +778,9 @@ operator.
\cgalExample{Boolean_set_operations_2/circle_segment.cpp}
<!----------------------------------------------------------------------------->
\subsection bso_ssecgeneral_polygon_concept General Polygon Set Traits Adapter
<!----------------------------------------------------------------------------->
The concept `GeneralPolygon_2` and its generic model
`General_polygon_2<ArrDirectionalXMonotoneTraits>` facilitate the
@ -786,7 +865,9 @@ the `Gps_traits_2` adapter.
\cgalExample{Boolean_set_operations_2/bezier_traits_adapter.cpp}
\subsection bso_ssecaggregated_gen_ops Example - Aggregated Operations
<!----------------------------------------------------------------------------->
\subsection bso_ssecaggregated_gen_ops Aggregated Operations
<!----------------------------------------------------------------------------->
In Section \ref bso_ssecagg_ops we describe how aggregated union
and intersection operations can be applied to a collection of ordinary