namespace CGAL {
/*!

\mainpage User Manual
\anchor Chapter_2D_Arrangements
\anchor chapterArrangement_on_surface_2
\cgalAutoToc

\authors Ron Wein, Eric Berberich, Efi Fogel, Dan Halperin,
Michael Hemmer, Oren Salzman, and Baruch Zukerman

<!-- ======================================================================= -->
\section aos_sec-intro Introduction
<!-- ======================================================================= -->

Geometric arrangements, or arrangements for short, are subdivisions of
some space induced by geometric objects.
\cgalFigureRef{aos_fig-simple_arr} shows an arrangement of two curves
\f$c_1\f$ and \f$c_2\f$ in the plane. It has three faces&mdash;two
bounded faces \f$f_1\f$ and \f$f_2\f$ (filled with diagonal-stripe
patterns) and an unbounded face. The arrangement has seven
vertices&mdash;four represent the endpoints of \f$c_1\f$ and \f$c_2\f$
(drawn as small discs), and three represent the intersection points of
the two curves (drawn as small rings). The arrangement also has eight
edges, each of which is a maximal portion of one curve not
intersecting the other.

\cgalFigureBegin{aos_fig-simple_arr,simple_arr.png}
\cgalFigureEnd

Arrangements are not restricted to curves in the plane. There are
useful arrangements in three and higher dimensions (these are not so
easy to visualize) and they can be induced by geometric objects of any
type, such as spheres, simplices, polytopes, or B&eacute;zier
surfaces. This package provides a data structure that represents a
two-dimensional arrangement of curves embedded in an orientable
parametric surface in three dimensional space, such as a plane, a
cylinder, a sphere, a torus, or a surface homeomorphic to them. This
package also provides operations that construct and manipulate such
arrangements.  Arrangements are ubiquitous in the
computational-geometry literature and have many applications; see,
e.g., \cgalCite{as-aa-00}, \cgalCite{cgal:bfhks-apsca-10},
\cgalCite{cgal:bfhmw-apsgf-10}, and \cgalCite{cgal:h-a-04}.

<!-- ----------------------------------------------------------------------- -->
\subsection aos_ssec-intro-sep Separation of Topology and Geometry
<!-- ----------------------------------------------------------------------- -->

The use of the generic programming paradigm enables a convenient
separation of the topology and the geometry of data
structures.\cgalFootnote{In this context, we sometimes say
<em>combinatorics</em> instead of topology, and say <em>algebra</em> or
<em>numerics</em> instead of geometry. We always mean the same
thing---the separation of the abstract, graph-like structure (the
topology) from the actual embedding in the plane (the geometry).}
This is a key aspect in the design of geometric software, and is put
into practice, for example, in the design of \cgal polyhedra, \cgal
triangulations, and our \cgal arrangements. This separation allows the
convenient abstraction of algorithms and data structures in
combinatorial and topological terms, regardless of the specific
geometry of the objects at hand. This abstraction is realized through
class and function templates that represent specific data structures
and algorithmic frameworks, respectively. Consider the class template

\code{.cpp}
template <typename GeometryTraits, typename Dcel>
class Arrangement_2 { ... };
\endcode

An instance of this template represents an arrangement embedded in the
plane. When the template is instantiated, the `GeometryTraits`
parameter must be substituted by a type that defines a set of
geometric-object types, such as point and curve, and a set of
operations on objects of these types (see Section \ref
aos_sec-geom_traits); the `Dcel` parameter must be substituted by a
type that represents a doubly-connected edge list (\dcel) data
structure. It defines types of topological objects, such as vertices,
edges, and faces, and the operations required to maintain the
incidence relations among objects of these types (see Section \ref
aos_ssec-basic-dcel).

The class template `Arrangement_2` derives from the following class
template:

\code{.cpp}
template <typename GeometryTraits, typename TopologyTraits>
class Arrangement_on_surface_2 { ... };
\endcode

An instance of this template represents a two-dimensional arrangement
embedded in a surface in three dimensional space. When the template is
instantiated, the `GeometryTraits` parameter must be substituted as
described above; the `TopologyTraits` parameter must be substituted
by a type that deals with the topology of the surface (see Section
\ref aos_sec-topol_traits). In particular, it maintains a
representation of the arrangement graph embedded in the surface using
a doubly-connected edge list (\dcel) data-structure suitable for
the particular topology.

Several member functions and nested types defined in the
`Arrangement_2` derived class-template inherit their definitions from
the base class-template `Arrangement_on_surface_2`; their semantics is
equivalent in both class templates. The names of these member
functions and nested types typically appear in the manual without any
scope, as each of these class templates can serve as their scope. (As
a matter of fact, the package provides additional class templates that
represent two-dimensional arrangements, such as the
`Arrangement_with_history_2` class template, which derives from the
class template `Arrangement_2`; these additional class templates also
contain inherited definitions of the aforementioned member functions
and nested types.)

An immediate advantage of the separation of the topology and the
geometry of data structures is that users with limited expertise in
computational geometry can employ the data structure with their own
special type of objects. They must, however, supply the relevant
traits class, which mainly involves algebraic computations. A traits
class also encapsulates the number types used to represent coordinates
of geometric objects and to carry out algebraic operations on them. It
encapsulates the type of coordinate system used (e.g., %Cartesian and
homogeneous), and the geometric or algebraic computation methods
themselves. The precise minimal sets of requirements the actual traits
classes must conform to are organized as a hierarchy of concepts; see
Section \ref aos_sec-geom_traits.

<!-- ----------------------------------------------------------------------- -->
\subsection aos_ssec-intro-well_behaved Well-Behaved Curves
<!-- ----------------------------------------------------------------------- -->

What constitutes valid curves that can be handled by the \ref
PkgArrangementOnSurface2 package is discussed in detail in Section
\ref aos_sec-geom_traits, where the models of the traits classes are
described. However, when we cite combinatorial complexity bounds or
bounds on the resources (i.e., running time and storage space)
required by algorithms, we often postulate stricter assumptions on the
input curves. The prevalent term in use is that the curves are
<em>well behaved</em>, which may have different interpretations in
different settings. If we are concerned with combinatorial complexity
bounds for curves embedded in a two-dimensional surface, then the
standard assumptions are that (i) each curve is non-self-intersecting
(a so-called Jordan arc) and (ii) every pair of curves intersects in
at most some constant number of points. For algorithmic purposes we
need to require more since we assume that any operation on a small
constant number of curves takes unit time. In this sense arcs of
algebraic curves of degree bounded by a constant (namely the zero set
of bivariate polynomials of constant maximum total degree) are well
behaved. Naturally, what are typically considered well-behaved
surfaces in \f$\mathbb{R}^3\f$ is even more complicated to state.

Remarks
<ol>

<li> From the complexity-bound perspective, most of the arrangements
  that we can deal with can be regarded as defined by well-behaved
  curves. Even though the package allows for self-intersecting curves,
  for most types each curve can be decomposed into a constant number
  of well-behaved curves, thus having no effect on the asymptotic
  bounds that we state.
</li>

<li> One type of curves that we deal with is special in this sense:
  <em>polylines</em>, namely concatenations of an unlimited number of
  line segments; see Section \ref arr_sssectr_polylines. A polyline is
  not well behaved, as it cannot be decomposed into a constant number
  of constant-descriptive complexity subcurves. Informative bounds for
  arrangements of polylines are expressed by other parameters in
  addition to the number of polylines, for example, the total number
  of segments in all the polylines together. The same holds for the
  more general type <em>polycurve</em>, which are piecewise curves
  that are not necessarily linear; see Section \ref
  arr_sssectr_polycurves.
</li>

</ol>

<!-- ----------------------------------------------------------------------- -->
\subsection aos_ssec-intro-outline Outline
<!-- ----------------------------------------------------------------------- -->

In Section \ref aos_sec-basic we provide the minimum material you need
to know in order to use \cgal 2D arrangements in the plane. In Section
\ref aos_sec-curved_surfaces we provide additional material you need
to know in order use \cgal 2D arrangements embedded in curved
surfaces.  Most of the succeeding material is oblivious to the type of
the embedding surface. In Section \ref arr_secqueries we show how
queries on an arrangement can be issued. In Section \ref
arr_secgl_funcs we review some useful free (global) functions that
operate on arrangements, the most important ones being the free
insertion-functions.  In Section \ref aos_sec-unbounded we explain how
to construct and manipulate arrangements of unbounded curves.  Section
\ref aos_sec-geom_traits contains detailed descriptions of the
geometric traits concept hierarchy and the various geometric traits
classes included in the \ref PkgArrangementOnSurface2 package. The
different traits classes enables the construction and manipulation of
arrangements of different families of curves. Naturally, here, the
embedding surface plays a significant role. In Section \ref
arr_ssecnotif we review the notification mechanism that allows
external classes to keep track of the changes that an arrangement
instance goes through. Section \ref arr_ssecex_dcel explains how to
extend the \dcel records, to store extra data with them, and to
efficiently update this data.  In Section \ref arr_ssecoverlay we
introduce the fundamental operation of overlaying two arrangements.
Section \ref arr_ssecarr_with_hist describes a class-template that
extends the arrangement by storing additional history records with its
curves. In Section \ref aos_sec-io we review the arrangement
input/output functions. In Section \ref aos_sec-bgl we describes how
to apply the graph algorithms implemented in the Boost Graph Library
to arrangement types. Finally, in Section \ref aos_sec-tips we provide
some tips that can be applied to expedite computation.

<!-- ======================================================================= -->
\section aos_sec-basic Basic Arrangements
<!-- ======================================================================= -->

We start with a formal definition of two-dimensional arrangements, and
proceed with an introduction to the data structure used to represent
the incidence relations among features of two-dimensional
arrangements, namely, the <em>doubly-connected edge list</em>, or
\dcel for short. In Section \ref aos_ssec-basic-arr_class we
describe a central component in the \ref PkgArrangementOnSurface2
package, namely, the `Arrangement_2` class-template, which can be used
to represent arrangements in the plane.

<!-- ----------------------------------------------------------------------- -->
\subsection aos_ssec-basic-dcel Representation of Arrangements: The Dcel
<!-- ----------------------------------------------------------------------- -->

Given a set \f$\mathcal{C}\f$ of curves embedded in a two-dimensional
surface, the <em>arrangement</em> \f$\mathcal{A}(\mathcal{C})\f$ is
the subdivision of the surface into zero-dimensional, one-dimensional
and two-dimensional cells,\cgalFootnote{We use the term <em>cell</em>
to describe the various dimensional entities in the induced
subdivision. Sometimes, the term <em>face</em> is used for this
purpose in the literature. However, we use the term <em>face</em> to
describe a <em>two-dimensional</em> cell.}  called <em>vertices</em>,
<em>edges</em> and <em>faces</em>, respectively, induced by the curves
in \f$\mathcal{C}\f$.

In our implementation we use a definition that slightly deviates from
the standard definition above for practical reasons. The curves in
\f$\mathcal{C}\f$ can intersect each other (a single curve may also be
self-intersecting or may comprise several disconnected branches) and
are not necessarily \f$x\f$-monotone.\cgalFootnote{A continuous planar
curve \f$c\f$ is <em>\f$x\f$-monotone</em> if every vertical line
intersects it at most once. For example, a non-vertical line segment
is always \f$x\f$-monotone and so is the graph of any continuous
function \f$y = f(x)\f$. For convenience, we treat vertical line
segments as <em>weakly \f$x\f$-monotone</em>, as there exists a single
vertical line that overlaps them. A circle of radius \f$r\f$ centered
at \f$(x_0, y_0)\f$ is not \f$x\f$-monotone, as the vertical line \f$x
= x_0\f$ intersects it at \f$(x_0, y_0 - r)\f$ and at \f$(x_0, y_0 +
r)\f$.}  We construct a collection \f$\mathcal{C}''\f$ of
\f$x\f$-monotone subcurves that are pairwise disjoint in their
interiors in two steps as follows. First, we decompose each curve in
\f$\mathcal{C}\f$ into maximal \f$x\f$-monotone subcurves and possibly
isolated points, obtaining the collection \f$\mathcal{C}'\f$. Note
that an \f$x\f$-monotone curve cannot be self-intersecting. Then, we
decompose each curve in \f$\mathcal{C}'\f$ into maximal connected
subcurves not intersecting any other curve (or point) in
\f$\mathcal{C}'\f$ in its interior. The collection \f$\mathcal{C}''\f$
contains isolated points, if the collection \f$\mathcal{C}'\f$
contains such points. The arrangement induced by the collection
\f$\mathcal{C}''\f$ can be conveniently embedded as a planar graph,
the vertices of which are associated with curve endpoints or with
isolated points, and the edges of which are associated with
subcurves. It is easy to see that the faces of
\f$\mathcal{A}(\mathcal{C})\f$ are the same as the faces of
\f$\mathcal{A}(\mathcal{C}'')\f$. There are possibly more vertices in
\f$\mathcal{A}(\mathcal{C}'')\f$ than in
\f$\mathcal{A}(\mathcal{C})\f$---the vertices where curves were cut
into \f$x\f$-monotone (non-intersecting) pieces; accordingly there may
also be more edges in \f$\mathcal{A}(\mathcal{C}'')\f$. This graph can
be represented using a <em>doubly-connected edge list</em>
data-structure (\dcel), which consists of containers of vertices,
edges and faces and maintains the incidence relations among these
cells. It is one of a family of combinatorial data structures called
<em>halfedge data structures</em> (<span class="textsc">Hds</span>),
which are edge-centered data structures capable of maintaining
incidence relations among cells of, for example, planar subdivisions,
polyhedra, or other orientable, two-dimensional surfaces embedded in a
space of arbitrary dimension. Geometric interpretation is added by
classes built on top of the halfedge data structure.

\cgalAdvancedBegin

The \f$x\f$-monotone curves of an arrangement are embedded in a
rectangular two-dimensional area called the parameter space. The
parameter space is defined as \f$X \times Y\f$, where \f$X\f$ and
\f$Y\f$ are open, half-open, or closed intervals with endpoints in the
compactified real line \f$\mathbb{R} \cup \{-\infty,+\infty\}\f$. Let
\f$x_{\rm min}\f$, \f$x_{\rm max}\f$, \f$y_{\rm min}\f$, and
\f$y_{\rm max}\f$ denote the endpoints of \f$X\f$ and \f$Y\f$,
respectively. We typically refer to these values as the left, right,
bottom, and top sides of the boundary of the parameter space. If the
parameter space is, for example, the entire compactified plane, as in
the case of arrangements in the plane,
\f$x_{\rm min} = y_{\rm min} = -\infty\f$ and
\f$x_{\rm max} = y_{\rm max} = +\infty\f$; see Section \ref
aos_sec-curved_surfaces for more details.

\cgalAdvancedEnd

The \dcel data-structure represents each edge using a pair of
directed <em>halfedges</em>, one going from the
\f$xy\f$-lexicographically smaller (left) endpoint of the curve
towards the \f$xy\f$-lexicographically larger (right) endpoint, and
the other, known as its <em>twin</em> halfedge, going in the opposite
direction. As each halfedge is directed, it has a <em>source</em>
vertex and a <em>target</em> vertex. Halfedges are used to separate
faces, and to connect vertices, with the exception of <em>isolated
vertices</em> (representing isolated points), which are disconnected.
If a vertex \f$v\f$ is the target of a halfedge \f$e\f$, we say that
\f$v\f$ and \f$e\f$ are <em>incident</em> to each other. The halfedges
incident to a vertex \f$v\f$ form a circular list sorted in a
clockwise order around this vertex. (An isolated vertex has no
incident halfedges.)

An <em>edge</em> of an arrangement is a maximal portion of a curve
between two vertices of the arrangement. Each edge is represented in
the \dcel by a pair of twin halfedges. Each halfedge \f$e\f$
stores a pointer to its <em>incident face</em>, which is the face lying
to its left. Moreover, every halfedge is followed by another halfedge
sharing the same incident face, such that the target vertex of the
halfedge is the same as the source vertex of the next halfedge. The
halfedges around faces form circular chains, such that all halfedges
of a chain are incident to the same face and wind along its boundary.
We call such a chain a <em>connected component of the boundary</em>, or
<em>CCB</em> for short.

The unique CCB of halfedges winding in a counterclockwise orientation
along a face boundary is referred to as the <em>outer CCB</em> of the
face. For the time being let us consider only (i) arrangements of
bounded curves, such that exactly one unbounded face exists in every
arrangement, and (ii) arrangements embedded in the plane, such that
every face has at most one outer CCB. The unbounded face does not have
an outer boundary. Any other connected component of the boundary of
the face is called a <em>hole</em>, or <em>inner CCB</em>, and can be
represented as a circular chain of halfedges winding in a clockwise
orientation around it. Note that a hole does not necessarily
correspond to a face at all, as it may have no area, or alternatively
it may contain several faces. Every face can have several inner CCBs
in its interior, or may not contain inner CCBs at all. In addition,
every face may contain isolated vertices in its interior. We
distinguish between isolated vertices and holes even though,
theoretically, the former are degenerate holes. See
\cgalFigureRef{aos_fig-arr_segs} for an illustration of the various
\dcel features. For more details on the \dcel data structure see
\cgalCite{bkos-cgaa-00} Chapter 2.

<!-- ----------------------------------------------------------------------- -->
\cgalFigureBegin{aos_fig-arr_segs,arr_segs.png}
An arrangement of interior-disjoint line segments with some of the
\dcel records that represent it. The unbounded face \f$f_0\f$ has
a single connected component that forms a hole inside it, and this
hole comprises of several faces. The halfedge \f$e\f$ is directed
from its source vertex \f$v_1\f$ to its target vertex \f$v_2\f$.
This edge, together with its twin \f$e'\f$, correspond to a
line segment that connects the points associated with \f$v_1\f$ and
\f$v_2\f$ and separates the face \f$f_1\f$ from \f$f_2\f$. The
predecessor \f$e_{\rm prev}\f$ and successor \f$e_{\rm next}\f$ of
\f$e\f$ are part of the chain that form the outer boundary of the
face \f$f_2\f$. The face \f$f_1\f$ has a more complicated structure
as it contains two holes in its interior: One hole consists of two
adjacent faces \f$f_3\f$ and \f$f_4\f$, while the other hole
comprises of two edges. \f$f_1\f$ also contains two isolated vertices
\f$u_1\f$ and \f$u_2\f$ in its interior.
\cgalFigureEnd
<!-- ----------------------------------------------------------------------- -->

<!-- ----------------------------------------------------------------------- -->
\subsection aos_ssec-basic-arr_class The Arrangement Class Template
<!-- ----------------------------------------------------------------------- -->

One of the main components of the \ref PkgArrangementOnSurface2
package is the `Arrangement_2<Traits,Dcel>` class template. An
instance of this template is used to represent an arrangement embedded
in the plane. The class template provides the interface needed to
construct such arrangements, traverse them, and maintain them.

The design of the \ref PkgArrangementOnSurface2 package is guided by
two aspects of modularity as follows:
<UL>
<LI>the separation of the representation of the arrangements and the
  various geometric algorithms that operate on them, and</LI>
<LI>the separation of the topological and geometric aspects of the
  two-dimensional subdivision.
</UL>

The latter separation is exhibited by the two template parameters of
the `Arrangement_2` class template; their description follows.

<UL>

<LI>The `Traits` template-parameter should be substituted by a
  model of the `AosBasicTraits_2` concept and optionally
  additional geometry traits concepts. A model of the
  `AosBasicTraits_2` concept defines the types of
  \f$x\f$-monotone curves and two-dimensional points, namely
  `AosBasicTraits_2::X_monotone_curve_2` and
  `AosBasicTraits_2::Point_2`, respectively, and supports
  basic geometric predicates on them. The instantiated traits class
  determines the family of planar curves that induce the arrangement.

  In this section we always use `Arr_non_caching_segment_traits_2` as
  our traits-class model in order to construct arrangements of line
  segments. In succeeding sections we also use `Arr_segment_traits_2`
  as our traits-class model. These two traits trade computation time
  and storage space. The latter stores the underlying line of every
  segment of the arrangement to expedite certain operations on the
  arrangement segments. In Section \ref aos_sec-unbounded we use
  `Arr_linear_traits_2` to construct arrangements of linear curves
  (i.e., lines, rays, and line segments). The \ref
  PkgArrangementOnSurface2 package contains several other traits
  classes that can handle other types of curves, such as polylines
  (continuous piecewise-linear curves), conic arcs, and arcs of
  rational functions. We exemplify the usage of these traits classes
  in Section \ref aos_sec-geom_traits.

<LI>The `Dcel` template-parameter should be substituted by a class
  that models the `AosDcel` concept, which is used to represent
  the topological layout of the arrangement. This parameter is
  substituted by `Arr_default_dcel<Traits>` by default, and
  we use this default value in this and in the following three
  sections. However, in many applications it is necessary to extend the
  \dcel features. This is done by substituting the `Dcel` parameter with
  a different type (typically, a different instance of the
  `Arr_dcel<>` class template); see Section \ref arr_ssecex_dcel
  for further explanations and examples.
</UL>

The function template `print_arrangement_size()` listed below, and
defined in the header file `Arr_print.h`, prints out quantitative
measures of a given arrangement. While in what follows it is used only
by examples, it demonstrates well the use of the member functions
\link Arrangement_on_surface_2::number_of_vertices()
`number_of_vertices()`\endlink, \link
Arrangement_on_surface_2::number_of_edges()
`number_of_edges()`\endlink, and \link
Arrangement_on_surface_2::number_of_faces()
`number_of_faces()`\endlink, which return the number of vertices,
edges, and faces of an arrangement, respectively.

\anchor lst_paz
\code{.cpp}
template <typename Arrangement>
void print_arrangement_size(const Arrangement& arr) {
  std::cout << "The arrangement size:\n"
            << "   |V| = " << arr.number_of_vertices()
            << ",  |E| = " << arr.number_of_edges()
            << ",  |F| = " << arr.number_of_faces() << std::endl;
}
\endcode

You can also obtain the number of halfedges of an arrangement using
the member function \link Arrangement_on_surface_2::number_of_halfedges()
`number_of_halfedges()`\endlink. Recall that the number of halfedges is
always twice the number of edges.

\image html triangle.png
\image latex triangle.png

The simple program listed below constructs an arrangement of three
connected line segments forming a triangle. It uses the
<em>Cartesian</em> kernel with an integral-number type to instantiate
the `Arr_non_caching_segment_traits_2<Kernel>` class template. The
resulting arrangement consists of two faces, a bounded triangular face
and the unbounded face.  Constructing and maintaining arrangements
using limited-precision numbers, such as `int`, works properly only
under severe restrictions, which in many cases render the program not
very useful. In this example, however, the points are far apart, and
constructions of new geometric objects do not occur. Thus, it is safe
to use `int` after all. The program constructs an arrangement induced
by three line segments that are pairwise disjoint in their interior,
prints out the number of faces, and ends. It uses the
\link insert(Arrangement_2<Traits, Dcel>&, InputIterator, InputIterator) `insert()`\endlink
free-function, which inserts the segments into the
arrangement; see Section \ref arr_secgl_funcs. It uses the member
function \link Arrangement_on_surface_2::number_of_faces
`number_of_faces()`\endlink to obtain the number of faces (two in this
case). We give more elaborate examples in the rest of this
chapter. The programs in those examples rely on computing with numbers
of arbitrary precision, which guarantees robust execution and correct
results.

\code{.cpp}
#include <CGAL/Cartesian.h>
#include <CGAL/Arr_non_caching_segment_traits_2.h>
#include <CGAL/Arrangement_2.h>

using Number_type = int;
using Kernel = CGAL::Cartesian<Number_type>;
using Traits = CGAL::Arr_non_caching_segment_traits_2<Kernel>;
using Point = Traits_2::Point_2;
using Segment = Traits_2::X_monotone_curve_2;
using Arrangement = CGAL::Arrangement_2<Traits_2>;

int main() {
  Arrangement arr;
  Point p1(1, 1), p2(1, 2), p3(2, 1);
  Segment cv[] = {Segment(p1, p2), Segment(p2, p3), Segment(p3, p1)};
  CGAL::insert(arr, &cv[0], &cv[sizeof(cv)/sizeof(Segment)]);
  return 0;
}
\endcode

<!-- ----------------------------------------------------------------------- -->
\subsection arr_ssectraverse Traversing the Arrangement
<!-- ----------------------------------------------------------------------- -->

The simplest and most fundamental arrangement operations are the
various traversal methods, which allow users to systematically go over
the relevant features of the arrangement at hand.

As mentioned above, the arrangement is represented as a \dcel,
which stores three containers of vertices, halfedges and faces; thus,
the `Arrangement_2` class template supplies iterator types for these
containers, respectively. For example, if `arr` is an `Arrangement_2`
object, the calls \link Arrangement_on_surface_2::vertices_begin()
`arr.vertices_begin()`\endlink and \link
Arrangement_on_surface_2::vertices_end `arr.vertices_end()`\endlink
return iterators of the nested \link
Arrangement_on_surface_2::Vertex_iterator `Vertex_iterator`\endlink
type that define the valid range of vertices of the arrangement
`arr`. The value type of this iterator is \link
Arrangement_on_surface_2::Vertex `Vertex`\endlink. Moreover, the
vertex-iterator type is convertible to \link
Arrangement_on_surface_2::Vertex_handle `Vertex_handle`\endlink, which
serves as a pointer to a vertex. As we show next, all functions
related to arrangement features accept handle types as input
parameters and return handle types as their output.
See Chapter \ref Chapter_Handles_Ranges_and_Circulators
"Handles and Circulators" for more information on \cgal handles.

In addition to the iterators for arrangement vertices, halfedges, and
faces, the arrangement class also provides an iterator for edges,
namely \link Arrangement_on_surface_2::Edge_iterator
`Edge_iterator`\endlink.  The value type of this iterator is \link
Arrangement_on_surface_2::Halfedge `Halfedge`\endlink, which is the
same as the value type of \link
Arrangement_on_surface_2::Halfedge_iterator
`Halfedge_iterator`\endlink. The calls \link
Arrangement_on_surface_2::edges_begin() `arr.edges_begin()`\endlink
and \link Arrangement_on_surface_2::edges_end()
`arr.edges_end()`\endlink return iterators that define the valid range
of arrangement edges. This range consists of half the number of
halfedges of the arrangement, as every twin halfedges has one
representative in this range.

All iterator, circulator\cgalFootnote{A <em>circulator</em> is used to
traverse a circular list, such as the list of halfedges incident to a
vertex.} and handle types also have non-mutable (<em>const</em>)
counterparts. These non-mutable iterator types are useful for
traversing an arrangement with the promise to keep it unchanged. For
example, the arrangement has a non-constant member function called
`Arrangement_on_surface_2::vertices_begin()` that returns a \link
Arrangement_on_surface_2::Vertex_iterator `Vertex_iterator`\endlink
object and another const member function that returns a \link
Arrangement_on_surface_2::Vertex_const_iterator
`Vertex_const_iterator`\endlink object. In fact, all methods listed in
this section that return an iterator, a circulator, or a handle have
non-mutable counterparts. It should be noted that, for example, \link
Arrangement_on_surface_2::Vertex_handle `Vertex_handle`\endlink can be
readily converted into a \link
Arrangement_on_surface_2::Vertex_const_handle
`Vertex_const_handle`\endlink, but not the other way around.

Conversions of non-mutable handles to the corresponding mutable
handles are nevertheless possible. They can be performed using the
overloaded member function \link
Arrangement_on_surface_2::non_const_handle()
`non_const_handle()`\endlink.  There are three variants that accept a
non-mutable handle to a vertex, a halfedge, or a face, respectively.
The call \link Arrangement_on_surface_2::non_const_handle()
`non_const_handle()`\endlink can be issued only if the arrangement
object `arr` is mutable; see, e.g., Section \ref arr_ssecpl.

<!-- ----------------------------------------------------------------------- -->
\subsubsection arr_sssectr_vertex Traversal Methods for an Arrangement Vertex
<!-- ----------------------------------------------------------------------- -->

A vertex \f$v\f$ of an arrangement induced by bounded curves is always
associated with a geometric entity, namely with an \link
Arrangement_on_surface_2::Point_2 `Point_2`\endlink object, which can
be obtained by \link Arrangement_on_surface_2::Vertex::point()
`v->point()`\endlink, where `v` identifies a handle to \f$v\f$.

The call \link Arrangement_on_surface_2::Vertex::is_isolated()
`v->is_isolated()`\endlink determines whether the vertex \f$v\f$ is
isolated or not. Recall that the halfedges incident to a non-isolated
vertex, namely, the halfedges that share a common target vertex, form
a circular list around this vertex. The call \link
Arrangement_on_surface_2::Vertex::incident_halfedges()
`v->incident_halfedges()`\endlink returns a circulator of the nested
type \link Arrangement_on_surface_2::Halfedge_around_vertex_circulator
`Halfedge_around_vertex_circulator`\endlink that enables the traversal
of this circular list around a given vertex \f$v\f$ in a clockwise
order. The value type of this circulator is \link
Arrangement_on_surface_2::Halfedge `Halfedge`\endlink. By convention,
the target of the halfedge is \f$v\f$. The call \link
Arrangement_on_surface_2::Vertex::degree() `v->degree()`\endlink
evaluates to the number of the halfedges incident to \f$v\f$.

The function below prints all the halfedges incident to a given
arrangement vertex (assuming that objects of the \link
Arrangement_on_surface_2::Point_2 `Point_2`\endlink type can be
inserted into the standard output using the `<<` operator). The
arrangement type is the same as in the simple example above.

\code
template <typename Arrangement>
void print_incident_halfedges(typename Arrangement::Vertex_const_handle v) {
  if (v->is_isolated()) {
    std::cout << "The vertex (" << v->point() << ") is isolated\n";
    return;
  }
  typename Arrangement::Halfedge_around_vertex_const_circulator first, curr;
  first = curr = v->incident_halfedges();
  std::cout << "The neighbors of the vertex (" << v->point() << ") are:";
  do std::cout << " (" << curr->source()->point() << ")";
  while (++curr != first);
  std::cout << std::endl;
}
\endcode

If \f$v\f$ is an isolated vertex, the call \link
Arrangement_on_surface_2::Vertex::face() `v->face()`\endlink can be used to
obtain the face that contains \f$v\f$.

<!-- ----------------------------------------------------------------------- -->
\subsubsection arr_sssectr_halfedge Traversal Methods for an Arrangement Halfedge
<!-- ----------------------------------------------------------------------- -->

A halfedge \f$e\f$ of an arrangement induced by bounded curves is
associated with an \link Arrangement_on_surface_2::X_monotone_curve_2
`X_monotone_curve_2`\endlink object, which can be obtained by
\link Arrangement_on_surface_2::Halfedge::curve()
`e->curve()`\endlink, where `e` identifies a handle to \f$e\f$.

The calls \link Arrangement_on_surface_2::Halfedge::source()
`e->source()`\endlink and \link
Arrangement_on_surface_2::Halfedge::target() `e->target()`\endlink
return handles to the halfedge's source-vertex and target-vertex,
respectively. You can obtain a handle to the twin halfedge using \link
Arrangement_on_surface_2::Halfedge::twin() `e->twin()`\endlink. Note
that from the definition of halfedges in the `Dcel` structure, the
following invariants always hold:
<UL>
<LI>\link Arrangement_on_surface_2::Halfedge::curve()
`e->curve()`\endlink is equivalent to \link
Arrangement_on_surface_2::Halfedge::curve()
`e->twin()->curve()`\endlink,
<LI>\link Arrangement_on_surface_2::Halfedge::source()
`e->source()`\endlink is equivalent to \link
Arrangement_on_surface_2::Halfedge::target()
`e->twin()->target()`\endlink, and
<LI>\link Arrangement_on_surface_2::Halfedge::target()
`e->target()`\endlink is equivalent to \link
Arrangement_on_surface_2::Halfedge::source()
`e->twin()->source()`\endlink.
</UL>

Every halfedge has an incident face that lies to its left, which can
be obtained by \link Arrangement_on_surface_2::Halfedge::face()
`e->face()`\endlink. Recall that a halfedge is always one link in a
connected chain (CCB) of halfedges that share the same incident
face. The \link Arrangement_on_surface_2::Halfedge::prev()
`e->prev()`\endlink and \link
Arrangement_on_surface_2::Halfedge::next() `e->next()`\endlink calls
return handles to the previous and next halfedges in the CCB,
respectively.

As the CCB is a circular list of halfedges, it is only natural to
traverse it using a circulator. Indeed \link
Arrangement_on_surface_2::Halfedge::ccb() `e->ccb()`\endlink returns
an \link Arrangement_on_surface_2::Ccb_halfedge_circulator
`Ccb_halfedge_circulator`\endlink object for traversing all halfedges
along the connected component of \f$e\f$. The value type of this
circulator is \link Arrangement_on_surface_2::Halfedge
`Halfedge`\endlink.

The function template `print_ccb()` listed below prints all
\f$x\f$-monotone curves along a given CCB (assuming that objects of
the \link Arrangement_on_surface_2::Point_2 `Point_2`\endlink and the
\link Arrangement_on_surface_2::X_monotone_curve_2
`X_monotone_curve_2`\endlink types can be inserted into the standard
output using the `<<` operator).

\code
template <typename Arrangement>
void print_ccb(typename Arrangement::Ccb_halfedge_const_circulator circ) {
  Ccb_halfedge_const_circulator curr = circ;
  std::cout << "(" << curr->source()->point() << ")";
  do {
    typename Arrangement::Halfedge_const_handle he = curr->handle();
    std::cout << " [" << e->curve() << "] "
              << "(" << e->target()->point() << ")";
  } while (++curr != circ);
  std::cout << std::endl;
}
\endcode

<!-- ----------------------------------------------------------------------- -->
\subsubsection arr_sssectr_face Traversal Methods for an Arrangement Face
<!-- ----------------------------------------------------------------------- -->

An `Arrangement_2` object `arr` that identifies an arrangement of
bounded curves always has a single unbounded face. The call \link
Arrangement_on_surface_2::unbounded_face()
`arr.unbounded_face()`\endlink returns a handle to this face.  Note
that an empty arrangement contains nothing <em>but</em> the unbounded
face.

Given a handle to a face \f$f\f$, you can use the call \link
Arrangement_on_surface_2::Face::is_unbounded()
`f->is_unbounded()`\endlink to determine whether the face \f$f\f$ is
unbounded. Bounded faces have an outer CCB, and the \link
Arrangement_on_surface_2::Face::outer_ccb() `outer_ccb()`\endlink
method returns a circulator for the halfedges along this CCB. Note
that the halfedges along this CCB wind in a counterclockwise order
around the outer boundary of the face.

A face can also contain disconnected components in its interior,
namely, holes and isolated vertices. You can access these components
as follows:

<UL>

<LI>You can obtain a pair of iterators of type \link
  Arrangement_on_surface_2::Face::Hole_iterator
  `Hole_iterator`\endlink that define the range of holes inside a face
  \f$f\f$ by calling \link
  Arrangement_on_surface_2::Face::holes_begin()
  `f->holes_begin()`\endlink and \link
  Arrangement_on_surface_2::Face::holes_end()
  `f->holes_end()`\endlink. The value type of this iterator type is
  \link Arrangement_on_surface_2::Ccb_halfedge_circulator
  `Ccb_halfedge_circulator`\endlink, defining the CCB that winds in a
  clockwise order around a hole.  The call \link
  Arrangement_on_surface_2::Face::number_of_holes()
  `f->number_of_holes()`\endlink return the number of holes in
  \f$f\f$.

<LI>The calls \link
  Arrangement_on_surface_2::Face::isolated_vertices_begin()
  `f->isolated_vertices_begin()`\endlink and \link
  Arrangement_on_surface_2::Face::isolated_vertices_end()
  `f->isolated_vertices_end()`\endlink return iterators of type \link
  Arrangement_on_surface_2::Isolated_vertex_iterator
  `Isolated_vertex_iterator`\endlink that define the range of isolated
  vertices inside the face \f$f\f$. The value type of this iterator is
  \link Arrangement_on_surface_2::Vertex `Vertex`\endlink.

</UL>

The function `print_face()` listed below prints the outer and inner
boundaries of a given face. It uses the function template
`print_ccb()` listed above.

\code
template <typename Arrangement>
void print_face(typename Arrangement::Face_const_handle f) {
  // Print the outer boundary.
  if (f->is_unbounded()) std::cout << "Unbounded face.\n";
  else {
    std::cout << "Outer boundary: ";
    print_ccb(f->outer_ccb());
  }

  // Print the boundary of each of the holes.
  std::size_t index = 1;
  for (auto hi = f->holes_begin(); hi != f->holes_end(); ++hi) {
    std::cout << " Hole #" << index++ << ": ";
    print_ccb(*hi);
  }

  // Print the isolated vertices.
  index = 1;
  for (auto iv = f->isolated_vertices_begin();
       iv != f->isolated_vertices_end(); ++iv)
  {
    std::cout << " Isolated vertex #" << index++ << ": "
              << "(" << iv->point() << ")\n";
  }
}
\endcode

The function `print_arrangement()` listed below prints the features of
a given arrangement. The file `arr_print.h`, which can be found under
the examples folder, includes the definitions of this function, as
well as the definitions of all other functions listed in this
section. This concludes the preview of the various traversal methods.

\code
void print_arrangement (const Arrangement_2& arr) {
  // Print the arrangement vertices.
  std::cout << arr.number_of_vertices() << " vertices:\n";
  for (auto vit = arr.vertices_begin(); vit != arr.vertices_end(); ++vit) {
    std::cout << "(" << vit->point() << ")";
    if (vit->is_isolated()) std::cout << " - Isolated.\n";
    else std::cout << " - degree " << vit->degree() << std::endl;
  }

  // Print the arrangement edges.
  std::cout << arr.number_of_edges() << " edges:\n";
  for (auto eit = arr.edges_begin(); eit != arr.edges_end(); ++eit)
    std::cout << "[" << eit->curve() << "]\n";

  // Print the arrangement faces.
  std::cout << arr.number_of_faces() << " faces:\n";
  for (auto fit = arr.faces_begin(); fit != arr.faces_end(); ++fit)
    print_face(fit);
}
\endcode

<!-- ----------------------------------------------------------------------- -->
\subsection arr_ssecmodify Modifying the Arrangement
<!-- ----------------------------------------------------------------------- -->

In this section we review the various member functions of the
`Arrangement_2` class that allow users to modify the topological
structure of the arrangement through the introduction of new edges or
vertices, or the modification or removal of existing edges and
vertices.

The arrangement member-functions that insert new \f$x\f$-monotone
curves into the arrangement, thus enabling the construction of a
two-dimensional surface subdivision, are rather specialized, as they
assume that the interior of the inserted curve is disjoint from all
existing arrangement vertices and edges, and in addition require
apriori knowledge of the location of the inserted curve. Indeed, for
most purposes it is more convenient to construct an arrangement using
the free (global) insertion functions, which relax these
restrictions. However, as these free functions are implemented in
terms of the specialized insertion functions, we start by describing
the fundamental functionality of the arrangement class, and describe
the operation of the free functions in Section \ref arr_secgl_funcs.

<!-- ----------------------------------------------------------------------- -->
\subsection arr_sssecmf_insert_cv Inserting Pairwise Disjoint x-Monotone Curves
<!-- ----------------------------------------------------------------------- -->

The most trivial functions that allow users to modify the arrangement
are the specialized functions for the insertion of an \f$x\f$-monotone
curve the interior of which is disjoint from the interior of all other
curves in the existing arrangement and does not contain any point of
the arrangement. In addition, these functions require that the
location of the curve in the arrangement be known.

The rather harsh restrictions on the inserted curves enable an
efficient implementation. While inserting an \f$x\f$-monotone curve,
the interior of which is disjoint from all curves in the existing
arrangement, is quite straightforward, as we show next, (efficiently)
inserting a curve that intersects with the curves already in the
arrangement is much more complicated and requires the application of
nontrivial geometric algorithms. The decoupling of the topological
arrangement representation from the various algorithms that operate on
it dictates that the general insertion operations be implemented as
free functions that operate on the arrangement and the inserted
curve(s); see Section \ref arr_secgl_funcs for more details and
examples.

<!-- ----------------------------------------------------------------------- -->
\cgalFigureBegin{aos_fig-insert,insert.png}
Illustrations of the various specialized insertion procedures. The
inserted \f$x\f$-monotone curve is drawn as a dashed line, surrounded
by two solid arrows that represent the pair of twin halfedges added to
the \dcel. Existing vertices are shown as red discs, while new
vertices are shown as blue discs. Existing halfedges that are
affected by the insertion operations are drawn as dashed arrows.  (a)
Inserting a curve as a new hole inside the face \f$f\f$.  (b)
Inserting a curve from an existing vertex \f$u\f$ that corresponds to
one of its endpoints.  (c) Inserting an \f$x\f$-monotone curve, the
endpoints of which correspond to existing vertices \f$u_1\f$ and
\f$u_2\f$. In this case, the new pair of halfedges closes a new face
\f$f'\f$. The hole \f$h_1\f$, which belonged to \f$f\f$ before
the insertion, becomes a hole in this new face.
\cgalFigureEnd
<!-- ----------------------------------------------------------------------- -->

When an \f$x\f$-monotone curve is inserted into an existing
arrangement, such that the interior of this curve is disjoint from the
interiors of all curves in the arrangement, only the following three
scenarios are possible, depending on the status of the endpoints of
the inserted curve:

<OL>

<LI>Neither curve endpoints correspond to any existing arrangement
vertex. In this case we have to create two new vertices that
correspond to the curve endpoints, respectively, and connect them
using a pair of twin halfedges. This halfedge pair forms a new
hole inside the face that contains the curve in its interior.</LI>

<LI>Exactly one endpoint corresponds to an existing arrangement
vertex. (We distinguish between a vertex that corresponds to the left
endpoint of the inserted curve and a vertex that corresponds to its
right endpoint.) In this case we have to create a new vertex that
corresponds to the other endpoint of the curve and to connect the two
vertices by a pair of twin halfedges that form an "antenna" emanating
from the boundary of an existing connected component. (Note that if
the existing vertex is isolated, we need to form a new hole inside
the face that contains this vertex, essentially falling back to the
handling of the previous case, naturally, skipping the creation of
the existing vertex.)</LI>

<LI>Both endpoints correspond to existing arrangement vertices. In
this case we connect these vertices using a pair of twin halfedges.
(If one or both vertices are isolated, we fall back to the handling of
the first or second case, respectively, naturally, skipping the
creation of the existing vertices.) The two following subcases may
occur:

<UL>

<LI>Two disconnected components are merged into a single connected
  component (as is the case with the segment \f$s_1\f$ in the figure
  below).</LI>

<LI>A new face, which is split from an existing arrangement face, is
  created (as is the case with the segment \f$s_2\f$ in the figure
  below). In this case we also have to examine the holes and isolated
  vertices in the existing face and move the relevant ones inside the
  new face.</LI>

</UL>
</LI>
</OL>

\image html connect_comp.png
\image latex connect_comp.png

The `Arrangement_2` class offers insertion functions that perform the
special insertion procedures listed above, namely, \link
Arrangement_on_surface_2::insert_in_face_interior()
`insert_in_face_interior()`\endlink, \link
Arrangement_on_surface_2::insert_from_left_vertex()
`insert_from_left_vertex()`\endlink, \link
Arrangement_on_surface_2::insert_from_right_vertex()
`insert_from_right_vertex()`\endlink and \link
Arrangement_on_surface_2::insert_at_vertices()
`insert_at_vertices()`\endlink. The first function accepts an
\f$x\f$-monotone curve \f$c\f$ and an arrangement face \f$f\f$ that
contains this curve in its interior. The other functions accept an
\f$x\f$-monotone curve \f$c\f$ and handles to the existing vertices
that correspond to the curve endpoint(s). Each of the four functions
returns a handle to one of the twin halfedges that have been created;
more precisely:

<UL>

<LI>\link Arrangement_on_surface_2::insert_in_face_interior()
`insert_in_face_interior(c, f)`\endlink returns a handle to the
halfedge directed from the left endpoint of \f$c\f$ towards the vertex
corresponding to its right endpoint.

<LI>\link Arrangement_on_surface_2::insert_from_left_vertex()
`insert_from_left_vertex(c, v)`\endlink and \link
Arrangement_on_surface_2::insert_from_right_vertex()
`insert_from_right_vertex(c, v)`\endlink each returns a handle to the
halfedge, the source of which is the vertex \f$v\f$, and the target of
which is the new vertex that has just been created.

<LI>\link Arrangement_on_surface_2::insert_at_vertices()
`insert_at_vertices(c, v1, v2)`\endlink returns a handle to the
halfedge directed from \f$v_1\f$ to \f$v_2\f$.

</UL>

<!-- ----------------------------------------------------------------------- -->
\cgalFigureBegin{aos_fig-edge_insertion,edge_insertion.png}
The arrangement of the line segments \f$s_1, \ldots, s_5\f$
constructed in \ref Arrangement_on_surface_2/edge_insertion.cpp.
The arrows mark the direction of the halfedges returned from the
various insertion functions.
\cgalFigureEnd
<!-- ----------------------------------------------------------------------- -->

The program below demonstrates the usage of the four specialized
insertion functions. It creates an arrangement of five line segments
\f$s_1, \ldots, s_5\f$, as depicted in
\cgalFigureRef{aos_fig-edge_insertion}.  \cgalFootnote{Notice that in
all figures in the rest of this chapter the coordinate axes are drawn
only for illustrative purposes and are <em>not</em> part of the
arrangement.} The first line segment \f$s_1\f$ is inserted in the
interior of the unbounded face, while the four succeeding line
segments \f$s_2, \ldots, s_5\f$ are inserted using the vertices
created by the insertion of preceding segments. The arrows in the
figure mark the direction of the halfedges \f$e_1, \ldots, e_5\f$
returned from the insertion functions. The resulting arrangement
consists of three faces, where the two bounded faces form together a
hole in the unbounded face.

Two header files are included in the code in order to make this and
the following examples more compact. The file
`arr_inexact_construction_segments.h` is listed
immediately after the program. The file `arr_print.h` is
introduced in Section \ref arr_ssectraverse.

\cgalExample{Arrangement_on_surface_2/edge_insertion.cpp}

The statements below define the types for arrangements of line
segments common to all examples that do not construct new geometric
objects. They are kept in the header file
`arr_inexact_construction_segments.h`.  In these examples the `Traits`
parameter of the `Arrangement_2<Traits, Dcel>` class template is
substituted by an instance of the
`Arr_non_caching_segment_traits_2<Kernel>` class template. The
`Arr_non_caching_segment_traits_2` class template is instantiated with
the predefined kernel that evaluates predicates in an exact manner,
but constructs geometric objects in an inexact manner, as none of
these examples construct new geometric objects.  In the remaining
examples the traits class-template is instantiated with a kernel that
evaluates predicates and constructs geometric objects, both in an
exact manner.

\code{.cpp}
#include <CGAL/Exact_predicates_inexact_constructions_kernel.h>
#include <CGAL/Arr_non_caching_segment_traits_2.h>
#include <CGAL/Arrangement_2.h>

using Kernel = CGAL::Exact_predicates_inexact_constructions_kernel;
using Number_type = Kernel::FT;

using Traits = CGAL::Arr_non_caching_segment_traits_2<Kernel>;
using Point = Traits::Point_2;
using Segment = Traits::X_monotone_curve_2;

using Arrangement = CGAL::Arrangement_2<Traits>;
using Vertex_handle = Arrangement::Vertex_handle;
using Halfedge_handle = Arrangement::Halfedge_handle;
using Face_handle = Arrangement::Face_handle;
\endcode

<!-- ----------------------------------------------------------------------- -->
\subsection arr_sssecmf_iso_verts Manipulating Isolated Vertices
<!-- ----------------------------------------------------------------------- -->

Isolated points are simpler geometric entities than curves, and indeed
the member functions that manipulate them are easier to understand.

The call \link Arrangement_on_surface_2::insert_in_face_interior()
`arr.insert_in_face_interior(p, f)`\endlink inserts an isolated point
\f$p\f$, located in the interior of a given face \f$f\f$, into the
arrangement and returns a handle to the arrangement vertex associated
with \f$p\f$ it has created. Naturally, this function has a
precondition that \f$p\f$ is really an isolated point; namely it does
not coincide with any existing arrangement vertex and does not lie on
any edge. As mentioned in Section \ref arr_ssectraverse, it is
possible to obtain the face containing an isolated vertex calling the
member function `Arrangement_on_surface_2::Vertex::face()`. The member
function
`Arrangement_on_surface_2::remove_isolated_vertex(Vertex_handle v)`
accepts a handle to an isolated vertex and removes it from the
arrangement.

<!-- ----------------------------------------------------------------------- -->
\cgalFigureBegin{aos_fig-isolated_vertices,isolated_vertices.png}
An arrangement of line segments containing three isolated vertices,
as constructed in \ref Arrangement_on_surface_2/isolated_vertices.cpp.
The vertices \f$u_2\f$ and \f$u_3\f$ are eventually removed from the
arrangement.
\cgalFigureEnd
<!-- ----------------------------------------------------------------------- -->

The following program demonstrates the usage of the arrangement
member-functions for manipulating isolated vertices. It first inserts
three isolated vertices, \f$u_1\f$, \f$u_2\f$, and \f$u_3\f$, located
inside the unbounded face of the arrangement. Then, it inserts four
line segments \f$s_1, \ldots, s_4\f$, that form a square hole inside
the unbounded face (see \cgalFigureRef{aos_fig-edge_insertion} for an
illustration). Finally, it traverses the vertices and removes those
isolated vertices that are still contained in the unbounded face
(\f$u_2\f$ and \f$u_3\f$ in this case):

\cgalExample{Arrangement_on_surface_2/isolated_vertices.cpp}

<!-- ----------------------------------------------------------------------- -->
\subsection arr_sssecmf_halfedges Manipulating Halfedges
<!-- ----------------------------------------------------------------------- -->

While reading the previous subsection you learned how to insert new
points that induce isolated vertices into the arrangement. You may
wonder now how you can insert a new point that lies on an
\f$x\f$-monotone curve that is associated with existing arrangement
edge.

The introduction of a vertex, the geometric mapping of which is a
point \f$p\f$ that lies on an \f$x\f$-monotone curve, requires the
splitting of the curve in its interior at \f$p\f$. The two resulting
subcurves induce two new edges, respectively. In general, the
`Arrangement_2` class template relies on the geometry traits to
perform such a split. As a matter of fact, it relies on the geometry
traits to perform all geometric operations. To insert a point \f$p\f$
that lies on an \f$x\f$-monotone curve associated with an existing
edge \f$e\f$ into the arrangement \f$\mathcal{A}\f$, you must first
construct the two curves \f$c_1\f$ and \f$c_2\f$, which are the two
subcurves that result from splitting the \f$x\f$-monotone curve
associated with the edge \f$e\f$ at \f$p\f$. Then, you have to issue
the call \link Arrangement_on_surface_2::split_edge()
`arr.split_edge(he, c1, c2)`\endlink, where `arr` identifies the
arrangement \f$\mathcal{A}\f$ and `he` is a handle to one of the two
halfedges that represent the edge \f$e\f$. The function splits the two
halfedges that represent \f$e\f$ into two pairs of halfedges,
respectively. Two new halfedges are incident to the new vertex \f$v\f$
associated with \f$p\f$. The function returns a handle to the new
halfedge, the source of which is the source vertex of the halfedge
handled by `he`, and the target of which is the new vertex \f$v\f$.

<!-- - For example, if the halfedge
drawn as a dashed line at the top in the figure xxx is passed as
input, the halfedge drawn as a dashed line at the bottom is returned
as output.- -->

The reverse operation is also possible. Consider a vertex \f$v\f$ of
degree \f$2\f$ that has two incident edges \f$e_1\f$ and \f$e_2\f$
associated with two curves \f$c_1\f$ and \f$c_2\f$, respectively, such
that the union of \f$c_1\f$ and \f$c_2\f$ results in a single
continuous \f$x\f$-monotone curve \f$c\f$ of the type supported by the
traits class in use. To merge the edges \f$e_1\f$ and \f$e_2\f$ into a
single edge associated with the curve \f$c\f$, essentially removing
the vertex \f$v\f$ from the arrangement identified by `arr`, you need
to issue the call \link Arrangement_2.merge_edge() `arr.merge_edge(he1,
he2, c)`\endlink, where `he1` and `he2` are handles to halfedges
representing \f$e_1\f$ and \f$e_2\f$, respectively.

Finally, the call \link Arrangement_2.remove_edge()
`remove_edge(he)`\endlink removes the edge \f$e\f$ from the
arrangement, where `he` is a handle to one of the two halfedges that
represents \f$e\f$. Note that this operation is the reverse of an
insertion operation, so it may cause a connected component to split
into two, or two faces to merge into one, or a hole to disappear.  By
default, if the removal of \f$e\f$ causes one of its end vertices to
become isolated, this vertex is removed as well. However, you can
control this behavior and choose to keep the isolated vertices by
supplying additional Boolean flags to \link
Arrangement_on_surface_2::remove_edge `remove_edge()`\endlink
indicating whether the source or the target vertices are to be removed
should they become isolated.

<!-- ----------------------------------------------------------------------- -->
\cgalFigureBegin{aos_fig-edge_manipulation,edge_manipulation.png}
The three steps of the example program \ref
Arrangement_on_surface_2/edge_manipulation.cpp. In Step (a) it
constructs an arrangement of four line segments. In Step (b) the edges
\f$e_1\f$ and \f$e_2\f$ are split, and the split points are connected
with a new segment \f$s\f$ that is inserted into the arrangement. This
operation is undone in Step (c), where \f$e\f$ is removed from the
arrangement, rendering its end vertices \f$u_1\f$ and \f$u_2\f$
redundant. We therefore remove these vertices by merging their
incident edges and go back to the arrangement depicted in (a).
\cgalFigureEnd
<!-- ----------------------------------------------------------------------- -->

The following example program shows how the edge-manipulation
functions can be used. The program works in three steps, as
demonstrated in \cgalFigureRef{aos_fig-isolated_vertices}. Note that
the program uses the fact that \link
Arrangement_on_surface_2::split_edge() `split_edge()`\endlink returns
one of the new halfedges (after the split) that has the same direction
as the original halfedge (the first parameter of the function) and is
directed towards the split point. Thus, it is easy to identify the
vertices \f$u_1\f$ and \f$u_2\f$ associated with the split points.

\cgalExample{Arrangement_on_surface_2/edge_manipulation.cpp}

The member functions \link Arrangement_on_surface_2::modify_vertex()
`modify_vertex()`\endlink and \link
Arrangement_on_surface_2::modify_edge() `modify_edge()`\endlink modify
the geometric mappings of existing features of the arrangement. The
call \link Arrangement_on_surface_2::modify_vertex
`arr.modify_vertex(v, p)`\endlink accepts a handle to a vertex \f$v\f$
and a reference to a point \f$p\f$, and sets \f$p\f$ to be the point
associated with the vertex \f$v\f$. The call \link
Arrangement_on_surface_2::modify_edge() `arr.modify_edge(he,
c)`\endlink accepts a handle to one of the two halfedges that
represent an edge \f$e\f$ and a reference to a curve \f$c\f$, and sets
\f$c\f$ to be the \f$x\f$-monotone curve associated with
\f$e\f$. (Note that both halfedges are modified; that is, both
expressions `e->curve()` and `e->twin()->curve()` evaluate to
\f$c\f$ after the modification.)  These functions have preconditions
that \f$p\f$ is geometrically equivalent to `v->point()` and \f$c\f$
is equivalent to `e->curve()`, respectively.\cgalFootnote{Roughly
speaking, two curves are equivalent iff they have the same graph. In
Section \ref aos_sssec-geom_traits-concepts_basic we give a formal
definition of curves and curve equivalence.} If these preconditions
are not met, the corresponding operation may invalidate the structure
of the arrangement. At first glance it may seem as if these two
functions are of little use. However, you should keep in mind that
there may be extraneous data (probably non-geometric) associated with
the point objects or with the curve objects, as defined by the traits
class. With these two functions you can modify this data; see more
details in Section \ref arr_sssec_tr_data_decorators. In addition, you can use
these functions to replace a geometric object (a point or a curve)
with an equivalent object that has a more compact representation. For
example, if we use some simple rational-number type to represent the
point coordinates, we can replace the point \f$(\frac{20}{40},
\frac{99}{33})\f$ associated with some vertex \f$v\f$ with an
equivalent point with normalized coordinates, namely \f$(\frac{1}{2},
3)\f$.

<!-- ----------------------------------------------------------------------- -->
\subsection arr_sssecadv_insert Advanced Insertion Functions
<!-- ----------------------------------------------------------------------- -->

\cgalAdvancedBegin

<table border="0" cellspacing="10">
<tr>
<td>
\image html pred_around_vertex.png
\image latex pred_around_vertex.png
</td>
<td>

Assume that the specialized insertion function \link
Arrangement_on_surface_2::insert_from_left_vertex()
`insert_from_left_vertex(c, v)`\endlink is given a curve \f$c\f$, the
left endpoint of which is already associated with a non-isolated
vertex \f$v\f$. Namely, \f$v\f$ has already several incident
halfedges. It is necessary in this case to locate the exact place for
the new halfedge mapped to the inserted new curve \f$c\f$ in the
circular list of halfedges incident to \f$v\f$. More precisely, in
order to complete the insertion, it is necessary to locate the
halfedge \f$e_{\mathrm{pred}}\f$ directed toward \f$v\f$, such that
\f$c\f$ is located between the curves associated with
\f$e_{\mathrm{pred}}\f$ and the next halfedge in the clockwise order
in the circular list of halfedges around \f$v\f$; see
\cgalFigureRef{aos_fig-insert}. This search may take \cgalBigO{d} time,
where \f$d\f$ is the degree of the vertex \f$v\f$. \cgalFootnote{We
can store the handles to the halfedges incident to \f$v\f$ in an efficient
search structure to obtain \cgalBigO{\log d} access time. However, as
\f$d\f$ is usually very small, this may lead to a waste of storage
space without a meaningful improvement in running time in practice.}
However, if the halfedge \f$e_{\mathrm{pred}}\f$ is known in advance,
the insertion can be carried out in constant time, and without
performing any geometric comparisons.  </td> </tr> </table>

The `Arrangement_2` class provides advanced versions of the
specialized insertion functions for a curve \f$c\f$, namely, \link
Arrangement_on_surface_2::insert_from_left_vertex()
`insert_from_left_vertex(c, he_pred)`\endlink and \link
Arrangement_on_surface_2::insert_from_right_vertex()
`insert_from_right_vertex(c, he_pred)`\endlink.  These functions
accept a halfedge \f$e_{\mathrm{pred}}\f$ as specified above, instead
of a handle to a vertex \f$v\f$. They are more efficient, as they take
constant time and do not perform any geometric operations. Thus, you
should use them when the halfedge \f$e_{\mathrm{pred}}\f$ is known. In
cases where the vertex \f$v\f$ is isolated or the predecessor halfedge
for the newly inserted curve is not known, the simpler versions of
these insertion functions should be used. Similarly, the member
function \link Arrangement_on_surface_2::insert_at_vertices()
`insert_at_vertices()`\endlink is overloaded with two additional
versions as follows. One accepts two handles to the two predecessor
halfedges around the two vertices \f$v_1\f$ and \f$v_2\f$,
respectively, that correspond to the curve endpoints. The other one
accepts a handle to one vertex and a handle to the predecessor
halfedge around the other vertex.

<!-- ----------------------------------------------------------------------- -->
\cgalFigureBegin{aos_fig-special_edge_insertion,special_edge_insertion.png}
An arrangement of line segments, as constructed in
\ref Arrangement_on_surface_2/special_edge_insertion.cpp. Note that
\f$p_0\f$ is initially inserted as an isolated point and later on
connected to the other four vertices.
\cgalFigureEnd
<!-- ----------------------------------------------------------------------- -->

The following program shows how to construct the arrangement
depicted in \cgalFigureRef{aos_fig-special_edge_insertion} using the specialized
insertion functions that accept predecessor halfedges:

\cgalExample{Arrangement_on_surface_2/special_edge_insertion.cpp}

It is possible to perform even more refined operations on an
`Arrangement_2` object given specific topological information.
As most of these operations are very fragile and perform no precondition
testing on their input in order to gain efficiency, they are not included
in the public interface of the arrangement class. Instead, the
`Arr_accessor<Arrangement>` class allows access to these internal
arrangement operations; see more details in the Reference Manual.
\cgalAdvancedEnd

<!-- ======================================================================= -->
\section arr_secqueries Issuing Queries on an Arrangement
<!-- ======================================================================= -->

One of the most useful query types defined on arrangements is the
<em>point-location</em> query: Given a point, find the arrangement
cell that contains it. Typically, the result of a point-location query
is one of the arrangement faces, but in degenerate situations the
query point can lie on an edge, or it may coincide with a vertex.

Point-location queries are common in many applications, and also
play an important role in the incremental construction of arrangements
(and more specifically in the free insertion-functions described in
Section \ref arr_secgl_funcs). Therefore, it is crucial to have the
ability to answer such queries effectively.

<!-- ----------------------------------------------------------------------- -->
\subsection arr_ssecpl Point-Location Queries
<!-- ----------------------------------------------------------------------- -->

Recall that the arrangement representation is decoupled from the
geometric algorithms that operate on it. Thus, the `Arrangement_2`
class template does not support point-location queries directly.
Instead, the \ref PkgArrangementOnSurface2 package provides a set of
class templates that are capable of answering such queries; all are
models of the concept `AosPointLocation_2`. Each model employs
a different algorithm or <em>strategy</em> for answering queries.  A
model of this concept must define the \link
AosPointLocation_2::locate() `locate()`\endlink member
function, which accepts an input query-point and returns a polymorphic
object representing the arrangement cell that contains this point.
The returned object is of type
`Arr_point_location_result<Arrangement_2>::%Type`, which is a
discriminated union container of the bounded types \link
Arrangement_on_surface_2::Vertex_const_handle
`Vertex_const_handle`\endlink, \link
Arrangement_on_surface_2::Halfedge_const_handle
`Halfedge_const_handle`\endlink, or \link
Arrangement_on_surface_2::Face_const_handle
`Face_const_handle`\endlink. Depending on whether the query point is
located inside a face, lies on an edge, or coincides with a vertex,
the appropriate handle can be obtained with <em>value retrieval</em>
by `std::get` as demonstrated in the example below.

Note that the handles returned by the \link
AosPointLocation_2::locate() `locate()`\endlink functions are
non-mutable (`const`). If necessary, such handles may be cast to
mutable handles using the
`Arrangement_on_surface_2::non_const_handle()` methods.

An object `pl` of any point-location class must be attached to an
`Arrangement_2` object `arr` before it is used to answer
point-location queries on `arr`. This attachment can be performed
when `pl` is constructed or at a later time using the
`pl.init(arr)` call.

The function template `locate_point()` listed below accepts a
point-location object, the type of which is a model of the
`AosPointLocation_2` concept, and a query point. The function
template issues a point-location query for the given point, and prints
out the result.  It is defined in the header file
`point_location_utils.h`.

\anchor lst_pl
\code
template <typename PointLocation>
void locate_point(const PointLocation& pl,
                  const typename PointLocation::Arrangement_2::Point_2& q) {
  using Point_location = PointLocation;
  using Arrangement_2 = typename Point_location::Arrangement_2;
  typename CGAL::Arr_point_location_result<Arrangement_2>::Type obj =
    pl.locate(q);

  // Print the result.
  print_point_location<Arrangement_2>(q, obj);
}
\endcode

The function template `locate_point()` calls an instance of the
function template `print_point_location()`, which inserts the
result of the query into the standard output-stream. It is listed
below, and defined in the header file `point_location_utils.h`.
Observe how the function `std::get()` is used to cast the
resulting object into a handle to an arrangement feature. The
point-location object `pl` is assumed to be already attached
to an arrangement.

\code
template <typename Arrangement_>
void print_point_location
(const typename PointLocation::Arrangement_::Point_2& q
 typename CGAL::Arr_point_location_result<Arrangement_>::Type obj) {
  using Arrangement_2 = Arrangement_;

  using Vertex_const_handle = typename Arrangement_2::Vertex_const_handle;
  using Halfedge_const_handle = typename Arrangement_2::Halfedge_const_handle;
  using Face_const_handle = typename Arrangement_2::Face_const_handle;

  const Vertex_const_handle*   v;
  const Halfedge_const_handle* e;
  const Face_const_handle*     f;

  std::cout << "The point (" << q << ") is located ";
  if (f = std::get_if<Face_const_handle>(&obj)) // located inside a face
    std::cout << "inside "
              << (((*f)->is_unbounded()) ? "the unbounded" : "a bounded")
              << " face.\n";
  else if (e = std::get_if<Halfedge_const_handle>(&obj)) // located on an edge
    std::cout << "on an edge: " << (*e)->curve() << std::endl;
  else if (v = std::get_if<Vertex_const_handle>(&obj)) // located on a vertex
    std::cout << "on " << (((*v)->is_isolated()) ? "an isolated" : "a")
              << " vertex: " << (*v)->point() << std::endl;
  else CGAL_error_msg("Invalid object.");
}
\endcode

<!-- ----------------------------------------------------------------------- -->
\subsection aos_sssec-pl_strategy Choosing a Point-Location Strategy
<!-- ----------------------------------------------------------------------- -->

Each of the various point-location class templates employs a different
algorithm or <em>strategy</em>\cgalFootnote{The term <em>strategy</em>
is borrowed from the design-pattern taxonomy \cgalCite{cgal:ghjv-dpero-95},
Chapter 5. A <em>strategy</em> provides the means to define a family of
algorithms, each implemented by a separate class. All classes that implement
the various algorithms are made interchangeable, letting the algorithm in use
vary according to the user choice.} for answering queries:
<UL>
<LI> `Arr_naive_point_location<Arrangement>` employs the
  <em>naive</em> strategy. It locates the query point naively,
  exhaustively scanning all arrangement cells.

<LI> `Arr_walk_along_line_point_location<Arrangement>` employs
  the <em>walk-along-a-line</em> (or <em>walk</em> for short) strategy.
  It simulates a traversal, in reverse order, along an imaginary
  vertical ray emanating from the query point. It starts from the
  unbounded face of the arrangement and moves downward toward the
  query point until it locates the arrangement cell containing it.

<LI>`Arr_landmarks_point_location<Arrangement,Generator>` uses a set
  of <em>landmark</em> points, the location of which in the
  arrangement is known. It employs the <em>landmark</em>
  strategy. Given a query point, it uses a nearest-neighbor
  search-structure (a <span class="textsc">Kd</span>-tree is used by
  default) to find the nearest landmark, and then traverses the
  straight-line segment connecting this landmark to the query point.

  There are various ways to select the landmark set in the
  arrangement. The selection is governed by the `Generator`
  template parameter. The default generator class, namely
  `Arr_landmarks_vertices_generator`, selects all the vertices of
  the attached arrangement as landmarks. Additional generators that
  select the set in other ways, such as by sampling random
  points or choosing points on a grid, are also available; see the
  Reference Manual for more details.

  The arrangement attached to the landmark strategy must be either (i)
  an instance of the `Arrangement_2<GeomTraits,Dcel>` class template,
  where the `GeomTraits` parameter is substituted by a geometry-traits
  class that models the `AosLandmarkTraits_2` concept, or (ii) an
  instance of the `Arrangement_on_surface_2<GeomTraits,TopolTraits>`
  class template, where the `GeomTraits` is similarly substituted;
  see Section \ref aos_sssec-tr_landmarks_concept for details about
  this concept. Most traits classes included in the \ref
  PkgArrangementOnSurface2 package are models of this refined concept.

<LI>`Arr_trapezoid_ric_point_location<Arrangement>` implements an
  improved variant of Mulmuley's point-location algorithm
  \cgalCite{m-fppa-90}; see also \cgalCite{bkos-cgaa-00}, Chapter 6.
  The (expected) query-time is logarithmic in the size of the
  arrangement. The arrangement faces are decomposed into simpler cells
  each of constant complexity, known as <em>pseudo trapezoids</em>,
  and a search structure (a directed acyclic graph) is constructed on
  top of these cells, facilitating the search of the pseudo trapezoid
  (hence the arrangement cell) containing a query point in expected
  logarithmic time. The trapezoidal map and the search structure are
  built by a randomized incremental construction algorithm (RIC).

<LI> `Arr_triangulation_point_location<Arrangement>` uses a
  constrained triangulation, provided by the \ref PkgTriangulation2
  package, as a search structure. Every time the arrangement is
  modified the constrained triangulation search-structure is
  reconstructed from scratch, where the edges of the arrangement are
  set to be the constrained edges of the triangulation. This strategy
  is inefficient (especially when the number of modifications applied
  to the arrangement is high) and provided only for educational
  purposes.

</UL>

The first two strategies do not require any extra data. The class
templates that implement them store a pointer to an arrangement object
and operate directly on it. Attaching such point-location objects to
an existing arrangement has virtually no running-time cost at all, but
the query time is linear in the size of the arrangement (the
performance of the walk strategy is much better in practice, but its
worst-case performance is linear). Using these strategies is therefore
recommended only when a relatively small number of point-location
queries are issued by the application, or when the arrangement is
constantly changing (That is, changes in the arrangement structure are
more frequent than point-location queries).  On the other hand, the
landmark and the trapezoid RIC strategies require auxiliary data
structures on top of the arrangement structure, which they need to
construct once they are attached to an arrangement object and need to
keep up-to-date as this arrangement changes.

As mentioned above, the triangulation strategy is provided only for
educational purposes, and thus we do not elaborate on this strategy.
The data structure needed by the landmark and the trapezoidal map RIC
strategies can be constructed in \cgalBigO{N \log N} time, where \f$N\f$
is the overall number of edges in the arrangement, but the constant
hidden in the \cgalBigO{~} notation for the trapezoidal map RIC strategy
is much larger. Thus, construction needed by the landmark algorithm is
in practice significantly faster than the construction needed by the
trapezoidal map RIC strategy. In addition, although both resulting
data structures are asymptotically linear in size, the actual amount
of memory consumed by the landmark algorithm is typically smaller than
to the amount used by the trapezoidal map RIC algorithm, due to the
space-efficient <span class="textsc">Kd</span>-tree used by the
landmark algorithm as the nearest-neighbor search-structure.  The
trapezoidal map RIC algorithm has expected logarithmic query time,
while the query time for the landmark algorithm may be as large as
linear. In practice however, the query times of both strategies are
competitive. For a detailed experimental comparison see
\cgalCite{cgal:hh-eplca-05}.

Updating the auxiliary data structures of the trapezoidal map RIC
algorithm is done very efficiently. On the other hand, updating the
nearest-neighbor search-structure of the landmark algorithm may
consume significant time when the arrangement changes frequently,
especially when a <span class="textsc">Kd</span>-tree is used, as it
must be rebuilt each time the arrangement changes. It is therefore
recommended that the `Arr_landmarks_point_location` class template be
used when the application frequently issues point-location queries on
an arrangement that only seldom changes. If the arrangement is more
dynamic and is frequently going through changes, the
`Arr_trapezoid_ric_point_location` class template should be the
selected point-location strategy.

<!-- ----------------------------------------------------------------------- -->
\cgalFigureBegin{aos_fig-point_location,point_location.png}
The arrangement of line segments, as constructed in \ref
Arrangement_on_surface_2/point_location.cpp, \ref
Arrangement_on_surface_2/vertical_ray_shooting.cpp, and \ref
Arrangement_on_surface_2/batched_point_location.cpp. The arrangement
vertices are drawn as small rings, while the query points \f$q_1,
\ldots, q_6\f$ are drawn as crosses.
\cgalFigureEnd
<!-- ----------------------------------------------------------------------- -->

The program listed below constructs a simple arrangement of five line
segments that form a pentagonal face, with a single isolated
vertex in its interior, as depicted in \cgalFigureRef{aos_fig-point_location}.
Notice that we use the same arrangement structure in the next
three example programs. The arrangement construction is performed by
the function `construct_segment_arr()` defined in the header file
`point_location_utils.h`. (Its listing is omitted here.) The
program employs the naive and the landmark strategies to issue
several point-location queries on this arrangement.

\cgalExample{Arrangement_on_surface_2/point_location.cpp}

Note that the program uses the `locate_point()` function template
to locate a point and nicely print the result of each query; see
\ref lst_pl "code example" in Section \ref arr_ssecpl.

<!-- ----------------------------------------------------------------------- -->
\subsection arr_ssecray_shoot Vertical Ray Shooting
<!-- ----------------------------------------------------------------------- -->

Another query frequently issued on arrangements is the vertical
ray-shooting query: Given a query point, which arrangement cell
is encounter by a vertical ray shot upward (or downward) from this
point? In the general case the ray hits an edge, but it is possible
that it hits a vertex, or that the arrangement does not have any
vertex or edge lying directly above (or below) the query point.

All point-location classes listed in the previous section are also
models of the `AosVerticalRayShoot_2` concept. That is, they
all have member functions called `ray_shoot_up(q)` and
`ray_shoot_down(q)` that accept a query point \f$q\f$. These functions
output a polymorphic object of type
`Arr_point_location_result<Arrangement_2>::%Type`, which is a
discriminated union container of the bounded types \link
Arrangement_on_surface_2::Vertex_const_handle
`Vertex_const_handle`\endlink, \link
Arrangement_on_surface_2::Halfedge_const_handle
`Halfedge_const_handle`\endlink, or \link
Arrangement_on_surface_2::Face_const_handle
`Face_const_handle`\endlink. The latter type is used for the unbounded
face of the arrangement, in case there is no edge or vertex lying
directly above (or below) \f$q\f$.

The function template `vertical_ray_shooting_query()` listed
below accepts a vertical ray-shooting object, the type of which
models the `AosVerticalRayShoot_2` concept. It exports
the result of the upward vertical ray-shooting operation from a
given query point to the standard output-stream. The ray-shooting
object `vrs` is assumed to be already attached to an arrangement.
The function template is defined in the header file
`point_location_utils.h.`

\code
template <typename VerticalRayShooting>
void shoot_vertical_ray(const RayShoot& vrs,
                        const typename
                        VerticalRayShooting::Arrangement_2::Point_2& q) {
  using Vertical_ray_shooting = VerticalRayShooting;

  // Perform the point-location query.
  typename Vertical_ray_shooting::result_type obj = vrs.ray_shoot_up(q);

  // Print the result.
  using Arrangement_2 = typename Vertical_ray_shooting::Arrangement_2;
  using Vertex_const_handle = typename Arrangement_2::Vertex_const_handle;
  using Halfedge_const_handle = typename Arrangement_2::Halfedge_const_handle;
  using Face_const_handle = typename Arrangement_2::Face_const_handle;

  const Vertex_const_handle* v;
  const Halfedge_const_handle* e;
  const Face_const_handle* f;

  std::cout << "Shooting up from (" << q << ") : ";
  if (v = std::get_if<Vertex_const_handle>(&obj))         // we hit a vertex
    std::cout << "hit " << (((*v)->is_isolated()) ? "an isolated" : "a")
              << " vertex: " << (*v)->point() << std::endl;
  else if (e = std::get_if<Halfedge_const_handle>(&obj))  // we hit an edge
    std::cout << "hit an edge: " << (*e)->curve() << std::endl;
  else if (f = std::get_if<Face_const_handle>(&obj)) {    // we hit nothing
    CGAL_assertion((*f)->is_unbounded());
    std::cout << "hit nothing.\n";
  }
  else CGAL_error();
}
\endcode

The program below uses the function template listed above to
perform vertical ray-shooting queries on an arrangement. The
arrangement and the query points are exactly the same as in
\ref Arrangement_on_surface_2/point_location.cpp; see
\cgalFigureRef{aos_fig-point_location}.
\cgalExample{Arrangement_on_surface_2/vertical_ray_shooting.cpp}

<!-- ----------------------------------------------------------------------- -->
\subsection arr_ssecbatched_pl Batched Point-Location
<!-- ----------------------------------------------------------------------- -->

Suppose that at a given moment our application has to issue a
relatively large number \f$m\f$ of point-location queries on a
specific arrangement object. Naturally, It is possible to define a
point-location object and use it to issue separate queries on the
arrangement. However, as explained in Section \ref arr_ssecpl choosing
a simple point-location strategy (either the naive or the walk
strategy) means inefficient queries, while the more sophisticated
strategies need to construct auxiliary structures that incur
considerable overhead in running time.

Alternatively, the <em>2D Arrangement</em> package includes a free
`locate()` function that accepts an arrangement and a range of query
points as its input and sweeps through the arrangement to locate all
query points in one pass. The function outputs the query results as
pairs, where each pair consists of a query point and a discriminated
union container, which represents the cell containing the point; see
Section \ref arr_ssecpl. The output pairs are sorted in increasing
\f$xy\f$-lexicographical order of the query point.

The batched point-location operation is carried out by sweeping the
arrangement. Thus, it takes \cgalBigO{(m+N)\log{(m+N)}} time, where
\f$N\f$ is the number of edges in the arrangement. Issuing separate
queries exploiting a point-location strategy with logarithmic query
time per query, such as the trapezoidal map RIC strategy (see Section
\ref aos_sssec-pl_strategy), is asymptotically more efficient. However,
experiments show that when the number \f$m\f$ of point-location
queries is of the same order of magnitude as \f$N\f$, the batched
point-location operation is more efficient in practice.  One of the
reasons for the inferior performance of the alternative
(asymptotically faster) procedures is the necessity to construct and
maintain complex additional data structures.

The program below issues a batched point-location query, which
is essentially equivalent to the six separate queries performed in
\ref Arrangement_on_surface_2/point_location.cpp; see Section
\ref arr_ssecpl.
\cgalExample{Arrangement_on_surface_2/batched_point_location.cpp}

<!-- ======================================================================= -->
\section arr_secgl_funcs Free Functions
<!-- ======================================================================= -->

The `Arrangement_on_surface_2` class template is used to represent
subdivisions of two-dimensional surfaces induced by curves that lie on
such surfaces. Its interface is minimal in the sense that the member
functions hardly perform any geometric operations. In this section we
explain how to utilize the free functions that enhance that set of
operations on arrangements. The implementation of these operations
typically require non-trivial geometric algorithms, and occasionally
incurs additional requirements on the geometry traits class; the
implementation of many of the operations is based on two frameworks,
namely the <em>surface sweep</em> and the <em>zone construction</em>.
These operations accepts \f$x\f$-monotone curves; thus, the
geometry-traits class used by the arrangements passed as input to, or
obtained as output from, these operations must be a model of the
`AosXMonotoneTraits_2` concept; see Section \ref
aos_sec-geom_traits for the precise definition of this concept. It
defines the minimal set of geometric primitives, among other things,
required to perform the algorithms of the surface-sweep and
zone-construction frameworks.

<!-- ----------------------------------------------------------------------- -->
\subsection arr_ssec_zone The Zone Construction Algorithm
<!-- ----------------------------------------------------------------------- -->

Given an arrangement of curves \f$\mathcal{A} =
\mathcal{A}(\mathcal{C})\f$ embedded in a two-dimensional surface, the
<em>zone</em> of an additional curve \f$\gamma \notin \mathcal{C}\f$
in \f$\mathcal{A}\f$ is the union of the features of
\f$\mathcal{A}\f$, whose closure is intersected by \f$\gamma\f$.  The
complexity of the zone is defined as the sum of the complexities of
its constituents. (Notice that some vertices are counted multiple
times.)  The zone of a curve \f$\gamma\f$ is computed by locating the
left endpoint of \f$\gamma\f$ in the arrangement and then "walking"'
along the curve towards the right endpoint, keeping track of the
vertices, edges, and faces crossed on the way. The \ref
PkgArrangementOnSurface2 package offers a generic implementation of an
algorithm that computes the zone. It is used to implement a set of
operations that incrementally construct arrangements induced by sets
of curves that lie in two-dimensional surfaces. For simplicity,
however, we continue to consider arrangements embedded in the plane.

<!-- ----------------------------------------------------------------------- -->
<!-- \subsection arr_ssecinc_insert Incremental Insertion Functions -->
<!-- ----------------------------------------------------------------------- -->

Section \ref aos_ssec-basic-arr_class explains how to construct
arrangements of \f$x\f$-monotone curves that are pairwise disjoint in
their interior when the location of the segment endpoints in the
arrangement is known. Here we relax this constraint, and allow the
location of the inserted \f$x\f$-monotone curve endpoints to be
unknown at the time of insertion.

<!-- ----------------------------------------------------------------------- -->
\subsubsection arr_sssecinsert_non_x Inserting Pairwise Disjoint Curves
<!-- ----------------------------------------------------------------------- -->

We retain, for the moment, the requirement that the interior of the
inserted curve is disjoint from all existing arrangement edges and
vertices.

The call \link CGAL::insert_non_intersecting_curve<>
`insert_non_intersecting_curve(arr, c, pl)`\endlink inserts the
\f$x\f$-monotone curve \f$c\f$ into the arrangement `arr`, with the
precondition that the interior of \f$c\f$ is disjoint from all
existing edges and vertices of `arr`. The third argument `pl` is a
point-location object attached to the arrangement; it is used to
locate both endpoints of \f$c\f$ in the arrangement. Each endpoint is
expected to either coincide with an existing vertex or lie inside a
face.  It is possible to invoke one of the specialized insertion
functions (see Section \ref aos_ssec-basic-arr_class), based on the
query results, and insert \f$c\f$ at its proper
location.\cgalFootnote{The \cgalFootnoteCode{CGAL::insert_non_intersecting_curve<>()}
function template, as all other functions reviewed in this section, is
parameterized by an arrangement type and a point-location type (The
latter must be substituted by a model of the
`AosPointLocation_2` concept).} The insertion operation thus
hardly requires any geometric operations on top of the ones needed to
answer the point-location queries. Moreover, it is sufficient that the
traits class that substitutes the `Traits` template parameter of the
`Arrangement_2<Traits,Dcel>` class template when the latter is
instantiated models the concept `AosBasicTraits_2` concept
(and the concept `AosLandmarkTraits_2` if the landmark
point-location strategy is used), and does not have to support the
computation of intersection points between curves. This implies that
using a kernel that provides exact geometric predicates, but
potentially inexact geometric constructions due to round-off errors, is
still sufficient.

The free-function template `CGAL::insert_non_intersecting_curve<>(arr,
c, pl)` is overloaded. There is a variant that instead of accepting a
user-defined point-location object, it constructs a local object of
the walk point-location type, namely, an instance of the
`Arr_walk_along_line_point_location` class template, and uses it to
insert the curve.

<!-- ----------------------------------------------------------------------- -->
\subsubsection arr_sssecinsert_x_mon Inserting X-monotone Curves
<!-- ----------------------------------------------------------------------- -->

The time it takes to insert a curve \f$c\f$ using the
`insert_non_intersecting_curve()` function template is the sum of the
time is takes to locate the two endpoints of \f$c\f$ and the time is
takes to find the exact place for the new two halfedges mapped to
\f$c\f$ in the circular list of halfedges incident to the two vertices
mapped to the endpoints of \f$c\f$, respectively. This makes the
function relatively efficient; however, its preconditions on the input
curves are still rather restricting. Let us assume that the traits
class that substitutes the `Traits` template parameter of the
`Arrangement_2<Traits,Dcel>` class template models the refined
`AosXMonotoneTraits_2` concept and supports curve intersection
computations; see Section \ref aos_sec-geom_traits for the exact
details. Given an \f$x\f$-monotone curve, it is sufficient to locate
its left endpoint in the arrangement and to trace its <em>zone</em>
(see Section \ref arr_ssec_zone) until the right endpoint is
reached. Each time the new curve \f$c\f$ crosses an existing vertex or
edge, the curve is split into subcurves (in the latter case, we have
to split the curve associated with the existing halfedge as well) and
new edges are associated with the resulting subcurves. Recall that an
edge is represented by a pair of twin halfedges, so we split it into
two halfedge pairs.

The call \link CGAL::insert<>() `insert(arr, c, pl)`\endlink performs
this insertion operation. The `CGAL::insert<>()` function template
accepts an \f$x\f$-monotone curve \f$c\f$, which may intersect some of
the curves already in the arrangement `arr`, and inserts it into the
arrangement by computing its zone.  Users may supply a point-location
object `pl` or use the default walk point-location strategy (namely,
the variant `CGAL::insert<>(arr, c)` is also available). The
running-time of this insertion function is proportional to the
complexity of the zone of the curve \f$c\f$.

<!-- ----------------------------------------------------------------------- -->
\cgalAdvancedBegin In some cases users may have a prior knowledge of
the location of the left endpoint of the \f$x\f$-monotone curve
\f$c\f$ they wish to insert, so they can perform the insertion without
issuing any point-location queries. This can be done by calling the
free function template `CGAL::insert<>(arr, c, obj)`, where `obj` is a
polymorphic object of type
`Arr_point_location_result<Arrangement_2>::%Type` that represents the
location of \f$c\f$s left endpoint in the arrangement.  It is a
discriminated union container of the bounded types \link
Arrangement_on_surface_2::Vertex_const_handle
`Vertex_const_handle`\endlink, \link
Arrangement_on_surface_2::Halfedge_const_handle
`Halfedge_const_handle`\endlink, or \link
Arrangement_on_surface_2::Face_const_handle
`Face_const_handle`\endlink; see also Section \ref arr_ssecpl.
\cgalAdvancedEnd
<!-- ----------------------------------------------------------------------- -->

<!-- ----------------------------------------------------------------------- -->
\subsubsection aos_ssec-insert_gen Inserting General Curves
<!-- ----------------------------------------------------------------------- -->

So far, all the examples have constructed arrangements of line
segments, where the `Arrangement_2` template was instantiated with an
instance of the `Arr_segment_traits_2` class template. In this case,
the restriction that `CGAL::insert<>()` requires an \f$x\f$-monotone
is irrelevant, as all line segments are \f$x\f$-monotone. (Note that
we always deal with <em>weakly</em> \f$x\f$-monotone curves, and we
consider vertical line-segments to be weakly \f$x\f$-monotone).

Consider an arrangement of circles. A circle is obviously not
\f$x\f$-monotone, so `CGAL::insert<>()` cannot be used in this
case.\cgalFootnote{A key operation performed by \cgalFootnoteCode{CGAL::insert<>()} is
to locate the left endpoint of the curve in the arrangement. A circle,
however, does not have any endpoints!} , it is necessary to subdivide
each circle into two \f$x\f$-monotone circular arcs, namely, its upper
half and its lower half, and to insert the two individual
\f$x\f$-monotone arcs.

The free function template `CGAL::insert<>()` is overloaded. It is
possible to another version of this function and pass a curve that is
not necessarily \f$x\f$-monotone, but this is subject to an important
condition. Consider the call \link CGAL::insert<>() `insert(arr, c,
pl)`\endlink, where \f$c\f$ is not necessarily \f$x\f$-monotone. In
this case the type of `arr` must be an instance of the
`Arrangement_2<Traits, Dcel>` class template, where the `Traits`
template parameter is substituted by a traits class that models the
concept `AosTraits_2`, which refines the
`AosXMonotoneTraits_2` concept. It has to define an additional
\link AosTraits_2::Curve_2 `Curve_2`\endlink type, which may
differ from the \link AosBasicTraits_2::X_monotone_curve_2
`X_monotone_curve_2`\endlink type.  It also has to support the
subdivision of curves of this new type into \f$x\f$-monotone curves
and possibly singular points; see the exact details in Section \ref
aos_sec-geom_traits. The `CGAL::insert<>(arr, c, pl)` function
performs the insertion of the curve \f$c\f$ that does not need to be
\f$x\f$-monotone, into the arrangement by subdividing it into
\f$x\f$-monotone subcurves and inserting all individual
\f$x\f$-monotone subcurves. Users may supply a point-location object
`pl`, or use the default walk point-location strategy by calling
`CGAL::insert<>(arr, c)`.

<!-- ----------------------------------------------------------------------- -->
\subsubsection arr_sssecinsert_point Inserting Points
<!-- ----------------------------------------------------------------------- -->

The `Arrangement_2` class template has a member function that inserts
a point as an isolated vertex in a given face. The free function
template `CGAL::insert_point<>(arr, p, pl)` inserts a vertex that
corresponds to the point \f$p\f$ into `arr` at an arbitrary
location. It uses the point-location object `pl` to locate the point
in the arrangement (by default, the walk point-location strategy is
used), and acts according to the result as follows:

<UL>

<LI>If \f$p\f$ is located inside a face, it is inserted as an
isolated vertex inside this face.

<LI>If \f$p\f$ lies on an edge, the edge is split to create a
vertex associated with \f$p\f$.

<LI>Otherwise,\f$p\f$  coincides with an existing vertex and
no further actions are needed.
</UL>

In all cases, the function returns a handle to the vertex
associated with \f$p\f$.

The type of `arr` must be and instance of the `Arrangement_2` class
template instantiated with a traits class that models the
`AosXMonotoneTraits_2` concept, as the insertion operation may
involve the splitting of curves.

<!-- ----------------------------------------------------------------------- -->
\subsubsection arr_sssecinsert_ex Inserting Intersecting Line Segments (code example)
<!-- ----------------------------------------------------------------------- -->

<!-- ----------------------------------------------------------------------- -->
\cgalFigureBegin{aos_fig-incremental_insertion,incremental_insertion.png}
An arrangement of five intersecting line segments, as constructed in
\ref Arrangement_on_surface_2/incremental_insertion.cpp and
\ref Arrangement_on_surface_2/aggregated_insertion.cpp. The
segment endpoints are marked by black disks and the arrangement
vertices that correspond to intersection points are marked by
circles. The query point \f$q\f$ is marked with a cross and the face
that contains it is shaded.
\cgalFigureEnd
<!-- ----------------------------------------------------------------------- -->

The program below constructs an arrangement of five intersecting
line-segments \f$s_1, \ldots, s_5\f$. It is known that \f$s_1\f$ and
\f$s_2\f$ do not intersect, so
`CGAL::insert_non_intersecting_curve<>()` is used to insert them into
the empty arrangement. The rest of the segments are inserted using
`CGAL::insert<>()`. Using a kernel that constructs geometric objects
in an inexact manner (due to round-off errors) may yield a program that
computes incorrect results and crashes from time to time. This is
avoided by using a kernel that provides exact geometric-object
constructions as well as exact geometric-predicate evaluations. The
header file `arr_exact_construction_segments.h`, just like the header
file `arr_inexact_construction_segments.h`, contains the definitions
for arrangements of line segments.  Unlike the latter, it uses a
kernel suitable for arrangements induced by curves that intersect each
other, namely a kernel that is exact always. Note that we alternately
use the naive point-location strategy, given explicitly to the
insertion functions, and the default walk point-location strategy.

The resulting arrangement is depicted in
\cgalFigureRef{aos_fig-incremental_insertion}, where the vertices that
correspond to segment endpoints are drawn as dark discs, and the
vertices that correspond to intersection points are drawn as
circles. It consists of 13 vertices, 16 edges, and 5 faces. We also
perform a point-location query on the resulting arrangement. The query
point \f$q\f$ is drawn as a plus sign. The face that contains it is
drawn with a shaded texture. The program calls an instance of the
function template `print_arrangement_size()`, which prints
quantitative measures of the arrangement; see \ref lst_paz
"code example" for its listing in Section \ref aos_ssec-basic-arr_class.

\cgalExample{Arrangement_on_surface_2/incremental_insertion.cpp}

<!-- ----------------------------------------------------------------------- -->
\subsection arr_ssseczone Other Zone Related Functions
<!-- ----------------------------------------------------------------------- -->

In this section we have described so far free functions that insert
curves and points into a given arrangement. Now we describe functions
that do not change the arrangement at all; nevertheless, they are
closely related to the incremental insertion functions, as they also
use the zone framework.

The free function template `%CGAL::do_intersect<>(arr, c, pl)` checks
whether the given query curve \f$c\f$ intersects the curves and points
of an existing arrangement `arr`. If \f$c\f$ is not \f$x\f$-monotone
(that is, it is of type \link AosTraits_2::Curve_2
`Curve_2`\endlink) the curve is subdivided into \f$x\f$-monotone
subcurves and isolated points. Each \f$x\f$-monotone curve (or point)
is checked for intersection in turn using the zone framework. For
points we simply apply point-location. Given an \f$x\f$-monotone
curve, first its left endpoint is located; then, its zone is computed
starting from its left endpoint location. The zone computation
terminates when an intersection with an arrangement curve or point is
found or when the right endpoint is reached.  A given point-location
object is used for locating the left endpoint of the curve in the
existing arrangement. There is a variant that instead of accepting a
user-defined point-location object, it constructs a local object of
the walk point-location type, namely, an instance of the
`Arr_walk_along_line_point_location` class template, and uses it to
locate the endpoint. If the given curve is \f$x\f$-monotone then the
traits type must model the `AosXMonotoneTraits_2` concept. If
the curve is not \f$x\f$-monotone then the traits type must model the
`AosTraits_2` concept.

The `CGAL::zone<>(arr, c, oi, pl)` function template computes the zone
of a given \f$x\f$-monotone curve in a given arrangement. More
precisely, it outputs all the arrangement cells (namely, vertices,
edges, and faces) that the input \f$x\f$-monotone curve \f$C\f$
intersects in the order they are discovered when traversing the curve
from left to right.  The function uses a given point-location object
to locate the left endpoint of the given curve. There is a variant
that instead of accepting a user-defined point-location object, it
constructs a local object of the walk point-location type, namely, an
instance of the `Arr_walk_along_line_point_location` class template,
and uses it to locate the endpoint. The traits type must model the
`AosXMonotoneTraits_2` concept.

<!-- ----------------------------------------------------------------------- -->
\subsection arr_ssec_sweep The Surface-Sweep Algorithm
<!-- ----------------------------------------------------------------------- -->

The famous plane-sweep algorithm introduced by Bentley and Ottmann was
originally formulated for sets of line segments in the plane. The \ref
PkgSurfaceSweep2 package offers a generic implementation of a
generalized version of the original plane-sweep algorithm. It (i)
operates in two-dimensional surfaces (not restricted to the plane),
(ii) accepts various families of \f$x\f$-monotone curves (not only
line segments), and (iii) handles overlaps. (Observe that the original
algorithm did not handle overlaps. Handling overlaps is difficult,
especially for polyline, as two polylines may overlap in more than one
connected component.) The generic implementation serves as the
foundation of a family of concrete operations described in the rest of
this section, such as aggregately constructing an arrangement induced
by a set of curves that lie in a two-dimensional surface and outputting
the overlay of two arrangements.

<!-- ----------------------------------------------------------------------- -->
<!-- \subsection arr_ssecagg_insert Aggregate Insertion Functions              -->
<!-- ----------------------------------------------------------------------- -->

Given a set of \f$n\f$ input curves, you can insert the curves in the
set into an arrangement incrementally one by one. However, the \ref
PkgArrangementOnSurface2 package also provides a couple of free
(overloaded) functions that aggregately insert a range of curves into
an arrangement using the surface-Sweep framework.

<UL>

<LI>`CGAL::insert_non_intersecting_curves<>(arr, begin, end)` inserts
a range of \f$x\f$-monotone curves given by the range `[begin, end)`
into an arrangement `arr`. The \f$x\f$-monotone curves
should be pairwise disjoint in their interior and also
interior-disjoint from all existing curves and points of `arr`.</LI>

<LI>\link CGAL::insert<>() `insert(arr, begin, end)`\endlink operates
  on a range of \f$x\f$-monotone curves that may intersect one
  another.</LI>

</UL>

We distinguish between two cases:
(i) The given arrangement `arr` is empty (has only an unbounded face),
so it must be construct from scratch.
(ii) The given arrangement `arr` is not empty.

In the first case, we sweep over the input curves, compute their
intersection points, and construct the \dcel that represents their
arrangement. This process is performed in \cgalBigO{(n + k)\log
n} time, where \f$k\f$ is the total number of intersection
points. The running time is asymptotically better than the time needed
for incremental insertion if the arrangement is relatively sparse
(when \f$k\f$ is \cgalBigO{\frac{n^2}{\log n}}), but it is recommended
that this aggregate construction process be used even for dense
arrangements, since the plane-sweep algorithm performs fewer geometric
operations compared to the incremental insertion algorithms, and hence
typically runs much faster in practice.

Another important advantage of the aggregated insertion functions is
that they do not issue point-location queries. Thus, no point-location
object needs to be attached to the arrangement. As explained in
Section \ref arr_ssecpl, there is a trade-off between construction
time and query time in each of the point-location strategies, which
affects the running times of the incremental insertion
process. Naturally, this trade-off is absent in the case of aggregated
insertion.

The example below shows how to construct the same arrangement of five
line segments built incrementally in \ref
Arrangement_on_surface_2/incremental_insertion.cpp depicted in
\cgalFigureRef{aos_fig-incremental_insertion} using the aggregate
insertion function \link CGAL::insert<>() `insert()`\endlink.  Note
that no point-location object needs to be defined and attached to the
arrangement.

\cgalExample{Arrangement_on_surface_2/aggregated_insertion.cpp}

Next we handle the case where we have to insert a set of \f$n\f$
curves into an existing arrangement. Let \f$N\f$ denote the number of
edges in the arrangement.  If \f$n\f$ is very small compared to
\f$N\f$ (in theory, we would say that if \f$n = o(\sqrt{N})\f$), we
insert the curves one by one. For larger input sets, we use the
aggregate insertion procedures.

<!-- ----------------------------------------------------------------------- -->
\cgalFigureBegin{aos_fig-global_insertion,global_insertion.png} An
arrangement of intersecting line segments, as constructed in \ref
Arrangement_on_surface_2/global_insertion.cpp. The segments of
\f$\mathcal{S}_1\f$ are drawn in solid lines and the segments of
\f$\mathcal{S}_2\f$ are drawn in dark dashed lines. Note that the
segment \f$s\f$ (light dashed line) overlaps one of the segments in
\f$\mathcal{S}_1\f$.  \cgalFigureEnd
<!-- ----------------------------------------------------------------------- -->

The program below aggregately construct an arrangement of a set
\f$\mathcal{S}_1\f$ containing five line segments (drawn as solid
lines). Then, it inserts a single segment \f$s\f$ (drawn as a dotted
line) using the incremental insertion function. Finally, it adds a set
\f$\mathcal{S}_2\f$ with five more line segments (drawn as dashed
lines) in an aggregate fashion.  Notice that the line segments of
\f$\mathcal{S}_1\f$ are pairwise interior-disjoint, so
`insert_non_intersecting_curves()` is safely used. \f$\mathcal{S}_2\f$
also contains pairwise interior-disjoint segments, but as they
intersect the existing arrangement, \link
insert(Arrangement_2<Traits,Dcel>&, InputIterator, InputIterator)
`insert()`\endlink must be used to insert them. Also note that the
single segment \f$s\f$ inserted incrementally partially overlaps an
existing arrangement curve; the overlapped portion is drawn as a
dash-dotted line.

\cgalExample{Arrangement_on_surface_2/global_insertion.cpp}

We summarize the three levels of arrangement types
based on curve monotonicity and intersection properties in the table
below. The three levels, starting from the most restrictive, are
(i) \f$x\f$-monotone curves that are pairwise disjoint in their
  interior,
(ii) \f$x\f$-monotone curves (which are possibly intersecting one
  another), and
(iii) general curves. We list the single-curve insertion functions.

<table>
<tr><th>Type of Curves <th>Geometry-Traits Concept <th>Insertion Function
<tr><td>\f$x\f$-monotone and pairwise disjoint <td>`AosBasicTraits_2` or `AosLandmarkTraits_2` <td>`CGAL::insert_non_intersecting_curve<>()`
<tr><td>\f$x\f$-monotone <td>`AosXMonotoneTraits_2` <td> `%CGAL::insert<>()`
<tr><td>general <td>`AosTraits_2` <td>`%CGAL::insert<>()`
</table>

The insertion function template `%insert()` is overloaded to
(i) incrementally insert a single \f$x\f$-monotone curve,
(ii) incrementally insert a single general curve,
(iii) aggregately insert a set of \f$x\f$-monotone curves, and
(iv) aggregately insert a set of general curves.
The `CGAL::insert_non_intersecting_curves<>()` function template
aggregately inserts a set of \f$x\f$-monotone pairwise interior-disjoint
curves into an arrangement.

<!-- ----------------------------------------------------------------------- -->
\subsection arr_ssecgl_remove Removing Vertices and Edges
<!-- ----------------------------------------------------------------------- -->

The free functions `remove_vertex()` and `remove_edge()` handle the
removal of vertices and edges from an arrangement, respectively. The
difference between these functions and the corresponding member
functions of the `Arrangement_2` class template (see Section \ref
arr_sssecmf_iso_verts and Section \ref arr_sssecmf_halfedges) has to do
with the ability to merge two curves associated with adjacent edges to
form a single curve associated with a single edge.  An attempt to
remove a vertex or an edge from an arrangement object `arr` using the
free functions above requires that the traits class used to
instantiate the arrangement type of `arr` models the concept
`AosXMonotoneTraits_2`, which refines the
`AosBasicTraits_2` concept; see Section \ref
aos_sec-geom_traits.

The function template `CGAL::remove_vertex<>(arr, v)` removes the
vertex \f$v\f$ from the given arrangement `arr`, where \f$v\f$ is
either an isolated vertex or is a <em>redundant</em> vertex. Namely,
it has exactly two incident edges that are associated with two curves
that can be merged to form a single \f$x\f$-monotone curve. If
neither of the two cases apply, the function returns an indication
that it has failed to remove the vertex.

The function `CGAL::remove_edge<>(arr, e)` removes the edge \f$e\f$
from the arrangement by simply calling `arr.remove_edge(e)`; see
Section \ref arr_ssecmodify. In addition, if either of the end
vertices of \f$e\f$ becomes isolated or redundant after the removal of
the edge, it is removed as well.

\image html global_removal.png
\image latex global_removal.png

The following example demonstrates the usage of the free removal
functions. It creates an arrangement of four line segment \f$s_1,
\ldots, s_4\f$ forming an H-shape with two horizontal edges induced by
\f$s_1\f$ and \f$s_2\f$ (drawn as dashed lines). Then it removes the
two horizontal edges and clears all redundant vertices (drawn as
lightly shaded discs), such that the final arrangement consists of
just two edges associated with the vertical line segments \f$s_3\f$
and \f$s_4\f$.

\cgalExample{Arrangement_on_surface_2/global_removal.cpp}

<!-- ----------------------------------------------------------------------- -->
\subsection arr_ssec_decompose Vertical Decomposition
<!-- ----------------------------------------------------------------------- -->

As you have already seen, an arrangement face may have a fairly
complicated structure; its outer boundary may be very large, and it
may contain numerous holes.  For many practical applications, it is
more convenient to analyze the faces by decomposing each into a finite
number of cells (preferably convex when dealing with arrangements of
linear curves) of constant complexity. Vertical decomposition is a
generic way to achieve such a simplification of the arrangement.

Given an arrangement, we consider each arrangement vertex \f$v\f$, and
locate the feature lying vertically below the vertex and the feature
lying vertically above it, or the unbounded face in case there is no
such feature. (Such a feature is also the result of the vertical
ray-shooting operation from the vertex \f$v\f$, as described in
Section \ref arr_ssecray_shoot.) It is now possible to construct two
vertical segments connecting \f$v\f$ to the feature above it and to
the feature below it, possibly extending the vertical segments to
infinity. The collection of the vertical segments and rays computed
for all arrangement vertices induces a subdivision of the arrangement
into simple cells. There are two types of bounded two-dimensional
cells, as follows:

<UL>

<LI> Cells whose outer boundaries comprise four edges, of which
two originate from the original arrangement and the other two are
vertical.

<li> Cells whose outer boundaries comprise three edges, of which two
originate from the original arrangement and intersect at a common
vertex and the remaining one is vertical.

</UL>

<!-- ----------------------------------------------------------------------- -->
\cgalFigureBegin{aos_fig-bounded_vd,bounded_vertical_decomposition.png}
An arrangement of four line segments and its vertical decomposition
into pseudo trapezoids, as constructed in \ref
Arrangement_on_surface_2/bounded_vertical_decomposition.cpp. The
segments of the arrangement are drawn in solid blue lines and the
segments of the vertical decomposition are drawn in dark dotted lines.
\cgalFigureEnd
<!-- ----------------------------------------------------------------------- -->

In the case of an arrangement of line segments, two-dimensional cells
of the former type are trapezoids (as they have a pair of parallel
vertical edges), while two-dimensional cells of the latter type are
triangles, which can be viewed as degenerate trapezoids. The unbounded
cells can be similarly categorized into two types. Observe that the
boundary of an unbounded cell contains only one original edge or none
and it may contain only non-vertical edges.  The resulting cells are
therefore referred to as <em>pseudo trapezoids</em>. The
\cgalFigureRef{aos_fig-bounded_vd} depicts the vertical decomposition
of an arrangement induced by four line segments, as constructed in
\ref Arrangement_on_surface_2/bounded_vertical_decomposition.cpp and
listed below. The decomposition consists of 14 pseudo trapezoids, out
of which two are bounded triangles, two are bounded trapezoids, and 10
are unbounded trapezoids.

The function template `decompose()` accepts an arrangement
\f$\mathcal{A}\f$ and outputs for each vertex \f$v\f$ of
\f$\mathcal{A}\f$ a pair of features---one that directly lies below
\f$v\f$ and another that directly lies above \f$v\f$. It is
implemented as a plane-sweep algorithm, which aggregately computes the
set of pairs of features. Let \f$v\f$ be a vertex of
\f$\mathcal{A}\f$. The feature above (respectively below) \f$v\f$ may
be one of the following:

<UL>

<LI> Another vertex \f$u\f$ having the same \f$x\f$-coordinate as \f$v\f$.

<LI> An arrangement edge associated with an \f$x\f$-monotone curve
that contains \f$v\f$ in its \f$x\f$-range.

<LI> An unbounded face in case \f$v\f$ is incident to an unbounded
face, and there is no curve lying above (respectively below) it.

<LI> An empty object, in case \f$v\f$ is the lower (respectively
upper) endpoint of a vertical edge in the arrangement.

</UL>

\cgalExample{Arrangement_on_surface_2/bounded_vertical_decomposition.cpp}

As you might have noticed, the code above contains a call to an
instance of a the function template `read_objects()`. It reads the
description of geometric objects from a file and constructs them. It
accepts the name of an input file that contains the plain-text
description of the geometric objects and an output iterator for
storing the newly constructed objects.  When the function is
instantiated, the first template parameter, namely `Type`, must be
substituted by the type of objects to read. It is assumed that an
extractor operator (`>>`) that extracts objects of the given type from
the input stream is available. The listing of the function template,
which is defined in the file `read_objects.h`, is omitted here

\cgalAdvancedBegin

In Section \ref aos_sec-unbounded you will learn that we also support
arrangements induced by unbounded curves, referred to as
<em>unbounded arrangements</em>.  For such an arrangement we maintain an
imaginary rectangle with left, right, bottom, and top boundaries,
which bound the concrete vertices and edges of the
arrangement. Halfedges that represent the boundaries of the rectangle
are <em>fictitious</em>. The `decompose()` function
template handles unbounded arrangements. If \f$v\f$ is a vertex of an
unbounded arrangement, and \f$v\f$ is incident to an unbounded face
and there is no curve lying above (respectively below) it, the feature
above (respectively below) \f$v\f$ returned by the function template
`decompose()` is a fictitious edge.

\cgalAdvancedEnd

<!-- ======================================================================= -->
\section aos_sec-unbounded Arrangements of Unbounded Curves
<!-- ======================================================================= -->

All the arrangements constructed and manipulated in previous chapters
were induced only by line segments, which are, in particular, bounded
curves. Such arrangements always have one unbounded face that contains
all other arrangement features. In this section we explain how to
construct arrangements of unbounded curves. For simplicity of
exposition, we stay with linear objects and restrict our examples in
this section to lines and rays.  However, the discussion in this
section, as well as the software described, apply more generally to
arbitrary curves in two-dimensional surfaces.

<!-- ----------------------------------------------------------------------- -->
\subsection aos_ssec-unbounded-rep Representing Arrangements of Unbounded Curves
<!-- ----------------------------------------------------------------------- -->

Given a set \f$\mathcal{C}\f$ of unbounded curves, a simple approach
for representing the arrangement induced by \f$\mathcal{C}\f$ would be
to clip the unbounded curves using an axis-parallel rectangle that
contains all finite curve endpoints and intersection points between
curves in \f$\mathcal{C}\f$. This process would result in a set of
bounded curves (line segments if \f$\mathcal{C}\f$ consists of lines
and rays), and it would be straightforward to compute the arrangement
induced by this set.  However, we would like to operate directly on
the unbounded curves without having to preprocess them. Moreover, if
we are not given all the curves inducing the arrangement in advance,
then the choice of a good bounding rectangle may change as more curves
are introduced.

<!-- ----------------------------------------------------------------------- -->
\cgalFigureBegin{aos_fig-unb_dcel,unb_dcel.png}
A \dcel representing an arrangement of four lines. Halfedges are
drawn as thin arrows. The vertices \f$v_1, \ldots, v_8\f$ lie at
infinity, and are not associated with valid points. The halfedges that
connect them are fictitious, and are not associated with concrete
curves. The face denoted \f$f_0\f$ (lightly shaded) is the fictitious
"unbounded face" which lies outside the bounding rectangle (dashed)
that bounds the actual arrangement. The four fictitious vertices
\f$v_{\rm bl}, v_{\rm tl}, v_{\rm br}\f$ and \f$v_{\rm tr}\f$
represent the four corners of the imaginary bounding rectangle.
\cgalFigureEnd
<!-- ----------------------------------------------------------------------- -->

Instead of an explicit approach, we use an implicit bounding rectangle
embedded in the \dcel structure. \cgalFigureRef{aos_fig-unb_dcel}
shows the arrangement of four lines that subdivide the plane into
eight unbounded faces and two bounded ones. Notice that in this case
portions of the the unbounded faces now have outer boundaries (those
portions inside the bounding rectangle), and the halfedges along these
outer CCBs are drawn as arrows. The bounding rectangle is drawn
dashed. The vertices \f$v_1,v_2,\ldots,v_8\f$, which lie on the
bounding rectangle, represent the unbounded ends of the four lines
that approach infinity. The halfedges connecting them, which overlap
with the bounding rectangle, are not associated with geometric curves.
Thus, we refer to them as <em>fictitious</em>. Note that the outer
CCBs of the unbounded faces contain fictitious halfedges. The twins of
these halfedges form together one connected component that corresponds
to the entire imaginary rectangle. It forms a single hole in the face
\f$\tilde{f}\f$. We refer to \f$\tilde{f}\f$ as <em>fictitious</em>,
since it does not correspond to a real two-dimensional cell of the
arrangement. Finally, there are four additional vertices denoted by
\f$v_{\rm bl}, v_{\rm tl}, v_{\rm br}\f$, and \f$v_{\rm tr}\f$, which
coincide with the bottom-left, top-left, bottom-right, and top-right
corners of the bounding rectangle, respectively. They do not lie on
any curve, and are referred to as <em>fictitious</em> as well. These
four vertices identify each of the fictitious edges as lying on the
top, the bottom, the left, and the right edge of the imaginary
bounding rectangle. The four fictitious vertices exist even when the
arrangement is empty: In this case they are connected by four pairs of
fictitious halfedges that define a single unbounded face (which
represents the entire \f$\mathbb{R}^2\f$ plane) lying inside the
imaginary bounding rectangle and a fictitious face lying outside.

In summary, there are four types of arrangement vertices, which differ
from one another by their location with respect to the imaginary
bounding rectangle as follows:

<OL>

<LI> \anchor type-normal A vertex, associated with a point in
  \f$\mathbb{R}^2\f$. Such a vertex always lies inside the bounding
  rectangle and has bounded coordinates..

<LI> \anchor type-unbounded A vertex that represents an unbounded end
  of an \f$x\f$-monotone curve that approaches \f$x = -\infty\f$ or at
  \f$x = \infty\f$. In case of a horizontal line or a curve with a
  horizontal asymptote, the \f$y\f$-coordinate of the curve end may be
  finite (see, for example, the vertices \f$v_2\f$ and \f$v_7\f$ in
  \cgalFigureRef{aos_fig-unb_dcel}), but in general the curve end also
  approaches \f$y = \pm\infty\f$; see for instance the vertices
  \f$v_1\f$, \f$v_3\f$, \f$v_6\f$ and \f$v_8\f$ in
  \cgalFigureRef{aos_fig-unb_dcel}). For convenience, we always take a
  "tall" enough bounding rectangle and treat such vertices as lying on
  either the left or the right rectangle edges (that is, if a curve
  approaches \f$x = -\infty\f$, its left end will be represented by a
  vertex on the left edge of the bounding rectangle, and if it
  approaches \f$x = \infty\f$, its right end will be represented by a
  vertex on the right edge).

<LI> \anchor typeunboundedvertical A vertex that represents the
  unbounded end of a vertical linear curve (line or ray) or of a curve
  with a vertical asymptote (finite \f$x\f$-coordinate and an
  unbounded \f$y\f$-coordinate). Such a vertex always lies on one of
  the horizontal edges of the bounding rectangle (either the bottom
  one if \f$y = -\infty\f$, or the top one if \f$y = \infty\f$). The
  vertices \f$v_4\f$ and \f$v_5\f$ in \cgalFigureRef{aos_fig-unb_dcel}
  are of this type.

<LI> \anchor typefictitious The fictitious vertices that represent the
  four corners of the bounding rectangle.

</OL>

<!-- ----------------------------------------------------------------------- -->
\cgalFigureBegin{aos_fig-unb_asymptote,unb_asymptote.png}
The portions of a horizontal line, a vertical line, and two rectangular
hyperbolas with horizontal and vertical asymptotes confined to the
imaginary bounding rectangle.
\cgalFigureEnd
<!-- ----------------------------------------------------------------------- -->

A vertex (at infinity) of Type 2 or Type 3 above always has three
incident edges---one concrete edge that is associated with an
unbounded portion of an \f$x\f$-monotone curve, and two fictitious
edges connecting the vertex to its neighboring vertices at infinity or
the corners of the bounding rectangle; see
\cgalFigureRef{aos_fig-unb_asymptote}.  Fictitious vertices (of type 4
above) have exactly two incident fictitious edges. See Section \ref
aos_sec-geom_traits for an explanation on how the traits-class
interface helps impose the fact that a vertex at infinity is incident
to a single non-fictitious edge.

The traits class that substitutes the `Traits` parameter of the
`Arrangement_2<Traits,Dcel>` class template when the latter is
instantiated specifies whether the arrangement instance supports
unbounded curves through the definitions of some tags nested in the
traits class; see Section \ref aos_sssec-geom_traits-concepts_basic
for details. Every arrangement that supports unbounded curves supports
bounded curves as well, but not vice versa. Maintaining an arrangement
that supports unbounded curves incurs an overhead due to the necessity
to manage the imaginary bounding rectangle. If you know beforehand
that all input curves that induce a particular arrangement are
bounded, define your arrangement accordingly. That is, use a traits
class that does not support unbounded curves.

<!-- ----------------------------------------------------------------------- -->
\subsubsection arr_sssecunb_basic Basic Manipulation and Traversal Methods
<!-- ----------------------------------------------------------------------- -->

The types \link Arrangement_on_surface_2::Vertex `Vertex`\endlink,
\link Arrangement_on_surface_2::Halfedge `Halfedge`\endlink, and \link
Arrangement_on_surface_2::Face `Face`\endlink nested in the
`Arrangement_2` class template support the methods described below in
addition to the ones listed in Section \ref arr_ssectraverse. Let
\f$v\f$, \f$e\f$, and \f$f\f$ be handles to a vertex of type \link
Arrangement_on_surface_2::Vertex `Vertex`\endlink, a halfedge of type
\link Arrangement_on_surface_2::Halfedge `Halfedge`\endlink, and a
face of type \link Arrangement_on_surface_2::Face `Face`\endlink,
respectively.

<UL>

<LI>The calls \link
  Arrangement_on_surface_2::Vertex::parameter_space_in_x()
  `v->parameter_space_in_x()`\endlink and \link
  Arrangement_on_surface_2::Vertex::parameter_space_in_y()
  `v->parameter_space_in_y()`\endlink determine the location of the
  geometric embedding of the vertex \f$v\f$. The call \link
  Arrangement_on_surface_2::Vertex::parameter_space_in_x()
  `v->parameter_space_in_x()`\endlink returns `CGAL::ARR_INTERIOR` if
  the \f$x\f$-coordinate associated with \f$v\f$ is finite,
  `CGAL::ARR_LEFT_BOUNDARY` if \f$v\f$ represents the end of a curve
  the \f$x\f$-coordinate of which approaches \f$-\infty\f$, and
  `CGAL::ARR_RIGHT_BOUNDARY` if \f$v\f$ represents the end of a curve
  the \f$x\f$-coordinate of which approaches \f$\infty\f$. Similarly,
  the call \link
  Arrangement_on_surface_2::Vertex::parameter_space_in_y()
  `v->parameter_space_in_y()`\endlink returns `CGAL::ARR_INTERIOR` if
  the \f$y\f$-coordinate associated with \f$v\f$ is finite and
  `CGAL::ARR_BOTTOM_BOUNDARY` or `CGAL::ARR_TOP_BOUNDARY` if \f$v\f$
  represents the end of a curve the \f$y\f$-coordinate of which
  approaches \f$-\infty\f$ or \f$\infty\f$, respectively.

  The nested \link Arrangement_on_surface_2::Vertex `Vertex`\endlink
  type also provides the Boolean predicate \link
  Arrangement_on_surface_2::Vertex::is_at_open_boundary()
  `is_at_open_boundary()`\endlink.  If the call \link
  Arrangement_on_surface_2::Vertex::is_at_open_boundary()
  `v->is_at_open_boundary()`\endlink predicates evaluates to `false`,
  you can access the point associated with \f$v\f$. Otherwise, \f$v\f$
  is not associated with a \link Arrangement_on_surface_2::Point_2
  `Point_2`\endlink object, as it represents the unbounded end of a
  curve that approaches infinity.

<LI>The nested \link Arrangement_on_surface_2::Halfedge
  `Halfedge`\endlink type provides the Boolean predicate \link
  Arrangement_on_surface_2::Halfedge::is_fictitious `is_fictitious()`\endlink. If
  the call \link Arrangement_on_surface_2::Halfedge::is_fictitious
  `e->is_fictitious()`\endlink evaluates to `false`, you can access
  the \f$x\f$-monotone curve associated with \f$e\f$. Otherwise,
  \f$e\f$ is not associated with an \link
  Arrangement_on_surface_2::X_monotone_curve_2 `X_monotone_curve_2`\endlink
  object.

<LI>The nested \link Arrangement_on_surface_2::Face `Face`\endlink
  type provides the Boolean predicate \link
  Arrangement_on_surface_2::Face::is_fictitious()
  `is_fictitious()`\endlink. The call \link
  Arrangement_on_surface_2::Face::is_fictitious()
  `f->is_fictitious()`\endlink evaluates to `true` only when \f$f\f$
  lies outside the bounding rectangle. The method \link
  Arrangement_on_surface_2::Face::outer_ccb() `outer_ccb()`\endlink
  (see Section \ref arr_sssectr_face must not be invoked for the
  fictitious face.  \cgalFootnote{Typically, the code is guarded
  against such malicious calls with adequate preconditions. However,
  these preconditions are suppressed when the code is compiled with
  maximum optimization.}  Note that a valid unbounded face (of an
  arrangement that supports unbounded curves) has a valid outer CCB,
  although the CCB comprises only fictitious halfedges if the
  arrangement is induced only by bounded curves.

</UL>

Let \f$p_l = (x_l,y_l)\f$ and \f$p_r = (x_r,y_r)\f$ be the left and
right endpoints of a bounded \f$x\f$-monotone curve \f$c\f$,
respectively. We say that a point \f$p = (x_p,y_p)\f$ lies in the
\f$x\f$-range of \f$c\f$ if \f$x_l \leq x_p \leq x_r\f$. Let \f$p_l =
(x_l,y_l)\f$ be the left endpoint of an \f$x\f$-monotone curve \f$c\f$
unbounded from the right. A point \f$p = (x_p,y_p)\f$ lies in the
\f$x\f$-range of \f$c\f$ if \f$x_l \leq x_p\f$. Similarly, A point
\f$p = (x_p,y_p)\f$ lies in the \f$x\f$-range of an \f$x\f$-monotone
curve unbounded from the left if \f$x_p \leq x_r\f$. Naturally, every
point \f$p \in \mathbb{R}^2\f$ is in the \f$x\f$-range of an
\f$x\f$-monotone curve unbounded from the left and from the right.

\cgalAdvancedBegin

The function template `is_in_x_range()` listed below, and defined in
the file `is_in_x_range.h`, checks whether a given point \f$p\f$ is in
the \f$x\f$-range of the curve associated with a given halfedge
\f$e\f$. The function template also exemplifies how some of the above
functions can be used. The traits functor \link
AosBasicTraits_2::Compare_x_2 `Compare_x_2`\endlink used in
the code is described in Section \ref
aos_sssec-geom_traits-concepts_basic.

\code
// Check whether the given point is in the x-range of the curve associated
// with the given halfedge.
template <typename Arrangement>
bool is_in_x_range(typename Arrangement::Halfedge_const_handle he,
                   const typename Arrangement::Point_2& p,
                   const typename Arrangement::Traits_2& traits)
{
  auto cmp = traits.compare_x_2_object();

  // Compare p with the source vertex (which may lie at x = +/- oo).
  CGAL::Arr_parameter_space src_px = e->source()->parameter_space_in_x();
  CGAL::Comparison_result res_s =
    (src_px == CGAL::ARR_LEFT_BOUNDARY) ? CGAL::SMALLER :
    ((src_px == CGAL::ARR_RIGHT_BOUNDARY) ? CGAL::LARGER :
     cmp(e->source()->point(), p));
  if (res_s == CGAL::EQUAL) return true;

  // Compare p with the target vertex (which may lie at x = +/- oo).
  CGAL::Arr_parameter_space trg_px = e->target()->parameter_space_in_x();
  CGAL::Comparison_result  res_t =
    (trg_px == CGAL::ARR_LEFT_BOUNDARY) ? CGAL::SMALLER :
    ((trg_px == CGAL::ARR_RIGHT_BOUNDARY) ? CGAL::LARGER :
     cmp(e->target()->point(), p));

  // p lies in the x-range of the halfedge iff its source and target lie
  // at opposite x-positions.
  return (res_s != res_t);
}
\endcode

\cgalAdvancedEnd

It is important to observe that the call \link
Arrangement_on_surface_2::number_of_vertices()
`arr.number_of_vertices()`\endlink does not count the vertices at
infinity in the arrangement `arr`. To find out this number you need to
issue the call \link
Arrangement_on_surface_2::number_of_vertices_at_infinity()
`arr.number_of_vertices_at_infinity()`\endlink. Similarly, \link
Arrangement_on_surface_2::number_of_edges()
`arr.number_of_edges()`\endlink does not count the fictitious edges
(whose number is always \link
Arrangement_on_surface_2::number_of_vertices_at_infinity()
`arr.number_of_vertices_at_infinity()`\endlink + 4) and \link
Arrangement_on_surface_2::number_of_faces()
`arr.number_of_faces()`\endlink does not count the fictitious
faces. The vertex, halfedge, edge, and face iterators defined by the
`Arrangement_2` class template only go over true features of the
arrangement; namely, vertices at infinity and fictitious halfedges and
fictitious faces are skipped. On the other hand, the
`Ccb_halfedge_circulator` of the outer boundary of an unbounded face
or the `Halfedge_around_vertex_circulator` of a vertex at infinity do
traverse fictitious halfedges. While an arrangement induced by bounded
curves has a single unbounded face, an arrangement induced by
unbounded curves may have several unbounded faces. The call \link
Arrangement_on_surface_2::number_of_unbounded_faces()
`arr.number_of_unbounded_faces()`\endlink returns the number of
unbounded arrangement faces (Thus, \link
Arrangement_on_surface_2::number_of_faces()
`arr.number_of_faces()`\endlink - \link
Arrangement_on_surface_2::number_of_unbounded_faces()
`arr.number_of_unbounded_faces()`\endlink is the number of bounded
faces). The calls \link
Arrangement_on_surface_2::unbounded_faces_begin()
`arr.unbounded_faces_begin()`\endlink and \link
Arrangement_on_surface_2::unbounded_faces_end()
`arr.unbounded_faces_end()`\endlink return iterators of the type
`Arrangement_on_surface_2::Unbounded_face_iterator` (or its
non-mutable, `const`, counterpart type) that define the range of the
arrangement unbounded faces. Naturally, the value-type of this
iterator is \link Arrangement_on_surface_2::Face `Face`\endlink.

There is no way to directly obtain the fictitious vertices that
represent the four corners of the imaginary bounding
rectangle. However, you can obtain the fictitious face through the
call \link Arrangement_on_surface_2::fictitious_face()
`arr.fictitious_face()`\endlink, and then iterate over the boundary of
its single hole, which represents the imaginary bounding
rectangle. Recall that an arrangement of bounded curves does not have
a fictitious face. In this case the call above returns a null handle.

The example below exhibits the difference between an arrangement
induced by bounded curves, which has a single unbounded face, and an
arrangement induced by unbounded curves, which may have several
unbounded faces. It also demonstrates the usage of the insertion
function for pairwise interior-disjoint unbounded curves. In this case
we use an instance of the traits class-template
`Arr_linear_traits_2<Kernel>` to substitute the `Traits` parameter of
the `Arrangement_2<Traits,Dcel>` class template when instantiated.
This traits class-template is capable of representing line segments as
well as unbounded linear curves, namely, lines and rays. Observe that
objects of the \link Arr_linear_traits_2::X_monotone_curve_2
`X_monotone_curve_2`\endlink type nested in this traits class-template
are constructible from objects of types \link
Arr_linear_traits_2<Kernel>::Line_2 `Line_2`\endlink, \link
Arr_linear_traits_2<Kernel>::Ray_2 `Ray_2`\endlink, and \link
Arr_linear_traits_2<Kernel>::Segment_2 `Segment_2`\endlink also nested
in the traits class-template. These three types and the \link
Arr_linear_traits_2<Kernel>::Point_2 `Point_2`\endlink type are
defined by the traits class-template `Arr_linear_traits_2<Kernel>` to
be the corresponding types of the kernel used to instantiate the
traits class-template; see Paragraph \ref arr_sssectr_linear.

<!-- ----------------------------------------------------------------------- -->
\cgalFigureBegin{aos_fig-unbounded_non_intersecting,unbounded_non_intersecting.png}
An arrangement of unbounded linear objects, as constructed in
\ref Arrangement_on_surface_2/unbounded_non_intersecting.cpp.
 \cgalFigureEnd
 <!-- ----------------------------------------------------------------------- -->

The first three curves, \f$c_1\f$, \f$c_2\f$, and \f$c_3\f$, are
inserted using the specialized insertion functions for
\f$x\f$-monotone curves whose location in the arrangement is
known. Notice that inserting an unbounded curve in the interior of an
unbounded face, or from an existing vertex that represents an bounded
end of the curve, may cause an unbounded face to split. (This is never
the case when inserting a bounded curve---compare with Section \ref
arr_sssecmf_insert_cv.) Three additional rays are then inserted
incrementally using the insertion function for \f$x\f$-monotone curves,
the interior of which is disjoint from all arrangement features; see
the illustration in
\cgalFigureRef{aos_fig-unbounded_non_intersecting}). Finally, the
program prints the size of the arrangement using the function template
`print_unbounded_arrangement_size()` defined in the header file
`arr_print.h`. (Its listing is omitted here.) The program also
traverses the outer boundaries of its six unbounded faces and prints
the curves along these boundaries. The header file `arr_linear.h`,
which contains the definitions used by the example program, is listed
immediately after the listing of the main function.

\cgalExample{Arrangement_on_surface_2/unbounded_non_intersecting.cpp}

The type definitions used by the example below, as well as by other
examples that use the `Arr_linear_traits_2` class template, are listed
next.  These types are defined in the header file `arr_linear.h`.

\code
#include <CGAL/Exact_predicates_exact_constructions_kernel.h>
#include <CGAL/Arr_linear_traits_2.h>
#include <CGAL/Arrangement_2.h>

using Kernel = CGAL::Exact_predicates_exact_constructions_kernel;
using Number_type = Kernel::FT;

using Traits = CGAL::Arr_linear_traits_2<Kernel>;
using Point = Traits::Point_2;
using Segment = Traits::Segment_2;
using Ray = Traits::Ray_2;
using Line = Traits::Line_2;
using X_monotone_curve = Traits::X_monotone_curve_2;

using Arrangement = CGAL::Arrangement_2<Traits>;
using Vertex_handle = Arrangement::Vertex_handle;
using Halfedge_handle = Arrangement::Halfedge_handle;
using Face_handle = Arrangement::Face_handle;
\endcode

<!-- ----------------------------------------------------------------------- -->
\subsubsection arr_sssec-unb_global Free Functions
<!-- ----------------------------------------------------------------------- -->

All the free functions that operate on arrangements of bounded curves
(see Section \ref arr_secgl_funcs) can also be applied to arrangements
of unbounded curves. For example, consider a container of linear
curves that has to be inserted into an arrangement object, the type of
which is an instance of the `Arrangement_2<Traits,Dcel>` class
template, where the `Traits` parameter is substituted by the traits
class that handles linear curves; see Section \ref
arr_sssectr_linear. You can do it incrementally; namely, insert the
curves one by one as follows:
\code
  for (auto it = curves.begin(); it != curves.end(); ++it) insert(arr, *it);
\endcode
Alternatively, the curves can be inserted aggregately using a single
call as follows:
\code
  insert(arr, curves.begin(), curves.end());
\endcode
It is also possible to issue point-location queries and vertical
ray-shooting queries (see also Section \ref arr_secqueries) on
arrangements of lines, where the only restriction is that the query
point has finite coordinates. Note that all the point-location
strategies mentioned above, except the trapezoidal map strategy, are
capable of handling arrangements of unbounded curves.

<!-- ----------------------------------------------------------------------- -->
\subsection arr_ssec-unb_duality Point-Line Duality
<!-- ----------------------------------------------------------------------- -->

In the following example we show how an arrangement of unbounded lines
is utilized to solve the following problem: Given a set of points,
does the set contain at least three collinear points? In this example
a set of input points is read from a file. The file `points.dat` is
used by default. It contains definitions of \f$100\f$ points randomly
selected on the grid \f$[-10000,10000]\times[-10000,10000]\f$. We
construct an arrangement of the dual lines, where the line \f$p^{*}\f$
dual to the point \f$p = (x_p, y_p)\f$ is given by the equation \f$y =
x_p*x - y_p\f$, and check whether three (or more) of the dual lines
intersect at a common point, by searching for a (dual) vertex, whose
degree is greater than \f$4\f$. If such a vertex exists, then there
are at least three dual lines that intersect at a common point, which
implies that there are at least three collinear points.

\cgalExample{Arrangement_on_surface_2/dual_lines.cpp}

Note that there are no three collinear points among the points defined
in the input file `points.dat`. In the second part of the example the
existence of a collinear triple is forced and verified as follows. A
line dual to the midpoint of two randomly selected points is
introduced, and inserted into the arrangement. This operation is
followed by a test that verifies that a vertex of degree greater than
\f$4\f$ exists.

<!-- ======================================================================= -->
\section aos_sec-curved_surfaces Arrangements on Curved Surfaces
<!-- ======================================================================= -->

We are given a surface \f$S\f$ in \f$\mathbb{R}^3\f$ and a set
\f$\mathcal{C}\f$ of curves embedded in this surface. The curves
subdivide \f$S\f$ into cells of dimension 0 (<em>vertices</em>), 1
(<em>edges</em>), and 2 (<em>faces</em>). This subdivision is the
<em>arrangement</em> \f$\mathcal{A}(\mathcal{C})\f$ induced by
\f$\mathcal{C}\f$ on \f$S\f$. Arrangements embedded in curved surfaces
in \f$\mathbb{R}^3\f$ are generalizations of arrangements embedded in
the plane. In this section we explain how to construct, maintain, and
manipulate two-dimensional arrangements embedded in orientable
parametric surfaces in three dimensions, such as planes, cylinders,
spheres, and tori, and surfaces homeomorphic to them; see
\cgalFigureRef{aos_fig-surfaces}. Such arrangements have many
theoretical and practical applications; see, e.g.,
\cgalCite{as-aa-00}, \cgalCite{cgal:bfhks-apsca-10},
\cgalCite{cgal:bfhmw-apsgf-10}, \cgalCite{cgal:fhktww-a-07}, and
\cgalCite{cgal:h-a-04}.

\cgalFigureAnchor{aos_fig-surfaces}
<center>
<table border=0>
<tr>
<td>\image html sphere.png</td>
<td>\image html cylinder.png</td>
<td>\image html cone.png</td>
<td>\image html ellipsoid.png</td>
<td>\image html torus.png</td>
<td>\image html paraboloid.png</td>
<tr align="center">
<td>(a) Sphere</td>
<td>(b) Cylinder</td>
<td>(c) Cone</td>
<td>(d) Ellipsoid</td>
<td>(e) Torus</td>
<td>(f) Paraboloid</td>
</tr>
</table>
</center>
\cgalFigureCaptionBegin{aos_fig-surfaces}
Various two-dimensional parametric surfaces, arrangements on which
are supported by the framework.
\cgalFigureCaptionEnd

<!-- ----------------------------------------------------------------------- -->
\subsection aos_ssec-curved_surfaces-parameteric Parametric Surfaces
<!-- ----------------------------------------------------------------------- -->

We use \f$\overline{\mathbb{R}}\f$ to denote the compactified real line
\f$\mathbb{R} \cup \{-\infty,+\infty\}\f$. The mapping
\f$x \mapsto x/(1 - x^2)\f$ is a homeomorphism between
\f$(-1,+1)\f$ and \f$\mathbb{R}\f$ and between \f$[-1,+1]\f$ and
\f$\overline{\mathbb{R}}\f$. So you may also think of finite intervals
instead of the (compactified) real line in what follows.

A parametric surface \f$S\f$ is given by a continuous function
\f$\phi_S: \Phi \rightarrow \mathbb{R}^3\f$, where the domain \f$\Phi
= X \times Y\f$ is a rectangular two-dimensional parameter space and
\f$S = \phi_S(\Phi)\f$. The sets \f$X\f$ and \f$Y\f$ are open,
half-open, or closed intervals with endpoints in
\f$\overline{\mathbb{R}}\f$. We use \f$x_{\rm min}\f$, \f$x_{\rm
max}\f$, \f$y_{\rm min}\f$, and \f$y_{\rm max}\f$ to denote the
endpoints of \f$X\f$ and \f$Y\f$, respectively.

<ul>

<li>The left side of the boundary of \f$\Phi\f$ consists of the points
\f$(x_{\rm min},y)\f$ with \f$y \in {\rm closure}(Y)\f$. It is
<em>open</em>, if \f$x_{\rm min} \not\in X\f$ or \f$y\not\in Y\f$, and
<em>closed</em>, otherwise. The right side is defined analogously.
The bottom side consists of the points \f$(x, y_{\rm min})\f$ with
\f$x \notin (x_{\rm min},x_{\rm max})\f$; the top side is defined
analogously. The bottom or top sides can also be open. Note that the
"corners" of the parameter space belong to the vertical sides; this
asymmetry corresponds to the fact that we sweep \f$x\f$-monotone
curves, and not \f$y\f$-monotone curves. The four sides together form
the boundary \f$\partial \Phi\f$.</li>

<li>A point \f$p \in S\f$ is <em>regular</em> if it has only one
pre-image under \f$\Phi\f$. All pre-images of a non-regular point lie
in the boundary of \f$\Phi\f$. In particular, \f$\phi_S\f$ is
bijective on \f$(x_{\rm min},x_{\rm max})\times(y_{\rm min},y_{\rm
max})\f$.  More precisely, a non-regular point has either exactly two
pre-images that lie on opposite sides of the domain, or all points of
exactly one side of the domain.</li>

</ul>

A side of the domain is contracted if \f$\phi_S\f$ is constant on it.
The image of the side is called a <em>contraction point</em>.

The bottom and top sides of the domain (similarly for the left and
right sides) are <em>identified</em> if
\f$\phi_S(x,y_{\rm min}) = \phi_S(x, y_{\rm max})\f$ for all
\f$x \in X \f$. The curve \f$x \mapsto \phi_S(x,y_{\rm min})\f$ is
called an <em>identification curve</em>.

Rectangles, strips, quadrants, half-planes, and planes can be modeled
with \f$\phi_S\f$ being the identity mapping. For example,
\f$\Phi_S(x, y) = (x, y, 0)\f$ with \f$X = Y =(-\infty, +\infty)\f$
parameterizes a plane. Surfaces such as paraboloids can be
modeled through continuous and bijective parameterizations, for
example, \f$\phi_S(x,y) = (x,y,x^2 + y^2)\f$, where
\f$U = V =(-\infty, +\infty)\f$, defines a paraboloid of revolution.
Cylinders, tori, spheres, and surfaces homeomorphic to them, require
more general parameterizations. For example, the unit sphere is
commonly parameterized as
\f$\phi_S(x, y) = (\cos x \cos y, \sin x \cos y, \sin y)\f$, where
\f$\Phi = [-\pi, \pi] \times [-\frac{\pi}{2}, \frac{\pi}{2}]\f$. With
respect to this parameterization, the north and the south pole and
all points on the opposite Prime (Greenwich) Meridian are
non-regular. The north pole \f$(0,0,1)\f$ has infinitely many
pre-images \f$(x, \pi/2)\f$ with \f$-\pi < x < \pi\f$ and so does the
south pole \f$(0,0,-1)\f$. The points on the opposite Prime Meridian
have two pre-images each, namely \f$(-\pi,y)\f$ and \f$(\pi,y)\f$
with \f$-\pi/2 \leq y \leq \pi/2\f$. We say that the top and bottom
side of the domain are <em>contracted</em> and the left and right sides
are <em>identified</em>. These are exactly the kinds of non-injectivity
that we allow.

We give more examples. A <em>triangle</em> with corners
\f$(a_1, b_1), (a_2, b_2)\f$, and \f$(a_3, b_3)\f$ can be
parameterized via \f$\Phi = [0,1] \times [0,1]\f$ with
\f$\phi_S(x,y) = (a_1 + x(a_2 - a_1) + xy(a_3-a_2), b_1 +
x(b_2 - b_1) + xy(b_3-b_2), 0)\f$. The left side of the rectangular
domain contracts to a point. An open or closed <em>cylinder</em> is
modeled by identifying the vertical sides and having \f$Y\f$ open or
closed, respectively. A <em>torus</em> is modeled by identifying the
vertical sides and the horizontal sides. A <em>paraboloid</em> or
<em>half-cone</em> may be modeled by identifying the vertical sides
and contracting one of the horizontal sides to a point. More elegantly,
they are modeled by a bijective parameterization as given above. A
<em>sphere</em> is modeled by identifying the vertical sides and
contracting both horizontal sides. A <em>croissant</em>, a torus with
one pinch point, is modeled by identifying the vertical and
identifying the horizontal sides and, in addition, contracting one of
the pairs. However, the croissant is excluded by our definitions. All
surfaces supported by our framework are locally homeomorphic to a
disk, and hence an \dcel data-structure suffices for representing
arrangements on these surfaces. The croissant is, at the pinch point,
not locally homeomorphic to a disk, and hence a more general
cell-tuple data structure than an \dcel would be needed.

A curve \f$\gamma\f$ is a continuous function \f$\gamma: I \rightarrow
\Phi\f$, where \f$I\f$ is an open, half-open, or closed interval with
endpoints 0 and 1, and \f$\gamma\f$ is injective except at a finite
number of points. If \f$0 \not\in I\f$, the limit \f$\lim_{t
\rightarrow 0+} \gamma(t)\f$ exists (in the closure of \f$\Phi\f$) and
lies in an open side of the boundary. Similarly, if \f$1 \not\in I\f$,
then \f$\lim_{t \rightarrow 1-} \gamma(t)\f$ exists and lies in an
open side of the boundary. A curve \f$c\f$ in \f$S\f$ is the image of
a curve \f$\gamma\f$ in the domain.

A curve is <em>closed in the domain</em> if \f$\gamma(0) =
\gamma(1)\f$; in particular, \f$0 \in I\f$ and \f$1 \in I\f$. A curve
is <em>closed in the surface \f$S\f$ (or simply closed)</em> if
\f$\phi_S(\gamma(0)) = \phi_S(\gamma(1))\f$. A curve \f$\gamma\f$ has
two <em>ends</em>, the 0-end \f$\langle \gamma,0 \rangle\f$ and the
1-end \f$\langle \gamma,1 \rangle\f$. If \f$d \in I\f$, the
\f$d\f$-end has a geometric interpretation. It is a point in
\f$\Phi\f$. If \f$d \not\in I\f$, the \f$d\f$-end has no geometric
interpretation. You may think of it as a point on an open side of the
domain or an initial or terminal segment of \f$\gamma\f$. If \f$d
\not\in I\f$, we say that the \f$d\f$-end of the curve is open. The
equator curve on the sphere in standard parameterization is given by
\f$\gamma(t) = (\pi(2t - 1),0)\f$ for \f$t \in [0,1]\f$. The
\f$0\f$-end of \f$\gamma\f$ is the point \f$(-\pi,0)\f$ in \f$\Phi\f$
and a point on the equator of the sphere. It is closed on the sphere,
but not closed in \f$\Phi\f$. The diagonal \f$(u,u)\f$ in the plane
is, for example, given by \f$\gamma(t) = (x(t),y(t))\f$ and \f$x(t) =
y(t) = (t - 1/2)/(t(1-t))\f$.  Both ends of this curve are open. The
\f$d\f$-end of a curve \f$\gamma\f$ is incident to the left side if
either \f$d \in I\f$ and \f$\gamma(d)\f$ lies on the left side or \f$d
\not\in I\f$ and \f$\lim_{t \rightarrow d} \gamma(t)\f$ lies on the
left side, which is then an open side. Similarly for the other sides.

A <em>strongly \f$x\f$-monotone curve</em> is the image of a curve
\f$\gamma\f$, such that if \f$t_1 < t_2\f$ for \f$t_1, t_2 \in I\f$,
then \f$x(t_1) < x(t_2)\f$. A <em>vertical curve</em> is the image of
a curve \f$\gamma\f$, such that \f$x(t) = C\f$ for all \f$t \in I\f$
and some \f$C \in X\f$ and \f$y(t_1) < y(t_2)\f$ for \f$t_1 <
t_2\f$. For instance, every Meridian curve of a sphere parameterized
as above is vertical. An <em>\f$x\f$-monotone curve</em> is either
vertical or strongly \f$x\f$-monotone.

<!-- ----------------------------------------------------------------------- -->
\subsection aos_ssec-curved_surfaces-aos_class The Arrangement on Surface Class Template
<!-- ----------------------------------------------------------------------- -->

The class template `Arrangement_on_surface_2<GeomTraits, TopolTraits>`
can be used to represent a 2D arrangement embedded in a 3D
surface. The template is parameterized by template parameters
<em>geometry traits</em> and <em>topology traits</em>. The
topology-traits type deals with the topology of the parametric
surface; see Section \ref aos_sec-topol_traits. As explained in the
previous section, a parametric surface \f$S = \phi_S(\Phi)\f$ is given
by a continuous function \f$\phi_S: \Phi \rightarrow \mathbb{R}^3\f$,
where the domain \f$\Phi = X \times Y\f$ is a rectangular
two-dimensional parameter space. \f$X\f$ and \f$Y\f$ are open,
half-open, or closed intervals with endpoints in
\f$\overline{\mathbb{R}}\f$.

The geometry-traits type introduces the type names of the basic
geometric objects (i.e., point, curve, and \f$x\f$-monotone curve)
and the set of operations on objects of these types required to
construct and maintain the arrangement and to operate on it. The
traits-concept hierarchy described in Section \ref aos_sec-geom_traits
accurately defines the requirements imposed on a model of a geometry
traits class. Recall that requirements apply to the parameter space
\f$\Phi = X \times Y\f$; thus, they are defined in terms of \f$x\f$
and \f$y\f$ coordinates.  Most requirements apply to all type of
arrangements regardless of the embedding surface. However, several
refined concepts apply only to arrangements on surfaces that are not
in the plane, that is, modeled with \f$\phi_S\f$ not being the
identity mapping. They differ according to the type of the side
boundaries of the parameter space being open, closed, contracted, or
identified.

At this point only one type of arrangements on non planar surfaces is
supported, namely, arrangements embedded in the sphere and induced by
arcs of great circles, also known as geodesic arcs.
\cgalFigureRef{aos_fig-voronoi} shows various Voronoi diagrams the
bisectors of which are geodesic arcs.  They are represented as
arrangements induced by geodesic arcs embedded in the sphere.

\cgalFigureAnchor{aos_fig-voronoi}
<center>
<table border=0>
<tr>
<td>\image html voronoi.jpg</td>
<td>\image html degenerate_voronoi.jpg</td>
<td>\image html power_diagram.jpg</td>
<td>\image html degenerate_power_diagram.jpg</td>
<tr align="center">
<td>(a)</td>
<td>(b)</td>
<td>(c)</td>
<td>(d)</td>
</tr>
</table>
</center>
\cgalFigureCaptionBegin{aos_fig-voronoi}
Voronoi diagrams on the sphere.
All diagram edges are geodesic arcs.
Sites are drawn in red and Voronoi edges are drawn in blue.
(a) The Voronoi diagram of 32 random points.
(b) A highly degenerate case of Voronoi diagram of 30 point sites on the sphere.
(c) The power diagram of 10 random circles.
(d) A degenerate power diagram of 14 sites on the sphere.
\cgalFigureCaptionEnd

<!-- ----------------------------------------------------------------------- -->
\subsection aos_ssec-curved_surfaces-basic Basic Manipulation and Traversal Methods
<!-- ----------------------------------------------------------------------- -->

The types \link Arrangement_on_surface_2::Vertex `Vertex`\endlink,
\link Arrangement_on_surface_2::Halfedge `Halfedge`\endlink, and \link
Arrangement_on_surface_2::Face `Face`\endlink nested in the
`Arrangement_on_surface_2` class template support the methods listed
in Section \ref arr_ssectraverse and in Section \ref
arr_sssecunb_basic.  Additional methods supported by these types are
described next. Let \f$v\f$, \f$e\f$, and \f$f\f$ be handles to a
vertex of type \link Arrangement_on_surface_2::Vertex
`Vertex`\endlink, a halfedge of type \link
Arrangement_on_surface_2::Halfedge `Halfedge`\endlink, and a face of
type \link Arrangement_on_surface_2::Face `Face`\endlink,
respectively.

<UL>

<LI>The calls \link
  Arrangement_on_surface_2::Vertex::parameter_space_in_x()
  `v->parameter_space_in_x()`\endlink and \link
  Arrangement_on_surface_2::Vertex::parameter_space_in_y()
  `v->parameter_space_in_y()`\endlink determine the location of the
  geometric embedding of the vertex \f$v\f$. The call \link
  Arrangement_on_surface_2::Vertex::parameter_space_in_x()
  `v->parameter_space_in_x()`\endlink returns `ARR_INTERIOR` if the
  geometric embedding of \f$v\f$ is a point \f$p\f$ the pre-image of
  which does not lie on the left nor on the right sides of the
  boundary of the parameter space. If the left and right sides are not
  identified, then `ARR_LEFT_BOUNDARY` or `ARR_RIGHT_BOUNDARY` are
  returned if the pre-image of \f$p\f$ lies on the left or the right
  side, respectively.  If the left and right sides are identified, the
  return value is unspecified and can be either
  `ARR_LEFT_BOUNDARY` or `ARR_RIGHT_BOUNDARY`. Similarly, the call
  \link Arrangement_on_surface_2::Vertex::parameter_space_in_y()
  `v->parameter_space_in_y()`\endlink returns `ARR_INTERIOR` if the
  geometric embedding of \f$v\f$ is a point \f$q\f$, the pre-image of
  which does not lie on the bottom nor on the top sides of the
  boundary of the parameter space. If the bottom and top sides are not
  identified, then `ARR_BOTTOM_BOUNDARY` or `ARR_TOP_BOUNDARY` are
  returned if the pre-image of \f$q\f$ lies on the bottom or the top
  side, respectively.  If the bottom and top sides are identified, the
  return value is unspecified.

  If you want to determine whether the pre-image of a point \f$p\f$
  lies on identified sides, you need to employ one of the two traits
  functors \link
  AosIdentifiedHorizontalTraits_2::Is_on_x_identification_2
  `Is_on_x_identification_2`\endlink or \link
  AosIdentifiedVerticalTraits_2::Is_on_y_identification_2
  `Is_on_y_identification_2`\endlink; see Section \ref
  aos_ssec-traits-curved. If the pre-image of an \f$x\f$-monotone
  curve \f$c\f$ does not entirely lie on identified sides, you can
  determine the location of the pre-image of an endpoint of \f$c\f$
  employing either the \link
  AosVerticalSideTraits_2::Parameter_space_in_x_2
  `Parameter_space_in_x_2`\endlink functor or the \link
  AosHorizontalSideTraits_2::Parameter_space_in_y_2
  `Parameter_space_in_y_2`\endlink functors; see Section \ref
  aos_ssec-traits-curved. The operations in both functors accept an
  enumeration that indicates the curve end, that is,
  `CGAL::ARR_MIN_END` or `CGAL::ARR_MAX_END`, in addition to the curve
  itself.

<LI>A face in a planar arrangement has at most one outer CCB. However,
  an arrangement embedded on a surface may present additional
  scenarios. For example, a face of an arrangement embedded on a torus
  may have two outer CCBs, and a face of an arrangement embedded on a
  sphere might be consider a hole inside the surrounding face or vice
  versa. To this end, outer CCBs and inner CCBs of faces of
  arrangements embedded on surfaces are symmetrically treated (while
  maintaining the invariant that a face always lies to the left of
  every halfedge of every CCB of the face regardless of whether the
  CCB is inner or outer). The classification of a CCB as inner or
  outer becomes an implementation detail.  The calls \link
  Arrangement_on_surface_2::Face::outer_ccbs_begin()
  `f->outer_ccbs_begin()`\endlink and \link
  Arrangement_on_surface_2::Face::outer_ccbs_end()
  `f->outer_ccbs_end()`\endlink return iterators of type \link
  Arrangement_on_surface_2::Face::Outer_ccb_iterator
  `Outer_ccb_iterator`\endlink that define a range of outer CCBs
  inside the face \f$f\f$. Similarly, the methods \link
  Arrangement_on_surface_2::Face::inner_ccbs_begin()
  `f->inner_ccbs_begin()`\endlink and \link
  Arrangement_on_surface_2::Face::inner_ccbs_end()
  `f->inner_ccbs_end()`\endlink return iterators of type \link
  Arrangement_on_surface_2::Face::Inner_ccb_iterator
  `Inner_ccb_iterator`\endlink that define a range of inner CCBs
  inside the face \f$f\f$. (The latter pair of member functions and
  the iterator type are equivalent to the methods \link
  Arrangement_on_surface_2::Face::holes_begin()
  `holes_begin()`\endlink, \link
  Arrangement_on_surface_2::Face::holes_end() `holes_end()`\endlink,
  and \link Arrangement_on_surface_2::Face::Hole_iterator
  `Hole_iterator`\endlink; see Section \ref arr_sssectr_face.) The
  calls \link Arrangement_on_surface_2::Face::number_of_outer_ccbs()
  `f->number_of_outer_ccbs()`\endlink and \link
  Arrangement_on_surface_2::Face::number_of_inner_ccbs()
  `f->number_of_inner_ccbs()`\endlink return the number of outer CCBs
  and the number of inner CCBs in \f$f\f$, respectively.

</UL>

\cgalAdvancedBegin

The function template `is_in_x_range()` listed below, and defined in
the file `spherical_is_in_x_range.h` checks whether a given point
\f$p\f$, in the interior of the parameter space, is in the
\f$x\f$-range of an \f$x\f$-monotone curve \f$c\f$ that represents a
great-circle arc. It assumes that the left and right sides of the
parameter space are identified and the bottom and top sides are
contracted, which is the settings used by the traits class template
`Arr_geodesic_arc_on_sphere_traits_2<Kernel,X,Y>`; see Section \ref
arr_ssectr_spherical. The traits functors \link
AosBasicTraits_2::Construct_min_vertex_2
`Construct_min_vertex_2`\endlink, \link
AosBasicTraits_2::Construct_max_vertex_2
`Construct_min_vertex_2`\endlink, and \link
AosBasicTraits_2::Compare_x_2 `Compare_x_2`\endlink used in
the code are described is Section \ref
aos_sssec-geom_traits-concepts_basic.  The traits functors \link
AosVerticalSideTraits_2::Parameter_space_in_x_2
`Parameter_space_in_x_2`\endlink, \link
AosHorizontalSideTraits_2::Parameter_space_in_y_2
`Parameter_space_in_y_2`\endlink, \link
AosIdentifiedVerticalTraits_2::Is_on_y_identification_2
`Is_on_y_identification_2`\endlink, and \link
AosHorizontalSideTraits_2::Compare_x_on_boundary_2
`Compare_x_on_boundary_2`\endlink, are described is Section \ref
aos_ssec-traits-curved.

\code
template <typename GeometryTraits>
bool is_in_x_range(const typename GeometryTraits::X_monotone_curve_2& c,
                   const typename GeometryTraits::Point_2& p,
                   const GeometryTraits& traits) {
  CGAL_assertion(! traits.is_on_y_identification_2_object()(p));

  if (traits.is_on_y_identification_2_object()(c)) return false;

  // Note that a great-circle arc that is incident to a pole is vertical.
  auto cmp_x_boundary = traits.compare_x_on_boundary_2_object();
  auto psy = traits.parameter_space_in_y_2_object();
  auto psy_min = psy(c, CGAL::ARR_MIN_END);
  if (psy_min == CGAL::ARR_BOTTOM_BOUNDARY)
    return cmp_x_boundary(p, c, CGAL::ARR_MIN_END) == CGAL::EQUAL;
  auto psy_max = psy(c, CGAL::ARR_MAX_END);
  if (psy_max == CGAL::ARR_TOP_BOUNDARY)
    return cmp_x_boundary(p, c, CGAL::ARR_MAX_END) == CGAL::EQUAL;
  auto psx = traits.parameter_space_in_x_2_object();
  auto psx_min = psx(c, CGAL::ARR_MIN_END);
  auto psx_max = psx(c, CGAL::ARR_MAX_END);
  if ((psx_min == CGAL::ARR_LEFT_BOUNDARY) &&
      (psx_min == CGAL::ARR_RIGHT_BOUNDARY))
    return true;
  auto cmp_x = traits.compare_x_2_object();
  if (psx_min == CGAL::ARR_LEFT_BOUNDARY) {
    const auto& p_right = traits.construct_max_vertex_2_object()(c);
    auto res = cmp_x(p, p_right);
    return ((res == CGAL::SMALLER) || (res == CGAL::EQUAL));
  }
  if (psx_max == CGAL::ARR_RIGHT_BOUNDARY) {
    const auto& p_left = traits.construct_min_vertex_2_object()(c);
    auto res = cmp_x(p_left, p);
    return ((res == CGAL::SMALLER) || (res == CGAL::EQUAL));
  }
  const auto& p_left = traits.construct_min_vertex_2_object()(c);
  auto res = cmp_x(p_left, p);
  if (res == CGAL::LARGER) return false;
  const auto& p_right = traits.construct_max_vertex_2_object()(c);
  res = cmp_x(p, p_right);
  if (res == CGAL::LARGER) return false;
  return true;
}
\endcode

\cgalAdvancedEnd

<!-- ======================================================================= -->
\section aos_sec-geom_traits The Geometry Traits
<!-- ======================================================================= -->

A geometry traits class encapsulates the definitions of the geometric
entities and the implementation of the geometric predicates and
constructions that handle these geometric entities, used by the
`Arrangement_on_surface_2` class template and by the peripheral
modules. The identified minimal requirements imposed by the various
algorithms that apply to arrangements are organized in a hierarchy of
refined geometry-traits concepts.  The requirements listed by each
concept include only the utterly essential types and operations needed
to implement specific algorithms. This modular structuring yields
controllable parts that can be produced, maintained, and utilized with
less effort. For each operation, all the preconditions that its
operands must satisfy are specified as well, as these may simplify the
implementation of models of these concepts even further. Each traits
class models one or more concepts. This section contains a detailed
description of the concepts in the refinement hierarchy and the
various traits classes that model these concepts.

All the algebra required for constructing and manipulating
arrangements is concentrated in the traits classes. The knowledge
required to devise a good traits class is very different from the
knowledge required for the development of the rest of the package or
for using the package. It has less to do with computational geometry
and it involves mainly algebra and numerical computation. This way,
traits classes for new types of curves can be developed with little
knowledge of algorithms and data structures in computational
geometry. In this section we discuss how to use existing traits
classes, but we also explain the concepts these traits classes
model---a starting point for every novice developer of such classes.

This section is divided into three parts. The first part describes the
refinement hierarchy of the arrangement geometry-traits concepts. The
second part reviews various models of these concepts. These traits
classes handle different curve families, such as line segments,
polylines, conic arcs, B&eacute;zier curves, algebraic curves, and
geodesic arcs on the sphere. The last part introduces decorators for
geometric traits classes. A decorator of a traits class attaches
auxiliary data to the geometric objects handled by the original traits
class, thereby extending it.

<!-- ----------------------------------------------------------------------- -->
\subsection aos_ssec-geom_traits-concepts The Hierarchy of the Geometry Traits Concepts
<!-- ----------------------------------------------------------------------- -->

A hierarchy of related concepts can be viewed as a directed acyclic
graph, where a node of the graph represents a concept and an arc
represents a refinement relation. An arc directed from concept <span
class="textsc">A</span> to concept <span class="textsc">B</span>
indicates that concept <span class="textsc">B</span> refines concept
<span class="textsc">A</span>.  A rather large directed acyclic graph
is required to capture the entire hierarchy of the geometry
traits-class concepts. In the following sections we review individual
clusters of the graph and describe the relations between them.
\cgalFigureRef{aos_fig-central_concept_cluster} depicts the central
cluster.

<!-- ----------------------------------------------------------------------- -->
\cgalFigureBegin{aos_fig-central_concept_cluster,central_concept_cluster.png}
The hierarchy of the main geometry traits concepts.
\cgalFigureEnd
<!-- ----------------------------------------------------------------------- -->

<!-- ----------------------------------------------------------------------- -->
\subsubsection aos_sssec-geom_traits-concepts_basic The Basic Concept
<!-- ----------------------------------------------------------------------- -->

A model of the basic concept `AosBasicTraits_2` needs to
define the types \link AosBasicTraits_2::Point_2
`Point_2`\endlink and \link
AosBasicTraits_2::X_monotone_curve_2
`X_monotone_curve_2`\endlink, where objects of the former type are the
geometric mapping of arrangement vertices, and objects of the latter
type are the geometric mapping of edges. In addition, it has to
support the set of predicates listed below. This basic set of
predicates is sufficient for constructing arrangements of bounded
\f$x\f$-monotone curves that are pairwise disjoint in their interiors
and points that do not lie in the interiors of the curves. The basic
set of predicates is also sufficient for answering vertical
ray-shooting queries and point-location queries with a small
exception: Locating a point using the landmark strategy requires a
traits class that models the concept `AosLandmarkTraits_2`;
see Section \ref aos_sssec-tr_landmarks_concept.

<DL>

<DT>\link AosBasicTraits_2::Compare_x_2 <B>`Compare_x_2`</B>\endlink:
<DD>Compares the \f$x\f$-coordinates of two points.

<DT>\link AosBasicTraits_2::Compare_xy_2 <B>`Compare_xy_2`</B>\endlink:
<DD>Compares two points lexicographically, first by their
  \f$x\f$-coordinates, and if they are equal, by their
  \f$y\f$-coordinates.

<DT>\link AosBasicTraits_2::Equal_2 <B>`Equal_2`</B>\endlink:
<DD>There are two overloaded Boolean operators that test equality. One
  returns true iff two given points represent the same geometric point
  in the two-dimensional surface, and the second returns true iff the
  graphs of two given \f$x\f$-monotone curves are the
  same.\cgalFootnote{The predicate that tests equality between graphs
  of two \f$x\f$-monotone curves is used only for testing as part of
  the test suite.}

<DT>\link AosBasicTraits_2::Construct_min_vertex_2 <B>`Construct_min_vertex_2`</B>\endlink:
<DD>Returns the lexicographically smallest (or left) endpoint of an
  \f$x\f$-monotone curve.

<DT>\link AosBasicTraits_2::Construct_max_vertex_2 <B>`Construct_max_vertex_2`</B>\endlink:
<DD> Returns the lexicographically largest (or right) endpoint of an
  \f$x\f$-monotone curve.

<DT>\link AosBasicTraits_2::Is_vertical_2 <B>`Is_vertical_2`</B>\endlink:
<DD> Determines whether an \f$x\f$-monotone curve is vertical.

<DT>\link AosBasicTraits_2::Compare_y_at_x_2 <B>`Compare_y_at_x_2`</B>\endlink:
<DD>Given an \f$x\f$-monotone curve \f$c\f$ and a point \f$p\f$ that
  lies in the \f$x\f$-range of \f$c\f$, determines whether \f$p\f$ is
  below, above or lies on \f$c\f$.

<DT>\link AosBasicTraits_2::Compare_y_at_x_right_2 <B>`Compare_y_at_x_right_2`</B>\endlink:
<DD> Given two \f$x\f$-monotone curves \f$c_1\f$ and \f$c_2\f$ that
  share a common minimal (left) endpoint \f$p\f$, determines whether
  \f$c_1\f$ is above or below \f$c_2\f$ immediately to the right of
  \f$p\f$, or whether the two curves overlap there.  </DL>

Every model of the concept `AosBasicTraits_2` needs to define
a nested type named \link AosBasicTraits_2::Has_left_category
`Has_left_category`\endlink. It determines whether the traits class
supports the following predicate:

<DL>

<DT>\link AosBasicTraits_2::Compare_y_at_x_left_2 <B>`Compare_y_at_x_left_2`</B>\endlink:
<DD> Given two \f$x\f$-monotone curves \f$c_1\f$ and \f$c_2\f$ that
  share a common maximal (right) endpoint \f$p\f$, determines whether
  \f$c_1\f$ is above or under \f$c_2\f$ immediately to the left of
  \f$p\f$, or whether the two curves overlap there.

</DL>

If the `AosBasicTraits_2::Has_left_category` type nested in a
model of the basic concept is defined as `Tag_true`\cgalFootnote{In
principle, the category type may only be convertible to the tag type,
but in practice the category is typically explicitly defined as the
tag.} the model must support the predicate. If the type is defined as
`Tag_false`, we resort to an internal version, which is based just on
the reduced set of provided operations.  The internal version might be
less efficient, but it exempts the traits developer from the providing
an (efficient) implementation of this predicate---a task that turns
out to be nontrivial in some cases.

The basic set of predicates is sufficient for constructing
arrangements of \f$x\f$-monotone curves that do not reach or approach
the boundary of the parameter space. The nature of the input curves,
whether they are expected to reach or approach the left, right,
bottom, or top side of the boundary of the parameter space, must be
conveyed by the traits class. This is done through the definition of
four additional nested types, namely
<ol>
<li>\link AosBasicTraits_2::Left_side_category
`Left_side_category`\endlink,
<li>\link AosBasicTraits_2::Right_side_category
`Right_side_category`\endlink,
<li>\link AosBasicTraits_2::Bottom_side_category
`Bottom_side_category`\endlink, and
<li>\link AosBasicTraits_2::Top_side_category
`Top_side_category`\endlink.
</ol>
Each of those types must be convertible
to the type `Arr_oblivious_side_tag` for the class to be a model of
the concept `AosBasicTraits_2`.

<!-- ----------------------------------------------------------------------- -->
\subsubsection aos_sssec-geom_traits-concepts_intersecting Intersections
<!-- ----------------------------------------------------------------------- -->

Constructing an arrangement induced by \f$x\f$-monotone curves that
may intersect in their interior requires operations that are not part
of the `AosBasicTraits_2` concept. The additional operations
are listed by the concept `AosXMonotoneTraits_2`, which
refines the basic arrangement geometry-traits concept described above.
While models of the `AosXMonotoneTraits_2` concept still
handle only \f$x\f$-monotone curves, the curves are not restricted to
be disjoint in their interiors. Such a model must be capable of
computing points of intersection between \f$x\f$-monotone curves,
splitting curves at these intersection points to obtain pairs of
interior-disjoint subcurves, and optionally merging pairs of
subcurves. A point of intersection between two curves is also
represented by the \link AosBasicTraits_2::Point_2
`Point_2`\endlink type. A model of the refined concept must define an
additional type called `Multiplicity`.  An object of this type
indicates the multiplicity of the intersection point of two curves,
also referred to as the <em>intersection
number</em>.\cgalFootnote{See, e.g.,
https://en.wikipedia.org/wiki/Intersection_number for more information
about intersection numbers.} Loosely speaking, if two curves intersect
at a point \f$p\f$ but have different tangents (first derivatives) at
\f$p\f$, The point \f$p\f$ is of multiplicity 1. If the curve tangents
are equal but their curvatures (second derivatives) are not, \f$p\f$
is of multiplicity 2, and so on. The multiplicity of points of
intersection between line segments is always 1, and the multiplicity
of a point of intersection between two polylines is 1 if the
intersection point is interior to the corresponding two line segments
of the polylines, and undefined (coded as 0) otherwise. A model of the
refined concept thus has to support the following additional
operations:

<DL>

<DT>\link AosXMonotoneTraits_2::Split_2 <B>`Split_2`</B>\endlink:
<DD> Splits an \f$x\f$-monotone curve \f$c\f$ into two subcurves at a
  given point \f$p\f$ that lies in the interior of \f$c\f$.

<DT>\link AosXMonotoneTraits_2::Are_mergeable_2 <B>`Are_mergeable_2`</B>\endlink:
<DD> Determines whether two \f$x\f$-monotone curves \f$c_1\f$ and
  \f$c_2\f$ that share a common endpoint can be merged into a single
  continuous \f$x\f$-monotone curve representable by the traits
  class.\cgalFootnote{On the face of it this seems a difficult
  predicate to implement. In practice we use very simple tests to
  decide whether two curves are mergeable: We check whether their
  underlying curves are identical and whether they do not bend to form
  a non-\f$x\f$-monotone curve.}

<DT>\link AosXMonotoneTraits_2::Merge_2 <B>`Merge_2`</B>\endlink:
<DD> Merges two mergeable \f$x\f$-monotone curves into a single curve.

<DT>\link AosXMonotoneTraits_2::Intersect_2 <B>`Intersect_2`</B>\endlink:
<DD> Computes all intersection points and overlapping sections of two
  given \f$x\f$-monotone curves. If possible, computes also the
  multiplicity of each intersection point. Providing the multiplicity
  of an intersection point is not required, but it can expedite the
  arrangement construction. Typically, the multiplicity is a byproduct
  of the intersection computation. However, if it is not available,
  undefined multiplicity (coded as 0) is assumed. Having the
  multiplicity of intersection points while constructing arrangements
  enables the exploitation of the geometric knowledge intersection
  points may have.

</DL>

Using a model of the `AosXMonotoneTraits_2` it is
possible to construct arrangements of sets of \f$x\f$-monotone curves
(and points) that may intersect one another. The two operations
listed above, regarding the merging of curves, are optional, and should
be provided only if the type `Has_merge_category` nested in a model of
the `AosXMonotoneTraits_2` concept is defined as `Tag_true`.
Otherwise, it is not possible to merge \f$x\f$-monotone curve and
redundant vertices may be left in the arrangement due to the removal of
edges.

<!-- ----------------------------------------------------------------------- -->
\subsubsection aos_sssec-geom_traits-concepts_arbitrary Supporting Arbitrary Curves
<!-- ----------------------------------------------------------------------- -->

The concept `AosTraits_2` refines the
`AosXMonotoneTraits_2` concept. A model of the refined concept
must define an additional type that is used to represent general, not
necessarily \f$x\f$-monotone and not necessarily continuous, curves,
named \link AosTraits_2::Curve_2 `Curve_2`\endlink. It also
has to support the subdivision of a curve of that type into a set of
continuous \f$x\f$-monotone curves and isolated points. For example,
the curve \f$c:\ (x^2 + y^2)(x^2 + y^2 - 1) = 0\f$ comprises the unit
circle (the locus of all points for which \f$x^2 + y^2 = 1\f$) and the
origin (the singular point \f$(0,0)\f$). \f$c\f$ should therefore be
subdivided into two circular arcs, the upper part and the lower part
of the unit circle, and a single isolated point.  In particular a
model of the refined concept has to support the following additional
operation:

<DL>

<DT>\link AosTraits_2::Make_x_monotone_2 <B>`Make_x_monotone_2`</B>\endlink:

<DD> Divides a given general curve of type \link
  AosTraits_2::Curve_2 `Curve_2`\endlink into continuous weakly
  \f$x\f$-monotone curves and isolated points.

</DL>

Note that a model of the refined concept `AosTraits_2` is
required only when using the free `insert()` function templates (see
Section \ref arr_secgl_funcs) that accept an object of type \link
AosTraits_2::Curve_2 `Curve_2`\endlink or a range of objects
of that type. In all other cases it is sufficient to use a model of
the `AosXMonotoneTraits_2` concept.

<!-- ----------------------------------------------------------------------- -->
\subsubsection aos_sssec-tr_landmarks_concept The Landmark Concept
<!-- ----------------------------------------------------------------------- -->

<!-- ----------------------------------------------------------------------- -->
\cgalFigureBegin{aos_fig-landmark_concept_cluster,landmark_concept_cluster.png}
The traits-concept hierarchy for arrangements associated with the landmark
point-location strategy.
\cgalFigureEnd
<!-- ----------------------------------------------------------------------- -->

The type of an arrangement associated with the landmark point-location
strategy (see Section \ref arr_ssecpl) must be an instance of the
`Arrangement_on_surface_2<GeomTraits, TopolTraits>` class template,
where the `GeomTraits` parameter is substituted by a model of the
concept `AosLandmarkTraits_2`. (Naturally, it can also model
either the `AosXMonotoneTraits_2` concept or the
`AosTraits_2` concept.) The `AosLandmarkTraits_2`
concept refines the two concepts `AosApproximatePointTraits_2` and
`AosConstructXMonotoneCurveTraits_2`. Each of these two
concepts, in turn, refines the concept `AosBasicTraits_2`.

A model of the `AosApproximatePointTraits_2` concept must define a
fixed precision number type (typically the double-precision
floating-point `double`) and support the operation below (in addition
to fulfilling the requirements listed by the `AosBasicTraits_2`
concept).

<DL>

<DT>\link AosApproximatePointTraits_2::Approximate_2 <B>`Approximate_2`</B>\endlink:
<DD> Given a point `p`, approximate the \f$x\f$ and
\f$y\f$-coordinates of `p` using a not necessarily multi-precision
number type. We use this operation for approximate
computations---there are certain operations performed during the
search for the location of the point that need not be exact, and that
can be performed faster when carried out, for example, using a
fixed-precision number type.

</DL>

A model of the `AosConstructXMonotoneCurveTraits_2` concept
must support the operation below (in addition to fulfilling the
requirements listed by the `AosBasicTraits_2` concept).

<DL>

<DT>\link AosConstructXMonotoneCurveTraits_2::Construct_x_monotone_curve_2 <B>`Construct_x_monotone_curve_2`</B>\endlink:
<DD> Given two points \f$p_1\f$ and \f$p_2\f$, construct
an \f$x\f$-monotone curve connecting \f$p_1\f$ and \f$p_2\f$.

</DL>

Most traits classes model the `AosTraits_2` concept, and some
also model the `AosLandmarkTraits_2` concept.

The concept `AosConstructCurveTraits_2` refines the concept
`AosBasicTraits_2`. A model of the `AosConstructCurveTraits_2` concept
must support the operation below (in addition to fulfilling the
requirements listed by the `AosBasicTraits_2` concept).

<!-- ----------------------------------------------------------------------- -->
\subsubsection aos_sssec-tr_additional_concepts The Construct Curve Concept
<!-- ----------------------------------------------------------------------- -->

<DL>
<DT>\link AosConstructCurveTraits_2::Construct_curve_2 <B>`Construct_curve_2`</B>\endlink:
<DD> Given two points \f$p_1\f$ and \f$p_2\f$, construct
a curve connecting \f$p_1\f$ and \f$p_2\f$.
</DL>

The `Arr_polyline_traits_2<SubcurveTraits_2>` class template handles
polylines; see Section ~\ref arr_sssectr_polylines.
The type that substitutes the template parameter `SubcurveTraits_2`
when `Arr_polyline_traits_2<SubcurveTraits_2>` is instantiated must be
a geometry-traits class that models the concept `AosConstructCurveTraits_2`
to enable the construction of polylines from a sequence of two or more points.

<!-- ----------------------------------------------------------------------- -->
\subsubsection aos_sssec-tr_approximatetion_concept Supporting Approximations of Curves
<!-- ----------------------------------------------------------------------- -->

Operations on arrangements are guaranteed to be robust only if the
operations of the geometry traits used to carry out the high-level
operations are robust. Geometry traits constructors are guaranteed to
be robust only if the kernel in use supports exact constructions, such
as the Epec kernel. Even if you only intend to perform point-location
queries on an arrangement induced by a collection of curves, you need
an exact-construction kernel, if the curves are not pairwise disjoint
in their interiors. However, when using an exact-construction kernel
you still may desire to perform (independent) operations on
approximations of the points or the interior-disjoint \f$x\f$-monotone
curves of the arrangements in order to gain speed, for example drawing
the arrangement on a raster window.  Naturally, reconstructing an
arrangement from the approximations of its points and
interior-disjoint \f$x\f$-monotone curves, may result with an arrangement
of a different topology, or even worse, intersections in the interior
of the curves.

The concept `AosApproximateTraits_2` refines the concept
`AosApproximatePointTraits_2`. In addition to the type
`Approximate_number_type` required by the latter, a model of the
`AosApproximateTraits_2` concept must define the type
`Approximate_point_2`, which is typically defined as
`CGAL::Cartesian<Approximate_number_type>::%Point_2`. Also, it must
support the operations below (in addition to the operation required by
the concept `AosApproximatePointTraits_2`).

<DL>
<DT>\link AosApproximateTraits_2::Approximate_2 <B>`Approximate_2`</B>\endlink:
<DD>This operation is overloaded with three versions. The first one
  returns an approximation of the \f$x\f$- or \f$y\f$-coordinates of a given
  point as required by the concept `AosApproximatePointTraits_2`; see
  Section \ref aos_sssec-tr_landmarks_concept. The description of the remaining
  two follow.

  (i) Given a point \f$p\f$, obtain an approximation of \f$p\f$, which is an
    object of type `Approximate_point_2`. This is trivially
    implemented using the first version.

  (ii) Given an \f$x\f$-monotone curve \f$c\f$, a small number \f$\epsilon\f$ of
    type `Approximate_number_type` that serves as an error bound, an
    output iterator associated with a container
    of approximate points, and a flag that indicates whether to
    approximate \f$c\f$ starting from its smallest lexicographic endpoint,
    compute a polyline that approximates \f$c\f$ in the indicated
    direction, such that the largest distance between \f$c\f$ and the
    polyline is not larger than \f$\epsilon\f$. The polyline is
    represented as a sequence of approximate points.
</DL>

<!-- ----------------------------------------------------------------------- -->
\subsubsection aos_ssec-traits-curved Supporting Unbounded Curves or Curved Surfaces
<!-- ----------------------------------------------------------------------- -->

We descend to the bottom level of the hierarchy. The refinements
described in this section provide the requirements imposed on traits
classes used with arrangements induced by curves with boundary
conditions. In particular, these requirements list additional
operations that handle curves that either reach specific sides of the
parameter-space boundary (the pre-images of their endpoints lie on
boundary sides) or approach them (the pre-images of their endpoints
approach boundary sides). These boundary conditions typically occur
with unbounded curves or with arrangements embedded in curved
surfaces. The category types \link
AosBasicTraits_2::Left_side_category
`Left_side_category`\endlink, \link
AosBasicTraits_2::Right_side_category
`Right_side_category`\endlink, \link
AosBasicTraits_2::Bottom_side_category
`Bottom_side_category`\endlink, and \link
AosBasicTraits_2::Top_side_category
`Top_side_category`\endlink, nested in every geometry traits class
indicate whether the corresponding boundary side (i.e., left, right,
bottom, and top) is open, closed, contracted, or identified, and
whether this information is relevant at all. When all curves inserted
into the arrangement are expected to neither approach nor reach that
particular boundary side, the information is irrelevant. (Note that we
explicitly distinguish closed-only, contracted, and identified sides,
although the latter two are closed in the parameter space as well.)
Each one of the categories above must be convertible to one of the tag
types listed below according to the boundary condition that should be
handled.

<ul>

<li>`Arr_open_side_tag`
<li>`Arr_closed_side_tag`
<li>`Arr_contracted_side_tag`
<li>`Arr_identified_side_tag`
<li>`Arr_oblivious_side_tag`

</ul>

For each of the four sides of the parameter space there are four
available concepts, models of which can be used to handle open,
closed, contracted, and identified sides, respectively. (When curves
are expected to neither reach nor approach a particular side, special
handling is not required; thus, there is no need for a corresponding
concept.) For example, it is required that the category type \link
AosOpenBottomTraits_2::Bottom_side_category
`Bottom_side_category`\endlink, nested in models of the concept
`AosOpenBottomTraits_2`, is convertible to the tag type
`Arr_open_side_tag`.  This makes for a total of 16 abstract concepts
(combine one of left, right, bottom, and top with one of open, closed,
contracted, identified). Any one of these individual abstract concept
is useless on its own; only concepts that refine a combination of 0,
1, 2, 3, or 4 abstract concepts (which capture the conditions that
occur in the four sides simultaneously) are purposeful. Theoretically,
there are \f$\sum_{i=0}^4\binom{i}{4} \cdot 4^i = 5^4 = 625\f$ such
concepts. However, only a subset of them is meaningful. If a side is
identified, the opposite side must also be identified. In addition, a
contracted side must be adjacent to two identified sides. While this
narrows down the number of tangible concepts, the total number is
still high; in practice we have used only two so far (not counting the
"plain" concept, models of which do not handle boundary conditions at
all), namely, `AosOpenBoundaryTraits_2` and
`AosSphericalBoundaryTraits_2`; see below for more
details. Many of the traits class-templates provided by the \ref
PkgArrangementOnSurface2 package do not handle boundary conditions at
all. Some of them, such as the `Arr_segment_traits_2` traits (see
Section \ref arr_ssectr_segs) only handle bounded curves. Thus, the
four category types nested in these models are defined to be
`Arr_oblivious_side_tag`.

<!-- ----------------------------------------------------------------------- -->
\cgalFigureBegin{aos_fig-open_concept_hierarchy,open_concept_hierarchy.png}
Bottom portion of the refinement hierarchy of the geometry-traits
concepts for curves embedded in an open surface, for instance, the
entire plane.
\cgalFigureEnd
<!-- ----------------------------------------------------------------------- -->

Several predicates are required to handle \f$x\f$-monotone curves that
approach the boundary of the parameter space. These predicates are
sufficient to handle not only curves embedded in an unbounded
parameter space, but also curves embedded in a bounded parameter space
with open boundaries. The arrangement type instantiated with a traits
class that models the combined concept
`AosOpenBoundaryTraits_2` shown in
\cgalFigureRef{aos_fig-open_concept_hierarchy} can handle curves that
are open in any direction. Recall that an arrangement that supports
unbounded \f$x\f$-monotone curves maintains an implicit bounding
rectangle in the \dcel structure; see Section \ref
aos_sec-unbounded. If some curves inserted into an arrangement object
are expected to be unbounded; namely, there exists \f$d \in \{0,1\}\f$
such that \f$\lim_{t \rightarrow d}x(t) = \pm\infty\f$ or \f$\lim_{t
\rightarrow d}y(t) = \pm\infty\f$ holds for at least one input curve
\f$c(t) = (x(t),y(t))\f$, the arrangement template must be
instantiated with a model of the `AosOpenBoundaryTraits_2`
concept.\cgalFootnote{A curve that reaches the boundary of the
parameter space in this case is open and unbounded.}

<!-- ----------------------------------------------------------------------- -->
\cgalFigureBegin{aos_fig-spherical_concept_hierarchy,spherical_concept_hierarchy.png}
The entire spherical boundary cluster of the refinement hierarchy of the
geometry-traits concepts for curves embedded in a sphere-like parameterized
surface.
\cgalFigureEnd
<!-- ----------------------------------------------------------------------- -->

A suitable geometry-traits component for arrangements embedded in
surfaces homeomorphic to a sphere is a model of the combined concept
`AosSphericalBoundaryTraits_2` shown in
\cgalFigureRef{aos_fig-spherical_concept_hierarchy}. Here the two
vertical sides of the parameter space are identified and the two
horizontal sides are contracted.

<!-- ----------------------------------------------------------------------- -->
\cgalFigureBegin{aos_fig-left_side_cluster,left_side_cluster.png}
Top portion of the refinement hierarchy of the geometry-traits
concepts for curves that either reach the left side of the boundary
of the parameter space or approach it. A similar hierarchy also
exists for the right, bottom, and top sides.
\cgalFigureEnd
<!-- ----------------------------------------------------------------------- -->

The shared requirements for the four options of a side are collected
in abstract layers called `AosLeftSideTraits_2`,
`AosRightSideTraits_2`, `AosBottomSideTraits_2`, and
`AosTopSideTraits_2`; see, e.g.,
\cgalFigureRef{aos_fig-left_side_cluster}.

<!-- ----------------------------------------------------------------------- -->
\cgalFigureBegin{aos_fig-side_clusters,side_clusters.png}
Top portion of the refinement hierarchy of the geometry-traits
concepts for curves that either reach the vertical sides of the
boundary of the parameter space or approach it, and similarly for
curves that either reach or approach horizontal sides.
\cgalFigureEnd
<!-- ----------------------------------------------------------------------- -->

The shared requirements for the options of opposite sides are
collected in two additional abstract layers called
`AosVerticalSideTraits_2` and
`AosHorizontalSideTraits_2`; see
\cgalFigureRef{aos_fig-side_clusters}.

<!-- ----------------------------------------------------------------------- -->
\cgalFigureBegin{aos_fig-identified_clusters,identified_clusters.png}
Top portion of the refinement hierarchy of the geometry-traits
concepts for curves that reach the identified vertical sides of the
parameter space and for curves that reach the identified horizontal
sides of the parameter space.
\cgalFigureEnd
<!-- ----------------------------------------------------------------------- -->

Individual concepts for curves that reach the identified left side of
the parameter space and for curves that reach the identified right
side of the parameter space do not exist, because if one side is
identified the opposite side must be identified as well. Similarly,
individual concepts for curves that reach the identified bottom side
of the parameter space and for curves that reach the identified top
side of the parameter space do not exist either. Instead, the shared
requirements for opposite identified sides are collected in two
additional abstract concepts called
`AosIdentifiedVerticalTraits_2` and
`AosIdentifiedHorizontalTraits_2`; see
\cgalFigureRef{aos_fig-identified_clusters}. The former lists
requirements for operations that handle curves that reach identified
vertical sides of the parameter space, and the latter lists
requirements for operations that handle curves that reach identified
horizontal sides of the parameter space.

In the following we list the specific requirements of all the
aforementioned concepts.

The abstract concept `AosVerticalSideTraits_2` requires the
following predicate:

<DL>

<DT>\link AosVerticalSideTraits_2::Parameter_space_in_x_2 <B>`Parameter_space_in_x_2`</B>\endlink:

<DD>This three-valued predicate is overloaded with two versions as
  follows:

(i) Given a curve \f$c = (x(t), y(t))\f$ and an enumerator that
specifies either the minimum end or the maximum end of the curve, and
thus maps to a parameter value \f$d \in \{0,1\}\f$, determine the
location of the \f$d\f$-end of \f$c\f$ along the
\f$x\f$-dimension. Formally, if \f$c\f$ is open at its \f$d\f$-end,
determine whether \f$\lim_{t \rightarrow d} x(t)\f$ evaluates to
\f$x_{\rm min}\f$, \f$x_{\rm max}\f$, or a value in between. If
\f$c\f$ is not open at its \f$d\f$-end, determine whether \f$x(d)\f$
is equal to \f$x_{\rm min}\f$, \f$x_{\rm max}\f$, or a value in
between. Return `CGAL::ARR_LEFT_BOUNDARY`, `CGAL::ARR_RIGHT_BOUNDARY`,
or `CGAL::ARR_INTERIOR`, accordingly. If \f$c\f$ is vertical and lies
on a vertical boundary; that is, either \f$\forall p=(x_p, y_p) \in c\f$
we have \f$x_p = x_{\rm min}\f$ or \f$\forall p=(x_p, y_p) \in c\f$ we
have \f$x_p = x_{\rm max}\f$, then the boundary side containing \f$c\f$
cannot be open.

(ii) Given a point \f$p=(x_p, y_p)\f$, determine the location of the
point with respect to the \f$x\f$-axis. Formally, determine whether
\f$x_p\f$ is equal to \f$x_{\rm min}\f$, \f$x_{\rm max}\f$, or a value
in between. Return `CGAL::ARR_LEFT_BOUNDARY`,
`CGAL::ARR_RIGHT_BOUNDARY`, or `CGAL::ARR_INTERIOR`, accordingly. If
\f$p\f$ is on a vertical boundary; that is, \f$x_p \in \{x_{\rm
min},x_{\rm max}\}\f$, then the boundary side containing \f$p\f$
cannot be open and must not be identified. In other words, this
overloaded version is required only for the concepts
`AosClosedLeftTraits_2`, `AosClosedRightTraits_2`,
`AosContractedLeftTraits_2` and
`AosContractedRightTraits_2`.

</DL>

The abstract concept `AosHorizontalSideTraits_2` requires the
following predicate:

<DL>

<DT>\link AosHorizontalSideTraits_2::Parameter_space_in_y_2 <B>`Parameter_space_in_y_2`</B>\endlink:

<DD>This three-valued predicate is overloaded with two versions as
  follows:

(i) Given a curve \f$c = (x(t), y(t))\f$ and an enumerator that
specifies either the minimum end or the maximum end of the curve, and
thus maps to a parameter value \f$d \in \{0,1\}\f$, determine the
location of the \f$d\f$-end of \f$c\f$ along the
\f$y\f$-dimension. Formally, if \f$c\f$ is open at its \f$d\f$-end,
determine whether \f$\lim_{t \rightarrow d} y(t)\f$ evaluates to
\f$y_{\rm min}\f$, \f$y_{\rm max}\f$, or a value in between. If
\f$c\f$ is not open at its \f$d\f$-end, determine whether \f$y(d)\f$
is equal to \f$y_{\rm min}\f$, \f$y_{\rm max}\f$, or a value in
between. Return `CGAL::ARR_BOTTOM_BOUNDARY`, `CGAL::ARR_TOP_BOUNDARY`,
or `CGAL::ARR_INTERIOR`, accordingly. If \f$c\f$ is horizontal and
lies on a horizontal boundary; that is, either \f$\forall p=(x_p, y_p)
\in c, y_p = y_{\rm min}\f$ or \f$\forall p=(x_p, y_p) \in c, y_p =
y_{\rm max}\f$, then the boundary side containing \f$c\f$ cannot be
open and must not be identified.

(ii) Given a point \f$p=(x_p, y_p)\f$, determine the location of the
point along the \f$y\f$-dimension. Formally, determine whether
\f$y_p\f$ is equal to \f$y_{\rm min}\f$, \f$y_{\rm max}\f$, or a value
in between. Return `CGAL::ARR_BOTTOM_BOUNDARY`,
`CGAL::ARR_TOP_BOUNDARY`, or `CGAL::ARR_INTERIOR`, accordingly. If
\f$p\f$ is on a horizontal boundary; that is, \f$y_p \in \{y_{\rm
min},y_{\rm max}\}\f$, then the boundary side containing \f$p\f$
cannot be open and must not be identified. In other words, this
overloaded version is required only for the concepts
`AosClosedBottomTraits_2`, `AosClosedTopTraits_2`,
`AosContractedBottomTraits_2` and
`AosContractedTopTraits_2`.

</DL>

The two symmetric predicates above determine the location of a
curve-end in the parameter space. However, in general,
\f$x\f$-coordinates and \f$y\f$-coordinates are handled
differently. This asymmetry is brought on by the various algorithms
applied to arrangements, the input and output arguments of which are
\f$x\f$-monotone curves. Indeed, all curves maintained by any
arrangement are continuous weakly \f$x\f$-monotone curves. A non
\f$x\f$-monotone curve is divided into \f$x\f$-monotone sub curves
(and perhaps points) before it is inserted into an arrangement. This
asymmetry is also reflected in the predicates listed below. They help
determining the order of curve-ends lying on the boundary of the
parameter space with respect to regular points and among each other.

The concepts `AosClosedLeftTraits_2`,
`AosClosedRightTraits_2`, and
`AosIdentifiedVerticalTraits_2` require the following
additional predicate:

<DL>

<DT>\link AosIdentifiedVerticalTraits_2::Compare_y_on_boundary_2 <B>`Compare_y_on_boundary_2`</B>\endlink:

<DD>Given two points \f$p_1=(x_{p_1},y_{p_1})\f$ and
\f$p_2=(x_{p_2},y_{p_2})\f$, such that at least one of them lies on a
vertical boundary side, compare the \f$y\f$-coordinates of the
points. That is, compare \f$y_{p_1}\f$ and \f$y_{p_2}\f$. If \f$p_1\f$
(resp. \f$p_2\f$) is on the boundary; that is, \f$x_{p_1} \in \{x_{\rm
min},x_{\rm max}\}\f$ (resp. \f$x_{p_2} \in \{x_{\rm min},x_{\rm
max}\}\f$), then the vertical boundary side containing \f$p_1\f$
(resp. \f$p_2\f$) must be either closed or identified. In other words,
this overloaded version is required only for the concepts
`AosClosedLeftTraits_2`, `AosClosedRightTraits_2`, and
`AosIdentifiedVerticalTraits_2`.

</DL>

The concept `AosVerticalSideTraits_2` requires the following additional predicate:

<DL>

<DT>\link AosVerticalSideTraits_2::Compare_y_near_boundary_2 <B>`Compare_y_near_boundary_2`</B>\endlink:

<DD>
<table border="0" cellspacing="10">
<tr>
<td>
\image html compare_y_near_boundary.png
\image latex compare_y_near_boundary.png
</td>
<td>

Given two \f$x\f$-monotone curves \f$c_1\f$ and \f$c_2\f$, and an
enumerator \f$i\f$ that specifies either the minimum ends or the
maximum ends of the two curves, and thus maps to a parameter value
\f$d \in \{0,1\}\f$, compare the \f$y\f$-coordinates of the curves
near their respective ends. More precisely, compare the
\f$y\f$-coordinates of the vertical projections of a point \f$p\f$
onto \f$c_1\f$ and onto \f$c_2\f$. If the enumerator \f$i\f$ specifies
the minimum ends, the curves must approach the left boundary-side. In
this case \f$p\f$ is located sufficiently close to the left
boundary-side, such that the result is invariant under a translation
of \f$p\f$ closer to the left boundary-side. If \f$i\f$ specifies the
maximum ends, the curves must approach the right boundary-side. In
that case \f$p\f$ is located sufficiently close to the right
boundary-side in a similar manner.

</td>
</tr>
</table>

</DL>

The concept `AosHorizontalSideTraits_2` requires two additional
predicates:

<DL>

<DT>\link AosHorizontalSideTraits_2::Compare_x_on_boundary_2 <B>`Compare_x_on_boundary_2`</B>\endlink:

<DD>This predicate is overloaded with three versions.
We distinguish between open and non-open sides as explained below.

(i) Given a regular point \f$p=(x_p,y_p)\f$, an \f$x\f$-monotone curve
\f$c = (x(t),y(t))\f$, and an enumerator that specifies either the
minimum end or the maximum end of the curve, and thus maps to a
parameter value \f$d \in \{0,1\}\f$, compare the \f$x\f$-coordinate of
\f$p\f$ and the \f$x\f$-coordinate of \f$c\f$ at its respective limit
or end depending on whether it is open or non-open. More precisely, if
\f$c\f$ is open at its \f$d\f$-end, compare the values \f$x_p\f$ and
\f$\lim_{t \rightarrow d} x(t)\f$. A precondition assures that \f$c\f$
has a vertical asymptote at its \f$d\f$-end; that is \f$\lim_{t
\rightarrow d} x(t)\f$ is a real value. If \f$c\f$ is not open,
compare the values \f$x_p\f$ and \f$x(d)\f$.

<table border="0" cellspacing="10">
<tr>
<td>
\image html compare_x_on_boundary.png
\image latex compare_x_on_boundary.png
</td>
<td>

(ii) Given two curves \f$c_1 = (x_1(t),y_1(t))\f$ and \f$c_2 =
(x_2(t),x_2(t))\f$ and enumerators that specify either the minimum end
or the maximum end of each curve, and thus map to parameter values
\f$d_1, d_2 \in \{0,1\}\f$, compare the \f$x\f$-coordinates of the
curves at their respective limits or ends. More precisely, if
\f$c_1\f$ (resp. \f$c_2\f$) is open at its \f$d_1\f$-end
(resp. \f$d_2\f$-end), use the value \f$\lim_{t \rightarrow d_1}
x_1(t)\f$ (resp. \f$\lim_{t \rightarrow d_2} x_2(t)\f$) for the
comparison.  A precondition assures that \f$c_1\f$ (resp. \f$c_2\f$)
has a vertical asymptote at its \f$d_1\f$-end (resp. \f$d_2\f$-end);
that is \f$\lim_{t \rightarrow d_1} x_1(t)\f$ is (resp. \f$\lim_{t
\rightarrow d_2} x_2(t)\f$) a real value. If \f$c_1\f$
(resp. \f$c_2\f$) is not open at its \f$d_1\f$-end
(resp. \f$d_2\f$-end), use the value \f$x_1(d_1)\f$
(resp. \f$x_2(d_2)\f$) for the comparison.

</td>
</tr>
</table>

(iii) Given two points \f$p_1=(x_{p_1},y_{p_1})\f$ and
\f$p_2=(x_{p_2},y_{p_2})\f$, such that at least one of them lies on a
horizontal boundary side, compare the \f$x\f$-coordinates of the
points. That is, compare \f$x_{p_1}\f$ and \f$x_{p_2}\f$. If \f$p_1\f$
(resp. \f$p_2\f$) is on the boundary; that is, \f$y_{p_1} \in \{y_{\rm
min},y_{\rm max}\}\f$ (resp. \f$y_{p_2} \in \{y_{\rm min},y_{\rm
max}\}\f$), then the boundary side containing \f$p_1\f$
(resp. \f$p_2\f$) must be either closed or identified. In other words,
this overloaded version is required only for the concepts
`AosClosedBottomTraits_2`, `AosClosedTopTraits_2`,
and `AosIdentifiedHorizontalTraits_2`.

<DT>\link AosHorizontalSideTraits_2::Compare_x_near_boundary_2
<B>`Compare_x_near_boundary_2`</B>\endlink:

<DD>
<table border="0" cellspacing="10">
<tr>
<td>
\image html compare_x_near_boundary.png
\image latex compare_x_near_boundary.png
</td>
<td>

Given two \f$x\f$-monotone curves \f$c_1\f$ and \f$c_2\f$ and an
enumerator \f$i\f$ that specifies either the minimum ends or the
maximum ends of the two curves, and thus map to parameter values
\f$d_1, d_2 \in \{0,1\}\f$, respectively, compare the
\f$x\f$-coordinate of the curves near their respective limits or
ends. A precondition assures that the \f$x\f$-coordinates of the
limits or ends of the curves at their respective ends are equal. That
is, the predicate `Compare_x_on_boundary_2` applied to \f$c_1\f$,
\f$c_2\f$, and \f$i\f$ evaluates to `CGAL::EQUAL`.  Formally, compare
the \f$x\f$-coordinates of the horizontal projection of a point
\f$p\f$ onto \f$c_1\f$ and onto \f$c_2\f$. A precondition assures that
\f$c_1\f$ and \f$c_2\f$ have vertical asymptotes at their respective
ends. Furthermore, both curves approach the same boundary-side, either
the bottom or the top, at their respective ends. If both curves
approach the bottom boundary-side, \f$p\f$ is located far to the
bottom, such that the result is invariant under a translation of
\f$p\f$ farther to the bottom. If both curves approach the top
boundary-side, \f$p\f$ is located far to the top in a similar manner.

</td>
</tr>
</table>

</DL>

The concept `AosIdentifiedVerticalTraits_2` requires the following
additional predicate:

<DL>

<DT>\link AosIdentifiedVerticalTraits_2::Is_on_y_identification_2 <B>`Is_on_y_identification_2`</B>\endlink:

<DD>This predicate is overloaded with two versions.

(i) Given a point \f$p=(x_p, y_p)\f$, determine whether \f$p\f$ lies
in the image of the vertical (and identified) sides of the
boundary. More precisely, determine whether \f$x_p \in \{x_{\rm
min},x_{\rm max}\}\f$ for all pre-images of \f$p\f$.

(ii) Given a curve \f$c\f$, determine whether the entire curve \f$c\f$
lies in the image of the vertical (and identified) sides of the
boundary.

</DL>

Similarly, the concept `AosIdentifiedHorizontalTraits_2`
requires the following additional predicate:

<DL>

<DT>\link AosIdentifiedHorizontalTraits_2::Is_on_x_identification_2 <B>`Is_on_x_identification_2`</B>\endlink:

<DD>This predicate is overloaded with two versions.

(i) Given a point \f$p=(x_p, y_p)\f$, determine whether \f$p\f$ lies
in the image of the horizontal (and identified) sides of the
boundary. More precisely, determine whether \f$y_p \in \{y_{\rm
min},y_{\rm max}\}\f$ for all pre-images of \f$p\f$.

(ii) Given a curve \f$c\f$, determine whether the entire curve \f$c\f$
lies in the image of the horizontal (and identified) sides of the
boundary.

</DL>

<!-- ----------------------------------------------------------------------- -->
\subsection aos_ssec-geom_traits-models Models of the Geometry Traits Concepts
<!-- ----------------------------------------------------------------------- -->

In this section we review the traits classes that are models of
concepts introduced in the previous sections. They handle line
segments, circular arcs, polylines, conic arcs, rational functions,
arcs of B&eacute;zier, and arcs of algebraic curves.  The last
subsection describes decorators for geometric traits classes
distributed with \cgal, which extend geometric traits-classes by
attaching auxiliary data with the geometric objects.

<!-- ----------------------------------------------------------------------- -->
\subsubsection arr_ssectr_segs Traits Classes for Line Segments and Linear Objects
<!-- ----------------------------------------------------------------------- -->

There are two distinct traits classes that handle line segments. One
caches information in the curve records (see Section \ref
arr_sssectr_caching_segs), while the other retains the minimal amount
of data (see Section \ref arr_sssectr_non_caching_segs). Operations
on arrangements instantiated with the former traits class consume more
space, but they are more efficient for dense arrangements (namely,
arrangements induced by line segments with a large number of
intersections). Another model handles not only (bounded) line
segments, but also rays and lines; see Section \ref
arr_sssectr_linear.

<!-- ----------------------------------------------------------------------- -->
\paragraph arr_sssectr_caching_segs The Caching Segment-Traits Class
<!-- ----------------------------------------------------------------------- -->

An instance of the `Arr_segment_traits_2<Kernel>` class template used
in most example programs so far is instantiated by substituting the
`Kernel` template parameter with a geometric kernel that must conform
to the `Kernel` concept; see Package \ref PkgKernel23Concepts. This
traits class defines its point type to be the `Kernel::Point_2`
type. However, neither the \link Arr_segment_traits_2::Curve_2
`Curve_2`\endlink nor the \link
Arr_segment_traits_2::X_monotone_curve_2 `X_monotone_curve_2`\endlink
nested types of the traits are defined as the `Kernel::Segment_2`
type. A kernel segment is represented by its two endpoints, and these
may have a large bit size representation when the segment is the
result of several split operations in comparison with the
representation of the original-segment endpoints. The large bit size
representation may significantly slow down the various traits-class
operations involving such segments. (A straightforward solution would
be to repeatedly normalize the results of all computations. However,
our experience shows that indiscriminate normalization considerably
slows down the arrangement construction.)

In contrast, the `Arr_segment_traits_2` class template represents a
segment using its supporting line in addition to the two endpoints.
Most computations are performed on the supporting line, which never
changes as the segment is split. The `Arr_segment_traits_2` class
template also caches some additional information with each segment to
speed up various predicates, i.e., two Boolean flags indicating (i)
whether the segment is vertical and (ii) whether the segment
target-point is lexicographically larger than its source.  The
calculation of the supporting line and two Boolean flags is delayed to
the point in time when needed to achieve further improvement in
efficiency. An \link Arr_segment_traits_2::X_monotone_curve_2
`X_monotone_curve_2`\endlink object is still constructible from two
endpoints or from a kernel segment and converted to an
`X_monotone_curve_2` object. Moreover, an \link
Arr_segment_traits_2::X_monotone_curve_2 `X_monotone_curve_2`\endlink
instance can also be cast or to a `Kernel::Segment_2` object. The two
types are thus convertible to one another.

Computing the intersection between two segments is preceded by an
application of an efficient predicate that tests whether an
intersection exists at all. This optimization has negligible overhead;
Thus, using an instance of the `Arr_segment_traits_2<Kernel>` class
template is still very efficient when constructing arrangements
induced by line segments with a large number of intersections.
Efficiency is affected by the substituted geometric kernel. Using
`Exact_predicates_exact_constructions_kernel` as the kernel type is in
general not a bad choice; the coordinates of the segment endpoints are
represented as multi-precision rational numbers, which ensures the
correctness of all computations regardless of the input.  Computations
on multi-precision number types (such as `Gmpq`) take longer than
computations on machine-precision floating-point. A kernel object of
the aforementioned type uses numerical filtering to expedite
computation; see `Kernel_2` and `Kernel_3`. If the input set of line
segments do not have degeneracies; namely, no two segments in the set
share a common endpoint, and no three segments intersect at a common
point, or at least, degeneracies exist but their number is relatively
small, then filtered computation incurs only negligible overhead
compared to floating-point arithmetic, which is error-prone. Indeed,
in almost all examples and applications given in this manual, the
predefined filtered kernel
`Exact_predicates_exact_constructions_kernel` is used to instantiate
the line-segment traits class.

<!-- ----------------------------------------------------------------------- -->
\cgalFigureBegin{aos_figpredef_kernels,fan_grids.png,Europe.png}
(a) An arrangement of \f$104\f$ line segments from the input file
`fan_grids.dat`. (b) An arrangement of more than \f$3000\f$ interior
disjoint line segments, defined in the input file `Europe.dat`.
\cgalFigureEnd
<!-- ----------------------------------------------------------------------- -->

In the following example we use the predefined
`Exact_predicates_exact_constructions_kernel` for instantiating our
segment-traits class. This kernel uses interval arithmetic to filter
the exact computations. The program reads a set of line segments with
integer coordinates from a file and computes their arrangement. By
default it opens the `fan_grids.dat` input-file, located in the
examples folder, which contains \f$104\f$ line segments that form
four "fan-like" grids and induce a dense arrangement, as illustrated
in \cgalFigureRef{aos_figpredef_kernels} (a):

\cgalExample{Arrangement_on_surface_2/predefined_kernel.cpp}

<!-- ----------------------------------------------------------------------- -->
\paragraph arr_sssectr_non_caching_segs The Non-Caching Segment-Traits Class
<!-- ----------------------------------------------------------------------- -->

The arrangement package offers an alternative segment-traits class
template that handles line segments, namely the
`Arr_non_caching_segment_basic_traits_2<Kernel>` class template.  This
class template and the `Arr_segment_traits_2<Kernel>` class template
are both parameterized by a geometric kernel and model the concepts
`AosTraits_2` and `AosLandmarkTraits_2`.
\cgalFootnote{They also model the refined concept
\cgalFootnoteCode{AosDirectionalXMonotoneTraits_2}, which enables Boolean set
operations; see Package \ref PkgBooleanSetOperations2.} The class
template `Arr_non_caching_segment_traits_2<Kernel>` derives from the
instance `Arr_non_caching_segment_basic_traits_2<Kernel>`, which
models the `AosLandmarkTraits_2` traits concept but not the
refined `AosXMonotoneTraits_2` concept. Like the
`Arr_segment_traits_2` class template it derives from the `Kernel`
type. Unlike the `Arr_segment_traits_2` class template it defines its
point and segment types as `Kernel::Point_2` and `Kernel::Segment_2`,
respectively, and most of its defined operations are delegations of
the corresponding operations of the `Kernel` type. For example, the
functor `Compare_xy_2` is defined as `Kernel::Compare_xy_2`. The
remaining operations are defined in terms of just a few other kernel
operations. For example, the `Compare_y_at_x_right_2` predicate is
defined in terms of the `Kernel::Compare_slope_2` predicate (ignoring
preconditions for the sake of clarity); see Section \ref
aos_sssec-geom_traits-concepts_basic for the description of this
predicate.  The class template
`Arr_non_caching_segment_basic_traits_2<Kernel>` is slightly less
efficient than the `Arr_segment_traits_2` class template for
constructing arrangements of pairwise interior-disjoint line-segments
in many cases, as it does not exploit caching at all. Nevertheless,
you may choose to use this traits class, as it consumes less
memory. For arrangements of line segments that do intersect you may
use the class template
`Arr_non_caching_segment_traits_2<Kernel>`. However, the performance
difference in favor of the `Arr_segment_traits_2` class template is
much larger, especially when the number of intersections is large.

In the following example we read an input file containing a set of
line segments that are pairwise disjoint in their interior. As the
segments do not intersect, no new points are constructed and we can
instantiate the `Arr_non_caching_segment_traits_basic_2<Kernel>`
class-template with the predefined
`Exact_predicates_inexact_constructions_kernel`. Note that we use the
`insert_non_intersecting_curves()` function to construct the
arrangement.  By default, the example opens the `Europe.dat`
input-file, located in the examples folder, which contains more than
\f$3000\f$ line segments with floating-point coordinates that form
the map of Europe, as depicted in
\cgalFigureRef{aos_figpredef_kernels} (b):

\cgalExample{Arrangement_on_surface_2/predefined_kernel_non_intersecting.cpp}

<!-- ----------------------------------------------------------------------- -->
\paragraph arr_sssectr_linear The Linear-Traits Class
<!-- ----------------------------------------------------------------------- -->

The `Arr_linear_traits_2<Kernel>` class used in Section \ref
aos_sec-unbounded for demonstrating the construction of arrangements
of unbounded curves is capable of handling bounded and unbounded
linear objects, namely, lines, rays, and line segments. It models the
concepts `AosTraits_2`, `AosLandmarkTraits_2`, and
`{AosOpenBoundaryTraits_2`. It is parameterized by a geometric
kernel and its nested \link Arr_linear_traits_2::Point_2
`Point_2`\endlink type is defined to be the kernel-point type. The
\link Arr_linear_traits_2::Curve_2 `Curve_2`\endlink (and \link
Arr_linear_traits_2::X_monotone_curve_2 `X_monotone_curve_2`\endlink)
nested types are constructible from a `Kernel::Line_2`, a
`Kernel::Ray_2`, or from a `Kernel::Segment_2` object. Given a
linear-curve object \f$c\f$, you can use the calls `c.is_line()`,
`c.is_ray()`, and `c.is_segment()` to find out whether it has a source
point or a target point. Based on the curve type, you can access its
endpoints using the methods `c.source()` (for rays and for line
segments) and `c.target()` (for segments only). It is also possible to
cast a curve into a `Kernel::Line_2`, a `Kernel::Ray_2`, or a
`Kernel::Segment_2` type, using the methods `c.line()`, `c.ray()`, and
`c.segment()`, respectively.  Just like the default segment-traits
class, the linear-curve traits class uses caching techniques to speed
up its predicate evaluations and object constructions.

<!-- ----------------------------------------------------------------------- -->
\subsubsection arr_ssectr_polylines The Polyline and Polycurve Traits Classes
<!-- ----------------------------------------------------------------------- -->

Polylines are continuous piecewise linear curves. Polylines are of
particular interest, as they can be used to approximate more complex
curves in the plane. At the same time they are easier to handle in
comparison to higher-degree algebraic curves, as rational arithmetic
is sufficient to carry out computations on polylines, and to construct
arrangements of polylines in an exact and robust manner. Here, we
extend the notion of polylines and use the term to refer to chains of
subcurves that are not necessarily linear. However, each subcurve must
be uniquely defined by (and, thus, can be uniquely constructed from)
two points within the handled family of curves; see Section \ref
arr_sssectr_polylines. We also provide a similar traits class that
handles continuous piecewise curves that are not necessarily linear
and are not subject to the aforementioned constraint; see Section \ref
arr_sssectr_polycurves.

<!-- ----------------------------------------------------------------------- -->
\paragraph arr_sssectr_polylines The Polyline Traits Class
<!-- ----------------------------------------------------------------------- -->

The `Arr_polyline_traits_2<SubcurveTraits_2>` class template handles
polylines. It models the following four concepts:

- `AosTraits_2`,

- `AosDirectionalXMonotoneTraits_2`

- `AosConstructXMonotoneCurveTraits_2`, and

- `AosConstructCurveTraits_2`.

The type that substitutes the template parameter `SubcurveTraits_2`
when `Arr_polyline_traits_2<SubcurveTraits_2>` is instantiated must be
a geometry-traits class that models the same four concepts.  We refer
to the type that substitutes the template parameter `SubcurveTraits_2`
as the <em>subcurve traits</em> hereafter.  If, in addition, the
subcurve traits also models the concept
`AosApproximatePointTraits_2` then the instantiated
`Arr_polyline_traits_2<SubcurveTraits>` type models the concept
`AosApproximatePointTraits_2` as well. (By definition, modeling the
concepts `AosApproximatePointTraits_2` and
`AosConstructXMonotoneCurveTraits_2` implies modeling the
concept `AosLandmarkTraits_2`.) Similarly, if the subcurve
traits also models the concept `AosOpenBoundaryTraits_2` then
the instantiated `Arr_polyline_traits_2<SubcurveTraits>` type models
the concept `AosOpenBoundaryTraits_2` as well. Modeling the
`AosConstructXMonotoneCurveTraits_2` concept implies that the
subcurve traits must support the construction of a unique
(\f$x\f$-monotone) segment given two input points.

An instance of the polyline traits class-template inherits its nested
point type, i.e., \link Arr_polyline_traits_2::Point_2
`Point_2`\endlink, from the subcurve traits, and defines the nested
types \link Arr_polyline_traits_2::Curve_2 `Curve_2`\endlink and \link
Arr_polyline_traits_2::X_monotone_curve_2
`X_monotone_curve_2`\endlink, which are used to represent polylines
and \f$x\f$-monotone polylines, respectively.  A polyline of the
nested type \link Arr_polyline_traits_2::Curve_2 `Curve_2`\endlink is
stored as a vector of `SubcurveTraits_2::Curve_2` objects, and an
\f$x\f$-monotone polyline of the nested type \link
Arr_polyline_traits_2::X_monotone_curve_2 `X_monotone_curve_2`\endlink
is stored as a vector of `SubcurveTraits_2::X_monotone_curve_2`
objects.  The nested `X_monotone_curve_2` type inherits from the
nested type \link Arr_polyline_traits_2::Curve_2 `Curve_2`\endlink.
By default, `Arr_segment_traits_2` is used as the subcurve traits (in
case where the `SubcurveTraits_2` parameter is omitted). In this case
the nested types `SubcurveTraits_2::Curve_2` and
`SubcurveTraits_2::X_monotone_curve_2` are identical types
representing line segments.

A polyline can be constructed given one of the following inputs:

- <b>A range of <em>points</em></b>, where two succeeding points in the
  range represent the endpoints of a segment of the polyline.

- <b>A range of <em>segments</em></b>.

- <b>A pair of points \a or a single segment</b>. In this case a polyline
  that consists of a single segment is constructed.

Note that degenerate polylines are not supported. That is, it is
impossible to construct a polyline that contains a segment of length
zero, or an isolated point. Finally, a polyline is
<b><em>continuous</em></b> and <b><em>well-oriented</em></b>.
Moreover, the target of the \f$i\f$th segment is the source of
the \f$i+1\f$st segment. If the macro `CGAL_ALWAYS_LEFT_TO_RIGHT` is
set to 1, then \f$x\f$-monotone polylines are always directed from
left-to-right. (This option is retained for backward compatibility.)
Also, note that a single polyline can be split into several
\f$x\f$-monotone polylines, and that the number of intersection points
(or overlapping sections) between two polylines can be large.

For example, the general polyline

\image html generic-polyline.png
\image latex generic-polyline.png

can be represented by one of the following two orientations.

\image html well_oriented_polyline.png
\image latex well_oriented_polyline.png

Distinct \f$x\f$-monotone polylines are rendered in different colors.

\cgalAdvancedBegin
Technically speaking, it is possible to construct a general polyline
that is neither well-oriented nor continuous. However, it is
impossible to use such polylines for the purpose of computing an
arrangement.
\cgalAdvancedEnd

The polyline traits class also supports the traversal over the range
of defining segments of a given polyline. The \a first and \a
past-the-end iterators can be obtained through the access methods
\link
CGAL::Arr_polyline_traits_2::X_monotone_curve_2::begin_segments()
`begin_segments()`\endlink and \link
CGAL::Arr_polyline_traits_2::X_monotone_curve_2::end_segments()
`end_segments()`\endlink, respectively, of a polyline \f$c\f$. The
vertices of an \f$x\f$-monotone curve are always stored in a strongly
monotonic lexicographical order.  In other words, \f$x\f$-monotone
polylines can be directed \a either left-to-right \a or right-to-left.

The polyline-traits class does not perform any geometric operations
directly. Instead, it solely relies on the functionality of the
segment traits. For example, when we need to determine the position of
a point with respect to an \f$x\f$-monotone polyline, we use binary
search to locate the relevant segment that contains the point in its
\f$x\f$-range. Then, we compute the position of the point with respect
to this segment. Thus, operations on \f$x\f$-monotone polylines of
size \f$m\f$ typically take \cgalBigO{\log m} time.

You are free to choose the underlying segment traits class. Your
decision could be based, for example, on the number of expected
intersection points; see Section \ref arr_ssectr_segs. Moreover, it is
possible to substitute the `SubcurveTraits_2` template parameter with
a traits class that handles segments with some additional data
attached to each individual segment; see Section \ref
arr_sssec_tr_data_decorators. This makes it possible to associate
different data objects with the different segments that compose a
polyline.

<!-- ----------------------------------------------------------------------- -->
\cgalFigureBegin{aos_fig-polylines,polylines.png}

An arrangement of three polylines, as constructed in \ref
Arrangement_on_surface_2/polylines.cpp. Red disks mark vertices
associated with polyline endpoints, while rings mark vertices that
correspond to intersection points. The target endpoint of \f$\pi_3\f$
is also an intersection point; it is rendered as a ring. Observe that
the polyline \f$\pi_2\f$ is split into three \f$x\f$-monotone
polylines, and that the two curves \f$\pi_1\f$ and \f$\pi_3\f$ have
two overlapping sections---an impossible scenario in arrangements of
line segments.  \cgalFigureEnd
<!-- ----------------------------------------------------------------------- -->

The following example program constructs an arrangement of three
polylines, \f$\pi_1\f$, \f$\pi_2\f$, and \f$\pi_3\f$, as depicted in
\cgalFigureRef{aos_fig-polylines}. In this example, each polyline is
constructed from points stored in a different container, i.e., array,
list, and vector. Points defining the polylines are not necessarily
associated with arrangement vertices. The arrangement vertices are
either the extreme points of each \f$x\f$-monotone polyline (drawn as
red discs) or the intersection points between two polylines (drawn as
rings).

\cgalExample{Arrangement_on_surface_2/polylines.cpp}

The common types used by the example programs involving arrangements
of polylines are listed below, and defined in the header file
`arr_polylines.h`. As we do in the case of segments and linear
objects, we use the predefined kernel to instantiate our traits class.
However, in this case we have yet another layer of template
instantiation, namely the instantiation of the polyline-traits
class-template with an instance of a subcurve traits
class-template. Naturally, we use the `Arr_segment_traits_2` class
template, instantiated with the predefined filtered kernel.

\code{.cpp}
#include <CGAL/Exact_predicates_exact_constructions_kernel.h>
#include <CGAL/Arr_segment_traits_2.h>
#include <CGAL/Arr_polyline_traits_2.h>
#include <CGAL/Arrangement_2.h>

using Kernel = CGAL::Exact_predicates_exact_constructions_kernel;
using Number_type = Kernel::FT;

using Segment_traits = CGAL::Arr_segment_traits_2<Kernel>;
using Traits = CGAL::Arr_polyline_traits_2<Segment_traits>;
using Point = Traits::Point_2;
using Polyline = Traits::Curve_2;
using Arrangement = CGAL::Arrangement_2<Traits>;
\endcode

<!-- ----------------------------------------------------------------------- -->
\paragraph arr_sssectr_polycurves The Polycurve Traits Class
<!-- ----------------------------------------------------------------------- -->

The traits class `Arr_polycurve_traits_2<SubcurveTraits_2>` handles
piecewise curves that are not necessarily linear, such as conic arcs,
circular arcs, B&eacute;zier curves, or line segments. We call such a
compound curve a <em>polycurve</em>. Similar to a polyline, a
polycurve is a chain of subcurves, where each two neighboring
subcurves in the chain share a common endpoint; that is, the polycurve
is continuous. As a matter of fact, most characteristics of the
`Arr_polyline_traits_2<SubcurveTraits_2>` traits class template apply
also to the `Arr_polycurve_traits_2<SubcurveTraits_2>` traits class
template. The only difference between the two, is that the latter is
not a model of the concepts
`AosConstructXMonotoneCurveTraits_2` nor
`AosConstructCurveTraits_2`, and as such, it is not
able to construct a subcurve from only two points. As a consequence,
it does not support the operations that (i) construct a polycurve from
a sequence of points, and (ii) push a point at the back or at the
front of a non-empty polycurve.

<!-- ----------------------------------------------------------------------- -->
\subsubsection arr_ssectr_algebraic Traits Classes for Algebraic Curves
<!-- ----------------------------------------------------------------------- -->

A curve in our context is typically (but not necessarily) defined as
the zero set of a bivariate nonzero polynomial with rational (or,
equivalently, integral) coefficients. We call such polynomials and the
curves they define \a algebraic. When dealing with linear curves
(e.g., line segments and polylines), having rational coefficients
guarantees that all intersection points also have rational
coordinates, such that the arrangement of such curves can be
constructed and maintained using only rational arithmetic. The \ref
PkgArrangementOnSurface2 package also offers geometry traits-classes
that handle algebraic curves defined by algebraic polynomials of
degree higher than~\f$1\f$. Unfortunately, the coordinates of the
intersection points constructed by these traits models are in general
algebraic numbers\cgalFootnote{A number is called \a algebraic, if it
is the root of a univariate algebraic polynomial with rational
coefficients.} of degree higher than \f$1\f$. It is therefore clear
that we have to use number types different from plain rational to
represent point coordinates and be able to apply arithmetic operations
on them.

Several types of algebraic curves are handled by more than one traits
model.  Section \ref arr_sssectr_linear introduces a few different
traits models that handle line segments. This duplication becomes more
evident with the introduction of traits classes that handle algebraic
curves. The different traits models have different properties. In some
cases they were developed by different authors at different times
exploiting different tools that were available at the time they were
developed. As a general rule, you should always use the minimal traits
model that still satisfies your needs, as the most dedicated model is
most likely to be the most efficient.

<!-- ----------------------------------------------------------------------- -->
\paragraph arr_sssectr_circ_seg Circular Arcs and Line Segments
<!-- ----------------------------------------------------------------------- -->

Arrangement of circular arcs and of line segments are very useful and
frequently arise in applications, where curves of interleaved line
segments and circular arcs are used to model the boundaries of complex
shapes. Such curves can fit the original boundary more tightly and
more compactly than, for example, a simple polyline. For example, when
dilating a polygon by some radius we obtain a shape whose boundary
comprises of line segments, which correspond to dilated polygon edges,
and circular arcs, which result from dilated polygon vertices. Using
the arrangement of the boundary curves it is possible, for example, to
compute the union of a set of dilated polygons.  Besides the
importance of arrangements of circular arcs and line segments it turns
out that it is possible to implement efficient traits models that
handle curves restricted to circular arcs and line segments. Rational
numbers cannot represent the coordinates of intersection points that
may arise in such arrangements in an exact manner. Thus, algebraic
numbers must be used. However, the performance impact that (general)
algebraic numbers incur can be reduced by the use of an efficient type
of exact algebraic numbers called <em>square root extension</em> that
uses rational arithmetic in an almost straightforward fashion.

Square root numbers have the form \f$\alpha + \beta\sqrt{\gamma}\f$,
where \f$\alpha\f$, \f$\beta\f$, and \f$\gamma\f$ are rational
numbers. (Square root numbers are also called one-root numbers.) The
rational number \f$\gamma\f$ is referred to as the extension. Each
subset that has a particular extension is closed under arithmetic
operations and order relations; hence, it is a valid algebraic
structure.\cgalFootnote{The term algebraic structure refers to the set
closed under one or more operations satisfying some axioms; see, e.g.,
https://en.wikipedia.org/wiki/Algebraic_structure.  For example, all
numbers that can be expressed as \f$\alpha + \beta\sqrt{K}\f$, where
\f$\alpha\f$ and \f$\beta\f$ are rational and \f$K\f$ is a rational
constant, compose an algebraic structure.}  The class template
`CGAL::Sqrt_extension<NT,Root>` implements the square root extension
type. Instances of this template represent square root numbers. It is
equipped with the implementation of a set of arithmetic operations and
order relations that exploit identical extensions of operands. It also
provides the ability to compare two numbers with different extensions
\f$\gamma_1 \neq \gamma_2\f$ efficiently. Each operation is
implemented using only few rational arithmetic operations. Here, `NT`
is the type of \f$\alpha\f$ and \f$\beta\f$, and `Root` is the type of
\f$\gamma\f$.  The running times of the arithmetic operations and
order relations provided by the square root extension when the
identical-extension condition is met are comparable to the running
times of the corresponding arithmetic operations of rational-number
types. The running times of order relations when the condition is not
met are only slightly larger. In practice, using number types that
represent (arbitrary) algebraic numbers increases the running time of
the application significantly.

We call circles whose center coordinates and squared radii are
rational numbers <em>rational circles</em>. The equation of such a
circle, that is, \f$(x - x_0)^2 + (y - y_0)^2 = r^2\f$, where
\f$(x_0,y_0)\f$ and \f$r\f$ denote the circle center and its radius,
respectively, has rational coefficients. The coordinates of the points
of intersection between two such circles are therefore solutions of
quadratic equations with rational coefficients, in other words,
algebraic numbers of degree~\f$2\f$ or simply square root numbers. The
same applies to intersection points between such a rational circle and
a line, or a line segment, with rational coefficients (a line whose
equation is \f$ax + by + c = 0\f$, where \f$a\f$, \f$b\f$, and \f$c\f$
are rational).

The \ref PkgArrangementOnSurface2 package offers a traits
class-template called `Arr_circle_segment_traits_2<Kernel>` that
exclusively handles line segments, circular arcs, and whole circles
and models the concepts `AosTraits_2` and
`AosDirectionalXMonotoneTraits_2`; see Package \ref
PkgBooleanSetOperations2Ref. Note that it is not a model of the
`AosLandmarkTraits_2` concept.  It exploits efficient
computations with square root numbers, which makes it attractive for
arrangements induced by line segments, circular arcs, and whole
circles.  When the traits class-template is instantiated, the `Kernel`
template parameter must be substituted by a geometric kernel that
models the `Kernel` concept. Always plug in a kernel that uses a
rational number type, such as
`Exact_predicates_exact_constructions_kernel`. Observe that the nested
type \link CGAL::Arr_circle_segment_traits_2::Point_2
`Point_2`\endlink defined by the traits class, whose coordinates are
typically algebraic numbers of degree 2, is \a not the same as the
`Kernel::Point_2` type. The coordinates of a point are represented
using the number type `CoordNT`, nested in the traits class-template.

<!-- ----------------------------------------------------------------------- -->
\cgalFigureBegin{aos_fig-circles,circles.png}
An arrangement of three circles constructed in \ref
Arrangement_on_surface_2/circles.cpp. Each circle is split into two
\f$x\f$-monotone circular arcs, whose endpoints are drawn as red
disks. Rings mark vertices that correspond to intersection points. The
vertex \f$v_{\rm max}\f$ is a common intersection point of all three
circles.
\cgalFigureEnd
<!-- ----------------------------------------------------------------------- -->

In the following example an arrangement of three full circles is
constructed, as shown in \cgalFigureRef{aos_fig-circles}. Each Index is
split into two \f$x\f$-monotone circular arcs, the endpoints of which
are drawn as red discs; rings mark vertices that correspond to
intersection points. Once the arrangement is constructed, we locate
the vertex of maximal degree in the arrangement. The geometric mapping
of this vertex, denoted by \f$v_{\rm max}\f$, is the point
\f$(4,3)\f$, as all three circles intersect at this point and the
associated vertex has six incident edges.

\cgalExample{Arrangement_on_surface_2/circles.cpp}

The types common to the example programs that use the
`Arr_circle_segment_traits_2` class template are listed below and
defined in the header file `arr_circular.h`.  Even though algebraic
numbers are required to represent coordinates of points where the
inducing curves are circles or circular arcs, such as the curves
handled by the `Arr_circle_segment_traits_2` class template, an
(exact) rational kernel suffices, and a filtered one improves the
performance further.

\code{.cpp}
#include <CGAL/Exact_predicates_exact_constructions_kernel.h>
#include <CGAL/Arr_circle_segment_traits_2.h>
#include <CGAL/Arrangement_2.h>

using Kernel = CGAL::Exact_predicates_exact_constructions_kernel;
using Number_type = Kernel::FT;
using Traits = CGAL::Arr_circle_segment_traits_2<Kernel>;
using CoordNT = Traits::CoordNT;
using Point = Traits::Point_2;
using Curve = Traits::Curve_2;
using Rational_point = Traits::Rational_point_2;
using Segment = Traits::Rational_segment_2;
using Circle = Traits::Rational_circle_2;
using Arrangement = CGAL::Arrangement_2<Traits>;
\endcode

The \link Arr_circle_segment_traits_2::Curve_2 `Curve_2`\endlink type
nested in `Arr_circle_segment_traits_2` can be used to represent
circles, circular arcs, or line segments. We now describe and
demonstrate a variety of ways in which the curves of this type can be
constructed. A Curve object can be constructed from a
`Kernel::Circle_2` object or from a `Kernel::Segment_2` object. A
circular arc is typically defined by a supporting circle and two
endpoints, where the endpoints are of type \link
Arr_circle_segment_traits_2::Point_2 `Point_2`\endlink, with rational
or irrational coordinates. The orientation of the arc is determined by
the orientation of the supporting circle. Similarly, we also support
the construction of line segments given their supporting line (of type
`Kernel::Line_2`) and two endpoints, which may have irrational
coordinates (unlike the `Kernel::Segment_2` type).

Note that the `Kernel::Circle_2` type is used to represent a circle
whose <em>squared radius</em> is rational, where the radius itself may
be irrational.  However, if the radius is known to be rational, its
use is recommended for efficiency. It is therefore also possible to
construct a circle, or a circular arc specifying the circle center (a
`Kernel::Point_2`), its rational radius (of type `Kernel::FT`), and
its orientation. Finally, we also support the construction of a
circular arc that is defined by two endpoints and an arbitrary
interior point that lies on the arc in between its endpoints. In this
case, all three points are required to have rational coordinates;
namely, they are all given as `Kernel::Point_2` objects.

<!-- ----------------------------------------------------------------------- -->
\cgalFigureBegin{aos_fig-circular_arcs,circular_arcs.png}
An arrangement of two full circles, two line segments, and three
circular arcs as constructed in \ref
Arrangement_on_surface_2/circular_arcs.cpp. Endpoints are drawn as
red disks and intersection points are drawn as rings.
\cgalFigureEnd
<!-- ----------------------------------------------------------------------- -->

The following example demonstrates the usage of the various
construction methods for circular arcs and line segments. The
resulting arrangement is depicted in
\cgalFigureRef{aos_fig-circular_arcs}. Note the usage of the
constructor of `CoordNT(alpha, beta, gamma)`, which creates a
degree-\f$2\f$ algebraic number whose value is \f$\alpha +
\beta\sqrt{\gamma}\f$.

\cgalExample{Arrangement_on_surface_2/circular_arcs.cpp}

It is also possible to construct \f$x\f$-monotone curve objects that
represent \f$x\f$-monotone circular arcs or line segments using
similar constructors. (Full circles are not \f$x\f$-monotone.)

The traits class-template
`Arr_circular_line_arc_traits_2<CircularKernel>` offered by the
arrangement package also handles circular arcs and line segments. It
is an alternative to the `Arr_circle_segment_traits_2<Kernel>`
class-template. These two class templates, while serve similar
purposes, are based on different concepts, and posses different
characteristics. You are encouraged to experiment with both, compare
their performance, and use the most suitable for your case.

<!--
\todo What is the difference and what are possible conditions under
which I should choose one over the other
 -->

<!-- ----------------------------------------------------------------------- -->
\paragraph arr_sssectr_conic A Traits Class for Conic Arcs
<!-- ----------------------------------------------------------------------- -->

A <em>conic curve</em> is an algebraic curve of degree 2. Namely, it
is the locus of all points \f$(x,y)\f$ satisfying the equation \f$c:\
r x^2 + s y^2 + t xy + u x + v y + w = 0\f$, where the six
coefficients \f$\langle r, s, t, u, v, w \rangle\f$ completely
characterize the curve. The sign of the expression \f$\Delta_{c} = 4 r
s - t^2\f$ determines the type of curve:

<UL>

<LI>If \f$\Delta_{c} > 0\f$, the curve is an ellipse. A circle is a
special case of an ellipse, where \f$r = s\f$ and \f$t = 0\f$.

<LI>If \f$\Delta_{c} = 0\f$, the curve is a parabola---an unbounded
conic curve with a single connected branch. When \f$r = s = t = 0\f$
we have a line, which can be considered as a degenerate parabola.

<LI>If \f$\Delta_{c} < 0\f$, the curve is a hyperbola. That is, it
comprises of two disconnected unbounded branches.

</UL>

The `Arr_conic_traits_2<RatKernel, AlgKernel, NtTraits>` class
template is capable of handling only bounded arcs of conic curves,
referred to as <em>conic arcs</em>. A conic arc \f$a\f$ may be either
(i) a full ellipse, or (ii) defined by the tuple \f$\langle \kappa,
p_s, p_t, o \rangle\f$, where \f$\kappa\f$ is a conic curve and
\f$p_s\f$ and \f$p_t\f$ are two points on \f$c\f$ (namely
\f$\kappa(p_s) = \kappa(p_t) = 0\f$) that define the <em>source</em>
and <em>target</em> of the arc, respectively. The arc is formed by
traversing \f$\kappa\f$ from the source to the target going in the
orientation specified by \f$o\f$, which is typically clockwise or
counterclockwise orientation, but may also be collinear in case of
degenerate conic conic-curves, namely, lines or pairs of lines.

We always assume that the conic coefficients \f$\langle r, s, t, u, v,
w \rangle\f$ are rational. The coordinates of points of intersection
between two conic curves with rational coefficients are in general
algebraic numbers of degree 4. Namely, they are roots of algebraic
polynomials of degree 4. In addition, conic arcs may not necessarily
be \f$x\f$-monotone, and must be split at points where the tangent to
the arc is vertical.  In the general case such points typically have
coordinates that are algebraic numbers of degree 2. Note that as
arrangement vertices induced by intersection points and points with
vertical tangents are likely to have algebraic coordinates, we also
allow the original endpoints of the input arcs \f$p_s\f$ and \f$p_t\f$
to have algebraic coordinates.

The `Arr_conic_traits_2<RatKernel, AlgKernel, NtTraits>` class
template is designed for efficient handling of arrangements of
bounded conic arcs. The template has three parameters, defined as
follows:

<UL>

<LI>The `RatKernel` template parameter must be substituted by a
geometric kernel whose field type is an exact rational type. It is
used to define basic geometric entities (e.g., a line segment or a
circle) with rational coefficients. Typically we use one of the
standard \cgal kernels, instantiated with the number type
`NtTraits::Rational` (see below).

<LI>The `AlgKernel` template parameter must be substituted by a
geometric kernel whose field type is an exact algebraic type. It is
used to define points with algebraic coordinates. Typically, we use
one of the standard \cgal kernels, instantiated with the number type
`NtTraits::Algebraic` (see below).

<LI>The `NtTraits` template parameter must be substituted by a type
that encapsulates all the numeric operations needed for performing
geometric computation carried out by the geometric traits class.  It
defines the `Integer`, `Rational`, and `Algebraic` number-types, and
supports several operations on these types, such as conversion between
these types, solving quadratic equations, and extracting the real
roots of polynomials with integer coefficients. The use of the
`CORE_algebraic_number_traits` class, which is included in the
arrangement package, is highly recommended. The traits class-template
relies on the multi-precision number types implemented in the \core
library and performs exact computations on the number types it
defines.

</UL>

The instantiation of the conic traits class-template is slightly more
complicated than the instantiation of the traits classes you have
encountered so far. This instantiation is exemplified in the header
file `arr_conics.h`. Note how we first define the rational and
algebraic kernels using the number types given by the \core number
type traits-class, then use them to define the conic traits
class-template. Also note the types defined by the rational kernels,
which we need for conveniently constructing conic arcs.

The `Arr_conic_traits_2` models the `AosTraits_2` and
`AosLandmarkTraits_2` concepts. Its \link
Arr_conic_traits_2::Point_2 `Point_2`\endlink type is derived from
`AlgKernel::Point_2`, while the \link Arr_conic_traits_2::Curve_2
`Curve_2`\endlink type represents a bounded, not necessarily
\f$x\f$-monotone, conic arc.  The \link
Arr_conic_traits_2::X_monotone_curve_2 `X_monotone_curve_2`\endlink
type is derived from \link Arr_conic_traits_2::Curve_2
`Curve_2`\endlink, but its constructors are used only by the traits
class.  Users should therefore construct only \link
Arr_conic_traits_2::Curve_2 `Curve_2`\endlink objects and insert them
into the arrangement using the `insert()` function.

Conic arcs are constructible from full ellipses or by specifying a
supporting curve, two endpoints, and an orientation. However, several
constructors of \link Arr_conic_traits_2::Curve_2 `Curve_2`\endlink
are available to allow for some special cases, such as circular arcs
or line segments. The \link Arr_conic_traits_2::Curve_2
`Curve_2`\endlink and the derived \link
Arr_conic_traits_2::X_monotone_curve_2 `X_monotone_curve_2`\endlink
classes also support basic access functions such as `source()`,
`target()`, and `%orientation()`.

<!-- ----------------------------------------------------------------------- -->
\cgalFigureBegin{aos_fig-conics,conics.png}
An arrangement of mixed conic arcs, as constructed in conics.cpp
\cgalFigureEnd
<!-- ----------------------------------------------------------------------- -->

The following example demonstrates the usage of the various
constructors for conic arcs. The resulting arrangement is depicted in
\cgalFigureRef{aos_fig-conics}. Especially noteworthy are the
constructor of a circular arc that accepts three points, the
constructor of a conic arc that accepts five points, and the
constructor that allows specifying approximate endpoints, where the
exact endpoints are given explicitly as intersections of the
supporting conic with two other conic curves. The approximate
endpoints are used to select the specific exact endpoints out of all
intersection points of the pair of curves (the supporting conic curve
and the auxiliary conic curve).  Also note that as the preconditions
required by some of these constructors are rather complicated (see the
Reference Manual for the details), a precondition violation does not
cause the program to terminate---instead, an <em>invalid</em> arc is
created. The call `a.is_valid()` verifies the validity of the arc
\f$a\f$. Naturally, inserting invalid arcs into an arrangement is not
allowed, so the validity of an arc should be checked once it is
constructed.

\cgalExample{Arrangement_on_surface_2/conics.cpp}

The types common to the example programs that use the
`Arr_conic_traits_2` class template are listed below and
defined in the header file `arr_conics.h`.

\code{.cpp}
#include <CGAL/Cartesian.h>
#include <CGAL/CORE_algebraic_number_traits.h>
#include <CGAL/Arr_conic_traits_2.h>
#include <CGAL/Arrangement_2.h>

using Nt_traits = CGAL::CORE_algebraic_number_traits;
using Rational = Nt_traits::Rational;
using Rat_kernel = CGAL::Cartesian<Rational>;
using Rat_point = Rat_kernel::Point_2;
using Rat_segment = Rat_kernel::Segment_2;
using Rat_circle = Rat_kernel::Circle_2;
using Algebraic = Nt_traits::Algebraic;
using Alg_kernel = CGAL::Cartesian<Algebraic>;
using Traits = CGAL::Arr_conic_traits_2<Rat_kernel, Alg_kernel, Nt_traits>;
using Point = Traits::Point_2;
using Conic_arc = Traits::Curve_2;
using X_monotone_conic_arc = Traits::X_monotone_curve_2;
using Arrangement = CGAL::Arrangement_2<Traits>;
\endcode

<!-- ----------------------------------------------------------------------- -->
\cgalFigureBegin{aos_fig-conic_multiplicities,conic_multiplicities.png}
An arrangement of a circular arc and an hyperbolic arc, as constructed
in \ref Arrangement_on_surface_2/conic_multiplicities.cpp.
\cgalFigureEnd
<!-- ----------------------------------------------------------------------- -->

The last example in this section demonstrates how the conic-traits
class can handle intersection points with multiplicity. The resulting
arrangement is depicted in
\cgalFigureRef{aos_fig-conic_multiplicities}. The supporting curves of
the two arcs, a circle centered at \f$(0,\frac{1}{2})\f$ with radius
\f$\frac{1}{2}\f$, and the hyperbola \f$y =
\frac{x^2}{1-x}\f$,\cgalFootnote{This curve can also be written as
\f$c: x^2 + xy - y = 0\f$. It is a hyperbola since \f$\Delta_{c} =
-1\f$.}  intersect at the origin such that the intersection point has
multiplicity \f$3\f$ (note that they both have the same horizontal
tangent at \f$(0,0)\f$ and the same curvature \f$1\f$). In addition,
they have another intersection point at
\f$(\frac{1}{2},\frac{1}{2})\f$ of multiplicity \f$1\f$.

\cgalExample{Arrangement_on_surface_2/conic_multiplicities.cpp}

<!-- ----------------------------------------------------------------------- -->
\paragraph arr_sssectr_ratfunc A Traits Class for Arcs of Rational Functions
<!-- ----------------------------------------------------------------------- -->

A <em>rational function</em> is given by the equation \f$y =
\frac{P(x)}{Q(x)}\f$, where \f$P\f$ and \f$Q\f$ are polynomials of
arbitrary degrees. In particular, if \f$Q(x) = 1\f$, then the
function is simply a polynomial function. A bounded <em>rational
arc</em> is defined by the graph of a rational function over some
interval \f$[x_{\rm min}, x_{\rm max}]\f$, where \f$Q\f$ does not have
any real roots in this interval (thus, the arc does not contain any
singularities). However, we may consider functions defined over
unbounded intervals, namely, over \f$(-\infty, x_{\max}]\f$,
\f$[x_{\min}, \infty)\f$, or \f$(-\infty, \infty)\f$. Rational
functions, and polynomial functions in particular, are not only
interesting in their own right, they are also useful for approximating
more complicated curves and for interpolation; see, e.g.,
\cgalCite{cgal:ptvf-nrcpp-02} Chapter 3.

Using the `Arr_rational_function_traits_2` class template it is
possible to construct and maintain arrangements induced by rational
arcs. Every instance of the `Arr_rational_function_traits_2` class
template models the concepts `AosTraits_2` and
`AosOpenBoundaryTraits_2`, but it does not model the
`AosLandmarkTraits_2` concept. It also models the refined
concept `AosDirectionalXMonotoneTraits_2`, which enables
Boolean set operations; see Package \ref PkgBooleanSetOperations2.
Note that it is not a model of `AosLandmarkTraits_2` concept,
so it is impossible to use the landmark point-location strategy with
this traits class.

<!-- ----------------------------------------------------------------------- -->
\cgalFigureBegin{aos_fig-rat_func_singular,rational_function_singular.png}
An arrangement of an arc of a rational functions that has
singularities at \f$x = 1\f$ and at \f$x = 2\f$.
\cgalFigureEnd
<!-- ----------------------------------------------------------------------- -->

A rational arc is always \f$x\f$-monotone in the mathematical sense.
However, it is not necessarily continuous, as it may have
singularities. An arc that has singularities must be split into
continuous portions before being inserted into the arrangement.
Consider, for example, the rational arc given by the equation \f$y =
\frac{1}{(x-1)(2-x)}\f$ defined over the interval \f$[0,3]\f$, as
depicted in \cgalFigureRef{aos_fig-rat_func_singular}. This arc has
two singularities, at \f$x = 1\f$ and at \f$x = 2\f$. It is split into
three continuous portions defined over the intervals \f$[0,1)\f$,
\f$(1,2)\f$, and \f$(2,3]\f$ by the traits operation \link
AosTraits_2::Make_x_monotone_2
`Make_x_monotone_2`\endlink. Arbitrary rational functions are
represented by the nested type \link
Arr_rational_function_traits_2::Curve_2 `Curve_2`\endlink and
continuous portions of rational functions are represented by the
nested type \link Arr_rational_function_traits_2::X_monotone_curve_2
`X_monotone_curve_2`\endlink.  Constructors for both types are
provided by the traits in form of functors.

When the `Arr_rational_function_traits_2<AlgebraicKernel_d_1>` class
template is instantiated, the template parameter must be substituted
by a model of the `AlgebraicKernel_d_1` concept. Models of this
concept, such as the `Algebraic_kernel_d_1<Coefficient>` class
template provided by the package \ref PkgAlgebraicFoundations are
meant to support algebraic functionalities on univariate polynomials
of arbitrary degree. See the documentation of the concept
`AlgebraicKernel_d_1` for more information. A rational function is
then represented as the quotient of two polynomials, \f$P\f$ and
\f$Q\f$, of type `Polynomial_1` nested in every model of the concept
`AlgebraicKernel_d_1` and in particular in the algebraic-kernel type
that substitutes the template parameter `AlgebraicKernel_d_1` when the
traits class-template is instantiated. Such a rational function is
constructible from a single polynomial \f$P\f$ (with \f$Q(x) = 1\f$),
or from two polynomials \f$P\f$ and \f$Q\f$. The type of the
polynomial coefficients, namely `Coefficient`, and the type of the
interval bounds, namely `Bound`, are also nested in the
algebraic-kernel type. If an instance of the
`Algebraic_kernel_d_1<Coefficient>` class template is used, for
example, as the algebraic-kernel type, the type that substitutes its
template parameter is defined as the `Coefficient` type. This type
cannot be algebraic. Moreover, it is recommended that this type is not
made rational either, since using rational (as opposed to integral)
coefficients does not extend the range of the rational arcs and is
typically less efficient.\cgalFootnote{The \cgalFootnoteCode{Algebraic_kernel_d_1}
class template uses the types provided by the \ref PkgPolynomial
package to define its nested \cgalFootnoteCode{Polynomial_1} type and conveniently
expose it to the user.} The `Bound` type, however, can be algebraic. A
point of type \link Arr_rational_function_traits_2::Point_2
`Point_2`\endlink nested in the `Arr_rational_function_traits_2` class
template is represented by a rational function and its
\f$x\f$-coordinate, which is derived from the type `Algebraic_real_1`
nested in the algebraic-kernel type. An explicit representation by the
nested type `Algebraic_real_1` of the \f$y\f$-coordinate is only
computed upon request, as it can be a rather costly operation.

The aforementioned types, `Polynomial_1`, `Coefficient`,
`Bound`, and `Algebraic_real_1`, are conveniently nested in
the `Arr_rational_function_traits_2` class template among
the others and obtained from there in the type definitions used
in the examples given in this section and listed below. These types
are defined in the header file `arr_rat_functions.h`.

\code{.cpp}
#include <CGAL/basic.h>
#include <CGAL/CORE_BigInt.h>
#include <CGAL/Algebraic_kernel_d_1.h>
#include <CGAL/Arr_rational_function_traits_2.h>
#include <CGAL/Arrangement_2.h>

using Number_type = CORE::BigInt;
using AK1 = CGAL::Algebraic_kernel_d_1<Number_type>;
using Traits = CGAL::Arr_rational_function_traits_2<AK1>;

using Polynomial = Traits::Polynomial_1;
using Alg_real = Traits::Algebraic_real_1;
using Bound = Traits::Bound;

using Arrangement = CGAL::Arrangement_2<Traits>;
\endcode

The constructed rational functions are cached by the traits class. The
cache is local to each traits class object. It is therefore necessary
to construct curves using only the constructor objects provided by
member functions of the traits class. Moreover, a curve must only be
used by the traits class object that was used to construct it. The
cache is automatically cleaned up from time to time. The amortized
clean up costs are constant. In addition, there is also a separate
member function that cleans up the cache upon request.

<!-- ----------------------------------------------------------------------- -->
\cgalFigureBegin{aos_fig-rational_functions,rational_functions.png}
An arrangement of four arcs of rational functions, as constructed in
\ref Arrangement_on_surface_2/rational_functions.cpp.
\cgalFigureEnd
<!-- ----------------------------------------------------------------------- -->

The following example demonstrates the construction of an arrangement
induced by rational arcs depicted in
\cgalFigureRef{aos_fig-rational_functions}. It uses constructors both
for polynomial arcs and for rational arcs.

\cgalExample{Arrangement_on_surface_2/rational_functions.cpp}

<!-- ----------------------------------------------------------------------- -->
\cgalFigureBegin{aos_fig-unbounded_rational_functions,unbounded_rational_functions.png}
An arrangement of six arcs of rational functions, as constructed in
\ref Arrangement_on_surface_2/unbounded_rational_functions.cpp.
\cgalFigureEnd
<!-- ----------------------------------------------------------------------- -->

The following example demonstrates the construction of an arrangement
of six rational arcs, four unbounded arcs and two bounded ones, as
depicted in \cgalFigureRef{aos_fig-unbounded_rational_functions}. Note
the usage of the constructors of an entire rational function and of an
infinite "ray" of such a function. Also observe that the hyperbolas
\f$y = \pm\frac{1}{x}\f$ and \f$y = \pm\frac{1}{2x}\f$ never
intersect, although they have common vertical and horizontal
asymptotes, so very "thin" unbounded faces are created between them:

\cgalExample{Arrangement_on_surface_2/unbounded_rational_functions.cpp}

The curve constructors have an additional advantage. They conveniently
enable the provision of two polynomials that define a rational arc
using rational coefficients. For example, let \f$P\f$ and \f$Q\f$
denote two polynomials with integral coefficients that define a
rational arc of interest, and let \f$P'\f$ and \f$Q'\f$ denote two
polynomials with rational coefficients that define the same rational
arc; that is, the quotients \f$P/Q\f$ and \f$P'/Q'\f$ are
identical. You can construct the rational arc providing the
coefficients of \f$P'\f$ and \f$Q'\f$ to the constructor. In this case
the constructor normalizes the coefficients and generates the desired
polynomials \f$P\f$ and \f$Q\f$. To this end, the curve constructors
of both types, namely \link Arr_rational_function_traits_2::Curve_2
`Curve_2`\endlink and \link
Arr_rational_function_traits_2::X_monotone_curve_2
`X_monotone_curve_2`\endlink, have operators that accept ranges of
polynomial coefficients as well as polynomials. The coefficients in a
given range must be in the order of the degrees of the corresponding
variables starting from the constant term.

<!-- ----------------------------------------------------------------------- -->
\paragraph arr_sssectr_bez A Traits Class for Planar B&eacute;zier Curves
<!-- ----------------------------------------------------------------------- -->

A planar <em>B&eacute;zier curve</em> \f$B\f$ is a parametric curve
defined by a sequence of <em>control points</em> \f$p_0, \ldots,
p_n\f$ as follows:

\f{eqnarray*}{
B(t) = \left(X(t), Y(t)\right)
= \ccSum{k=0}{n}{p_k \cdot \frac{n!}{k! (n-k)!} \cdot
t^k (1-t)^{n-k}}\ .
\f}

where \f$t \in [0, 1]\f$. The degree of the curve is therefore \f$n\f$;
namely, \f$X(t)\f$ and \f$Y(t)\f$ are polynomials of degree
\f$n\f$. B&eacute;zier curves have numerous applications in computer
graphics and solid modeling. They are used, for example, in free-form
sketches and for defining the true-type fonts.

Using the `Arr_Bezier_curve_traits_2<RatKernel, AlgKernel, NtTraits>`
class template you can construct and maintain arrangements induced by
B&eacute;zier curves (including self-intersecting B&eacute;zier
curves) of arbitrary degree. The curves are given by rational control
points, that is, a sequence of objects of the `RatKernel::Point_2`
type.  (In general, a sequence of \f$n+1\f$ control points define a
B&eacute;zier curve of degree \f$n\f$.)  The three types that
substitute the template parameters `RatKernel`, `AlgKernel`, and
`NtTraits`, respectively, when the traits is instantiated must fulfill
the same requirements of the corresponding types used to instantiate
the `Arr_conic_traits_2` class template. Here, the use of the
`CORE_algebraic_number_traits` class is also recommended with
%Cartesian kernels instantiated with the `Rational` and `Algebraic`
number types defined by this class. The examples given in this manual
use the type definitions listed below. These types are defined in the
header file `arr_Bezier.h`.

\code{.cpp}
#include <CGAL/Cartesian.h>
#include <CGAL/CORE_algebraic_number_traits.h>
#include <CGAL/Arr_Bezier_curve_traits_2.h>
#include <CGAL/Arrangement_2.h>

using Nt_traits = CGAL::CORE_algebraic_number_traits;
using NT = Nt_traits::Rational;
using Rational = Nt_traits::Rational;
using Algebraic = Nt_traits::Algebraic;
using Rat_kernel = CGAL::Cartesian<Rational>;
using Alg_kernel = CGAL::Cartesian<Algebraic>;
using Rat_point = Rat_kernel::Point_2;
using Traits =
  CGAL::Arr_Bezier_curve_traits_2<Rat_kernel, Alg_kernel, Nt_traits>;
using Bezier_curve = Traits::Curve_2;
using Arrangement = CGAL::Arrangement_2<Traits>;
\endcode

As mentioned above, we assume that the coordinates of all control
points that define a B&eacute;zier curve are rational numbers, so both
\f$X(t)\f$ and \f$Y(t)\f$ are polynomials with rational
coefficients. The intersection points between curves are, however,
algebraic numbers, and their exact computation is time-consuming. The
traits class therefore contains a layer of geometric filtering that
performs all computations in an approximate manner whenever
possible. Thus, it resorts to exact computations only when the
approximate computation fails to produce an unambiguous result. Most
arrangement vertices are therefore associated with approximated
points. You cannot access the coordinates of such points as algebraic
numbers. However, access to the approximate coordinates is possible.
See the Reference Manual for the exact interface of the \link
Arr_Bezier_curve_traits_2::Point_2 `Point_2`\endlink, \link
Arr_Bezier_curve_traits_2::Curve_2 `Curve_2`\endlink, and \link
Arr_Bezier_curve_traits_2::X_monotone_curve_2
`X_monotone_curve_2`\endlink types defined by the traits class.

Every instance of the `Arr_Bezier_curve_traits_2` class templates
models the concept `AosTraits_2` (but it does not model the
`AosLandmarkTraits_2` concept). It also models the refined
concept `AosDirectionalXMonotoneTraits_2`, which enables
Boolean set operations; see Package \ref PkgBooleanSetOperations2.

<!-- ----------------------------------------------------------------------- -->
\cgalFigureBegin{aos_fig-bezier_curves,bezier_curves.png}
An arrangement of ten B&eacute;zier curves of degree \f$5\f$, as
constructed in \ref Arrangement_on_surface_2/Bezier_curves.cpp.
\cgalFigureEnd
<!-- ----------------------------------------------------------------------- -->

The following example reads a set of B&eacute;zier curves from an
input file, where each file is specified by an integer stating its
number of control points, followed by the sequence of control points
given as integer or rational coordinates. By default, the program uses
the `Bezier.dat` file, which contains ten curves of degree \f$5\f$
each; their resulting arrangement is depicted in
\cgalFigureRef{aos_fig-bezier_curves}.

\cgalExample{Arrangement_on_surface_2/Bezier_curves.cpp}

<!-- ----------------------------------------------------------------------- -->
\paragraph arr_sssectr_alg A Traits Class for Planar Algebraic Curves of Arbitrary Degree
<!-- ----------------------------------------------------------------------- -->

The traits class, namely `Arr_algebraic_segment_traits_2`, is based on
the `Algebraic_kernel_d_1` class template, which models the
algebraic-kernel concept `AlgebraicKernel_d_1`; see Section \ref
arr_sssectr_ratfunc. The traits class handles (i) algebraic curves and
(ii) continuous (weakly) \f$x\f$-monotone segments of algebraic
curves, which, however, are not necessarily maximal. (A formal
definition is given below.)  Observe that non-\f$x\f$-monotone
segments are not supported. Still, it is the traits class that
supports the most general type of curves among the traits classes
included in the package.

Recall that an algebraic curve \f$c\f$ in the plane is defined as the
(real) zero set of a bivariate polynomial \f$f(x,y)\f$. The curve is
uniquely defined by \f$f\f$, although several polynomials might define
the same curve.  We call \f$f\f$ a <em>defining polynomial</em> of
\f$c\f$.

A formal definition of (weakly) \f$x\f$-monotone segments of algebraic
curves follows. A point \f$p\f$ on a curve \f$c_f \subset \mathbb{R}^2\f$
(with defining polynomial \f$f\f$) is called <em>semi-regular</em> if,
locally around \f$p\f$, the curve \f$c_f\f$ can be written as a
function graph of some continuous function in \f$x\f$ or in
\f$y\f$. (We also say that \f$p\f$ is parameterizable in \f$x\f$ or
\f$y\f$, respectively.)  The only two cases of non-semi-regular points
are isolated points and self-intersections. A <em>segment</em> of a
curve in this context is a closed and continuous point set such that
each interior point is semi-regular. It follows that a segment is
either vertical or a closed connected point set, with all interior
points parameterizable in \f$x\f$.

Every instance of the `Arr_algebraic_segment_traits_2<Coefficient>`
class template models the `AosTraits_2` and
`AosOpenBoundaryTraits_2` concepts (but it does not model the
`AosLandmarkTraits_2` concept).  The template argument
`Coefficient` determines the type of the scalar coefficients of the
polynomial.  Currently supported integral number types are `Gmpz`,
`leda_integer`, and `CORE::BigInt`. This is reflected in the
statements included in the header file `integer_type.h`, the listings
of which are omitted here. This header file is used by the two example
programs listed in this section. The template parameter `Coefficient`
can be substituted in addition by an instance of the
`Sqrt_extension<A,B>` class template, where the template parameters
`NT` and `Root` are substituted in turn by one of the integral
number types above. Finally, the template parameter `Coefficient` can
be substituted also by a rational number type, where the type of the
numerator and denominator is one of the types above.

The type \link Arr_algebraic_segment_traits_2::Curve_2
`Curve_2`\endlink nested in the `Arr_algebraic_segment_traits_2` class
template defines an algebraic curve. An object of this type can be
constructed by the \link
Arr_algebraic_segment_traits_2::Construct_curve_2
`Construct_curve_2`\endlink functor also nested in the class
template. Its function operator accepts as an argument an object of
type \link Arr_algebraic_segment_traits_2::Polynomial_2
`Polynomial_2`\endlink, nested as well in the traits class-template.
The type \link Arr_algebraic_segment_traits_2::Polynomial_2
`Polynomial_2`\endlink models the concept `Polynomial_d`. An object of
the nested type \link Arr_algebraic_segment_traits_2::Polynomial_2
`Polynomial_2`\endlink represents a bivariate polynomial. It can be
constructed in a few convenient ways, some are exemplified by the
programs listed below. Consult the reference guide for the complete
set of options.

<!-- ----------------------------------------------------------------------- -->
\cgalFigureBegin{aos_fig-algebraic_curves,algebraic_curves.png}
An arrangement of algebraic curves of degrees \f$1\f$, \f$2\f$,
\f$3\f$, and \f$6\f$, as constructed in
\ref Arrangement_on_surface_2/algebraic_curves.cpp.
\cgalFigureEnd
<!-- ----------------------------------------------------------------------- -->

The following examples computes the arrangement depicted in in
\cgalFigureRef{aos_fig-algebraic_curves}. The arrangement is induced
by four algebraic curves, \f$c_1\f$, \f$c_2\f$, \f$c_3\f$, and
\f$c_4\f$, of degrees \f$1\f$, \f$2\f$, \f$3\f$, and \f$6\f$,
respectively. For each curve the defining polynomial is constructed
first. Then, the algebraic curve is constructed using the \link
Arr_algebraic_segment_traits_2::Construct_curve_2
`Construct_curve_2`\endlink functor.  Finally, the curve is inserted
into the arrangement.

\cgalExample{Arrangement_on_surface_2/algebraic_curves.cpp}

The `Arr_algebraic_segment_traits_2` class template carries state to
expedite some of its computations. Thus, it is essential to have only
one copy of the traits object during the life time of a program that
utilizes this traits class. To this end, the example above uses the
constructor of the `Arrangement_2` data structure that accepts the traits
object as input. Carrying state is not a unique property of the
`Arr_algebraic_segment_traits_2` class template; it is common to many
traits classes, especially to traits classes that handle algebraic
curves.  Therefore, as a general rule, if your application requires
direct access to a traits object, define it locally, and pass it to
the constructor of the `Arrangement_2` data structure to avoid the
construction of a duplicate traits-class object.

A weakly \f$x\f$-monotone segment of an algebraic curve is represented
by the \link Arr_algebraic_segment_traits_2::X_monotone_curve_2
`X_monotone_curve_2`\endlink type nested in the traits
class-template. You can construct such segments in two ways as
follows: (i) using the \link AosTraits_2::Make_x_monotone_2
`Make_x_monotone_2`\endlink functor or (ii) using the \link
Arr_algebraic_segment_traits_2::Construct_x_monotone_segment_2
`Construct_x_monotone_segment_2`\endlink functor.  Both functors are
nested in the traits class-template. The former is required by the
concept `AosTraits_2` our traits class models; see Section
\ref aos_sssec-geom_traits-concepts_arbitrary. The latter enables the
construction of individual segments. The \link
Arr_algebraic_segment_traits_2::X_monotone_curve_2
`X_monotone_curve_2`\endlink type represents weakly \f$x\f$-monotone
segments of a curve; however, for technical reasons, segments may need
to be further subdivided into several sub-segments, called terminal
segments. Therefore, \link
Arr_algebraic_segment_traits_2::Construct_x_monotone_segment_2
`Construct_x_monotone_segment_2`\endlink constructs a sequence of
\link Arr_algebraic_segment_traits_2::X_monotone_curve_2
`X_monotone_curve_2`\endlink objects, whose union represents the
desired weakly \f$x\f$-monotone segment. The function operator of the
\link Arr_algebraic_segment_traits_2::Construct_x_monotone_segment_2
`Construct_x_monotone_segment_2`\endlink functor accepts as arguments
the underlying algebraic curve, the leftmost point of the segment, the
rightmost point of the segment, and an output iterator associated with
a container of output terminal segments. The function operator is
overloaded. In addition to the variant above, there is one that
accepts the underlying algebraic curve, a single point \f$p\f$, an
enumerator that delimits the segment, and an output iterator. It
returns the maximal \f$x\f$-monotone segment that contains
\f$p\f$. The enumerator specifies whether \f$p\f$ is interior to the
returned segment, its left endpoint, or its right endpoint. The third
variant accepts only two delimiting points and an output iterator. It
constructs line segments.

\cgalAdvancedBegin The subdivision terminal segments is due to the
internal representation of \f$x\f$-monotone segments, which is based
on a vertical decomposition.  We assume the defining polynomial
\f$f\f$ of the curve \f$c\f$ to be <em>square-free</em>. That is, it
contains no divisor \f$g^2\f$ of total degree greater than zero. We
define a <em>(complex) critical point</em> \f$p\in\mathbb{C}^2\f$ by
\f[ f(p)=0=\frac{\partial f}{\partial y}(p). \f] An \f$x\f$-coordinate
\f$\alpha\in\mathbb{R}\f$ is <em>critical</em> either if some critical
point has \f$x\f$-coordinate \f$\alpha\f$, or if the leading
coefficient of \f$f\f$, considered as a polynomial in \f$y\f$,
vanishes. In particular, vertical lines and isolated points of \f$c\f$
can only take place at critical \f$x\f$-coordinates.  Between two
consecutive critical \f$x\f$-coordinates the curve decomposes into a
finite number of \f$x\f$-monotone segments (the same holds to the left
of the leftmost, and to the right of the rightmost critical
\f$x\f$-coordinate).  The type \link
Arr_algebraic_segment_traits_2::X_monotone_curve_2
`X_monotone_curve_2`\endlink is only capable of representing such
segments (and sub-segments of them). Formally, a terminal segment is
either a vertical line-segment or a segment of an \f$x\f$-monotone
curve whose \f$x\f$-range does not contain critical points in its
interior. See \cgalFigureRef{aos_fig-algebraic_curves_decomposition}
for an example of a quartic curve and its decomposition into terminal
segments.  Notice that six vertices split the curve into
\f$x\f$-monotone segments, and four additional vertices further split
the corresponding \f$x\f$-monotone segments into terminal segments.
\cgalAdvancedEnd

<!-- ----------------------------------------------------------------------- -->
\cgalFigureBegin{aos_fig-algebraic_curves_decomposition,algebraic_curves_decomposition.png}

The critical \f$x\f$-coordinates of an algebraic curve (dashed
lines), and its decomposition into terminal segments (in different
colors). The segment from \f$p\f$ to \f$q\f$ consists of the union
of three terminal segments.
\cgalFigureEnd
<!-- ----------------------------------------------------------------------- -->

The type `Algebraic_real_1` must be defined by any model of the
`AlgebraicKernel_d_1` concept. The traits class-template
`Arr_algebraic_segment_traits_2` exploits an instance of the
`Algebraic_kernel_d_1` class template, which models the concept
`AlgebraicKernel_d_1`. The exploited instance is nested in the traits
class-template. You can use this model to create algebraic numbers as
roots of univariate polynomials, and process them, for instance,
compare them or approximate them to any precision. See the
documentation of the concept `AlgebraicKernel_1` for more information.
Coordinates of points are represented by the type `Algebraic_real_1`
nested in the traits class-template. This type is defined as the
corresponding type nested in the instance of `Algebraic_kernel_d_1`.

You can construct an object of type \link
Arr_algebraic_segment_traits_2::Point_2 `Point_2`\endlink using the
\link Arr_algebraic_segment_traits_2::Construct_point_2
`Construct_point_2`\endlink functor nested in the traits
class-template. Its function operator is overloaded with a couple of
variants that accepts the \f$x\f$ and \f$y\f$ coordinates of the
point. Their types must be either `Algebraic_real_1` or
`Coefficient`. Another efficient variant accepts a triple
\f$(x_0,c,i)\f$, which identifies the \f$i\f$-th point (counted from
below) in the fiber of \f$c\f$ at the \f$x\f$-coordinate
\f$x_0\f$. \cgalFootnote{The fiber of a curve \f$c\f$ at some
\f$x\f$-coordinate \f$x'\f$ is the set of all points on \f$c\f$ with
\f$x\f$-coordinate \f$x'\f$.  Formally, for a curve \f$c\f$ and \f$x'
\in \mathbb{R}\f$, the fiber of \f$c\f$ at \f$x'\f$ is \f$c \cap
\{(x',b)\,|\,b \in \mathbb{R}\}\f$.} In the example depicted in
\cgalFigureRef{aos_fig-algebraic_curves_decomposition}, if \f$x_1\f$
denotes the \f$x\f$-coordinate of \f$p\f$, and \f$c\f$ represents the
algebraic curve, then \f$p\f$ could be represented by
\f$(x_1,c,3)\f$. If \f$x_2\f$ is the \f$x\f$-coordinate of \f$q\f$,
then \f$(x_2,c,1)\f$ is a valid representation of \f$q\f$. Points are
represented internally using the triple described above. Although the
\f$y\f$-coordinate of a point represented by an object of the nested
type `Algebraic_real_1` can be obtained, we advise caution with that
option, since computing an explicit representation of the
\f$y\f$-coordinate can be rather expensive.

<!-- ----------------------------------------------------------------------- -->
\cgalFigureBegin{aos_fig-algebraic_segments,algebraic_segments.png}
An arrangement of algebraic segments (solid lines), as constructed in
\ref Arrangement_on_surface_2/algebraic_segments.cpp. The supporting
curves are drawn as dashed lines.
\cgalFigureEnd
<!-- ----------------------------------------------------------------------- -->

The following code exemplifies the method to construct points and the
various methods to construct algebraic segments. The computed
arrangement is depicted in \cgalFigureRef{aos_fig-algebraic_segments}.

\cgalExample{Arrangement_on_surface_2/algebraic_segments.cpp}

<!-- ----------------------------------------------------------------------- -->
\subsubsection arr_ssectr_spherical Arcs of Great Circles Embedded in the Sphere
<!-- ----------------------------------------------------------------------- -->

A great circle of a sphere is the intersection of the sphere and a
plane that passes through the center point of the sphere. For all
pairs of distinct points on the sphere except for antipodal points,
there is a unique great circle through the two points. There are
infinitely many great circles through antipodal points. The minor arc
of a great circle between two points is the shortest spherical-path
between them. In this sense, minor arcs are analogous to line
segments in Euclidean geometry.

The `Arr_geodesic_arc_on_sphere_traits_2<Kernel,X,Y>` class template
handles arcs of great circles (also known as geodesic arcs) of a unit
sphere (centered at the origin in \f$\mathbb{R}^3\f$). It is a model of the
concept `AosSphericalBoundaryTraits_2`; see Section \ref
aos_ssec-traits-curved. An arrangement type (an instance of the
template `Arrangement_on_surface_2<GeomTraits, TopolTraits>`) that
uses an instance of this traits class as the geometry traits must use
a matching topology traits.  Currently, this package provides one
template, namely, `Arr_spherical_topology_traits_2<GeometryTraits_2,
Dcel>` an instance of which can be used as the topology traits.

The unit sphere is defined over a parameter space \f$\Phi =
[\tau,2\pi+\tau] \times [-\frac{\pi}{2}, \frac{\pi}{2}]\f$, where
\f$\tau = \arctan(X, Y)\f$. By default, \f$X = -1, Y = 0\f$, which
implies \f$\tau = -\pi\f$, which implies a default parameterization
\f$\Phi = [-\pi, \pi] \times [-\frac{\pi}{2}, \frac{\pi}{2}]\f$. The
equator curve, for example, is given by \f$\gamma(t) = (2t\pi + \tau,
0)\f$, for \f$t \in [0,1]\f$. The surface is given by
\f$\phi_S(\alpha,\beta) = (\cos \alpha \cos \beta, \sin \alpha \cos
\beta, \sin \beta)\f$; see Section \ref aos_sec-curved_surfaces for
more details. This parameterization induces two contraction points
\f$(0,0,-1) = \phi_S(\alpha,-\frac{\pi}{2})\f$ and \f$(0,0,1) =
\phi_S(\alpha,\frac{\pi}{2})\f$, for all \f$\alpha\f$, referred to as
the south and north poles, respectively, and an identification curve
\f$\{\phi_S(\alpha,\beta)\,|\,-\frac{\pi}{2} \leq \beta \leq
\frac{\pi}{2}\}\f$, as \f$\phi_S(\pi,\beta) = \phi_S(2\pi +
\tau,\beta)\f$ for all \f$\beta\f$. When \f$\tau = -\pi\f$ (the
default), the identification curve coincides with the opposite Prime
(Greenwich) Meridian. In other words, the left and right boundary
sides of the parameter space are identified and the top and bottom
boundary sides are contracted.  The arguments that substitute the
template parameters `X` and `Y` when
`Arr_geodesic_arc_on_sphere_traits_2<Kernel, X, Y>` is instantiated
determine the value of \f$\tau\f$. Essentially, overriding their default
values rotates the identification curve about the vertical axes of the
image coordinate system (that is, the sphere coordinate system). These
arguments must be integral values. They define a not-necessarily
normalized vector \f$(x,y)\f$ in the \f$xy\f$-plane in the image
coordinate system, that bisects the identification curve. The explicit
expression for the surface above is not used at all in the
implementation of the traits. Indeed, all the required geometric
operations listed in the traits concept are implemented using only
rational arithmetic.

The following example constructs an arrangement induced by 12 arcs of
great circles embedded in the sphere. The arrangement is depicted in
\cgalFigureRef{spherical_insert}.

<!-- ----------------------------------------------------------------------- -->
\cgalFigureBegin{spherical_insert,spherical_insert.png}
An arrangement induced by 12 arcs of great circles, as constructed in
\ref Arrangement_on_surface_2/spherical_insert.cpp. The number of
vertices, edges, and faces of the arrangement is 7, 13, and 8,
respectively. The intersection of the curve \f$(-1,0,0),(0,1,0)\f$
with the identification curve induces a vertex at
\f$(\frac{-11}{\sqrt{11^2+7^2}},\frac{7}{\sqrt{11^2+7^2}},0)\f$ drawn
in green. The north and south poles are drawn as little spheres. The
identification curve is drawn as a gray tube.
\cgalFigureEnd
<!-- ----------------------------------------------------------------------- -->

\cgalExample{Arrangement_on_surface_2/spherical_insert.cpp}

Use the `Arr_geodesic_arc_on_sphere_traits_2::Construct_point_2`,
`Arr_geodesic_arc_on_sphere_traits_2::Construct_x_monotone_curve_2`,
and `Arr_geodesic_arc_on_sphere_traits_2::Construct_curve_2` functors
to construct a point, an \f$X\f$-monotone curve and a curve objects,
respectively. Observe that an \f$X\f$-monotone curve cannot intersect
the identification curve in its interior. A curve can be constructed
from either (i) two endpoints, (ii) two endpoints and a normal, or
(iii) a normal. The two endpoints determine the plane. The normal
determines the orientation of the plane and the final arc (whether it
is the minor arc or the major arc). If the normal is not provided, the
minor arc is constructed. If a curve is constructed and only the
normal is provided a full great circle is constructed. If an
\f$X\f$-monotone curve is constructed and only the normal is provided
an arc that resembles a full circle is constructed; this arc has one
endpoint that lies on the identification curve; this point is
considered both the source and target (and also the left and right)
point of the arc. See \cgalFigureRef{aos_fig-right_hand_rule} for an
illustration of the right-hand rule, which depicts the relation
between the arc and the normal.

<!-- ----------------------------------------------------------------------- -->
\cgalFigureBegin{aos_fig-right_hand_rule,right_hand_rule.png}
To use the right hand rule, point your right thumb in the direction of
the normal and curl your fingers in the direction of the arc starting
with source endpoint and ending at the target endpoint.
\cgalFigureEnd
<!-- ----------------------------------------------------------------------- -->

<!-- ----------------------------------------------------------------------- -->
\subsection arr_ssec_tr_decorators Traits-Class Decorators
<!-- ----------------------------------------------------------------------- -->

Decorator is a structural pattern that allows adding new behaviors to
objects by placing them inside special wrapper objects, called
decorators. One type of decorators attaches auxiliary data to the
geometric objects handled by the original traits. Another type enables
the retrieval of debugging and informative metadata.

<!-- ----------------------------------------------------------------------- -->
\subsubsection arr_sssec_tr_data_decorators Data Decorators
<!-- ----------------------------------------------------------------------- -->

Geometric traits-class decorators allow you to attach auxiliary data
to the geometric objects (curves and to points). The data is
automatically manipulated by the decorators and distributed to the
constructed geometric entities. Additional information can
alternatively be maintained by extending the vertex, halfedge, or face
types provided by the \dcel class used by the arrangement; see
Section \ref arr_ssecex_dcel for details. In many cases, however, it is
convenient to attach the data to the curve itself, exploiting the
automatic proliferation of the additional data fields from each curve
to all its induced subcurves. Moreover, as two halfedges are
associated with a single curve, storing the data once in the curve
record either saves space or avoids an indirect access from one
halfedge to its twin.

The \ref PkgArrangementOnSurface2 package includes a traits-class
decorator used to attach a data field to curves and to
\f$x\f$-monotone curves. It is a class template named
`Arr_curve_data_traits_2<BaseTraits, XMonotoneCurveData, Merge,
CurveData, Convert>` parameterized by a base-traits class, which must
be substituted by one of the geometric traits models described in
the previous subsections or with a user-defined traits model, when the
decorator is instantiated. The curve-data decorator derives from the
base-traits class, and in particular inherits its \link
Arr_curve_data_traits_2::Point_2 `Point_2`\endlink type. The remaining
nested types are defined as follows:

<UL>

<LI>\link Arr_curve_data_traits_2::Curve_2 `Curve_2`\endlink is
  derived from the basic `BaseTraits::Curve_2` class, extending it by
  an extra field of type `CurveData`.

<LI>\link Arr_curve_data_traits_2::X_monotone_curve_2
  `X_monotone_curve_2`\endlink is derived from the basic
  `BaseTraits::X_monotone_curve_2` class, extending it by an extra
  field of type `XMonotoneCurveData`, which must model the concepts
  CopyConstructible, EqualityComparable, and DefaultConstructible.
  The latter ensures that every instance of the class template
  `Arr_curve_data_traits_2` obtained by substituting the `BaseTraits`
  template parameter with a model of the `AosLandmarkTraits_2`
  concept models the `AosLandmarkTraits_2` concept as well

</UL>

Note that the nested \link Arr_curve_data_traits_2::Curve_2
`Curve_2`\endlink and \link
Arr_curve_data_traits_2::X_monotone_curve_2
`X_monotone_curve_2`\endlink are not the same, even if the
`BaseTraits::Curve_2` and `BaseTraits::X_monotone_curve_2` are (as in
the case of the segment-traits class, for example). The extended curve
types support the additional methods \link
CGAL::Arr_curve_data_traits_2<Tr, XData, Mrg, CData,
Cnv>::Curve_2::data() `data()`\endlink and \link
CGAL::Arr_curve_data_traits_2<Tr, XData, Mrg, CData,
Cnv>::Curve_2::set_data() `set_data()`\endlink for accessing and
modifying the data field.

You can create an extended curve (or an extended \f$x\f$-monotone curve)
from a basic curve and a curve-data object. When curves are
inserted into an arrangement, they may be split, and the
decorator handles their data fields automatically  as follows:

<UL>

<LI>When a curve is subdivided into \f$x\f$-monotone subcurves, its
  data field of type `CurveData` is converted to an object of type
  `XMonotoneCurveData` using the `Convert` functor. The object is
  automatically associated with each of the resulting \f$x\f$-monotone
  subcurves.

  Note that by default, the `CurveData` type is identical to the
  `XMonotoneCurveData` type (and the conversion functor `Convert` is
  trivially defined). Thus, the data field associated with the
  original curve is just duplicated and stored with the
  \f$x\f$-monotone subcurves.

<LI>When an \f$x\f$-monotone curve is split into two (typically, when
  it intersects another curve), the decorator class automatically
  copies its data field to both resulting subcurves.

<LI>When two \f$x\f$-monotone curves, \f$c_1\f$ and \f$c_2\f$,
intersect, the result may include overlapping sections represented as
\f$x\f$-monotone curves. In this case the data fields of \f$c_1\f$ and
\f$c_2\f$ are merged into a single `XMonotoneCurveData` object using
the `Merge` functor, which is supplied as a parameter to the traits
class-template. The resulting object is assigned to the data field of
the overlapping subcurves.

<LI>Merging two \f$x\f$-monotone curves is allowed only when (i) the
two curves are geometrically mergeable---that is, the base-traits
class allows to merge them, and (ii) the two curves store the same
data field.

</UL>

Another decorator supported by the \ref PkgArrangementOnSurface2
package is the `Arr_consolidated_curve_data_traits_2<BaseTraits,
Data>` class template. It derives from the `Arr_curve_data_traits_2`
class template, and it extends the basic type `BaseTraits::Curve_2` by
a single `Data` field, and the basic `BaseTraits::X_monotone_curve_2`
with a <em>set</em> of (distinct) data objects. The `Data` type must
model the concept `EqualityComparable` to ensure that each set
contains only distinct data objects with no duplicates. When a curve
with a data field \f$d\f$ is subdivided into \f$x\f$-monotone
subcurves, each subcurve is associated with a set \f$S = \{d\}\f$. In
the case of an overlap between two \f$x\f$-monotone curves \f$c_1\f$
and \f$c_2\f$ with associated data sets \f$S_1\f$ and \f$S_2\f$,
respectively, the overlapping subcurve is associated with the
consolidated set \f$S_1 \cup S_2\f$.

<!-- ----------------------------------------------------------------------- -->
\cgalFigureBegin{aos_fig-consolidated_curve_data,consolidated_curve_data.png}
An arrangement of six red and blue segments, as constructed in \ref
Arrangement_on_surface_2/consolidated_curve_data.cpp. Disks correspond
to red-blue intersection points, while circles mark the endpoints of
red-blue overlaps.
\cgalFigureEnd
<!-- ----------------------------------------------------------------------- -->

The following example uses `Arr_segment_traits_2` as the base-traits
class, attaching an additional <em>color</em> field to the segments
using the consolidated curve-data traits class. A color may be either
<em>blue</em> or <em>red</em>. Having constructed the arrangement of
colored segments, as depicted in
\cgalFigureRef{aos_fig-consolidated_curve_data}, we detect the
vertices that have incident edges mapped to both blue and red
segments. These vertices, drawn as black discs in the figure,
correspond to red-blue intersection points. We also locate the edge
that corresponds to overlap between a red and a blue line segment (its
endpoints are also drawn as black discs)

\cgalExample{Arrangement_on_surface_2/consolidated_curve_data.cpp}

<!-- ----------------------------------------------------------------------- -->
\cgalFigureBegin{aos_fig-generic_curve_data,generic_curve_data.png}
An arrangement of four polylines, named A-D, as constructed in
\ref Arrangement_on_surface_2/generic_curve_data.cpp.
\cgalFigureEnd
<!-- ----------------------------------------------------------------------- -->

The following example uses `Arr_polyline_traits_2` as the base-traits
class, attaching an additional <em>name</em> field to each polyline
using the generic curve-data traits class. It constructs an
arrangement of four polylines, named \f$A\f$, \f$B\f$, \f$c\f$, and
\f$D\f$, as illustrated in
\cgalFigureRef{aos_fig-generic_curve_data}.  In the case of
overlaps, it simply concatenate the names of the overlapping
polylines. At the end of the program the curve associated with the
edges that correspond to overlapping polylines are replaced with
geometrically equivalent curves, but with different data fields.

\cgalExample{Arrangement_on_surface_2/generic_curve_data.cpp}

The third example we give in this section is based on \ref
Arrangement_on_surface_2/dual_lines.cpp given in Section \ref
arr_ssec-unb_duality. It constructs the arrangement of the dual lines
for a set of point given in an input file (by default we use
`coll_points.dat`, which contains \f$50\f$ points randomly selected on
the grid \f$[-100,100]\times[-100,100]\f$; the file contains two
distinct triplets of collinear points). Here we use the generic
curve-data decorator to attach the index of the primal point to each
of the lines.  Doing so, we can go over the incident edges of each
vertex whose degree is greater than \f$4\f$ and report the subsets of
collinear points (if we have a vertex of degree \f$d\f$, we actually
need to go over \f$\frac{d}{2}\f$ edges, as each incident line
contributes exactly \f$2\f$ edges). Note that in this case the dual
line cannot overlap, so we use a dummy merge functor to instantiate
the curve-data traits:

\cgalExample{Arrangement_on_surface_2/dual_with_data.cpp}

<!-- ----------------------------------------------------------------------- -->
\subsubsection arr_sssec_tr_metadata_decorators Metadata Decorators
<!-- ----------------------------------------------------------------------- -->

The package provides two traits-class decorators, namely
`Arr_counting_traits_2<BaseTraits>` and
`Arr_tracing_traits_2<BaseTraits>`, that can be used to insert
debugging and informative metadata to an output stream. The former is
used to count the number of invocations of traits-class functors, and
the latter is used to trace these invocations. Note that the
constructors of each of these class templates apply perfect
forwarding. The counting traits also exports the count of traits-class
objects of specific types constructed during the execution of the
program. The tracing traits supports filtering of traced functors. The
calls `traits.enable_trace(id)` and `traits.disable_trace(id)` enables
and disables the tracing of a functor identified by `id`,
respectively. A functor is identified by an enumeration. For example,
the functor \link AosTraits_2::Make_x_monotone_2
`Make_x_monotone_2`\endlink is identified by the enumeration
`Arr_tracing_traits_2::MAKE_X_MONOTONE_OP`. The calls
`traits.enable_all_traces()` and `traits.disable_all_traces()` enables
and disables the traces of all functors, respectively. The example
program listed below demonstrates the use of both of these metadata
decorators.

\cgalExample{Arrangement_on_surface_2/count_and_trace.cpp}

<!-- ======================================================================= -->
\section aos_sec-topol_traits The Topology Traits
<!-- ======================================================================= -->
A topology traits class encapsulates the definitions of the
topological entities and the implementation of the functions that
handle these topological entities, used by the
`Arrangement_on_surface_2<GeometryTraits_2, TopologyTraits>` class
template and by the peripheral modules. Every topology traits class
must model the basic concept `AosBasicTopologyTraits`. A model
of this basic concept holds the (\dcel) data structure used to
represent the arrangement cells (i.e., vertices, edges, and facets)
and the incidence relations between them. At this point we do not
expose the concepts that refine the basic concept.  The package
contains three topology traits class templates, namely,
`Arr_bounded_planar_topology_traits_2`,
`Arr_unb_planar_topology_traits_2`, and
`Arr_spherical_topology_traits_2`. The first two are internally used
to define any instance of the class template
`Arrangement_2<GeometryTraits_2, Dcel>`. In particular, an instance
`Arrangement_2<Geometry_traits_2, Dcel_>` is derived from the instance
`Arrangement_on_surface_2<Geometry_traits_2,Topology_traits>`, where
the `Topology_traits` type is selected based on the provided geometry
traits `Geometry_traits_2`, or more precisely, on the boundary
conditions defined by the geometry traits. If all sides of the
boundary of the parameter space are closed, the instance
`Arr_bounded_planar_topology_traits_2<Geometry_traits_2,Dcel_>` is
selected; otherwise the instance
`Arr_unb_planar_topology_traits_2<Geometry_traits_2,Dcel_>` is
selected.  The third topology traits serves as a topology traits for
an arrangement embedded on a sphere. More precisely, for an
arrangement embedded on a sphere defined over a parameter space, the
left and right boundary sides of which are identified, and the top and
bottom boundary sides are contracted.

<!-- ======================================================================= -->
\section arr_sec_extending Extending the Arrangement
<!-- ======================================================================= -->

Developing applications that use arrangements to solve problems that
are a bit more complicated than the problems presented in previous
chapters requires the ability to adapt the arrangement data structure
to the application needs. One technique to do this is to extend the
arrangement with auxiliary, usually non-geometric, data. In this
chapter we describe several ways to extend an arrangement data
structure.

<!-- ----------------------------------------------------------------------- -->
\subsection arr_ssecnotif The Notification Mechanism
<!-- ----------------------------------------------------------------------- -->

In some cases it is essential to know exactly what happens inside a
specific arrangement object. For example, when a new curve is inserted
into an arrangement, it may be necessary to keep track of the faces
that are split due to this insertion operation.  Other important
examples are the point-location strategies that require auxiliary data
structures (see Section \ref arr_ssecpl), which must be kept
up-to-date when the arrangement changes. The \ref
PkgArrangementOnSurface2 package offers a mechanism that uses
<em>observers</em> (see \cgalCite{cgal:ghjv-dpero-95}). The objective
behind this mechanism is to define a one-to-many dependency between
objects, so that when one object changes state, all its dependents are
notified and updated automatically. The observed object does not know
anything about the observers. It merely "publishes" information about
changes when they occur. In our case observers can be attached to an
arrangement object.

An observer object that observes changes in an arrangement object
stores a pointer to the attached arrangement object. It receives
notifications about the changes this arrangement undergoes. The
observer receives notifications <em>just before</em> a structural
change occurs in the arrangement and <em>immediately after</em> such a
change takes place.  An observer object that observes changes in an
arrangement object of type `Arrangement` must be of a type derived
from `Arrangement::Observer`, which is an alias to
`Aos_observer<Arrangement_on_surface_2>`, where
`Arrangement_on_surface_2` is the type of the arrangement object or
its base type. An instance of `Aos_observer<>` serves as a base type
for other observer classes and defines a set of virtual notification
functions, with default empty implementations.  You can also use the
template alias `Arr_observer<Arrangement_2>`, where `Arrangement_2` is
the type of the arrangement object in case it is derived from an
instance of the template `Arrangement_on_surface_2`.  The set of
functions can be divided into three categories, as follows:

<OL>

<LI>Notifiers of changes that affect the entire topological structure
of the arrangement. This category consists of two pairs
(<em>before</em> and <em>after</em>) that notify the observer of the
following changes:

<UL>
<LI>The arrangement is cleared.
<LI>The arrangement is assigned with the contents of another arrangement.
</UL>

<LI>Pairs of notifiers before and after a local change that occurs in
the topological structure. Most notifier functions belong to this
category. The relevant local changes include:

<UL>

<LI>A new vertex is constructed and associated with a point.

<li>An edge\cgalFootnote{The term "edge" refers here to a pair of twin
halfedges.} is constructed and associated with an \f$x\f$-monotone
curve.

<LI>An edge is split into two edges.

<LI>An existing face is split into two faces, as a consequence of the
insertion of a new edge.

<LI>A hole is created in the interior of a face.

<LI>Two holes are merged to form a single hole, as a consequence of
the insertion of a new edge.

<LI>A hole is moved from one face to another, as a consequence of a
face split.

<LI>Two edges are merged into one edge.

<LI>Two faces are merged into one face, as a consequence of the
removal of an edge that used to separate them.

<LI>One hole is split into two, as a consequence of the deletion of an
edge that used to connect the two components.

<LI>A vertex is removed.
<LI>An edge is removed.
<LI>A hole is deleted from the interior of a face.

</UL>

<LI>Notifiers about a change caused by a free function; see Section
\ref arr_secgl_funcs for a discussion on the free functions.  This
category consists of a single pair of notifiers, namely
`before_global_change()` and `after_global_change()`. Neither of these
functions is invoked by methods of the `Arrangement_2` class template.
Instead, they are called by the free functions themselves. It is
implied that no point-location queries (or any other queries for that
matter) are issued between the call to `before_global_change()` and
the call to `after_global_change()`.

</OL>

See the Reference Manual for a detailed specification of the
`Aos_observer` class template and the prototypes of all notification
functions.

Each arrangement object stores a list of pointers to `Aos_observer`
objects. This list may be empty, in which case the arrangement does
not have to notify any external class on the structural changes it
undergoes. If, however, there are observers associated with the
arrangement object, then whenever one of the structural changes listed
in the first two categories above is about to take place, the
arrangement object performs a <em>forward</em> traversal on this list
and invokes the appropriate function of each observer. After the
change takes place the observer list is traversed <em>backward</em>
(from tail to head), and the appropriate notification function is
invoked for each observer.
<!--  This allows for the nesting of \Index{observer} objects. -->

Concrete arrangement-observer classes should inherit from
`Aos_observer`. When an observer is constructed, it is attached to a
valid arrangement supplied to the observed constructor, or
alternatively the observer can be attached to the arrangement at a
later time.  When this happens, the observer object inserts itself
into the observer list of the associated arrangement and starts
receiving notifications whenever this arrangement changes
thereafter. Subsequently, the observer object unregisters itself by
removing itself from this list just before it is destroyed. Most
concrete observer-classes do not need to use the full set of
notifications. Thus, the bodies of all notification methods defined in
the base class `Aos_observer` are empty. A concrete observer that
inherits from `Aos_observer` needs to override only the relevant
notification methods. The remaining methods are invoked when
corresponding changes occur, but they do nothing.

The trapezoidal map RIC and the landmark point-location strategies
both use observers to keep their auxiliary data structures
up-to-date. In addition, you can define your own observer classes,
inheriting from the base observer class and overriding the relevant
notification functions, as required by their applications.

<!-- ----------------------------------------------------------------------- -->
\cgalFigureBegin{aos_fig-observer,observer.png}
An arrangement of six line segments, as constructed in \ref
Arrangement_on_surface_2/observer.cpp.  The halfedge \f$e_v\f$
(dashed) is eventually removed, so that the final arrangement consists
of four faces (one unbounded and three bounded ones).
\cgalFigureEnd
<!-- ----------------------------------------------------------------------- -->

The following example shows how to define and use an observer
class. The observer in the example responds to changes in the
arrangement faces. It prints a message whenever a face is split into
two due to the insertion of an edge and whenever two faces merge into
one due to the removal of an edge. The layout of the arrangement is
depicted in \cgalFigureRef{aos_fig-observer}; it comprises six line
segments and eight edges (the horizontal segment \f$s_h\f$ and the
vertical segment \f$s_v\f$ induce two edges each).  The halfedge
\f$e_v\f$ is induced by the vertical segment \f$s_v\f$. First, it is
associated with the (entire) segment, as obtained by the `insert()`
function; see Line 40 in the code excerpt below. After the insertion
of \f$s_h\f$ (see Line 41) the halfedge is split. After the split
\f$e_v\f$ (drawn dashed in the figure) is associated with the lower
split curve. Eventually, it is removed (along with its twin
halfedge). Note the face-split notifications that are invoked as a
consequence of the insertion of \f$s_v\f$ and \f$s_h\f$ and the
face-merge notification that is invoked as a consequent of the removal
of \f$e_v\f$.

\cgalExample{Arrangement_on_surface_2/observer.cpp}

Observers are especially useful when the \dcel records are
extended and store additional data-fields, since they help update
this data stored in these fields, as the following sections reveal.

<!-- ----------------------------------------------------------------------- -->
\subsection arr_ssecex_dcel Extending the DCEL
<!-- ----------------------------------------------------------------------- -->

For many applications of the \ref PkgArrangementOnSurface2 package it
is necessary to store additional information (perhaps of non-geometric
nature) with the arrangement features. Vertices are associated with
\link Arrangement_on_surface_2::Point_2 `Point_2`\endlink objects and
edges (halfedge pairs) are associated with \link
Arrangement_on_surface_2::X_monotone_curve_2
`X_monotone_curve_2`\endlink objects, both defined by the traits
class. Extending the geometric traits-class types by using a
traits-class decorator, as explained in Section \ref arr_ssec_tr_decorators,
might be a sufficient solution for some applications.  However, the
\dcel faces are not associated with any geometric object, so
traits-class decorators cannot help here. Extending the \dcel face
records comes in handy is such cases. As a matter of fact, it is
possible to conveniently extend all \dcel records (namely
vertices, halfedges, and faces), which is advantageous for some
applications.

All examples presented so far use the default \dcel; namely, they
employ the `Arr_default_dcel<Traits>` instance. This is done
implicitly, as this instance of the `Arr_default_dcel` class template
serves as the default parameter for the `Arrangement_2` class
template; see Section \ref aos_ssec-basic-arr_class. The default \dcel
class associates points with vertices and \f$x\f$-monotone curves with
halfedges, but nothing more.  In this section we show how to use
alternative \dcel types to extend the desired \dcel records.

<!-- ----------------------------------------------------------------------- -->
\subsubsection arr_sssecex_dcel_face Extending the DCEL Faces
<!-- ----------------------------------------------------------------------- -->

The `Arr_face_extended_dcel<Traits, FaceData>` class-template is used
to associate auxiliary data field of type `FaceData` to each face
record in the \dcel.  When the `Arrangement_2<Traits,Dcel>` class
template is instantiated, substituting the \dcel parameter with an
instance of this class template, the interface of the nested `Face`
type is extended with the access function `data()` and with the
modifier `set_data()`. Using these extra functions it is
straightforward to access and maintain the auxiliary face-data field.

Note that the extra data-fields must be maintained by the user
application. User may choose to construct their arrangement, and may
only then go over the faces and store data in the appropriate
data-fields of the arrangement faces. However, in some cases the face
data can only be computed when the face is created (split from another
face or merged with another face). In such cases one can use an
arrangement observer tailored for this task, which receives updates
whenever a face is modified and sets its data field accordingly.

<!-- ----------------------------------------------------------------------- -->
\cgalFigureBegin{aos_fig-dcel_extension,dcel_extension.png}
An arrangement of six line segments, as constructed in \ref
Arrangement_on_surface_2/face_extension.cpp and \ref
Arrangement_on_surface_2/dcel_extension.cpp (in \ref
Arrangement_on_surface_2/dcel_extension.cpp we treat the segments as
directed, so they are drawn as arrows directed from the source to the
target). The indices associated with the halfedges in
\ref Arrangement_on_surface_2/face_extension.cpp are shown in brackets.
\cgalFigureEnd
<!-- ----------------------------------------------------------------------- -->

The next example constructs an arrangement that contains seven bounded
faces induced by six line segments, \f$s_1, \ldots, s_6\f$, as shown
in \cgalFigureRef{aos_fig-dcel_extension}. An observer gets notified
each time a new face \f$f\f$ is created, and it associates \f$f\f$
with a running index, where the index of the unbounded face is 0. As a
result, the faces are numbered according to their creation order,
These numbers are shown in brackets, and their order can easily be
verified by examining the insertion order of the
segments.\cgalFootnote{For simplicity, the particular observer used
must be attached to an empty arrangement. It is not difficult however
to modify the program to handle the general case of attaching a
similar observer to a non-empty arrangement.}

\cgalExample{Arrangement_on_surface_2/face_extension.cpp}

<!-- ----------------------------------------------------------------------- -->
\subsubsection arr_sssecex_dcel_all Extending All DCEL Records
<!-- ----------------------------------------------------------------------- -->

As you continue to use arrangements to solve various problems you will
find out that the ability to extend the face records is
crucial. Perhaps less common, but also important to satisfy, is the
need to extend the vertex and halfedge records as well. The
`Arr_extended_dcel<Traits, VertexData, HalfedgeData, FaceData>`
class-template is used to associate auxiliary data fields of types
`VertexData`, `HalfedgeData`, and `FaceData` with \dcel vertex,
halfedge, and face record types, respectively.  When the
`Arrangement_2<Traits,Dcel>` class template is instantiated,
substituting the `Dcel` parameter with an instance of this \dcel
class-template, the interfaces of the nested types Vertex, Halfedge,
and Face are extended with the access function `data()` and with the
modifier `set_data()`.

The next example shows how to use a \dcel with extended vertex,
halfedge, and face records. In this example each vertex is associated
with a color, which is either blue, red, or white, depending on whether
the vertex is isolated, represents a segment endpoint, or represents
an intersection point. (Notice that the coloring rules suggested here
apply only to non-degenerate arrangements, where the sets of isolated
points, curve endpoints, and intersection points are mutually
exclusive.) In this example segments are treated as directed objects.
Each halfedge is associated with Boolean flag indicating whether its
direction is the same as the direction of its associated segment. Each
face is also extended to store the size of its outer boundary, that
is, the number of halfedges along its outer boundary.

The constructed arrangement, depicted in
\cgalFigureRef{aos_fig-dcel_extension}, is similar to the
arrangement constructed in the previous example.  In this case,
however, we do not use an observer; instead, all auxiliary data-fields
are set after the construction phase.  Also note that the data fields
are properly maintained when the arrangement is copied to another
arrangement object.

\cgalExample{Arrangement_on_surface_2/dcel_extension.cpp}

\cgalAdvancedBegin

The various \dcel classes presented in this section are well
suited for most applications based on the \ref
PkgArrangementOnSurface2 package. They are all defined using helper
constructs, and in particular the base \dcel class-template
`Arr_dcel_base}`.  However, there are cases where special
requirements, not addressed by these \dcel classes, are needed.
In such cases you may explicitly extend the base \dcel
class-template, as described in the next paragraph, or implement your
own \dcel class from scratch and use the resulting \dcel to
instantiate the `Arrangement_2` class template. In any case such a
class must model the concept `AosDcel` or its refinement
`AosDcelWithRebind`. The latter requires a `rebind` struct
template, which implements a policy-clone idiom. Here, the \dcel
class is the policy class and the `rebind` member template struct
is used to pass a different traits type parameter to the policy class
template.

In some cases you may want to extend a certain feature type with
several fields. You can gather all these fields (and perhaps methods
that access and retrieve these fields) in a single construct, and
substitute the appropriate parameter of the class template
`Arr_extended_dcel<Traits, VertexData, HalfedgeData, FaceData>` with
this construct. Naturally, you can define three constructs, one for
each feature type, and substitute all the three corresponding template
parameters appropriately. For example, consider an arrangement that
represents a map where features of the same type represent different
cartographic entities, e.g., an edge represents a road, a river, or a
railway. We would like to associate two strings with each feature,
namely, the name and the type of the feature. Following the solution
above, accessing or retrieving a specific field will always require an
indirection through one of the member functions `set_data()` and
`data()`. While this indirection is typically resolved at compile
time, and thus has no negative effect on the running time of the
generated code, it may have some implication on the space consumption
due to compiler padding.\cgalFootnote{Compilers add pad bytes into
user-defined constructs to comply with alignment restrictions imposed
by target microprocessors.} Moreover, the code may look cumbersome.

The extended \dcel class that addresses the problem raised above
is listed below. Here, each feature type is explicitly extended with
two strings, namely, `name` and `type`, eliminating the data
constructs.

\code{.cpp}
#include <string>

#include <CGAL/basic.h>
#include <CGAL/Arr_dcel_base.h>

// The map-extended dcel vertex.
template <typename Point_2>
class Arr_map_vertex : public CGAL::Arr_vertex_base<Point_2> {
public:
  std::string name, type;
};

// The map-extended dcel halfedge.
template <typename X_monotone_curve_2>
class Arr_map_halfedge : public CGAL::Arr_halfedge_base<X_monotone_curve_2> {
public:
  std::string name, type;
};

// The map-extended dcel face.
class Arr_map_face : public CGAL::Arr_face_base {
public:
  std::string name, type;
};

// The map-extended dcel.
template <typename Traits>
class Arr_map_dcel : public
  CGAL::Arr_dcel_base<Arr_map_vertex<typename Traits::Point_2>,
                      Arr_map_halfedge<typename Traits::X_monotone_curve_2>,
                      Arr_map_face>
{};
\endcode

\cgalAdvancedEnd

<!-- ----------------------------------------------------------------------- -->
\subsection arr_ssecoverlay Overlaying Arrangements
<!-- ----------------------------------------------------------------------- -->

Assume that we are given two geographic maps represented as
arrangements, with some data objects attached to their faces,
representing some geographic information---for instance, a map of the
annual precipitation in some country and a map of the vegetation in
the same country---and you are asked to locate, for example, places
where there is a pine forest <em>and</em> the annual precipitation is
between 1,000mm and 1,500mm. Overlaying the two maps may help you
figure out the answer.  Computing the overlay of two two-dimensional
arrangements is also useful for supporting Boolean set operations on
polygons or general polygons; see e.g., \cgalCite{cgal:behhms-cbcab-02}).

Formally, the <em>map overlay</em> of two two-dimensional subdivisions
\f$\mathcal{S}_1\f$ and \f$\mathcal{S}_2\f$ is a two-dimensional
subdivision \f$\mathcal{S}\f$, such that there is a face \f$f\f$ in
\f$\mathcal{S}\f$ iff there are faces \f$f_1\f$ and \f$f_2\f$ in
\f$\mathcal{S}_1\f$ and \f$\mathcal{S}_2\f$, respectively, such that
\f$f\f$ is a maximal connected component of \f$f_1 \cap f_2\f$.

The overlay of two given arrangements, conveniently referred to as the
"blue" and the "red" arrangements, is implemented as a plane-sweep
algorithm employing a dedicated visitor; see Section
\ref arr_ssec_sweep.  The \f$x\f$-monotone curve type is extended with
a color attribute (whose value is either blue or red); see Section \ref
arr_ssec_tr_decorators. With the help of the extended type unnecessary
computations are filtered out while the plane is swept, yielding an
efficient process. For example, monochromatic intersections are not
computed.

The plane-sweep visitor that concretizes the overlay operation needs
to construct a \dcel that properly represents the overlay of two
input arrangements. A face in the overlay arrangement corresponds to
overlapping regions of the blue and red faces. An edge in the overlay
arrangement is due to a blue edge, a red edge, or an overlap of two
differently colored edges. An overlay vertex is due to a blue vertex,
a red vertex, a coincidence of two differently colored vertices, or an
intersection of a blue and a red curve.

The call \link overlay() `overlay(arr_r, arr_b, arr_o,
ovl_traits)`\endlink constructs the arrangement `arr_o`, which is the
overlay of two input arrangement `arr_r` and `arr_b`. All three
arrangements must use the same geometric primitives. In other words,
their types are instances of the `Arrangement_2<Traits,Dcel>` class
template, where the `Traits` parameter is substituted by three
geometry-traits classes, respectively. The geometry-traits classes of
the input arrangements must be convertible to the geometry-traits
class of the resulting arrangement.\cgalFootnote{It is sufficient that
all three geometry-traits classes used to instantiate the three types
of arrangements derive from a common ancestor that models the
geometry-traits concept.} Typically, all three arrangements use the
same geometry-traits class.

The `overlay()` function template is suitable for arrangements that do
not store any additional data with their \dcel records; namely,
arrangements defined using the default \dcel, which is the instance
`Arr_default_dcel<Traits>`. Typically, the overlay arrangement in this
case does not store extra data with its \dcel records as well. (If it
does, the additional data-fields cannot be computed by the overlay
operation in this case.) The overlay arrangement is equivalent to the
arrangement induced by all curves of `arr_r` and `arr_b`. Indeed, it
is possible to obtain the same result using the standard
insertion-operations instead, but, as mentioned above, this is less
efficient.

<!-- ----------------------------------------------------------------------- -->
\cgalFigureBegin{aos_figex_overlay,overlay.png}
Overlaying two simple arrangements of line segments, as done in \ref
Arrangement_on_surface_2/overlay.cpp and \ref
Arrangement_on_surface_2/face_extension_overlay.cpp. In \ref
Arrangement_on_surface_2/face_extension_overlay.cpp the two bounded
faces are considered as <em>marked</em>, and the octagonal face which
is the intersection of the two marked faces is denoted by \f$f_0\f$.
\cgalFigureEnd
<!-- ----------------------------------------------------------------------- -->

The next program constructs two simple arrangements; each comprises
four line segments that form a square, as depicted in
\cgalFigureRef{aos_figex_overlay}. The program computes the overlay of the
two arrangements. The resulting arrangement has 16 vertices, 24
edges, and 10 faces (including the unbounded one.

\cgalExample{Arrangement_on_surface_2/overlay.cpp}

The `overlay()` function template is overloaded with a variant that
accepts four arguments, that is, `overlay(arr_r, arr_b, arr_o,
ovl_traits)`. The type of the `ovl_traits` additional argument,
referred to as the overlay traits, must model the `OverlayTraits`
concept described below. Assume that `arr_r` is of type
`Arrangement_2<Traits,Dcel_R>`, `arr_b` is of type
`Arrangement_2<Traits,Dcel_B>`, and the resulting `arr_o` is of type
`Arrangement_2<Traits,Dcel_O>`. The overlay traits enables the
creation of `Dcel_O` records in the overlay arrangement from the
features of `Dcel_R` and `Dcel_B` records from the arrangements
`arr_r` and `arr_b`, respectively.

We distinguish between (i) an overlay of two arrangements that store
additional data-fields only with their faces e.g., the geographic-map
example given at the beginning of this section) and (ii) an overlay of
two arrangements that store additional data fields with all their
\dcel records (or at least not only with their faces).  The
arrangement that results from overlaying two face-extended
arrangements typically also stores additional data-fields with its
faces. The types of such arrangements, for example, could be instances
of the `Arrangement_2<Traits,Dcel>` class template, where the `Dcel`
parameters are substituted by instances of the
`Arr_face_extended_dcel` class template (see Section \ref
arr_sssecex_dcel_face). The data field that is attached to an overlay
face can be computed from the data fields of the two faces (in `arr_r`
and `arr_b`) that induce the overlay face. Similarly, the arrangement
that results from overlaying two arrangements that store additional
data fields with all their \dcel records typically also stores
additional data-fields with all its \dcel records. The types of
such arrangements, for example, could be instances of the
`Arrangement_2<Traits,Dcel>` class template, where the `Dcel`
parameters are substituted by instances of the `Arr_extended_dcel`
class template (see Section \ref arr_sssecex_dcel_all). The data field
attached to an overlay feature can be computed from the data fields of
the two features (in `arr_r` and `arr_b`) that induce the overlay
feature.

As mentioned in the previous paragraph, if any of the \dcel
records of your arrangements are extended, you can pass a fourth
argument to the `overlay()` call, also referred to as the overlay
traits, to control the generation of the extended data in the
resulting arrangement. If only the face records are extended, the type
of the overlay traits can be an instance of the class template
`Arr_face_overlay_traits<ArrangementR,ArrangementB,ArrangementO,OverlayFaceData>`,
which models the concept `OverlayTraits`. An object of this type
operates on face-extended arrangements. When instantiated, the
`OverlayFaceData` parameter must be substituted by a functor that is
capable of combining two face-data fields of types
`ArrangementR::Dcel::Face_data` and `ArrangementB::Dcel::Face_data`
and computing the output `ArrangementO::Dcel::Face_data` object. The
face-overlay traits-class uses this functor to properly construct the
overlay faces.

The following example shows how to compute the intersection of two
polygons using the `overlay()` function template. It uses a
face-extended \dcel type to instantiate the arrangement
classes. Each face of the the \dcel is extended with a Boolean
flag. A polygon is represented as a <em>marked</em> arrangement face
(whose flag is set). The example uses an instance of the
`Arr_face_overlay_traits<ArrR,ArrB,ArrO,OverlayFaceData>` class
template as the face-overlay traits class where the `OverlayFaceData`
template parameter is substituted by a functor that simply performs
a logical <em>and</em> operation on Boolean flags. As a result, a face
in the overlay arrangement is marked only when it corresponds to an
overlapping region of two marked faces in the input
arrangements. Namely, it is part of the intersection of the two
polygons. The example computes the intersection between a
parallel-axis square and a congruent square rotated
\f$45^\circ\f$. The resulting polygon from the intersection operation
is an octagon, which corresponds to the face~\f$\hat{f}\f$ in the
arrangement depicted in \cgalFigureRef{aos_figex_overlay}.

\cgalExample{Arrangement_on_surface_2/face_extension_overlay.cpp}

<!-- ----------------------------------------------------------------------- -->
\cgalFigureBegin{aos_figex_overlay_unbounded,overlay_unbounded.png}
Overlaying two arrangements of lines that have unbounded faces, as
done in \ref Arrangement_on_surface_2/overlay_unbounded.cpp.
\cgalFigureEnd
<!-- ----------------------------------------------------------------------- -->

The next example, depicted in
\cgalFigureRef{aos_figex_overlay_unbounded}, demonstrates the face
overlay of two arrangements that have unbounded faces as well as
bounded ones.  The first arrangement (blue) is induced by the two
lines \f$y = x\f$ and \f$y = -x\f$, which subdivide the plane into
four unbounded faces, labeled \f$A\f$, \f$B\f$, \f$C\f$ and
\f$D\f$. The second arrangement (red) comprises four line segments
that form a square-shaped face indexed \f$1\f$. The unbounded face is
indexed 2. When the two arrangements are overlaid, each of the four
faces \f$A\f$, \f$B\f$, \f$C\f$ and \f$D\f$ is split into an unbounded
face (indexed 2) and a bounded face (indexed 1), so the faces of the
resulting arrangement are labeled \f$A_1, A_2, \ldots, D_1,
D_2\f$. `boost::lexical_cast` is used to cast the integral indices
into strings to produce the final labels.

\cgalExample{Arrangement_on_surface_2/overlay_unbounded.cpp}

If the red and blue arrangements store additional data-fields with all
their \dcel records, and the data associated with the overlay
\dcel features should be computed from the red and blue \dcel
features that induce it, then an appropriate overlay-traits argument
must be passed to the `overlay()` call. The overlay-traits type models
the `OverlayTraits` concept, which requires the provision of ten
functions that handle all possible cases as listed below. Let
\f$v_r\f$, \f$e_r\f$, and \f$f_r\f$ denote input <span
style="color:red;">red</span> features, i.e., a vertex, an edge, and a
face, respectively, \f$v_b\f$, \f$e_b\f$, and \f$f_b\f$ denote input
<span style="color:blue;">blue</span> features, and \f$v\f$, \f$e\f$,
and \f$f\f$ denote output features.

<OL>

<LI> A new vertex \f$v\f$ is induced by coinciding vertices
\f$v_r\f$ and \f$v_b\f$.</LI>

<LI> A new vertex \f$v\f$ is induced by a vertex \f$v_r\f$ that lies
on an edge \f$e_b\f$.</LI>

<LI> An analogous case of a vertex \f$v_b\f$ that lies on an edge
\f$e_r\f$.</LI>

<LI> A new vertex \f$v\f$ is induced by a vertex \f$v_r\f$ that is
  contained in a face \f$f_b\f$.</LI>

<LI> An analogous case of a vertex \f$v_b\f$ contained in a face
  \f$f_r\f$.</LI>

<LI> A new vertex \f$v\f$ is induced by the intersection of two edges
  \f$e_r\f$ and \f$e_b\f$.</LI>

<LI> A new edge \f$e\f$ is induced by the (possibly partial) overlap
  of two edges \f$e_r\f$ and \f$e_b\f$.</LI>

<LI> A new edge \f$e\f$ is induced by the an edge \f$e_r\f$ that is
  contained in a face \f$f_b\f$.</LI>

<LI> An analogous case of an edge \f$e_b\f$ contained in a face
  \f$f_r\f$.</LI>

<LI> A new face \f$f\f$ is induced by the overlap of two faces
  \f$f_r\f$ and \f$f_b\f$.</LI>

</OL>

The `Overlay_color_traits` class template listed below models the
concept `OverlayTraits`.  It assumes that each feature of the input
arrangements and of the overlay arrangement is extended with an RGB
color stored as an `unsigned int`. It defines ten member functions
that correspond to the ten cases listed above. Each of these functions
accepts three handles as follows: two handles to the two features of
the input arrangements, respectively, that induce a feature of the
overlay arrangement and a handle to the induced overlay-arrangement
feature. Each of these member functions blends the colors attached to
the inducing features and assigns the resulting color to the induced
feature. The `Overlay_color_traits` class template is defined in the
header file `Overlay_color_traits.h`.

\code{.cpp}
template <typename Arrangement> struct Overlay_color_traits {
  using Color = unsigned int;
  using V_const_handle = typename Arrangement::Vertex_const_handle;
  using H_const_handle = typename Arrangement::Halfedge_const_handle;
  using F_const_handle = typename Arrangement::Face_const_handle;
  using V_handle = typename Arrangement::Vertex_handle;
  using H_handle = typename Arrangement::Halfedge_handle;
  using F_handle = typename Arrangement::Face_handle;

  // Compute the average of the red, green, and blue components separately.
  Color blend(Color color1, Color color2) const {
    return
      ((((color1 & 0x000000ff) + (color2 & 0x000000ff)) / 2) & 0x000000ff) |
      ((((color1 & 0x0000ff00) + (color2 & 0x0000ff00)) / 2) & 0x0000ff00) |
      ((((color1 & 0x00ff0000) + (color2 & 0x00ff0000)) / 2) & 0x00ff0000);
  }

  void create_face(F_const_handle f1, F_const_handle f2, F_handle f) const
  { f->set_data(blend(f1->data(), f2->data())); }
  void create_vertex(H_const_handle h1, H_const_handle h2, V_handle v) const
  { v->set_data(blend(h1->data(), h2->data())); }
  void create_vertex(V_const_handle v1, V_const_handle v2, V_handle v) const
  { v->set_data(blend(v1->data(), v2->data())); }
  void create_vertex(V_const_handle v1, H_const_handle h2, V_handle v) const
  { v->set_data(blend(v1->data(), h2->data())); }
  void create_vertex(H_const_handle h1, V_const_handle v2, V_handle v) const
  { v->set_data(blend(h1->data(), v2->data())); }
  void create_vertex(F_const_handle f1, V_const_handle v2, V_handle v) const
  { v->set_data(blend(f1->data(), v2->data())); }
  void create_vertex(V_const_handle v1, F_const_handle f2, V_handle v) const
  { v->set_data(blend(v1->data(), f2->data())); }
  void create_edge(H_const_handle h1, H_const_handle h2, H_handle h) const
  {
    h->set_data(blend(h1->data(), h2->data()));
    h->twin()->set_data(blend(h1->data(), h2->data()));
  }
  void create_edge(H_const_handle h1, F_const_handle f2, H_handle h) const
  {
    h->set_data(blend(h1->data(), f2->data()));
    h->twin()->set_data(blend(h1->data(), f2->data()));
  }
  void create_edge(F_const_handle f1, H_const_handle h2, H_handle h) const
  {
    h->set_data(blend(f1->data(), h2->data()));
    h->twin()->set_data(blend(f1->data(), h2->data()));
  }
};
\endcode

<!-- ----------------------------------------------------------------------- -->
\cgalFigureBegin{aos_figex_overlay_color,overlay_color.png}

The overlay of two extended arrangements]{The overlay (c) of two
arrangements (a) and (b). Each feature of the arrangements is extended
with a color. The color of each feature of the overlay arrangement is
the blend of the colors of the two inducing features.

\cgalFigureEnd
<!-- ----------------------------------------------------------------------- -->

The example program listed below computes the overlay, depicted in
\cgalFigureRef{aos_figex_overlay_color}, of the two arrangements
depicted in (a) and (d). Each feature of the input arrangements and of
the overlay arrangement is extended with an RGB color stored as an
`unsigned int`. The vertices, halfedges, and faces of the red
arrangement are assigned three different shades of red. Similarly, the
vertices, halfedges, and faces of the blue arrangement are assigned
three different shades of blue. Using an instance of the
`Overlay_color_traits` class template as the overlay traits, each
feature of the overlay arrangement is assigned a color that is a blend
of the colors attached to the inducing features.

\cgalExample{Arrangement_on_surface_2/overlay_color.cpp}

<!-- ----------------------------------------------------------------------- -->
\subsection arr_ssecarr_with_hist Storing the Curve History
<!-- ----------------------------------------------------------------------- -->

When you constructs an arrangement induced by a set \f$\mathcal{C}\f$
of arbitrary two-dimensional curves, you end up with a collection
\f$\mathcal{C}''\f$ of \f$x\f$-monotone subcurves of \f$\mathcal{C}\f$
that are pairwise disjoint in their interior; see Section \ref
aos_sec-intro. These subcurves are associated with the arrangement
edges (more precisely, with pairs of \dcel halfedges). The connection
between the originating input curves and the arrangement edges is lost
during the construction process. This loss might be acceptable for
some applications. However, in many practical cases it is important to
determine the input curves that give rise to the final subcurves.

The
`Arrangement_on_surface_with_history_2<GeometryTraits,TopologyTraits>`
class-template extends the
`Arrangement_on_surface_2<GeometryTraits,TopologyTraots>` class
template by keeping an additional container of input curves
representing \f$\mathcal{C}\f$, and by maintaining a cross-mapping
between these curves and the arrangement edges they induce. Similarly,
the `Arrangement_with_history_2<GeometryTraits,Dcel>` class-template
extends the `Arrangement_2<GeometryTraits,Dcel>` class template. The
`GeometryTraits` template parameter, of either class templates, must
be substituted by a model of the `AosTraits_2` concept; see
Section \ref aos_ssec-insert_gen. It should define the \link
AosTraits_2::Curve_2 `Curve_2`\endlink type and support its
subdivision into \link AosBasicTraits_2::X_monotone_curve_2
`X_monotone_curve_2`\endlink objects, among the others.  The `Dcel`
parameter must be substituted by a model of the `AosDcel`
concept. You can use either the default \dcel class or an extended
\dcel class (see Section \ref arr_ssecex_dcel) based on your needs. An
arrangement that support the cross-mapping mentioned above is referred
to as an arrangement with history. In the following we use the
`Arrangement_with_history_2<>` class template to demonstrate
arrangements with history. However, the explanation applies also to
`Arrangement_on_surface_with_history_2<>`, as the type of the
embedding surface is irrelevant to the discussion.

<!-- ----------------------------------------------------------------------- -->
\subsubsection arr_sssecarrwh_traverse Traversing an Arrangement with History
<!-- ----------------------------------------------------------------------- -->

The `Arrangement_with_history_2` class template extends the
`Arrangement_2` class template. Thus, all the iterator and circulator
types that are defined in the base class are also available in
`Arrangement_with_history_2`.  (Refer to Section \ref
arr_ssectraverse for a comprehensive review of this functionality.)

As mentioned above, the `Arrangement_with_history_2` class template
maintains a container of input curves, which can be accessed using
curve handles.  Let `arr` identify an object, the type of which is an
instance of this template. The call \link
Arrangement_with_history_2::number_of_curves()
`arr.number_of_curves()`\endlink returns the number of input curves
stored in the container, while \link
Arrangement_with_history_2::curves_begin()
`arr.curves_begin()`\endlink and \link
Arrangement_with_history_2::curves_end() `arr.curves_end()`\endlink
return `Arrangement_with_history_2::Curve_iterator` objects that
define the range of curves that induce the arrangement.  The value
type of this iterator is \link Arrangement_with_history_2::Curve_2
`Curve_2`\endlink. Moreover, the curve-iterator type is convertible to
`Arrangement_with_history_2::Curve_handle`, which is used for
accessing the stored curves. For convenience, the corresponding
constant-iterator and constant-handle types are also defined.

As mentioned in the previous paragraph, a `Curve_handle` object `ch`
serves as a pointer to a curve stored in an arrangement-with-history
object `arr`. Using this handle, it is possible to obtain the number
of arrangement edges this curve induces by calling \link
Arrangement_with_history_2::number_of_induced_edges()
`arr.number_of_induced_edges(ch)`\endlink. The functions \link
Arrangement_with_history_2::induced_edges_begin()
`arr.induced_edges_begin(ch)`\endlink and \link
Arrangement_with_history_2::induced_edges_end()
`arr.induced_edges_end(ch)`\endlink return iterators of type
`Arrangement_with_history_2::Induced_edges_iterator` that define the
range of edges induced by `ch`. The value type of these iterators is
\link Arrangement_on_surface_2::Halfedge_handle
`Halfedge_handle`\endlink. It is thus possible to traverse all
arrangement edges induced by an input curve.

The ability to perform the inverse mapping is also important. Given an
arrangement edge, you may want to determine which input curve induces
it. In case the edge represents an overlap of several curves, you
should be able to trace all input curves that overlap in this edge.
The `Arrangement_with_history_2` class template is extended by several
member functions that enable such an inverse mapping. Given a handle
to halfedge `e` in an arrangement with history object `arr`, the call
\link Arrangement_with_history_2::number_of_originating_curves()
`arr.number_of_originating_curves(e)`\endlink returns the number of
curves that induce the edge (which should be 1 in non-degenerate
cases, and 2 or more in case of overlaps), while \link
Arrangement_with_history_2::originating_curves_begin()
`arr.originating_curves_begin(e)`\endlink and \link
Arrangement_with_history_2::originating_curves_end()
`arr.originating_curves_end(e)`\endlink return
`Arrangement_with_history_2::Originating_curve_iterator` objects that
define the range of curves that induce `e`. The value type of these
iterators is \link Arrangement_with_history_2::Curve_2
`Curve_2`\endlink.

Overlaying two arrangement-with-history objects is possible only if
their types are instances of the
`Arrangement_with_history_2<Traits,Dcel>` class template, where the
respective `Traits` parameters are substituted by two traits classes
that are convertible to one another. In this case, the resulting
arrangement stores a consolidated container of input curves, and
automatically preserves the cross-mapping between the arrangement
edges and the consolidated curve-set. You may also employ an
overlay-traits class to maintain any type of auxiliary data stored
with the \dcel cells; see Section \ref arr_ssecoverlay.

<!-- ----------------------------------------------------------------------- -->
\subsubsection arr_sssecmodif_traverse Modifying an Arrangement with History
<!-- ----------------------------------------------------------------------- -->

The `Arrangement_with_history_2` class template extends the
`Arrangement_2` class template; thus, it inherits the fundamental
modification operations, such as \link
Arrangement_on_surface_2::assign() `assign()`\endlink and \link
Arrangement_on_surface_2::clear() `clear()`\endlink, from it. The
vertex-manipulation functions are also inherited and supported; see
Sections \ref arr_sssecmf_iso_verts and \ref arr_sssecinsert_point for
details. However, there are some fundamental differences between the
interfaces of the two class templates, which we highlight next.

The most significant difference between the arrangement-with-history
class template and the basic arrangement class template is the way
they handle their input curves.  `Arrangement_with_history_2` always
stores the \link Arrangement_with_history_2::Curve_2 `Curve_2`\endlink
objects that induce it. Thus, it is impossible to insert
\f$x\f$-monotone curves into an arrangement with history. The free
functions `insert_non_intersecting_curve()` and the version of
`insert()` that accept \f$x\f$-monotone curves, as well as their
aggregated versions), are therefore not available for
arrangement-with-history instances. Only the free overloaded functions
`insert()` that accept general curves, namely, the incremental
insertion function and the aggregate insertion function, are
supported; see Section \ref aos_ssec-insert_gen for a review of these
functions. Notice however that while the incremental insertion
function `insert(arr, c)` for an `Arrangement_2` object `arr` does not
have a return value, the corresponding arrangement-with-history
function returns a `Curve_handle` object that points to the inserted
curve.

As we are able to keep track of all edges induced by an input curve,
we also provide a free function that removes a curve from an
arrangement. By calling `remove_curve(arr,ch)`, where `ch` is a valid
curve handle, the given curve is deleted from the curve container, and
all edges induced solely by this curve (i.e., excluding overlapping
edges) are removed from the arrangement. The function returns the
number of edges that have been removed.

In some cases, users may need to operate directly on the arrangement
edges.  We first mention that the specialized insertion functions (see
Section \ref arr_sssecmf_insert_cv) are not supported, as they accept
\f$x\f$-monotone curves. Insertion can only be performed via the free
insertion-functions. The other edge-manipulation functions (see
Section \ref arr_sssecmf_halfedges) are, however, available, but have
a different interface that does not use \f$x\f$-monotone curves.

<UL>

<LI>Invoking \link Arrangement_with_history_2::split_edge()
  `split_edge(e,p)`\endlink splits the edge `e` at a given point `p`
  that lies in its interior.

<LI>Invoking \link Arrangement_with_history_2::merge_edge()
  `merge_edge(e1,e2)`\endlink merges the two given edges. There is a
  precondition that `e1` and `e2` shared a common end-vertex of degree
  2 prior to the merge, and that the \f$x\f$-monotone subcurves
  associated with these edges are mergeable.

<LI>It is possible to remove an edge by simply invoking \link
  Arrangement_with_history_2::remove_edge()
  `remove_edge(e)`\endlink.</LI>

</UL>

In all cases, the maintenance of cross-pointers for the appropriate
input curves will be done automatically.

Note that it is possible to attach observers to an
arrangement-with-history object in order to get detailed notifications
of the changes the arrangements undergoes; see Section \ref
arr_ssecnotif for the details).

<!-- ----------------------------------------------------------------------- -->
\cgalFigureBegin{aos_fig-curve_history,curve_history.png}
An arrangement with history as constructed in \ref
Arrangement_on_surface_2/curve_history.cpp. Note that \f$s_1\f$ and
\f$s_3\f$ overlap over two edges. The point-location query points
\f$q_1\f$, \f$q_2\f$, and \f$q_3\f$ are drawn as lightly shaded dots.
\cgalFigureEnd
<!-- ----------------------------------------------------------------------- -->

In the following example we construct a simple arrangement of six line
segments, as depicted in \cgalFigureRef{aos_fig-curve_history}, while
maintaining the curve history. Note that the input segments \f$s_1\f$
and \f$s_3\f$ overlap over two edges. The example demonstrates the
usage of the special traversal functions. It also shows how to issue
point-location queries on the resulting arrangement (the query points
\f$q_1\f$, \f$q_2\f$, and \f$q_3\f$ are drawn as crosses), using the
auxiliary function `locate_point()` defined in the header file
`point_location_utils.h`; see also Section \ref arr_ssecpl.

\cgalExample{Arrangement_on_surface_2/curve_history.cpp}

<!-- ----------------------------------------------------------------------- -->
\cgalFigureBegin{aos_fig-edge_manipulation_curve_hostory,edge_manipulation_curve_history.png}
An arrangement with history of nine circles as constructed in \ref
Arrangement_on_surface_2/edge_manipulation_curve_history.cpp. Note the
vertical tangency points of \f$c_0\f$, marked as dark dots, which
subdivide this circle into an upper half and a lower half, each
consists of 9 edges. The large circle \f$c_0\f$ is eventually removed
from the arrangement, with all 18 edges it induces.
\cgalFigureEnd
<!-- ----------------------------------------------------------------------- -->

The following example demonstrates the usage of the free
`remove_curve()` function. We construct an arrangement of nine
circles, while keeping a handle to each inserted circle. We then
remove the large circle \f$c_0\f$, which induces \f$18\f$ edges, as
depicted in \cgalFigureRef{aos_fig-edge_manipulation_curve_hostory}.
The example also shows how to use the \link
Arrangement_with_history_2::split_edge() `split_edge()`\endlink and
\link Arrangement_with_history_2::merge_edge() `merge_edge()`\endlink
member functions when operating on an arrangement-with-history object.

\cgalExample{Arrangement_on_surface_2/edge_manipulation_curve_history.cpp}

<!-- ======================================================================= -->
\section aos_sec-io Input/Output Streams and Visualization
<!-- ======================================================================= -->

In some cases, one would like to save an arrangement object
constructed by some application, so that later on it can be
restored. In other cases one would like to create nice drawings that
represent arrangements constructed by some application. These
drawings can be hard printed or displayed on a computer screen.

<!-- ----------------------------------------------------------------------- -->
\subsection aos_ssec-io-stream Input/Output Stream
<!-- ----------------------------------------------------------------------- -->

Consider an arrangement that represents a very complicated geographical
map, and assume that there are various applications that need to answer
point-location queries on this map. Naturally, you can store the set of
curves that induces the arrangement, but this implies that you would need
to construct the arrangement from scratch each time you need to reuse it.
A more efficient solution is to write the arrangement to a file in a format
that other applications can read.

This package provides an <em>inserter</em> (the `<<` operator) and an
<em>extractor</em> (the `>>` operator) for the
`Arrangement_2<Traits,Dcel>` class that inserts an arrangement object
into an output stream and extracts an arrangement object from an input
stream, respectively. The arrangement is written using a simple
predefined \ascii format that encodes the arrangement topology, as well
as all geometric entities associated with vertices and edges.

The ability to use the input/output operators, requires that the \link
AosBasicTraits_2::Point_2 `Point_2`\endlink type and the \link
AosBasicTraits_2::X_monotone_curve_2
`X_monotone_curve_2`\endlink type defined by the traits class both
support the `<<` and `>>` operators. The `Arr_conic_traits_2` class
(see Section \ref arr_sssectr_conic), the
`Arr_rational_function_traits_2` class (see Section \ref
arr_sssectr_ratfunc), and the `Arr_linear_traits_2` class (see Section
\ref arr_ssectr_segs) currently do not provide these operators for the
geometric types they define.  Thus, only arrangements of line segments
or of polylines can be written or read.

The following example constructs the arrangement depicted in
\cgalFigureRef{aos_fig-special_edge_insertion} and writes it to an
output file. It also demonstrates how to re-read the arrangement from
a file.

\cgalExample{Arrangement_on_surface_2/io.cpp}

<!-- ----------------------------------------------------------------------- -->
\subsection arr_ssecarr_io_aux_data Arrangements with Auxiliary Data
<!-- ----------------------------------------------------------------------- -->

\cgalAdvancedBegin The inserter and extractor both ignore any
auxiliary data stored with the arrangement features. Thus, they are
ideal for arrangements instantiated using the default \dcel, which is
the instance `Arr_default_dcel<Traits>`.  However, as explained in
Section \ref arr_ssecex_dcel, one can easily extend the arrangement
faces by using the `Arr_face_extended_dcel` template, extend all \dcel
records by using the `Arr_extended_dcel` template, or use the
`Arr_dcel` template. In such cases, it might be crucial that the
auxiliary data fields are written to the file and read from there.

The arrangement package includes the free functions
`write(arr, os, formatter)`, which writes the arrangement `arr`
to an output stream `os`, and `read(arr, os, formatter)`, which
reads the arrangement `arr` from an input stream `is`. Both
operations are performed using a `formatter` object, which defines
the I/O format. The package contains three formatter classes:
<UL>
<LI>`Arr_text_formatter<Arrangement>` defines a simple textual
I/O format for the arrangement topology and geometry, disregarding any
auxiliary data that may be associated with the arrangement features.
This is the default formatter used by the arrangement inserter and the
arrangement extractor, as defined above.
<LI>`Arr_face_extended_text_formatter<Arrangement>` operates on
arrangements whose \dcel representation is based on the
`Arr_face_extended_dcel<Traits,FaceData>` class (see
Section \ref arr_sssecex_dcel_face). It supports reading and writing
the auxiliary data objects stored with the arrangement faces provided
that the `FaceData` class supports an inserter and an extractor.
<LI>`Arr_extended_dcel_text_formatter<Arrangement>` operates on
arrangements whose \dcel representation is based on the
`Arr_extended_dcel<Traits,VertexData,HalfedgeData,FaceData>` class
(see Section \ref arr_sssecex_dcel_all). It supports reading and writing
the auxiliary data objects stored with the arrangement vertices, edges
and faces, provided that the `VertexData`, `HalfedgeData` and
`FaceData` classed all have inserters and extractors.
</UL>

The following example constructs the same arrangement as the example
`dcel_extension` does (see Section \ref arr_sssecex_dcel_all),
depicted in \cgalFigureRef{aos_fig-dcel_extension}, and writes it to
an output file. It also demonstrates how to re-read the arrangement
from a file:

\cgalExample{Arrangement_on_surface_2/dcel_extension_io.cpp}

You may develop your own formatter classes - models of the
`AosInputFormatter` and `AosOutputFormatter`
concepts, as defined in the Reference Manual.
Doing so, you can define other I/O formats, such as an XML-based
format or a binary format.
\cgalAdvancedEnd

<!-- ----------------------------------------------------------------------- -->
\subsection arr_ssecarr_io_hist Arrangements with Curve History
<!-- ----------------------------------------------------------------------- -->

Section \ref arr_ssecarr_with_hist introduces the
`Arrangement_with_history_2<Traits,Dcel>` class, which saves the
set of curves inducing an arrangement and maintains the relations between
these curves and the edges they induce. Naturally, when reading or writing
an arrangement-with-history instance we would like this information to be
saved to the output stream or restored from the input stream alongside
with the basic arrangement structure.

The arrangement package supplies an inserter and an extractor for the
`Arrangement_with_history_2<Traits,Dcel>` class. The arrangement is
represented using a simple predefined \ascii format. An object of the
`Arrangement_with_history_2<Traits,Dcel>` type can be saved and
restored, as long as the \link Arrangement_with_history_2::Curve_2
`Curve_2`\endlink type defined by the traits class---as well as the
\link Arrangement_with_history_2::Point_2 `Point_2`\endlink type and
the \link Arrangement_with_history_2::X_monotone_curve_2
`X_monotone_curve_2`\endlink types---support the `<<` and`>>`
operators.

The following example constructs the same arrangement as example
`curve_history` does, depicted in \cgalFigureRef{aos_fig-curve_history}, and
writes it to an output file. It also demonstrates how to re-read the
arrangement-with-history from a file:

\cgalExample{Arrangement_on_surface_2/io_curve_history.cpp}

\cgalAdvancedBegin
The arrangement package also includes the free functions `write(arr,
os, formatter)` and `read(arr, os, formatter)` that operate on a given
arrangement-with-history instance `arr`.  Both functions are
parameterized by a `formatter` object, which defines the I/O
format. The package contains a template called,
`Arr_with_hist_text_formatter<ArranagmentFormatter>`, which extends an
arrangement formatter class (see Section \ref arr_ssecarr_io_aux_data)
and defines a simple textual input/output format.
\cgalAdvancedEnd

<!-- ----------------------------------------------------------------------- -->
\subsection arr_ssecarr_io_vis Drawing an Arrangement
<!-- ----------------------------------------------------------------------- -->

An arrangement data structure can be visualized by calling the \link PkgArrangementOnSurface2Draw CGAL::draw<arr>() \endlink function as shown in the following example. This function opens a new window showing the given arrangement. A call to this function is blocking; that is, the program continues execution only after the user closes the window.

\cgalExample{Arrangement_on_surface_2/draw_arr.cpp}

This function requires `CGAL_Qt6`, and is only available if the macro `CGAL_USE_BASIC_VIEWER` is defined.
Linking with the cmake target `CGAL::CGAL_Basic_viewer` will link with `CGAL_Qt6` and add the definition `CGAL_USE_BASIC_VIEWER`.

\cgalFigureBegin{aos_fig-draw_arr,draw_arr.png}
A snapshot of the window created by the program
\ref Arrangement_on_surface_2/draw_arr.cpp. The constructed arrangement consists
of 14 vertices, 15 edges, and 3 faces. Notice that the colors are generated at random.
\cgalFigureEnd


<!-- ======================================================================= -->
\section aos_sec-bgl Adapting to Boost Graphs
<!-- ======================================================================= -->

\boost\cgalFootnote{See also \boost's homepage at:
\cgalFootnoteCode{www.boost.org}.}  is a collection of portable \cpp libraries
that extend the \cpp Standard Library. The \boost Graph Library
(\bgl), which one of the libraries in the collection, offers an
extensive set of generic graph algorithms parameterized through
templates.  As our arrangements are embedded as planar graphs, it is
only natural to extend the underlying data structure with the
interface that the \bgl expects, and gain the ability to perform the
operations that the \bgl supports, such as shortest-path
computation. This section describes how to apply the graph algorithms
implemented in the \bgl to `Arrangement_2` instances.

An instance of `Arrangement_2` is adapted to a \boost graph through
the provision of a set of free functions that operate on the
arrangement features and conform with the relevant BGL
concepts. Besides the straightforward adaptation, which associates a
vertex with each \dcel vertex and an edge with each \dcel halfedge,
the package also offer a <em>dual</em> adaptor, which associates a
graph vertex with each \dcel face, such that two vertices are
connected, iff there is a \dcel halfedge that connects the two
corresponding faces.

<!-- ----------------------------------------------------------------------- -->
\subsection arr_ssecbgl_primal The Primal Arrangement Representation
<!-- ----------------------------------------------------------------------- -->

Arrangement instances are adapted to \boost graphs by specializing the
\link BGLArgtGT `boost::graph_traits` \endlink template for
`Arrangement_2` instances. The graph-traits states the graph concepts
that the arrangement class models (see below) and defines the types
required by these concepts.

In this specialization the `Arrangement_2` vertices correspond to the
graph vertices, where two vertices are adjacent if there is at least
one halfedge connecting them. More precisely, \link
Arrangement_on_surface_2::Vertex_handle `Vertex_handle`\endlink is the
graph-vertex type, while \link
Arrangement_on_surface_2::Halfedge_handle `Halfedge_handle`\endlink is
the graph-edge type. As halfedges are directed, we consider the graph
to be directed as well. Moreover, as several interior-disjoint
\f$x\f$-monotone curves (say circular arcs) may share two common
endpoints, inducing an arrangement with two vertices that are
connected with several edges, we allow parallel edges in our \boost.

Given an `Arrangement_2` instance, we can efficiently traverse its
vertices and halfedges. Thus, the arrangement graph is a model of the
concepts `VertexListGraph` and `EdgeListGraph` introduced by the \bgl.
At the same time, we use an iterator adapter of the circulator over
the halfedges incident to a vertex
(`Halfedge_around_vertex_circulator` - see Section \ref
arr_sssectr_vertex), so it is possible to go over the ingoing and
outgoing edges of a vertex in linear time. Thus, our arrangement graph
is a model of the concept `BidirectionalGraph` (this concept refines
`IncidenceGraph`, which requires only the traversal of outgoing
edges).

It is important to notice that the vertex descriptors we use are \link
Arrangement_2 Vertex_handle `Vertex_handle`\endlink objects and
<em>not</em> vertex indices. However, in order to gain more efficiency
in most \bgl algorithms, it is better to have them indexed \f$0, 1,
\ldots, (n-1)\f$, where \f$n\f$ is the number of vertices. We
therefore introduce the `Arr_vertex_index_map<Arrangement>`
class-template, which maintains a mapping of vertex handles to
indices, as required by the \bgl. An instance of this class must be
attached to a valid arrangement vertex when it is created. It uses the
notification mechanism (see Section \ref arr_ssecnotif) to
automatically maintain the mapping of vertices to indices, even when
new vertices are inserted into the arrangement or existing vertices
are removed.

In most algorithms provided by the \bgl, the output is given by
<em>property maps</em>, such that each map entry corresponds to a
vertex.  For example, when we compute the shortest paths from a given
source vertex \f$s\f$ to all other vertices we can obtain a map of
distances and a map of predecessors - namely for each \f$v\f$ vertex
we have its distance from \f$s\f$ and a descriptor of the vertex that
precedes \f$v\f$ in a shortest path from \f$s\f$.

If the vertex descriptors are simply indices, boost supplies tools to
easily represent property maps using vectors.  The
`Arr_vertex_index_map<Arrangement>` class template enables the
creation of such indices, and together with
`boost::vector_property_map<Type, IndexMap>` it generates an efficient
mapping from \link Arrangement_on_surface_2::Vertex_handle
`Vertex_handle`\endlink objects to properties of type `Type`. Note,
however, that unlike the `Arr_vertex_index_map` class template, the
vertex property-map class is not kept synchronized with the number of
vertices in the arrangement, so it should not be reused in calls to
\bgl functions in case the arrangement is modified in between these
calls.

The first example of this section demonstrates the application of
Dijkstra's shortest path algorithm to compute the shortest-path length
between a given vertex of an arrangement of linear curves and all
other vertices. The length of a path is defined as the sum of squared
Euclidean lengths of its segments. It uses an instance of the functor
template `Edge_length<Arrangement>}` to compute the squared Euclidean
length of the linear curve associated with a given halfedge of the
arrangement. The functor implements a \boost property-map that
attaches square lengths to edges; when the \bgl algorithm queries the
property map for a squared length of an edge the property map computes
and returns it. The functor template is defined in the header file
`Edge_length.h`.

\code
#include <CGAL/Exact_predicates_exact_constructions_kernel.h>
#include <CGAL/property_map.h>

using Kernel = CGAL::Exact_predicates_exact_constructions_kernel;
using Number_type = Kernel::FT;

template <typename Arrangement> struct Edge_length {
  // Boost property-type definitions.
  using category = boost::readable_property_map_tag;
  using value_type = Number_type;
  using reference = value_type;
  using key_type = typename Arrangement::Halfedge_handle;

  value_type operator()(typename Arrangement::Halfedge_handle e) const {
    const auto diff_x = e->target()->point().x() - e->source()->point().x();
    const auto diff_y = e->target()->point().y() - e->source()->point().y();
    return diff_x * diff_x + diff_y * diff_y;
  }

  friend value_type get(const Edge_length& edge_length, key_type key)
  { return edge_length(key); }
};
\endcode

<!-- ----------------------------------------------------------------------- -->
\cgalFigureBegin{aos_fig-bgl_primal_adapter,bgl_primal_adapter.png}
An arrangement of seven line segments, as constructed by
\ref Arrangement_on_surface_2/bgl_primal_adapter.cpp and
\ref Arrangement_on_surface_2/bgl_dual_adapter.cpp.
\cgalFigureEnd
<!-- ----------------------------------------------------------------------- -->

In the following example we construct an arrangement of seven line
segments, as shown in \cgalFigureRef{aos_fig-bgl_primal_adapter}.
Then, it uses the \bgl generic implementation of Dijkstra's
shortest-paths algorithm to compute the sum of squared distances to
all vertices from the lexicographically smallest vertex \f$v_0\f$ in
the arrangement. Note the usage of the `Arr_vertex_property_map` class
template in the call to `boost::dijkstra_shortest_paths()` and in the
definition of the distance property-map. We instantiate a property map
that attaches a number of type `Number_type` (which is a type of
unlimited precision) to each vertex. The number represents the sum of
squared distances of the vertex from \f$v_0\f$.

\cgalExample{Arrangement_on_surface_2/bgl_primal_adapter.cpp}

<!-- ----------------------------------------------------------------------- -->
\subsection arr_ssecbgl_dual The Dual Arrangement Representation
<!-- ----------------------------------------------------------------------- -->

An arrangement instance can be represented as a graph other than the
one described in the previous section. A dual-graph representation
refers to the graph, where each arrangement face corresponds to a
graph vertex, and two vertices are adjacent iff the corresponding faces
share a common edge on their boundaries. This is done by specializing
the `boost::graph_traits` template for `Dual<Arrangement_2>` instances,
where `Dual<Arrangement_2>` is a template specialization that gives a
dual interpretation to an arrangement instance.

In a dual representation, \link Arrangement_on_surface_2::Face_handle
`Face_handle`\endlink is the graph-vertex type, while \link
Arrangement_on_surface_2::Halfedge_handle `Halfedge_handle`\endlink is
the graph-edge type. We treat the graph edges as directed, such that a
halfedge `e` is directed from \f$f_1\f$, which is its incident face,
to \f$f_2\f$, which is the incident face of its twin halfedge. As two
arrangement faces may share more than a single edge on their boundary,
we allow parallel edges (loops) in our \boost graph. As is the case in
the primal graph, the dual arrangement graph is also a model of the
concepts `VertexListGraph`, `EdgeListGraph` and `BidirectionalGraph`
(thus also of `IncidenceGraph`).

Since we use \link Arrangement_on_surface_2::Face_handle
`Face_handle`\endlink objects as the vertex descriptors, we define the
`Arr_face_index_map<Arrangement>` class-template, which maintains an
efficient mapping of face handles to indices.

The next example demonstrates how a property map can be used to update
or receive information directly from a feature of the arrangement
without the need to search for its index. The example also
demonstrates the application of the breadth-first search} (BFS)
algorithm on a dual arrangement. It uses the functor template
`Extended_face_property_map<Arrangement, Type>` to directly access
information stored inside the faces. The functor implements a property
map that utilizes the `data()` and `set_data()` member functions of the
extended face to update or obtain the property. When the property map
is instantiated, the `Type` parameter must be substituted by the
same type that is used to extend the arrangement face; see Section
\ref arr_sssecex_dcel_face. The functor template is defined in the
header file `Extended_face_property_map.h` listed below.

\code
// A property map that reads/writes the information to/from the extended face.
template <typename Arrangement, class Type> class Extended_face_property_map {
public:
  using Face_handle = typename Arrangement::Face_handle;

  // Boost property type definitions.
  using category = boost::read_write_property_map_tag;
  using value_type = Type;
  using reference = value_type&;
  using key_type = Face_handle;

  // The get function is required by the property map concept.
  friend reference get(const Extended_face_property_map& map, key_type key)
  { return key->data(); }

  // The put function is required by the property map concept.
  friend void put(const Extended_face_property_map& map,
                  key_type key, value_type val)
  { key->set_data(val); }
};
\endcode

<!-- ----------------------------------------------------------------------- -->
\cgalFigureBegin{aos_fig-bgl_dual_adapter,bgl_dual_adapter.png}
An arrangement of seven line segments, as constructed by \ref
Arrangement_on_surface_2/bgl_dual_adapter.cpp and its dual face graph,
where every arrangement face is a vertex of the graph. The index of a
dual vertex is the discovery time of a breadth-first search applied to
the face graph, starting from the unbounded face \f$f_0\f$.
\cgalFigureEnd
<!-- ----------------------------------------------------------------------- -->

The following example constructs the same arrangement constructed by
the program coded in \ref
Arrangement_on_surface_2/bgl_primal_adapter.cpp; see
\cgalFigureRef{aos_fig-bgl_primal_adapter}. Then, it performs a
breadth-first search traversal on the face graph, starting from the
unbounded face. The \dcel faces are extended with an unsigned
integer indicating the discovered time of the face. The code uses a
visitor that obtains the times and writes them into a property map
that updates the faces
accordingly. \cgalFigureRef{aos_fig-bgl_dual_adapter} shows the graph
dual to the arrangement. It is clear that the unbounded face \f$f_0\f$
is discovered at time \f$0\f$, the neighboring faces \f$f_1\f$,
\f$f_3\f$, and \f$f_4\f$ are discovered at times \f$1\f$, \f$2\f$, and
\f$3\f$, and finally \f$f_2\f$ is discovered at time \f$4\f$.

\cgalExample{Arrangement_on_surface_2/bgl_dual_adapter.cpp}

<!-- ======================================================================= -->
\section aos_sec-tips How To Speed Up Your Computation
<!-- ======================================================================= -->

Before the specific tips, we remind you that compiling programs with
debug flags disabled and with optimization flags enabled significantly
reduces the running time.

<OL>

<LI>When the curves to be inserted into an arrangement are
\f$x\f$-monotone and pairwise disjoint in their interior to start
with, then it is more efficient (in running time) and less demanding
(in traits-class functionality) to use the non-intersecting
insertion-functions instead of the general ones; e.g., `insert()`.

<LI>When the curves to be inserted into an arrangement are segments that
are pairwise disjoint in their interior, it is more efficient to use
the traits class `Arr_non_caching_segment_traits_2` rather than
the default one (`Arr_segment_traits_2`).

If the segments may intersect each other, the default traits class
`Arr_segment_traits_2` can be safely used with the somehow limited
number type `Quotient<MP_float>`.

On rare occasions the traits class `Arr_non_caching_segment_traits_2`
exhibits slightly better performance than the default one
(`Arr_segment_traits_2` even when the segments intersect each other,
due to the small overhead of the latter (optimized) traits class. (For
example, when the so-called \leda rational kernel is used.)

<LI>Prior knowledge of the combinatorial structure of the arrangement
can be used to accelerate operations that insert \f$x\f$-monotone
curves, whose interior is disjoint from existing edges and vertices of
the arrangement. The specialized insertion functions, i.e.,
`Arrangement_on_surface_2::insert_in_face_interior()`,
`Arrangement_on_surface_2::insert_from_left_vertex()`,
`Arrangement_on_surface_2::insert_from_right_vertex()`, and
`Arrangement_on_surface_2::insert_at_vertices()` can be used according
to the available information. These functions hardly involve any
geometric operations, if at all. They accept topologically related
parameters, and use them to operate directly on the \dcel records,
thus saving algebraic operations, which are especially expensive when
high-degree curves are involved.

A polygon, represented by a list of segments along its boundary, can
be inserted into an empty arrangement as follows. First, one segment
is inserted using
`Arrangement_on_surface_2::insert_in_face_interior()` into the
unbounded face. Then, a segment with a common end point is inserted
using either `Arrangement_on_surface_2::insert_from_left_vertex()` or
`Arrangement_on_surface_2::insert_from_right_vertex()`, and so on with
the rest of the segments except for the last, which is inserted using
`Arrangement_on_surface_2::insert_at_vertices()`, as both endpoints of
which are the mapping of known vertices.

<LI>The main trade-off among point-location strategies is between
time and storage. Using the naive or walk strategies, for example,
takes more query time but does not require preprocessing or
maintenance of auxiliary structures and saves storage space.

<LI>If point-location queries are not performed frequently, but other
modifying functions, such as removing, splitting, or merging edges
are, then using a point-location strategy that does not require the
maintenance of auxiliary structures, such as the naive or walk
strategies, is preferable.

<LI>There is a trade-off between two modes of the trapezoidal RIC
strategy that enables the user to choose whether preprocessing should
be performed or not. If preprocessing is not used, the creation of the
structure is faster. However, for some input sequences the structure
might be unbalanced and therefore queries and updates might take
longer, especially, if many removal and split operations are
performed.

<LI>When the curves to be inserted into an arrangement are available
in advance (as opposed to supplied on-line), it is advised to use the
more efficient aggregate (sweep-based) insertion over the incremental
insertion; e.g., \link insert<Traits,Dcel,InputIterator>()
`insert(arr, first, last)`\endlink.

<LI>The various traits classes should be instantiated with an exact
number type to ensure robustness when the input of the operations to
be carried out might be degenerate. Inexact number types can be used
at the user's own risk.

<LI>Maintaining short bit-lengths of coordinate representations may
drastically decrease the time consumption of arithmetic operations on
the coordinates. This can be achieved by caching certain information
or normalization (of rational numbers). However, both solutions should
be used cautiously, as the former may lead to an undue space
consumption, and indiscriminate normalization may considerably slow
down the overall process.

<LI>Geometric functions (e.g., traits methods) dominate the time
consumption of most operations. Thus, calls to such function should be
avoided or at least their number should be decreased, perhaps at the
expense of increased combinatorial-function calls or increased space
consumption. For example, repetition of geometric-function calls could
be avoided by storing the results obtained by the first call, and
reusing them when needed.
</OL>

<!-- ======================================================================= -->
\section aos_sec-design Design and Implementation History
<!-- ======================================================================= -->

The code of this package is the result of a long development process.
Initially (and until version 3.1), the code was spread among several
components, namely, `Topological_map`, `Planar_map_2`,
`Planar_map_with_intersections_2` and `Arrangement_2`, that were
developed by Ester Ezra, Eyal Flato, Efi Fogel, Dan Halperin, Iddo
Hanniel, Idit Haran, Shai Hirsch, Eugene Lipovetsky, Oren Nechushtan,
Sigal Raab, Ron Wein, Baruch Zukerman, and Tali Zvi.

In version 3.2, as part of the ACS project, the packages have gone
through a major re-design, resulting in an improved and unified
<em>2D Arrangements</em> package.
The code of the new package was restructured and developed by
Efi Fogel, Idit Haran, Ron Wein, and Baruch Zukerman. This
version included for the first time a new geometry-traits
class that handles circular and linear curves, and is based
on the circular kernel. The circular kernel was developed
by Monique Teillaud, Sylvain Pion, and Julien Hazebrouck.

Version 3.3 features arrangements of unbounded curves for the first
time. The design and development of this feature required yet another
restructuring of the entire package. All this was done by Eric
Berberich, Efi Fogel, Dan Halperin, Ophir Setter, and Ron
Wein. Michael Hemmer helped tuning up parts of the geometry-traits
concept related to unbounded curves.

Version 3.7 introduced a geometry-traits class
that handles planar algebraic curves of arbitrary degree.
It was developed by Eric Berberich and Michael Kerber.

Version 3.9 introduced a new geometry-traits class that handles
rational arcs. It was developed by Oren Salzman and Michael Hemmer.
It replaced an old traits, which handled the same family of
curves, developed by Ron Wein.

Version 4.1 introduces a revised implementation of the point location class
via a randomized incremental construction of the trapezoidal map.
The old class was implemented by Oren Nechushtan, while the revamp
was done by Michal Kleinbort and Michael Hemmer. The new class adds support
for unbounded curves and can now guarantee logarithmic query time in all
cases.

*/
} /* namespace CGAL */
