\( \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 5.0 - Polygon Mesh Processing
Named Parameters for Polygon Mesh Processing
Polygon Mesh Processing Reference

In this package, all functions optional parameters are implemented as BGL optional named parameters (see Named Parameters for more information on how to use them).

Since the parameters of the various polygon mesh processing functions defined in this package are redundant, their long descriptions are centralized below. The sequence of named parameters starts with CGAL::parameters::. CGAL::parameters::all_default() can be used to indicate that default values of optional named parameters shall be used.

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:

The following named parameters, offered by the package CGAL and the Boost Graph Library (see BGL Named Parameters), are used 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:

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

vertex_index_map

is 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:

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

face_index_map

is 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:

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

If this internal property map exists, its values must be initialized.

edge_is_constrained_map is the property map containing information about edges of the input polygon mesh being marked or not. In isotropic_remeshing() and connected_components(), the marked edges are constrained.
Type: a class model of ReadWritePropertyMap with boost::graph_traits<PolygonMesh>::edge_descriptor as key type and bool as value type. It must be default constructible.
Default: a default property map where no edge is constrained

In addition to these named parameters, this package offers the following named parameters:

geom_traits

is the geometric traits instance used for the mesh processing operation.
Type: a Geometric traits class.
Default:

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

vertex_incident_patches_map

is the property map containing the surface patches incident to each vertex of the input polygon mesh.
Type: a class model of LvaluePropertyMap with boost::graph_traits<PolygonMesh>::vertex_descriptor as key type. Its value type must be a container of boost::property_traits<PatchIdMap>::value_type and have a function insert(). A std::set or a boost::unordered_set are recommended, as a patch index may be inserted several times.
Default:

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

vertex_feature_degree_map

is the property map containing the number of feature edges being incident to the vertices of the polygon mesh pmesh.
Type: a class model of ReadWritePropertyMap with boost::graph_traits<PolygonMesh>::vertex_descriptor as key type and int as value type. It must be default constructible.
Default:

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

vertex_is_constrained_map

is 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 must be default constructible.
Default: a default property map where no vertex is constrained is provided.

face_patch_map

is 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: 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

first_index

is the index of the first surface patch.
Type: std::size_t
Default: 1

density_control_factor

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

fairing_continuity

controls the tangential continuity of the output surface in fair(). The possible values are 0, 1 and 2, refering to the C0, C1 and C2 continuity.
Type: unsigned int between 0 and 2
Default: 1

sparse_linear_solver

is the solver used.
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:
in fair():

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

in smooth_shape():

CGAL::Eigen_solver_traits<Eigen::BiCGSTAB<CGAL::Eigen_sparse_matrix<double>::EigenType, Eigen::IncompleteLUT<double> > >

number_of_iterations

is the number of iterations of the sequence of iterations performed in isotropic_remeshing().
Type: unsigned int
Default: 1

protect_constraints

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

collapse_constraints

enables the collapse of constraints listed by edge_is_constrained_map and boundary edges in isotropic_remeshing(). If false, constraint edges cannot be collapsed during the remeshing process.
Type: bool
Default: true

relax_constraints

enables the tangential relaxation step in isotropic_remeshing() 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: true

number_of_relaxation_steps

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

use_delaunay_triangulation

enables the use of the Delaunay triangulation facet search space for hole filling functions. If no valid triangulation can be found in this search space, the algorithm falls back to the non-Delaunay triangulations search space to find a solution.
Type: bool
Default: true

use_random_uniform_sampling

is a parameter used in sample_triangle_mesh() to indicate that the points are picked in a random uniform way.
Type: bool
Default: true

use_grid_sampling

is a parameter used in sample_triangle_mesh() to indicate that the points are picked on a grid in each face.
Type: bool
Default: false

use_monte_carlo_sampling

is a parameter used in sample_triangle_mesh() to indicate that the points are picked using a Monte-Carlo approach.
Type: bool
Default: false

sample_edges

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

sample_vertices

is a parameter used in sample_triangle_mesh() to indicate that triangle vertices are copied in the output iterator.
Type: bool
Default: true

sample_faces

is a parameter used in sample_triangle_mesh() to indicate if the interior of faces is considered for the sampling.
Type: bool
Default: true

number_of_points_on_faces

is a 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: 0

number_of_points_on_edges

is a 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: 0

number_of_points_per_face

is a 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: 0

number_of_points_per_edge

is a 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: 0

grid_spacing

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

number_of_points_per_area_unit

is a 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: 0

number_of_points_per_distance_unit

is a 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: 0

do_project

is a parameter used in random_perturbation() to set whether vertices are re-projected to the input surface after their geometric perturbation.
Type: bool
Default: true

random_seed

is a parameter used in random_perturbation() to choose a seed to initialize the random number generator CGAL::Random(). If this parameter is not provided, the perturbation is not deterministic (i.e. not reproducible from one run to the other).
Type: unsigned int
Default: the random number generator is initialized with CGAL::Random()

outward_orientation

Parameter used in orientation functions to choose between an outward or inward orientation.
Type: bool
Default: true

do_overlap_test_of_bounded_sides

Parameter used in intersection test functions to indicate whether overlapping tests of bounded sides of close meshes are done in addition to surface intersection tests.
Type: bool
Default: false

projection_functor

Parameter used in isotropic_remeshing() to specify an alternative vertex projection method.
Type: Unary function object with vertex descriptor as argument type.
Default: A function object projecting vertices on the input surface.

apply_per_connected_component

Parameter used to indicate whether an algorithm should consider each connected component of a mesh independently.
Type: bool
Default: false

visitor

Parameter used to pass a visitor class to a function. Its type and behavior depend on the visited function.
Type: A class
Default: Specific to the function visited

throw_on_self_intersection

Parameter used in corefinement-related functions to make the functions throw an exception in case some faces involved in the intersection of the input are self-intersecting and make the operation impossible with the current version of the code.
Type: bool
Default: false

clip_volume

Parameter used in clip() functions to clip a volume rather than a surface.
Type: bool
Default: false

use_compact_clipper

Parameter used in clip() functions to indicate whether the boundary of the clipper should be considered as part of the clipping volume or not.
Type: bool
Default: true

output_iterator

Parameter to pass an output iterator.
Type : a model of OutputIterator
Default : CGAL::Emptyset_iterator

erase_all_duplicates

Parameter used in the function merge_duplicate_polygons_in_polygon_soup() to indicate, when multiple faces are duplicates, whether all the duplicate faces should be removed or if one (arbitrarily chosen) face should be kept.
Type: bool
Default: false

require_same_orientation

Parameter used in the function merge_duplicate_polygons_in_polygon_soup() to indicate if orientation should matter when determining whether two faces are duplicates.
Type: bool
Default: false

snapping_tolerance

Parameter used in the function locate_in_face() to to snap barycentric coordinates. Depending on the geometric traits used, the computation of the barycentric coordinates might be an inexact construction, thus leading to sometimes surprising values (e.g. a triplet [0.5, 0.5, -1-e17] for a point at the middle of an edge). The coordinates will be snapped towards 0 and 1 if the difference is smaller than the tolerance value, while still ensuring that the total sum of the coordinates is 1.
Type: Kernel::FT
Default: 0

use_angle_smoothing_t

Parameter used in the function smooth_mesh() to indicate if angle-based smoothing should be used. When this type of smoothing is used, the algorithm attempts to equalize angles incident to each vertex.


Type: bool
Default: true

use_area_smoothing_t

Parameter used in the function smooth_mesh() to indicate if area-based smoothing should be used. When this type of smoothing is used, the algorithm attempts to equalize the areas of the triangles incident to each vertex. Since this can create elongated triangles, a second phase uses Delaunay-based flips to recover good shapes, unless specified otherwise (see below).


Type: bool
Default: true

use_Delaunay_flips_t

Parameter used in the function smooth_mesh() to indicate if Delaunay-based flips should be used after area-based smoothing has been performed. A user wishing to preserve combinatorial information can set this parameter to false, but the mesh might have elongated elements.


Type: bool
Default: true

use_safety_constraints

Parameter used in the function smooth_mesh() to indicate if some sanity checks should be used to decide if the move of a vertex should be applied or rejected. These sanity checks consists of checking that no face incident to the vertex becomes inverted and that the minimum angle of the incident faces is not decreased by the move.


Type: bool
Default: true

face_size_map

Parameter used in the functions keep_large_connected_components() and keep_largest_connected_components() to pass a property map that gives the size of a face when evaluating the size of a connected component (which is defined as the sum of the sizes of its faces).


Type: a class model of ReadablePropertyMap with boost::graph_traits<PolygonMesh>::face_descriptor as key type and a value type supporting construction from 0, operator+=(), and comparison operators.
Default: CGAL::Constant_property_map<face_descriptor, std::size_t> with value 1