\( \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.10.1 - Polygon Mesh Processing
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Groups Pages
Functions
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::. CGAL::Polygon_mesh_processing::parameters::all_default() can be used to indicate that default values of optional named parameters must be used.

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.

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: bool
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 SparseLinearAlgebraWithFactorTraits_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

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 the value type

typename boost::property_traits<
typename boost::property_map<PolygonMesh, CGAL::face_index_t>::type>::value_type

Default value is

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

If this internal property map exists, its values should be initialized

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 the value type

typename boost::property_traits<
typename boost::property_map<PolygonMesh, CGAL::vertex_index_t>::type>::value_type

Default value is

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

number_of_iterations

the number of iterations of the sequence of iterations performed by the isotropic remeshing algorithm.
Type : unsigned int
Default value is 1

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 ReadWritePropertyMap 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.

vertex_is_constrained_map

the property map containing information about vertices of the input polygon mesh being constrained or not. Constrained vertices may be replaced by new vertices, but the number and location of vertices remain unchanged.
Type : a class model of ReadWritePropertyMap with boost::graph_traits<PolygonMesh>::vertex_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 vertex is constrained is provided.

protect_constraints

enables the protection of constraints listed by edge_is_constrained_map and boundary edges during isotropic remeshing. If true, constraint edges cannot be modified at all during the remeshing process.
Type : bool
Default value is false

face_patch_map

a property map containing information about faces. It is particularly well-suited for preserving surface patch IDs, or face colors. The edges at the interface between surface patches are treated similarly to the ones of edge_is_constrained_map
Type : a class model of ReadWritePropertyMap with boost::graph_traits<PolygonMesh>::face_descriptor as key type and the desired property, model of CopyConstructible as value type.
Default : if this parameter is omitted, a default property map where each face is associated with the ID of the connected component it belongs to. Connected components are computed with respect to the constrained edges listed in the property map edge_is_constrained_map

number_of_relaxation_steps

the number of iterations of tangential relaxation that are performed at each iteration of the isotropic remeshing process. A larger number of relaxation steps lead to a more isotropic mesh.
Type : unsigned int
Default value is 1

relax_constraints

enables the tangential relaxation step of the isotropic remeshing algorithm to be performed on vertices that are endpoints of constraints listed by edge_is_constrained_map, and boundary edges. The vertices move along the constrained polylines they belong to. Corners (i.e. vertices incident to more than 2 constraints, and vertices listed in vertex_is_constrained_map) are not allowed to move at all. If protect_constraints is set to true, this parameter is ignored.
Type : bool
Default value is true

use_random_uniform_sampling

Parameter used in sample_triangle_mesh() to indicate if points should be picked in a random uniform way.
Type : bool
Default value is true

use_grid_sampling

Parameter used in sample_triangle_mesh() to indicate if points should be picked in on a grid in each face.
Type : bool
Default value is false

use_monte_carlo_sampling

Parameter used in sample_triangle_mesh() to indicate if points should be picked using a Monte-Carlo approach.
Type : bool
Default value is false

sample_edges

Parameter used in sample_triangle_mesh() to indicate if a dedicated sampling of edges should be done.
Type : bool
Default value is true

sample_vertices

Parameter used in sample_triangle_mesh() to indicate if triangle vertices should be copied in the output iterator.
Type : bool
Default value is true

sample_faces

Parameter used in sample_triangle_mesh() to indicate if the interior of faces should be considered for the sampling.
Type : bool
Default value is true

number_of_points_on_faces

Parameter used in sample_triangle_mesh() to set the number of points picked using the random uniform method on faces.
Type : std::size_t
Default value is 0

number_of_points_on_edges

Parameter used in sample_triangle_mesh() to set the number of points picked using the random uniform method on edges.
Type : std::size_t
Default value is 0

number_of_points_per_face

Parameter used in sample_triangle_mesh() to set the number of points picked per face using the Monte-Carlo method.
Type : std::size_t
Default value is 0

number_of_points_per_edge

Parameter used in sample_triangle_mesh() to set the number of points picked per edge using the Monte-Carlo method.
Type : std::size_t
Default value is 0

grid_spacing

Parameter used in sample_triangle_mesh() to set the grid spacing when using the grid sampling method.
Type : double
Default value is 0

number_of_points_per_area_unit

Parameter used in sample_triangle_mesh() to set the number of points per area unit to be picked up in faces for the random uniform sampling and Monte-Carlo methods.
Type : double
Default value is 0

number_of_points_per_distance_unit

Parameter used in sample_triangle_mesh() to set the number of points per distance unit to be picked up on edges for the random uniform sampling and Monte-Carlo methods.
Type : double
Default value is 0

Functions

unspecified_type CGAL::Polygon_mesh_processing::parameters::all_default ()
 This function can be used to indicate that all optional named parameters to be used are the default ones. More...
 

Function Documentation

unspecified_type CGAL::Polygon_mesh_processing::parameters::all_default ( )

This function can be used to indicate that all optional named parameters to be used are the default ones.

This is particularly useful when a function requires more than one sequence of named parameters and default values is fine only for some of them.

#include <CGAL/polygon_mesh_processing.h>

Examples:
Polygon_mesh_processing/corefinement_difference_remeshed.cpp.