From 62979fc9b5e8c79dda8700159e76e370af5e40f2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mael=20Rouxel-Labb=C3=A9?= Date: Tue, 8 Nov 2016 18:08:24 +0100 Subject: [PATCH] Improved SMP's documentation --- .../PackageDescription.txt | 3 +- .../Surface_mesh_parameterization.txt | 111 ++++++++---------- .../examples.txt | 4 +- .../CGAL/Fixed_border_parameterizer_3.h | 2 +- 4 files changed, 56 insertions(+), 64 deletions(-) diff --git a/Surface_mesh_parameterization/doc/Surface_mesh_parameterization/PackageDescription.txt b/Surface_mesh_parameterization/doc/Surface_mesh_parameterization/PackageDescription.txt index f593dea8d86..282ea872517 100644 --- a/Surface_mesh_parameterization/doc/Surface_mesh_parameterization/PackageDescription.txt +++ b/Surface_mesh_parameterization/doc/Surface_mesh_parameterization/PackageDescription.txt @@ -65,8 +65,7 @@ This package implements all common border parameterization methods: - For fixed border methods: - the user can select a border parameterization among two common methods: uniform or arc-length parameterizations. - - one convex shape specified by: - - one shape among a set of standard ones (circle, square). + - the user can select a convex shape among a set of standard ones (circle, square). - For free border methods: at least two constraints (the pinned vertices). - `CGAL::Circular_border_uniform_parameterizer_3` diff --git a/Surface_mesh_parameterization/doc/Surface_mesh_parameterization/Surface_mesh_parameterization.txt b/Surface_mesh_parameterization/doc/Surface_mesh_parameterization/Surface_mesh_parameterization.txt index 0bc9cd95902..3952de21d24 100644 --- a/Surface_mesh_parameterization/doc/Surface_mesh_parameterization/Surface_mesh_parameterization.txt +++ b/Surface_mesh_parameterization/doc/Surface_mesh_parameterization/Surface_mesh_parameterization.txt @@ -36,11 +36,10 @@ planar domain (convex polygon vs. free border) and by the guarantees provided in terms of bijective mapping. The package proposes an interface for any model of the concept `FaceGraph`, -that is classes as `Polyhedron_3`, `Surface_mesh`, as well as mesh +such as the classes `Surface_mesh`, `Polyhedron_3`, or the mesh classes of OpenMesh. - -Since parameterizing meshes require efficient representation of sparse +Since parameterizing meshes requires an efficient representation of sparse matrices and efficient iterative or direct linear solvers, we provide a unified interface to linear solvers as described in Chapter \ref PkgSolverSummary. @@ -48,9 +47,8 @@ a unified interface to linear solvers as described in Chapter Note that linear solvers commonly use double precision floating point numbers. Therefore, this package is intended to be used with a \cgal %Cartesian kernel with doubles. - \cgalFigureBegin{Surface_mesh_parameterizationfigintroduction,introduction.jpg} -Texture mapping via Least Squares Conformal Maps parameterization. Top: original mesh and texture. Bottom: parameterizedmesh (left: parameter space, right: textured mesh). +Texture mapping via Least Squares Conformal Maps parameterization. Top: original mesh and texture. Bottom: parameterized mesh (left: parameter space, right: textured mesh). \cgalFigureEnd \section Surface_mesh_parameterizationBasics Basics @@ -65,34 +63,32 @@ template Parameterizer_traits::Error_code parameterize(TriangleMesh & mesh, boost::graph_traits::halfedge_descriptor bhd, - VertexUvMap uvm); + VertexUVMap uvm); \endcode The function `parameterize()` applies a default surface parameterization method, namely Floater Mean Value Coordinates \cgalCite{cgal:f-mvc-03}, to the connected component of the mesh of type `TriangleMesh` with the border given by the halfedge `bhd`. This border is parameterized with an arc-length circular border parameterization. -The sparse linear solver used is from the \ref thirdpartyEigen library. +The sparse linear solver of the \ref thirdpartyEigen library is used. -The mesh of type `TriangleMesh` which must be a model of the concept -`FaceGraph`, additionally must be triangulated, 2-manifold, oriented, -and homeomorphic to a disc (possibly with holes). We will later show -how to parameterize a mesh that is not a topological disk. +The mesh of type `TriangleMesh` must be a model of the concept +`FaceGraph` and must additionally be triangulated, 2-manifold, oriented, +and homeomorphic to a disc (possibly with holes). The last requirement +is not hard and we will later show how to parameterize a mesh that is +not a topological disk (Section \ref Surface_mesh_parameterizationComputingaCut). +The result is stored in a property map (whose type is here VertexUVMap) +for the mesh vertices. See also Chapter \ref PkgProperty_mapSummary. -The result is stored in a property map for the mesh vertices. See also -Chapter \ref PkgProperty_mapSummary. - - -`Parameterizer_traits_3` is a base class of all surface +The class `Parameterizer_traits_3` is a base class of all surface parameterizations and defines the error codes. - +\subsection Surface_mesh_parameterizationDefaultExample Default Parameterization Example In the following example, we apply the default parameterization to a -`Polyhedron_3` mesh, and we use a `Unique_hash_map` to store the uv-coordinates -of each vertex. - -\cgalExample{Surface_mesh_parameterization/Simple_parameterization.cpp} +`Surface_mesh` mesh. We store the UV-coordinates as a vertex property +using the `Surface_mesh` built-in property mechanism. +\cgalExample{Surface_mesh_parameterization/simple_parameterization.cpp} \subsection Surface_mesh_parameterizationEnhancedparameterize Choosing a Parameterization Algorithm @@ -105,22 +101,22 @@ Parameterizer_traits::Error_code parameterize(TriangleMesh& mesh, ParameterizerTraits_3 parameterizer, boost::graph_traits::halfedge_descriptor bhd, - VertexUvMap uvm); + VertexUVMap uvm); \endcode +It computes a one-to-one mapping from a 3D triangle surface mesh to a simple 2D domain. +The mapping is piecewise linear on the triangle mesh. The result is a pair (u,v) +of parameter coordinates for each vertex of the input mesh. +A one-to-one mapping may be guaranteed or not, depending on the chosen +ParameterizerTraits_3 algorithm. - -In the following example, we apply the circular border parameterizations -and then the discrete authalic parameterization to a -`Surface_mesh`. We store the uv-coordinates as a vertex property -using the built-in property mechanism. +In the following example, we use a circular uniform border parameterization +and then use the discrete authalic parameterizer with a +`Surface_mesh`. We store the UV-coordinates as a vertex property +using the `Surface_mesh` built-in property mechanism. \cgalExample{Surface_mesh_parameterization/discrete_authalic.cpp} - - - - \section secSurfaceParameterizationMethods Surface Parameterization Methods This \cgal package implements surface parameterization methods, such @@ -224,40 +220,35 @@ Border parameterizations for fixed border surface parameterizations are a family of methods to define a set of constraints, namely two \f$ u,v\f$ coordinates for each vertex along the border. +Different choices are offered to the user when choosing border parameterizers +for fixed border methods:
    -
  • The user can select a border parameterization among two commonly used methods: uniform or arc-length parameterization. -Usage: - -Uniform border parameterization is more stable, although it gives -poor visual results. The -arc-length border parameterization is used by default. +Usage: Uniform border parameterizations are more stable, +although they give poor visual results. The arc-length border +parameterization is used by default.
  • One convex shape specified by one shape among two standard ones: a circle or a square. -Usage: - -The circular border parameterization is used by default as it +Usage: 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. -
