songsenand
/
cgal
mirror of https://github.com/CGAL/cgal
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

clean lloyd_optimize_mesh_3

This commit is contained in:
Sébastien Loriot 2022-09-20 14:27:30 +02:00
parent 928ef0b447
commit e23d77bbf7
1 changed files with 113 additions and 117 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

230
Mesh_3/include/CGAL/lloyd_optimize_mesh_3.h
View File

@ -32,123 +32,119 @@
namespace CGAL { namespace CGAL {
/*! /*!
\ingroup PkgMesh3Functions * \ingroup PkgMesh3Functions
*
The function `lloyd_optimize_mesh_3()` is a mesh optimization process * The function `lloyd_optimize_mesh_3()` is a mesh optimization process
based on the minimization of a global energy function. * based on the minimization of a global energy function.
*
In `lloyd_optimize_mesh_3()`, the minimized global energy may be interpreted * In `lloyd_optimize_mesh_3()`, the minimized global energy may be interpreted
as the \f$ L^1\f$-norm of the error achieved * as the \f$ L^1\f$-norm of the error achieved
when the function \f$ x^2\f$ is interpolated on the mesh domain * when the function \f$ x^2\f$ is interpolated on the mesh domain
using a piecewise linear function which is linear * using a piecewise linear function which is linear
in each cell of the Voronoi diagram of the mesh vertices. * in each cell of the Voronoi diagram of the mesh vertices.
*
The optimizer `lloyd_optimize_mesh_3()` works in iterative steps. * The optimizer `lloyd_optimize_mesh_3()` works in iterative steps.
At each iteration, mesh vertices are moved into * At each iteration, mesh vertices are moved into
positions that bring to zero the energy gradient * positions that bring to zero the energy gradient
and the Delaunay triangulation is updated. * and the Delaunay triangulation is updated.
Vertices on the mesh boundaries are handled * Vertices on the mesh boundaries are handled
in a special way so as to preserve an accurate * in a special way so as to preserve an accurate
representation of the domain boundaries. * representation of the domain boundaries.
*
\pre `time_limit` \f$ \geq\f$ 0 and 0 \f$ \leq\f$ `convergence` \f$ \leq\f$ 1 and 0 \f$ \leq\f$ `freeze_bound` \f$ \leq\f$ 1 * \tparam C3T3 is required to be a model of the concept
* `MeshComplex_3InTriangulation_3`.
\tparam C3T3 is required to be a model of the concept * The argument `c3t3`, passed by
`MeshComplex_3InTriangulation_3`. * reference, provides the initial mesh
The argument `c3t3`, passed by * and is modified by the algorithm
reference, provides the initial mesh * to represent the final optimized mesh.
and is modified by the algorithm *
to represent the final optimized mesh. * \tparam MD is required to be a model of the concept
* `MeshDomain_3`. The argument `domain` must be the `MD`
\tparam MD is required to be a model of the concept * object used to create the `c3t3` parameter.
`MeshDomain_3`. The argument `domain` must be the `MD` *
object used to create the `c3t3` parameter. * \tparam NamedParameters a sequence of \ref bgl_namedparameters "Named Parameters"
*
\tparam NamedParameters a sequence of \ref bgl_namedparameters "Named Parameters" * @param c3t3 the initial mesh that will be modified by the algorithm to represent the final optimized mesh.
* @param domain the domain to be discretized
@param c3t3 the initial mesh that will be modified by the algorithm to represent the final optimized mesh. * @param np an optional sequence of \ref bgl_namedparameters "Named Parameters" among the ones listed below:
@param domain the domain to be discretized *
@param np an optional sequence of \ref bgl_namedparameters "Named Parameters" among the ones listed below: * \cgalNamedParamsBegin
* \cgalParamNBegin{time_limit}
\cgalNamedParamsBegin * \cgalParamDescription{to set up, in seconds, a CPU time limit after which the optimization process is stopped.
\cgalParamNBegin{time_limit} * This time is measured using `CGAL::Real_timer`. 0 means that there is no time limit.}
\cgalParamDescription{to set up, in seconds, a CPU time limit after which the optimization process is stopped. * \cgalParamType{`double`}
This time is measured using `CGAL::Real_timer`. 0 means that there is no time limit.} * \cgalParamExtra{\pre `time_limit >= 0`}
\cgalParamType{`double`} * \cgalParamDefault{0}
\cgalParamExtra{\pre `time_limit` \f$ \geq\f$ 0} * \cgalParamNEnd
\cgalParamDefault{0} * \cgalParamNBegin{max_iteration_number}
* \cgalParamDescription{limit on the number of performed iterations. 0 means that there is
\cgalParamNBegin{max_iteration_number} * no limit on the number of performed iterations.}
\cgalParamDescription{limit on the number of performed iterations. 0 means that there is * \cgalParamExtra{\pre `max_iteration_number >=0`}
no limit on the number of performed iterations.} * \cgalParamType{`int`}
\cgalParamExtra{\pre `max_iteration_number >=0`} * \cgalParamDefault{0}
\cgalParamType{`int`} * \cgalParamNEnd
\cgalParamDefault{0} * \cgalParamNBegin{freeze_bound}
* \cgalParamDescription{designed to reduce running time of each optimization iteration.
* Any vertex that has a displacement less than a given fraction of the length
\cgalParamNBegin{freeze_bound} * of its shortest incident edge, is frozen (i.e.\ is not relocated).
\cgalParamDescription{designed to reduce running time of each optimization iteration. * The parameter `freeze_bound` gives the threshold ratio.
Any vertex that has a displacement less than a given fraction of the length * If it is set to 0, freezing of vertices is disabled.}
of its shortest incident edge, is frozen (i.e.\ is not relocated). * \cgalParamExtra{\pre `0<= freeze_bound <=1`}
The parameter `freeze_bound` gives the threshold ratio. * \cgalParamType{`double`}
If it is set to 0, freezing of vertices is disabled.} * \cgalParamDefault{0.001}
\cgalParamExtra{\pre `0<= freeze_bound <=1} * \cgalParamNEnd
\cgalParamType{`double`} * \cgalParamNBegin{convergence}
\cgalParamDefault{0.001} * \cgalParamDescription{threshold ratio of stopping criterion based on convergence: the optimization process is stopped
* when at the last iteration the displacement of any vertex is less than
\cgalParamNBegin{convergence} * a given fraction of the length of the shortest edge incident to that vertex.}
\cgalParamDescription{threshold ratio of stopping criterion based on convergence: the optimization process is stopped * \cgalParamExtra{\pre `0 <=convergence <= 1`}
when at the last iteration the displacement of any vertex is less than * \cgalParamType{`double`}
a given fraction of the length of the shortest edge incident to that vertex.} * \cgalParamDefault{0.02}
\cgalParamExtra{\pre `0 <=convergence <= 1`} * \cgalParamNEnd
\cgalParamType{`double`} * \cgalParamNBegin{do_freeze}
\cgalParamDefault{0.001} * \cgalParamDescription{completes the `freeze_bound` parameter. If it is set to `true` (default value),
* frozen vertices will not move anymore in next iterations. Otherwise, at each iteration, any vertex that
\cgalParamNBegin{do_freeze} * moves, unfreezes all its incident vertices.}
\cgalParamDescription{completes the `freeze_bound` parameter. If it is set to `true` (default value), * \cgalParamType{`bool`}
frozen vertices will not move anymore in next iterations. Otherwise, at each iteration, any vertex that * \cgalParamDefault{true}
moves, unfreezes all its incident vertices.} * \cgalParamNEnd
\cgalParamType{`bool`} * \cgalNamedParamsEnd
\cgalParamDefault{true} *
* \return a value of type `CGAL::Mesh_optimization_return_code` which is:
\cgalNamedParamsEnd * <UL>
\return * <LI>`CGAL::TIME_LIMIT_REACHED` when the time limit is reached.
The function `lloyd_optimize_mesh_3()` returns a value of type `CGAL::Mesh_optimization_return_code` * <LI>`CGAL::MAX_ITERATION_NUMBER_REACHED` when `lloyd_optimize_mesh_3()` stops because it has performed `max_iteration_number` iterations.
which is: * <LI>`CGAL::CONVERGENCE_REACHED` when `lloyd_optimize_mesh_3()` stops because the convergence criterion
<UL> * is achieved.
<LI>`CGAL::TIME_LIMIT_REACHED` when the time limit is reached. * <LI>`CGAL::ALL_VERTICES_FROZEN` when all vertices have been frozen, when the
<LI>`CGAL::MAX_ITERATION_NUMBER_REACHED` when `lloyd_optimize_mesh_3()` stops because it has performed `max_iteration_number` iterations. * `do_freeze` parameter is set to true.
<LI>`CGAL::CONVERGENCE_REACHED` when `lloyd_optimize_mesh_3()` stops because the convergence criterion * <LI>`CGAL::CANT_IMPROVE_ANYMORE` when `lloyd_optimize_mesh_3()` stops because
is achieved. * most vertices have been frozen, and no better convergence can be reached.
<LI>`CGAL::ALL_VERTICES_FROZEN` when all vertices have been frozen, when the * </UL>
`do_freeze` parameter is set to true. *
<LI>`CGAL::CANT_IMPROVE_ANYMORE` when `lloyd_optimize_mesh_3()` stops because * \cgalHeading{Example}
most vertices have been frozen, and no better convergence can be reached. *
</UL> *
* \code{.cpp}
\cgalHeading{Example} * // Lloyd-smoothing until convergence reaches 0.01, freezing vertices which
* // move less than 0.001*shortest_incident_edge_length
* lloyd_optimize_mesh_3(c3t3,
\code{.cpp} * domain,
// Lloyd-smoothing until convergence reaches 0.01, freezing vertices which * parameters::convergence=0.01,
// move less than 0.001*shortest_incident_edge_length * parameters::freeze_bound=0.001,
lloyd_optimize_mesh_3(c3t3, * parameters::do_freeze=true);
domain, *
parameters::convergence=0.01, * \endcode
parameters::freeze_bound=0.001, *
parameters::do_freeze=true); * \sa `CGAL::Mesh_optimization_return_code`
* \sa `CGAL::make_mesh_3()`
\endcode * \sa `CGAL::refine_mesh_3()`
* \sa `CGAL::exude_mesh_3()`
\sa `CGAL::Mesh_optimization_return_code` * \sa `CGAL::perturb_mesh_3()`
\sa `CGAL::make_mesh_3()` * \sa `CGAL::odt_optimize_mesh_3()`
\sa `CGAL::refine_mesh_3()` *
\sa `CGAL::exude_mesh_3()` * \note This function requires the \ref thirdpartyEigen library.
\sa `CGAL::perturb_mesh_3()` */
\sa `CGAL::odt_optimize_mesh_3()`
\note This function requires the \ref thirdpartyEigen library.
*/
template<typename C3T3, typename MeshDomain, typename CGAL_NP_TEMPLATE_PARAMETERS> template<typename C3T3, typename MeshDomain, typename CGAL_NP_TEMPLATE_PARAMETERS>
Mesh_optimization_return_code lloyd_optimize_mesh_3(C3T3& c3t3, MeshDomain& domain,const CGAL_NP_CLASS& np = parameters::default_values()) Mesh_optimization_return_code lloyd_optimize_mesh_3(C3T3& c3t3, MeshDomain& domain,const CGAL_NP_CLASS& np = parameters::default_values())
{ {