CGAL 4.7 - Polygon Mesh Processing: Named Parameters

\( \newcommand{\E}{\mathrm{E}} \) \( \newcommand{\A}{\mathrm{A}} \) \( \newcommand{\R}{\mathrm{R}} \) \( \newcommand{\N}{\mathrm{N}} \) \( \newcommand{\Q}{\mathrm{Q}} \) \( \newcommand{\Z}{\mathrm{Z}} \) \( \def\ccSum #1#2#3{ \sum_{#1}^{#2}{#3} } \def\ccProd #1#2#3{ \sum_{#1}^{#2}{#3} }\)

CGAL 4.7 - Polygon Mesh Processing

All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Groups Pages
Named Parameters
Polygon Mesh Processing Reference

How to use BGL Optional Named Parameters

The notion of named parameters was introduced in the BGL. You can read about it in the following site: http://www.boost.org/libs/graph/doc/bgl_named_params.html. Named parameters allow the user to specify only those parameters which are really needed, by name, making the parameter ordering unimportant.

Say there is a function `f()` that takes 3 parameters called name, age and gender, and you have variables `n`, `a` and `g` to pass as parameters to that function. Without named parameters, you would call it like this: `f(n,a,g)`, whereas with named parameters, you call it like this: `f(name(n).age(a).gender(g))`.

That is, you give each parameter a name by wrapping it into a function whose name matches that of the parameter. The entire list of named parameters is really a composition of function calls separated by a dot ( .). Thus, if the function takes a mix of mandatory and named parameters, you use a comma to separate the last non-named parameter from the first named parameters, like this:

`f(non_named_par0, non_named_par1, name(n).age(a).gender(g))`

When you use named parameters, the ordering is irrelevant, so `f(name(n).age(a).gender(g))` is equivalent to `f(age(a).gender(g).name(n))`, and you can just omit any named parameter that has a default value.

The sequence of named parameters should start with `CGAL::Polygon_mesh_processing::parameters::`.

Example

See below a sample call of a function that uses the optional BGL named parameters.

/* pmesh : polygon mesh with patches to be refined
faces : the range of faces defining the patches to refine
faces_out : output iterator into which descriptors of new faces are put
vertices_out : output iterator into which descriptors of new vertices are put
vertex_point_map : the property map with the points associated to the vertices of `pmesh`
density_control_factor : factor to control density of the output mesh
*/
refine(pmesh
, faces
, faces_out
, vertices_out
, CGAL::Polygon_mesh_processing::parameters::vertex_point_map(vpmap)
.density_control_factor(d));

List of Available Named Parameters

In this package, all functions optional parameters are implemented as BGL optional named parameters.

Since the parameters of the various polygon mesh processing functions defined in this package are redundant, their long descriptions are centralized below.

In the following, we assume that the following types are provided as template parameters of polygon mesh processing functions and classes. Note that, for some of these functions, the type is more specific.

- `PolygonMesh` implements a `FaceGraph`
- `GeomTraits` a geometric traits class in which constructions are performed and predicates evaluated. Everywhere in this package, a CGAL `Kernel` fulfills the requirements.

Here is the list of the named parameters available in this package:

  vertex_point_map

  is the property map with the points associated to the vertices of the polygon mesh `pmesh`.
  Type: a class model of `ReadablePropertyMap` with `boost::graph_traits<PolygonMesh>::vertex_descriptor` as key type and `GeomTraits::Point_3` as value type.
  Default value is

  boost::get(CGAL::vertex_point, pmesh)

  use_delaunay_triangulation | enables the use of the Delaunay triangulation facet search space for hole filling functions. Type: boolean Default value is `true`

  density_control_factor

  controls the density of the mesh generated by refinement, and larger values cause denser refinements. The density of vertices in the refined region is this factor times higher than before refinement.
  Type: floating scalar value
  Default value is `CGAL::sqrt(2)`

  fairing_continuity | controls the tangential continuity of the output surface for fairing.The possible values are 0, 1 and 2, refering to the C0, C1 and C2 continuity. Type: `unsigned` `int` between 0 and 2 Default value is `1`

  sparse_linear_solver

  is the solver used for fairing of polygon meshes.
  Type: a class model of `SparseLinearAlgebraTraitsWithFactor_d`.
  Default: if Eigen 3.2 (or greater) is available and `CGAL_EIGEN3_ENABLED` is defined, then the following overload of `Eigen_solver_traits` is provided as default value

  CGAL::Eigen_solver_traits<
  Eigen::SparseLU<
  CGAL::Eigen_sparse_matrix<double>::EigenType,
  Eigen::COLAMDOrdering<int> > >

  geom_traits

  the geometric traits instance in which the mesh processing operation should be performed.
  Type: a Geometric traits class.
  Default type is

  typename CGAL::Kernel_traits<
  typename boost::property_traits<
  typename boost::property_map<PolygonMesh, CGAL::vertex_point_t>::type>::value_type>::Kernel

  edge_is_constrained_map

  the property map containing information about edges of the input polygon mesh being constrained or not.
  Type: a class model of `ReadablePropertyMap` with `boost::graph_traits<PolygonMesh>::edge_descriptor` as key type and `bool` as value type. It should be default - constructible.
  Default: if this parameter is omitted, a default property map where no edge is constrained is provided.

  face_index_map

  the property map containing the index of each face of the input polygon mesh.
  Type: a class model of `ReadablePropertyMap` with `boost::graph_traits<PolygonMesh>::face_descriptor` as key type and `boost::face_index_t` as value type.
  Default value is

  boost::get(CGAL::face_index, pmesh)

  vertex_index_map

  the property map containing the index of each vertex of the input polygon mesh.
  Type: a class model of `ReadablePropertyMap` with `boost::graph_traits<PolygonMesh>::vertex_descriptor` as key type and `CGAL::vertex_index_t` as value type.
  Default value is

  boost::get(CGAL::vertex_index, pmesh)