General Introduction

CGAL, the Computational Geometry Algorithms Library, is written in C++ and consists of several parts.

The first part is about the kernels, which consist of constant-size non-modifiable geometric primitive objects and operations on these objects. The objects are represented both as stand-alone classes that are parameterized by a representation class, which specifies the underlying number types used for calculations and as members of the kernel classes, which allows for more flexibility and adaptability of the kernel. CGAL has several kernels, for 2D and 3D, for arbitrary dimensional objects, and for 2D curved objects.

The following parts present a collection of basic geometric data structures and algorithms, which are parameterized by traits classes that define the interface between the data structure or algorithm and the primitives they use. In many cases, the kernel classes provided in CGAL can be used as traits classes for these data structures and algorithms. The collection of basic geometric algorithms and data structures currently includes polygons, half-edge data structures, polyhedral surfaces, arrangements of curves, triangulations in 2D and 3D, surface mesh generators, subdivision and parameterization of surface meshes, Voronoi diagrams of points, disks and segments, Boolean operations on polygons and polyhedra, convex hulls, alpha shapes, optimization algorithms, dynamic point sets for geometric queries, range and segment trees, and kinetic data structures.

The last part of the library consists of non-geometric support facilities, such as support for number types, STL extensions for CGAL, handles, circulators, protected access to internal representations, geometric object generators, timers, I/O stream operators and other stream support including PostScript, colors, windows, and visualization tools Geomview and a Qt widget for 2D CGAL objects.

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 book by Austern [Aus98] for the STL and its notion of concepts and models.

1.1 License Issues

CGAL is Open Source software, and consists of different parts covered by different licenses. In this section we explain the essence of the different licenses, as well as the rationale why we have chosen them.

The fact that CGAL is Open Source software does not mean that users are free to do whatever they want with the software. Using the software means to accept the license, which has the status of a contract between the user and the owner of the CGAL software. A more detailed description of the license terms is available in the CGAL software tarball.

1.1.1 QPL

The QPL is an Open Source license that obliges you to distribute your software based on QPLed CGAL data structures. The rationale behind this is that we can claim access to your software. The license further obliges you to put your software under an Open Source license as well. The rationale behind is that we can distribute your software, even if this is not your intention. Finally, the QPL requires that, if you modify CGAL, you distribute the modifications in the form of patches and you distribute the sources of your changes as well.

1.1.2 LGPL

The LGPL is an Open Source license that obliges you to distribute modifications you make on CGAL software accessible to the users. There is no obligation to make the source code of software you build on top of LGPLed CGAL data structures available.

Currently the linear kernel, the support library, the halfedge data structure, the kinetic data structures, and the mesh subdivision framework are distributed under the LGPL. The rationale behind is that we want to promote them as de facto standards.

1.1.3 Commercial Licenses

Users who cannot comply to the Open Source license terms can buy individual data structures under various commercial licenses from GeometryFactory: http://www.geometryfactory.com.

1.1.4 License Compatibility

The General Public License (GPL) has a viral effect which makes it incompatible with the QPL. For more information, please refer to the paragraph about the QPL on the licenses web page of the Free Software Foundation (FSF): http://www.fsf.org/licensing/licenses/index_html. It is therefore not possible to build a program including GPL code and some QPL parts of CGAL. In this case, if you are the copyright owner of the GPL code, you can amend the license by adding an exception allowing the use of CGAL with it (see again the FSF web page).

1.2 Third Party Software

1.2.1 Standard Template Library

CGAL heavily uses the STL, and in particular adopted many of its design ideas. The STL comes with the compiler, but it is possible to use the compiler together with an alternative STL implementation.

1.2.2 Boost

Boost is a collection of libraries. CGAL needs some of them, that is it is mandatory. If Boost is not already on your system, e.g., on Windows, you can download it from http://www.boost.org.

1.2.3 Blas

1.2.4 Lapack

LAPACK provides routines for solving systems of simultaneous linear equations, least-squares solutions of linear systems of equations, eigenvalue problems, and singular value problems. In CGAL, LAPACK is required by the packages Estimation of Local Differential Properties and Approximation of Ridges and Umbilics only.

You can download the official release from http://www.netlib.org/lapack/. Alternatively, installing TAUCS customized for CGAL provides LAPACK.

1.2.5 GMP

A library for multi precision integers and rational numbers. CGAL offers adapters for these number types. The usage of the GMP library is optional. If it is not already on your system, e.g., on Windows, you can download it from http://gmplib.org/ or from the download section of http://www.cgal.org.

1.2.6 MPFR

A library for multi precision floating point numbers. The usage of the MPFR library is optional, and you must install it when you use GMP. You can download MPFR from http://www.mpfr.org or from the download section of http://www.cgal.org.

1.2.7 Leda

A library of efficient data structures and algorithms. CGAL offers adapters to the LEDA number types. The usage is optional. It is only available commercially from http://www.algorithmic-solutions.com.