-`Circular_border_arc_length_parameterizer_3` - -`Circular_border_uniform_parameterizer_3` - -`Square_border_arc_length_parameterizer_3` - -`Square_border_uniform_parameterizer_3` - \cgalFigureBegin{Surface_mesh_parameterizationfigcircular_border,border.png} Left: Julius Cesar mask parameterization with Authalic/circular border. Right: Julius Cesar mask's image with Floater/square border. \cgalFigureEnd +All combinations of uniform/arc-length and circle/square are provided by +the following classes: +`Circular_border_arc_length_parameterizer_3` +`Circular_border_uniform_parameterizer_3` +`Square_border_arc_length_parameterizer_3` +`Square_border_uniform_parameterizer_3` + \subsection Surface_mesh_parameterizationFreeBorderSurface Free Border Surface Parameterizations \subsubsection Surface_mesh_parameterizationLeastSquares Least Squares Conformal Maps @@ -289,35 +280,37 @@ parameterization methods define only two constraints: the pinned vertices.
  • `Two_vertices_parameterizer_3` -Usage: - -`Two_vertices_parameterizer_3` is the default +Usage: `Two_vertices_parameterizer_3` is the default free border parameterization, and is the only one available in the current version of this package. - \section secCuttingaMesh Cutting a Mesh \subsection Surface_mesh_parameterizationComputingaCut Computing a Cut Graph -All surface parameterization methods proposed in this package only +The surface parameterization methods proposed in this package only deal with meshes which are homeomorphic (topologically equivalent) to -discs. Nevertheless meshes with arbitrary topology and number of -connected components car be parameterized, provided that the user +discs. Nevertheless, meshes with arbitrary topology and number of +connected components can be parameterized, provided that the user specifies a cut graph (a set of edges), which defines the border of a topological disc. These edges can be passed together with -the mesh to a `Seam_mesh`. +a mesh to a `Seam_mesh`. \cgalFigureBegin{Surface_mesh_parameterizationfigcut,cut.png} Cut Graph \cgalFigureEnd +In the following example, we apply the default parameterization to a +`Polyhedron_3`-based `Seam_mesh`. We store the UV-coordinates as a +halfedge property using a `Unique_hash_map`. -\cgalExample{Surface_mesh_parameterization/seam.cpp} - +Note that vertices on a seam are duplicated in a `Seam_mesh` structure +and thus the UV-coordinates are here associated to halfedges of the +seam mesh. +\cgalExample{Surface_mesh_parameterization/seam_Polyhedron_3.cpp} \section Surface_mesh_parameterizationComplexity Complexity and Guarantees diff --git a/Surface_mesh_parameterization/doc/Surface_mesh_parameterization/examples.txt b/Surface_mesh_parameterization/doc/Surface_mesh_parameterization/examples.txt index 122d7ba8110..1599a25c1b9 100644 --- a/Surface_mesh_parameterization/doc/Surface_mesh_parameterization/examples.txt +++ b/Surface_mesh_parameterization/doc/Surface_mesh_parameterization/examples.txt @@ -1,6 +1,6 @@ /*! - \example Surface_mesh_parameterization/Simple_parameterization.cpp + \example Surface_mesh_parameterization/simple_parameterization.cpp \example Surface_mesh_parameterization/discrete_authalic.cpp - \example Surface_mesh_parameterization/seam.cpp + \example Surface_mesh_parameterization/seam_Polyhedron_3.cpp \example Surface_mesh_parameterization/lscm.cpp */ diff --git a/Surface_mesh_parameterization/include/CGAL/Fixed_border_parameterizer_3.h b/Surface_mesh_parameterization/include/CGAL/Fixed_border_parameterizer_3.h index d4677655709..501f2dfc343 100644 --- a/Surface_mesh_parameterization/include/CGAL/Fixed_border_parameterizer_3.h +++ b/Surface_mesh_parameterization/include/CGAL/Fixed_border_parameterizer_3.h @@ -216,7 +216,7 @@ protected: } } - /// Compute w_ij = (i, j) coefficient of matrix A for j neighbor vertex of i. + /// Compute w_ij, coefficient of matrix A for j neighbor vertex of i. /// Implementation note: Subclasses must at least implement compute_w_ij(). /// /// \param mesh a triangulated surface.