Large changes of the user manual requested by MK:

- added paragraph about exact arithmetic and algorithmic complexity (BL)
- concepts are now described at the begining of the user manual
- mesh cutting is better explained (picture provided by PA)
- improved description of available solvers
- reference pages are listed thematically in the reference manual
- Fixed UML diagrams in Software Design section

Other changes requested by PA:
- pictures of algorithms output in 2D (EPS)

.gitattributes

@@ -1643,20 +1643,38 @@ Subdivision_method_3/test/Subdivision_method_3/data/quint_tris.off -text
 Surface_mesh_parameterization/doc/specification/param.pdf -text svneol=unset#unset
 Surface_mesh_parameterization/doc_tex/Surface_mesh_parameterization/LSCM.eps -text
 Surface_mesh_parameterization/doc_tex/Surface_mesh_parameterization/LSCM.png -text svneol=unset#unset
+Surface_mesh_parameterization/doc_tex/Surface_mesh_parameterization/LSCM_2.eps -text
+Surface_mesh_parameterization/doc_tex/Surface_mesh_parameterization/LSCM_2.png -text
 Surface_mesh_parameterization/doc_tex/Surface_mesh_parameterization/authalic.eps -text
 Surface_mesh_parameterization/doc_tex/Surface_mesh_parameterization/authalic.png -text svneol=unset#unset
+Surface_mesh_parameterization/doc_tex/Surface_mesh_parameterization/authalic_2.eps -text
+Surface_mesh_parameterization/doc_tex/Surface_mesh_parameterization/authalic_2.png -text
+Surface_mesh_parameterization/doc_tex/Surface_mesh_parameterization/circular_border.eps -text
+Surface_mesh_parameterization/doc_tex/Surface_mesh_parameterization/circular_border.png -text
 Surface_mesh_parameterization/doc_tex/Surface_mesh_parameterization/conformal.eps -text
 Surface_mesh_parameterization/doc_tex/Surface_mesh_parameterization/conformal.png -text svneol=unset#unset
+Surface_mesh_parameterization/doc_tex/Surface_mesh_parameterization/conformal_2.eps -text
+Surface_mesh_parameterization/doc_tex/Surface_mesh_parameterization/conformal_2.png -text
+Surface_mesh_parameterization/doc_tex/Surface_mesh_parameterization/cut.eps -text
+Surface_mesh_parameterization/doc_tex/Surface_mesh_parameterization/cut.png -text
 Surface_mesh_parameterization/doc_tex/Surface_mesh_parameterization/floater.eps -text
 Surface_mesh_parameterization/doc_tex/Surface_mesh_parameterization/floater.png -text svneol=unset#unset
+Surface_mesh_parameterization/doc_tex/Surface_mesh_parameterization/floater_2.eps -text
+Surface_mesh_parameterization/doc_tex/Surface_mesh_parameterization/floater_2.png -text
 Surface_mesh_parameterization/doc_tex/Surface_mesh_parameterization/introduction.eps -text
 Surface_mesh_parameterization/doc_tex/Surface_mesh_parameterization/introduction.png -text svneol=unset#unset
 Surface_mesh_parameterization/doc_tex/Surface_mesh_parameterization/parameterizer_class_diagram.eps -text
 Surface_mesh_parameterization/doc_tex/Surface_mesh_parameterization/parameterizer_class_diagram.png -text svneol=unset#unset
+Surface_mesh_parameterization/doc_tex/Surface_mesh_parameterization/parameterizer_class_diagram_simplified.eps -text
+Surface_mesh_parameterization/doc_tex/Surface_mesh_parameterization/parameterizer_class_diagram_simplified.png -text
 Surface_mesh_parameterization/doc_tex/Surface_mesh_parameterization/parameterizers_class_hierarchy.eps -text
 Surface_mesh_parameterization/doc_tex/Surface_mesh_parameterization/parameterizers_class_hierarchy.png -text svneol=unset#unset
+Surface_mesh_parameterization/doc_tex/Surface_mesh_parameterization/square_border.eps -text
+Surface_mesh_parameterization/doc_tex/Surface_mesh_parameterization/square_border.png -text
 Surface_mesh_parameterization/doc_tex/Surface_mesh_parameterization/uniform.eps -text
 Surface_mesh_parameterization/doc_tex/Surface_mesh_parameterization/uniform.png -text svneol=unset#unset
+Surface_mesh_parameterization/doc_tex/Surface_mesh_parameterization/uniform_2.eps -text
+Surface_mesh_parameterization/doc_tex/Surface_mesh_parameterization/uniform_2.png -text
 Surface_mesh_parameterization/examples/Surface_mesh_parameterization/data/check_16_2048.bmp -text
 Surface_mesh_parameterization/examples/Surface_mesh_parameterization/data/holes.off -text
 Surface_mesh_parameterization/examples/Surface_mesh_parameterization/data/mannequin-devil.off -text

Surface_mesh_parameterization/doc/concepts/BorderParameterizer_3.h

@@ -24,7 +24,7 @@
 /// Implementation note:
 /// To simplify the implementation, BorderParameterizer_3 models know only the
 /// ParameterizationMesh_3 class. They do not know the parameterization algorithm
-/// requirements nor the kind of sparse linear system used.
+/// requirements or the kind of sparse linear system used.
 ///
 /// Design Pattern:
 /// BorderParameterizer_3 models are Strategies [GHJV95]: they implement

Surface_mesh_parameterization/doc/concepts/ParameterizationMesh_3.h

@@ -39,14 +39,14 @@
 /// Among other things, this concept defines accessors to fields specific
 /// to parameterizations methods: index, u, v, is_parameterized.
 ///
-/// ParameterizationMesh_3 meshes can have any genus, arity or number of components. In the other hand,
+/// ParameterizationMesh_3 meshes can have any genus, arity or number of components. On the other hand,
 /// as parameterization methods deal only with topological disks, ParameterizationMesh_3
 /// defines an interface oriented towards topological disks.
 ///
 /// Models:
 /// - Adaptator for Polyhedron_3 is provided.
 /// - Parameterization_mesh_patch_3<M> is a model of ParameterizationMesh_3 if
-///   M is a model of MeshAdaptorWithStream_3.
+///   M is a model of ParameterizationPatchableMesh_3.
 ///
 /// Design Pattern:
 /// ParameterizationMesh_3 is an Adaptor [GHJV95]: it changes the

Surface_mesh_parameterization/doc/concepts/ParameterizationPatchableMesh_3.h

@@ -22,8 +22,8 @@
 /// thus is a concept of a 3D surface mesh.
 ///
 /// ParameterizationPatchableMesh_3 adds the ability to support patches and virtual seams.
-/// Patches are a subset of a 3D mesh. Virtual seams are the ability
+/// "Patches" are a subset of a 3D mesh. "Virtual seams" are the ability
-/// to behave exactly as if the surface was "cut" following a certain path.
+/// to behave exactly as if the surface was cut following a certain path.
 ///
 /// This mainly means that:
 /// - vertices can be tagged as inside or outside the patch to parameterize.

Surface_mesh_parameterization/doc_tex/Surface_mesh_parameterization/basics.tex

@@ -1,7 +1,7 @@
 \section{Basics}
 
 
-\subsection{Default Parameterization}
+\subsection{Default Surface Parameterization}
 
 From the user point of view, the simplest entry point to this package
 is the following function:
@@ -14,18 +14,24 @@ Preconditions:\begin{itemize}
 \item 'mesh' must be a surface with one connected component.\item 'mesh' must be a triangular mesh.\end{itemize}
 }
 
-The CGAL::parameterize() function provides a default parameterization
+The \ccc{CGAL::parameterize()} function applies a default surface parameterization
 method: Floater Mean Value Coordinates~\cite{cgal:f-mvc-03}, with an
 arc-length circular border parameterization, and using OpenNL sparse
 linear solver~\cite{cgal:l-nmdgp-05}.
 
-The result is stored into the (u,v) fields of the mesh vertices and/or
+The \ccc{ParameterizationMesh_3} concept defines the input meshes handled
-halfedges.
+by \ccc{CGAL::parameterize()}. See Section \ref{sec:Input-Mesh-for-parameterize}.
+
+The result is stored into the (u,v) fields of the mesh halfedges.
+
+Note: \ccc{CGAL::Parameterizer_traits_3<ParameterizationMesh_3>} is the (pure virtual)
+superclass of all surface parameterizations and defines the error codes.
 
 
-\subsection{List of Supported Meshes and Concept}
+\subsection{Input Mesh for parameterize()}
+\label{sec:Input-Mesh-for-parameterize}
 
-The general definition of input meshes handled by the package is:
+The general definition of input meshes handled by \ccc{CGAL::parameterize()} is:
 
 \begin{itemize}
 
@@ -35,47 +41,131 @@ The general definition of input meshes handled by the package is:
 
 \item Oriented.
 
-\item All surface parameterization methods only deal with topological discs.
+\item Homeomorphic to a disc (may have holes).
-The input mesh can be of any genus and have an arbitrary 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 as input, we
-assume that the surface border is the longest border already
-present in the input mesh (the other borders are considered as
-holes).
-
-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.
-
-The package will only parameterize the inside part of the given
-border, thus only one connected component.
 
 \end{itemize}
 
-The package accesses such meshes through the
+These input meshes must be models of the \ccc{ParameterizationMesh_3} concept.
-\ccc{ParameterizationMesh_3} concept. Among other things, this concept
+In fact, \ccc{ParameterizationMesh_3} is a general concept to access to a
-defines the accessor to the (u,v) values computed by
+polyhedral mesh.
-parameterizations.
+It is optimized for the \ccc{Surface_mesh_parameterization} package
+only in the sense that it
+defines the accessors to fields specific to the parameterization domain
+(\ccc{index}, \ccc{u}, \ccc{v}, \ccc{is_parameterized}).
 
-The package provides a model of the concept
+The extra constraints  needed by the surface parameterization methods (triangulated,
-\ccc{ParameterizationMesh_3} to access \cgal\ \ccc{Polyhedron_3}:
+2-manifold, homeomorphic to a disc) are not part of the concept and
+are checked at runtime.
+
+This package provides a model of the \ccc{ParameterizationMesh_3} concept
+to access \ccc{CGAL::Polyhedron_3<Traits>}:
 
 \ccc{CGAL::Parameterization_polyhedron_adaptor_3<Polyhedron_3_>}  \\
 
-Note that these interfaces are decorators which add {\em on the fly}
-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 \ccc{Polyhedron_ex}
-class in \ccc{polyhedron_ex_parameterization.C} example.
-
 
 \subsection{Default Parameterization Example}
 
 \ccc{Simple_parameterization.C} applies the default parameterization to a
-\ccc{Polyhedron_3} mesh (must be a topological disk).
+\ccc{CGAL::Polyhedron_3<Traits>} mesh (must be a topological disk).
 Eventually, it extracts the result from halfedges and prints it.
 
 \ccIncludeExampleCode{Surface_mesh_parameterization/Simple_parameterization.C}
 
 
