namespace CGAL {
/*!

\mainpage User Manual
\anchor Chapter_2D_Regularized_Boolean_Set-Operations

\anchor chapter_Boolean_set_operations_2

\cgalAutoToc
\authors Efi Fogel, Ophir Setter, Ron Wein, Guy Zucker, Baruch Zukerman, and Dan Halperin

\section bso_secintro Introduction

\cgalFigureBegin{figteaser,teaser.png}
Examples of Boolean set-operations on general polygons.
\cgalFigureEnd

This package consists of the implementation of Boolean set-operations
on point sets bounded by weakly \f$ x\f$-monotone curves\cgalFootnote{A continuous planar curve \f$ C\f$ is <I>weakly \f$ x\f$-monotone</I> if every vertical line intersects it at most once, or if it is vertical. Hereafter we refer to weakly \f$ x\f$-monotone curves as \f$ x\f$-monotone curves.} in 2-dimensional Euclidean space. In particular,
it contains the implementation of <I>regularized</I> Boolean set-operations,
intersection predicates, and point containment predicates.
\cgalFigureRef{figteaser} shows simple examples of such operations.

Ordinary Boolean set-operations, which distinguish between the
interior and the boundary of a polygon, are not implemented within this
package. The Chapter \ref PkgNef2 supports these operations for (linear)
polygons.

In the rest of this chapter we use, unless otherwise stated, the
traditional notation to denote regularized operations; e.g., \f$ P \cap Q\f$
means the <I>regularized</I> intersection of \f$ P\f$ and \f$ Q\f$.

Our package supports the following Boolean set-operations on two point
sets \f$ P\f$ and \f$ Q\f$ that each is the union of one or more general polygons:
<DL>
<DT><B>Intersection</B><DD> computes the intersection \f$ R = P \cap Q\f$.
<DT><B>Join</B><DD> computes the union \f$ R = P \cup Q\f$.
<DT><B>Difference</B><DD> computes the difference \f$ R = P \setminus Q\f$.
<DT><B>Symmetric Difference</B><DD> computes the symmetric
difference \f$ P = P \oplus Q = (P \setminus Q) \cup (Q \setminus P)\f$.
<DT><B>Complement</B><DD> computes the complement \f$R = \overline{P}\f$.
<DT><B>Intersection predicate</B><DD> tests whether the two sets \f$ P\f$ and \f$ Q\f$
overlap, distinguishing three possible scenarios: (i) the two sets
intersect on their interior (that is, their regularized intersection
is not empty \f$ P \cap Q \neq \emptyset\f$); (ii) the boundaries of two
sets intersect but their interiors are disjoint; namely they have a
finite number of common points or even share a boundary curve (still
in this case \f$ P \cap Q = \emptyset\f$; and (iii) the two sets are
disjoint.
</DL>
In general, the set \f$ R\f$, resulting from a regularized Boolean
set-operation, is considered as being a closed point-set; see definition of regularized boolean set operations below.

In the rest of this chapter we review the Boolean set-operations package
in more depth. In Section \ref bso_secbso_lin we focus on Boolean
set-operations on linear polygons, introducing the notion of polygons with
holes and of a general polygon set. Section \ref bso_secbso_gen
introduces general polygons.
We first discuss polygons whose edges are either line segments or circular
arcs and then explain how to construct and use general polygons whose edges
can be arbitrary weakly \f$ x\f$-monotone curves.

\section bso_secbso_def Terms and Definitions

\cgalFigureBegin{simpleDefsExamples,simpleDefsExamples.png}
Examples of polygons. (a) A simple polygon. (b) A relatively simple polygon (c) A polygon that is neither simple nor relatively simple.
\cgalFigureEnd


<UL>

<LI>The counterclockwise cyclic sequence of alternating polygon edges and
polygon vertices is referred to as the polygon <B>(outer) boundary</B>.

<LI>A polygon whose curves are pairwise disjoint in their interior, and whose vertices' degree equals two is defined as a <B>Simple polygon</B>. Such a polygon has a well-defined interior and exterior and is topologically equivalent to a disk. Note that while traversing the edges of the relatively simple polygon illustrated above (B), no curve is crossed over.

<LI>A <B>Relatively simple</B> polygon allows vertices with a degree\f$> 2\f$, but all of its edges are disjoint in their interior. Furthermore, it must be an orientable polygon. Namely when it is inserted into an arrangement and its outer boundary is traversed, the same face is adjacent to all of the halfedges (no crossing over any curve during the traversal).
Note that while polygon C has the same curves as polygon B, traversal of the curves leads to crossing over a previously traversed curve, and is therefore neither simple nor relatively simple.

<LI>A polygon in our context must be relatively simple and its outer boundary vertices must be ordered in a counterclockwise direction around the interior of the polygon.
We extend the notion of a polygon to a <B>point set</B> in \f$ \mathbb{R}^2\f$
that has a topology of a polygon and its boundary edges must map to
\f$ x\f$-monotone curves, and refer to it as a <B>general polygon</B>. We
sometimes use the term <I>polygon</I> instead of general polygon for
simplicity hereafter.

<LI>A <B>polygon with holes</B> represents a point set that may
be bounded or unbounded. In case of a bounded set, its <I>outer
boundary</I> is represented as a <I>relatively simple </I> (but not necessarily simple) polygon, whose vertices are oriented in a <I>counterclockwise </I>
order around the interior of the set. In addition, the set may contain
<I>holes</I>, where each hole is represented as a <I>simple</I>
polygon, whose vertices are oriented in a <I>clockwise</I> order around the
interior of the hole. Note that an unbounded polygon without holes
spans the entire plane. Vertices of holes may coincide with vertices
of the boundary.

<LI>A <B>regularized Boolean set-operation</B> \f$ \mbox{op}^*\f$ can be obtained by
first taking the interior of the resultant point set of an <I>ordinary</I>
Boolean set-operation \f$ (P\ \mbox{op}\ Q)\f$ and then by taking the
closure \cgalCite{cgal:h-sm-04}. That is,
\f$ P\ \mbox{op}^*\ Q = \mbox{closure}(\mbox{interior} (P\ \mbox{op}\ Q))\f$.
Regularized Boolean set-operations appear in Constructive Solid
Geometry (CSG), because regular sets are closed under regularized
Boolean set-operations, and because regularization eliminates lower
dimensional features, namely isolated vertices and antennas, thus
simplifying and restricting the representation to physically meaningful
solids. Our package provides regularized operations on polygons and
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:

<OL>
<LI><I>Closed Boundary</I> - the polygon's outer boundary must be a connected sequence of curves, that start and end at the same vertex.
<LI><I>Simplicity</I> - the polygon must be simple.
<LI><I>Orientation</I> - the polygon's outer boundary must be <I>counterclockwise oriented</I>.
</OL>

\subsection bso_ssecpolygon_with_holes_validation Conditions for Valid Polygons with Holes

In our context, a polygon with holes must uphold the following conditions:

<OL>
<LI><I>Closed Boundary</I> - both the outer boundary and the holes must be closed polygons as defined above.
<LI><I>Simplicity</I> - the outer boundary must be a <I></I><B><I>relatively</I></B><I> simple</I> polygon (as defined above). Every hole must be a <I>simple</I> polygon.
<LI><I>Orientation</I> - The polygon with holes must have an outer boundary with <I>counter clockwise orientation</I>. Every hole's outer boundary should have <I>clockwise orientation</I>.
<LI><I>The holes and the outer boundary must be pairwise disjoint,except maybe on vertices</I>.
<UL>
<LI><I>All holes are contained in the outer boundary</I> - holes must be contained inside the outer boundary and must be disjoint from it (except on vertices).
<LI><I>Pairwise disjoint holes (on interior)</I> - the polygon's holes must be <I>pairwise disjoint</I>, except for intersection on a joint vertex/vertices.

</UL>
</OL>

\section bso_secbso_lin Boolean Set-Operations on Linear Polygons

The basic library of \cgal includes the `Polygon_2<Kernel,Container>`
class-template that represents a linear polygon in the plane. The
polygon is represented by its vertices stored in a container of
objects of type `Kernel::Point_2`. The polygon edges are line
segments (`Kernel::Segment_2` objects) between adjacent points in
the container. By default, the `Container` is a vector of
`Kernel::Point_2` objects.

The following function demonstrates how to use the basic access
functions of the `Polygon_2` class. It accepts a polygon \f$ P\f$ and
prints it in a readable format:
\code{.cpp}
template<class Kernel, class Container>
void print_polygon (const CGAL::Polygon_2<Kernel, Container>& P)
{
  typename CGAL::Polygon_2<Kernel, Container>::Vertex_const_iterator vit;

  std::cout << "[ " << P.size() << " vertices:";
  for (vit = P.vertices_begin(); vit != P.vertices_end(); ++vit)
    std::cout << " (" << *vit << ')';
  std::cout << " ]" << std::endl;
}
\endcode

In this section we use the term <I>polygon</I> to indicate a
`Polygon_2` instance, namely, a polygon having linear
edges. General polygons are only discussed in
Section \ref bso_secbso_gen.

The basic components of our package are the free (global) functions
`complement()` that accepts a single `Polygon_2` object, and
`intersection()`, `join()`,\cgalFootnote{The function that computes the union of two polygons is called \cgalFootnoteCode{join()}, since the word \cgalFootnoteCode{union} is reserved in \cpp.} `difference()`,
`symmetric_difference()` and the predicate `do_intersect()`
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

Testing whether two polygons intersect results with a Boolean value,
and does not require any additional data beyond the provision of the
two input polygons. The example listed below tests whether the two
triangles depicted on the right intersect. It uses, as do the other
example programs in this chapter, the auxiliary header file
`bso_rational_nt.h`, which defines the type `Number_type` as
\gmp's rational number-type (`Gmpq`), or as the
number type `Quotient<MP_Float>` that is included in the support
library of \cgal, based on whether the \gmp library is installed
or not. It also uses the function `print_polygon.h` listed above,
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).
\cgalFigureEnd

In many cases a binary operation that operates on two simple
polygons that have no holes may result in a set of polygons that
contain holes in their interior (see \cgalFigureRef{figsimple} (a)),
or a set of disjoint polygons (see \cgalFigureRef{figsimple} (b); a similar
set may result from the union, or the symmetric difference, of two disjoint
polygons). Moreover, the complement of a simple polygon is an unbounded set
that contains a hole; see \cgalFigureRef{figsimple} (c).

Regular sets are closed under regularized Boolean set-operations.
These operations accept as input, and may result as output, polygons
with holes.
A <I>polygon with holes</I> represents a point set that may
be bounded or unbounded. In case of a bounded set, its <I>outer
boundary</I> is represented as a relatively simple (but not necessarily simple) polygon, whose vertices are oriented in a counterclockwise
order around the interior of the set. In addition, the set may contain
<I>holes</I>, where each hole is represented as a simple
polygon, whose vertices are oriented in a clockwise order around the
interior of the hole. Note that an unbounded polygon without holes
spans the entire plane. Vertices of holes may coincide with vertices
of the boundary; see below for an example.

A point set represented by a polygon with holes is considered to be
closed. Therefore, the boundaries of the holes are parts of the set
(and not part of the holes).
The exact definition of the obtained polygon with holes as a result of
a Boolean set-operation or a sequence of such operations is closely
related to the definition of regularized Boolean set-operations, being
the closure of the interior of the corresponding ordinary operation as
explained next.

\image html unique.png
\image latex unique.png

Consider, for example, the regular set depicted on the right, which is
the result of the union of three small triangles translated
appropriately. Alternatively, the same set can be reached by taking
the difference between a large triangle and a small
upside-down triangle. In general, there are many ways to arrive at
a particular point set. However, the set of polygons with holes
obtained through the application of any sequence of operations is
unique. The set depicted on the right is represented as a single
polygon having a triangular outer boundary with a single triangular
hole in its interior - and not as three triangles that have no holes
at all. As a general rule, if two point sets are connected, then they
belong to the same polygon with holes.

The class template `Polygon_with_holes_2<Kernel,Container>`
represents polygons with holes as described above, where the outer
boundary and the hole boundaries are realized as
`Polygon_2<Kernel,Container>` objects. Given an instance \f$ P\f$ of
the `Polygon_with_holes_2` class, you can use the predicate
`is_unbounded()` to check whether \f$ P\f$ is a unbounded set. If it is
bounded, you can obtain the counterclockwise-oriented polygon that
represents its outer boundary through the member function
`outer_boundary()`. You can also traverse the holes of \f$ P\f$ through
`holes_begin()` and `holes_end()`. The two functions return
iterators of the nested type
`Polygon_with_holes_2::Hole_const_iterator` that
defines the valid range of \f$ P\f$'s holes. The value type of this
iterator is `Polygon_2`.

The following function demonstrates how to traverse a polygon with holes.
It accepts a `Polygon_with_holes_2` object and uses the auxiliary
function `print_polygon()` to prints all its components in a readable
format:
\code{.cpp}
template<class Kernel, class Container>
void print_polygon_with_holes(const CGAL::Polygon_with_holes_2<Kernel, Container> & pwh)
{
  if (! pwh.is_unbounded()) {
    std::cout << "{ Outer boundary = ";
    print_polygon (pwh.outer_boundary());
  } else
    std::cout << "{ Unbounded polygon." << std::endl;

  typename CGAL::Polygon_with_holes_2<Kernel,Container>::Hole_const_iterator hit;
  unsigned int k = 1;

  std::cout << " " << pwh.number_of_holes() << " holes:" << std::endl;
  for (hit = pwh.holes_begin(); hit != pwh.holes_end(); ++hit, ++k) {
    std::cout << " Hole #" << k << " = ";
    print_polygon (*hit);
  }
  std::cout << " }" << std::endl;
}
\endcode

The simple versions of the free functions mentioned therefore
accept two `Polygon_2` object \f$ P\f$ and \f$ Q\f$ as their input, while
their output is given using polygon with holes instances:
<UL>
<LI>The complement of a simple polygon \f$ P\f$ is always an unbounded set
with a single polygonal hole. The function `complement(P)` therefore
returns a polygon-with-holes object that represents the complement of \f$ P\f$.
<LI>The union of two polygons \f$ P\f$ and \f$ Q\f$ is always a single connected
set, unless of course the two input polygons are completely disjoint. In
the latter case \f$ P \cup Q\f$ trivially consists of the two input polygons.
The free function `join(P, Q, R)` therefore returns a Boolean value
indicating whether \f$ P \cap Q \neq \emptyset\f$. If the two polygons are not
disjoint, it assigns the polygon with holes object \f$ R\f$ (which it
accepts by reference) with the union of the regularized union operation
\f$ P \cup Q\f$.
<LI>The other three functions, namely `intersection(P, Q, oi)`,
`difference(P, Q, oi)` and `symmetric_difference(P, Q, oi)`, all
have a similar interface. As the result of these operation may consist
of several disconnected components, they all accept an output iterator
`oi`, whose value type is `Polygon_with_holes_2`, and adds the
output polygons to its associated container.
</UL>

\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
intersection of the two simple polygons depicted in
\cgalFigureRef{figsimple} (b). The example uses the auxiliary function
`print_polygon_with_holes()` listed above, which is located in
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 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

The following example demonstrates how to compute the symmetric
difference between two sets that contain holes. Each set is a
rectangle that contains a rectangular hole in its interior, such that
the symmetric difference between the two sets is a single polygon that
contains of five holes:

\cgalExample{Boolean_set_operations_2/symmetric_difference.cpp}

In some cases it is convenient to connect the outer boundary of a
polygon with holes with the holes inside it. The
function `connect_holes()` accepts a polygon with
holes, and connects the topmost vertex in each hole with the polygon
feature located directly above it (a vertex or an edge of the outer
boundary, or of another hole). It produces an output sequence of
points that match the traversal of all vertices in the connected
polygon (note that there are additional vertices, induced by the
vertical walls).

\cgalExample{Boolean_set_operations_2/connect_polygon.cpp}

\subsection bso_ssecmain_component Operating on Polygon Sets

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 \dcel 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.

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 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.

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 `Polygon_set_2`
(respectively `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()` 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
convenience. A typical such function constructs a pair of
`General_polygon_set_2` objects, invokes the appropriate method to
apply the desired Boolean operation, and transforms the resulting
polygon set to the required output format. Thus, when several
operations are performed in a sequence, it is much more efficient to
use the member functions of the `General_polygon_set_2` type
directly, as the extraction of the polygons from the internal
representation for some operation, and the reconstruction of the
internal representation for the succeeding operation could be time
consuming.

\image html sequence.png
\image latex sequence.png

The next example performs a sequence of three Boolean set-operations.
First, it computes the union of two simple polygons depicted in
\cgalFigureRef{figsimple} (a). It then computes the complement of the result
of the union operation. Finally, it computes the intersection of the result
of the complement operation with a rectangle, confining the final result to
the area of the rectangle. The resulting set \f$ S\f$ is comprised of two
components: a polygon with a hole, and a simple polygon contained in the
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
\f$ R\f$, and store the result in \f$ R\f$, you can construct a polygon set
\f$ S(P)\f$, and apply the <I>union</I> operation as follows:
\code{.cpp}
General_polygon_2 S (P);
R.join (S);
\endcode

As a matter of fact, you can apply the union operation directly:
\code{.cpp}
R.join (P);
\endcode

However, if you know that the polygon does not intersect any one of the
polygons represented by \f$ R\f$, you can use the more efficient method
`insert()`:
\code{.cpp}
R.insert (P);
\endcode

As `insert()` assumes that \f$ P \cap R = \emptyset\f$, it does not try to
compute intersections between the boundaries of \f$ P\f$ and of \f$ R\f$. This
fact significantly speeds up the insertion process in comparison with the
insertion of a non-disjoint polygon that intersects \f$ R\f$.

The `insert()` function is also overloaded, so it can also accept a
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
compute the union of \f$ S_{k-1} = \bigcup_{i=1}^{k-1}{P_i}\f$
with \f$ P_{k}\f$ and obtain \f$ S_k\f$. Namely, if the polygon set is given
as a pair of iterator `[begin, end)`, the following loop computes
their union in \f$ S\f$.
\code{.cpp}
InputIterator iter = begin;
Polygon_set_2 S (*iter);

while (++iter != end) {
  S.join (*iter);
  ++iter;
}
\endcode
A second option is to use a divide-and-conquer approach. You bisect
the set of polygons into two sets. Compute the union of each set
recursively and obtain the partial results in \f$ S_1\f$ and \f$ S_2\f$, and
finally, you compute the union \f$ S_1 \cup S_2\f$. However, the union
operation can be done more efficiently for sparse polygons, having
a relatively small number of intersections, using a third option that
simultaneously computes the union of all polygons. This is done by
constructing a planar arrangement of all input polygons, utilizing the
sweep-line algorithm, then extracting the result from the
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
range defined by the two input iterators `[begin, end)` intersect.

The class `General_polygon_set_2` also provides equivalent member
functions that aggregately operate on a range of input polygons or
polygons with holes. When such a member function is called, the general
polygons represented by the current object are considered operands as
well. Thus, you can easily compute the union of our polygon range as
follows:
\code{.cpp}
Polygon_set_2 S;
S.join (begin, end);
\endcode

\subsection bso_ssectraits_sel Traits Selection

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 somehow can influence this selection
using a template parameter as described below.

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 behavior 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 behavior (where the boundary of each input linear
polygon is treated as a cyclic sequence of single \f$x\f$-monotone
segments).

\cgalAdvancedBegin

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.

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 utilizes the
`Arr_polyline_traits_2` class template; see Section \ref
arr_ssectr_polylines in the 2D Arrangements package.

<li>Each input linear polygon (respectively linear polygon with holes) is
converted into a general polygon (respectively general polygon with holes)
bounded by \f$x\f$-monotone polylines. Then, the resulting general
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.

Using the topological terminology, a general polygon can represent any
simply-connected point set whose boundary is a strictly simple curve.
Such a polygon is a model of the `GeneralPolygon_2` concept. A model
of this concept must fulfill the following requirements:
<UL>
<LI>A general polygon is constructible from a range of pairwise
interior disjoint \f$ x\f$-monotone curves \f$ c_1, \ldots, c_n\f$. The target
point of the \f$ k\f$th curve \f$ c_k\f$ and the source point of the next curve
in the range (in a cyclic order) must coincide, such that this point
defines the \f$ k\f$th polygon vertex.
<LI>It is possible to traverse the \f$ x\f$-monotone curves that form the
edges of a general polygon.
</UL>

\image html general_polygon_with_holes.png
\image latex general_polygon_with_holes.png

The concept `GeneralPolygonWithHoles_2` is defined in an analogous
way to the definition of linear polygons with holes. A model of this
concept represent a bounded or an unbounded set that may not be simply
connected, and must provide the following operations:

<UL>
<LI>Construction for a general polygon that represent the outer boundary
and a range of general polygons that represent the holes.
<LI>Accessing the general polygons that represents the outer boundary
(in case of a bounded set).
<LI>Traversing the holes.
</UL>
In Section \ref bso_secbso_lin we introduce the classes
`Polygon_2` and `Polygon_with_holes_2` that model the concepts
`GeneralPolygon_2` and `GeneralPolygonWithHoles_2`
respectively. In this section we introduce other models of these two
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 \dcel 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 \dcel 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 \dcel 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
`General_polygon_set_2<Traits,Dcel>::%Polygon_2` and
`General_polygon_set_2<Traits,Dcel>::%Polygon_with_holes_2`, which model
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`,
and is tailored to handle a specific family of curves. The concept
`GeneralPolygonSetTraits_2` refines the concept
`AosDirectionalXMonotoneTraits_2` specified next.

The concept `AosDirectionalXMonotoneTraits_2` refines the
concept `AosXMonotoneTraits_2` (see
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
\f$ x\f$-monotone curve or an intersection point between two curves.
It must also provide various geometric predicates and operations
on these types listed by the base concept, such as determining whether
a point lies above or below an \f$ x\f$-monotone curve, computing the
intersections between two curves, etc. Note that the base concept does
not assume that \f$ x\f$-monotone curves are directed: an \f$ x\f$-monotone
curve is not required to have a designated <I>source</I> and <I>target</I>, it is only required to determine the left (lexicographically
smaller) and the right (lexicographically larger) endpoints of a given
curve.

The `AosDirectionalXMonotoneTraits_2` concept treats its
\f$ x\f$-monotone curves as directed objects. It thus requires two additional
operations on \f$ x\f$-monotone curves:
<UL>
<LI>Given an \f$ x\f$-monotone curve, compare its source and target points
lexicographically.
<LI>Given an \f$ x\f$-monotone curve, construct its opposite curve (namely,
swap its source and target points).
</UL>

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 <I>not</I> 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.

\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
set-operations on ordinary polygons and polygons with holes. In fact,
the class `Polygon_set_2` introduced in
Section \ref bso_ssecmain_component is a specialization of
`General_polygon_set_2<Gps_segment_traits_2>`. This class defined
its polygon and polygon with holes types, such that the usage of this
traits class is encapsulated in the polygon-set class.

The other predefined traits class is named
`Gps_circle_segment_traits_2<Kernel>` and is parameterized by a
geometric \cgal kernel. By instantiating the `General_polygon_set_2`
with this traits class, we obtain the representation of a polygon whose
boundary may be comprised of line segments and circular arcs.
The circle-segment traits class provides predicates and constructions
on non-linear objects; yet, it uses only rational arithmetic and is
very efficient as a consequence.

\image html circles_rects.png
\image latex circles_rects.png

The following example uses the `Gps_circle_segment_traits_2` class
to compute the union of four rectangles and four circles. Each circle
is represented as a general polygon having two \f$ x\f$-monotone circular arcs.
The union is computed incrementally, resulting with a single polygon with
a single hole, as depicted on the right. Note that as the four circles
are disjoint, their union is computed with the `insert` method,
while the union with the rectangles is computed with the `join`
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
production of general-polygon set traits classes. A model of the concept
`GeneralPolygon_2` represents a simple point-set in the plane bounded
by \f$ x\f$-monotone curves. As opposed to the plain `Traits::Polygon_2` type
defined by any traits class, it must define the type
`X_monotone_curve_2`, which represents an \f$ x\f$-monotone curve of the
point-set boundary. It must provide a constructor from a range of such
curves, and a pair of methods, namely `curves_begin()` and
`curves_end()`, that can be used to iterate over the point-set boundary
curves.

The class-template `General_polygon_2<ArrDirectionalXMonotoneTraits>`
models the concept `GeneralPolygon_2`. Its sole template parameter
must be instantiated with a model of the concept
`AosDirectionalXMonotoneTraits_2` from which it obtains the
`X_monotone_curve_2` type. It uses the geometric operations
on this type provided by such a model to maintain a container of
directed curves of type `X_monotone_curve_2`, which represents a
boundary of the general polygon.

The class-template
`Gps_traits_2<ArrDirectionalXMonotoneTraits,GeneralPolygon>`
models the concept `GeneralPolygonSetTraits_2`, and can be used to
instantiate the class template `General_polygon_set_2`.
It serves as an adapter for a geometric traits class, which models the
concept `AosDirectionalXMonotoneTraits_2`.
It can be used for performing set-operations on general polygons.
The implementation of the adapter is rather simple, as it is derived
from the instantiated template-parameter `ArrXMonotoneTraits_2`
inheriting its necessary types and methods. It further exploits
the methods provided by the instantiated parameter
`GeneralPolygon`, which is a model of the concept
`GeneralPolygon_2`. By default, the `GeneralPolygon` parameter
is defined as
`General_polygon_2<AosDirectionalXMonotoneTraits_2>`.

The code excerpt listed below defines a general-polygon set type that
can be used to perform Boolean set-operations on point sets bounded by
the \f$ x\f$-monotone curve type defined by the arrangement-traits class
`Arr_traits_2`, which is some representative model of the concept
`AosDirectionalXMonotoneTraits_2`.

\code{.cpp}
#include <CGAL/General_polygon_2.h>
#include <CGAL/Gps_traits_2.h>

typedef CGAL::General_polygon_2<Arr_traits_2> General_polygon_2;
typedef CGAL::Gps_traits_2<Arr_traits_2, General_polygon_2> Traits_2;
typedef CGAL::General_polygon_set_2<Traits_2> General_polygon_set_2;
\endcode

\image html tnr_m_g.png
\image latex tnr_m_g.png

Instantiating the arrangement-traits `Arr_traits_2` above with the
traits class that handle B&eacute;zier curves `Arr_Bezier_curve_traits_2`,
results with the definition of a general-polygon set type that can be
used to perform Boolean set-operations on point sets bounded by B&eacute;zier
curves.

The next example computes the intersection of two general polygons
bounded by B&eacute;zier curves read from two input files respectively. The
default input files our example uses (`char_g.dat` and
`char_m.dat`) define two general polygons shaped in the form of
the characters <B>g</B> and <B>m</B> in the Times New Roman font
respectively. Their intersection comprises nine simple polygons, as
depicted to the right.

Recall that every B&eacute;zier curve is defined by a sequence of control
points that form chains (see Section \ref arr_sssectr_bez. The last
control point of every curve must be identical to the first control
point of its successor. The function `read_Bezier_polygon()`
included in the example reads the curves from an input file until they
form a closed chain, which is assumed to be the outer boundary of the
polygon. If more curves are available, its starts constructing
polygons that correspond to holes in the area bounded by the outer
boundary. Note that this function is also responsible for subdividing
the input B&eacute;zier curves into \f$ x\f$-monotone subcurves, as required by
the `Gps_traits_2` adapter.

\cgalExample{Boolean_set_operations_2/bezier_traits_adapter.cpp}

\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
polygons or polygons with holes. Naturally, the aggregated operations
can be applied also to collections of general polygons. As was the
case with ordinary polygons, using aggregated operations is
recommended when the number of intersections of the input polygons
is of the same order of magnitude as the complexity of the result. If
this is not the case, computing the result incrementally may prove
faster.

\image html disks.png
\image latex disks.png

The next example computes the union of eight unit discs whose centers are
placed a unit distance from the origin, as depicted to the right. The example
also allows users to provide a different number of discs through the command
line.

\cgalExample{Boolean_set_operations_2/set_union.cpp}

*/
} /* namespace CGAL */
