namespace CGAL {
/*!

\mainpage User Manual 
\anchor Chapter_Planar_Parameterization_of_Triangulated_Surface_Meshes

\anchor chapsurface_mesh_parameterization
\cgalAutoToc

\authors Laurent Saboret, Pierre Alliez and Bruno L&eacute;vy

\section Surface_mesh_parameterizationIntroduction Introduction

Parameterizing a surface amounts to finding a one-to-one mapping from
a suitable domain to the surface. A good mapping is the one which
minimizes either angle distortions (conformal parameterization) or
area distortions (equiareal parameterization) in some sense. In this
package, we focus on parameterizing triangulated surfaces which are
homeomorphic to a disk, and on piecewise linear mappings onto a planar
domain.

Although the main motivation behind the first parameterization methods
was the application to texture mapping, it is now frequently used for
mapping more sophisticated modulation signals (such as normal,
transparency, reflection or light modulation maps), fitting scattered
data, re-parameterizing spline surfaces, repairing CAD models,
approximating surfaces and remeshing.

This \cgal package implements some of the state-of-the-art
surface parameterization methods, such as least squares conformal maps,
discrete conformal map, discrete authalic
parameterization, Floater mean value coordinates or Tutte barycentric
mapping. These methods mainly distinguish by the distortion they
minimize (angles vs. areas), by the constrained border onto the
planar domain (convex polygon vs. free border) and by the guarantees
provided in terms of bijective mapping.

The package proposes currently an interface with the `Polyhedron_3`
data structure.

Since parameterizing meshes require efficient representation of sparse
matrices and efficient iterative or direct linear solvers, we provide
a unified interface to linear solvers  as described in Chapter 
\ref PkgSolverSummary.

Note that linear solvers commonly use double precision floating point
numbers. Therefore, this package is intended to be used with a \cgal %Cartesian kernel with doubles.

The intended audience of this package is researchers, developers or
students developing algorithms around parameterization of triangle
meshes for geometry processing as well as for signal mapping on
triangulated surfaces.

\cgalFigureBegin{Surface_mesh_parameterizationfigintroduction,introduction.jpg}
Texture mapping via Least Squares Conformal Maps parameterization. Top: original mesh and texture. Bottom: parameterizedmesh (left: parameter space, right: textured mesh).
\cgalFigureEnd

\section Surface_mesh_parameterizationBasics Basics

\subsection Surface_mesh_parameterizationDefaultSurface Default Surface Parameterization

From the user point of view, the simplest entry point to this package
is the following function:

\code{.cpp}
Parameterizer_traits_3<ParameterizationMesh_3>::Error_code parameterize (ParameterizationMesh_3 & mesh);
\endcode

The function `parameterize()` applies a default surface parameterization
method, namely Floater Mean Value Coordinates \cgalCite{cgal:f-mvc-03}, with an
arc-length circular border parameterization, and using a sparse
linear solver from the \ref thirdpartyEigen library. The `ParameterizationMesh_3` concept defines the input meshes handled by `parameterize()`. See Section \ref secInputMeshforparameterize. The result is stored into the `(u,v)` fields of the mesh halfedges.
The mesh must be a triangle mesh surface with one connected component.

Note: `Parameterizer_traits_3<ParameterizationMesh_3>` is the (pure virtual) superclass of all surface parameterizations and defines the error codes.

\subsection secInputMeshforparameterize Input Mesh for parameterize() 

The input meshes handled <I>directly</I> by `parameterize()` must be models of `ParameterizationMesh_3`, triangulated, 2-manifold, oriented, and homeomorphic to discs (possibly with holes).

Note: `ParameterizationMesh_3` is a general concept to access a
polyhedral mesh. It is optimized for the `Surface_mesh_parameterization` package
only in the sense that it
defines the accessors to fields specific to the parameterization domain
(`index`, `u`, `v`, `is_parameterized`).
The extra constraints needed by the surface parameterization methods (triangulated,
2-manifold, homeomorphic to a disc) are not part of the concept and
are checked at runtime.

This package provides a model of the `ParameterizationMesh_3` concept
to access `Polyhedron_3<Traits>`: 

`Parameterization_polyhedron_adaptor_3<Polyhedron_3_>`

We will see later that `parameterize()` can support <I>indirectly</I>
meshes that are not topological disks.

\subsection Surface_mesh_parameterizationDefaultParameterization Default Parameterization Example

In the following example, we apply the default parameterization to a
`Polyhedron_3<Traits>` mesh (must be a topological disk).
Eventually, it extracts the result from halfedges and prints it.

\cgalExample{Surface_mesh_parameterization/Simple_parameterization.cpp}

\subsection Surface_mesh_parameterizationEnhancedparameterize Enhanced parameterize() Function

This package provides a second `parameterize()` entry point
where the user can specify a parameterization method:

\code{.cpp}
Parameterizer_traits_3<ParameterizationMesh_3>::Error_code parameterize (ParameterizationMesh_3 & mesh, ParameterizerTraits_3 parameterizer);
\endcode

It computes a one-to-one mapping from a 3D triangle surface mesh to a
simple 2D domain. The mapping is piecewise linear on the triangle
mesh. The result is a pair `(u,v)` of parameter coordinates for each
vertex of the input mesh.  One-to-one mapping may be guaranteed or
not, depending on the chosen `ParametizerTraits_3` algorithm.
<br>
The mesh must be a triangle surface mesh with one
connected component, and the mesh border must be mapped onto a convex
polygon (for fixed border parameterizations).



\subsection Surface_mesh_parameterizationIntroductionPC Introduction to the Package Concepts

\subsection Surface_mesh_parameterizationTheParameterizerTraits3 The ParameterizerTraits_3 Concept

This \cgal package implements 
surface parameterization methods, such as Least Squares Conformal Maps,
Discrete Conformal Map, Discrete Authalic
Parameterization, Floater Mean Value Coordinates or Tutte Barycentric
Mapping. These methods are provided as models of the
`ParameterizerTraits_3` concept. See Section \ref secSurfaceParameterizationMethods.

Each of these surface parameterization methods is templated by
the input mesh type, a border parameterization and a solver:

\cgalFigureBegin{Surface_mesh_parameterizationfigparameterizer_class_diagram_simplified,parameterizer_class_diagram_simplified.png}
A parameterizer UML class diagram (simplified).
\cgalFigureEnd

\subsection Surface_mesh_parameterizationTheBorderParameterizer3 The BorderParameterizer_3 Concept

Parameterization methods for
borders are used as traits classes modifying the behavior of
`ParameterizerTraits_3` models.
They are provided as models of the `BorderParameterizer_3` concept.
See Sections \ref secBorderParameterizationsforFixedMethods
and \ref secBorderParameterizationsforFreeMethods.

\subsection Surface_mesh_parameterizationTheSparseLinearAlgebraTraitsd The SparseLinearAlgebraTraits_d Concept

This package solves sparse linear systems using solvers which are models
of `SparseLinearAlgebraTraits_d`. See Chapter \ref PkgSolverSummary.

\subsection Surface_mesh_parameterizationTheParameterizationMesh3 The ParameterizationMesh_3 and ParameterizationPatchableMesh_3 Concepts

As described in Section \ref secInputMeshforparameterize
the input meshes handled by `parameterize()`
must be models of the `ParameterizationMesh_3` concept. The surface parameterization methods provided by this package only support
surfaces which are homeomorphic to disks, possibly with holes. Nevertheless meshed with arbitrary topology and number of connected components can be parameterized, provided that the user specifies a <I>cut graph</I> (an oriented list of
vertices) which is the border of a topological disc. If no cut graph is
specified as input, the longest border of the input mesh is taken by default, the others being considered as holes.

For this purpose, the
`Parameterization_mesh_patch_3<ParameterizationPatchableMesh_3>`
class is responsible for <I>virtually</I> cutting
a patch into a `ParameterizationPatchableMesh_3` mesh.
The resulting patch is a topological
disk (if the input cutting path is correct)
and provides a `ParameterizationMesh_3` interface. It can be used as
parameter for the function `parameterize()`.

`ParameterizationPatchableMesh_3` inherits from `ParameterizationMesh_3`,
thus is a concept for a 3D surface mesh.
`ParameterizationPatchableMesh_3` adds the ability to support patches and
virtual seams. <I>Patches</I> are a subset of a 3D mesh.
<I>Virtual seams</I> behave as if the surface was cut along a cut graph. More information is provided in Section \ref secCuttingaMesh.

\section secSurfaceParameterizationMethods Surface Parameterization Methods 

This \cgal package implements some of the state-of-the-art
surface parameterization methods, such as Least Squares Conformal Maps,
Discrete Conformal Map, Discrete Authalic
Parameterization, Floater Mean Value Coordinates or Tutte Barycentric
Mapping. These methods are provided as models of the
`ParameterizerTraits_3` concept.

\subsection Surface_mesh_parameterizationFixedBorder Fixed Border Surface Parameterizations

Fixed Border Surface Parameterizations need a set of constraints: two
(u,v) coordinates for each vertex along the border.
Such border parameterizations are described in Section
\ref secBorderParameterizationsforFixedMethods.

\subsection Surface_mesh_parameterizationTutteBarycentric Tutte Barycentric Mapping

`Barycentric_mapping_parameterizer_3<ParameterizationMesh_3, BorderParameterizer_3, SparseLinearAlgebraTraits_d>` 

The Barycentric Mapping parameterization method has been introduced by
Tutte \cgalCite{t-hdg-63}. In parameter space, each vertex is
placed at the barycenter of its neighbors to achieve the so-called
convex combination condition. This algorithm amounts to solve one
sparse linear solver for each set of parameter coordinates, with a
\#vertices x \#vertices sparse and symmetric positive definite matrix
(if the border vertices are eliminated from the linear system).
A coefficient \f$ (i, j)\f$ of the matrix is set to 1 for an edge linking
the vertex \f$ v_i\f$ to the vertex \f$ v_j\f$, to minus the degree of the
vertex \f$ v_i\f$ for a diagonal element, and to 0 for any other matrix
entry. Although a bijective mapping is guaranteed when the border is convex,
this method does not minimize angles nor areas distortion.

\cgalFigureBegin{Surface_mesh_parameterizationfiguniform,uniform.png}
Left: Tutte barycentric mapping parameterization (the red line depicts the cut graph). Right: parameter space.
\cgalFigureEnd

\subsection Surface_mesh_parameterizationDiscreteConformal Discrete Conformal Map

`Discrete_conformal_map_parameterizer_3<ParameterizationMesh_3, BorderParameterizer_3, SparseLinearAlgebraTraits_d>` 

Discrete conformal map parameterization has been introduced by Eck et
al. to the graphics community \cgalCite{cgal:eddhls-maam-95}. It attempts to
lower angle deformation by minimizing a discrete version of the
Dirichlet energy as derived by Pinkall and
Polthier \cgalCite{cgal:pp-cdmsc-93}. A one-to-one mapping is guaranteed
only when the two following conditions are fulfilled: the barycentric mapping
condition (each vertex in parameter space is a convex combination if
its neighboring vertices), and the border is convex.
This method solves two \#vertices x \#vertices sparse linear
systems. The matrix (the same for both systems) is sparse and symmetric definite
positive (if the border vertices are eliminated from the linear system
and if the mesh contains no hole),
thus can be efficiently solved using dedicated linear solvers.

\cgalFigureBegin{Surface_mesh_parameterizationfigconformal,conformal.png}
Left: discrete conformal map. Right: parameter space.
\cgalFigureEnd

\subsection Surface_mesh_parameterizationFloaterMean Floater Mean Value Coordinates

`Mean_value_coordinates_parameterizer_3<ParameterizationMesh_3, BorderParameterizer_3, SparseLinearAlgebraTraits_d>` 

The mean value coordinates parameterization method has been introduced
by Floater \cgalCite{cgal:f-mvc-03}. Each vertex in parameter space is
optimized so as to be a convex combination of its neighboring
vertices. The barycentric coordinates are this time unconditionally
positive, by deriving an application of the mean theorem for harmonic
functions. This method is in essence an approximation of the discrete conformal
maps, with a guaranteed one-to-one mapping when the border is convex.
This method solves two \#vertices x \#vertices sparse linear systems. The matrix (the
same for both systems) is asymmetric.

\cgalFigureBegin{Surface_mesh_parameterizationfigfloater,floater.png}
Floater Mean Value Coordinates
\cgalFigureEnd

\subsection Surface_mesh_parameterizationDiscreteAuthalic Discrete Authalic Parameterization

`Discrete_authalic_parameterizer_3<ParameterizationMesh_3, BorderParameterizer_3, SparseLinearAlgebraTraits_d>` 

The discrete authalic parameterization method has been introduced by
Desbrun et al. \cgalCite{cgal:dma-ipsm-02}. It corresponds to
a weak formulation of an area-preserving method, and in essence
locally minimizes the area distortion. A one-to-one mapping is
guaranteed only if the convex combination condition is fulfilled and
the border is convex. This method solves two
\#vertices x \#vertices sparse linear systems. The matrix (the same
for both systems) is asymmetric.

\cgalFigureBegin{Surface_mesh_parameterizationfigauthalic,authalic.png}
Discrete Authalic Parameterization
\cgalFigureEnd

\subsection secBorderParameterizationsforFixedMethods Border Parameterizations for Fixed Methods 

Parameterization methods for
borders are used as traits classes modifying the behavior of
`ParameterizerTraits_3` models.
They are provided as models of the `BorderParameterizer_3` concept.
Border parameterizations for fixed border surface parameterizations
are a family of methods to define a set of constraints, namely two
\f$ u,v\f$ coordinates for each vertex along the border.

<UL>

<LI>The user can select a border parameterization among
two commonly used methods: uniform or arc-length parameterization.

<I>Usage:</I>

Uniform border parameterization is more stable, although it gives
poor visual results. The
arc-length border parameterization is used by default.

<LI>One convex shape specified by one shape among two standard ones:
a circle or a square.

<I>Usage:</I>

The circular border parameterization is used by default as it
corresponds to the simplest convex shape. The square border
parameterization is commonly used for texture mapping.

</UL>

`Circular_border_arc_length_parameterizer_3<ParameterizationMesh_3>` 

`Circular_border_uniform_parameterizer_3<ParameterizationMesh_3>` 

`Square_border_arc_length_parameterizer_3<ParameterizationMesh_3>` 

`Square_border_uniform_parameterizer_3<ParameterizationMesh_3>` 

\cgalFigureBegin{Surface_mesh_parameterizationfigcircular_border,border.png}
Left: Julius Cesar mask parameterization with Authalic/circular border. Right: Julius Cesar mask's image with Floater/square border.
\cgalFigureEnd

\subsection Surface_mesh_parameterizationFreeBorderSurface Free Border Surface Parameterizations

\subsection Surface_mesh_parameterizationLeastSquares Least Squares Conformal Maps

`LSCM_parameterizer_3<ParameterizationMesh_3, BorderParameterizer_3, SparseLinearAlgebraTraits_d>` 

The Least Squares Conformal Maps (LSCM) parameterization method has
been introduced by L&eacute;vy et al. \cgalCite{cgal:lprm-lscm-02}.
It corresponds to a conformal method with a free border (at least two
vertices have to be constrained to obtain a unique solution), which
allows further lowering of the angle distortion. A one-to-one mapping
is not guaranteed by this method. It solves a (2 \f$ \times\f$
\#triangles) \f$ \times\f$ \#vertices sparse linear system in the least squares sense,
which implies solving a symmetric matrix.

\cgalFigureBegin{Surface_mesh_parameterizationfigLSCM,LSCM.png}
Least squares conformal maps.
\cgalFigureEnd

\subsection secBorderParameterizationsforFreeMethods Border Parameterizations for Free Methods 

Parameterization methods for
borders are used as traits classes modifying the behavior of
`ParameterizerTraits_3` models. They are provided as models of the `BorderParameterizer_3` concept.
The border parameterizations associated to free border surface
parameterization methods define only two constraints: the pinned vertices.

<UL>

<LI>`Two_vertices_parameterizer_3<ParameterizationMesh_3>` 

<I>Usage:</I>

`Two_vertices_parameterizer_3<ParameterizationMesh_3>` is the default
free border parameterization, and is the only one available
in the current version of this package.

</UL>

\subsection Surface_mesh_parameterizationDiscreteAuthalic_1 Discrete Authalic Parameterization Example

In the following example, we compute a Discrete Authalic parameterization
over a `Polyhedron_3<Traits>` mesh. Specifying a specific surface parameterization
instead of the default one means using the second parameter of `parameterize()`. The
differences with the first example  \ref Surface_mesh_parameterization/Simple_parameterization.cpp "Simple_parameterization.cpp" are:

\code{.cpp}

#include <CGAL/Discrete_authalic_parameterizer_3.h>

...

//***************************************
// Discrete Authalic Parameterization
//***************************************

typedef CGAL::Discrete_authalic_parameterizer_3<Parameterization_polyhedron_adaptor>
Parameterizer;

Parameterizer::Error_code err = CGAL::parameterize(mesh_adaptor, Parameterizer());

...

\endcode

\subsection Surface_mesh_parameterizationSquareBorder Square Border Arc Length Parameterization Example

In the following example, we compute a Floater mean value coordinates
parameterization with a square border arc length parameterization.
Specifying a specific border parameterization
instead of the default one means using the second parameter of
`Mean_value_coordinates_parameterizer_3<ParameterizationMesh_3, BorderParameterizer_3, SparseLinearAlgebraTraits_d>`.
The differences with the first example \ref Surface_mesh_parameterization/Simple_parameterization.cpp "Simple_parameterization.cpp" are:

\code{.cpp}

#include <CGAL/Square_border_parameterizer_3.h>

...

//***************************************
// Floater Mean Value Coordinates parameterization
// with square border
//***************************************

// Square border parameterizer
typedef CGAL::Square_border_arc_length_parameterizer_3<Parameterization_polyhedron_adaptor>
Border_parameterizer;

// Floater Mean Value Coordinates parameterizer with square border
typedef CGAL::Mean_value_coordinates_parameterizer_3<Parameterization_polyhedron_adaptor,
Border_parameterizer>
Parameterizer;

Parameterizer::Error_code err = CGAL::parameterize(mesh_adaptor, Parameterizer());

...

\endcode



\section secCuttingaMesh Cutting a Mesh 

\subsection Surface_mesh_parameterizationComputingaCut Computing a Cut Graph

All surface parameterization methods proposed in this package only
deal with meshes which are homeomorphic (topologically equivalent) to discs.
Nevertheless meshes with arbitrary topology and number of connected components car be parameterized, provided that the user specifies a cut graph (an oriented list of vertices), which is the border of a topological disc. If no cut graph is
provided as input, the longest border already
in the input mesh is taken as default border, all other borders being considered as holes. Note that only the inside part (i.e., one connected component) of the given border is parameterized.

\cgalFigureBegin{Surface_mesh_parameterizationfigcut,cut.png}
Cut Graph
\cgalFigureEnd

This package does not provide any algorithm to transform an arbitrary mesh
into a topological disk, the user being responsible
for generating such a cut graph. Nevertheless, we provide in
\ref Surface_mesh_parameterization/polyhedron_ex_parameterization.cpp "polyhedron_ex_parameterization.cpp"
a simple cutting algorithm for the sake of completeness.

\subsection Surface_mesh_parameterizationApplyingaCut Applying a Cut

The surface parameterization classes in this package only <I>directly</I> support
surfaces which are homeomorphic to disks (models of
`ParameterizationMesh_3`). This software design simplifies the
implementation of all new parameterization methods.

The `Parameterization_mesh_patch_3<ParameterizationPatchableMesh_3>`
class is responsible for <I>virtually</I> cutting
a patch in a `ParameterizationPatchableMesh_3` mesh.
The resulting patch is a topological
disk (if the cut graph is correct)
and provides a `ParameterizationMesh_3` interface. It can be used as
parameter of `parameterize()`.

`ParameterizationPatchableMesh_3` inherits from concept `ParameterizationMesh_3`,
thus is a concept for a 3D surface mesh.
`ParameterizationPatchableMesh_3` adds the ability to support patches and
virtual seams. <I>Patches</I> are a subset of a 3D mesh.
<I>Virtual seams</I> behave exactly as if the surface was cut along a certain graph.

The `ParameterizationMesh_3` interface with the Polyhedron is both a model of
`ParameterizationMesh_3` and `ParameterizationPatchableMesh_3`: 

`Parameterization_polyhedron_adaptor_3<Polyhedron_3_>`

Note that this class is a decorator which adds <I>on the fly</I>
the necessary fields to unmodified \cgal data structures (using STL
maps). For better performances, it is recommended to use \cgal data
structures enriched with the proper fields. See `Polyhedron_ex`
class in \ref Surface_mesh_parameterization/polyhedron_ex_parameterization.cpp "polyhedron_ex_parameterization.cpp" example.

\subsection Surface_mesh_parameterizationCuttingaMesh Cutting a Mesh Example

In the following example, we <I>virtually</I> cut a
`Polyhedron_3<Traits>` mesh
to make it a topological disk, then applies the default parameterization:

\cgalExample{Surface_mesh_parameterization/Mesh_cutting_parameterization.cpp}

\section Surface_mesh_parameterizationOutput Output

Parameterization methods compute \f$ (u,v)\f$ fields for each vertex
of the input mesh, with the seam vertices being virtually duplicated (thanks
to `Parameterization_mesh_patch_3<ParameterizationPatchableMesh_3>`).
To support this duplication,
`Parameterization_polyhedron_adaptor_3<Polyhedron_3_>` stores
the result in the \f$ (u,v)\f$ fields of the input mesh halfedges.
A \f$ (u,v)\f$ pair is computed for
each inner vertex (i.e.\ its halfedges share the same \f$ (u,v)\f$ pair),
while a \f$ (u,v)\f$ pair is computed for each border halfedge.
The user has to iterate over the mesh halfedges to get the result.
Note that \f$ (u,v)\f$ fields do not exist in `Polyhedron_3<Traits>`,
thus the output traversal is specific to the way the (u,v) fields are implemented by the adaptor.

\subsection Surface_mesh_parameterizationEPSOutputExample EPS Output Example

The follwing example is a complete parameterization
example which outputs the resulting parameterization to a EPS file. It gets the \f$ (u,v)\f$ fields computed by a parameterization method over a `Polyhedron_3<Traits>` mesh with a
`Parameterization_polyhedron_adaptor_3<Polyhedron_3_>` adaptor:

\cgalExample{Surface_mesh_parameterization/Complete_parameterization_example.cpp}

\section Surface_mesh_parameterizationComplexity Complexity and Guarantees

\subsection Surface_mesh_parameterizationParameterization Parameterization Methods and Guarantees

<UL>

<LI>Fixed boundaries

<UL>

<LI>One-to-one mapping

Tutte's theorem guarantees a one-to-one mapping provided that the weights are all positive
and the border convex.
It is the case for Tutte barycentric mapping and Floater mean value coordinates.
It is not always the case for discrete conformal map (cotangents) and
discrete authalic parameterization.

<LI>Non-singularity of the matrix

Geshorgin's theorem guarantees the convergence of the solver if the matrix is diagonal dominant.
This is the case with positive weights (Tutte barycentric mapping and Floater mean value coordinates).

</UL>

<LI>Free boundaries

<UL>

<LI>One-to-one mapping

No guarantee is provided by LSCM (both global overlaps and triangle flips can
occur).

<LI>Non-singularity of the matrix

For LSCM, the matrix of the system is the Gram matrix of a matrix with maximal rank,
and is therefore non-singular (Gram theorem).

</UL>

</UL>



\section Surface_mesh_parameterizationSoftware Software Design

\subsection Surface_mesh_parameterizationGlobalFunction Global Function parameterize()

This package's entry point is:

\code{.cpp}

// Compute a one-to-one mapping from a 3D triangle surface mesh to a
// 2D circle, using Floater Mean Value Coordinates algorithm.
// A one-to-one mapping is guaranteed.
template <class ParameterizationMesh_3>
typename Parameterizer_traits_3<ParameterizationMesh_3>::Error_code
parameterize(ParameterizationMesh_3& mesh) // 3D mesh, model of ParameterizationMesh_3 concept
{
Mean_value_coordinates_parameterizer_3<ParameterizationMesh_3> parameterizer;
return parameterizer.parameterize(mesh);
}

// Compute a one-to-one mapping from a 3D triangle surface mesh to a
// simple 2D domain.
// One-to-one mapping may be guaranteed or not,
// depending on the chosen ParametizerTraits_3 algorithm.
template <class ParameterizationMesh_3, class ParameterizerTraits_3>
typename Parameterizer_traits_3<ParameterizationMesh_3>::Error_code
parameterize(ParameterizationMesh_3& mesh, // 3D mesh, model of ParameterizationMesh_3
ParameterizerTraits_3 parameterizer) // Parameterization method for mesh
{
return parameterizer.parameterize(mesh);
}

\endcode

You may notice that these global functions simply call the
parameterize() method of a `ParameterizerTraits_3` object.
The purpose of these global functions is:
<UL>
<LI>to be consistent with other \cgal algorithms that are also provided as
global functions, e.g. `convex_hull_2()`,
<LI>to provide a default parameterization method (Floater Mean Value Coordinates),
which wouldn't be possible with a direct call to an object's method.
</UL>

You may also wonder why there is not just one `parameterize()` function
with a default `ParameterizerTraits_3` argument equal to
`Mean_value_coordinates_parameterizer_3<ParameterizationMesh_3>`.
The reason is simply that this is not allowed by the C++ standard (see
\cgalCite{cgal:ansi-is14882-98}, paragraph 14.1/9).

\subsection Surface_mesh_parameterizationNoCommonParameterization No Common Parameterization Algorithm

`ParameterizerTraits_3` models modify the behavior of the global function
`parameterize()` - hence the <I>Traits</I> in the name.
On the other hand, `ParameterizerTraits_3` models do not modify the behavior
of a common parameterization algorithm - as you might expect.

In this package, we focus on triangulated surfaces that are homeomorphic to a
disk and on piecewise linear mappings onto planar domains.
A consequence is that the skeleton of all parameterization methods of this
package is the same:
<UL>
<LI>Allocate a sparse linear system \f$ A \times X = B\f$
<LI>Parameterize the mesh border and initialize \f$ B\f$
<LI>Parameterize the inner points of the mesh and set \f$ A\f$ coefficients
<LI>Solve the system
</UL>

It is tempting to make the parameterization method a traits class that
modifies the behavior of a common parameterization algorithm.
On the other hand, there are several differences among methods:
<UL>
<LI>Fixed border methods need to parameterize all border vertices,
while free border methods parameterize only two vertices.
<LI>Some methods create symmetric definite positive systems,
which may be solved more efficiently than general systems.
<LI>Most parameterization methods use two \#vertices x \#vertices systems,
where Least Squares Conformal Maps uses one (2 * \#triangles) x \#vertices system.
<LI>Most parameterization methods invert the \f$ A\f$ matrix,
when Least Squares Conformal Maps solves the system in the least squares sense.
</UL>

Therefore, the software design chosen is:
<UL>
<LI>Each `ParameterizerTraits_3` model implements its own version
of the parameterization algorithm as a parameterize() method.
<LI>Each `ParameterizerTraits_3` model has template arguments
defining the border parameterization and sparse linear solver to use,
with default values adapted to the method.
<LI>Code factorization is achieved using a class hierarchy and (few) virtual methods.
</UL>

\cgalFigureBegin{Surface_mesh_parameterizationfigparameterizer_class_diagram,parameterizer_class_diagram.png}
A parameterizer UML class diagram (main types and methods only)
\cgalFigureEnd

\cgalFigureBegin{Surface_mesh_parameterizationfigparameterizers_class_hierarchy,parameterizers_class_hierarchy.png}
Surface parameterizer classes hierarchy
\cgalFigureEnd

\note `Parameterizer_traits_3<ParameterizationMesh_3>` is the (pure virtual)
superclass of all surface parameterization classes.

\subsection Surface_mesh_parameterizationFixedborderparameterizer3 Fixed_border_parameterizer_3 Class

Linear fixed border parameterization algorithms are very close. They mainly
differ by the energy that they try to minimize, i.e.\ by the value of the \f$ w_{ij}\f$
coefficient of the \f$ A\f$ matrix, for \f$ v_i\f$ and \f$ v_j\f$ neighbor vertices of the mesh
\cgalCite{cgal:fh-survey-05}. One consequence is that most of the code of the fixed border methods is factorized in the
`Fixed_border_parameterizer_3<ParameterizationMesh_3, BorderParameterizer_3, SparseLinearAlgebraTraits_d>` class.

Subclasses:
<UL>
<LI>must provide `BorderParameterizer_3` and `SparseLinearAlgebraTraits_d`
default template parameters that make sense,
<LI>must implement `compute_w_ij`() to compute \f$ w_{ij}\f$ = (i, j) coefficient
of matrix \f$ A\f$ for \f$ v_j\f$ neighbor vertex of \f$ v_i\f$,
<LI>may implement an optimized version of `is_one_to_one_mapping`().
</UL>

See `Barycentric_mapping_parameterizer_3<ParameterizationMesh_3, BorderParameterizer_3, SparseLinearAlgebraTraits_d>`
class as an example.

\subsection Surface_mesh_parameterizationBorderParameterizations Border Parameterizations

Border Parameterizations are models of the `BorderParameterizer_3` concept.
To simplify the implementation, `BorderParameterizer_3` models know only the
`ParameterizationMesh_3` mesh class. They do not know the parameterization algorithm or the sparse linear solver used.

\subsection Surface_mesh_parameterizationParameterizationMesh3 ParameterizationMesh_3 and ParameterizationPatchableMesh_3 Concepts

All parameterization methods are templated by the kind of mesh they are applied on.
The mesh type must be a model of `ParameterizationMesh_3`.

The purpose of such a model is to:
<OL>
<LI>Support several kind of meshes.
<LI>Hide the implementation of extra fields specific to the parameterization domain
(`index`, `u`, `v`, `is_parameterized`).
<LI>%Handle in the mesh type the complexity of <I>virtually</I> cutting a mesh
to make it homeomorphic to a disk (instead of duplicating this
code in each parameterization method).
</OL>

Two options are possible for 1) and 2):
<UL>
<LI>Pass to all classes and methods a mesh pointer, a traits class to manipulate it,
and accessors to the extra field arrays.
This is the choice of the Boost Graph Library with `boost::graph_traits<>`
and the property maps.
<LI>Pass to all classes and methods an object that points to the actual mesh and knows
how to access to its fields. This is the Adaptor concept \cgalCite{cgal:ghjv-dpero-95}.
</UL>

The current design of this package uses the second option, which is simpler.
Of course, we may decide at some point to switch to the first one to reach a deeper integration
of \cgal with Boost.

Point 3) is solved by class `Parameterization_mesh_patch_3<ParameterizationPatchableMesh_3>`,
which takes care of <I>virtually</I> cutting
a patch in a `ParameterizationPatchableMesh_3` mesh, to make it appear as a topological disk
with a `ParameterizationMesh_3` interface.
`ParameterizationPatchableMesh_3` inherits from concept `ParameterizationMesh_3` and adds
the ability to support patches and virtual seams.

This mainly means that:
<UL>
<LI>vertices can be tagged as inside or outside the patch to parameterize,
<LI>the fields specific to parameterizations (`index`, `u`, `v`, `is_parameterized`)
can be set <I>per corner</I> (which is a more general way of saying <I>per half-edge</I>).
</UL>


\subsection Surface_mesh_parameterizationCuttingaMesh_1 Cutting a Mesh

In this package, we focus on triangulated surfaces that are homeomorphic to a
disk.

Computing a cutting path that transforms a closed mesh of arbitrary genus into
a topological disk is a research topic on its own. This package does
not intend to cover this topic at the moment.

\section Surface_mesh_parameterizationExtendingthe Extending the Package and Reusing Code



\subsection Surface_mesh_parameterizationAddingNewParameterization Adding New Parameterization Methods

Implementing a new fixed border linear parameterization is easy. Most
of the code of the fixed border methods is factorized in the
`Fixed_border_parameterizer_3<ParameterizationMesh_3, BorderParameterizer_3, SparseLinearAlgebraTraits_d>`
class. Subclasses must mainly
implement a `compute_w_ij`() method which computes each
\f$ w_{ij}\f$ = \f$ (i, j)\f$ coefficient of the matrix \f$ A\f$ for \f$ v_j\f$ neighboring
vertices of \f$ v_i\f$.

Although implementing a new free border linear parameterization
method is more challenging, the Least Squares Conformal Maps
parameterization method provides a good starting point.

Implementing <I>non</I> linear parameterizations is a natural extension
to this package, although only the mesh adaptors can be reused.

\subsection Surface_mesh_parameterizationAddingNewBorder Adding New Border Parameterization Methods

Implementing a new border parameterization method is easy.
Square, circular and two-points border parameterizations are good starting points.

\subsection Surface_mesh_parameterizationMeshCutting Mesh Cutting

Obviously, this package would benefit of having robust algorithms
which transform arbitrary meshes into topological disks.


*/ 
} /* namespace CGAL */

