mirror of https://github.com/CGAL/cgal
399 lines
16 KiB
Plaintext
399 lines
16 KiB
Plaintext
/*!
|
|
\defgroup namedparameters Named Parameters
|
|
\ingroup PkgPolygonMeshProcessing
|
|
|
|
\cgalHeading{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.
|
|
|
|
|
|
\cgalHeading{Example}
|
|
|
|
See below a sample call of a function that uses the optional BGL named parameters.
|
|
|
|
\code
|
|
// 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));
|
|
\endcode
|
|
|
|
|
|
|
|
|
|
\cgalHeading{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.
|
|
|
|
<ul>
|
|
<li>`PolygonMesh` implements a `FaceGraph`
|
|
<li>`GeomTraits` a geometric traits class in which constructions are performed and predicates evaluated. Everywhere in this package, a \cgal `Kernel` fulfills the requirements.
|
|
</ul>
|
|
|
|
|
|
Here is the list of the named parameters available in this package:
|
|
|
|
\todo reorder this list, maybe
|
|
|
|
\cgalNPTableBegin
|
|
\cgalNPBegin{vertex_point_map} \anchor PMP_vertex_point_map
|
|
is the property map with the points associated to the vertices of the polygon mesh `pmesh`.\n
|
|
\b Type: a class model of `ReadablePropertyMap` with
|
|
`boost::graph_traits<PolygonMesh>::%vertex_descriptor` as key type and
|
|
`GeomTraits::Point_3` as value type. \n
|
|
\b Default value is \code boost::get(CGAL::vertex_point, pmesh)\endcode
|
|
\cgalNPEnd
|
|
|
|
\cgalNPBegin{use_delaunay_triangulation} \anchor PMP_use_delaunay_triangulation
|
|
enables the use of the Delaunay triangulation facet search space for hole filling functions.\n
|
|
\b Type: `bool` \n
|
|
\b Default value is `true`
|
|
\cgalNPEnd
|
|
|
|
\cgalNPBegin{density_control_factor} \anchor PMP_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.\n
|
|
\b Type: floating scalar value\n
|
|
\b Default value is `CGAL::sqrt(2)`
|
|
\cgalNPEnd
|
|
|
|
\cgalNPBegin{fairing_continuity} \anchor PMP_fairing_continuity
|
|
controls the tangential continuity of the output surface for fairing.The possible values are 0, 1 and 2, refering to the C<sup>0</sup>, C<sup>1</sup> and C<sup>2</sup> continuity.\n
|
|
\b Type: \c unsigned \c int between 0 and 2\n
|
|
\b Default value is `1`
|
|
\cgalNPEnd
|
|
|
|
\cgalNPBegin{sparse_linear_solver} \anchor PMP_sparse_linear_solver
|
|
is the solver used for fairing of polygon meshes.\n
|
|
\b Type: a class model of `SparseLinearAlgebraWithFactorTraits_d`.\n
|
|
\b Default: if \ref thirdpartyEigen "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\n
|
|
\code
|
|
CGAL::Eigen_solver_traits<
|
|
Eigen::SparseLU<
|
|
CGAL::Eigen_sparse_matrix<double>::EigenType,
|
|
Eigen::COLAMDOrdering<int> > >
|
|
\endcode
|
|
\cgalNPEnd
|
|
|
|
\cgalNPBegin{geom_traits} \anchor PMP_geom_traits
|
|
the geometric traits instance in which the mesh processing operation should be performed.\n
|
|
\b Type: a Geometric traits class.\n
|
|
\b Default type is
|
|
\code
|
|
typename CGAL::Kernel_traits<
|
|
typename boost::property_traits<
|
|
typename boost::property_map<PolygonMesh, CGAL::vertex_point_t>::type>::value_type>::Kernel
|
|
\endcode
|
|
\cgalNPEnd
|
|
|
|
\cgalNPBegin{face_index_map} \anchor PMP_face_index_map
|
|
the property map containing the index of each face of the input polygon mesh.\n
|
|
\b Type: a class model of `ReadablePropertyMap` with
|
|
`boost::graph_traits<PolygonMesh>::%face_descriptor` as key type and
|
|
the value type
|
|
\code typename boost::property_traits<
|
|
typename boost::property_map<PolygonMesh, CGAL::face_index_t>::type>::value_type
|
|
\endcode
|
|
\b Default value is \code boost::get(CGAL::face_index, pmesh)\endcode
|
|
If this internal property map exists, its values should be initialized
|
|
\cgalNPEnd
|
|
|
|
\cgalNPBegin{vertex_index_map} \anchor PMP_vertex_index_map
|
|
the property map containing the index of each vertex of the input polygon mesh.\n
|
|
\b Type: a class model of `ReadablePropertyMap` with
|
|
`boost::graph_traits<PolygonMesh>::%vertex_descriptor` as key type and
|
|
the value type
|
|
\code typename boost::property_traits<
|
|
typename boost::property_map<PolygonMesh, CGAL::vertex_index_t>::type>::value_type
|
|
\endcode
|
|
\b Default value is \code boost::get(CGAL::vertex_index, pmesh)\endcode
|
|
\cgalNPEnd
|
|
|
|
\cgalNPBegin{ number_of_iterations } \anchor PMP_number_of_iterations
|
|
the number of iterations of the sequence of iterations performed by the isotropic remeshing
|
|
algorithm.\n
|
|
\b Type : \c unsigned \c int \n
|
|
\b Default value is `1`
|
|
\cgalNPEnd
|
|
|
|
\cgalNPBegin{ edge_is_constrained_map } \anchor PMP_edge_is_constrained_map
|
|
the property map containing information about edges of the input polygon mesh being marked or not.\n
|
|
In `CGAL::Polygon_mesh_processing::isotropic_remeshing()` and `CGAL::Polygon_mesh_processing::connected_components()`,
|
|
the marked edges are constrained.\n
|
|
\b 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.\n
|
|
\b Default : if this parameter is omitted,
|
|
a default property map where no edge is constrained is provided.
|
|
\cgalNPEnd
|
|
|
|
\cgalNPBegin{ vertex_incident_patches_map } \anchor PMP_vertex_incident_patches_map
|
|
the property map containing the surface patches incident to each vertex of the input polygon mesh.\n
|
|
\b 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.\n
|
|
\b Default value is \code boost::get(CGAL::vertex_incident_patches_t, pmesh)\endcode
|
|
\cgalNPEnd
|
|
|
|
\cgalNPBegin{ first_index } \anchor PMP_first_index
|
|
The index of the first surface patch.\n
|
|
\b Type : `std::size_t`\n
|
|
\b Default : 1
|
|
\cgalNPEnd
|
|
|
|
\cgalNPBegin{ vertex_feature_degree_map } \anchor PMP_vertex_feature_degree_map
|
|
the property map containing the number of feature edges being incident to the vertices of the polygon mesh `pmesh`.\n
|
|
\b Type : a class model of `ReadWritePropertyMap` with
|
|
`boost::graph_traits<PolygonMesh>::%vertex_descriptor` as key type and
|
|
`int` as value type. It should be default constructible.\n
|
|
\b Default value is \code boost::get(CGAL::vertex_feature_degree_t(), pmesh)\endcode
|
|
\cgalNPEnd
|
|
|
|
|
|
|
|
\cgalNPBegin{ vertex_is_constrained_map } \anchor PMP_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.\n
|
|
\b 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.\n
|
|
\b Default : if this parameter is omitted,
|
|
a default property map where no vertex is constrained is provided.
|
|
\cgalNPEnd
|
|
|
|
\cgalNPBegin{protect_constraints} \anchor PMP_protect_constraints
|
|
enables the protection of constraints listed by \ref PMP_edge_is_constrained_map
|
|
"edge_is_constrained_map" and boundary edges
|
|
during isotropic remeshing. If `true`, constraint edges cannot be modified at all
|
|
during the remeshing process.\n
|
|
\b Type : `bool` \n
|
|
\b Default value is `false`
|
|
\cgalNPEnd
|
|
|
|
\cgalNPBegin{face_patch_map} \anchor PMP_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`
|
|
\n
|
|
\b 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.\n
|
|
\b 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`
|
|
\cgalNPEnd
|
|
|
|
\cgalNPBegin{number_of_relaxation_steps} \anchor PMP_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.
|
|
\n
|
|
\b Type : \c unsigned \c int \n
|
|
\b Default value is `1`
|
|
\cgalNPEnd
|
|
|
|
\cgalNPBegin{relax_constraints} \anchor PMP_relax_constraints enables the tangential relaxation step
|
|
of the isotropic remeshing algorithm to be performed on vertices that are endpoints
|
|
of constraints listed by \ref PMP_edge_is_constrained_map "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
|
|
\ref PMP_vertex_is_constrained_map "vertex_is_constrained_map") are not allowed
|
|
to move at all.
|
|
If \ref PMP_protect_constraints "protect_constraints" is
|
|
set to `true`, this parameter is ignored.
|
|
\n
|
|
\b Type : `bool` \n
|
|
\b Default value is `true`
|
|
\cgalNPEnd
|
|
|
|
\cgalNPBegin{use_random_uniform_sampling} \anchor PMP_use_random_uniform_sampling
|
|
Parameter used in `sample_triangle_mesh()` to indicate if points should be picked
|
|
in a random uniform way.
|
|
\n
|
|
\b Type : `bool` \n
|
|
\b Default value is `true`
|
|
\cgalNPEnd
|
|
|
|
\cgalNPBegin{use_grid_sampling} \anchor PMP_use_grid_sampling
|
|
Parameter used in `sample_triangle_mesh()` to indicate if points should be picked
|
|
in on a grid in each face.
|
|
\n
|
|
\b Type : `bool` \n
|
|
\b Default value is `false`
|
|
\cgalNPEnd
|
|
|
|
\cgalNPBegin{use_monte_carlo_sampling} \anchor PMP_use_monte_carlo_sampling
|
|
Parameter used in `sample_triangle_mesh()` to indicate if points should be picked
|
|
using a Monte-Carlo approach.
|
|
\n
|
|
\b Type : `bool` \n
|
|
\b Default value is `false`
|
|
\cgalNPEnd
|
|
|
|
\cgalNPBegin{sample_edges} \anchor PMP_sample_edges
|
|
Parameter used in `sample_triangle_mesh()` to indicate if a dedicated sampling
|
|
of edges should be done.
|
|
\n
|
|
\b Type : `bool` \n
|
|
\b Default value is `true`
|
|
\cgalNPEnd
|
|
|
|
\cgalNPBegin{sample_vertices} \anchor PMP_sample_vertices
|
|
Parameter used in `sample_triangle_mesh()` to indicate if triangle vertices should
|
|
be copied in the output iterator.
|
|
\n
|
|
\b Type : `bool` \n
|
|
\b Default value is `true`
|
|
\cgalNPEnd
|
|
|
|
\cgalNPBegin{sample_faces} \anchor PMP_sample_faces
|
|
Parameter used in `sample_triangle_mesh()` to indicate if the interior of faces
|
|
should be considered for the sampling.
|
|
\n
|
|
\b Type : `bool` \n
|
|
\b Default value is `true`
|
|
\cgalNPEnd
|
|
|
|
\cgalNPBegin{number_of_points_on_faces} \anchor PMP_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.
|
|
\n
|
|
\b Type : `std::size_t` \n
|
|
\b Default value is `0`
|
|
\cgalNPEnd
|
|
|
|
\cgalNPBegin{number_of_points_on_edges} \anchor PMP_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.
|
|
\n
|
|
\b Type : `std::size_t` \n
|
|
\b Default value is `0`
|
|
\cgalNPEnd
|
|
|
|
\cgalNPBegin{number_of_points_per_face} \anchor PMP_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.
|
|
\n
|
|
\b Type : `std::size_t` \n
|
|
\b Default value is `0`
|
|
\cgalNPEnd
|
|
|
|
\cgalNPBegin{number_of_points_per_edge} \anchor PMP_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.
|
|
\n
|
|
\b Type : `std::size_t` \n
|
|
\b Default value is `0`
|
|
\cgalNPEnd
|
|
|
|
\cgalNPBegin{grid_spacing} \anchor PMP_grid_spacing
|
|
Parameter used in `sample_triangle_mesh()` to set the grid spacing when using
|
|
the grid sampling method.
|
|
\n
|
|
\b Type : `double` \n
|
|
\b Default value is `0`
|
|
\cgalNPEnd
|
|
|
|
\cgalNPBegin{number_of_points_per_area_unit} \anchor PMP_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.
|
|
\n
|
|
\b Type : `double` \n
|
|
\b Default value is `0`
|
|
\cgalNPEnd
|
|
|
|
\cgalNPBegin{number_of_points_per_distance_unit} \anchor PMP_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.
|
|
\n
|
|
\b Type : `double` \n
|
|
\b Default value is `0`
|
|
\cgalNPEnd
|
|
|
|
\cgalNPBegin{do_project} \anchor PMP_do_project
|
|
Parameter used in `random_perturbation()` to set whether vertices should be re-projected
|
|
to the input surface after their geometric perturbation.
|
|
\n
|
|
\b Type : `bool` \n
|
|
\b Default value is `true`
|
|
\cgalNPEnd
|
|
|
|
\cgalNPBegin{random_seed} \anchor PMP_random_seed
|
|
Parameter used in `random_perturbation()` to choose a seed to initialize
|
|
the random number generator `CGAL::Random()`.
|
|
If this parameter is not provided,
|
|
the random number generator is initialized with `CGAL::Random()`,
|
|
and perturbation is not deterministic
|
|
(i.e. not reproducible from one run to the other).
|
|
\n
|
|
\b Type : `unsigned int` \n
|
|
\b Default is that this variable is not set
|
|
\cgalNPEnd
|
|
|
|
\cgalNPBegin{use_weights} \anchor PMP_use_weights
|
|
Parameter used in `angle_remeshing()` to set whether angles should carry weights while remeshing
|
|
so that small angles carry more weight.
|
|
\n
|
|
\b Type : `bool` \n
|
|
\b Default is `false`
|
|
\cgalNPEnd
|
|
|
|
\cgalNPBegin{gradient_descent_precision} \anchor PMP_gradient_descent_precision
|
|
Parameter used in `smooth_area()` to set precision to be met while the relative energy
|
|
between iterations of each triagle is minimized. Triangle energy is defined based on its area compared to the
|
|
average area of all triagnles adjacent to the vertex that is being moved.
|
|
\n
|
|
\b Type : `double` \n
|
|
\b Default is `0.001`
|
|
\cgalNPEnd
|
|
|
|
\cgalNPBegin{distance_precision} \anchor PMP_distance_precision
|
|
Parameter used in `compatible_remeshing()` to set precision for the Hausdorff distance
|
|
of the mesh between the previous and the current iteration that has to be achieved for a mesh to converge
|
|
during smoothing.
|
|
\n
|
|
\b Type : `double` \n
|
|
\b Default is `0.01`
|
|
\cgalNPEnd
|
|
|
|
\cgalNPTableEnd
|
|
|
|
*/
|