1.2.8 Taucs

The TAUCS web site is http://www.tau.ac.il/~stoledo/taucs/.
The latest official version is TAUCS version 2.2, September 4, 2003. Copyright (c) 2001, 2002, 2003 by Sivan Toledo, Tel-Aviv University, stoledo@tau.ac.il. All Rights Reserved.
See http://www.tau.ac.il/~stoledo/taucs/ for the license and the availability note.
Used by permission of Sivan Toledo.

The CGAL project provides a modified version of TAUCS in the download section of http://www.cgal.org. This version fixes some bugs, supports 64-bit platforms and allows a simplified installation process. It also contains a complete LAPACK implementation.
CAUTION: Since version 3.3.1, CGAL is no longer compatible with the official release of TAUCS (currently 2.2). Make sure to use the modified version provided in the download section.

1.2.9 OpenNL

OpenNL (Open Numerical Library) is a library to easily construct and solve sparse linear systems. It is the default solver of the Surface Mesh Parameterization package.

CGAL includes a version of OpenNL in C++, made especially for CGAL by Bruno Lévy.

1.2.10 zlib

A data compression library. It is used in the examples of the Surface Mesh Generation package. If it is not already on your system, e.g., on Windows, you can download it from http://www.gzip.org/zlib.

1.2.11 Qt

A GUI library. The usage of Qt is optional, but note that it is used for all 2D demos.

As Qt is the layer underneath KDE, Qt is installed on many Linux systems. Otherwise you can download it from http://www.trolltech.com.

1.2.12 Coin

1.3 Marking of Advanced Features

advanced

Some functionality is considered more advanced. Such functionality is described in sections such as this one that are bounded by horizontal brackets.

advanced

1.4 Namespace CGAL

All names introduced by CGAL, especially those documented in these manuals, are in a namespace called CGAL, which is in global scope. A user can either qualify names from CGAL by adding CGAL::, e.g., CGAL::Point_2< CGAL::Homogeneous< int> >, make a single name from CGAL visible in a scope via a using statement, e.g., using CGAL::Cartesian;, and then use this name unqualified in this scope, or even make all names from namespace CGAL visible in a scope with using namespace CGAL;. The latter, however, is likely to give raise to name conflicts and is therefore not recommended.

1.5 Inclusion Order of Header Files

Not all compilers fully support standard header names. CGAL provides workarounds for these problems in CGAL/basic.h. Consequently, as a golden rule, you should always include CGAL/basic.h first in your programs (or CGAL/Cartesian.h, or CGAL/Homogeneous.h, since they include CGAL/basic.h first).

1.6 Compile-time Flags to Control Inlining

Making functions inlined can, at times, improve the efficiency of your code. However this is not always the case and it can differ for a single function depending on the application in which it is used. Thus CGAL defines a set of compile-time macros that can be used to control whether certain functions are designated as inlined functions or not. The following table lists the macros and their default values, which are set in one of the CGAL include files.

If you wish to change the value of one or more of these macros, you can simply give it a new value when compiling. For example, to make functions that use the macro CGAL_KERNEL_MEDIUM_INLINE inline functions, you should set the value of this macro to inline instead of the default blank.

1.7 Identifying the version of CGAL

1.8 Checks

Much of the CGAL code contains checks. For example, all checks used in the kernel code are prefixed by CGAL_KERNEL. Other packages have their own prefixes, as documented in the corresponding chapters. Some are there to check if the kernel behaves correctly, others are there to check if the user calls kernel routines in an acceptable manner.

There are four types of checks. The first three are errors and lead to a halt of the program if they fail. The last only leads to a warning.

By default, all of these checks are performed. It is however possible to turn them off through the use of compile time switches. For example, for the checks in the kernel code, these switches are the following: CGAL_KERNEL_NO_PRECONDITIONS, CGAL_KERNEL_NO_POSTCONDITIONS, CGAL_KERNEL_NO_ASSERTIONS and CGAL_KERNEL_NO_WARNINGS. So, in order to compile the file foo.C with the postcondition checks off, you can do:
CC -DCGAL_KERNEL_NO_POSTCONDITIONS foo.C

This is also preferably done by modifying your makefile by adding -DCGAL_KERNEL_NO_POSTCONDITIONS to the CXXFLAGS variable.

The name KERNEL in the macro name can be replaced by a package specific name in order to control assertions done in a given package. This name is given in the documentation of the corresponding package, in case it exists.

Note that global macros can also be used to control the behavior over the whole CGAL library:

Moreover, the standard macro NDEBUG, which controls the behavior of the standard assert macro, also affects all checks in CGAL. This way, adding -DNDEBUG to your compilation flags removes absolutely all checks, including standard ones using assert. This is the default recommended setup for performing timing benchmarks for example. In addition, the macro CGAL_NDEBUG also disables all checks in CGAL but does not affect the standard assert macro.

