Named Parameters

How to use BGL Optional Named Parameters

The notion of named parameters was introduced in the BGL. Details can be found from: https://www.boost.org/libs/graph/doc/bgl_named_params.html. Named parameters enable the user to specify only those parameters which are really needed, by name, making the parameter ordering not required. See also BGL Named Parameters.

The sequence of named parameters should start with CGAL::parameters::. The function all_default() can be used to indicate that default values of optional named parameters are used.

Example

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

// tm: input triangle mesh to be approximated
// method: seeding initialization method
// number_of_proxies: number of proxies used to approximate the input mesh
// number_of_iterations: number of relaxation iterations after initialization
// anchors: output anchor points
// triangles: output triplets of indexed triangles

CGAL::Surface_mesh_approximation::approximate_triangle_mesh(tm,
  CGAL::parameters::seeding_method(method).
    max_number_of_proxies(number_of_proxies).
    number_of_iterations(number_of_iterations).
    anchors(std::back_inserter(anchors)).
    triangles(std::back_inserter(triangles)));

List of Available Named Parameters

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

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

• TriangleMesh implements a FaceListGraph
• GeomTraits a geometric traits class in which constructions are performed and predicates evaluated. Throughout this package, a CGAL Kernel fulfills the requirements.

The named parameters available in this package are categorized into 3 groups below.

1. Parameters for the Approximation Step

geom_traits	the geometric traits instance in which the mesh approximation operation should be performed. Type: a Geometric traits class. Default type is typename CGAL::Kernel_traits< typename boost::property_traits< typename boost::property_map<TriangleMesh, CGAL::vertex_point_t>::type>::value_type>::Kernel
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<TriangleMesh>::vertex_descriptor as key type and GeomTraits::Point_3 as value type. Default value is boost::get(CGAL::vertex_point, pmesh)
verbose_level	set the verbose level of the function. Type : CGAL::Surface_mesh_approximation::Verbose_level Default value is CGAL::Surface_mesh_approximation::SILENT
seeding_method	the selection of seeding method. Type : CGAL::Surface_mesh_approximation::Seeding_method Default value is CGAL::Surface_mesh_approximation::HIERARCHICAL
max_number_of_proxies	the maximum number of proxies used to approximate the input mesh. Type : std::size_t Default value is num_faces(tm) / 3, used when min_error_drop is also not provided
min_error_drop	the minimum total error drop to approximate the input mesh. Type : GeomTraits::FT Default value is 0.1, used when max_number_of_proxies is also not provided.
number_of_relaxations	the number of relaxation iterations interleaved within seeding. Type : std::size_t Default value is 5
number_of_iterations	the number of partitioning and fitting iterations after seeding. Type : std::size_t Default value is std::min(std::max(number_of_faces / max_number_of_proxies, 20), 60)

2. Parameters for the Meshing Step

subdivision_ratio	the chord subdivision ratio threshold used in the meshing step. Type : GeomTraits::FT Default value is 5.0
relative_to_chord	set the chord subdivision ratio threshold relative to the chord length. Type : bool Default value is false
with_dihedral_angle	set the chord subdivision with dihedral angle weighting. Type : bool Default value is false
optimize_anchor_location	set if optimize the anchor position in the meshing step. Type : bool Default value is true
pca_plane	set the plane approximated with the PCA algorithm in the meshing step. Type : bool Default value is false

3. Parameters for Retrieving the Results

face_proxy_map	the property map outputs the proxy index of each face of the input polygon mesh. Type: a class model of WritablePropertyMap with boost::graph_traits<TriangleMesh>::face_descriptor as key type and the value type std::size_t Default : if this parameter is omitted, no output operation is performed
proxies	an OutputIterator to put proxies in. Type : a class model of OutputIterator with CGAL::Surface_mesh_approximation::L21_metric_vector_proxy_no_area_weighting::Proxy value type. Default : if this parameter is omitted, no output operation is performed
anchors	an OutputIterator to put anchor points in. Type : a class model of OutputIterator with GeomTraits::Point_3 value type. Default : if this parameter is omitted, no output operation is performed
triangles	an OutputIterator to put indexed triangles in. Type : a class model of OutputIterator with CGAL::cpp11::array<std::size_t, 3> value type. Default : if this parameter is omitted, no output operation is performed

Functions
unspecified_type	CGAL::Surface_mesh_approximation::parameters::all_default ()
	This function is used when default parameters are just fine for approximation or meshing.