mirror of https://github.com/CGAL/cgal
169 lines
6.4 KiB
TeX
169 lines
6.4 KiB
TeX
|
|
\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/|.
|