Not all checks are on by default. All four types of checks can be marked as expensive or exactness checks (or both). These checks need to be turned on explicitly by supplying one or both of the compile time switches CGAL_KERNEL_CHECK_EXPENSIVE and CGAL_KERNEL_CHECK_EXACTNESS.

Expensive checks are, as the word says, checks that take a considerable time to compute. Considerable is an imprecise phrase. Checks that add less than 10 percent to the execution time of the routine they are in are not expensive. Checks that can double the execution time are. Somewhere in between lies the border line. Checks that increase the asymptotic running time of an algorithm are always considered expensive. Exactness checks are checks that rely on exact arithmetic. For example, if the intersection of two lines is computed, the postcondition of this routine may state that the intersection point lies on both lines. However, if the computation is done with doubles as number type, this may not be the case, due to round off errors. So, exactness checks should only be turned on if the computation is done with some exact number type.

1.8.1 Altering the Failure Behavior

As stated above, if a postcondition, precondition or assertion is violated, the program will abort (stop and produce a core dump). This behavior can be changed by means of the following function.

If the EXIT value is set, the program will stop and return a value indicating failure, but not dump the core. The CONTINUE value tells the checks to go on after diagnosing the error.

advanced

If the EXIT_WITH_SUCCESS value is set, the program will stop and return a value corresponding to successful execution and not dump the core.

advanced

The value that is returned by set_error_behaviour is the value that was in use before.

For warnings there is a separate routine, which works in the same way. The only difference is that for warnings the default value is CONTINUE.

1.8.2 Control at a Finer Granularity

The compile time flags as described up to now all operate on the whole library. Sometimes you may want to have a finer control. CGAL offers the possibility to turn checks on and off with a bit finer granularity, namely the module in which the routines are defined. The name of the module is to be appended directly after the CGAL prefix. So, the flag CGAL_KERNEL_NO_ASSERTIONS switches off assertions in the kernel only, the flag CGAL_CH_CHECK_EXPENSIVE turns on expensive checks in the convex hull module. The name of a particular module is documented with that module.

advanced

1.8.3 Customizing how Errors are Reported

Normally, error messages are written to the standard error output. It is possible to do something different with them. To that end you can register your own handler. This function should be declared as follows.

void

my_failure_function (
const char *type,
const char *expression,
const char *file,
int line,
const char *explanation)

Your failure function will be called with the following parameters. type is a string that contains one of the words precondition, postcondition, assertion or warning. The parameter expression contains the expression that was violated. file and line contain the place where the check was made. The explanation parameter contains an explanation of what was checked. It can be NULL, in which case the expression is thought to be descriptive enough.

There are several things that you can do with your own handler. You can display a diagnostic message in a different way, for instance in a pop up window or to a log file (or a combination). You can also implement a different policy on what to do after an error. For instance, you can throw an exception or ask the user in a dialog whether to abort or to continue. If you do this, it is best to set the error behavior to CONTINUE, so that it does not interfere with your policy.

You can register two handlers, one for warnings and one for errors. Of course, you can use the same function for both if you want. When you set a handler, the previous handler is returned, so you can restore it if you want.

#include <CGAL/assertions.h>

Failure_function	set_error_handler ( Failure_function handler)
Failure_function	set_warning_handler ( Failure_function handler)

Example

#include <CGAL/assertions.h>

void my_failure_handler(
    const char *type,
    const char *expr,
    const char* file,
    int line,
    const char* msg)
{
    /* report the error in some way. */
}

void foo()
{
    CGAL::Failure_function prev;
    prev = CGAL::set_error_handler(my_failure_handler);
    /* call some routines. */
    CGAL::set_error_handler(prev);
}

advanced

macro name	default

CGAL_KERNEL_INLINE	inline
CGAL_KERNEL_MEDIUM_INLINE
CGAL_KERNEL_LARGE_INLINE
CGAL_MEDIUM_INLINE	inline
CGAL_LARGE_INLINE
CGAL_HUGE_INLINE

Chapter 1General Introduction

1.1 License Issues

1.1.1 QPL

1.1.2 LGPL

1.1.3 Commercial Licenses

1.1.4 License Compatibility

1.2 Third Party Software

1.2.1 Standard Template Library

1.2.2 Boost

1.2.3 Blas

1.2.4 Lapack

1.2.5 GMP

1.2.6 MPFR

1.2.7 Leda

1.2.8 Taucs

1.2.9 OpenNL

1.2.10 zlib

1.2.11 Qt

1.2.12 Coin

1.3 Marking of Advanced Features

1.4 Namespace CGAL

1.5 Inclusion Order of Header Files

1.6 Compile-time Flags to Control Inlining

1.7 Identifying the version of CGAL

1.8 Checks

1.8.1 Altering the Failure Behavior

1.8.2 Control at a Finer Granularity

1.8.3 Customizing how Errors are Reported

Example

Chapter 1
General Introduction