namespace CGAL {

/*!
\mainpage User Manual 
\anchor Chapter_2D_Polygon
\anchor Chapter_Polygon

\authors Geert-Jan Giezeman and Wieger Wesselink
\cgalAutoToc

\section secPolygonIntroduction Introduction

A polygon is a closed chain of edges. Several algorithms are available for
polygons. For some of those algorithms, it is necessary that the polygon is
simple. A polygon is simple if edges don't intersect, except consecutive edges,
which intersect in their common vertex.

The following algorithms are available:

- find the leftmost, rightmost, topmost and bottommost vertex.
- compute the (signed) area.
- check if a polygon is simple.
- check if a polygon is convex.
- find the orientation (clockwise or counterclockwise)
- check if a point lies inside a polygon.

All those operations take two forward iterators as parameters in order to
describe the polygon. These parameters have a point type as value type.

The type `Polygon_2` can be used to represent polygons.
Polygons are dynamic. Vertices can be modified, inserted and erased.
They provide the algorithms described above as member functions.
Moreover, they provide ways of iterating over the vertices and edges.

The `Polygon_2` class is a wrapper around a container of
points, but little more. Especially, computed values are not cached.
That is, when the `Polygon_2::is_simple()` member function is called
twice or more, the result is computed each time anew.

\section secPolygonExamples Examples

\subsection subsecPolygon The Polygon Class

The following example creates a polygon and illustrates the usage of
some member functions.

\cgalExample{Polygon/Polygon.cpp}

\cgalFigureBegin{polygon2_algo,pgn_algos.png}
A polygon and some points
\cgalFigureEnd

\subsection subsecPolygonAlgorithms Algorithms Operating on Sequences of Points

The following example creates a polygon and illustrates the usage of
some global functions that operate on sequences of points.

\cgalExample{Polygon/polygon_algorithms.cpp}

\subsection subsecPolygon3D Polygons in 3D Space

Sometimes it is useful to run a 2D algorithm on 3D data.
Polygons may be contours of a 3D object, where the contours
are organized in parallel slices, generated by segmentation
of image data from a scanner.

In order to avoid an explixit projection on the \c xy plane, one can
use the traits class `Projection_traits_xy_3` which is part of the 2D
and 3D Linear Geometric %Kernel.

\cgalExample{Polygon/projected_polygon.cpp}

*/

\section secPolygonWithHole Polygons with Holes

This package also provides two classes to represent polygons with holes,
namely `Polygon_with_holes_2` and `General_polygon_with_holes_2`. They
can store a polygon that represents the outer boundary and a sequence
of polygons that represent the holes.

These classes do not add any semantic requirements on the simplicity
or orientation of their boundary polygons.

}
