songsenand
/
cgal
mirror of https://github.com/CGAL/cgal
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

start rewriting the doc

This commit is contained in:
Andreas Fabri 2016-05-23 09:42:00 +02:00 committed by Mael Rouxel-Labbé
parent fa68850338
commit afc6476992
18 changed files with 161 additions and 935 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

31
Surface_mesh_parameterization/doc/Surface_mesh_parameterization/Concepts/BorderParameterizer_3.h
View File

@ -3,28 +3,16 @@
\ingroup PkgSurfaceParameterizationConcepts
\cgalConcept
`BorderParameterizer_3` is a concept of class that parameterizes a given type of mesh, `Adaptor`, which is a model of the `ParameterizationMesh_3` concept.
`BorderParameterizer_3` is a concept of class that parameterizes a given type of mesh, `TriangleMesh`, which is a model of the `FaceGraph` concept.
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.
Design Pattern
--------------
`BorderParameterizer_3` models are Strategies \cgalCite{cgal:ghjv-dpero-95} : they implement a strategy of border parameterization for models of `ParameterizationMesh_3`.
Creation
--------------
Construction and destruction are undefined.
\cgalHasModel `CGAL::Circular_border_arc_length_parameterizer_3<ParameterizationMesh_3>`
\cgalHasModel `CGAL::Circular_border_uniform_parameterizer_3<ParameterizationMesh_3>`
\cgalHasModel `CGAL::Square_border_arc_length_parameterizer_3<ParameterizationMesh_3>`
\cgalHasModel `CGAL::Square_border_uniform_parameterizer_3<ParameterizationMesh_3>`
\cgalHasModel `CGAL::Two_vertices_parameterizer_3<ParameterizationMesh_3>`
\cgalHasModel `CGAL::Circular_border_arc_length_parameterizer_3<TriangleMesh>`
\cgalHasModel `CGAL::Circular_border_uniform_parameterizer_3<TriangleMesh>`
\cgalHasModel `CGAL::Square_border_arc_length_parameterizer_3<TriangleMesh>`
\cgalHasModel `CGAL::Square_border_uniform_parameterizer_3<TriangleMesh>`
\cgalHasModel `CGAL::Two_vertices_parameterizer_3<TriangleMesh>`
\sa `ParameterizerTraits_3`
\sa `ParameterizationMesh_3`
*/
@ -33,14 +21,11 @@ public:
/// \name Types
/// @{
/*!
Export `ParameterizationMesh_3` template parameter.
*/
typedef unspecified_type Adaptor;
typedef unspecified_type TriangleMesh;
/*!
The various errors detected by this package.
@ -58,7 +43,7 @@ typedef unspecified_type Error_code;
Assign to mesh's border vertices a 2D position (i.e.\ a `(u, v)` pair) on border's shape. Mark them as <I>parameterized</I>. Return false on error.
*/
Error_code parameterize_border(Adaptor& mesh);
Error_code parameterize_border(const TriangleMesh& mesh);
/*!

404
Surface_mesh_parameterization/doc/Surface_mesh_parameterization/Concepts/ParameterizationMesh_3.h
View File

@ -1,404 +0,0 @@
/*!
\ingroup PkgSurfaceParameterizationConcepts
\cgalConcept
`ParameterizationMesh_3` is a concept for a 3D surface mesh. Its main purpose is to allow the parameterization methods to access meshes in a uniform manner.
A `ParameterizationMesh_3` surface consists of vertices, facets and an incidence relation on them. No notion of edge is requested. Vertices represent points in 3d-space. Facets are planar polygons without holes defined by the circular sequence of vertices along their border. The surface itself can have holes. The vertices along the border of a hole are called <I>border vertices</I>. A surface is <I>closed</I> if it contains no border vertices.
The surface must be an oriented 2-manifold with border vertices, i.e.\ the neighborhood of each point on the surface is either homeomorphic to a disc or to a half disc, except for vertices where many holes and surfaces with border can join.
`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. On the other hand, as parameterization methods deal only with topological disks, `ParameterizationMesh_3` defines an interface oriented towards topological disks.
Design Pattern
--------------
`ParameterizationMesh_3` is an Adaptor \cgalCite{cgal:ghjv-dpero-95} : it changes the interface of a 3D mesh to match the interface expected by the parameterization methods.
Creation
--------------
Construction and destruction are undefined.
We provide 2 models of this concept:
\cgalHasModel `CGAL::Parameterization_polyhedron_adaptor_3<Polyhedron_3_>`
\cgalHasModel `CGAL::Parameterization_mesh_patch_3<ParameterizationPatchableMesh_3>`
\sa `ParameterizationPatchableMesh_3`
*/
class ParameterizationMesh_3 {
public:
/// \name Types
/// The following mutable handles, iterators, and circulators have appropriate non-mutable counterparts, i.e.\ `const_handle`, `const_iterator`, and `const_circulator`. The mutable types are assignable to their non-mutable counterparts. Both circulators are assignable to the `Vertex_iterator`. The iterators are assignable to the respective handle types. Wherever the handles appear in function parameter lists, the corresponding iterators can be used as well.
/// @{
/*!
Number type to represent coordinates.
*/
typedef unspecified_type NT;
/*!
2D point that represents (u, v) coordinates computed by parameterization methods. Must provide `x()` and `y()` methods.
*/
typedef unspecified_type Point_2;
/*!
3D point that represents vertices coordinates. Must provide `x()`, `y()` and `z()` methods.
*/
typedef unspecified_type Point_3;
/*!
2D vector. Must provide `x()` and `y()` methods.
*/
typedef unspecified_type Vector_2;
/*!
3D vector. Must provide `x()`, `y()` and `z()` methods.
*/
typedef unspecified_type Vector_3;
/*!
Opaque type representing a facet of the 3D mesh. No methods are expected.
*/
typedef unspecified_type Facet;
/*!
Handle to a facet. Model of the Handle concept.
*/
typedef unspecified_type Facet_handle;
/*!
*/
typedef unspecified_type Facet_const_handle;
/*!
Iterator over all mesh facets. Model of the `ForwardIterator` concept.
*/
typedef unspecified_type Facet_iterator;
/*!
*/
typedef unspecified_type Facet_const_iterator;
/*!
Opaque type representing a vertex of the 3D mesh. No methods are expected.
*/
typedef unspecified_type Vertex;
/*!
Handle to a vertex. Model of the Handle concept.
*/
typedef unspecified_type Vertex_handle;
/*!
*/
typedef unspecified_type Vertex_const_handle;
/*!
Iterator over all vertices of a mesh. Model of the `ForwardIterator` concept.
*/
typedef unspecified_type Vertex_iterator;
/*!
*/
typedef unspecified_type Vertex_const_iterator;
/*!
Iterator over vertices of the mesh <I>main border</I>. Model of the `ForwardIterator` concept.
*/
typedef unspecified_type Border_vertex_iterator;
/*!
*/
typedef unspecified_type Border_vertex_const_iterator;
/*!
Counter-clockwise circulator over a facet's vertices. Model of the `BidirectionalCirculator` concept.
*/
typedef unspecified_type Vertex_around_facet_circulator;
/*!
*/
typedef unspecified_type Vertex_around_facet_const_circulator;
/*!
Clockwise circulator over the vertices incident to a vertex. Model of the `BidirectionalCirculator` concept.
*/
typedef unspecified_type Vertex_around_vertex_circulator;
/*!
*/
typedef unspecified_type Vertex_around_vertex_const_circulator;
/// @}
/// \name Operations
/// The following mutable methods returning a handle, iterator, or circulator have appropriate non-mutable counterpart methods, i.e.\ `const`, returning a `const_handle`, `const_iterator`, or `const_circulator`.
/// @{
/*!
Indicate if the mesh matches the `ParameterizationMesh_3` concept.
*/
bool is_valid() const;
/*!
Get iterator over first vertex of mesh.
*/
Vertex_iterator mesh_vertices_begin();
/*!
*/
Vertex_const_iterator mesh_vertices_begin() const;
/*!
Get iterator over past-the-end vertex of mesh.
*/
Vertex_iterator mesh_vertices_end();
/*!
*/
Vertex_const_iterator mesh_vertices_end() const;
/*!
Count the number of vertices of the mesh.
*/
int count_mesh_vertices() const;
/*!
Index vertices of the mesh from 0 to `count_mesh_vertices`()-1.
*/
void index_mesh_vertices();
/*!
Get iterator over first vertex of mesh's <I>main border</I>.
*/
Border_vertex_iterator mesh_main_border_vertices_begin();
/*!
*/
Border_vertex_const_iterator mesh_main_border_vertices_begin() const;
/*!
Get iterator over past-the-end vertex of mesh's <I>main border</I>.
*/
Border_vertex_iterator mesh_main_border_vertices_end();
/*!
*/
Border_vertex_const_iterator mesh_main_border_vertices_end() const;
/*!
Return the border containing `seed_vertex`. Return an empty list if not found.
*/
std::list<Vertex_handle> get_border(Vertex_handle seed_vertex);
/*!
Get iterator over first facet of mesh.
*/
Facet_iterator mesh_facets_begin();
/*!
*/
Facet_const_iterator mesh_facets_begin() const;
/*!
Get iterator over past-the-end facet of mesh.
*/
Facet_iterator mesh_facets_end();
/*!
*/
Facet_const_iterator mesh_facets_end() const;
/*!
Count the number of facets of the mesh.
*/
int count_mesh_facets() const;
/*!
Return true of all mesh's facets are triangles.
*/
bool is_mesh_triangular() const;
/*!
Count the number of halfedges of the mesh.
*/
int count_mesh_halfedges() const;
/*!
Get circulator over facet's vertices.
*/
Vertex_around_facet_circulator facet_vertices_begin(Facet_handle facet);
/*!
*/
Vertex_around_facet_const_circulator facet_vertices_begin(Facet_const_handle facet) const;
/*!
Count the number of vertices of a facet.
*/
int count_facet_vertices(Facet_const_handle facet) const;
/*!
Get the 3D position of a vertex.
*/
Point_3 get_vertex_position(Vertex_const_handle vertex) const;
/*!
Get/set the 2D position (u/v pair) of a vertex. Default value is undefined.
*/
Point_2 get_vertex_uv(Vertex_const_handle vertex) const;
/*!
*/
void set_vertex_uv(Vertex_handle vertex, const Point_2& uv);
/*!
Get/set <I>is parameterized</I> field of vertex. Default value is undefined.
*/
bool is_vertex_parameterized(Vertex_const_handle vertex) const;
/*!
*/
void set_vertex_parameterized(Vertex_handle vertex, bool parameterized);
/*!
Get/set vertex index. Default value is undefined.
*/
int get_vertex_index(Vertex_const_handle vertex) const;
/*!
*/
void set_vertex_index(Vertex_handle vertex, int index);
/*!
Get/set vertex' all purpose tag. Default value is undefined.
*/
int get_vertex_tag(Vertex_const_handle vertex) const;
/*!
*/
void set_vertex_tag(Vertex_handle vertex, int tag);
/*!
Return true if a vertex belongs to ANY mesh's border.
*/
bool is_vertex_on_border(Vertex_const_handle vertex) const;
/*!
Return true if a vertex belongs to the UNIQUE mesh's main border.
*/
bool is_vertex_on_main_border(Vertex_const_handle vertex) const;
/*!
Get circulator over the vertices incident to `vertex`. `start_position` defines the optional initial position of the circulator.
*/
Vertex_around_vertex_circulator vertices_around_vertex_begin(Vertex_handle vertex, Vertex_handle start_position = Vertex_handle());
/*!
*/
Vertex_around_vertex_const_circulator vertices_around_vertex_begin(Vertex_const_handle vertex, Vertex_const_handle start_position = Vertex_const_handle()) const;
/// @}
}; /* end ParameterizationMesh_3 */

