% +------------------------------------------------------------------------+
% | Reference manual page: Parameterization/intro.tex
% +------------------------------------------------------------------------+
% | 08.22.2005   Laurent Saboret, Pierre Alliez
% | Package: Parameterization
% |
% |
% +------------------------------------------------------------------------+

%\clearpage
%\section{Reference Pages for Planar Parameterization of Triangulated Surface Meshes}
\chapter{Planar Parameterization of Triangulated Surface Meshes}
\label{chap:parameterization_ref}
\ccChapterAuthor{Laurent Saboret \and Pierre Alliez}

% pierre: replace border by boundary
% laurent: Andreas asked to replace boundary by border everywhere...


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 or area distortions in some sense. In this
package, we focus on triangulated surfaces that are homeomorphic to a
disk and on piecewise linear mappings into a planar domain.

\ccHeading{Parameterization methods}

This \cgal\ package implements some of
the state-of-the-art parameterization methods:

\begin{itemize}

\item Fixed border:

    \begin{itemize}

    \item Tutte Barycentric Mapping \cite{t-hdg-63}.
    One-to-one mapping is guaranteed for convex border.

    \item Floater Mean Value Coordinates \cite{cgal:f-mvc-03}.
    One-to-one mapping is guaranteed for convex border.

    \item Discrete Conformal Map \cite{cgal:eddhls-maam-95}.
    Conditionally guaranteed if all weights are positive and border is convex.

    \item Discrete Authalic parameterization \cite{cgal:dma-ipsm-02}.
    Conditionally guaranteed if all weights are positive and border is convex.

    \end{itemize}

\item Free border:

    \begin{itemize}

    \item Least Squares Conformal Maps \cite{cgal:lprm-lscm-02}.

    \item Natural Conformal Map \cite{cgal:dma-ipsm-02}.

    \end{itemize}

\end{itemize}


\ccHeading{Border Parameterization Methods}

Border parameterization methods define a
set of constraints (a constraint specifies two u,v coordinates for
each instance of a vertex along the border).

This package implements all common border parameterization methods:
\begin{itemize}

\item For free border methods: at least two constraints (the pinned
vertices). They have to be on the specified border.

\item For fixed border methods:

    \begin{itemize}

    \item the user can select a border
        parameterization among two common methods: uniform or
        arc-length parameterization.

    \item one convex shape specified by:

        \begin{itemize}

        \item one shape among a set of standard ones (circle, square).

        \item a convex polygon.

        \end{itemize}

    \end{itemize}

\end{itemize}


\ccHeading{Mesh}

The general definition of input meshes handled by the package is:

\begin{itemize}

\item Triangulated

\item 2-manifold

\item Oriented.

\item Surface parameterization methods deal only with topological discs.
The input mesh can be of any genus and have any number of connected components.
If it is not a topological disc, it has to come with a description of a border
(a list of vertices) which is the border of a topological disc.
If no border is given, we assume that the surface border
is the longest border already in the input mesh (the other borders will
be considered as holes).

The package will only parameterize the inside part of the given border,
thus only one connected component.

Note that this way the user is responsible for cutting a closed mesh of
arbitrary genus (even a topological disc with an intricate seam
cut), as long as this condition is fulfilled.

\end{itemize}

The package proposes
an interface with both the 2D Triangulation Data Structure enriched
with 3D points (not yet implemented) and the Polyhedron.

The \cgal\ parameterization package is loosely linked to the
mesh data structure. Replacing it is relatively easy.


\ccHeading{Output}

One uv coordinate for each interior vertex, and one uv coordinate for
each instance of a vertex along the input border.


\ccHeading{Sparse Linear Algebra}

