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 secPolygonWithHole Polygons with Holes and Multipolygons with Holes

This package also provides classes to represent polygons with holes and multipolygons with holes.

For polygons with holes, these are `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.

For multipolygons with holes, there is `Multipolygon_with_holes_2`.
It stores a sequence of polygons with holes.

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

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

\subsection SubsectionPolygonRepair_Multipolygon The Multipolygon with Holes Class

The following example shows the creation of a multipolygon with holes and the traversal
of the polygons in it.

\cgalExample{Polygon/multipolygon.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 explicit 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}


\subsection subsecPolygonIterate Iterating over Vertices and Edges

The polygon class provides member functions such as `Polygon_2::vertices_begin()` and `Polygon_2::vertices_end()` to iterate over the
vertices. It additionally provides a member function `Polygon_2::vertices()` that returns a range, mainly to be used with modern
`for` loops. The same holds for edges and for the holes of the class `Polygon_with_holes_2`.

\cgalExample{Polygon/ranges.cpp}


\subsection subsecPolygonDraw Draw a Polygon

A polygon can be visualized by calling the \link  PkgDrawPolygon2 CGAL::draw<P>() \endlink function as shown in the following example. This function opens a new window showing the given polygon. A call to this function is blocking, that is the program continues as soon as the user closes the window. Versions for polygons with holes and multipolygons with holes also exist, cf. \link PkgDrawPolygonWithHoles2 CGAL::draw<PH>() \endlink and \link PkgDrawMultipolygonWithHoles2
CGAL::draw<MPH>() \endlink.

\cgalExample{Polygon/draw_polygon.cpp}

This function requires `CGAL_Qt6`, and is only available if the macro `CGAL_USE_BASIC_VIEWER` is defined.
Linking with the cmake target `CGAL::CGAL_Basic_viewer` will link with `CGAL_Qt6` and add the definition `CGAL_USE_BASIC_VIEWER`.

\cgalFigureBegin{fig_draw_polygon,draw_polygon.png}
Result of the run of the draw_polygon program. A window shows the polygon and allows to navigate through the scene.
\cgalFigureEnd

*/
}
