
\chapter{General 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 
\ccRef[triangulations]{Part:TriangulationsAndDelaunayTriangulations},
\ccRef[Voronoi diagrams]{Part:VoronoiDiagrams},
\ccRef[Boolean operations on polygons]{Part:Polygons},
\ccRef[Boolean operations on polyhedra]{Part:Polyhedra},
\ccRef[arrangements of curves]{Part:Arrangements} and their applications,
\ccRef[mesh generation]{Part:Meshing},
\ccRef[geometry processing]{Part:GeometryProcessing},
\ccRef[convex hull algorithms]{Part:ConvexHullAlgorithms},
\ccRef[interpolation]{Part:Interpolation},
\ccRef[shape analysis, fitting, and distances]{Part:GeometricOptimization},
and \ccRef[kinetic data structures]{Part:KineticDataStructures}.


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\ \ccRef[Kernels]{Part:Kernels}.


Finally, the \ccRef[Support Library]{Part:SupportLibrary}
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 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 funcions.

The manual has a table of contents, 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 a 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 one of the \cgal\ example
programs, namely a 2D convex hull algorithm. The 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}.

\ccIncludeExampleCode{Convex_hull_2/convex_hull_2.cpp}


All \cgal\ header files are in the subdirectory ``CGAL''.  All \cgal\ 
classes and functions are in the namespace ``CGAL''.  The geometric
primitives, like point, 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 constructions.

You next see input and output stream iterators templated with the 
point type.  Iterators are a generalization of pointers, that is
they can be dereferenced, and one can increment them.  They
come in \ccc{begin/end} pairs (where \ccc{end} is a pointer 
past-the end), and you get from \ccc{begin} to \ccc{end} by 
incrementing the iterator. When you dereference an iterator you 
obtain what it points to, in our case a \ccc{Point_2}. 

A \ccc{std::istream_iterator<Point_2>}  hence allows to traverse
a sequence of \ccc{Points}, which in the example 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}


Additional documents accompanying the \cgal\ distribution are the
`Installation Guide' and `The Use of \stl\ and \stl\ Extensions in
\cgal', which gives a manual style introduction to \stl\ constructs
such as iterators and containers, as well an extension, called
circulator, used in many places in \cgal. 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/|.