Since parameterizing meshes requires
efficient representation of sparse matrices and efficient iterative or
direct linear solvers, we provide an interface to several
sparse linear solvers:
\begin{itemize}
\item OpenNL (Bruno L{\'e}vy) is shipped with \cgal. This is the default solver.
\item TAUCS is a state-of-the-art direct solver for sparse symmetric matrices.
\item SuperLU is a state-of-the-art direct solver for sparse unsymmetric matrices (not yet implemented).
\end{itemize}

The \cgal\ parameterization package is loosely linked to the
solver. Replacing it is easy.


\ccHeading{Assertions}

The assertion flags for the package
use \ccc{PARAMETERIZATION} in their names (\textit{e.g.},
\ccc{CGAL_PARAMETERIZATION_NO_ASSERTIONS}).

For \emph{fixed} border parameterizations:
\begin{itemize}
\item Preconditions:
    \begin{itemize}
    \item check that the border is mapped onto a convex polygon.
    \item check that the input mesh is triangular (expensive check).
    \item check that the input mesh is a surface with 1 connected component (expensive check).
    \end{itemize}
\item Postconditions:
    \begin{itemize}
    \item check one-to-one mapping.
    \item check if the linear system was solved with a good conditioning (expensive check).
    \end{itemize}
\end{itemize}

For \emph{free} border parameterizations:
\begin{itemize}
\item Preconditions:
    \begin{itemize}
    \item check that the input mesh is triangular (expensive check).
    \item check that the input mesh is a surface with 1 connected component (expensive check).
    \end{itemize}
\item Postconditions:
    \begin{itemize}
    \item check one-to-one mapping.
    \item check if the linear system was solved with a good conditioning (expensive check, not yet implemented).
    \end{itemize}
\end{itemize}

Expensive checking is off by default. It can be enabled by
defining \ccc{CGAL_PARAMETERIZATION_CHECK_EXPENSIVE}.


\ccHeading{Concepts}

\ccRefIdfierPage{ParameterizerTraits_3}  \\
\ccRefIdfierPage{BorderParameterizer_3}  \\
\ccRefIdfierPage{ParameterizationMesh_3}  \\
\ccRefIdfierPage{ParameterizationPatchableMesh_3}  \\
\ccRefIdfierPage{SparseLinearAlgebraTraits_d}  \\


\ccHeading{Parameterization Methods Traits Classes}

\ccRefIdfierPage{CGAL::Parameterizer_traits_3}  \\
\ccRefIdfierPage{CGAL::Fixed_border_parameterizer_3}  \\
\ccRefIdfierPage{CGAL::Barycentric_mapping_parameterizer_3}  \\
\ccRefIdfierPage{CGAL::Discrete_authalic_parameterizer_3}  \\
\ccRefIdfierPage{CGAL::Discrete_conformal_map_parameterizer_3}  \\
\ccRefIdfierPage{CGAL::LSCM_parameterizer_3}  \\
\ccRefIdfierPage{CGAL::Mean_value_coordinates_parameterizer_3}  \\


\ccHeading{Border Parameterization Methods Traits Classes}

\ccRefIdfierPage{CGAL::Circular_border_arc_length_parameterizer_3}  \\
\ccRefIdfierPage{CGAL::Circular_border_uniform_parameterizer_3}  \\
\ccRefIdfierPage{CGAL::Square_border_arc_length_parameterizer_3}  \\
\ccRefIdfierPage{CGAL::Square_border_uniform_parameterizer_3}  \\
\ccRefIdfierPage{CGAL::Two_vertices_parameterizer_3}  \\


\ccHeading{MeshAdaptor\_3 and PatchableMeshAdaptor\_3 Traits Classes}

\ccRefIdfierPage{CGAL::Parameterization_polyhedron_adaptor_3}  \\
\ccRefIdfierPage{CGAL::Parameterization_mesh_patch_3}  \\


\ccHeading{Sparse Linear Algebra Traits Classes}

\ccRefIdfierPage{CGAL::Taucs_solver_traits}  \\
\ccRefIdfierPage{CGAL::Taucs_symmetric_solver_traits}  \\
\ccc{OpenNL::DefaultLinearSolverTraits}  \\
\ccc{OpenNL::SymmetricLinearSolverTraits}  \\


\ccHeading{Helper Classes}

\ccRefIdfierPage{CGAL::Parameterization_mesh_feature_extractor}  \\


\ccHeading{Functions}

\ccRefIdfierPage{CGAL::parameterize}  \\


\clearpage

\lcHtml{\ccHeading{Alphabetical Listing of Reference Pages}}