110
Surface_mesh_parameterization/doc/Surface_mesh_parameterization/Concepts/ParameterizationPatchableMesh_3.h
View File

@ -1,110 +0,0 @@
/*!
\ingroup PkgSurfaceParameterizationConcepts
\cgalConcept
`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. <I>Patches</I> are a subset of a 3D mesh. <I>Virtual seams</I> are the ability 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. the fields specific to parameterizations (index, u, v, `is_parameterized`) can be set per <I>corner</I> (aka half-edge).
The main purpose of this feature is to allow the `Surface_mesh_parameterization` package to parameterize any 3D surface by decomposing it as a list of topological disks.
Design Pattern
--------------
`ParameterizationPatchableMesh_3` is an Adaptor \cgalCite{cgal:ghjv-dpero-95} : it changes the interface of a 3D mesh to match the interface expected by class `Parameterization_mesh_patch_3`.
\cgalRefines `ParameterizationMesh_3`
Creation
--------------
Construction and destruction are undefined.
\cgalHasModel Adaptator for `Polyhedron_3` is provided: `CGAL::Parameterization_polyhedron_adaptor_3<Polyhedron_3_>`
\sa `ParameterizationMesh_3`
*/
class ParameterizationPatchableMesh_3 {
public:
/// \name Operations
/// @{
/*!
%Get vertex seaming flag. Default value is undefined.
*/
int get_vertex_seaming(Vertex_const_handle vertex) const;
/*!
Set vertex seaming flag. Default value is undefined.
*/
void set_vertex_seaming(Vertex_handle vertex, int seaming);
/*!
%Get oriented edge's seaming flag, i.e.\ position of the oriented edge w.r.t.\ to the UNIQUE main border.
*/
int get_halfedge_seaming(Vertex_const_handle source, Vertex_const_handle target) const;
/*!
Set oriented edge's seaming flag, i.e.\ position of the oriented edge w.r.t.\ to the UNIQUE main border.
*/
void set_halfedge_seaming(Vertex_handle source, Vertex_handle target, int seaming);
/*!
%Get the 2D position (= (u, v) pair) of corners at the <I>right</I> of the `prev_vertex -> vertex -> next_vertex` line. Default value is undefined.
*/
Point_2 get_corners_uv(Vertex_const_handle vertex, Vertex_const_handle prev_vertex, Vertex_const_handle next_vertex) const;
/*!
Set the 2D position (= (u, v) pair) of corners at the <I>right</I> of the `prev_vertex -> vertex -> next_vertex` line. Default value is undefined.
*/
void set_corners_uv(Vertex_handle vertex, Vertex_const_handle prev_vertex, Vertex_const_handle next_vertex, const Point_2& uv);
/*!
%Get <I>is parameterized</I> field of corners at the <I>right</I> of the `prev_vertex -> vertex -> next_vertex` line. Default value is undefined.
*/
bool are_corners_parameterized(Vertex_const_handle vertex, Vertex_const_handle prev_vertex, Vertex_const_handle next_vertex) const;
/*!
Set <I>is parameterized</I> field of corners at the <I>right</I> of the `prev_vertex -> vertex -> next_vertex` line. Default value is undefined.
*/
void set_corners_parameterized(Vertex_handle vertex, Vertex_const_handle prev_vertex, Vertex_const_handle next_vertex, bool parameterized);
/*!
%Get index of corners at the <I>right</I> of the `prev_vertex -> vertex -> next_vertex` line. Default value is undefined.
*/
int get_corners_index(Vertex_const_handle vertex, Vertex_const_handle prev_vertex, Vertex_const_handle next_vertex) const;
/*!
Set index of corners at the <I>right</I> of the `prev_vertex -> vertex -> next_vertex` line. Default value is undefined.
*/
void set_corners_index(Vertex_handle vertex, Vertex_const_handle prev_vertex, Vertex_const_handle next_vertex, int index);
/*!
%Get all purpose tag of corners at the <I>right</I> of the `prev_vertex -> vertex -> next_vertex` line. Default value is undefined.
*/
int get_corners_tag(Vertex_const_handle vertex, Vertex_const_handle prev_vertex, Vertex_const_handle next_vertex) const;
/*!
Set all purpose tag of corners at the <I>right</I> of the `prev_vertex -> vertex -> next_vertex` line. Default value is undefined.
*/
void set_corners_tag(Vertex_handle vertex, Vertex_const_handle prev_vertex, Vertex_const_handle next_vertex, int tag);
/// @}
}; /* end ParameterizationPatchableMesh_3 */

20
Surface_mesh_parameterization/doc/Surface_mesh_parameterization/Concepts/ParameterizerTraits_3.h
View File

