diff --git a/Surface_mesh_parameterization/doc/Surface_mesh_parameterization/PackageDescription.txt b/Surface_mesh_parameterization/doc/Surface_mesh_parameterization/PackageDescription.txt index a71fc081194..310d87f05cd 100644 --- a/Surface_mesh_parameterization/doc/Surface_mesh_parameterization/PackageDescription.txt +++ b/Surface_mesh_parameterization/doc/Surface_mesh_parameterization/PackageDescription.txt @@ -41,23 +41,26 @@ This \cgal package implements several parameterization methods: - Fixed border: - Tutte Barycentric Mapping \cgalCite{t-hdg-63} : One-to-one mapping is guaranteed for convex border. + - Discrete Authalic Parameterization \cgalCite{cgal:dma-ipsm-02} : + Conditionally guaranteed if all weights are positive and border is convex. + - Discrete Conformal Map \cgalCite{cgal:eddhls-maam-95} : + Conditionally guaranteed if all weights are positive and border is convex. - Floater Mean Value Coordinates \cgalCite{cgal:f-mvc-03} : One-to-one mapping is guaranteed for convex border. - - Discrete Conformal Map \cgalCite{cgal:eddhls-maam-95} : - Conditionally guaranteed if all weights are positive and border is convex. - - Discrete Authalic parameterization \cgalCite{cgal:dma-ipsm-02} : - Conditionally guaranteed if all weights are positive and border is convex. - Free border: - - As Rigid As Possible Maps \cgalCite{liu2008local} + - As Rigid As Possible Parameterization \cgalCite{liu2008local} - Least Squares Conformal Maps \cgalCite{cgal:lprm-lscm-02}. +- Borderless: + - Orbifold Tutte Embeddings \cgalCite{aigerman2015orbifold}. -- `CGAL::Surface_mesh_parameterization::Fixed_border_parameterizer_3` -- `CGAL::Surface_mesh_parameterization::ARAP_parameterizer_3` -- `CGAL::Surface_mesh_parameterization::Barycentric_mapping_parameterizer_3` -- `CGAL::Surface_mesh_parameterization::Discrete_authalic_parameterizer_3` -- `CGAL::Surface_mesh_parameterization::Discrete_conformal_map_parameterizer_3` -- `CGAL::Surface_mesh_parameterization::LSCM_parameterizer_3` -- `CGAL::Surface_mesh_parameterization::Mean_value_coordinates_parameterizer_3` +- `CGAL::Surface_mesh_parameterization::Fixed_border_parameterizer_3` +- `CGAL::Surface_mesh_parameterization::ARAP_parameterizer_3` +- `CGAL::Surface_mesh_parameterization::Barycentric_mapping_parameterizer_3` +- `CGAL::Surface_mesh_parameterization::Discrete_authalic_parameterizer_3` +- `CGAL::Surface_mesh_parameterization::Discrete_conformal_map_parameterizer_3` +- `CGAL::Surface_mesh_parameterization::LSCM_parameterizer_3` +- `CGAL::Surface_mesh_parameterization::Mean_value_coordinates_parameterizer_3` +- `CGAL::Surface_mesh_parameterization::Orbifold_Tutte_parameterizer_3` ## Border Parameterization Methods ## @@ -99,6 +102,10 @@ The package performs the next checks: - Preconditions: - the input mesh is triangular. - the input mesh is a surface with one connected component. +- For borderless parameterizations: + - Preconditions: + - the input mesh is triangular. + - the input mesh is a surface with one connected component. */ /// \defgroup PkgSurfaceParameterizationMainFunction Main Function @@ -128,6 +135,8 @@ This \cgal package implements several parameterization methods: - Free border: - As Rigid As Possible Maps \cgalCite{liu2008local} - Least Squares Conformal Maps \cgalCite{cgal:lprm-lscm-02}. + - Borderless: + - Orbifold Tutte Embeddings \cgalCite{aigerman2015orbifold} */ /*! 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 96b2c2de9d9..2c2aa6fb601 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 @@ -26,14 +26,14 @@ transparency, reflection or light modulation maps), fitting scattered data, re-parameterizing spline surfaces, repairing CAD models, approximating surfaces and remeshing. -This \cgal package implements -surface parameterization methods, such as As Rigid As Possible Parameterization, -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 +This \cgal package implements surface parameterization methods, such as +As Rigid As Possible Parameterization, Tutte Barycentric Mapping, +Discrete Authalic Parameterization, Discrete Conformal Maps, +Least Squares Conformal Maps, Floater Mean Value Coordinates, or Orbifold Tutte Embeddings. +These methods mainly distinguish by the distortion they minimize (angles vs. areas), by the constrained border onto the -planar domain (convex polygon vs. free border) and by the guarantees -provided in terms of bijective mapping. +planar domain (convex polygon vs. free border) and by the bijectivity guarantees +of the mapping. The package proposes an interface for any model of the concept `FaceGraph`, such as the classes `Surface_mesh`, `Polyhedron_3`, or the mesh @@ -102,12 +102,12 @@ Error_code parameterize(TriangleMesh& mesh, 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 +A one-to-one mapping may be guaranteed or not, depending on the choice of the Parameterizer_3 algorithm. -In the following example, we use a circular border parameterization -and then use the discrete authalic parameterizer with a -`Surface_mesh`. We store the UV-coordinates as a vertex property +In the following example, we use the Discrete Authalic parameterizer with a +a circular border parameterization. +We use a `Surface_mesh` for the mesh and store the UV-coordinates as a vertex property using the `Surface_mesh` built-in property mechanism. \cgalExample{Surface_mesh_parameterization/discrete_authalic.cpp} @@ -135,7 +135,7 @@ The Barycentric Mapping parameterization method has been introduced by Tutte \cgalCite{t-hdg-63}. In parameter space, each vertex is placed at the barycenter of its neighbors to achieve the so-called convex combination condition. This algorithm amounts to solve one -sparse linear solver for each set of parameter coordinates, with a +sparse linear system for each set of parameter coordinates, with a \#vertices x \#vertices sparse and symmetric positive definite matrix (if the border vertices are eliminated from the linear system). A coefficient \f$ (i, j)\f$ of the matrix is set to 1 for an edge linking @@ -145,54 +145,14 @@ entry. Although a bijective mapping is guaranteed when the border is convex, this method does not minimize angles nor areas distortion. \cgalFigureBegin{Surface_mesh_parameterizationfiguniform,uniform.png} -Left: Tutte barycentric mapping parameterization (the red line depicts the cut graph). Right: parameter space. -\cgalFigureEnd - -\subsubsection Surface_mesh_parameterizationDiscreteConformal Discrete Conformal Map - -`Surface_mesh_parameterization::Discrete_conformal_map_parameterizer_3` - -Discrete conformal map parameterization has been introduced to the graphics community -by Eck et al. \cgalCite{cgal:eddhls-maam-95}. It attempts to -lower angle deformation by minimizing a discrete version of the -Dirichlet energy as derived by Pinkall and -Polthier \cgalCite{cgal:pp-cdmsc-93}. A one-to-one mapping is guaranteed -only when the two following conditions are fulfilled: the barycentric mapping -condition (each vertex in parameter space is a convex combination if -its neighboring vertices), and the border is convex. -This method solves two \#vertices x \#vertices sparse linear -systems. The matrix (the same for both systems) is sparse and symmetric definite -positive (if the border vertices are eliminated from the linear system -and if the mesh contains no hole), -thus can be efficiently solved using dedicated linear solvers. - -\cgalFigureBegin{Surface_mesh_parameterizationfigconformal,conformal.png} -Left: discrete conformal map. Right: parameter space. -\cgalFigureEnd - -\subsubsection Surface_mesh_parameterizationFloaterMean Floater Mean Value Coordinates - -`Surface_mesh_parameterization::Mean_value_coordinates_parameterizer_3` - -The mean value coordinates parameterization method has been introduced -by Floater \cgalCite{cgal:f-mvc-03}. Each vertex in parameter space is -optimized so as to be a convex combination of its neighboring -vertices. The barycentric coordinates are this time unconditionally -positive, by deriving an application of the mean theorem for harmonic -functions. This method is in essence an approximation of the discrete conformal -maps, with a guaranteed one-to-one mapping when the border is convex. -This method solves two \#vertices x \#vertices sparse linear systems. The matrix (the -same for both systems) is asymmetric. - -\cgalFigureBegin{Surface_mesh_parameterizationfigfloater,floater.png} -Floater Mean Value Coordinates +Left: Tutte Barycentric mapping parameterization (the red line depicts the cut graph). Right: parameter space. \cgalFigureEnd \subsubsection Surface_mesh_parameterizationDiscreteAuthalic Discrete Authalic Parameterization `Surface_mesh_parameterization::Discrete_authalic_parameterizer_3` -The discrete authalic parameterization method has been introduced by +The Discrete Authalic parameterization method has been introduced by Desbrun et al. \cgalCite{cgal:dma-ipsm-02}. It corresponds to a weak formulation of an area-preserving method, and in essence locally minimizes the area distortion. A one-to-one mapping is @@ -205,7 +165,47 @@ for both systems) is asymmetric. Discrete Authalic Parameterization \cgalFigureEnd -\subsection secBorderParameterizationsforFixedMethods Border Parameterizations for Fixed Methods +\subsubsection Surface_mesh_parameterizationDiscreteConformal Discrete Conformal Map + +`Surface_mesh_parameterization::Discrete_conformal_map_parameterizer_3` + +Discrete Conformal Map parameterization has been introduced to the graphics community +by Eck et al. \cgalCite{cgal:eddhls-maam-95}. It attempts to +lower angle deformation by minimizing a discrete version of the +Dirichlet energy as derived by Pinkall and +Polthier \cgalCite{cgal:pp-cdmsc-93}. A one-to-one mapping is guaranteed +only when the two following conditions are fulfilled: the barycentric mapping +condition (each vertex in parameter space is a convex combination of +its neighboring vertices), and the border is convex. +This method solves two \#vertices x \#vertices sparse linear +systems. The matrix (the same for both systems) is sparse and symmetric positive +definite(if the border vertices are eliminated from the linear system +and if the mesh contains no hole), +thus can be efficiently solved using dedicated linear solvers. + +\cgalFigureBegin{Surface_mesh_parameterizationfigconformal,conformal.png} +Left: Discrete Conformal Map. Right: parameter space. +\cgalFigureEnd + +\subsubsection Surface_mesh_parameterizationFloaterMean Floater Mean Value Coordinates + +`Surface_mesh_parameterization::Mean_value_coordinates_parameterizer_3` + +The mean value coordinates parameterization method has been introduced +by Floater \cgalCite{cgal:f-mvc-03}. Each vertex in parameter space is +optimized so as to be a convex combination of its neighboring +vertices. The barycentric coordinates are this time unconditionally +positive, by deriving an application of the mean theorem for harmonic +functions. This method is in essence an approximation of the Discrete Conformal +Map, with a guaranteed one-to-one mapping when the border is convex. +This method solves two \#vertices x \#vertices sparse linear systems. The matrix (the +same for both systems) is asymmetric. + +\cgalFigureBegin{Surface_mesh_parameterizationfigfloater,floater.png} +Floater Mean Value Coordinates +\cgalFigureEnd + +\subsubsection secBorderParameterizationsforFixedMethods Border Parameterizations for Fixed Methods Parameterization methods for borders are used as traits classes modifying the behavior of `Parameterizer_3` models. They are also provided as models of the @@ -246,7 +246,8 @@ the following classes: An illustration of the use of different border parameterizers can be found in the -example `Surface_mesh_parameterization/square_border_parameterizer.cpp`. +example \ref Surface_mesh_parameterization/square_border_parameterizer.cpp +"square_border_parameterizer.cpp". \subsection Surface_mesh_parameterizationFreeBorderSurface Free Border Surface Parameterizations @@ -264,7 +265,7 @@ is not guaranteed by this method. It solves a (2 \f$ \times\f$ which implies solving a symmetric matrix. \cgalFigureBegin{Surface_mesh_parameterizationfigLSCM,LSCM.png} -Least squares conformal maps. +Least Squares Conformal Maps. \cgalFigureEnd \subsubsection Surface_mesh_parameterizationARAP As Rigid As Possible Parameterization @@ -290,7 +291,7 @@ possible) when λ goes to infinity, or a balance of both. As Rigid As Possible parameterization (the cut is traced in red). \cgalFigureCaptionEnd -\subsection secBorderParameterizationsforFreeMethods Border Parameterizations for Free Methods +\subsubsection secBorderParameterizationsforFreeMethods Border Parameterizations for Free Methods Parameterization methods for borders are used as traits classes modifying the behavior of `Parameterizer_3` models. They are also provided as models of @@ -310,7 +311,7 @@ in the current version of this package. \subsection Surface_mesh_parameterizationBorderless Borderless Surface Parameterizations -\subsubsection Surface_mesh_parameterizationOrbi Orbifold Tutte Embedding +\subsubsection Surface_mesh_parameterizationOrbi Orbifold Tutte Embeddings `Surface_mesh_parameterization::Orbifold_Tutte_parameterizer_3` @@ -318,7 +319,7 @@ Orbifold-Tutte Planar Embedding was introduced by Aigerman and Lipman \cgalCite{ and is a generalization of Tutte’s embedding to other topologies, and in particular spheres. The orbifold-Tutte embedding bijectively maps the original surface to a canonical, topologically equivalent, two-dimensional flat surface called -a Euclidean orbifold. There are 17 Euclidean orbifolds, of which only the 4 sphere +an Euclidean orbifold. There are 17 Euclidean orbifolds, of which only the 4 sphere orbifolds are implemented here. The orbifold-Tutte embedding yields a seamless, globally bijective parameterization that, @@ -327,7 +328,7 @@ for its computation. The parameterization process internally requires the uses of seams, but the choice of these seams have no influence on the result. The `Seam_mesh` structure -(see also next Section) is used for this purpose. +(see also Section \ref secCuttingaMesh) is used for this purpose. \cgalFigureAnchor{Surface_mesh_parameterizationfigOrbifold}
@@ -375,15 +376,15 @@ seam mesh.
  • One-to-one mapping Tutte's theorem guarantees a one-to-one mapping provided that the weights are all positive -and the border convex. -It is the case for Tutte barycentric mapping and Floater mean value coordinates. -It is not always the case for discrete conformal map (cotangents) and -discrete authalic parameterization. +and the border is convex. +It is the case for Tutte Barycentric Mapping and Floater Mean Value Coordinates. +It is not always the case for Discrete Conformal Map (cotangents) and +Discrete Authalic parameterization.
  • 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). +This is the case with positive weights (Tutte Barycentric Mapping and Floater Mean Value Coordinates). @@ -403,7 +404,7 @@ and is therefore non-singular (Gram theorem). -
  • Boundaryless +
  • Boundary-less
      diff --git a/Surface_mesh_parameterization/examples/Surface_mesh_parameterization/discrete_authalic.cpp b/Surface_mesh_parameterization/examples/Surface_mesh_parameterization/discrete_authalic.cpp index fbde3a5a8b9..23cb0787dd1 100644 --- a/Surface_mesh_parameterization/examples/Surface_mesh_parameterization/discrete_authalic.cpp +++ b/Surface_mesh_parameterization/examples/Surface_mesh_parameterization/discrete_authalic.cpp @@ -30,10 +30,13 @@ namespace SMP = CGAL::Surface_mesh_parameterization; int main(int argc, char * argv[]) { - SurfaceMesh sm; - std::ifstream in((argc>1) ? argv[1] : "data/nefertiti.off"); + if(!in) { + std::cerr << "Problem loading the input data" << std::endl; + return 1; + } + SurfaceMesh sm; in >> sm; halfedge_descriptor bhd = CGAL::Polygon_mesh_processing::longest_border(sm).first; diff --git a/Surface_mesh_parameterization/examples/Surface_mesh_parameterization/lscm.cpp b/Surface_mesh_parameterization/examples/Surface_mesh_parameterization/lscm.cpp index 3fd6129d1a1..133889070c8 100644 --- a/Surface_mesh_parameterization/examples/Surface_mesh_parameterization/lscm.cpp +++ b/Surface_mesh_parameterization/examples/Surface_mesh_parameterization/lscm.cpp @@ -42,14 +42,13 @@ namespace SMP = CGAL::Surface_mesh_parameterization; int main(int argc, char * argv[]) { - SurfaceMesh sm; - std::ifstream in_mesh((argc>1) ? argv[1] : "data/lion.off"); if(!in_mesh){ std::cerr << "Error: problem loading the input data" << std::endl; return 1; } + SurfaceMesh sm; in_mesh >> sm; // Two property maps to store the seam edges and vertices diff --git a/Surface_mesh_parameterization/examples/Surface_mesh_parameterization/orbifold.cpp b/Surface_mesh_parameterization/examples/Surface_mesh_parameterization/orbifold.cpp index 29229b30ba9..d97a48e1622 100644 --- a/Surface_mesh_parameterization/examples/Surface_mesh_parameterization/orbifold.cpp +++ b/Surface_mesh_parameterization/examples/Surface_mesh_parameterization/orbifold.cpp @@ -53,14 +53,14 @@ int main(int argc, char * argv[]) CGAL::Timer task_timer; task_timer.start(); - SurfaceMesh sm; // underlying mesh of the seam mesh - const char* mesh_filename = (argc>1) ? argv[1] : "../data/bear.off"; std::ifstream in_mesh(mesh_filename); if(!in_mesh) { std::cerr << "Error: problem loading the input data" << std::endl; return 1; } + + SurfaceMesh sm; // underlying mesh of the seam mesh in_mesh >> sm; // Selection file that contains the cones and possibly the path between cones diff --git a/Surface_mesh_parameterization/examples/Surface_mesh_parameterization/seam_Polyhedron_3.cpp b/Surface_mesh_parameterization/examples/Surface_mesh_parameterization/seam_Polyhedron_3.cpp index 21acd72e520..16eb8314287 100644 --- a/Surface_mesh_parameterization/examples/Surface_mesh_parameterization/seam_Polyhedron_3.cpp +++ b/Surface_mesh_parameterization/examples/Surface_mesh_parameterization/seam_Polyhedron_3.cpp @@ -42,14 +42,13 @@ namespace SMP = CGAL::Surface_mesh_parameterization; int main(int argc, char * argv[]) { - PolyMesh sm; - std::ifstream in_mesh((argc>1)?argv[1]:"data/lion.off"); if(!in_mesh) { std::cerr << "Error: problem loading the input data" << std::endl; return 1; } + PolyMesh sm; in_mesh >> sm; // Two property maps to store the seam edges and vertices @@ -73,7 +72,7 @@ int main(int argc, char * argv[]) UV_uhm uv_uhm; UV_pmap uv_pm(uv_uhm); - // a halfedge on the (possibly virtual) border + // A halfedge on the (possibly virtual) border halfedge_descriptor bhd = CGAL::Polygon_mesh_processing::longest_border(mesh).first; SMP::parameterize(mesh, bhd, uv_pm); diff --git a/Surface_mesh_parameterization/package_info/Surface_mesh_parameterization/description.txt b/Surface_mesh_parameterization/package_info/Surface_mesh_parameterization/description.txt index 9dad6b845fe..673f53ddb95 100644 --- a/Surface_mesh_parameterization/package_info/Surface_mesh_parameterization/description.txt +++ b/Surface_mesh_parameterization/package_info/Surface_mesh_parameterization/description.txt @@ -6,12 +6,12 @@ surfaces that are homeomorphic to a disk and on piecewise linear mappings into a planar domain. This CGAL package implements several surface mesh parameterization -methods, such as As Rigid As Possible Parameterization, Least Squares Conformal Maps, -Discrete Conformal Map, Discrete Authalic Parameterization,Floater Mean Value Coordinates or -Tutte Barycentric Mapping. +methods, such as As Rigid As Possible Parameterization, Tutte Barycentric Mapping, +Discrete Authalic Parameterization, Discrete Conformal Map, Least Squares Conformal Maps, +Floater Mean Value Coordinates, or Orbifold Tutte Embeddings. The package proposes an interface with the Boost Graph Library API data structure. -It can thus be used either with Polyhedron_3, Surface_mesh, or any class model of the concept FaceGraph. +It can thus be used either with Polyhedron_3, Surface_mesh, or any class model of the concept `FaceGraph`. Since parameterizing meshes requires an efficient representation of sparse matrices and efficient iterative or direct linear solvers, we provide links to the standard