- the chord subdivision ratio threshold to the chord length or average edge length
-
Type:
geom_traits::FT -
Default:
5.0
|
CGAL 6.0 - Triangulated Surface Mesh Approximation
|
#include <CGAL/Variational_shape_approximation.h>
Main class for Variational Shape Approximation algorithm.
It is based on [1]. For simple use cases, the function CGAL::Surface_mesh_approximation::approximate_mesh() might be sufficient.
| TriangleMesh | a model of FaceListGraph |
| VertexPointMap | a ReadablePropertyMap with boost::graph_traits<TriangleMesh>::vertex_descriptor as key and GeomTraits::Point_3 as value type |
| ErrorMetricProxy | a model of ErrorMetricProxy |
| GeomTraits | a model of Kernel |
| Concurrency_tag | concurrency tag. |
Types | |
| typedef GeomTraits | Geom_traits |
| Geometric traits type. | |
| typedef ErrorMetricProxy | Error_metric |
| Error metric for proxy fitting type. | |
| typedef Error_metric::Proxy | Proxy |
| Proxy type. | |
| typedef std::array< std::size_t, 3 > | Indexed_triangle |
| Indexed triangle type. | |
Construction | |
| Variational_shape_approximation (const TriangleMesh &tm, const VertexPointMap &vpoint_map, const Error_metric &error_metric) | |
| initializes internal data for the approximation. | |
Approximation | |
| template<typename NamedParameters > | |
| std::size_t | initialize_seeds (const NamedParameters &np) |
| initializes the seeds with both maximum number of proxies and minimum error drop stop criteria. | |
| FT | run (std::size_t nb_iterations=1) |
| runs the partitioning and fitting processes on the whole surface. | |
| bool | run_to_convergence (const FT cvg_threshold, const std::size_t max_iterations=100, std::size_t avg_interval=3) |
calls run while error decrease is greater than cvg_threshold. | |
| FT | compute_total_error () |
| computes fitting error of current partition to the proxies. | |
| std::size_t | add_to_furthest_proxies (const std::size_t nb_proxies, const std::size_t nb_iterations=5) |
| adds proxies to the worst regions one by one. | |
| std::size_t | add_proxies_error_diffusion (const std::size_t nb_proxies) |
| adds proxies by diffusing fitting error into current partition. | |
Refinement Operations | |
| std::size_t | teleport_proxies (const std::size_t nb_proxies, const std::size_t nb_iterations=5, const bool no_threshold_test=false) |
| teleports the local minimum to the worst region by combining the merging and adding processes. | |
| FT | merge (const std::size_t px0, const std::size_t px1) |
| merges two specified adjacent regions. | |
| std::optional< std::pair< std::size_t, std::size_t > > | find_best_merge (const bool use_threshold_test) |
| simulates merging and local re-fitting of all pairs of adjacent proxies and finds the best pair to merge. | |
| bool | split (const std::size_t px_idx, const std::size_t n=2, const std::size_t nb_relaxations=10) |
| splits within a specified proxy area via N-section (by default bisection), other regions are not affected. | |
Meshing | |
| template<typename NamedParameters > | |
| bool | extract_mesh (const NamedParameters &np) |
| extracts the output mesh in the form of an indexed triangle set. | |
Output | |
| template<typename NamedParameters > | |
| void | output (const NamedParameters &np) const |
| outputs approximation results. | |
| std::size_t | number_of_proxies () const |
| returns the number of proxies. | |
| CGAL::Variational_shape_approximation< TriangleMesh, VertexPointMap, ErrorMetricProxy, GeomTraits, Concurrency_tag >::Variational_shape_approximation | ( | const TriangleMesh & | tm, |
| const VertexPointMap & | vpoint_map, | ||
| const Error_metric & | error_metric | ||
| ) |
initializes internal data for the approximation.
| tm | CGAL TriangleMesh on which approximation operates |
| vpoint_map | vertex point map of the mesh |
| error_metric | an ErrorMetricProxy object |
| std::size_t CGAL::Variational_shape_approximation< TriangleMesh, VertexPointMap, ErrorMetricProxy, GeomTraits, Concurrency_tag >::add_proxies_error_diffusion | ( | const std::size_t | nb_proxies | ) |
adds proxies by diffusing fitting error into current partition.
Each partition is added with the number of proxies in proportion to its fitting error.
| nb_proxies | number of proxies to be added |
| std::size_t CGAL::Variational_shape_approximation< TriangleMesh, VertexPointMap, ErrorMetricProxy, GeomTraits, Concurrency_tag >::add_to_furthest_proxies | ( | const std::size_t | nb_proxies, |
| const std::size_t | nb_iterations = 5 |
||
| ) |
adds proxies to the worst regions one by one.
The re-fitting is performed after each proxy is inserted.
| nb_proxies | number of proxies to be added |
| nb_iterations | number of re-fitting iterations |
| FT CGAL::Variational_shape_approximation< TriangleMesh, VertexPointMap, ErrorMetricProxy, GeomTraits, Concurrency_tag >::compute_total_error | ( | ) |
computes fitting error of current partition to the proxies.
| bool CGAL::Variational_shape_approximation< TriangleMesh, VertexPointMap, ErrorMetricProxy, GeomTraits, Concurrency_tag >::extract_mesh | ( | const NamedParameters & | np | ) |
extracts the output mesh in the form of an indexed triangle set.
| NamedParameters | a sequence of Named Parameters |
| np | an optional sequence of Named Parameters among the ones listed below |
true if the extracted surface mesh is manifold, and false otherwise.
| |
| |
| |
| |
| |
| |
|
| std::optional< std::pair< std::size_t, std::size_t > > CGAL::Variational_shape_approximation< TriangleMesh, VertexPointMap, ErrorMetricProxy, GeomTraits, Concurrency_tag >::find_best_merge | ( | const bool | use_threshold_test | ) |
simulates merging and local re-fitting of all pairs of adjacent proxies and finds the best pair to merge.
| use_threshold_test | if true and a best pair of proxies is found, it is returned only if the error change after the merge is lower than the half of the maximum proxy error. |
| std::size_t CGAL::Variational_shape_approximation< TriangleMesh, VertexPointMap, ErrorMetricProxy, GeomTraits, Concurrency_tag >::initialize_seeds | ( | const NamedParameters & | np | ) |
initializes the seeds with both maximum number of proxies and minimum error drop stop criteria.
The first criterion met stops the seeding. Parameters out of range are ignored.
| NamedParameters | a sequence of Named Parameters |
| np | an optional sequence of Named Parameters among the ones listed below |
| |
| |
| |
|
| FT CGAL::Variational_shape_approximation< TriangleMesh, VertexPointMap, ErrorMetricProxy, GeomTraits, Concurrency_tag >::merge | ( | const std::size_t | px0, |
| const std::size_t | px1 | ||
| ) |
merges two specified adjacent regions.
The overall re-fitting is not performed and the proxy index map is maintained.
| px0 | the kept proxy index |
| px1 | the merged and erased proxy index, proxies with greater indeies are decreased by 1 to fill the gap |
| void CGAL::Variational_shape_approximation< TriangleMesh, VertexPointMap, ErrorMetricProxy, GeomTraits, Concurrency_tag >::output | ( | const NamedParameters & | np | ) | const |
outputs approximation results.
| NamedParameters | a sequence of Named Parameters |
| np | an optional sequence of Named Parameters among the ones listed below |
| |
| |
| |
|
| FT CGAL::Variational_shape_approximation< TriangleMesh, VertexPointMap, ErrorMetricProxy, GeomTraits, Concurrency_tag >::run | ( | std::size_t | nb_iterations = 1 | ) |
runs the partitioning and fitting processes on the whole surface.
| nb_iterations | number of iterations. |
| bool CGAL::Variational_shape_approximation< TriangleMesh, VertexPointMap, ErrorMetricProxy, GeomTraits, Concurrency_tag >::run_to_convergence | ( | const FT | cvg_threshold, |
| const std::size_t | max_iterations = 100, |
||
| std::size_t | avg_interval = 3 |
||
| ) |
calls run while error decrease is greater than cvg_threshold.
| cvg_threshold | the percentage of error change between two successive runs, should be in range (0, 1). |
| max_iterations | maximum number of iterations allowed |
| avg_interval | size of error average interval to have smoother convergence curve, if 0 is assigned, 1 is used instead. |
true if converged before hitting the maximum iterations. | bool CGAL::Variational_shape_approximation< TriangleMesh, VertexPointMap, ErrorMetricProxy, GeomTraits, Concurrency_tag >::split | ( | const std::size_t | px_idx, |
| const std::size_t | n = 2, |
||
| const std::size_t | nb_relaxations = 10 |
||
| ) |
splits within a specified proxy area via N-section (by default bisection), other regions are not affected.
| px_idx | proxy index. |
| n | number of split sections. |
| nb_relaxations | number of relaxations within the proxy area px_idx after the split |
true if split succeeds, and false otherwise. | std::size_t CGAL::Variational_shape_approximation< TriangleMesh, VertexPointMap, ErrorMetricProxy, GeomTraits, Concurrency_tag >::teleport_proxies | ( | const std::size_t | nb_proxies, |
| const std::size_t | nb_iterations = 5, |
||
| const bool | no_threshold_test = false |
||
| ) |
teleports the local minimum to the worst region by combining the merging and adding processes.
The re-fitting is performed after each teleportation. Here if we specify more than one proxy this means we teleport in a naive iterative fashion.
| nb_proxies | number of proxies requested to teleport. |
| nb_iterations | number of re-fitting iterations. |
| no_threshold_test | if true, no check on the approximation error before merging a pair of proxies is done. In other words, find_best_merge(!no_threshold_test) is called. |