cgal/Surface_mesh_approximation/doc/Surface_mesh_approximation/NamedParameters.txt

/*!
\defgroup vsa_namedparameters Named Parameters
\ingroup PkgTSMARef

\cgalHeading{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 \ref bgl_namedparameters.

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.
<!-- clashing tag with PMP named space -->

\cgalHeading{Example}

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

\code
// 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)));
\endcode

\cgalHeading{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.

<ul>
<li>`TriangleMesh` implements a `FaceListGraph`
<li>`GeomTraits` a geometric traits class in which constructions are performed and predicates evaluated. Throughout this package, a \cgal `Kernel` fulfills the requirements.
</ul>

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

\cgalHeading{1. Parameters for the Approximation Step}
\cgalNPTableBegin

\cgalNPBegin{geom_traits} \anchor VSA_geom_traits
 the geometric traits instance in which the mesh approximation 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<TriangleMesh, CGAL::vertex_point_t>::type>::value_type>::Kernel
\endcode
\cgalNPEnd

\cgalNPBegin{vertex_point_map} \anchor VSA_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<TriangleMesh>::%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{verbose_level} \anchor VSA_verbose_level
set the verbose level of the function.\n
\b Type : \c CGAL::Surface_mesh_approximation::Verbose_level \n
\b Default value is `CGAL::Surface_mesh_approximation::SILENT`
\cgalNPEnd

\cgalNPBegin{seeding_method} \anchor VSA_seeding_method
the selection of seeding method.\n
\b Type : \c CGAL::Surface_mesh_approximation::Seeding_method \n
\b Default value is `CGAL::Surface_mesh_approximation::HIERARCHICAL`
\cgalNPEnd

\cgalNPBegin{max_number_of_proxies} \anchor VSA_max_number_of_proxies
the maximum number of proxies used to approximate the input mesh.\n
\b Type : `std::size_t` \n
\b Default value is `num_faces(tm) / 3`, used when `min_error_drop` is also not provided
\cgalNPEnd

\cgalNPBegin{min_error_drop} \anchor VSA_min_error_drop
the minimum total error drop to approximate the input mesh.\n
\b Type : `GeomTraits::FT` \n
\b Default value is `0.1`, used when `max_number_of_proxies` is also not provided.
\cgalNPEnd

\cgalNPBegin{number_of_relaxations} \anchor VSA_number_of_relaxations
the number of relaxation iterations interleaved within seeding.\n
\b Type : `std::size_t` \n
\b Default value is `5`
\cgalNPEnd

\cgalNPBegin{number_of_iterations} \anchor VSA_number_of_iterations
the number of partitioning and fitting iterations after seeding.\n
\b Type : `std::size_t` \n
\b Default value is `std::min(std::max(number_of_faces / max_number_of_proxies, 20), 60)`
\cgalNPEnd

\cgalNPTableEnd

\cgalHeading{2. Parameters for the Meshing Step}
\cgalNPTableBegin

\cgalNPBegin{subdivision_ratio} \anchor VSA_subdivision_ratio
the chord subdivision ratio threshold used in the meshing step.\n
\b Type : `GeomTraits::FT` \n
\b Default value is `5.0`
\cgalNPEnd

\cgalNPBegin{relative_to_chord} \anchor VSA_relative_to_chord
set the chord subdivision ratio threshold relative to the chord length.\n
\b Type : `bool` \n
\b Default value is `false`
\cgalNPEnd

\cgalNPBegin{with_dihedral_angle} \anchor VSA_with_dihedral_angle
set the chord subdivision with dihedral angle weighting.\n
\b Type : `bool` \n
\b Default value is `false`
\cgalNPEnd

\cgalNPBegin{optimize_anchor_location} \anchor VSA_optimize_anchor_location set if optimize the anchor position in the meshing step.\n
\b Type : `bool` \n
\b Default value is `true`
\cgalNPEnd

\cgalNPBegin{pca_plane} \anchor VSA_pca_plane
set the plane approximated with the PCA algorithm in the meshing step.\n
\b Type : `bool` \n
\b Default value is `false`
\cgalNPEnd

\cgalNPTableEnd

\cgalHeading{3. Parameters for Retrieving the Results}
\cgalNPTableBegin

\cgalNPBegin{face_proxy_map} \anchor VSA_face_proxy_map
the property map outputs the proxy index of each face of the input polygon mesh.\n
\b Type: a class model of `WritablePropertyMap` with `boost::graph_traits<TriangleMesh>::%face_descriptor` as key type and the value type `std::size_t`\n
\b Default : if this parameter is omitted, no output operation is performed
\cgalNPEnd

\cgalNPBegin{proxies} \anchor VSA_proxies
an `OutputIterator` to put proxies in.\n
\b Type : a class model of `OutputIterator` with `CGAL::Surface_mesh_approximation::L21_metric_vector_proxy_no_area_weighting::Proxy` value type.\n
\b Default : if this parameter is omitted, no output operation is performed
\cgalNPEnd

\cgalNPBegin{anchors} \anchor VSA_anchors
an `OutputIterator` to put anchor points in.\n
\b Type : a class model of `OutputIterator` with `GeomTraits::%Point_3` value type.\n
\b Default : if this parameter is omitted, no output operation is performed
\cgalNPEnd

\cgalNPBegin{triangles} \anchor VSA_triangles
an `OutputIterator` to put indexed triangles in.\n
\b Type : a class model of `OutputIterator` with `CGAL::cpp11::array<std::size_t, 3>` value type.\n
\b Default : if this parameter is omitted, no output operation is performed
\cgalNPEnd

\cgalNPTableEnd

*/