\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} 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} 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/|.