@ -3,7 +3,7 @@
\ingroup PkgSurfaceParameterizationConcepts
\cgalConcept
`ParameterizerTraits_3` is a concept of parameterization object for a given type of mesh, `Adaptor`, which is a model of the `ParameterizationMesh_3` concept.
`ParameterizerTraits_3` is a concept of parameterization object for a given type of mesh, `TriangleMesh`, which must be a model of the `FaceGraph` concept.
Design Pattern
--------------
@ -15,15 +15,13 @@ Creation
Construction and destruction are undefined.
\cgalHasModel `CGAL::Parameterizer_traits_3<ParameterizationMesh_3>`
\cgalHasModel `CGAL::Fixed_border_parameterizer_3<ParameterizationMesh_3, BorderParameterizer_3, SparseLinearAlgebraTraits_d>`
\cgalHasModel `CGAL::Barycentric_mapping_parameterizer_3<ParameterizationMesh_3, BorderParameterizer_3, SparseLinearAlgebraTraits_d>`
\cgalHasModel `CGAL::Discrete_authalic_parameterizer_3<ParameterizationMesh_3, BorderParameterizer_3, SparseLinearAlgebraTraits_d>`
\cgalHasModel `CGAL::Discrete_conformal_map_parameterizer_3<ParameterizationMesh_3, BorderParameterizer_3, SparseLinearAlgebraTraits_d>`
\cgalHasModel `CGAL::LSCM_parameterizer_3<ParameterizationMesh_3, BorderParameterizer_3, SparseLinearAlgebraTraits_d>`
\cgalHasModel `CGAL::Mean_value_coordinates_parameterizer_3<ParameterizationMesh_3, BorderParameterizer_3, SparseLinearAlgebraTraits_d>`
\sa `ParameterizationMesh_3`
\cgalHasModel `CGAL::Parameterizer_traits_3<TriangleMesh>`
\cgalHasModel `CGAL::Fixed_border_parameterizer_3<TriangleMesh, BorderParameterizer_3, SparseLinearAlgebraTraits_d>`
\cgalHasModel `CGAL::Barycentric_mapping_parameterizer_3<TriangleMesh, BorderParameterizer_3, SparseLinearAlgebraTraits_d>`
\cgalHasModel `CGAL::Discrete_authalic_parameterizer_3<TriangleMesh, BorderParameterizer_3, SparseLinearAlgebraTraits_d>`
\cgalHasModel `CGAL::Discrete_conformal_map_parameterizer_3<TriangleMesh, BorderParameterizer_3, SparseLinearAlgebraTraits_d>`
\cgalHasModel `CGAL::LSCM_parameterizer_3<TriangleMesh, BorderParameterizer_3, SparseLinearAlgebraTraits_d>`
\cgalHasModel `CGAL::Mean_value_coordinates_parameterizer_3<TriangleMesh, BorderParameterizer_3, SparseLinearAlgebraTraits_d>`
*/
@ -70,7 +68,7 @@ Compute a one-to-one mapping from a triangular 3D surface `mesh` to a piece of t
\pre `mesh` must be a surface with one connected component and no hole. `mesh` must be a triangular mesh.
*/
Error_code parameterize(Adaptor& mesh);
Error_code parameterize(TriangleMesh& mesh);
/// @}

41
Surface_mesh_parameterization/doc/Surface_mesh_parameterization/Concepts/PolyhedronTraitsWithKernel_3.h
View File

@ -1,41 +0,0 @@
/*!
\ingroup PkgSurfaceParameterizationConcepts
\cgalConcept
\anchor pagePolyTraitsRef
Required types for the `PolyhedronTraitsWithKernel_3` concept. This
geometric traits concept is used in the polyhedral surface data
structure `CGAL::Polyhedron_3<Traits>`. This concept provides
additional requirements to the `PolyhedronTraits_3` concept
required by `CGAL::Polyhedron_3<Traits>` used within the class
`CGAL::Parameterization_polyhedron_adaptor_3<Polyhedron_3_>`.
\cgalRefines `PolyhedronTraits_3`
\cgalHasModel `CGAL::Polyhedron_traits_3<Kernel>`
\cgalHasModel `CGAL::Polyhedron_traits_with_normals_3<Kernel>`
\cgalHasModel All models of the `CGAL::Kernel` concept such as `Simple_cartesian<FieldNumberType>`.
\sa `CGAL::Parameterization_polyhedron_adaptor_3<Polyhedron_3_>`
\sa `CGAL::Polyhedron_3<Traits>`
*/
class PolyhedronTraitsWithKernel_3 {
public:
/// \name Types
/// @{
/*!
a kernel type providing: a field type `FT`; 2D and 3D point types `Point_2`
and `Point_3`; 2D and 3D vector types `Vector_2` and `Vector_3`.
*/
typedef unspecified_type Kernel;
/// @}
}; /* end PolyhedronTraitsWithKernel_3 */

68
Surface_mesh_parameterization/doc/Surface_mesh_parameterization/PackageDescription.txt
View File

