mirror of https://github.com/CGAL/cgal
fix named parameters doc
This commit is contained in:
Lingjie Zhu
parent
605486191c
commit
2f15e2fc13
|
|
@ -10,7 +10,7 @@ HIDE_UNDOC_CLASSES = true
|
|||
# macros to be used inside the code
|
||||
ALIASES += "cgalNamedParamsBegin=<dl class=\"params\"><dt>Named Parameters</dt><dd> <table class=\"params\">"
|
||||
ALIASES += "cgalNamedParamsEnd=</table> </dd> </dl>"
|
||||
ALIASES += "cgalParamBegin{1}=<tr><td class=\"paramname\">\ref PMP_\1 \"\1\"</td><td>"
|
||||
ALIASES += "cgalParamBegin{1}=<tr><td class=\"paramname\">\ref VSA_\1 \"\1\"</td><td>"
|
||||
ALIASES += "cgalParamEnd=</td></tr>"
|
||||
|
||||
#macros for NamedParameters.txt
|
||||
|
|
|
|||
|
|
@ -4,6 +4,8 @@
|
|||
|
||||
\cgalHeading{How to use BGL Optional Named Parameters}
|
||||
|
||||
<!-- This page contains similar content to the \ref PkgPolygonMeshProcessing. -->
|
||||
|
||||
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.
|
||||
|
|
@ -23,27 +25,23 @@ The sequence of named parameters should start with `CGAL::Polygon_mesh_processin
|
|||
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));
|
||||
// input : input triangle mesh to be approximated
|
||||
// output : output polyhedron mesh
|
||||
// init : seed initialization method
|
||||
// num_proxies : number of proxies used to approximate the geometry
|
||||
// num_iterations : number of relaxation iterations
|
||||
// anchors : the container to get the anchor points
|
||||
vsa_mesh_approximation(input,
|
||||
, output
|
||||
, CGAL::VSA::parameters::init_method(init)
|
||||
.number_of_proxies(num_proxies)
|
||||
.number_of_iterations(num_iterations)
|
||||
.anchor_point(std::back_inserter(anchors)));
|
||||
\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 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 polygon mesh processing functions and classes. Note that, for some of these functions, the type is more specific.
|
||||
|
||||
|
|
@ -52,19 +50,11 @@ In the following, we assume that the following types are provided as template pa
|
|||
<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:
|
||||
|
||||
\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{geom_traits} \anchor PMP_geom_traits
|
||||
\cgalNPBegin{geom_traits} \anchor VSA_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
|
||||
|
|
@ -75,105 +65,65 @@ typename CGAL::Kernel_traits<
|
|||
\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
|
||||
\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<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{init_method} \anchor VSA_init_method
|
||||
the selection of seed initialization method\n
|
||||
\b Type : \c unsigned \c int \n
|
||||
\b Default value is `1`
|
||||
\cgalNPEnd
|
||||
|
||||
\cgalNPBegin{number_of_proxies} \anchor VSA_number_of_proxies
|
||||
the number of proxies used to approximate the input mesh.\n
|
||||
\b Type : `std::size_t` \n
|
||||
\b Default value is `0`
|
||||
\cgalNPEnd
|
||||
|
||||
\cgalNPBegin{number_of_iterations} \anchor VSA_number_of_iterations
|
||||
the number of iterations of the sequence of iterations performed by the isotropic remeshing
|
||||
algorithm.\n
|
||||
\b Type : `std::size_t` \n
|
||||
\b Default value is `10`
|
||||
\cgalNPEnd
|
||||
|
||||
\cgalNPBegin{chord_subdivide} \anchor VSA_chord_subdivide
|
||||
the chord subdivision threshold used in the meshing step.\n
|
||||
\b Type : `std::double` \n
|
||||
\b Default value is `1`
|
||||
\cgalNPEnd
|
||||
|
||||
\cgalNPBegin{face_proxy_map} \anchor VSA_face_proxy_map
|
||||
the property map containing the proxy 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
|
||||
the value type `std::size_t`
|
||||
\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
|
||||
\cgalNPBegin{anchor_vertex} \anchor VSA_anchor_vertex
|
||||
an `OutputIterator` to write anchor vertex in.\n
|
||||
\b Type : a class model of `OutputIterator` with
|
||||
`boost::graph_traits<PolygonMesh>::%vertex_descriptor` value type.\n
|
||||
\b Default : if this parameter is omitted, no output operation performed
|
||||
\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`
|
||||
\cgalNPBegin{anchor_point} \anchor VSA_anchor_point
|
||||
an `OutputIterator` to write anchor point 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 performed
|
||||
\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 constrained or not.\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_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{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{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`
|
||||
\cgalNPBegin{indexed_triangles} \anchor VSA_indexed_triangles
|
||||
an `OutputIterator` to write the approximation triangles in.\n
|
||||
\b Type : a class model of `OutputIterator` with `std::size_t` value type.\n
|
||||
\b Default : if this parameter is omitted, no output operation performed
|
||||
\cgalNPEnd
|
||||
|
||||
\cgalNPTableEnd
|
||||
|
|
|
|||
|
|
@ -25,8 +25,8 @@ framework to approximate a triangle surface with shape primitives. Given a trian
|
|||
to drive the distortion error down with the parameterized <em>geometric proxies</em>. The overview of the algorithm can be found in \ref sma_approximation.
|
||||
|
||||
This package offers both the approximation and mesh extraction functionalities.
|
||||
They can be accessed as simple free functions or more advanced interactive class-based interfaces with customized metric and proxy.
|
||||
It can be used as not only an approximation package, but also a mesh simplification, shape discovery one or a complement to current mesh segmentation package.
|
||||
They can be accessed through a free function or more advanced interactive class-based interfaces with customized metric and proxy.
|
||||
Apart from approximation, it can be viewed as a package for simplification or shape discovery or a complement to current mesh segmentation package.
|
||||
|
||||
\section sma_overview Overview
|
||||
|
||||
|
|
@ -145,6 +145,31 @@ In the following example, it defines a simple point-wise proxy to achieves a com
|
|||
|
||||
\section sma_perf Performances
|
||||
|
||||
We provide some performance comparisons in this section.
|
||||
The machine used is a PC running Windows10 X64 with an Intel Xeon E5-1620 clocked at 3.70 GHz with 32GB of RAM.
|
||||
The program has been optimized with the O2 option with Visual Studio 2015.
|
||||
<!-- By default the kernel used is Simple_cartesian<double> (the fastest in our experiments). -->
|
||||
|
||||
We compare the running timing of 3 phase of the algorithm: seeding, relaxation and meshing. By default the kernel used is `Exact_predicates_inexact_constructions_kernel` (`EPICK`).
|
||||
|
||||
<center>
|
||||
Number of triangles | Random Seeding | Incremental Seeding | Hierarchical Seeding | Relaxation | Meshing
|
||||
---------------------| ------------: | -----------------: | ------------------: | --------: | ------:
|
||||
7,828 | tbd | tbd | tbd | tbd | tbd
|
||||
20,188 | tbd | tbd | tbd | tbd | tbd
|
||||
88,928 | tbd | tbd | tbd | tbd | tbd
|
||||
</center>
|
||||
|
||||
With different metrics, we compare the running time and complexity of the output mesh.
|
||||
|
||||
<center>
|
||||
Number of triangles | \f$ \mathcal{L}^{2,1} \f$ | \f$ \mathcal{L}^2 \f$ | %Compact Metric
|
||||
---------------------| -----------------------: | -------------------: | -------------:
|
||||
7,828 | tbd | tbd | tbd
|
||||
20,188 | tbd | tbd | tbd
|
||||
88,928 | tbd | tbd | tbd
|
||||
</center>
|
||||
|
||||
\section sma_history Design and Implementation History
|
||||
|
||||
This package is the result of the work of Lingjie Zhu during the 2017 season
|
||||
|
|
|
|||
|
|
@ -39,14 +39,21 @@ namespace CGAL
|
|||
* \cgalParamBegin{vertex_point_map} the property map with the points associated
|
||||
* to the vertices of `tm_in`. Instance of a class model of `ReadWritePropertyMap`.
|
||||
* \cgalParamEnd
|
||||
* \cgalParamBegin{face_index_map} a property map containing the index of each face of `tm_in`
|
||||
* \cgalParamBegin{init_method} the selection of seed initialization method.
|
||||
* \cgalParamEnd
|
||||
* \cgalParamBegin{number_of_iterations} the number of iterations for the
|
||||
* sequence of atomic operations performed (listed in the above description)
|
||||
* \cgalParamBegin{number_of_proxies} the number of proxies to approximate the geometry.
|
||||
* \cgalParamEnd
|
||||
* \cgalParamBegin{face_patch_map} a property map with the patch id's associated to the
|
||||
faces of `faces`. Instance of a class model of `ReadWritePropertyMap`. It gets
|
||||
updated during the remeshing process while new faces are created.
|
||||
* \cgalParamBegin{number_of_iterations} the relaxation iterations.
|
||||
* \cgalParamEnd
|
||||
* \cgalParamBegin{chord_subdivide} the threshold of chord subdivision.
|
||||
* \cgalParamEnd
|
||||
* \cgalParamBegin{face_proxy_map} a property map containing the assigned proxy index of each face of `tm_in`
|
||||
* \cgalParamEnd
|
||||
* \cgalParamBegin{anchor_vertex} the anchor verteices output iterator
|
||||
* \cgalParamEnd
|
||||
* \cgalParamBegin{anchor_point} the anchor points output iterator
|
||||
* \cgalParamEnd
|
||||
* \cgalParamBegin{indexed_triangles} the indexed triangles output iterator
|
||||
* \cgalParamEnd
|
||||
* \cgalNamedParamsEnd
|
||||
*/
|
||||
|
|
|
|||
Loading…
Reference in New Issue