namespace CGAL {
/*!
\mainpage User Manual
\anchor Chapter_PolygonMeshProcessing

\cgalAutoToc
\authors Sébastien Loriot, Jane Tournois, Ilker %O. Yaz

\image html neptun_head.jpg
\image latex neptun_head.jpg
<BR>

\section PMPIntroduction Introduction

This package implements a collection of methods and classes for polygon mesh processing,
ranging from basic operations on simplices, to complex geometry processing algorithms.
The implementation of this package mainly follows algorithms and references
given in Botsch et al.'s book on polygon mesh processing \cgalCite{botsch2010PMP}.

\subsection PMPDef Polygon Mesh
A \a polygon \a mesh is a consistent and orientable surface mesh, that can have
one or more boundaries.
The \a faces are simple polygons.
The \a edges are segments. Each edge connects two \a vertices,
and is shared by two faces (including the \a null \a face for boundary edges).
A polygon mesh can have any number of connected components, and also some self-intersections.
In this package, a polygon mesh is considered to have the topology of a 2-manifold.

\subsection PMPAPI API
This package follows the BGL API described in \ref PkgBGL.
It can thus be used either with `Polyhedron_3`, `Surface_mesh`, or
any class model of the concept `FaceGraph`. Each function or class of this package
details the requirements on the input polygon mesh.

\ref BGLNamedParameters are used to deal with optional parameters.
The page \ref pmp_namedparameters describes their usage
and provides a list of the parameters that are used in this package.

\subsection PMPOutline Outline
The algorithms described in this manual are organized in sections:
- \ref PMPMeshing : meshing algorithms, including triangulation of non-triangulated
meshes, refinement, optimization by fairing, and isotropic remeshing of triangulated surface meshes.
- \ref Coref_section : methods to corefine triangle meshes and to compute
  boolean operations out of corefined closed triangle meshes.
- \ref PMPHoleFilling : available hole filling algorithms, which can possibly be combined with refinement and fairing.
- \ref PMPPredicates : predicates that can be evaluated on the processed polygon.
mesh, which includes point location and self intersection tests.
- \ref PMPOrientation : checking or fixing the orientation of a polygon soup.
- \ref PMPRepairing :  repair of polygon meshes and polygon soups.
- \ref PMPNormalComp : normal computation at vertices and on faces of a polygon mesh.
- \ref PMPSlicer : functor able to compute the intersections of a polygon mesh with arbitrary planes (slicer).
- \ref PMPConnectedComponents : methods to deal with connected
  components of a polygon mesh (extraction, marks, removal, ...).

****************************************
\section PMPMeshing Meshing

A surface patch can be refined by inserting new vertices and flipping edges to get a triangulation.
Using a criterion presented in \cgalCite{liepa2003filling},
the density of triangles near the boundary of the patch is approximated by the refinement function.
The validity of the mesh is enforced by flipping edges.
An edge is flipped only if the opposite edge does not exist in the original mesh
and if no degenerate triangles are generated.

A region of the surface mesh (\e e.\e g. the refined region), can be faired
to obtain a tangentially continuous and smooth surface patch.
The region to be faired is defined as a range of vertices that are relocated.
The fairing step minimizes a linear bi-Laplacian system with boundary constraints,
described in \cgalCite{Botsch2008OnLinearVariational}.
The visual results of aforementioned steps are depicted by \cgalFigureRef{Mech_steps} (c and d).

\subsection MeshingAPI API

\subsubsection Meshing

Refinement and fairing functions can be applied to an arbitrary region on a triangle mesh, using :
- `CGAL::Polygon_mesh_processing::refine()` : given a set of facets on a mesh, refines the region.
- `CGAL::Polygon_mesh_processing::fair()` : given a set of vertices on a mesh, fairs the region.

Fairing needs a sparse linear solver and we recommend the use of \ref thirdpartyEigen 3.2 or later.
Note that fairing might fail if fixed vertices, which are used as boundary conditions, do
not suffice to solve the constructed linear system.

Many algorithms require as input meshes in which all the faces have the same degree,
or even are triangles. Hence, one may want to triangulate all polygon faces of a mesh.

This package provides the function `CGAL::Polygon_mesh_processing::triangulate_faces()`
that triangulates all faces of the input polygon mesh.
An approximated support plane is chosen for each face, orthogonal to the normal vector
computed by `CGAL::Polygon_mesh_processing::compute_face_normal()`.
Then, the triangulation of each face is the one obtained by building a
`CGAL::Constrained_Delaunay_triangulation_2` in this plane.
This choice is made because the constrained Delaunay triangulation
is the triangulation that, given the edges of the face to be triangulated,
maximizes the minimum angle of all the angles of the triangles in the triangulation.

\subsubsection Remeshing

The incremental triangle-based isotropic remeshing algorithm introduced by Botsch et al
 \cgalCite{botsch2004remeshing}, \cgalCite{botsch2010PMP} is implemented in this package.
This algorithm incrementally performs simple operations such as edge splits, edge collapses,
edge flips, and Laplacian smoothing. All the vertices of the remeshed patch are reprojected
to the original surface to keep a good approximation of the input.

A triangulated region of a polygon mesh can be remeshed using the function
`CGAL::Polygon_mesh_processing::isotropic_remeshing()`, as illustrated
by \cgalFigureRef{iso_remeshing}. The algorithm has only two parameters :
the target edge length for the remeshed surface patch, and
the number of iterations of the abovementioned sequence of operations. The bigger
this number, the smoother and closer to target edge length the mesh will be.

An additional option has been added to \e protect (\e i.\e e. not modify) some given polylines.
In some cases, those polylines are too long, and reaching the desired target edge length while protecting them is not
possible and leads to an infinite loop of edge splits in the incident faces. To avoid that pitfall, the
function `CGAL::Polygon_mesh_processing::split_long_edges()` should be called on the list of
constrained edges before remeshing.

\cgalFigureBegin{iso_remeshing, iso_remeshing.png}
Isotropic remeshing. (a) Triangulated input surface mesh.
(b) Surface uniformly and entirely remeshed.
(c) Selection of a range of faces to be remeshed.
(d) Surface mesh with the selection uniformly remeshed.
\cgalFigureEnd


\subsection MeshingExamples Meshing Examples

\subsubsection MeshingExample_1 Refine and Fair a Region on a Triangle Mesh

The following example calls the functions `CGAL::Polygon_mesh_processing::refine()`
and `CGAL::Polygon_mesh_processing::fair()` for some selected regions on the input triangle mesh.

\cgalExample{Polygon_mesh_processing/refine_fair_example.cpp}

\subsubsection MeshingExample_2 Triangulate a Polygon Mesh

Triangulating a polygon mesh can be achieved through the function
`CGAL::Polygon_mesh_processing::triangulate_faces()`
as shown in the following example.

\cgalExample{Polygon_mesh_processing/triangulate_faces_example.cpp}


\subsubsection RemeshingExample_1 Isotropic Remeshing of a Region on a Polygon Mesh

The following example shows a complete example of how the isotropic remeshing function can be used.
First, the border of the polygon mesh is collected.
Since the boundary edges will be considered as constrained and protected in this example, the function `split_long_edges()` is called first on these edges.

Once this is done, remeshing is run on all the surface, with protection of constraints activated, for 3 iterations.

\cgalExample{Polygon_mesh_processing/isotropic_remeshing_example.cpp}

\section Coref_section Corefinement and Boolean Operations

\subsection coref_def_subsec Definitions

<b>Corefinement</b> Given two triangulated surface meshes, the <i>corefinement</i>
operation consists in refining both meshes so that their intersection polylines
are a subset of edges in both refined meshes.
\todo more information on coplanar patches.

\cgalFigureBegin{coref_fig, corefine.png}
Corefinement of two triangulated surface meshes. (Left) Input meshes; (Right)
The two input meshes corefined. The common edges of the two meshes are
drawn in green.
\cgalFigureEnd

<b>Volume bounded by a triangulated surface mesh</b> Given a closed triangulated surface
mesh, each connected component splits the 3D space into two subspaces. The vertex
sequence of each face of a component is seen either clockwise or counterclockwise
from these two subspaces. The subspace that sees the sequence clockwise
(resp. counterclockwise) is on the negative (resp. positive) side of the component. Given a
closed triangulated surface mesh `tm` with no self-intersections,
the connected components of `tm` divide
the 3D space into subspaces. We say that `tm` bounds a volume if each
subspace lies exclusively on the positive (or negative) side of all the
incident connected components of `tm`. The volume bounded by `tm` is the union
of all subspaces that are on negative sides of their incident connected components
of `tm`.

\cgalFigureBegin{boundedvol_fig, bounded_vols.jpg}
Volumes bounded by a triangulated surface mesh: The figure shows meshes
representing three nested spheres (three connected components).
The left side of the picture shows a clipped triangulated surface mesh,
with the two possible orientations of the faces for which
a volume is bounded by the mesh.
The positive and negative sides of each connected component is displayed in
light and dark blue, respectively. The right part of the picture shows clipped
tetrahedral meshes of the corresponding bounded volumes.
\cgalFigureEnd

\subsection coref_coref_subsec Corefinement
The corefinement of two triangulated surface meshes can be done using the function
`CGAL::Polygon_mesh_processing::corefine()`. It takes as input the two
triangulated surface meshes to corefine.
If constrained edge maps are provided, edges belonging to the
intersection of the input meshes will be marked as constrained. In addition,
if an edge that was marked as constrained is split during the corefinement,
sub-edges will be marked as constrained as well.

\subsection coref_bolop_subsec Boolean Operations

\cgalFigureBegin{boolop_fig, bool_op.png}
Let `C` and `S` be the volumes bounded by the triangulated surface meshes of
a cube and a sphere, respectively. From left to right, the picture shows
the triangulated surface meshes bounding the union of `C` and `S`,
`C` minus `S`, the intersection of `C` and `S` and `S` minus `C`.
\cgalFigureEnd


The corefinement of two triangulated surface meshes can naturally be used
for computing Boolean operations on volumes.
Considering two triangulated surface meshes, each bounding
a volume, the functions `CGAL::Polygon_mesh_processing::corefine_and_compute_union()`,
`CGAL::Polygon_mesh_processing::corefine_and_compute_intersection()` and
`CGAL::Polygon_mesh_processing::corefine_and_compute_difference()` respectively compute the union,
the intersection and the difference of the two volumes. If several Boolean operations must be
computed at the same time, the function `corefine_and_compute_boolean_operations()` should be used.

There is no restriction on the topology of the input volumes.
However, there are some requirements on the input to guarantee that
the operation is possible. First, the input meshes must not self-intersect.
Second, the operation is possible only if the output
can be bounded by a manifold triangulated surface mesh.
In particular this means that the output volume has no part with zero thickness.
Mathematically speaking, the intersection with an infinitesimally small ball
centered in the output volume is a topological ball. At the surface level this means
that no non-manifold vertex or edge is allowed in the output. For example, it
is not possible to compute the union of two cubes that are disjoint but sharing an edge.
In case you have to deal with such scenarios, you should consider using the
package \ref PkgNef3.

It is possible to update the input so that it contains the result (in-place operation).
In that case the whole mesh will not be copied and only the region around the
intersection polyline will be modified. In case the Boolean operation is not
possible, the input mesh will nevertheless be corefined.


\subsection coref_valid_subsec Kernel and Validity of the Output
The corefinement operation (which is also internally used in the three
Boolean operations) will correctly change the topology of the input surface mesh
if the point type used in the point property maps of the input meshes is
from a \cgal Kernel with exact predicates. If that kernel does not
have exact constructions, the embedding of the output surface mesh might
have self-intersections. In case of consecutive operations, it is thus
recommended to use a point property map with points from a kernel with exact
predicates and exact constructions
(such as `CGAL::Exact_predicates_exact_constructions_kernel`).

In practice, this means that with exact predicates and inexact constructions,
edges will be split at each intersection with a triangle but the
position of the intersection point might create self-intersections due to
the limited precision of floating point numbers.

\subsection coref_clip Clipping

As a natural extension, some clipping functionalities with a volume bounded by a closed mesh
and a halfspace (defined by the negative side of a plane to be consistent with
the outward normal convention) are offered. The functions `CGAL::Polygon_mesh_processing::clip()`
have some options to select whether the clipping should be done at the volume or surface
level, and also if the clipper should be considered as compact or not. This is illustrated on
\cgalFigureRef{coref_clip_close_open} and \cgalFigureRef{coref_clip_compact}.

\cgalFigureBegin{coref_clip_close_open, clip_open_close.png}
Clipping a cube with a halfspace. From left to right: (i) initial cube and the plane
defining the clipping halfspace; (ii) `close_volumes=false`: clipping of the surface mesh (boundary edges
depicted in red); (iii) `close_volumes=true`: clipping of the volume bounded by the surface mesh.
\cgalFigureEnd

\cgalFigureBegin{coref_clip_compact, clip_compact.png}
Clipping a cube with a halfspace: compacity of the clipper (`close_volumes=false` in both cases).
From left to right: (i) initial cube and the plane defining the clipping halfspace,
note that a whole face of the cube (2 triangles) is exactly contained in the plane;
(ii) `use_compact_clipper=true`: clipping of the surface mesh with a compact halfspace: coplanar faces are part of the output;
(iii) `use_compact_clipper=false`: clipping of the surface mesh with a non-compact halfspace: coplanar faces are not part of the output.
\cgalFigureEnd

\subsection coref_ex_subsec Examples

\subsubsection coref_ex_union_subsec Computing the Union of Two Volumes

\cgalExample{Polygon_mesh_processing/corefinement_mesh_union.cpp}

\subsubsection coref_ex_refine_subsec Boolean Operation and Local Remeshing

This example is similar to the previous one, but here we
substract a volume and update the first input triangulated surface mesh
(in-place operation). The edges that are on the intersection of the input
meshes are marked and the region around them is remeshed isotropically
while preserving the intersection polyline.
\cgalExample{Polygon_mesh_processing/corefinement_difference_remeshed.cpp}


\subsubsection coref_ex_consq_subsec Robustness of Consecutive Operations
This example computes the intersection of two volumes and then does the
union of the result with one of the input volumes. This operation is in
general not possible when using inexact constructions. Instead of using a
mesh with a point from a kernel with exact constructions, the exact points
are a property of the mesh vertices that we can reuse in a later operations.
With that property, we can manipulate a mesh with points having floating point coordinates
but benefit from the robustness provided by the exact constructions.
\cgalExample{Polygon_mesh_processing/corefinement_consecutive_bool_op.cpp}

********************************************
\section PMPHoleFilling Hole Filling

This package provides an algorithm for filling one closed hole that is either in a triangulated surface mesh
or defined by a sequence of points that describe a polyline.
The main steps of the algorithm are described in \cgalCite{liepa2003filling} and can be summarized as follows.

First, the largest patch triangulating the boundary of the hole is generated without introducing any new vertex.
The patch is selected so as to minimize a quality function evaluated for all possible triangular patches.
The quality function first minimizes the worst dihedral angle between patch triangles,
then the total surface area of the patch as a tiebreaker.
Following the suggestions in \cgalCite{zou2013algorithm}, the performance of the algorithm is significantly improved
by narrowing the search space to faces of a 3D Delaunay triangulation of the hole boundary vertices,
from all possible patches, while searching for the best patch with respect to the
aforementioned quality criteria.

For some complicated input hole boundary, the generated patch may have self-intersections.
After hole filling, the generated patch can be refined and faired using the meshing functions
`CGAL::Polygon_mesh_processing::refine()` and `CGAL::Polygon_mesh_processing::fair()`
described in Section \ref PMPMeshing.

\cgalFigureBegin{Mech_steps, mech_hole_horz.jpg}
Results of the main steps of the algorithm.
From left to right: (a) the hole,
(b) the hole after its triangulation,
(c) after triangulation and refinement,
(d) after triangulation, refinement and fairing.
\cgalFigureEnd


\subsection HoleFillingAPI API

This package provides four functions for hole filling:
  - `triangulate_hole_polyline()` : given a sequence of points defining the hole, triangulates the hole.
  - `triangulate_hole()` : given a border halfedge on the boundary of the hole on a mesh, triangulates the hole.
  - `triangulate_and_refine_hole()` : in addition to `triangulate_hole()` the generated patch is refined.
  - `triangulate_refine_and_fair_hole()` : in addition to `triangulate_and_refine_hole()` the generated patch is also faired.

\subsection HFExamples Examples

\subsubsection HFExample_1 Triangulate a Polyline

The following example triangulates a hole described by an input polyline.

\cgalExample{Polygon_mesh_processing/triangulate_polyline_example.cpp}


\subsubsection HFExample_2 Hole Filling From the Border of the Hole

If the input polygon mesh has a hole or more than one hole, it is possible
to iteratively fill them by detecting border edges (i.e. with only
one incident non-null face) after each hole filling step.

Holes are filled one after the other, and the process stops when there is no border edge left.

This process is illustrated by the example below, where holes are
iteratively filled, refined and faired to get a faired mesh with no hole.


\cgalExample{Polygon_mesh_processing/hole_filling_example.cpp}

 \cgalFigureBegin{Triangulated_fork, fork.jpg}
 Holes in the fork model are filled with triangle patches.
 \cgalFigureEnd

\subsection HFPerformance Performance

The hole filling algorithm has a complexity which depends on the
number of vertices.  While \cgalCite{liepa2003filling} has a running
time of \f$ O(n^3)\f$ , \cgalCite{zou2013algorithm} in most cases has
running time of \f$ O(n \log n)\f$. We benchmarked the function
`triangulate_refine_and_fair_hole()` for the two meshes below (as well as two
more meshes with smaller holes). The machine used was a PC running
Windows 10 with an Intel Core i7 CPU clocked at 2.70 GHz.
The program was compiled with the Visual C++ 2013 compiler with the O2
option, which maximizes speed.

\cgalFigureBegin{Elephants, elephants-with-holes.png}
The elephant on the left/right has a hole with 963/7657 vertices.
\cgalFigureEnd

The following running times were observed:

<center>
|  # vertices | without Delaunay (sec.) | with Delaunay (sec.)|
| ----:       | ----:                   | ----:               |
  565         | 8.5                     | 0.03                |
  774         | 21                      | 0.035               |
  967         | 43                      | 0.06                |
 7657         | na                      | 0.4                 |
</center>

***************************************
\section PMPPredicates Predicates

This packages provides several predicates to be evaluated with respect to a triangle mesh.

\subsection PMPDoIntersect Intersections Detection
Intersection tests between triangle meshes and/or polylines can be done using
\link PMP_predicates_grp `CGAL::Polygon_mesh_processing::do_intersect()` \endlink.
Additionally, the function `CGAL::Polygon_mesh_processing::intersecting_meshes()`
records all pairs of intersecting meshes in a range.

\subsubsection PMPSelIntersections Self Intersections

Self intersections within a triangle mesh can be detected by calling the function
`CGAL::Polygon_mesh_processing::does_self_intersect()`.
Additionally, the function `CGAL::Polygon_mesh_processing::self_intersections()`
reports all pairs of intersecting triangles.

\subsubsection SIExample Self Intersections Example

The following example illustrates the detection of self intersection in the `pig.off` mesh.
The detected self-intersection is illustrated on Figure \cgalFigureRef{SelfIntersections}.

\cgalExample{Polygon_mesh_processing/self_intersections_example.cpp}

\cgalFigureAnchor{SelfIntersections}
<center>
<img src="selfintersections.jpg" style="max-width:70%;"/>
</center>
\cgalFigureCaptionBegin{SelfIntersections}
Detecting self-intersections on a triangle mesh.
The intersecting triangles are displayed in dark grey and red on the right image.
\cgalFigureCaptionEnd

\subsection PMPInsideTest Side of Triangle Mesh

The class `CGAL::Side_of_triangle_mesh` provides a functor that tests whether a query point is
inside, outside, or on the boundary of the domain bounded by a given closed triangle mesh.

A point is said to be on the bounded side of the domain bounded by the input triangle mesh
if an odd number of surfaces is crossed when walking from the point to infinity.
The input triangle mesh is expected to contain no self-intersections
and to be free from self-inclusions.

The algorithm can handle the case of a triangle mesh with several connected components,
and returns correct results.
In case of self-inclusions, the ray intersections parity test is performed,
and the execution will not fail.
However, the user should be aware that the predicate
alternately considers sub-volumes to be on the bounded and unbounded sides of the
input triangle mesh.

\subsubsection InsideExample Inside Test Example
\cgalExample{Polygon_mesh_processing/point_inside_example.cpp}

\subsection PMPShapePredicates Shape Predicates

Badly shaped or, even worse, completely degenerate elements of a polygon mesh are problematic
in many algorithms which one might want to use on the mesh.
This package offers a toolkit of functions to detect such undesirable elements.
- `CGAL::Polygon_mesh_processing::is_degenerate_edge()`, to detect if an edge is degenerate
  (that is, if its two vertices share the same geometric location).
- `CGAL::Polygon_mesh_processing::is_degenerate_triangle_face()`, to detect if a face is
  degenerate (that is, if its three vertices are collinear).
- `CGAL::Polygon_mesh_processing::degenerate_edges()`, to collect degenerate edges within a range of edges.
- `CGAL::Polygon_mesh_processing::degenerate_faces()`, to collect degenerate faces within a range of faces.
- `CGAL::Polygon_mesh_processing::is_cap_triangle_face()`
- `CGAL::Polygon_mesh_processing::is_needle_triangle_face()`

****************************************
\section PMPOrientation Orientation

This package offers multiple functions to compute consistent face orientations for set of faces
(Section \ref PolygonSoups) and polygon meshes (Section \ref OrientingPolygonMeshes).
Section \ref PolygonSoupExample offers an example of combination of these functions.

\subsection PolygonSoups Polygon Soups

When the faces of a polygon mesh are given but the connectivity is unknown,
this set of faces is called a \e polygon \e soup.

Before running any of the algorithms on a polygon soup,
one should ensure that the polygons are consistently oriented.
To do so, this package provides the function
`CGAL::Polygon_mesh_processing::orient_polygon_soup()`,
described in \cgalCite{gueziec2001cutting}.

To deal with polygon soups that cannot be converted to a
combinatorially manifold surface, some points must be duplicated.
Because a polygon soup does not have any connectivity (each point
has as many occurences as the number of polygons it belongs to),
duplicating one point (or a pair of points)
amounts to duplicating the polygon to which it belongs.
The duplicated points are either an endpoint of an edge incident to more
than two polygons, an endpoint of an edge between
two polygons with incompatible orientations (during the re-orientation process),
or more generally a point \a p at which the intersection
of an infinitesimally small ball centered at \a p
with the polygons incident to it is not a topological disk.

Once the polygon soup is consistently oriented,
with possibly duplicated (or more) points,
the connectivity can be recovered and made consistent
to build a valid polygon mesh.
The function `CGAL::Polygon_mesh_processing::polygon_soup_to_polygon_mesh()`
performs this mesh construction step.

\subsection OrientingPolygonMeshes Polygon Meshes

This package provides functions dealing with the orientation of faces in a closed polygon mesh.

- The function `CGAL::Polygon_mesh_processing::orient()` makes each connected component
of a closed polygon mesh outward- or inward-oriented.
- The function `CGAL::Polygon_mesh_processing::orient_to_bound_a_volume()` orients
the connected components of a closed polygon mesh so that it bounds a volume
(see \ref coref_def_subsec for the precise definition).
- The function `CGAL::Polygon_mesh_processing::is_outward_oriented()` checks whether
an oriented polygon mesh is oriented such that the normals to all faces are oriented towards the
outside of the domain bounded by the input polygon mesh.
- The function `CGAL::Polygon_mesh_processing::reverse_face_orientations()` reverses the orientation
of halfedges around faces.
As a consequence, the normal computed for each face (see Section
\ref PMPNormalComp) is also reversed.

\subsection PolygonSoupExample Orientation Example

This example shows how to generate a mesh from a polygon soup.
The first step is to get a soup of consistently oriented faces, before
rebuilding the connectivity.
In this example, some orientation tests are performed on the output
polygon mesh to illustrate
Section \ref PMPOrientation.

\cgalExample{Polygon_mesh_processing/orient_polygon_soup_example.cpp}

****************************************
\section PMPRepairing Combinatorial Repairing

*******************
\subsection PSRepairing Polygon Soup Repairing
To ensure that a polygon soup can be oriented (see Section \ref PolygonSoups) and transformed
into a workable polygon mesh, it might be necessary to preprocess the data to remove combinatorial
and geometrical errors. This package offers the following functions:
- `CGAL::Polygon_mesh_processing::merge_duplicate_points_in_polygon_soup()`,
- `CGAL::Polygon_mesh_processing::merge_duplicate_polygons_in_polygon_soup()`,
- `CGAL::Polygon_mesh_processing::remove_isolated_points_in_polygon_soup()`,

as well as the function `CGAL::Polygon_mesh_processing::repair_polygon_soup()`,
which bundles the previous functions and an additional handful of repairing techniques
to obtain an as-clean-as-possible polygon soup.

\subsection Stitching

It happens that a polygon mesh has several edges and vertices that are duplicated.
For those edges and vertices, the connectivity of the mesh is incomplete, if not considered incorrect.

Stitching the borders of such a polygon mesh consists in two main steps.
First, border edges that are similar but duplicated are detected and paired.
Then, they are "stitched" together so that the edges and vertices duplicates are removed
from the mesh, and each of these remaining edges is incident to exactly two faces.

The function \link PMP_repairing_grp `CGAL::Polygon_mesh_processing::stitch_borders()` \endlink
 performs such repairing operation. The input mesh should be manifold.
Otherwise, stitching is not guaranteed to succeed.

\subsubsection StitchingExample Stitching Example

The following example applies the stitching operation to a simple quad mesh
with duplicated border edges.

\cgalExample{Polygon_mesh_processing/stitch_borders_example.cpp}

\if READY_TO_PUBLISH

\subsection DegenerateFaces Removing Degenerate Faces

Some degenerate faces may be part of a given triangle mesh.
A face is considered \e degenerate if two of its vertices
share the same location, or more generally if its three vertices are collinear.
The function `CGAL::Polygon_mesh_processing::remove_degenerate_faces()`
removes those faces and fixes the connectivity of the newly cleaned up mesh.
It is also possible to remove isolated vertices from any polygon mesh, using the function
`CGAL::Polygon_mesh_processing::remove_isolated_vertices()`.

\subsubsection RemoveDegenerateExample Example

In the following example, the degenerate faces of a triangle mesh
are removed, the connectivity is fixed, and the number of removed faces
is output.

\cgalExample{Polygon_mesh_processing/remove_degeneracies_example.cpp}
\endif

\subsection PMPManifoldness Polygon Mesh Manifoldness
This package offers repairing methods to clean ill-formed polygon soups,
see Section \ref PMPRepairing.

Non-manifold vertices can be detected using the function `CGAL::Polygon_mesh_processing::is_non_manifold_vertex()`.
The function `CGAL::Polygon_mesh_processing::duplicate_non_manifold_vertices()` can be used
to attempt to create a combinatorially manifold surface mesh by splitting any non-manifold vertex
into as many vertices as there are manifold sheets at this geometric position.
Note however that the mesh will still not be manifold from a geometric
point of view, as the positions of the new vertices introduced at a non-manifold vertex are identical
to the input non-manifold vertex.

\subsubsection FixNMVerticeExample Manifoldness Repair Example

In the following example, a non-manifold configuration is artifically created and
fixed with the help of the functions described above.

\cgalExample{Polygon_mesh_processing/manifoldness_repair_example.cpp}

\subsection PMPDuplicateVertexBoundaryCycle Duplicated Vertices in Boundary Cycles

Similarly to the problematic configuration described in the previous section, another issue that can be present
in a polygon mesh is the occurrence of a "pinched" hole, that is the configuration where, when
starting from a border halfedge and walking the halfedges of this border, a geometric position appears
more than once (although, with different vertices) before reaching the initial border halfedge again. The functions
`CGAL::Polygon_mesh_processing::merge_duplicated_vertices_in_boundary_cycle()` and
`CGAL::Polygon_mesh_processing::merge_duplicated_vertices_in_boundary_cycle()`, which merge
vertices at identical positions, can be used to repair this configuration.

****************************************
\section PMPNormalComp Computing Normals

This package provides methods to compute normals on the polygon mesh.
The normal can either be computed for each single face,
or estimated for each vertex, as the average of its incident face normals.
These computations are performed with :
- `CGAL::Polygon_mesh_processing::compute_face_normal()`
- `CGAL::Polygon_mesh_processing::compute_vertex_normal()`

Furthermore, we provide functions to compute all the normals to faces,
or to vertices, or to both :
- `CGAL::Polygon_mesh_processing::compute_face_normals()`
- `CGAL::Polygon_mesh_processing::compute_vertex_normals()`
- `CGAL::Polygon_mesh_processing::compute_normals()`.

Property maps are used to record the computed normals.

\subsection NormalsExample Normals Computation Examples

Property maps are an API introduced in the boost library that allows to
associate values to keys. In the following examples we associate
a normal vector to each vertex and to each face.

\subsubsection NormalsExampleSM Normals Computation for a Surface Mesh

The following example illustrates how to
compute the normals to faces and vertices
and store them in property maps provided by the class `Surface_mesh`.

\cgalExample{Polygon_mesh_processing/compute_normals_example.cpp}

\subsubsection NormalsExampleP Normals Computation for a Polyhedron_3

The following example illustrates how to
compute the normals to faces and vertices
and store them in ordered or unordered maps as the class `Polyhedron_3` does
not provide storage for the normals.

\cgalExample{Polygon_mesh_processing/compute_normals_example_Polyhedron.cpp}


****************************************
\section PMPSlicer Slicer

The `CGAL::Polygon_mesh_slicer` is an operator that intersects a triangle surface
mesh with a plane. It records the intersection as a set of polylines since the intersection
can be made of more than one connected component. The degenerate case
where the intersection is a single point is handled.

\cgalFigureRef{SlicerFig} shows
the polylines returned by the slicing operation for a triangle mesh
and a set of parallel planes.

\cgalFigureBegin{SlicerFig, slicer.jpg}
Slicing a mesh. A triangle mesh (left) and the polylines
computed by the mesh slicer by intersecting
a set of parallel planes (right).
\cgalFigureEnd

\subsection SlicerExample Slicer Example

The example below illustrates how to use the mesh slicer for a given
triangle mesh and a plane. Two constructors are used in the example
for pedagogical purposes.

\cgalExample{Polygon_mesh_processing/mesh_slicer_example.cpp}

****************************************
\section PMPConnectedComponents Connected Components

This package provides functions to enumerate and store
the connected components of a polygon mesh.
The connected components can be either closed and geometrically separated,
or separated by border or user-specified \e constraint edges.

First, the function `CGAL::Polygon_mesh_processing::connected_component()`
collects all the faces that belong to the same connected component as
the face that is given as a parameter.

Then, `CGAL::Polygon_mesh_processing::connected_components()`
collects all the connected components, and fills a property map
with the indices of the different connected components.

The functions `CGAL::Polygon_mesh_processing::keep_connected_components()`
and `CGAL::Polygon_mesh_processing::remove_connected_components()`
enable the user to keep and remove only a selection of connected components,
provided either as a range of faces that belong to the desired connected components
or as a range of connected component ids (one or more per connected component).

Finally, `CGAL::Polygon_mesh_processing::keep_largest_connected_components()`
enables the user to keep only the largest connected components. This feature can
for example be useful for noisy data were small connected components
should be discarded in favour of major connected components.


\subsection CCExample Connected Components Example

The first example shows how to record the connected
components of a polygon mesh.
In particular, we provide an example for the optional parameter \c EdgeConstraintMap,
a property map that returns information about an edge being a \e constraint or not.
A \e constraint provides a mean to demarcate the border of a connected component, and prevents
the propagation of a connected component index to cross it.

\cgalExample{Polygon_mesh_processing/connected_components_example.cpp}

The second example shows how to use the class template `Face_filtered_graph`
which enables to treat one or several connected components as a face graph.

\cgalExample{Polygon_mesh_processing/face_filtered_graph_example.cpp}


\section PMPDistance Approximate Hausdorff Distance

This package provides methods to compute (approximate) distances between meshes and point sets.

The function \link approximate_Hausdorff_distance() `approximate_Hausdorff_distance()`\endlink
computes an approximation of the Hausdorff distance from a mesh `tm1` to a mesh `tm2`. Given a
a sampling of `tm1`, it computes the distance to `tm2` of the farthest sample point to `tm2` \cgalCite{cignoni1998metro}.
The symmetric version (\link CGAL::Polygon_mesh_processing::approximate_symmetric_Hausdorff_distance() `approximate_symmetric_Hausdorff_distance()`\endlink)
is the maximum of the two non-symmetric distances. Internally, points are sampled using
\link CGAL::Polygon_mesh_processing::sample_triangle_mesh() `sample_triangle_mesh()`\endlink and the distance
to each sample point is computed using
\link CGAL::Polygon_mesh_processing::max_distance_to_triangle_mesh() `max_distance_to_triangle_mesh()`\endlink.
The quality of the approximation depends on the quality of the sampling and the runtime depends on the number of sample points.
Three sampling methods with different parameters are provided (see \cgalFigureRef{sampling_bunny}).

\cgalFigureBegin{sampling_bunny, pmp_sampling_bunny.jpg}
Sampling of a triangle mesh using different sampling methods. From left to right: (a) Grid sampling, (b) Monte-Carlo sampling with fixed number of points per face and per edge,
(c) Monte-Carlo sampling with a number of points proportional to the area/length, and (d) Uniform random sampling.
The four pictures represent the sampling on the same portion of a mesh, parameters were adjusted so that the total number of points sampled in faces (blue points) and on
edges (red points) are roughly the same.
Note that when using the random uniform sampling some faces/edges may not contain any point, but this method is the only one that allows to exactly match a given number of points.
\cgalFigureEnd

The function \link CGAL::Polygon_mesh_processing::approximate_max_distance_to_point_set() `approximate_max_distance_to_point_set()`\endlink
computes an approximation of the Hausdorff distance from a mesh to a point set.
For each triangle, a lower and upper bound of the Hausdorff distance to the point set are computed.
Triangles are refined until the difference between the bounds is lower than a user-defined precision threshold.

\subsection AHDExample Approximate Hausdorff Distance Example
In the following example, a mesh is isotropically remeshed and the approximate distance between the input and the output is computed.

\cgalExample{Polygon_mesh_processing/hausdorff_distance_remeshing_example.cpp}

\subsection PoissonDistanceExample Max Distance Between Point Set and Surface Example
In \ref Poisson_surface_reconstruction_3/poisson_reconstruction_example.cpp,
a triangulated surface mesh is constructed from a point set using the
\link PkgPoissonSurfaceReconstruction3 Poisson reconstruction algorithm \endlink,
and the distance between the point set and the reconstructed surface is computed
with the following code:

\snippet Poisson_surface_reconstruction_3/poisson_reconstruction_example.cpp PMP_distance_snippet

\section PMPDetectFeatures Feature Detection

This package provides methods to detect some features of a polygon mesh.

The function `CGAL::Polygon_mesh_processing::sharp_edges_segmentation()`
detects the sharp edges of a polygon mesh and deduces surface patches and vertices incidences.
It can be split into three functions : `CGAL::Polygon_mesh_processing::detect_sharp_edges()`, `CGAL::Polygon_mesh_processing::connected_components()`
and `CGAL::Polygon_mesh_processing::detect_vertex_incident_patches()`,
that respectively detect the sharp edges, compute the patch indices, and give each of `pmesh` vertices the patch indices of its incident faces.

\subsection DetectFeaturesExample Feature Detection Example
In the following example, we count how many edges of `pmesh` are incident to two faces
whose normals form an angle smaller than 90 degrees,
and the number of surface patches that are separated by these edges.

\cgalExample{Polygon_mesh_processing/detect_features_example.cpp}

\section PMPHistory Implementation History

A first version of this package was started by Ilker %O. Yaz and Sébastien Loriot.
Jane Tournois worked on the finalization of the API, code, and documentation.


*/
} /* namespace CGAL */