@ -29,9 +29,6 @@
- `ParameterizerTraits_3`
- `BorderParameterizer_3`
- `ParameterizationMesh_3`
- `ParameterizationPatchableMesh_3`
- `PolyhedronTraitsWithKernel_3`
## Surface Parameterization Methods ##
@ -89,42 +86,7 @@ The general definition of input meshes handled directly by `CGAL::parameterize()
- Oriented.
- Homeomorphic to a disc (may have holes).
This package provides a model of the `ParameterizationMesh_3` concept
to access `CGAL::Polyhedron_3<Traits>`:
- `CGAL::Parameterization_polyhedron_adaptor_3<Polyhedron_3_>`
The meshes supported <I>indirectly</I> by the package can be of any genus and
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).
The `CGAL::Parameterization_mesh_patch_3<ParameterizationPatchableMesh_3>`
class is responsible for <I>virtually</I> cutting
a patch in a `ParameterizationPatchableMesh_3` mesh.
The resulting patch is a topological
disk (if the input cutting path is correct)
and provides a `ParameterizationMesh_3` interface. It can be used as
parameter of `CGAL::parameterize()`.
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 provides an interface with `CGAL::Polyhedron_3<Traits>`:
- `CGAL::Parameterization_polyhedron_adaptor_3<Polyhedron_3_>`
## Output ##
A `(u,v)` pair is computed for each inner vertex (i.e.\ its halfedges share the same `(u,v)` pair), while a `(u,v)` pair is computed for each border halfedge. The user must iterate over the mesh halfedges to get the result.
## Helper Classes ##
- `CGAL::Parameterization_mesh_feature_extractor<ParameterizationMesh_3>`
## Checks and Assertions ##
@ -146,8 +108,6 @@ For <i>free</i> border parameterizations:
-Postconditions:
- check one-to-one mapping.
Assertions are optional checks. The assertion flags for the package
use `SURFACE_MESH_PARAMETERIZATION` in their names (e.g. `CGAL_SURFACE_MESH_PARAMETERIZATION_NO_ASSERTIONS`).
*/
@ -202,39 +162,13 @@ vertices).
The general definition of input meshes handled directly by `CGAL::parameterize()` is:
- Model of `ParameterizationMesh_3`.
- Model of `FaceGraph`.
- Triangulated.
- 2-manifold.
- Oriented.
- Homeomorphic to a disc (may have holes).
This package provides a model of the `ParameterizationMesh_3` concept
to access `CGAL::Polyhedron_3<Traits>`:
`CGAL::Parameterization_polyhedron_adaptor_3<Polyhedron_3_>`
The meshes supported <I>indirectly</I> by the package can be of any genus and
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).
The `CGAL::Parameterization_mesh_patch_3<ParameterizationPatchableMesh_3>`
class is responsible for <I>virtually</I> cutting
a patch in a `ParameterizationPatchableMesh_3` mesh.
The resulting patch is a topological
disk (if the input cutting path is correct)
and provides a `ParameterizationMesh_3` interface. It can be used as
parameter of `CGAL::parameterize()`.
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 provides an interface with `CGAL::Polyhedron_3<Traits>`:
`CGAL::Parameterization_polyhedron_adaptor_3<Polyhedron_3_>`
*/

276
Surface_mesh_parameterization/doc/Surface_mesh_parameterization/Surface_mesh_parameterization.txt
View File

@ -26,7 +26,7 @@ transparency, reflection or light modulation maps), fitting scattered
data, re-parameterizing spline surfaces, repairing CAD models,
approximating surfaces and remeshing.
This \cgal package implements some of the state-of-the-art
This \cgal package implements
surface parameterization methods, such as least squares conformal maps,
discrete conformal map, discrete authalic
parameterization, Floater mean value coordinates or Tutte barycentric
@ -35,8 +35,10 @@ minimize (angles vs. areas), by the constrained border onto the
planar domain (convex polygon vs. free border) and by the guarantees
provided in terms of bijective mapping.
The package proposes currently an interface with the `Polyhedron_3`
data structure.
The package proposes an interface for any model of the concept `FaceGraph`,
that is classes as `Polyhedron_3`, `Surface_mesh`, as well as mesh
classes of OpenMesh.
Since parameterizing meshes require efficient representation of sparse
matrices and efficient iterative or direct linear solvers, we provide
@ -46,10 +48,6 @@ 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.
The intended audience of this package is researchers, developers or
students developing algorithms around parameterization of triangle
meshes for geometry processing as well as for signal mapping on
triangulated surfaces.
\cgalFigureBegin{Surface_mesh_parameterizationfigintroduction,introduction.jpg}
Texture mapping via Least Squares Conformal Maps parameterization. Top: original mesh and texture. Bottom: parameterizedmesh (left: parameter space, right: textured mesh).
@ -63,60 +61,57 @@ From the user point of view, the simplest entry point to this package
is the following function:
\code{.cpp}
Parameterizer_traits_3<ParameterizationMesh_3>::Error_code parameterize (ParameterizationMesh_3 & mesh);
parameterize(TriangleMesh & mesh,
boost::graph_traits<TriangleMesh>::halfedge_descriptor bhd,
VertexUvMap uvm);
\endcode
The function `parameterize()` applies a default surface parameterization
method, namely Floater Mean Value Coordinates \cgalCite{cgal:f-mvc-03}, with an
arc-length circular border parameterization, and using a sparse
linear solver from the \ref thirdpartyEigen library. The `ParameterizationMesh_3` concept defines the input meshes handled by `parameterize()`. See Section \ref secInputMeshforparameterize. The result is stored into the `(u,v)` fields of the mesh halfedges.
The mesh must be a triangle mesh surface with one connected component.
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.
Note: `Parameterizer_traits_3<ParameterizationMesh_3>` is the (pure virtual) superclass of all surface parameterizations and defines the error codes.
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).
\subsection secInputMeshforparameterize Input Mesh for parameterize()
The result is stored in a property map for the mesh vertices.
The input meshes handled <I>directly</I> by `parameterize()` must be models of `ParameterizationMesh_3`, triangulated, 2-manifold, oriented, and homeomorphic to discs (possibly with holes).
The adapter class `Seam_mesh` enables to introduce virtual borders, so that one can parameterize
a mesh that is not a topological disk.
Note: `ParameterizationMesh_3` is a general concept to access a
polyhedral mesh. It is optimized for the `Surface_mesh_parameterization` package
only in the sense that it
defines the accessors to fields specific to the parameterization domain
(`index`, `u`, `v`, `is_parameterized`).
The extra constraints needed by the surface parameterization methods (triangulated,
2-manifold, homeomorphic to a disc) are not part of the concept and
are checked at runtime.
This package provides a model of the `ParameterizationMesh_3` concept
to access `Polyhedron_3<Traits>`:
\subsection secErrorCodes Error Codes
`Parameterization_polyhedron_adaptor_3<Polyhedron_3_>`
`Parameterizer_traits_3<TriangleMesh>` is the (pure virtual) superclass of all surface parameterizations and defines the error codes.
We will see later that `parameterize()` can support <I>indirectly</I>
meshes that are not topological disks.
\todo work out this subsection
\subsection Surface_mesh_parameterizationDefaultParameterization Default Parameterization Example
In the following example, we apply the default parameterization to a
`Polyhedron_3<Traits>` mesh (must be a topological disk).
Eventually, it extracts the result from halfedges and prints it.
`Polyhedron_3` mesh.
\cgalExample{Surface_mesh_parameterization/Simple_parameterization.cpp}
\subsection Surface_mesh_parameterizationEnhancedparameterize Enhanced parameterize() Function
\subsection Surface_mesh_parameterizationEnhancedparameterize Choosing a Parameterization Algorithm
This package provides a second `parameterize()` entry point
where the user can specify a parameterization method:
\code{.cpp}
Parameterizer_traits_3<ParameterizationMesh_3>::Error_code parameterize (ParameterizationMesh_3 & mesh, ParameterizerTraits_3 parameterizer);
parameterize(TriangleMesh& mesh,
ParameterizerTraits_3 parameterizer,
boost::graph_traits<TriangleMesh>::halfedge_descriptor bhd,
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. One-to-one mapping may be guaranteed or
not, depending on the chosen `ParametizerTraits_3` algorithm.
not, depending on the chosen `ParameterizerTraits_3` algorithm.
<br>
The mesh must be a triangle surface mesh with one
connected component, and the mesh border must be mapped onto a convex
@ -156,37 +151,26 @@ and \ref secBorderParameterizationsforFreeMethods.
This package solves sparse linear systems using solvers which are models
of `SparseLinearAlgebraTraits_d`. See Chapter \ref PkgSolverSummary.
\subsection Surface_mesh_parameterizationTheParameterizationMesh3 The ParameterizationMesh_3 and ParameterizationPatchableMesh_3 Concepts
\subsection Surface_mesh_parameterizationTheParameterizationMesh3 The TriangleMesh Concept
As described in Section \ref secInputMeshforparameterize the input
meshes handled by `parameterize()` must be models of the
`TriangleMesh` concept. The surface parameterization methods provided
by this package only support surfaces which are homeomorphic to disks,
possibly with holes. Nevertheless meshed with arbitrary topology and
number of connected components can be parameterized, provided that the
user specifies a <I>cut graph</I> (a set of edges) which is the border
of a topological disc.
As described in Section \ref secInputMeshforparameterize
the input meshes handled by `parameterize()`
must be models of the `ParameterizationMesh_3` concept. The surface parameterization methods provided by this package only support
surfaces which are homeomorphic to disks, possibly with holes. Nevertheless meshed with arbitrary topology and number of connected components can be parameterized, provided that the user specifies a <I>cut graph</I> (an oriented list of
vertices) which is the border of a topological disc. If no cut graph is
specified as input, the longest border of the input mesh is taken by default, the others being considered as holes.
For this purpose, the
`Parameterization_mesh_patch_3<ParameterizationPatchableMesh_3>`
class is responsible for <I>virtually</I> cutting
a patch into a `ParameterizationPatchableMesh_3` mesh.
The resulting patch is a topological
disk (if the input cutting path is correct)
and provides a `ParameterizationMesh_3` interface. It can be used as
parameter for the function `parameterize()`.
`ParameterizationPatchableMesh_3` inherits from `ParameterizationMesh_3`,
thus is a concept for a 3D surface mesh.
`ParameterizationPatchableMesh_3` adds the ability to support patches and
virtual seams. <I>Patches</I> are a subset of a 3D mesh.
<I>Virtual seams</I> behave as if the surface was cut along a cut graph. More information is provided in Section \ref secCuttingaMesh.
\section secSurfaceParameterizationMethods Surface Parameterization Methods
This \cgal package implements some of the state-of-the-art
surface parameterization methods, such as Least Squares Conformal Maps,
Discrete Conformal Map, Discrete Authalic
Parameterization, Floater Mean Value Coordinates or Tutte Barycentric
Mapping. These methods are provided as models of the
This \cgal package implements surface parameterization methods, such
as Least Squares Conformal Maps, Discrete Conformal Map, Discrete
Authalic Parameterization, Floater Mean Value Coordinates or Tutte
Barycentric Mapping. These methods are provided as models of the
`ParameterizerTraits_3` concept.
\subsection Surface_mesh_parameterizationFixedBorder Fixed Border Surface Parameterizations
@ -198,7 +182,7 @@ Such border parameterizations are described in Section
\subsection Surface_mesh_parameterizationTutteBarycentric Tutte Barycentric Mapping
`Barycentric_mapping_parameterizer_3<ParameterizationMesh_3, BorderParameterizer_3, SparseLinearAlgebraTraits_d>`
`Barycentric_mapping_parameterizer_3<TriangleMesh, BorderParameterizer_3, SparseLinearAlgebraTraits_d>`
The Barycentric Mapping parameterization method has been introduced by
Tutte \cgalCite{t-hdg-63}. In parameter space, each vertex is
@ -219,7 +203,7 @@ Left: Tutte barycentric mapping parameterization (the red line depicts the cut g
\subsection Surface_mesh_parameterizationDiscreteConformal Discrete Conformal Map
`Discrete_conformal_map_parameterizer_3<ParameterizationMesh_3, BorderParameterizer_3, SparseLinearAlgebraTraits_d>`
`Discrete_conformal_map_parameterizer_3<TriangleMesh, BorderParameterizer_3, SparseLinearAlgebraTraits_d>`
Discrete conformal map parameterization has been introduced by Eck et
al. to the graphics community \cgalCite{cgal:eddhls-maam-95}. It attempts to
@ -241,7 +225,7 @@ Left: discrete conformal map. Right: parameter space.
\subsection Surface_mesh_parameterizationFloaterMean Floater Mean Value Coordinates
`Mean_value_coordinates_parameterizer_3<ParameterizationMesh_3, BorderParameterizer_3, SparseLinearAlgebraTraits_d>`
`Mean_value_coordinates_parameterizer_3<TriangleMesh, BorderParameterizer_3, SparseLinearAlgebraTraits_d>`
The mean value coordinates parameterization method has been introduced
by Floater \cgalCite{cgal:f-mvc-03}. Each vertex in parameter space is
@ -259,7 +243,7 @@ Floater Mean Value Coordinates
\subsection Surface_mesh_parameterizationDiscreteAuthalic Discrete Authalic Parameterization
`Discrete_authalic_parameterizer_3<ParameterizationMesh_3, BorderParameterizer_3, SparseLinearAlgebraTraits_d>`
`Discrete_authalic_parameterizer_3<TriangleMesh, BorderParameterizer_3, SparseLinearAlgebraTraits_d>`
The discrete authalic parameterization method has been introduced by
Desbrun et al. \cgalCite{cgal:dma-ipsm-02}. It corresponds to
@ -306,13 +290,13 @@ parameterization is commonly used for texture mapping.
</UL>
`Circular_border_arc_length_parameterizer_3<ParameterizationMesh_3>`
`Circular_border_arc_length_parameterizer_3<TriangleMesh>`
`Circular_border_uniform_parameterizer_3<ParameterizationMesh_3>`
`Circular_border_uniform_parameterizer_3<TriangleMesh>`
`Square_border_arc_length_parameterizer_3<ParameterizationMesh_3>`
`Square_border_arc_length_parameterizer_3<TriangleMesh>`
`Square_border_uniform_parameterizer_3<ParameterizationMesh_3>`
`Square_border_uniform_parameterizer_3<TriangleMesh>`
\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.
@ -322,7 +306,7 @@ Left: Julius Cesar mask parameterization with Authalic/circular border. Right: J
\subsection Surface_mesh_parameterizationLeastSquares Least Squares Conformal Maps
`LSCM_parameterizer_3<ParameterizationMesh_3, BorderParameterizer_3, SparseLinearAlgebraTraits_d>`
`LSCM_parameterizer_3<TriangleMesh, BorderParameterizer_3, SparseLinearAlgebraTraits_d>`
The Least Squares Conformal Maps (LSCM) parameterization method has
been introduced by L&eacute;vy et al. \cgalCite{cgal:lprm-lscm-02}.
@ -347,11 +331,11 @@ parameterization methods define only two constraints: the pinned vertices.
<UL>
<LI>`Two_vertices_parameterizer_3<ParameterizationMesh_3>`
<LI>`Two_vertices_parameterizer_3<TriangleMesh>`
<I>Usage:</I>
`Two_vertices_parameterizer_3<ParameterizationMesh_3>` is the default
`Two_vertices_parameterizer_3<TriangleMesh>` is the default
free border parameterization, and is the only one available
in the current version of this package.
@ -374,10 +358,10 @@ differences with the first example \ref Surface_mesh_parameterization/Simple_pa
// Discrete Authalic Parameterization
//***************************************
typedef CGAL::Discrete_authalic_parameterizer_3<Parameterization_polyhedron_adaptor>
typedef CGAL::Discrete_authalic_parameterizer_3<Mesh>
Parameterizer;
Parameterizer::Error_code err = CGAL::parameterize(mesh_adaptor, Parameterizer());
Parameterizer::Error_code err = CGAL::parameterize(mesh, Parameterizer());
...
@ -389,7 +373,7 @@ In the following example, we compute a Floater mean value coordinates
parameterization with a square border arc length parameterization.
Specifying a specific border parameterization
instead of the default one means using the second parameter of
`Mean_value_coordinates_parameterizer_3<ParameterizationMesh_3, BorderParameterizer_3, SparseLinearAlgebraTraits_d>`.
`Mean_value_coordinates_parameterizer_3<TriangleMesh, BorderParameterizer_3, SparseLinearAlgebraTraits_d>`.
The differences with the first example \ref Surface_mesh_parameterization/Simple_parameterization.cpp "Simple_parameterization.cpp" are:
\code{.cpp}
@ -404,15 +388,14 @@ The differences with the first example \ref Surface_mesh_parameterization/Simple
//***************************************
// Square border parameterizer
typedef CGAL::Square_border_arc_length_parameterizer_3<Parameterization_polyhedron_adaptor>
typedef CGAL::Square_border_arc_length_parameterizer_3<Mesh>
Border_parameterizer;
// Floater Mean Value Coordinates parameterizer with square border
typedef CGAL::Mean_value_coordinates_parameterizer_3<Parameterization_polyhedron_adaptor,
Border_parameterizer>
typedef CGAL::Mean_value_coordinates_parameterizer_3<Mesh,Border_parameterizer>
Parameterizer;
Parameterizer::Error_code err = CGAL::parameterize(mesh_adaptor, Parameterizer());
Parameterizer::Error_code err = CGAL::parameterize(mesh, Parameterizer());
...
@ -425,10 +408,15 @@ Parameterizer::Error_code err = CGAL::parameterize(mesh_adaptor, Parameterizer()
\subsection Surface_mesh_parameterizationComputingaCut Computing a Cut Graph
All surface parameterization methods proposed in this package only
deal with meshes which are homeomorphic (topologically equivalent) to discs.
Nevertheless meshes with arbitrary topology and number of connected components car be parameterized, provided that the user specifies a cut graph (an oriented list of vertices), which is the border of a topological disc. If no cut graph is
provided as input, the longest border already
in the input mesh is taken as default border, all other borders being considered as holes. Note that only the inside part (i.e., one connected component) of the given border is parameterized.
deal with meshes which are homeomorphic (topologically equivalent) to
discs. Nevertheless meshes with arbitrary topology and number of
connected components car be parameterized, provided that the user
specifies a cut graph (a set of edges), which is the
border of a topological disc. If no cut graph is provided as input,
the longest border already in the input mesh is taken as default
border, all other borders being considered as holes. Note that only
the inside part (i.e., one connected component) of the given border is
parameterized.
\cgalFigureBegin{Surface_mesh_parameterizationfigcut,cut.png}
Cut Graph
@ -444,27 +432,15 @@ a simple cutting algorithm for the sake of completeness.
The surface parameterization classes in this package only <I>directly</I> support
surfaces which are homeomorphic to disks (models of
`ParameterizationMesh_3`). This software design simplifies the
`TriangleMesh`). This software design simplifies the
implementation of all new parameterization methods.
The `Parameterization_mesh_patch_3<ParameterizationPatchableMesh_3>`
class is responsible for <I>virtually</I> cutting
a patch in a `ParameterizationPatchableMesh_3` mesh.
The resulting patch is a topological
disk (if the cut graph is correct)
and provides a `ParameterizationMesh_3` interface. It can be used as
parameter of `parameterize()`.
The `Seam_mesh<TriangleMesh>` class is responsible for
<I>virtually</I> cutting a patch in a `TriangleMesh` mesh. The
resulting patch is a topological disk (if the cut graph is correct)
and provides a `TriangleMesh` interface. It can be used as parameter
of `parameterize()`.
`ParameterizationPatchableMesh_3` inherits from concept `ParameterizationMesh_3`,
thus is a concept for a 3D surface mesh.
`ParameterizationPatchableMesh_3` adds the ability to support patches and
virtual seams. <I>Patches</I> are a subset of a 3D mesh.
<I>Virtual seams</I> behave exactly as if the surface was cut along a certain graph.
The `ParameterizationMesh_3` interface with the Polyhedron is both a model of
`ParameterizationMesh_3` and `ParameterizationPatchableMesh_3`:
`Parameterization_polyhedron_adaptor_3<Polyhedron_3_>`
Note that this class is a decorator which adds <I>on the fly</I>
the necessary fields to unmodified \cgal data structures (using STL
@ -480,28 +456,7 @@ to make it a topological disk, then applies the default parameterization:
\cgalExample{Surface_mesh_parameterization/Mesh_cutting_parameterization.cpp}
\section Surface_mesh_parameterizationOutput Output
Parameterization methods compute \f$ (u,v)\f$ fields for each vertex
of the input mesh, with the seam vertices being virtually duplicated (thanks
to `Parameterization_mesh_patch_3<ParameterizationPatchableMesh_3>`).
To support this duplication,
`Parameterization_polyhedron_adaptor_3<Polyhedron_3_>` stores
the result in the \f$ (u,v)\f$ fields of the input mesh halfedges.
A \f$ (u,v)\f$ pair is computed for
each inner vertex (i.e.\ its halfedges share the same \f$ (u,v)\f$ pair),
while a \f$ (u,v)\f$ pair is computed for each border halfedge.
The user has to iterate over the mesh halfedges to get the result.
Note that \f$ (u,v)\f$ fields do not exist in `Polyhedron_3<Traits>`,
thus the output traversal is specific to the way the (u,v) fields are implemented by the adaptor.
\subsection Surface_mesh_parameterizationEPSOutputExample EPS Output Example
The follwing example is a complete parameterization
example which outputs the resulting parameterization to a EPS file. It gets the \f$ (u,v)\f$ fields computed by a parameterization method over a `Polyhedron_3<Traits>` mesh with a
`Parameterization_polyhedron_adaptor_3<Polyhedron_3_>` adaptor:
\cgalExample{Surface_mesh_parameterization/Complete_parameterization_example.cpp}
\section Surface_mesh_parameterizationComplexity Complexity and Guarantees
@ -559,11 +514,11 @@ This package's entry point is:
// Compute a one-to-one mapping from a 3D triangle surface mesh to a
// 2D circle, using Floater Mean Value Coordinates algorithm.
// A one-to-one mapping is guaranteed.
template <class ParameterizationMesh_3>
typename Parameterizer_traits_3<ParameterizationMesh_3>::Error_code
parameterize(ParameterizationMesh_3& mesh) // 3D mesh, model of ParameterizationMesh_3 concept
template <class TriangleMesh>
typename Parameterizer_traits_3<TriangleMesh>::Error_code
parameterize(TriangleMesh& mesh) // 3D mesh, model of TriangleMesh concept
{
Mean_value_coordinates_parameterizer_3<ParameterizationMesh_3> parameterizer;
Mean_value_coordinates_parameterizer_3<TriangleMesh> parameterizer;
return parameterizer.parameterize(mesh);
}
@ -571,9 +526,9 @@ return parameterizer.parameterize(mesh);
// simple 2D domain.
// One-to-one mapping may be guaranteed or not,
// depending on the chosen ParametizerTraits_3 algorithm.
template <class ParameterizationMesh_3, class ParameterizerTraits_3>
typename Parameterizer_traits_3<ParameterizationMesh_3>::Error_code
parameterize(ParameterizationMesh_3& mesh, // 3D mesh, model of ParameterizationMesh_3
template <class TriangleMesh, class ParameterizerTraits_3>
typename Parameterizer_traits_3<TriangleMesh>::Error_code
parameterize(TriangleMesh& mesh, // 3D mesh, model of TriangleMesh
ParameterizerTraits_3 parameterizer) // Parameterization method for mesh
{
return parameterizer.parameterize(mesh);
@ -593,7 +548,7 @@ which wouldn't be possible with a direct call to an object's method.
You may also wonder why there is not just one `parameterize()` function
with a default `ParameterizerTraits_3` argument equal to
`Mean_value_coordinates_parameterizer_3<ParameterizationMesh_3>`.
`Mean_value_coordinates_parameterizer_3<TriangleMesh>`.
The reason is simply that this is not allowed by the C++ standard (see
\cgalCite{cgal:ansi-is14882-98}, paragraph 14.1/9).
@ -647,7 +602,7 @@ A parameterizer UML class diagram (main types and methods only)
Surface parameterizer classes hierarchy
\cgalFigureEnd
\note `Parameterizer_traits_3<ParameterizationMesh_3>` is the (pure virtual)
\note `Parameterizer_traits_3<TriangleMesh>` is the (pure virtual)
superclass of all surface parameterization classes.
\subsection Surface_mesh_parameterizationFixedborderparameterizer3 Fixed_border_parameterizer_3 Class
@ -656,7 +611,7 @@ Linear fixed border parameterization algorithms are very close. They mainly
differ by the energy that they try to minimize, i.e.\ by the value of the \f$ w_{ij}\f$
coefficient of the \f$ A\f$ matrix, for \f$ v_i\f$ and \f$ v_j\f$ neighbor vertices of the mesh
\cgalCite{cgal:fh-survey-05}. One consequence is that most of the code of the fixed border methods is factorized in the
`Fixed_border_parameterizer_3<ParameterizationMesh_3, BorderParameterizer_3, SparseLinearAlgebraTraits_d>` class.
`Fixed_border_parameterizer_3<TriangleMesh, BorderParameterizer_3, SparseLinearAlgebraTraits_d>` class.
Subclasses:
<UL>
@ -667,67 +622,16 @@ of matrix \f$ A\f$ for \f$ v_j\f$ neighbor vertex of \f$ v_i\f$,
<LI>may implement an optimized version of `is_one_to_one_mapping`().
</UL>
See `Barycentric_mapping_parameterizer_3<ParameterizationMesh_3, BorderParameterizer_3, SparseLinearAlgebraTraits_d>`
See `Barycentric_mapping_parameterizer_3<TriangleMesh, BorderParameterizer_3, SparseLinearAlgebraTraits_d>`
class as an example.
\subsection Surface_mesh_parameterizationBorderParameterizations Border Parameterizations
Border Parameterizations are models of the `BorderParameterizer_3` concept.
To simplify the implementation, `BorderParameterizer_3` models know only the
`ParameterizationMesh_3` mesh class. They do not know the parameterization algorithm or the sparse linear solver used.
\subsection Surface_mesh_parameterizationParameterizationMesh3 ParameterizationMesh_3 and ParameterizationPatchableMesh_3 Concepts
All parameterization methods are templated by the kind of mesh they are applied on.
The mesh type must be a model of `ParameterizationMesh_3`.
The purpose of such a model is to:
<OL>
<LI>Support several kind of meshes.
<LI>Hide the implementation of extra fields specific to the parameterization domain
(`index`, `u`, `v`, `is_parameterized`).
<LI>%Handle in the mesh type the complexity of <I>virtually</I> cutting a mesh
to make it homeomorphic to a disk (instead of duplicating this
code in each parameterization method).
</OL>
Two options are possible for 1) and 2):
<UL>
<LI>Pass to all classes and methods a mesh pointer, a traits class to manipulate it,
and accessors to the extra field arrays.
This is the choice of the Boost Graph Library with `boost::graph_traits<>`
and the property maps.
<LI>Pass to all classes and methods an object that points to the actual mesh and knows
how to access to its fields. This is the Adaptor concept \cgalCite{cgal:ghjv-dpero-95}.
</UL>
The current design of this package uses the second option, which is simpler.
Of course, we may decide at some point to switch to the first one to reach a deeper integration
of \cgal with Boost.
Point 3) is solved by class `Parameterization_mesh_patch_3<ParameterizationPatchableMesh_3>`,
which takes care of <I>virtually</I> cutting
a patch in a `ParameterizationPatchableMesh_3` mesh, to make it appear as a topological disk
with a `ParameterizationMesh_3` interface.
`ParameterizationPatchableMesh_3` inherits from concept `ParameterizationMesh_3` and adds
the ability to support patches and virtual seams.
This mainly means that:
<UL>
<LI>vertices can be tagged as inside or outside the patch to parameterize,
<LI>the fields specific to parameterizations (`index`, `u`, `v`, `is_parameterized`)
can be set <I>per corner</I> (which is a more general way of saying <I>per half-edge</I>).
</UL>
`TriangleMesh` mesh class. They do not know the parameterization algorithm or the sparse linear solver used.
\subsection Surface_mesh_parameterizationCuttingaMesh_1 Cutting a Mesh
In this package, we focus on triangulated surfaces that are homeomorphic to a
disk.
Computing a cutting path that transforms a closed mesh of arbitrary genus into
a topological disk is a research topic on its own. This package does
not intend to cover this topic at the moment.
\section Surface_mesh_parameterizationExtendingthe Extending the Package and Reusing Code
@ -737,7 +641,7 @@ not intend to cover this topic at the moment.
Implementing a new fixed border linear parameterization is easy. Most
of the code of the fixed border methods is factorized in the
`Fixed_border_parameterizer_3<ParameterizationMesh_3, BorderParameterizer_3, SparseLinearAlgebraTraits_d>`
`Fixed_border_parameterizer_3<TriangleMesh, BorderParameterizer_3, SparseLinearAlgebraTraits_d>`
class. Subclasses must mainly
implement a `compute_w_ij`() method which computes each
\f$ w_{ij}\f$ = \f$ (i, j)\f$ coefficient of the matrix \f$ A\f$ for \f$ v_j\f$ neighboring
@ -747,18 +651,12 @@ Although implementing a new free border linear parameterization
method is more challenging, the Least Squares Conformal Maps
parameterization method provides a good starting point.
Implementing <I>non</I> linear parameterizations is a natural extension
to this package, although only the mesh adaptors can be reused.
\subsection Surface_mesh_parameterizationAddingNewBorder Adding New Border Parameterization Methods
Implementing a new border parameterization method is easy.
Square, circular and two-points border parameterizations are good starting points.
\subsection Surface_mesh_parameterizationMeshCutting Mesh Cutting
Obviously, this package would benefit of having robust algorithms
which transform arbitrary meshes into topological disks.
*/

3
Surface_mesh_parameterization/doc/Surface_mesh_parameterization/dependencies
View File

@ -1,3 +1,5 @@
BGL
Surface_mesh
Manual
Kernel_23
STL_Extension
@ -8,4 +10,5 @@ Polyhedron
Kernel_d
Solver_interface
Convex_hull_2
Polygon_mesh_processing

58
Surface_mesh_parameterization/examples/Surface_mesh_parameterization/Simple_parameterization.cpp
View File

@ -1,72 +1,46 @@
#include <CGAL/Simple_cartesian.h>
#include <CGAL/Surface_mesh.h>
#include <CGAL/parameterize.h>
#include <CGAL/Polyhedron_3.h>
#include <CGAL/boost/graph/graph_traits_Polyhedron_3.h>
#include <CGAL/Polygon_mesh_processing/measure.h>
#include <CGAL/parameterize.h>
#include <iostream>
#include <fstream>
typedef CGAL::Simple_cartesian<double> Kernel;
typedef Kernel::Point_2 Point_2;
typedef Kernel::Point_3 Point_3;
typedef CGAL::Surface_mesh<Point_3> Mesh;
typedef CGAL::Polyhedron_3<Kernel> Mesh;
typedef boost::graph_traits<Mesh>::vertex_descriptor vertex_descriptor;
typedef boost::graph_traits<Mesh>::halfedge_descriptor halfedge_descriptor;
typedef boost::graph_traits<Mesh>::face_descriptor face_descriptor;
namespace PMP = CGAL::Polygon_mesh_processing;
int main(int argc, char * argv[])
{
std::cerr << "Floater parameterization on the border of a circle" << std::endl;
std::ifstream in((argc>1)?argv[1]:"data/nefertiti.off");
Mesh sm;
in >> sm;
halfedge_descriptor hd = PMP::longest_border(sm).first;
if(hd == boost::graph_traits<Mesh>::null_halfedge()){
std::cout << "mesh has no border" << std::endl;
return(EXIT_FAILURE);
}
halfedge_descriptor hd = CGAL::Polygon_mesh_processing::longest_border(sm).first;
Mesh::Property_map<vertex_descriptor,Point_2> uv_pm;
uv_pm = sm.add_property_map<vertex_descriptor,Point_2>("v:uv").first;
Mesh::Property_map<vertex_descriptor,bool> parameterized_pm;
parameterized_pm = sm.add_property_map<vertex_descriptor,bool>("v:parameterized",false).first;
typedef CGAL::Parameterizer_traits_3<Mesh> Parameterizer;
Parameterizer::Error_code err = CGAL::parameterize(sm,
hd,
uv_pm,
parameterized_pm);
switch(err) {
case Parameterizer::OK: // Success
break;
case Parameterizer::ERROR_EMPTY_MESH: // Input mesh not supported
case Parameterizer::ERROR_NON_TRIANGULAR_MESH:
case Parameterizer::ERROR_NO_TOPOLOGICAL_DISC:
case Parameterizer::ERROR_BORDER_TOO_SHORT:
std::cerr << "Input mesh not supported: "
<< Parameterizer::get_error_message(err) << std::endl;
return EXIT_FAILURE;
break;
default: // Error
std::cerr << "Error: " << Parameterizer::get_error_message(err) << std::endl;
return EXIT_FAILURE;
break;
};
CGAL::Unique_hash_map<vertex_descriptor,Point_2> uvhm;
boost::associative_property_map<CGAL::Unique_hash_map<vertex_descriptor,Point_2> > uvpm(uvhm);
CGAL::parameterize(sm, hd, uvpm);
// Write the result in the polyline format
// Write the result in the polyline format that can be loaded in the Polyhedron demo
BOOST_FOREACH(face_descriptor fd, faces(sm)){
halfedge_descriptor hd = halfedge(fd,sm);
std::cout << "4 " << uv_pm[target(hd,sm)].x() << " " << uv_pm[target(hd,sm)].y() << " 0 ";
std::cout << "4 " << uvhm[target(hd,sm)] << " 0 ";
hd = next(hd,sm);
BOOST_FOREACH(vertex_descriptor vd, vertices_around_face(hd,sm)){
std::cout << uv_pm[vd].x() << " " << uv_pm[vd].y() << " 0 ";
std::cout << uvhm[vd] << " 0 ";
}
std::cout << std::endl;
}
return EXIT_SUCCESS;
return 0;
}

2
Surface_mesh_parameterization/include/CGAL/Barycentric_mapping_parameterizer_3.h
View File

@ -50,7 +50,7 @@ namespace CGAL {
/// \cgalModels `ParameterizerTraits_3`
///
///
/// \tparam TriangleMesh 3D surface mesh.
/// \tparam TriangleMesh a model of `FaceGraph`
/// \tparam BorderParameterizer_3 Strategy to parameterize the surface border.
/// \tparam SparseLinearAlgebraTraits_d Traits class to solve a sparse linear system.
/// Note: the system is *not* symmetric because `Fixed_border_parameterizer_3`

30
Surface_mesh_parameterization/include/CGAL/Circular_border_parameterizer_3.h
View File

@ -42,25 +42,22 @@ namespace CGAL {
/// 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 or the kind of sparse linear system used.
/// It implements most of the algorithm.
///
/// \cgalModels `BorderParameterizer_3`
///
/// \sa `CGAL::Circular_border_arc_length_parameterizer_3<TriangleMesh>`
/// \sa `CGAL::Circular_border_uniform_parameterizer_3<TriangleMesh>`
template<class TriangleMesh> //< 3D surface
template<class TriangleMesh_> //< a model of `FaceGraph`
class Circular_border_parameterizer_3
{
// Public types
public:
typedef TriangleMesh_ TriangleMesh;
typedef typename boost::graph_traits<TriangleMesh>::vertex_descriptor vertex_descriptor;
typedef typename boost::graph_traits<TriangleMesh>::halfedge_descriptor halfedge_descriptor;
// Private types
@ -83,7 +80,7 @@ public:
/// on border's shape. Mark them as <i>parameterized</i>.
template <typename VertexUVmap, typename VertexParameterizedMap>
Error_code
parameterize_border(TriangleMesh& mesh,
parameterize_border(const TriangleMesh& mesh,
halfedge_descriptor bhd,
VertexUVmap uvmap,
VertexParameterizedMap vpmap)
@ -124,14 +121,7 @@ public:
/// Indicate if border's shape is convex.
bool is_border_convex () { return true; }
// Protected operations
protected:
/// Compute the length of an edge.
/// virtual double compute_edge_length(const Adaptor& mesh,
/// vertex_descriptor source,
/// vertex_descriptor target) = 0;
// Private operations
private:
/// Compute the total length of the border
double compute_border_length(const TriangleMesh& tmesh, halfedge_descriptor bhd){
@ -157,15 +147,14 @@ public:
/// with an arc-length parameterization: (u,v) values are
/// proportional to the length of border edges.
/// `Circular_border_parameterizer_3` implements most of the border parameterization
/// algorithm. This class implements only `compute_edge_length()` to compute a
/// segment's length.
/// algorithm.
///
/// \cgalModels `BorderParameterizer_3`
///
/// \sa `CGAL::Circular_border_parameterizer_3<TriangleMesh>`
/// \sa `CGAL::Circular_border_uniform_parameterizer_3<TriangleMesh>`
template<class TriangleMesh> //< 3D surface
template<class TriangleMesh_> //< 3D surface
class Circular_border_arc_length_parameterizer_3
: public Circular_border_parameterizer_3<TriangleMesh>
{
@ -173,12 +162,11 @@ public:
public:
// We have to repeat the types exported by superclass
/// @cond SKIP_IN_MANUAL
typedef TriangleMesh Adaptor;
typedef TriangleMesh_ TriangleMesh;
/// @endcond
// Private types
private:
// Mesh_Adaptor_3 subtypes:
typedef typename Parameterizer_traits_3<TriangleMesh>::Point_2 Point_2;
typedef typename Parameterizer_traits_3<TriangleMesh>::Vector_3 Vector_3;

2
Surface_mesh_parameterization/include/CGAL/Discrete_authalic_parameterizer_3.h
View File

@ -64,7 +64,7 @@ namespace CGAL {
template
<
class TriangleMesh, ///< 3D surface mesh
class TriangleMesh, ///< a model of `FaceGraph`
class BorderParameterizer_3 ///< Strategy to parameterize the surface border
= Circular_border_arc_length_parameterizer_3<TriangleMesh>,
class SparseLinearAlgebraTraits_d ///< Traits class to solve a sparse linear system

2
Surface_mesh_parameterization/include/CGAL/Discrete_conformal_map_parameterizer_3.h
View File

@ -54,7 +54,7 @@ namespace CGAL {
/// \cgalModels `ParameterizerTraits_3`
///
///
/// \param TriangleMesh 3D surface mesh.
/// \param TriangleMesh a model of `FaceGraph`
/// \param BorderParameterizer_3 Strategy to parameterize the surface border.
/// \param SparseLinearAlgebraTraits_d Traits class to solve a sparse linear system.
/// Note: the system is *not* symmetric because `Fixed_border_parameterizer_3`

9
Surface_mesh_parameterization/include/CGAL/Fixed_border_parameterizer_3.h
View File

@ -78,7 +78,7 @@ namespace CGAL {
template
<
class TriangleMesh, ///< 3D surface mesh
class TriangleMesh, ///< a model of FaceGraph
class BorderParameterizer_3 ///< Strategy to parameterize the surface border
= Circular_border_arc_length_parameterizer_3<TriangleMesh>,
class SparseLinearAlgebraTraits_d ///< Traits class to solve a sparse linear system
@ -275,8 +275,11 @@ template <class TriangleMesh, class Border_param, class Sparse_LA>
template <typename VertexUVmap, typename VertexIndexMap, typename VertexParameterizedMap>
typename Fixed_border_parameterizer_3<TriangleMesh, Border_param, Sparse_LA>::Error_code
Fixed_border_parameterizer_3<TriangleMesh, Border_param, Sparse_LA>::
parameterize(TriangleMesh& mesh, halfedge_descriptor bhd, VertexUVmap uvmap, VertexIndexMap vimap,
VertexParameterizedMap vpm)
parameterize(TriangleMesh& mesh,
halfedge_descriptor bhd,
VertexUVmap uvmap,
VertexIndexMap vimap,
VertexParameterizedMap vpm)
{
Error_code status = Base::OK;

2
Surface_mesh_parameterization/include/CGAL/LSCM_parameterizer_3.h
View File

@ -73,7 +73,7 @@ namespace CGAL {
template
<
class TriangleMesh, ///< 3D surface mesh.
class TriangleMesh, ///< a model of `FaceGraph`
class BorderParameterizer_3
= Two_vertices_parameterizer_3<TriangleMesh>,
///< Strategy to parameterize the surface border.

4
Surface_mesh_parameterization/include/CGAL/Mean_value_coordinates_parameterizer_3.h
View File

@ -63,7 +63,7 @@ namespace CGAL {
template
<
class TriangleMesh, ///< 3D surface mesh
class TriangleMesh, ///< a model of `FaceGraph`
class BorderParameterizer_3 ///< Strategy to parameterize the surface border
= Circular_border_arc_length_parameterizer_3<TriangleMesh>,
class SparseLinearAlgebraTraits_d ///< Traits class to solve a sparse linear system
@ -137,7 +137,7 @@ protected:
typedef typename Parameterizer_traits_3<TriangleMesh>::VPM PPmap;
PPmap ppmap = get(vertex_point, mesh);
const PPmap ppmap = get(vertex_point, mesh);
Point_3 position_v_i = get(ppmap,main_vertex_v_i);
Point_3 position_v_j = get(ppmap, *neighbor_vertex_v_j);

2
Surface_mesh_parameterization/include/CGAL/Parameterizer_traits_3.h
View File

@ -78,7 +78,7 @@ public:
};
typedef typename boost::property_map<TriangleMesh, CGAL::vertex_point_t>::type VPM;
typedef typename boost::property_map<TriangleMesh, CGAL::vertex_point_t>::const_type VPM;
typedef typename boost::property_traits<VPM>::value_type Point_3;
typedef typename Kernel_traits<Point_3>::Kernel Kernel;

32
Surface_mesh_parameterization/include/CGAL/Square_border_parameterizer_3.h
View File

@ -58,12 +58,13 @@ namespace CGAL {
/// \cgalModels `BorderParameterizer_3`
///
template<class TriangleMesh> //< 3D surface
template<class TriangleMesh_> //< 3D surface
class Square_border_parameterizer_3
{
// Public types
public:
typedef typename boost::graph_traits<TriangleMesh>::vertex_descriptor vertex_descriptor;
typedef TriangleMesh_ TriangleMesh;
typedef typename boost::graph_traits<TriangleMesh>::vertex_descriptor vertex_descriptor;
typedef Halfedge_around_face_iterator<TriangleMesh> halfedge_around_face_iterator;
// Private types
@ -108,8 +109,8 @@ private:
// Compute the total length of the border.
template<class TriangleMesh>
inline
double Square_border_parameterizer_3<TriangleMesh>::compute_border_length(
const TriangleMesh& mesh, halfedge_descriptor bhd)
double Square_border_parameterizer_3<TriangleMesh>::compute_border_length(const TriangleMesh& mesh,
halfedge_descriptor bhd)
{
VPM vpm = get(CGAL::vertex_point,mesh);
double len = 0.0;
@ -125,9 +126,9 @@ template<class TriangleMesh>
inline
typename Parameterizer_traits_3<TriangleMesh>::Error_code
Square_border_parameterizer_3<TriangleMesh>::parameterize_border(TriangleMesh& mesh,
halfedge_descriptor bhd,
VertexUVmap uvmap,
VertexParameterizedMap vpmap)
halfedge_descriptor bhd,
VertexUVmap uvmap,
VertexParameterizedMap vpmap)
{
VPM vpm = get(vertex_point, mesh);
#ifdef DEBUG_TRACE
@ -251,16 +252,17 @@ Square_border_parameterizer_3<TriangleMesh>::closest_iterator(TriangleMesh& mesh
/// \cgalModels `BorderParameterizer_3`
///
template<class TriangleMesh> //< 3D surface
template<class TriangleMesh_> //< 3D surface
class Square_border_uniform_parameterizer_3
: public Square_border_parameterizer_3<TriangleMesh>
: public Square_border_parameterizer_3<TriangleMesh_>
{
// Public types
public:
// We have to repeat the types exported by superclass
/// @cond SKIP_IN_MANUAL
typedef typename boost::graph_traits<TriangleMesh>::vertex_descriptor vertex_descriptor;
typedef TriangleMesh_ TriangleMesh;
typedef typename boost::graph_traits<TriangleMesh>::vertex_descriptor vertex_descriptor;
/// @endcond
@ -305,24 +307,20 @@ protected:
/// \cgalModels `BorderParameterizer_3`
///
template<class TriangleMesh> //< 3D surface
template<class TriangleMesh_> //< 3D surface
class Square_border_arc_length_parameterizer_3
: public Square_border_parameterizer_3<TriangleMesh>
: public Square_border_parameterizer_3<TriangleMesh_>
{
// Public types
public:
typedef TriangleMesh_ TriangleMesh;
// Private types
private:
// Mesh_TriangleMesh_3 subtypes:
typedef typename TriangleMesh::Point_2 Point_2;
typedef typename TriangleMesh::Vector_3 Vector_3;
// Public operations
public:
// Default constructor, copy constructor and operator =() are fine
// Protected operations
protected:
/// Compute the length of an edge.
virtual double compute_edge_length(const TriangleMesh& mesh,