+\subsection{Enhanced parameterize() function}
+
+This package provides a second \ccc{CGAL::parameterize()} entry point
+where the user can specify a parameterization method:
+
+\ccFunction{Parameterizer_traits_3<ParameterizationMesh_3>::Error_code parameterize (ParameterizationMesh_3 & mesh, ParameterizerTraits_3 parameterizer);}
+{
+Compute 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 \ccc{ParametizerTraits_3} algorithm.
+Preconditions:\begin{itemize}
+\item 'mesh' must be a surface with one connected component.\item 'mesh' must be a triangular mesh.\item the mesh border must be mapped onto a convex polygon (for fixed border parameterizations).\end{itemize}
+}
+
+
+\subsection{Introduction to the Package Concepts}
+
+\subsubsection{The ParameterizerTraits\_3 concept}
+
+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
+\ccc{ParameterizerTraits_3} concept.
+See Section \ref{sec:Surface-Parameterization-Methods}.
+
+Each of these surface parameterization methods is templated by
+the input mesh type, a border parameterization and a solver:
+
+% Insert image parameterizer_class_diagram_simplified.png/eps
+% with title "A parameterizer UML class diagram (simplified)"
+\begin{center}
+    \label{Surface_mesh_parameterization-fig-parameterizer_class_diagram_simplified}
+    % Image
+    \begin{ccTexOnly}
+        \includegraphics[width=0.80\textwidth]{Surface_mesh_parameterization/parameterizer_class_diagram_simplified} % omit .eps suffix
+    \end{ccTexOnly}
+    \begin{ccHtmlOnly}
+        <img width="80%" border=0 src="./parameterizer_class_diagram_simplified.png"><P>
+    \end{ccHtmlOnly}
+    % Title
+    \begin{figure}[h]
+        \caption{A parameterizer UML class diagram (simplified)}
+    \end{figure}
+\end{center}
+
+
+\subsubsection{The BorderParameterizer\_3 concept}
+
+Parameterization methods for
+borders are used as traits classes modifying the behavior of
+\ccc{ParameterizerTraits_3} models.
+They are provided as models of the \ccc{BorderParameterizer_3} concept.
+See Sections \ref{sec:Border-Parameterizations-for-Fixed-Methods}
+and \ref{sec:Border-Parameterizations-for-Free-Methods}.
+
+
+\subsubsection{The SparseLinearAlgebraTraits\_d concept}
+
+This package solves sparse linear systems using solvers which are models
+of \ccc{SparseLinearAlgebraTraits_d}.
+See Section \ref{sec:Sparse-Linear-Algebra}.
+
+
+\subsubsection{The ParameterizationMesh\_3 and ParameterizationPatchableMesh\_3 Concepts}
+
+We saw in Section \ref{sec:Input-Mesh-for-parameterize}
+that the input meshes handled by \ccc{CGAL::parameterize()}
+must be models of the \ccc{ParameterizationMesh_3} concept.
+
+We also saw that the surface parameterization methods in this package only support
+surfaces that are homeomorphic to disks. How about non disk-like meshes?
+
+\emph{In practice}, 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 cutting path (an oriented list of
+vertices) which is the border of a topological disc.  If no cutting path is
+given as input, we assume that the surface border is the longest border already
+in the input mesh (the other borders will be considered as holes).
+
+For this purpose, the
+\ccc{CGAL::Parameterization_mesh_patch_3<ParameterizationPatchableMesh_3>}
+class is responsible for \emph{virtually} cutting
+a patch in a \ccc{ParameterizationPatchableMesh_3} mesh.
+The resulting patch is a topological
+disk (if the input cutting path is correct)
+and provides a \ccc{ParameterizationMesh_3} interface. It can be used as
+parameter of \ccc{CGAL::parameterize()}.
+
+\ccc{ParameterizationPatchableMesh_3} inherits from \ccc{ParameterizationMesh_3},
+thus is a concept for a 3D surface mesh.
+\ccc{ParameterizationPatchableMesh_3} adds the ability to support patches and
+virtual seams. \emph{Patches} are a subset of a 3D mesh.
+\emph{Virtual seams} are the ability
+to behave exactly as if the surface was cut along a certain path.
+
+See more information in Section \ref{sec:Cutting-a-Mesh}.

Surface_mesh_parameterization/doc_tex/Surface_mesh_parameterization/complexity_and_guarantees.tex

