
namespace CGAL {
/*!

\mainpage User Manual 
\anchor Chapter_3D_Convex_Hulls
\anchor chapconvexhull3
\cgalAutoToc
\authors Susan Hert and Stefan Schirra

\cgalFigureBegin{figchbimba,chull_bimba.png}
The convex hull of a model made of 192135 points.
\cgalFigureEnd

\section Convex_hull_3Introduction Introduction

A subset \f$ S \subseteq \mathbb{R}^3\f$ is convex if for any two points \f$ p\f$ and \f$ q\f$
in the set the line segment with endpoints \f$ p\f$ and \f$ q\f$ is contained
in \f$ S\f$. The convex hull of a set \f$ S\f$ 
is the smallest convex set containing
\f$ S\f$. The convex hull of a set of points \f$ P \in \mathbb{R}^3\f$ is a convex 
polytope with vertices in \f$ P\f$. A point in \f$ P\f$ is an extreme point 
(with respect to \f$ P\f$) if it is a vertex of 
the convex hull of \f$ P\f$. A set of points is said to be strongly convex if it consists of only extreme points.

This chapter describes the functions provided in
\cgal for producing convex hulls in three dimensions as well as
functions for checking if sets of points are strongly convex are not. 
One can compute the convex hull of a set of points in three dimensions
in two ways in \cgal: using a static algorithm or using a
triangulation to get a fully dynamic computation.

\section secconvex_hull_3 Static Convex Hull Construction

The function 
`convex_hull_3()` provides an 
implementation of the quickhull algorithm \cgalCite{bdh-qach-96}.
There are two versions of this
function available, one that can be used when it is known that the output
will be a polyhedron (<I>i.e.</I>, there are more than three points and
they are not all collinear) and one that handles all degenerate cases
and returns an `Object`, which may be a point, a segment, a
triangle, or a polyhedron. Both versions accept a range of input
iterators defining the set of points whose convex hull is to be computed
and a traits class defining the geometric types and predicates used in
computing the hull.

\subsection Convex_hull_3TraitsClass Traits Class

The function `convex_hull_3()` is parameterized by a traits class,
which specifies the types and geometric primitives to be used in the
computation. If input points from a kernel with exact predicates 
and non-exact constructions are used, and a certified result is expected,
the traits `Convex_hull_traits_3<R>` should be used 
(`R` being the input kernel). Note that the default traits class takes this into
account.

\subsubsection Convex_hull_3Example Example

The following program reads points from an input file and computes
their convex hull.  We assume that the points are
not all identical and not all collinear, thus we directly use a polyhedron
as output. In the example you see that the convex hull function can
write in any model of the concept `MutableFaceGraph`.


\cgalExample{Convex_hull_3/quickhull_3.cpp}


\subsubsection Convex_hull_3ExampleLower Example for Lower Dimensional Results

The following program reads points from an input file and computes
their convex hull. Depending on the dimension of the result, we will
get a point, a segment, a triangle, or a polyhedral surface.
Note that the latter may also be planar polygon with a border.

\cgalExample{Convex_hull_3/quickhull_any_dim_3.cpp}

\subsection Convex_hull_3ExtremePoints Extreme points
In addition to the `convex_hull_3()` function, the function `extreme_points_3()` is also
provided in case only the points on the convex hull are required (without the connectivity
information). In addition the traits class adapter `CGAL::Extreme_points_traits_adapter_3`
is also provided in order to get the indices or more generally any given entity that
is associated a 3D point that is on the convex hull.

The following program reads a set of points from an OFF file and outputs the indices
of the points that are on the convex hull.
\cgalExample{Convex_hull_3/extreme_indices_3.cpp}

The following program reads and builds a mesh from an OFF file, and then collects the vertices
that are on the convex hull of the mesh.
\cgalExample{Convex_hull_3/extreme_points_3_sm.cpp}

\subsection Convex_hull_3HalfspaceIntersection Halfspace Intersection

The functions `halfspace_intersection_3()` and
`halfspace_intersection_with_constructions_3()`
uses the convex hull algorithm and the duality to compute the intersection
of a list of halfspaces. The first version does not explicitly compute
the dual points: the traits class handles this issue. The second one constructs
these points and hence is less robust but the computation is faster.

In order to compute the intersection an interior point is needed. It can be
either given by the user or computed using linear programming. Notice that the
second approach is slower due to the resolution of a linear program.

\subsubsection Convex_hull_3HalfspaceInntersectionExample Example

The following example computes the intersection of halfspaces defined by
tangent planes to a sphere. 

\cgalExample{Convex_hull_3/halfspace_intersection_3.cpp}


\subsection Convex_hull_3ConvexityChecking Convexity Checking

The function `is_strongly_convex_3()`
implements the algorithm of Mehlhorn <I>et al.</I> \cgalCite{mnssssu-cgpvg-96} 
to determine if the vertices of a given polytope constitute a strongly convex 
point set or not. This function is used in postcondition testing for
`convex_hull_3()`.


\section Convex_hull_3Dynamic Dynamic Convex Hull Construction

Fully dynamic maintenance of a convex hull can be achieved by using the
class `Delaunay_triangulation_3`. This class supports insertion
and removal of points (<I>i.e.</I>, vertices of the triangulation) and the 
convex hull edges are simply the finite edges of infinite faces. 
The following example illustrates the dynamic construction of a convex hull.
First, random points from a sphere of a certain radius are generated and are
inserted into a triangulation. Then the number of points of the convex hull 
are obtained by counting the number of triangulation vertices incident to the 
infinite vertex. Some of the points are removed and then the number of points 
remaining on the hull are determined. Notice that the vertices incident to the
infinite vertex of the triangulation are on the convex hull but it may be that
not all of them are vertices of the hull.

\subsection Convex_hull_3Example_2 Example

The following example shows how to compute a convex hull with a triangulation.
The vertices incident to the infinite vertex are on the convex hull.

The function `convex_hull_3_to_face_graph()` can be used to obtain a polyhedral surface 
that is model of the concept `MutableFaceGraph`, e.g. `Polyhedron_3` and `Surface_mesh`.

\cgalExample{Convex_hull_3/dynamic_hull_3.cpp}

\section Convex_hull_3Performance Performance

In the following, we compare the running times of the two approaches to compute 3D convex hulls.
For the static version (using `convex_hull_3()`) and the dynamic version
(using `Delaunay_triangulation_3` and `convex_hull_3_to_face_graph()`), the kernel
used was `Exact_predicates_inexact_constructions_kernel`.

To compute the convex hull of a million of random points in a unit ball the static approach needed 1.63s, while 
the dynamic approach needed 9.50s.
To compute the convex hull of the model of \cgalFigureRef{figchbimba} featuring 192135 points, 
the static approach needed 0.18s, while the dynamic approach needed 1.90s.

The measurements have been performed using \cgal 3.9, using the <span class="textsc">Gnu</span> \cpp compiler version 4.3.5, under Linux (Debian distribution),
with the compilation options <TT>-O3 -DCGAL_NDEBUG</TT>. The computer used was equipped with a 64bit Intel Xeon 2.27GHz processor and 12GB of RAM.

*/ 
} /* namespace CGAL */

