
\chapter{Introduction}
\ccChapterAuthor{CGAL Editorial Board}
\input{Introduction/PkgDescription}


The goal of the \cgal\ Open Source Project is to provide 
{\em easy access to efficient and reliable geometric algorithms}
in the form of a \CC\ library.

The Computational Geometry Algorithms Library offers data
structures and algorithms like 
triangulations,
Voronoi diagrams,
Boolean operations on polygons and on polyhedra,
arrangements of curves,
mesh generation,
geometry processing,
convex hull algorithms,
to name just a few.


All these data structures and algorithms operate on geometric objects
like points and segments, and perform geometric tests on them.
These objects and predicates are regrouped in \cgal\ {\em Kernels}.


Finally, the  \cgal\ {\em Support Library}
offers geometric object generators and spatial sorting functions,  
as well as a matrix search framework and a solver for linear and quadratic programs. 
It further offers interfaces to third party software such as the {\sc Gui} libraries Qt, 
Geomview, and the Boost Graph Library.


\section{Organization of the Manual}

This manual is organized in several parts covering the many domains
of computational geometry. Each part consists of several chapters,
and each chapter is split into a {\em user manual}  and a {\em reference
manual}. The user manual gives the general idea and comes with examples.
The reference manual presents the {\sc Api} of the various classes
and functions.

The manual has a table of contents, and an index, as well as a package overview,
which gives a short paragraph what the package is about, what license
it has, and on which other packages it depends. It further provides
links to precompiled demo programs for the Windows platform.

\section{Demos and Examples}

In the distribution of the library  you find the two directories {\em demo}
and {\em examples}. They contain subdirectories for the \cgal\ packages.  
The demos use third party libraries for the graphical user interface. The 
examples don't have this dependency and most examples are refered to in the 
user manual.



\section{Hello World}

In this section we will take a closer look at three \cgal\ example
programs, all of them computing the 2D convex hull of a set of points.


\subsection{Points in a built-in array}

In the first example we have an array of five points.
As the convex hull of these points is a subset of the input
it is safe to provide an array for storing the result which
has the same size.

\ccIncludeExampleCode{Convex_hull_2/array_convex_hull_2.cpp}


All \cgal\ header files are in the subdirectory ``include/CGAL''.  All \cgal\ 
classes and functions are in the namespace ``CGAL''.  The geometric
primitives, like the point type, are defined in a kernel. \cgal\ comes
with several kernels, and as the convex hull algorithm only makes
comparisons of coordinates and orientation tests of input points,
we can choose a kernel that provides exact predicates, but no 
exact geometric construction.

The convex hull function takes three arguments, the start
and past-the-end pointer for the input, and the start pointer of the 
array for the result. The function returns the pointer
into the result array just behind the last convex hull
point written, so the pointer difference tells us how
many points are on the convex hull. 
 

\subsection{Points in a STL vector}

In the second example we replace the built-in array
by a \ccc{std::vector} of the Standard Template Library.

\ccIncludeExampleCode{Convex_hull_2/vector_convex_hull_2.cpp}

We put some points in the vector calling the \ccc{push_back()}
method of the \ccc{std::vector} class.

We then call the convex hull function. The first two arguments,
\ccc{points.begin()} and \ccc{points.end()} are  {\em iterators}, 
which are a generalization of pointers:
they can be dereferenced and incremented. The convex hull
function is {\em generic} in the sense that it takes as
input whatever can be dereferenced and incremented.

The third argument is where the result gets written to.
In the previous example we provided a pointer to allocated memory.
The generalization of such a pointer is the {\em output iterator},
which allows to increment and assign a value to the dereferenced iterator.
In this example we start with an empty vector which grows as needed. 
Therefore, we cannot simply pass it \ccc{result.begin()}, but
an output iterator generated by the helper function \ccc{std::back_inserter(result)}.
This output iterator does nothing when incremented,
and calls \ccc{result.push_back(..)} on the assignment.



\subsection{Points in Streams}

The last example program reads a sequence of points from standard
input \ccc{std::cin} and writes the points on the convex hull to
standard output \ccc{std::cout}.

Instead of storing the points in a container such as an
\ccc{std::vector}, and passing the begin/end iterator of the vector to
the convex hull function, we use helper classes that turn file
pointers into iterators.


\ccIncludeExampleCode{Convex_hull_2/iostream_convex_hull_2.cpp}

In the example code you see input and output stream iterators
templated with the point type.  A \ccc{std::istream_iterator<Point_2>}
hence allows to traverse a sequence of objects of type \ccc{Point_2}, which 
come from standard input as we pass \ccc{std::cin} to the
constructor of the iterator. The variable \ccc{input_end} denotes
end-of-file.

A \ccc{std::ostream_iterator<Point_2>} is an output iterator,
that is an iterator to which, when dereferenced, we can assign a value. 
When such an assignment to the output iterator
happens somewhere inside the convex hull function, the iterator 
just writes the assigned point to standard output, because the iterator 
was  constructed with \ccc{std::cout}.

The call to the convex hull function takes three arguments,
the input iterator range, and the output iterator to which
the result gets written. 

If you know the \stl, the Standard Template Library, the above
makes perfect sense, as this is the way the \stl\  decouples algorithms 
from containers. If you don't know the \stl, you maybe better
first familiarize yourself with its basic ideas.



\section{Further Reading}

We also recommend the standard text books by
Josuttis~\cite{cgal:j-csl-99}, or Austern~\cite{cgal:a-gps-98} for the
\stl\ and its notion of \emph{concepts} and \emph{models}.


Other resources for \cgal\ are the tutorials at
\path|http://www.cgal.org/Tutorials/| and the user support page at
\path|http://www.cgal.org/|.