@@ -0,0 +1,113 @@
+\section{Complexity and Guarantees}
+
+
+\subsection{Parameterization Methods and Guarantees}
+
+\begin{itemize}
+
+\item Fixed boundaries
+
+    \begin{itemize}
+
+    \item One-to-one mapping
+
+        Tutte's theorem guarantees a one-to-one mapping provided that the weights are positive.
+        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.
+
+    \item 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).
+
+    \end{itemize}
+
+\item Free boundaries
+
+    \begin{itemize}
+
+    \item One-to-one mapping
+
+        No guarantee can be given for LSCM (both global overlaps and triangle flips can
+        occur).
+
+    \item Non-singularity of the matrix
+
+        Proven for LSCM: the matrix of the system is the Gramm matrix of a matrix of maximal rank,
+        and is therefore non-singular (Gramm theorem).
+
+    \item Non-singularity of the matrix
+
+    \end{itemize}
+
+\end{itemize}
+
+
+\subsection{Precision}
+
+Only a few algorithms of this package construct the sparse linear system(s)
+using trigonometric functions, incompatible with an exact arithmetic:
+
+\begin{itemize}
+
+\item Floater Mean Value Coordinates
+
+\item Circular border parameterization
+
+\end{itemize}
+
+On the other hand, linear solvers commonly use double precision floating point
+numbers. \\
+OpenNL's BICGSTAB solver (accessible though the
+\ccc{OpenNL::DefaultLinearSolverTraits<COEFFTYPE, MATRIX, VECTOR, SOLVER>} interface)
+is the only solver supported by this package that
+computes an exact results (when used with an exact arithmetic).
+
+Therefore, this package is intended to be used with a \cgal\
+cartesian kernel with doubles.
+
+
+\subsubsection{OpenNL's BICGSTAB Solver with an Exact Arithmetic}
+
+The BICGSTAB conjugate gradient is in fact a direct solver.
+In a nutshell, it computes a vector basis
+orthogonal with respect to the matrix, and the coordinates of the solution in this vector basis.
+Each iteration computes one component of the basis and one coordinate, therefore the algorithm
+converges to the solution in $n$ iterations, where $n$ is the dimension of the matrix.
+In fact, it can be even less than $n$, it converges in $k$ iteration, where $k$ is the number
+of distinct eigenvalues of the matrix. \\
+\emph{Note:} for a perfectly conditioned matrix, it converges in one iteration!
+
+
+\subsubsection{Solvers with a Floating Point Arithmetic}
+
+\emph{OpenNL's BICGSTAB example:}
+
+When inexact numerical types are used (e.g. doubles), accumulated errors slow down convergence
+(in practice, it requires approximately $5k$ iterations to converge).
+The required number of iterations depends on the eigenvalues of the matrix, and these eigenvalues depend
+on the shape of the triangles. The optimum is when the triangles are equilateral (then the solver converges
+in less than 10 iterations). The worst case is obtained when the mesh has a large number of skinny triangles (near-singular Jacobian matrix of the triangle). In this case, the spectrum of the matrix
+is wide (many different eigenvalues), and the solver requires nearly $5n$ iterations to converge.
+
+
+\subsection{Algorithmic Complexity}
+
+In this package, we focus on piecewise linear mappings onto a planar
+domain. All surface parameterization methods are based on solving one (or two)
+sparse linear system(s).
+
+The algorithmic complexity is dominated by the resolution of the sparse linear system(s).
+
+\emph{OpenNL's BICGSTAB example:}
+
+At each iteration, the operation of highest complexity is the sparse-matrix x vector product.
+The sparse matrix has a fixed number of non-zero coefficients per row,
+therefore the sparse-matrix x vector product has $O(n)$ complexity.
+Since convergence is reached after $k$ iterations, the complexity is $O(k.n)$
+(where $k$ is the number of distinct eigenvalues of the matrix).
+Therefore, best case complexity is $O(n)$ (equilateral triangles),
+and worst case complexity is $O(n^2)$ (skinny triangles).
+

Surface_mesh_parameterization/doc_tex/Surface_mesh_parameterization/extensions_and_reuse.tex

@@ -3,8 +3,13 @@
 \subsection{Reusing Mesh Adaptors}
 
 \ccc{ParameterizationMesh_3} defines a concept to access to a
-general polyhedral mesh.  The current interface is optimized for the
+general polyhedral mesh.
-\ccc{Surface_mesh_parameterization} package, but may be easily generalized.
+It is optimized for the \ccc{Surface_mesh_parameterization} package
+only in the sense that it
+defines the accessors to fields specific to the parameterization domain
+(\ccc{index}, \ccc{u}, \ccc{v}, \ccc{is_parameterized}).
+
+It may be easily generalized.
 
 
 \subsection{Reusing Sparse Linear Algebra}
@@ -12,24 +17,24 @@ general polyhedral mesh.  The current interface is optimized for the
 The \ccc{SparseLinearAlgebraTraits_d} concept and the traits classes
 for OpenNL and {\sc Taucs} are independent of the rest of the
 \ccc{Surface_mesh_parameterization} package, and may be reused by
-CGAL developers for other purposes.
+\cgal\ developers for other purposes.
 
 
 \subsection{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
-\ccc{Fixed_border_parameterizer_3<ParameterizationMesh_3, BorderParameterizer_3, SparseLinearAlgebraTraits_d>}
+\ccc{CGAL::Fixed_border_parameterizer_3<ParameterizationMesh_3, BorderParameterizer_3, SparseLinearAlgebraTraits_d>}
 class.  Subclasses must mainly
 implement a \ccc{compute_w_ij}() method which computes each
-coefficient $w_{ij}$ = (i,j) of a matrix $A$ for $v_j$ neighbouring
+$w_{ij}$ = $(i, j)$ coefficient of the matrix $A$ for $v_j$ neighboring
 vertices of $v_i$.
 
 Although implementing a new free border linear parameterization
 method is more challenging, the Least Squares Conformal Maps
-parameterization method is a good starting point.
+parameterization method provides a good starting point.
 
-Implementing \ccc{non} linear parameterizations is a natural extension
+Implementing \emph{non} linear parameterizations is a natural extension
 to this package, although only the mesh adaptors can be reused.
 
 
@@ -44,4 +49,4 @@ Square, circular and two-points border parameterizations are good starting point
 Obviously, this package would benefit of having robust algorithms
 which transform arbitrary meshes into topological disks.
 
-% references ?
+% pierre : references ?

Surface_mesh_parameterization/doc_tex/Surface_mesh_parameterization/introduction.tex

@@ -20,11 +20,11 @@ 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
+minimize (angles vs. areas), by the constrained border onto the
-planar domain (convex polygon vs free border) and by the guarantees
+planar domain (convex polygon vs. free border) and by the guarantees
 provided in terms of bijective mapping.
 
-The package proposes currently an interface with \cgal\ \ccc{Polyhedron_3}
+The package proposes currently an interface with \ccc{CGAL::Polyhedron_3<Traits>}
 data structure.
 
 Since parameterizing meshes require efficient representation of sparse
@@ -34,7 +34,7 @@ and propose a separate package devoted to OpenNL sparse
 linear solver.
 
 Note that linear solvers commonly use double precision floating point
-numbers. This package is thus intended to be used with a \cgal\
+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
@@ -42,7 +42,8 @@ students developing algorithms around parameterization of triangle
 meshes for geometry processing as well as for signal mapping on
 triangulated surfaces.
 
-% Insert image introduction.png/eps with title "Least Squares Conformal Maps parameterization"
+% Insert image introduction.png/eps
+% with title "Julius Cesar mask textured by Least Squares Conformal Maps parameterization"
 \begin{center}
     \label{Surface_mesh_parameterization-fig-introduction}
     % Image
@@ -54,7 +55,7 @@ triangulated surfaces.
     \end{ccHtmlOnly}
     % Title
     \begin{figure}[h]
-        \caption{Least Squares Conformal Maps parameterization}
+        \caption{Julius Cesar mask textured by Least Squares Conformal Maps parameterization}
     \end{figure}
 \end{center}
 

Surface_mesh_parameterization/doc_tex/Surface_mesh_parameterization/main.tex

@@ -10,5 +10,6 @@
 \input{Surface_mesh_parameterization/solvers}
 \input{Surface_mesh_parameterization/seam}
 \input{Surface_mesh_parameterization/output}
+\input{Surface_mesh_parameterization/complexity_and_guarantees}
 \input{Surface_mesh_parameterization/software_design}
 \input{Surface_mesh_parameterization/extensions_and_reuse}

Surface_mesh_parameterization/doc_tex/Surface_mesh_parameterization/output.tex

@@ -2,17 +2,17 @@
 
 Parameterization methods compute $(u,v)$ fields for each vertex
 of the input mesh, with the seam vertices being virtually duplicated (thanks
-to \ccc{Parameterization_mesh_patch_3<ParameterizationPatchableMesh_3>}).
+to \ccc{CGAL::Parameterization_mesh_patch_3<ParameterizationPatchableMesh_3>}).
 
 To support this duplication,
-\ccc{Parameterization_polyhedron_adaptor_3<Polyhedron_3_>} stores
+\ccc{CGAL::Parameterization_polyhedron_adaptor_3<Polyhedron_3_>} stores
 the result in the $(u,v)$ fields of the input mesh halfedges.
 A $(u,v)$ pair is provided for
 each inner vertex (i.e. its halfedges share the same $(u,v)$ pair),
-while a $(u,v)$ pair is provided for each seam halfedge.
+while a $(u,v)$ pair is provided for each border halfedge.
 The user has to iterate over the mesh halfedges to get the result.
 
-Note: $(u,v)$ fields do not exist in CGAL \ccc{Polyhedron_3},
+Note: $(u,v)$ fields do not exist in \ccc{CGAL::Polyhedron_3<Traits>},
 thus the output traversal is specific to the way the (u,v) fields are implemented by the adaptor.
 
 \subsection{EPS Output Example}
@@ -20,8 +20,8 @@ thus the output traversal is specific to the way the (u,v) fields are implemente
 \ccc{Complete_parameterization_example.C} is a complete parameterization
 example that outputs the result as an EPS image.
 It gets the $(u,v)$ fields computed by a
-parameterization method over a \ccc{Polyhedron_3} mesh with a
+parameterization method over a \ccc{CGAL::Polyhedron_3<Traits>} mesh with a
-\ccc{Parameterization_polyhedron_adaptor_3<Polyhedron_3_>} adaptor:
+\ccc{CGAL::Parameterization_polyhedron_adaptor_3<Polyhedron_3_>} adaptor:
 
 \ccIncludeExampleCode{Surface_mesh_parameterization/Complete_parameterization_example.C}
 

Surface_mesh_parameterization/doc_tex/Surface_mesh_parameterization/parameterization_methods.tex

@@ -1,23 +1,12 @@
 \section{Surface Parameterization Methods}
+\label{sec:Surface-Parameterization-Methods}
 
-
+This \cgal\ package implements some of the state-of-the-art
-This package provides a second \ccc{parameterize()} entry point
+surface parameterization methods, such as Least Squares Conformal Maps,
-where the user can specify a parameterization method:
+Discrete Conformal Map, Discrete Authalic
-
+Parameterization, Floater Mean Value Coordinates or Tutte Barycentric
-\ccFunction{Parameterizer_traits_3<ParameterizationMesh_3>::Error_code parameterize (ParameterizationMesh_3 & mesh, ParameterizerTraits_3 parameterizer);}
+Mapping. These methods are provided as models of the
-{
+\ccc{ParameterizerTraits_3} concept.
-Compute 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 \ccc{ParametizerTraits_3} algorithm.
-Preconditions:\begin{itemize}
-\item 'mesh' must be a surface with one connected component.\item 'mesh' must be a triangular mesh.\item the mesh border must be mapped onto a convex polygon (for fixed border parameterizations).\end{itemize}
-}
-
-
-This \cgal\ package implements some of the state-of-the-art surface
-parameterization methods which can be used as
-\ccc{ParameterizerTraits_3} parameter. This package also provides common parameterization methods for
-borders which are used as traits classes modifying the behavior of
-the \ccc{ParameterizerTraits_3} methods.
 
 
 \subsection{Fixed Border Surface Parameterizations}
@@ -26,8 +15,8 @@ the \ccc{ParameterizerTraits_3} methods.
 % laurent: Andreas asked to replace boundary by border everywhere...
 
 Fixed Border Surface Parameterizations need a set of constraints: two
-u,v coordinates for each vertex along the border. Some helper
+(u,v) coordinates for each vertex along the border.
-classes to achieve this goal are described in Section
+Such border parameterizations are described in Section
 \ref{sec:Border-Parameterizations-for-Fixed-Methods}.
 
 \subsubsection{Tutte Barycentric Mapping}
@@ -37,14 +26,26 @@ classes to achieve this goal are described in Section
 The Barycentric Mapping parameterization method has been introduced by
 Tutte~\cite{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 amounts to solve one
+convex combination condition.
+
+\emph{Complexity:}
+
+This amounts to solve one
 sparse linear solver for each set of parameter coordinates, with a
 \#vertices x \#vertices sparse and symmetric positive definite matrix.
 A coefficient $(i, j)$ of the matrix is set to 1 for an edge linking
 the vertex $v_i$ to the vertex $v_j$, to minus the degree of the
 vertex $v_i$ for a diagonal element, and to 0 for any other matrix
-entry. Although Tutte Barycentric Mapping method is fast and
+entry.
-guaranteed to be bijective, it does not minimize angle nor area
+
+\emph{Guarantees:}
+
+Always bijective when the border is convex.
+
+\emph{Usage:}
+
+Although Tutte Barycentric Mapping method is fast and
+guaranteed to be bijective, it does not minimize angles nor areas
 distortion.
 
 % Insert image uniform.png/eps with
@@ -53,10 +54,10 @@ distortion.
     \label{Surface_mesh_parameterization-fig-uniform}
     % Image
     \begin{ccTexOnly}
-        \includegraphics[width=0.5\textwidth]{Surface_mesh_parameterization/uniform} % omit .eps suffix
+        \includegraphics[width=0.45\textwidth]{Surface_mesh_parameterization/uniform}
     \end{ccTexOnly}
     \begin{ccHtmlOnly}
-        <img width="50%" border=0 src="./uniform.png"><P>
+        <img width="45%" border=0 src="./uniform.png"><P>
     \end{ccHtmlOnly}
     % Title
     \begin{figure}[h]
@@ -64,41 +65,66 @@ distortion.
     \end{figure}
 \end{center}
 
+% Insert image uniform_2.png/eps with title "Teapot's image with Tutte Barycentric Mapping"
+\begin{center}
+    \label{Surface_mesh_parameterization-fig-uniform_2}
+    % Image
+    \begin{ccTexOnly}
+        \includegraphics[width=0.45\textwidth]{Surface_mesh_parameterization/uniform_2}
+    \end{ccTexOnly}
+    \begin{ccHtmlOnly}
+        <img width="45%" border=0 src="./uniform_2.png"><P>
+    \end{ccHtmlOnly}
+    % Title
+    \begin{figure}[h]
+        \caption{Teapot's image with Tutte Barycentric Mapping}
+    \end{figure}
+\end{center}
+
 
 \subsubsection{Discrete Conformal Map}
 
 \ccc{CGAL::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~\cite{cgal:eddhls-maam-95}. It attempts to
+al. to the graphics community~\cite{cgal:eddhls-maam-95}.
+
+\emph{Usage:}
+
+It attempts to
 lower angle deformation by minimizing a discrete version of the
 Dirichlet energy as derived by Pinkall and
 Polthier~\cite{cgal:fh-survey-05}.
+In practice, this gives visually nice results.
 
 % pierre: fix references
 
+\emph{Guarantees:}
+
 A one-to-one mapping is guaranteed only when two conditions are
 fulfilled: the barycentric mapping condition (each vertex in parameter
-space is a convex combination if its neighbouring vertices) and the
+space is a convex combination if its neighboring vertices) and the
 border is convex.
 
 % pierre: add cot figure, and detail what it means to have all weights
 % positive, otherwise it is confusing.
 
+\emph{Complexity:}
+
 This method solves two \#vertices x \#vertices sparse linear
 systems. The matrix (the same for both systems) is symmetric definite
 positive, thus can be efficiently solved using dedicated linear
-solvers (x s for the example shown).
+solvers.
 
 % Insert image conformal.png/eps with title "Discrete Conformal Map"
 \begin{center}
     \label{Surface_mesh_parameterization-fig-conformal}
     % Image
     \begin{ccTexOnly}
-        \includegraphics[width=0.5\textwidth]{Surface_mesh_parameterization/conformal} % omit .eps suffix
+        \includegraphics[width=0.45\textwidth]{Surface_mesh_parameterization/conformal}
     \end{ccTexOnly}
     \begin{ccHtmlOnly}
-        <img width="50%" border=0 src="./conformal.png"><P>
+        <img width="45%" border=0 src="./conformal.png"><P>
     \end{ccHtmlOnly}
     % Title
     \begin{figure}[h]
@@ -106,6 +132,22 @@ solvers (x s for the example shown).
     \end{figure}
 \end{center}
 
+% Insert image conformal_2.png/eps with title "Teapot's image with Discrete Conformal Map"
+\begin{center}
+    \label{Surface_mesh_parameterization-fig-conformal_2}
+    % Image
+    \begin{ccTexOnly}
+        \includegraphics[width=0.45\textwidth]{Surface_mesh_parameterization/conformal_2}
+    \end{ccTexOnly}
+    \begin{ccHtmlOnly}
+        <img width="45%" border=0 src="./conformal_2.png"><P>
+    \end{ccHtmlOnly}
+    % Title
+    \begin{figure}[h]
+        \caption{Teapot's image with Discrete Conformal Map}
+    \end{figure}
+\end{center}
+
 
 \subsubsection{Floater Mean Value Coordinates}
 
@@ -113,11 +155,23 @@ solvers (x s for the example shown).
 
 The Mean Value Coordinates parameterization method has been introduced
 by Floater~\cite{cgal:f-mvc-03}. Each vertex in parameter space is
-optimized so as to be a convex combination of its neighbouring
+optimized so as to be a convex combination of its neighboring
-vertices. The barycentric coordinates are this time unconditionnaly
+vertices. The barycentric coordinates are this time unconditionally
 positive, by deriving an application of the mean theorem for harmonic
-functions. It is in essence an approximation of the Discrete Conformal
+functions.
-Maps, with a one-to-one mapping always guaranteed. This method solves
+
+\emph{Usage:}
+
+It is in essence an approximation of the Discrete Conformal
+Maps, with a one-to-one mapping always guaranteed.
+
+\emph{Guarantees:}
+
+Always bijective when the border is convex.
+
+\emph{Complexity:}
+
+This method solves
 two \#vertices x \#vertices sparse linear systems. The matrix (the
 same for both systems) is asymmetric.
 
@@ -126,10 +180,10 @@ same for both systems) is asymmetric.
     \label{Surface_mesh_parameterization-fig-floater}
     % Image
     \begin{ccTexOnly}
-        \includegraphics[width=0.5\textwidth]{Surface_mesh_parameterization/floater} % omit .eps suffix
+        \includegraphics[width=0.45\textwidth]{Surface_mesh_parameterization/floater}
     \end{ccTexOnly}
     \begin{ccHtmlOnly}
-        <img width="50%" border=0 src="./floater.png"><P>
+        <img width="45%" border=0 src="./floater.png"><P>
     \end{ccHtmlOnly}
     % Title
     \begin{figure}[h]
@@ -137,17 +191,45 @@ same for both systems) is asymmetric.
     \end{figure}
 \end{center}
 
+% Insert image floater_2.png/eps with title "Teapot's image with Floater Mean Value Coordinates"
+\begin{center}
+    \label{Surface_mesh_parameterization-fig-floater_2}
+    % Image
+    \begin{ccTexOnly}
+        \includegraphics[width=0.45\textwidth]{Surface_mesh_parameterization/floater_2}
+    \end{ccTexOnly}
+    \begin{ccHtmlOnly}
+        <img width="45%" border=0 src="./floater_2.png"><P>
+    \end{ccHtmlOnly}
+    % Title
+    \begin{figure}[h]
+        \caption{Teapot's image with Floater Mean Value Coordinates}
+    \end{figure}
+\end{center}
+
 
 \subsubsection{Discrete Authalic parameterization}
 
 \ccc{CGAL::Discrete_authalic_parameterizer_3<ParameterizationMesh_3, BorderParameterizer_3, SparseLinearAlgebraTraits_d>}  \\
 
 The Discrete Authalic parameterization method has been introduced by
-Desbrun, Meyer and Alliez~\cite{cgal:dma-ipsm-02}.  It corresponds to
+Desbrun, Meyer and Alliez~\cite{cgal:dma-ipsm-02}.
+
+\emph{Usage:}
+
+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
+locally minimizes the area distortion.
+
+\emph{Guarantees:}
+
+A one-to-one mapping is
 guaranteed only if the convex combination condition is fulfilled and
-the border is convex.  This method solves two
+the border is convex.
+
+\emph{Complexity:}
+
+ This method solves two
 \#vertices x \#vertices sparse linear systems. The matrix (the same
 for both systems) is asymmetric.
 
@@ -156,10 +238,10 @@ for both systems) is asymmetric.
     \label{Surface_mesh_parameterization-fig-authalic}
     % Image
     \begin{ccTexOnly}
-        \includegraphics[width=0.5\textwidth]{Surface_mesh_parameterization/authalic} % omit .eps suffix
+        \includegraphics[width=0.45\textwidth]{Surface_mesh_parameterization/authalic}
     \end{ccTexOnly}
     \begin{ccHtmlOnly}
-        <img width="50%" border=0 src="./authalic.png"><P>
+        <img width="45%" border=0 src="./authalic.png"><P>
     \end{ccHtmlOnly}
     % Title
     \begin{figure}[h]
@@ -167,38 +249,98 @@ for both systems) is asymmetric.
     \end{figure}
 \end{center}
 
+% Insert image authalic_2.png/eps with title "Teapot's image with Discrete Authalic Parameterization"
+\begin{center}
+    \label{Surface_mesh_parameterization-fig-authalic_2}
+    % Image
+    \begin{ccTexOnly}
+        \includegraphics[width=0.45\textwidth]{Surface_mesh_parameterization/authalic_2}
+    \end{ccTexOnly}
+    \begin{ccHtmlOnly}
+        <img width="45%" border=0 src="./authalic_2.png"><P>
+    \end{ccHtmlOnly}
+    % Title
+    \begin{figure}[h]
+        \caption{Teapot's image with Discrete Authalic Parameterization}
+    \end{figure}
+\end{center}
+
 
 \subsubsection{Border Parameterizations for Fixed Methods}
 \label{sec:Border-Parameterizations-for-Fixed-Methods}
 
+Parameterization methods for
+borders are used as traits classes modifying the behavior of
+\ccc{ParameterizerTraits_3} models.
+They are provided as models of the \ccc{BorderParameterizer_3} concept.
+
 Border Parameterizations for Fixed Border Surface Parameterizations
 are a family of methods to define a set of constraints, namely two
 $u,v$ coordinates for each vertex along the border.
 
 \begin{itemize}
 
-\item The user can select a border parameterization among
+\item
-two commonly used methods: uniform or arc-length parameterization, the
+    The user can select a border parameterization among
-arc-length parameterization being used by default.
+    two commonly used methods: uniform or arc-length parameterization.
 
-\item One convex shape specified by:
+    \emph{Usage:}
 
-    \begin{itemize}
+    Uniform border parameterization is more stable, although it gives
+    poor visual results. The
+    arc-length border parameterization is used by default.
+
+\item
+    One convex shape specified by one shape among two standard ones:
+    a circle or a square.
+
+    \emph{Usage:}
 
-    \item one shape among two standard ones: a circle or a square.
     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.
 
 \end{itemize}
 
-\end{itemize}
-
 \ccc{CGAL::Circular_border_arc_length_parameterizer_3<ParameterizationMesh_3>}  \\
 \ccc{CGAL::Circular_border_uniform_parameterizer_3<ParameterizationMesh_3>}  \\
 \ccc{CGAL::Square_border_arc_length_parameterizer_3<ParameterizationMesh_3>}  \\
 \ccc{CGAL::Square_border_uniform_parameterizer_3<ParameterizationMesh_3>}  \\
 
+% Insert image circular_border.png/eps
+% with title "Julius Cesar mask's image with Authalic/circular border"
+\begin{center}
+    \label{Surface_mesh_parameterization-fig-circular_border}
+    % Image
+    \begin{ccTexOnly}
+        \includegraphics[width=0.35\textwidth]{Surface_mesh_parameterization/circular_border}
+    \end{ccTexOnly}
+    \begin{ccHtmlOnly}
+        <img width="35%" border=0 src="./circular_border.png"><P>
+    \end{ccHtmlOnly}
+    % Title
+    \begin{figure}[h]
+        \caption{Julius Cesar mask's image with Authalic/circular border}
+    \end{figure}
+\end{center}
+
+% Insert image square_border.png/eps
+% with title "Julius Cesar mask's image with Floater/square border"
+\begin{center}
+    \label{Surface_mesh_parameterization-fig-square_border}
+    % Image
+    \begin{ccTexOnly}
+        \includegraphics[width=0.35\textwidth]{Surface_mesh_parameterization/square_border}
+    \end{ccTexOnly}
+    \begin{ccHtmlOnly}
+        <img width="35%" border=0 src="./square_border.png"><P>
+    \end{ccHtmlOnly}
+    % Title
+    \begin{figure}[h]
+        \caption{Julius Cesar mask's image with Floater/square border}
+    \end{figure}
+\end{center}
+
 
 \subsection{Free Border Surface Parameterizations}
 
@@ -207,22 +349,34 @@ arc-length parameterization being used by default.
 \ccc{CGAL::LSCM_parameterizer_3<ParameterizationMesh_3, BorderParameterizer_3, SparseLinearAlgebraTraits_d>}  \\
 
 The Least Squares Conformal Maps (LSCM) parameterization method has
-been introduced by L\'evy et al.~\cite{cgal:lprm-lscm-02}. It
+been introduced by L\'evy et al.~\cite{cgal:lprm-lscm-02}.
-corresponds to a conformal method with a free border (at least two
+
+\emph{Usage:}
+
+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
+allows further lowering of the angle distortion.
-is not guaranteed by this method. It solves a (2 $\times$
+
-\#triangles) $\times$ \#vertices sparse linear system in the least squares sense.
+\emph{Guarantees:}
+
+A one-to-one mapping
+is not guaranteed by this method.
+
+\emph{Complexity:}
+
+It solves a (2 $\times$
+\#triangles) $\times$ \#vertices sparse linear system in the least squares sense,
+which implies to solve a symmetric matrix.
 
 % Insert image LSCM.png/eps with title "Least Squares Conformal Maps"
 \begin{center}
     \label{Surface_mesh_parameterization-fig-LSCM}
     % Image
     \begin{ccTexOnly}
-        \includegraphics[width=0.5\textwidth]{Surface_mesh_parameterization/LSCM} % omit .eps suffix
+        \includegraphics[width=0.45\textwidth]{Surface_mesh_parameterization/LSCM}
     \end{ccTexOnly}
     \begin{ccHtmlOnly}
-        <img width="50%" border=0 src="./LSCM.png"><P>
+        <img width="45%" border=0 src="./LSCM.png"><P>
     \end{ccHtmlOnly}
     % Title
     \begin{figure}[h]
@@ -230,19 +384,54 @@ is not guaranteed by this method. It solves a (2 $\times$
     \end{figure}
 \end{center}
 
+% Insert image LSCM_2.png/eps with title "Teapot's image with Least Squares Conformal Maps"
+\begin{center}
+    \label{Surface_mesh_parameterization-fig-LSCM_2}
+    % Image
+    \begin{ccTexOnly}
+        \includegraphics[width=0.75\textwidth]{Surface_mesh_parameterization/LSCM_2}
+    \end{ccTexOnly}
+    \begin{ccHtmlOnly}
+        <img width="75%" border=0 src="./LSCM_2.png"><P>
+    \end{ccHtmlOnly}
+    % Title
+    \begin{figure}[h]
+        \caption{Teapot's image with Least Squares Conformal Maps}
+    \end{figure}
+\end{center}
+
 
 \subsubsection{Border Parameterizations for Free Methods}
+\label{sec:Border-Parameterizations-for-Free-Methods}
 
+Parameterization methods for
+borders are used as traits classes modifying the behavior of
+\ccc{ParameterizerTraits_3} models.
+They are provided as models of the \ccc{BorderParameterizer_3} concept.
+
+The border parameterizations associated to Free Border Surface
+Parameterization methods define only two constraints
+(the pinned vertices). 
+
+\begin{itemize}
+
+\item
     \ccc{CGAL::Two_vertices_parameterizer_3<ParameterizationMesh_3>}  \\
 
-The associated Border Parameterization method defines only two constraints
+    \emph{Usage:}
-(the pinned vertices). They have to be on the specified border.
+
+    \ccc{CGAL::Two_vertices_parameterizer_3<ParameterizationMesh_3>} is the default
+    free border parameterization (and in fact the only one available
+    in the package today).
+
+\end{itemize}
 
 
 \subsection{Discrete Authalic Parameterization Example}
 
 \ccc{Authalic_parameterization.C} computes a Discrete Authalic parameterization
-over a \ccc{Polyhedron_3} mesh. 
+over a \ccc{CGAL::Polyhedron_3<Traits>} mesh. Specifying a specific surface parameterization
+instead of the default one means using the second parameter of \ccc{CGAL::parameterize()}.
 
 The differences with the first example \ccc{Simple_parameterization.C} are:
 
@@ -270,6 +459,9 @@ Parameterizer::Error_code err = CGAL::parameterize(mesh_adaptor, Parameterizer()
 
 \ccc{Square_border_parameterization.C} computes 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
+\ccc{CGAL::Mean_value_coordinates_parameterizer_3<ParameterizationMesh_3, BorderParameterizer_3, SparseLinearAlgebraTraits_d>}.
 
 The differences with the first example \ccc{Simple_parameterization.C} are:
 

Surface_mesh_parameterization/doc_tex/Surface_mesh_parameterization/seam.tex

@@ -1,54 +1,84 @@
 \section{Cutting a Mesh}
+\label{sec:Cutting-a-Mesh}
 
-\subsection{Computing a Cut}
+\subsection{Computing a Cutting Path}
 
 All surface parameterization methods proposed in this package only
-deal with topological discs.  The input mesh can be of any genus and
+deal with topological discs (from a mathematical point of view).
-have any number of connected components, but if it is not a topological
+
-disc, it has to come with a description of a border (an oriented list of
+Fortunately, the meshes supported by the package can be of any genus and
-vertices) which is the border of a topological disc.  If no border  is
+have any number of connected components. If it is not a topological
+disc, the input mesh has to come with a description of a cutting path (an oriented list of
+vertices) which is the border of a topological disc.  If no cutting path is
 given as input, we assume that the surface border is the longest border already
-in the input mesh (the other borders will be considered as holes).
+in the input mesh (the other borders will be considered as holes). \\
+Note: the package will only parameterize the inside part of the given border,
+thus only one connected component.
 
 % pierre: big contradiction here - it can be something else than a
 % disk then!
 
+% Insert image cut.png/eps with title "Cutting Path"
+\begin{center}
+    \label{Surface_mesh_parameterization-fig-cut}
+    % Image
+    \begin{ccTexOnly}
+        \includegraphics[width=0.4\textwidth]{Surface_mesh_parameterization/cut} % omit .eps suffix
+    \end{ccTexOnly}
+    \begin{ccHtmlOnly}
+        <img width="40%" border=0 src="./cut.png"><P>
+    \end{ccHtmlOnly}
+    % Title
+    \begin{figure}[h]
+        \caption{Cutting Path}
+    \end{figure}
+\end{center}
+
 This package does not provide any algorithm to transform a closed mesh
 of arbitrary genus into a topological disk, the user being responsible
-for computing such a cut. Nevertheless we provide in
+for computing such a cutting path. Nevertheless, we provide in
 \ccc{polyhedron_ex_parameterization.C} a simple cutting algorithm for
 the sake of completeness.
 
 
 \subsection{Applying a Cut}
 
-Parameterization methods in this package only support triangulated
+The surface parameterization classes in this package only support
-surfaces that are homeomorphic to a disk (models of
+\emph{directly} surfaces that are homeomorphic to a disk (models of
 \ccc{ParameterizationMesh_3}). This software design simplifies the
-implementation of all new parameterization methods based on linear
+implementation of all new parameterization methods.
-solvers.
 
-\ccc{Parameterization_mesh_patch_3<ParameterizationPatchableMesh_3>}
+The \ccc{CGAL::Parameterization_mesh_patch_3<ParameterizationPatchableMesh_3>}
-class is responsible for virtually
+class is responsible for \emph{virtually} cutting
-{\em cutting} a patch to a \ccc{ParameterizationPatchableMesh_3} mesh,
+a patch in a \ccc{ParameterizationPatchableMesh_3} mesh.
-to make it similar (from the interface point of view) to a topological
+The resulting patch is a topological
-disk with a \ccc{ParameterizationMesh_3} interface.
+disk (if the input cutting path is correct)
+and provides a \ccc{ParameterizationMesh_3} interface. It can be used as
+parameter of \ccc{CGAL::parameterize()}.
 
 \ccc{ParameterizationPatchableMesh_3} inherits from concept \ccc{ParameterizationMesh_3},
 thus is a concept for a 3D surface mesh.
 \ccc{ParameterizationPatchableMesh_3} adds the ability to support patches and
-virtual seams. Patches are a subset of a 3D mesh. Virtual seams are the ability
+virtual seams. \emph{Patches} are a subset of a 3D mesh.
-to behave exactly as if the surface was {\em cut} following a certain path.
+\emph{Virtual seams} are the ability
+to behave exactly as if the surface was cut along a certain path.
 
-The \ccc{ParameterizationMesh_3} interface with the Polyhedron is also model of
+The \ccc{ParameterizationMesh_3} interface with the Polyhedron is both a model of
-\ccc{ParameterizationPatchableMesh_3}:
+\ccc{ParameterizationMesh_3} and \ccc{ParameterizationPatchableMesh_3}:
 
 \ccc{CGAL::Parameterization_polyhedron_adaptor_3<Polyhedron_3_>}  \\
 
+Note that this class is a decorator which adds {\em on the fly}
+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 \ccc{Polyhedron_ex}
+class in \ccc{polyhedron_ex_parameterization.C} example.
+
 
 \subsection{Cutting a Mesh Example}
 
-\ccc{Mesh_cutting_parameterization.C} virtually {\em cuts} a \ccc{Polyhedron_3} mesh
+\ccc{Mesh_cutting_parameterization.C} \emph{virtually} cuts a
+\ccc{CGAL::Polyhedron_3<Traits>} mesh
 to make it a topological disk, then applies the default parameterization:
 
 \ccIncludeExampleCode{Surface_mesh_parameterization/Mesh_cutting_parameterization.C}

Surface_mesh_parameterization/doc_tex/Surface_mesh_parameterization/software_design.tex

@@ -5,14 +5,9 @@
 This package's entry point is:
 
 \begin{ccExampleCode}
-
 // 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.
-//
-// The mapping is piecewise linear on the input mesh triangles.
-// The result is a (u,v) pair of parameter coordinates for each vertex of the input mesh.
-//
 template <class ParameterizationMesh_3>
 typename Parameterizer_traits_3<ParameterizationMesh_3>::Error_code
 parameterize(ParameterizationMesh_3& mesh)  // 3D mesh, model of ParameterizationMesh_3 concept
@@ -24,12 +19,8 @@ parameterize(ParameterizationMesh_3& mesh)  // 3D mesh, model of Parameterizatio
 
 // Compute 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.
+// One-to-one mapping may be guaranteed or not,
-// The result is a pair (u,v) of parameter coordinates for each vertex of the input mesh.
+// depending on the chosen ParametizerTraits_3 algorithm.
-//
-// 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
@@ -37,30 +28,29 @@ parameterize(ParameterizationMesh_3& mesh,          // 3D mesh, model of Paramet
 {
     return parameterizer.parameterize(mesh);
 }
-
 \end{ccExampleCode}
 
 You may notice that these global functions simply call the
 parameterize() method of a \ccc{ParameterizerTraits_3} object.
 The purpose of these global functions is:
 \begin{itemize}
-\item to be consistent with other CGAL algorithms that are also provided as
+\item to be consistent with other \cgal\ algorithms that are also provided as
-      global functions, e.g. \ccc{convex_hull_2}()
+      global functions, e.g. \ccc{CGAL::convex_hull_2()},
 \item to provide a default parameterization method (Floater Mean Value Coordinates),
-      which wouldn't be possible with a direct call to an object's method
+      which wouldn't be possible with a direct call to an object's method.
 \end{itemize}
 
-You may also wonder why there is not just one parameterize() function with a
+You may also wonder why there is not just one \ccc{CGAL::parameterize()} function 
-default \ccc{ParameterizerTraits_3} argument equal to
+with a default \ccc{ParameterizerTraits_3} argument equal to
-\ccc{Mean_value_coordinates_parameterizer_3<ParameterizationMesh_3>}.
+\ccc{CGAL::Mean_value_coordinates_parameterizer_3<ParameterizationMesh_3>}.
 The reason is simply that this is not allowed by the C++ standard (see
 \cite{cgal:ansi-is14882-98}, paragraph 14.1/9).
 
 
-\subsection{ParameterizerTraits\_3 is not really a Traits Class}
+\subsection{No Common Parameterization Algorithm}
 
 \ccc{ParameterizerTraits_3} models modify the behavior of the global function
-\ccc{parameterize}() - hence the {\em Traits} in the name.
+\ccc{CGAL::parameterize()} - hence the {\em Traits} in the name.
 On the other hand, \ccc{ParameterizerTraits_3} models do not modify the behavior
 of a common parameterization algorithm - as you might expect.
 
@@ -69,9 +59,9 @@ disk and on piecewise linear mappings into a planar domain.
 A consequence is that the skeleton of all parameterization methods of this
 package is the same:
 \begin{itemize}
-\item Allocate a sparse linear system A*X = B
+\item Allocate a sparse linear system $A.X = B$
-\item Parameterize the mesh border and initialize B
+\item Parameterize the mesh border and initialize $B$
-\item Parameterize the inner points of the mesh and set A coefficients
+\item Parameterize the inner points of the mesh and set $A$ coefficients
 \item Solve the system
 \end{itemize}
 
@@ -81,16 +71,16 @@ modifies the behavior of a common parameterization algorithm.
 On the other hand, there are several differences among methods:
 \begin{itemize}
 \item Fixed border methods need to parameterize all border vertices,
-      when free border methods parameterize only two vertices
+      when free border methods parameterize only two vertices.
 \item Some methods create symmetric definite positive systems,
-      which may be solved more efficiently than general systems
+      which may be solved more efficiently than general systems.
 \item Most parameterization methods use two \#vertices x \#vertices systems,
-      when Least Squares Conformal Maps uses one (2 * \#triangles) x \#vertices system
+      when Least Squares Conformal Maps uses one (2 * \#triangles) x \#vertices system.
-\item Most parameterization methods invert the A matrix,
+\item Most parameterization methods invert the $A$ matrix,
       when Least Squares Conformal Maps solves the system in the least squares sense.
 \end{itemize}
 
-Eventually, the software design chosen is:
+Therefore, the software design chosen is:
 \begin{itemize}
 \item Each \ccc{ParameterizerTraits_3} model implements its own version
       of the parameterization algorithm as a parameterize() method.
@@ -101,59 +91,63 @@ Eventually, the software design chosen is:
 \end{itemize}
 
 % Insert image parameterizer_class_diagram.png/eps with
-% title "A parameterizer's UML class diagram (main types and methods only)"
+% title "A parameterizer UML class diagram (main types and methods only)"
 \begin{center}
     \label{Surface_mesh_parameterization-fig-parameterizer_class_diagram}
     % Image
     \begin{ccTexOnly}
-        \includegraphics[width=1.1\textwidth]{Surface_mesh_parameterization/parameterizer_class_diagram}
+        \includegraphics[width=1.0\textwidth]{Surface_mesh_parameterization/parameterizer_class_diagram}
     \end{ccTexOnly}
     \begin{ccHtmlOnly}
         <img width="100%" border=0 src="./parameterizer_class_diagram.png"><P>
     \end{ccHtmlOnly}
     % Title
     \begin{figure}[h]
-        \caption{A parameterizer's UML class diagram (main types and methods only)}
+        \caption{A parameterizer UML class diagram (main types and methods only)}
     \end{figure}
 \end{center}
 
 % Insert image parameterizers_class_hierarchy.png/eps with
-% title "Parameterizers class hierarchy"
+% title "Surface parameterizer classes hierarchy"
 \begin{center}
     \label{Surface_mesh_parameterization-fig-parameterizers_class_hierarchy}
     % Image
     \begin{ccTexOnly}
-        \includegraphics[width=1.1\textwidth]{Surface_mesh_parameterization/parameterizers_class_hierarchy}
+        \includegraphics[width=0.9\textwidth]{Surface_mesh_parameterization/parameterizers_class_hierarchy}
     \end{ccTexOnly}
     \begin{ccHtmlOnly}
-        <img width="100%" border=0 src="./parameterizers_class_hierarchy.png"><P>
+        <img width="90%" border=0 src="./parameterizers_class_hierarchy.png"><P>
     \end{ccHtmlOnly}
     % Title
     \begin{figure}[h]
-        \caption{Parameterizers class hierarchy}
+        \caption{Surface parameterizer classes hierarchy}
     \end{figure}
 \end{center}
 
+Note: \ccc{CGAL::Parameterizer_traits_3<ParameterizationMesh_3>} is the (pure virtual)
+superclass of all surface parameterization classes.
+
 
 \subsection{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 $w_{ij}$
-coefficient of the A matrix, for $v_i$ and $v_j$ neighbor vertices of the mesh
+coefficient of the $A$ matrix, for $v_i$ and $v_j$ neighbor vertices of the mesh
 \cite{cgal:fh-survey-05}.
 
 The consequence is that most of the code of the fixed border methods is factorized in the
-\ccc{Fixed_border_parameterizer_3<ParameterizationMesh_3, BorderParameterizer_3, SparseLinearAlgebraTraits_d>} class.
+\ccc{CGAL::Fixed_border_parameterizer_3<ParameterizationMesh_3, BorderParameterizer_3, SparseLinearAlgebraTraits_d>} class.
+
 Subclasses:
 \begin{itemize}
 \item must provide \ccc{BorderParameterizer_3} and \ccc{SparseLinearAlgebraTraits_d}
-      template parameters that make sense
+      default template parameters that make sense,
 \item must implement \ccc{compute_w_ij}() to compute $w_{ij}$ = (i, j) coefficient
-      of matrix A for $v_j$ neighbor vertex of $v_i$
+      of matrix $A$ for $v_j$ neighbor vertex of $v_i$,
-\item may implement an optimized version of \ccc{is_one_to_one_mapping}()
+\item may implement an optimized version of \ccc{is_one_to_one_mapping}().
 \end{itemize}
 
-See \ccc{Barycentric_mapping_parameterizer_3<ParameterizationMesh_3, BorderParameterizer_3, SparseLinearAlgebraTraits_d>}
+See \ccc{CGAL::Barycentric_mapping_parameterizer_3<ParameterizationMesh_3, BorderParameterizer_3, SparseLinearAlgebraTraits_d>}
 class as an example.
 
 
@@ -163,49 +157,50 @@ Border Parameterizations are models of the \ccc{BorderParameterizer_3} concept.
 
 To simplify the implementation, \ccc{BorderParameterizer_3} models know only the
 \ccc{ParameterizationMesh_3} mesh class. They do not know the parameterization algorithm
-nor the sparse linear solver used.
+or the sparse linear solver used.
 
 
-\subsection{MeshAdaptor\_3 and PatchableMeshAdaptor\_3 Concepts}
+\subsection{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 \ccc{ParameterizationMesh_3}.
 
 The purpose of such a model is to:
 \begin{enumerate}
-\item Support several kind of meshes
+\item Support several kind of meshes.
 \item Hide the implementation of extra fields specific to the parameterization domain
-      (\ccc{index}, \ccc{u}, \ccc{v}, \ccc{is_parameterized})
+      (\ccc{index}, \ccc{u}, \ccc{v}, \ccc{is_parameterized}).
-\item Handle in the mesh type the complexity of virtually {\em cutting} a mesh
+\item Handle in the mesh type the complexity of \emph{virtually} cutting a mesh
       to make it homeomorphic to a disk (instead of duplicating this
-      code in each parameterization method)
+      code in each parameterization method).
 \end{enumerate}
 
 Two options are possible for 1) and 2):
 \begin{itemize}
 \item Pass to all classes and methods a mesh pointer, a traits class to manipulate it,
-      and accessors to the extra fields arrays.
+      and accessors to the extra field arrays.
       This is the choice of the Boost Graph Library with \ccc{boost::graph_traits<>}
       and the property maps.
 \item Pass to all classes and methods an object that points to the actual mesh and knows
-      how to access to it. This is the Adaptor concept \cite{cgal:ghjv-dpero-95}.
+      how to access to its fields. This is the Adaptor concept \cite{cgal:ghjv-dpero-95}.
 \end{itemize}
 
 The current design of this package uses the second option, which is simpler.
-Of course, we may decide to switch to the first one to reach a deeper integration
+Of course, we may decide at some point to switch to the first one to reach a deeper integration
-of CGAL with Boost.
+of \cgal\ with Boost.
 
-Point 3) is solved by class \ccc{Parameterization_mesh_patch_3<ParameterizationPatchableMesh_3>},
+Point 3) is solved by class \ccc{CGAL::Parameterization_mesh_patch_3<ParameterizationPatchableMesh_3>},
-which takes care of virtually {\em cutting}
+which takes care of \emph{virtually} cutting
 a patch in a \ccc{ParameterizationPatchableMesh_3} mesh, to make it appear as a topological disk
 with a \ccc{ParameterizationMesh_3} interface.
 \ccc{ParameterizationPatchableMesh_3} inherits from concept \ccc{ParameterizationMesh_3} and adds
 the ability to support patches and virtual seams. 
+
 This mainly means that:
 \begin{itemize}
-\item vertices can be tagged as inside or outside the patch to parameterize
+\item vertices can be tagged as inside or outside the patch to parameterize,
 \item the fields specific to parameterizations (\ccc{index}, \ccc{u}, \ccc{v}, \ccc{is_parameterized})
-      can be set per {\em corner} (aka half-edge)
+      can be set {\em per corner} (which is a more general way of saying {\em per half-edge}).
 \end{itemize}
 
 
@@ -214,9 +209,9 @@ This mainly means that:
 This package solves sparse linear systems using solvers which are models
 of \ccc{SparseLinearAlgebraTraits_d}.
 
-\ccc{SparseLinearAlgebraTraits_d} is a sub-concept of \ccc{LinearAlgebraTraits_d} concept
+\ccc{SparseLinearAlgebraTraits_d} is a sub-concept of the \ccc{LinearAlgebraTraits_d} concept
 in \ccc{Kernel_d}.
-The goal is to adapt easily code wriiten for dense matrices to sparse ones,
+The goal is to adapt easily code written for dense matrices to sparse ones,
 and vice-versa.
 
 
@@ -225,7 +220,7 @@ and vice-versa.
 In this package, we focus on triangulated surfaces that are homeomorphic to a
 disk.
 
-Computing a cut that transforms a closed mesh of arbitrary genus into
+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.
 

Surface_mesh_parameterization/doc_tex/Surface_mesh_parameterization/solvers.tex

@@ -1,38 +1,61 @@
 \section{Sparse Linear Algebra}
+\label{sec:Sparse-Linear-Algebra}
 
 Parameterizing triangle meshes requires both efficient representation
 of sparse matrices and efficient iterative or direct linear
 solvers. We provide links to standard libraries ({\sc Taucs})
 and include a separate package devoted to OpenNL sparse linear solver.
 
-\subsection{List of Solvers and Concept}
+\subsection{List of Solvers}
 
 We provide an interface to several sparse linear solvers, as models
 of the \ccc{SparseLinearAlgebraTraits_d} concept:
 
 \begin{itemize}
 
-\item OpenNL \cite{cgal:l-nmdgp-05} is shipped with \cgal. This is the default solver:
+\item
+    OpenNL \cite{cgal:l-nmdgp-05} is shipped with \cgal. This is the default solver.
 
     \ccc{OpenNL::DefaultLinearSolverTraits<COEFFTYPE, MATRIX, VECTOR, SOLVER>} in OpenNL package  \\
     \ccc{OpenNL::SymmetricLinearSolverTraits<COEFFTYPE, MATRIX, VECTOR, SOLVER>} in OpenNL package  \\
 
-\item {\sc Taucs} is a state-of-the-art direct solver for sparse symmetric matrices.
+    \emph{Usage:}
+
+    OpenNL (in the version shipped with \cgal) is a lightweight sparse linear solver.
+    It does not support large systems.
+    On the other hand, it is highly portable and supports exact number types.
+
+\item
+    \ccAnchor{http://www.cs.tau.ac.il/~stoledo/taucs}{{\sc Taucs}}
+    is a state-of-the-art direct solver for sparse symmetric matrices.
+    It also includes an out-of-core general sparse solver.
 
     \ccc{CGAL::Taucs_solver_traits<T>}  \\
     \ccc{CGAL::Taucs_symmetric_solver_traits<T>}  \\
 
+    \emph{Usage:}
+
+    {\sc Taucs} is very robust and supports large systems.
+    On the other hand, it is \emph{not} available on all platforms
+    supported by \cgal\ and does \emph{not} support exact number types.
+
+    \emph{Install:}
+
+    {\sc Taucs} can be downloaded from
+    \ccAnchor{http://www.tau.ac.il/~stoledo/taucs/2.2/taucs_full.zip}
+    {\ccc{http://www.tau.ac.il/~stoledo/taucs/2.2/taucs_full.zip}}.
+
 \end{itemize}
 
 
 \subsection{{\sc Taucs} Solver Example}
 
-The examples provided so far use the default sparse linear solver
-OpenNL. 
-
 \ccc{Taucs_parameterization.C} computes the default parameterization
 method (Floater Mean Value Coordinates with a circular border), but
 specifically instantiates the {\sc Taucs} solver.
+Specifying a specific solver
+instead of the default one (OpenNL) means using the third parameter of
+\ccc{CGAL::Mean_value_coordinates_parameterizer_3<ParameterizationMesh_3, BorderParameterizer_3, SparseLinearAlgebraTraits_d>}.
 
 The differences with the first example \ccc{Simple_parameterization.C} are:
 

Surface_mesh_parameterization/doc_tex/Surface_mesh_parameterization_ref/BorderParameterizer_3.tex

@@ -25,7 +25,7 @@
 
 BorderParameterizer\_3 is a concept of class that parameterizes a given type of mesh, 'Adaptor', which is a model of the ParameterizationMesh\_3 concept.
 
-Implementation note: To simplify the implementation, BorderParameterizer\_3 models know only the ParameterizationMesh\_3 class. They do not know the parameterization algorithm requirements nor the kind of sparse linear system used.
+Implementation note: To simplify the implementation, BorderParameterizer\_3 models know only the ParameterizationMesh\_3 class. They do not know the parameterization algorithm requirements or the kind of sparse linear system used.
 
 %END-AUTO(\ccDefinition)
 

Surface_mesh_parameterization/doc_tex/Surface_mesh_parameterization_ref/Circular_border_parameterizer_3.tex

@@ -25,7 +25,7 @@
 
 This is the base class of strategies that parameterize the border of a 3D surface onto a circle. Circular\_border\_parameterizer\_3 is a pure virtual class, thus cannot be instantiated. It implements most of the algorithm. Subclasses just have to implement compute\_edge\_length() to compute a segment's length.
 
-Implementation note: To simplify the implementation, BorderParameterizer\_3 models know only the ParameterizationMesh\_3 class. They do not know the parameterization algorithm requirements nor the kind of sparse linear system used.
+Implementation note: To simplify the implementation, BorderParameterizer\_3 models know only the ParameterizationMesh\_3 class. They do not know the parameterization algorithm requirements or the kind of sparse linear system used.
 
 %END-AUTO(\ccDefinition)
 

Surface_mesh_parameterization/doc_tex/Surface_mesh_parameterization_ref/ParameterizationMesh_3.tex

@@ -4,8 +4,8 @@
 % | 23.08.2005   Laurent Saboret, Pierre Alliez, Bruno Levy
 % | Package: Surface_mesh_parameterization
 % |
-\RCSdef{\RCSMeshAdaptorRev}{$Id$}
+\RCSdef{\RCSParameterizationMeshRev}{$Id$}
-\RCSdefDate{\RCSMeshAdaptorDate}{$Date$}
+\RCSdefDate{\RCSParameterizationMeshDate}{$Date$}
 % |
 \ccRefPageBegin
 %%RefPage: end of header, begin of main body
@@ -31,7 +31,7 @@ The surface must be an oriented 2-manifold with border vertices, i.e. the neighb
 
 ParameterizationMesh\_3 defines the types, data and methods that a mesh must implement to allow surface parameterization. Among other things, this concept defines accessors to fields specific to parameterizations methods: index, u, v, is\_parameterized.
 
-ParameterizationMesh\_3 meshes can have any genus, arity or number of components. In the other hand, as parameterization methods deal only with topological disks, ParameterizationMesh\_3 defines an interface oriented towards topological disks.
+ParameterizationMesh\_3 meshes can have any genus, arity or number of components. On the other hand, as parameterization methods deal only with topological disks, ParameterizationMesh\_3 defines an interface oriented towards topological disks.
 
 %END-AUTO(\ccDefinition)
 
@@ -352,7 +352,7 @@ Get circulator over the vertices incident to 'vertex'. 'start\_position' defines
 %START-AUTO(\ccHasModels)
 
 \begin{itemize}
-\item Adaptator for Polyhedron\_3 is provided.\item Parameterization\_mesh\_patch\_3$<$M$>$ is a model of ParameterizationMesh\_3 if M is a model of MeshAdaptorWithStream\_3.\end{itemize}
+\item Adaptator for Polyhedron\_3 is provided.\item Parameterization\_mesh\_patch\_3$<$M$>$ is a model of ParameterizationMesh\_3 if M is a model of ParameterizationPatchableMesh\_3.\end{itemize}
 
 %END-AUTO(\ccHasModels)
 

Surface_mesh_parameterization/doc_tex/Surface_mesh_parameterization_ref/ParameterizationPatchableMesh_3.tex

@@ -4,8 +4,8 @@
 % | 29.08.2005   Laurent Saboret, Pierre Alliez, Bruno Levy
 % | Package: Surface_mesh_parameterization
 % |
-\RCSdef{\RCSPatchableMeshAdaptorRev}{$Id$}
+\RCSdef{\RCSParameterizationPatchableMeshRev}{$Id$}
-\RCSdefDate{\RCSPatchableMeshAdaptorDate}{$Date$}
+\RCSdefDate{\RCSParameterizationPatchableMeshDate}{$Date$}
 % |
 \ccRefPageBegin
 %%RefPage: end of header, begin of main body
@@ -25,7 +25,7 @@
 
 ParameterizationPatchableMesh\_3 inherits from concept ParameterizationMesh\_3, thus is a concept of a 3D surface mesh.
 
-ParameterizationPatchableMesh\_3 adds the ability to support patches and virtual seams. Patches are a subset of a 3D mesh. Virtual seams are the ability to behave exactly as if the surface was {\em cut} following a certain path.
+ParameterizationPatchableMesh\_3 adds the ability to support patches and virtual seams. {\em Patches} are a subset of a 3D mesh. {\em Virtual seams} are the ability to behave exactly as if the surface was cut following a certain path.
 
 This mainly means that:\begin{itemize}
 \item vertices can be tagged as inside or outside the patch to parameterize.\item the fields specific to parameterizations (index, u, v, is\_parameterized) can be set per {\em corner} (aka half-edge).\end{itemize}
@@ -55,8 +55,8 @@ ParameterizationPatchableMesh\_3 inherits from concept ParameterizationMesh\_3.
 
 %END-AUTO(\ccRefines)
 
-In addition to the requirements described in the concept MeshAdaptor\_3,
+In addition to the requirements described in the concept \ccc{ParameterizationMesh_3},
-PatchableMeshAdaptor\_3 provides the following:
+\ccc{ParameterizationPatchableMesh_3} provides the following:
 
 
 \ccTypes

Surface_mesh_parameterization/doc_tex/Surface_mesh_parameterization_ref/Parameterization_mesh_patch_3.tex

@@ -23,7 +23,7 @@
 % The section below is automatically generated. Do not edit!
 %START-AUTO(\ccDefinition)
 
-Parameterization\_mesh\_patch\_3 is a Decorator class to virtually {\em cut} a patch in a ParameterizationPatchableMesh\_3 3D surface. Only the patch is exported, making the 3D surface look like a topological disk.
+Parameterization\_mesh\_patch\_3 is a Decorator class to {\em virtually} cut a patch in a ParameterizationPatchableMesh\_3 3D surface. Only the patch is exported, making the 3D surface look like a topological disk.
 
 The input mesh can be of any genus, but it has to come with a {\em seam} that describes the border of a topological disc. This border may be an actual border of the mesh or a virtual border.
 

Surface_mesh_parameterization/doc_tex/Surface_mesh_parameterization_ref/Parameterization_polyhedron_adaptor_3.tex

@@ -33,7 +33,7 @@ ParameterizationMesh\_3 meshes can have any genus, arity or number of components
 
 It can have have any number of borders. Its {\em main border} will be the mesh's longest border (if there is at least one border).
 
-It has also the ability to support patches and virtual seams. Patches are a subset of a 3D mesh. Virtual seams are the ability to behave exactly as if the surface was {\em cut} following a certain path.
+It has also the ability to support patches and virtual seams. {\em Patches} are a subset of a 3D mesh. {\em Virtual seams} are the ability to behave exactly as if the surface was cut following a certain path.
 
 %END-AUTO(\ccDefinition)
 

Surface_mesh_parameterization/doc_tex/Surface_mesh_parameterization_ref/Square_border_parameterizer_3.tex

@@ -27,7 +27,7 @@ This is the base class of strategies that parameterize the border of a 3D surfac
 
 It implements most of the algorithm. Subclasses just have to implement compute\_edge\_length() to compute a segment's length.
 
-Implementation note: To simplify the implementation, BorderParameterizer\_3 models know only the ParameterizationMesh\_3 class. They do not know the parameterization algorithm requirements nor the kind of sparse linear system used.
+Implementation note: To simplify the implementation, BorderParameterizer\_3 models know only the ParameterizationMesh\_3 class. They do not know the parameterization algorithm requirements or the kind of sparse linear system used.
 
 %END-AUTO(\ccDefinition)
 

Surface_mesh_parameterization/doc_tex/Surface_mesh_parameterization_ref/Two_vertices_parameterizer_3.tex

@@ -28,7 +28,7 @@ for Least Squares Conformal Maps parameterization.
 
 The class Two\_vertices\_parameterizer\_3 parameterizes two extreme vertices of a 3D surface. This kind of border parameterization is used by free border parameterizations.
 
-Implementation note: To simplify the implementation, BorderParameterizer\_3 models know only the ParameterizationMesh\_3 class. They do not know the parameterization algorithm requirements nor the kind of sparse linear system used.
+Implementation note: To simplify the implementation, BorderParameterizer\_3 models know only the ParameterizationMesh\_3 class. They do not know the parameterization algorithm requirements or the kind of sparse linear system used.
 
 %END-AUTO(\ccDefinition)
 

Surface_mesh_parameterization/doc_tex/Surface_mesh_parameterization_ref/intro.tex

@@ -23,7 +23,22 @@ 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}
+
+\ccHeading{Main Function}
+
+\ccRefIdfierPage{CGAL::parameterize}  \\
+
+
+\ccHeading{Concepts}
+
+\ccRefIdfierPage{ParameterizerTraits_3}  \\
+\ccRefIdfierPage{BorderParameterizer_3}  \\
+\ccRefIdfierPage{ParameterizationMesh_3}  \\
+\ccRefIdfierPage{ParameterizationPatchableMesh_3}  \\
+\ccRefIdfierPage{SparseLinearAlgebraTraits_d}  \\
+
+
+\ccHeading{Surface Parameterization Methods}
 
 This \cgal\ package implements some of
 the state-of-the-art parameterization methods:
@@ -58,18 +73,26 @@ the state-of-the-art parameterization methods:
 
 \end{itemize}
 
+\ccRefIdfierPage{CGAL::Parameterizer_traits_3<ParameterizationMesh_3>}  \\
+\ccRefIdfierPage{CGAL::Fixed_border_parameterizer_3<ParameterizationMesh_3, BorderParameterizer_3, SparseLinearAlgebraTraits_d>}  \\
+\ccRefIdfierPage{CGAL::Barycentric_mapping_parameterizer_3<ParameterizationMesh_3, BorderParameterizer_3, SparseLinearAlgebraTraits_d>}  \\
+\ccRefIdfierPage{CGAL::Discrete_authalic_parameterizer_3<ParameterizationMesh_3, BorderParameterizer_3, SparseLinearAlgebraTraits_d>}  \\
+\ccRefIdfierPage{CGAL::Discrete_conformal_map_parameterizer_3<ParameterizationMesh_3, BorderParameterizer_3, SparseLinearAlgebraTraits_d>}  \\
+\ccRefIdfierPage{CGAL::LSCM_parameterizer_3<ParameterizationMesh_3, BorderParameterizer_3, SparseLinearAlgebraTraits_d>}  \\
+\ccRefIdfierPage{CGAL::Mean_value_coordinates_parameterizer_3<ParameterizationMesh_3, BorderParameterizer_3, SparseLinearAlgebraTraits_d>}  \\
+
 
 \ccHeading{Border Parameterization Methods}
 
 Border parameterization methods define a
-set of constraints (a constraint specifies two u,v coordinates for
+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.
+vertices).
 
 \item For fixed border methods:
 
@@ -77,7 +100,7 @@ vertices). They have to be on the specified border.
 
     \item the user can select a border
         parameterization among two common methods: uniform or
-        arc-length parameterization.
+        arc-length parameterizations.
 
     \item one convex shape specified by:
 
@@ -91,6 +114,12 @@ vertices). They have to be on the specified border.
 
 \end{itemize}
 
+\ccRefIdfierPage{CGAL::Circular_border_arc_length_parameterizer_3<ParameterizationMesh_3>}  \\
+\ccRefIdfierPage{CGAL::Circular_border_uniform_parameterizer_3<ParameterizationMesh_3>}  \\
+\ccRefIdfierPage{CGAL::Square_border_arc_length_parameterizer_3<ParameterizationMesh_3>}  \\
+\ccRefIdfierPage{CGAL::Square_border_uniform_parameterizer_3<ParameterizationMesh_3>}  \\
+\ccRefIdfierPage{CGAL::Two_vertices_parameterizer_3<ParameterizationMesh_3>}  \\
+
 
 \ccHeading{Mesh}
 
@@ -104,16 +133,15 @@ The general definition of input meshes handled by the package is:
 
 \item Oriented.
 
-\item Surface parameterization methods deal only with topological discs.
+\item Surface parameterization methods deal only with topological discs
-The input mesh can be of any genus and have any number of connected components.
+(from a mathematical point of view).
-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,
+Fortunately, the meshes supported by the package can be of any genus and
-thus only one connected component.
+have any number of connected components. If it is not a topological
+disc, the input mesh has to come with a description of a cutting path (an oriented list of
+vertices) which is the border of a topological disc.  If no cutting path is
+given as input, we assume that the surface border is the longest border already
+in the input mesh (the other borders will be considered as holes).
 
 Note that this way the user is responsible for cutting a closed mesh of
 arbitrary genus (even a topological disc with an intricate seam
@@ -121,16 +149,25 @@ cut), as long as this condition is fulfilled.
 
 \end{itemize}
 
-The package provides an interface with the Polyhedron.
+The package provides an interface with the Polyhedron:
 
-The \cgal\ \ccc{Surface_mesh_parameterization} package is loosely linked to the
+\ccRefIdfierPage{CGAL::Parameterization_polyhedron_adaptor_3<Polyhedron_3_>}  \\
-mesh data structure. Replacing it is relatively easy.
+
+The \ccc{CGAL::Parameterization_mesh_patch_3<ParameterizationPatchableMesh_3>}
+class is responsible for \emph{virtually} cutting
+a patch in a \ccc{ParameterizationPatchableMesh_3} mesh.
+The resulting patch is a topological
+disk (if the input cutting path is correct)
+and provides a \ccc{ParameterizationMesh_3} interface. It can be used as
+parameter of \ccc{CGAL::parameterize()}.
 
 
 \ccHeading{Output}
 
-One uv coordinate for each interior vertex, and one uv coordinate for
+A $(u,v)$ pair is provided for
-each instance of a vertex along the input border.
+each inner vertex (i.e. its halfedges share the same $(u,v)$ pair),
+while a $(u,v)$ pair is provided for each border halfedge.
+The user has to iterate over the mesh halfedges to get the result.
 
 
 \ccHeading{Sparse Linear Algebra}
@@ -144,8 +181,15 @@ sparse linear solvers:
 \item {\sc Taucs} is a state-of-the-art direct solver for sparse symmetric matrices.
 \end{itemize}
 
-The \cgal\ \ccc{Surface_mesh_parameterization} package is loosely linked to the
+\ccc{OpenNL::DefaultLinearSolverTraits<COEFFTYPE, MATRIX, VECTOR, SOLVER>} in OpenNL package  \\
-solver. Replacing it is easy.
+\ccc{OpenNL::SymmetricLinearSolverTraits<COEFFTYPE, MATRIX, VECTOR, SOLVER>} in OpenNL package  \\
+\ccRefIdfierPage{CGAL::Taucs_solver_traits<T>}  \\
+\ccRefIdfierPage{CGAL::Taucs_symmetric_solver_traits<T>}  \\
+
+
+\ccHeading{Helper Classes}
+
+\ccRefIdfierPage{CGAL::Parameterization_mesh_feature_extractor<ParameterizationMesh_3>}  \\
 
 
 \ccHeading{Assertions}
@@ -185,59 +229,6 @@ Expensive checking is off by default. It can be enabled by
 defining \ccc{CGAL_SURFACE_MESH_PARAMETERIZATION_CHECK_EXPENSIVE}.
 
 
-\ccHeading{Main Function}
-
-\ccRefIdfierPage{CGAL::parameterize}  \\
-
-
-\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<ParameterizationMesh_3>}  \\
-\ccRefIdfierPage{CGAL::Fixed_border_parameterizer_3<ParameterizationMesh_3, BorderParameterizer_3, SparseLinearAlgebraTraits_d>}  \\
-\ccRefIdfierPage{CGAL::Barycentric_mapping_parameterizer_3<ParameterizationMesh_3, BorderParameterizer_3, SparseLinearAlgebraTraits_d>}  \\
-\ccRefIdfierPage{CGAL::Discrete_authalic_parameterizer_3<ParameterizationMesh_3, BorderParameterizer_3, SparseLinearAlgebraTraits_d>}  \\
-\ccRefIdfierPage{CGAL::Discrete_conformal_map_parameterizer_3<ParameterizationMesh_3, BorderParameterizer_3, SparseLinearAlgebraTraits_d>}  \\
-\ccRefIdfierPage{CGAL::LSCM_parameterizer_3<ParameterizationMesh_3, BorderParameterizer_3, SparseLinearAlgebraTraits_d>}  \\
-\ccRefIdfierPage{CGAL::Mean_value_coordinates_parameterizer_3<ParameterizationMesh_3, BorderParameterizer_3, SparseLinearAlgebraTraits_d>}  \\
-
-
-\ccHeading{Border Parameterization Methods Traits Classes}
-
-\ccRefIdfierPage{CGAL::Circular_border_arc_length_parameterizer_3<ParameterizationMesh_3>}  \\
-\ccRefIdfierPage{CGAL::Circular_border_uniform_parameterizer_3<ParameterizationMesh_3>}  \\
-\ccRefIdfierPage{CGAL::Square_border_arc_length_parameterizer_3<ParameterizationMesh_3>}  \\
-\ccRefIdfierPage{CGAL::Square_border_uniform_parameterizer_3<ParameterizationMesh_3>}  \\
-\ccRefIdfierPage{CGAL::Two_vertices_parameterizer_3<ParameterizationMesh_3>}  \\
-
-
-\ccHeading{MeshAdaptor\_3 and PatchableMeshAdaptor\_3 Traits Classes}
-
-\ccRefIdfierPage{CGAL::Parameterization_polyhedron_adaptor_3<Polyhedron_3_>}  \\
-\ccRefIdfierPage{CGAL::Parameterization_mesh_patch_3<ParameterizationPatchableMesh_3>}  \\
-
-
-\ccHeading{Sparse Linear Algebra Traits Classes}
-
-\ccRefIdfierPage{CGAL::Taucs_solver_traits<T>}  \\
-\ccRefIdfierPage{CGAL::Taucs_symmetric_solver_traits<T>}  \\
-\ccc{OpenNL::DefaultLinearSolverTraits<COEFFTYPE, MATRIX, VECTOR, SOLVER>} in OpenNL package  \\
-\ccc{OpenNL::SymmetricLinearSolverTraits<COEFFTYPE, MATRIX, VECTOR, SOLVER>} in OpenNL package  \\
-
-
-\ccHeading{Helper Classes}
-
-\ccRefIdfierPage{CGAL::Parameterization_mesh_feature_extractor<ParameterizationMesh_3>}  \\
-
-
 \clearpage
 
 \lcHtml{\ccHeading{Alphabetical Listing of Reference Pages}}

Surface_mesh_parameterization/doc_tex/Surface_mesh_parameterization_ref/parameterize.tex

@@ -20,14 +20,14 @@
 
 \ccDefinition
 
-\ccc{parameterize()} is the main entry-point of the \ccc{Surface_mesh_parameterization} package.
+\ccc{CGAL::parameterize()} is the main entry-point of the \ccc{Surface_mesh_parameterization} package.
 
 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 algorithm.
 
-The \ccc{parameterize()} function exists in two flavors, to provide a default parameterization algorithm
+The \ccc{CGAL::parameterize()} function exists in two flavors, to provide a default parameterization algorithm
 of Floater Mean Value Coordinates.
 
 \ccInclude{CGAL/parameterize.h}

Surface_mesh_parameterization/examples/Surface_mesh_parameterization/Complete_parameterization_example.C

@@ -230,7 +230,7 @@ int main(int argc,char * argv[])
 
     // The parameterization methods support only meshes that
     // are topological disks => we need to compute a "cutting" of the mesh
-    // that makes it it homeomorphic to a disk
+    // that makes it homeomorphic to a disk
     Seam seam = cut_mesh(mesh_adaptor);
     if (seam.empty())
     {

Surface_mesh_parameterization/examples/Surface_mesh_parameterization/Mesh_cutting_parameterization.C

@@ -141,7 +141,7 @@ int main(int argc,char * argv[])
 
     // The parameterization methods support only meshes that
     // are topological disks => we need to compute a "cutting" of the mesh
-    // that makes it it homeomorphic to a disk
+    // that makes it homeomorphic to a disk
     Seam seam = cut_mesh(mesh_adaptor);
     if (seam.empty())
     {

Surface_mesh_parameterization/examples/Surface_mesh_parameterization/polyhedron_ex_parameterization.C

@@ -124,7 +124,7 @@ static Seam cut_mesh(Parameterization_polyhedron_adaptor& mesh_adaptor)
         Backbone seamingBackbone;           // result of cutting
         Backbone::iterator he;
 
-        // Virtually "cut" mesh to make it a topological disk
+        // Compute a cutting path that makes the mesh a "virtual" topological disk
         mesh.compute_facet_centers();
         Mesh_cutter cutter(mesh);
         if (genus == 0)
@@ -464,8 +464,8 @@ int main(int argc,char * argv[])
     Parameterization_polyhedron_adaptor mesh_adaptor(mesh);
 
     // The parameterization methods support only meshes that
-    // are topological disks => we need to virtually "cut" the mesh
+    // are topological disks => we need to compute a cutting path
-    // to make it homeomorphic to a disk
+    // that makes the mesh a "virtual" topological disk
     //
     // 1) Cut the mesh
     Seam seam = cut_mesh(mesh_adaptor);

Surface_mesh_parameterization/include/CGAL/Circular_border_parameterizer_3.h

@@ -41,7 +41,7 @@ CGAL_BEGIN_NAMESPACE
 /// Implementation note:
 /// To simplify the implementation, BorderParameterizer_3 models know only the
 /// ParameterizationMesh_3 class. They do not know the parameterization algorithm
-/// requirements nor the kind of sparse linear system used.
+/// requirements or the kind of sparse linear system used.
 ///
 /// Concept: Model of the BorderParameterizer_3 concept (although you cannot instantiate this class).
 ///

Surface_mesh_parameterization/include/CGAL/Parameterization_mesh_patch_3.h

@@ -35,7 +35,7 @@
 CGAL_BEGIN_NAMESPACE
 
 
-/// Parameterization_mesh_patch_3 is a Decorator class to virtually "cut" a patch
+/// Parameterization_mesh_patch_3 is a Decorator class to "virtually" cut a patch
 /// in a ParameterizationPatchableMesh_3 3D surface. Only the patch is exported,
 /// making the 3D surface look like a topological disk.
 ///

Surface_mesh_parameterization/include/CGAL/Parameterization_polyhedron_adaptor_3.h

@@ -55,8 +55,8 @@ CGAL_BEGIN_NAMESPACE
 /// will be the mesh's longest border (if there is at least one border).
 ///
 /// It has also the ability to support patches and virtual seams.
-/// Patches are a subset of a 3D mesh. Virtual seams are the ability
+/// "Patches" are a subset of a 3D mesh. "Virtual seams" are the ability
-/// to behave exactly as if the surface was "cut" following a certain path.
+/// to behave exactly as if the surface was cut following a certain path.
 ///
 /// Concept:
 /// Model of ParameterizationPatchableMesh_3 concept, whose purpose is to allow

Surface_mesh_parameterization/include/CGAL/Square_border_parameterizer_3.h

@@ -46,7 +46,7 @@ CGAL_BEGIN_NAMESPACE
 /// Implementation note:
 /// To simplify the implementation, BorderParameterizer_3 models know only the
 /// ParameterizationMesh_3 class. They do not know the parameterization algorithm
-/// requirements nor the kind of sparse linear system used.
+/// requirements or the kind of sparse linear system used.
 ///
 /// Concept: Model of the BorderParameterizer_3 concept (although you cannot instantiate this class).
 ///

Surface_mesh_parameterization/include/CGAL/Two_vertices_parameterizer_3.h

@@ -41,7 +41,7 @@ CGAL_BEGIN_NAMESPACE
 /// Implementation note:
 /// To simplify the implementation, BorderParameterizer_3 models know only the
 /// ParameterizationMesh_3 class. They do not know the parameterization algorithm
-/// requirements nor the kind of sparse linear system used.
+/// requirements or the kind of sparse linear system used.
 ///
 /// Concept: Model of the BorderParameterizer_3 concept.
 ///

Surface_mesh_parameterization/long_description.txt

@@ -27,7 +27,7 @@ The intended audience of this package is researchers, developers or students dev
   - One connected component.
 The input mesh can be of any genus, -but- it has to come with a description of a border (a list of oriented edges given by a set or vertices) which is the border of a topological disc. If no border is given, we assume that it coincides with the unique border already in the input mesh. 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 verified.
 
-* A set of constraints (a constraint specifies two u,v coordinates for each instance of a vertex along the border).
+* A set of constraints (a constraint specifies two (u,v) coordinates for each instance of a vertex along the border).
   - For free border methods: only two constraints (the pinned vertices). They have to be on the specified border.
   - For fixed border methods:
     + a list of constraints given by the user. The whole border has to be specified.

Surface_mesh_parameterization/test/Surface_mesh_parameterization/extensive_parameterization_test.C

@@ -118,7 +118,7 @@ static Seam cut_mesh(Parameterization_polyhedron_adaptor& mesh_adaptor)
         Backbone seamingBackbone;           // result of cutting
         Backbone::iterator he;
 
-        // Virtually "cut" mesh to make it a topological disk
+        // Compute a cutting path that makes the mesh a "virtual" topological disk
         mesh.compute_facet_centers();
         Mesh_cutter cutter(mesh);
         if (genus == 0)
@@ -239,8 +239,8 @@ int main(int argc,char * argv[])
         Parameterization_polyhedron_adaptor mesh_adaptor(mesh);
 
         // The parameterization methods support only meshes that
-        // are topological disks => we need to virtually "cut" the mesh
+        // are topological disks => we need to compute a cutting path
-        // to make it homeomorphic to a disk
+        // that makes the mesh a "virtual" topological disk
         //
         // 1) Cut the mesh
         Seam seam = cut_mesh(mesh_adaptor);