diff --git a/Mesh_2/doc/Mesh_2/CGAL/lloyd_optimize_mesh_2.h b/Mesh_2/doc/Mesh_2/CGAL/lloyd_optimize_mesh_2.h new file mode 100644 index 00000000000..63b75dad08d --- /dev/null +++ b/Mesh_2/doc/Mesh_2/CGAL/lloyd_optimize_mesh_2.h @@ -0,0 +1,99 @@ +namespace CGAL { + +/*! +\ingroup PkgMesh_2Functions + +The function `lloyd_optimize_mesh_2()` is a mesh optimization process +based on the minimization of a global energy function. + +In `lloyd_optimize_mesh_2()`, the minimized global energy may be interpreted +as the \f$ L^1\f$-norm of the error achieved +when the function \f$ x^2\f$ is interpolated on the mesh domain +using a piecewise linear function which is linear +in each cell of the Voronoi diagram of the mesh vertices. + +The optimizer `lloyd_optimize_mesh_2()` works in iterative steps. +At each iteration, mesh vertices are moved into +positions that bring to zero the energy gradient +and the Delaunay triangulation is updated. +Vertices on the mesh boundaries are not moved. + +\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 CDT is required to be or derive from +`CGAL::Constrained_Delaunay_triangulation_2`. +The argument `cdt`, passed by reference, provides the initial mesh +and is modified by the algorithm to represent the final optimized mesh. + +The function has several optional parameters which are named parameters +(we use the Boost.Parameter library). +Therefore, when calling the function, the parameters can be provided in any order +provided that the names of the parameters are used +(see example at the bottom of this page). + +\cgalHeading{Named Parameters} + +- `parameters::time_limit` +is used to set up, in seconds, +a CPU time limit after which the optimization process is stopped. This time is +measured using `Timer`. +The default value is 0 and means that there is no time limit. + +- `parameters::%max_iteration_number` sets a limit on the +number of performed iterations. The default value of 0 means that there is +no limit on the number of performed iterations. + +- `parameters::%convergence` is a stopping criterion based on convergence: +the optimization process is stopped, when at the last iteration, +the displacement of any vertex is less than a given fraction of the +length of the shortest edge incident to that vertex. +The parameter `convergence` gives the threshold ratio. + +- `parameters::freeze_bound` is designed to reduce running time of each +optimization iteration. Any vertex that has a displacement less than a given +fraction of the length of its shortest incident edge, is frozen (i.e.\ is +not relocated). The parameter `freeze_bound` gives the threshold ratio. +The default value is 0.001. If it is set to 0, freezing of vertices is disabled. + + +\return +The function `lloyd_optimize_mesh_2()` returns a value of type `CGAL::Mesh_optimization_return_code` +which is: + + +\cgalHeading{Example} + + +\code{.cpp} +// Lloyd-smoothing until convergence reaches 0.01, freezing vertices which +// move less than 0.001*shortest_incident_edge_length +lloyd_optimize_mesh_2(cdt, + parameters::convergence=0.01, + parameters::freeze_bound=0.001); + +\endcode + +\sa `CGAL::Mesh_optimization_return_code` +\sa `CGAL::refine_mesh_2()` + +*/ + +template +Mesh_optimization_return_code +lloyd_optimize_mesh_2(CDT& cdt, +double parameters::time_limit=0, +std::size_t parameters::max_iteration_number=0, +double parameters::convergence=0.02, +double parameters::freeze_bound = 0.01, +bool parameters::do_freeze=true); + +} /* namespace CGAL */ diff --git a/Mesh_2/examples/Mesh_2/mesh_optimization.cpp b/Mesh_2/examples/Mesh_2/mesh_optimization.cpp index 7dee4b16979..88d203791e7 100644 --- a/Mesh_2/examples/Mesh_2/mesh_optimization.cpp +++ b/Mesh_2/examples/Mesh_2/mesh_optimization.cpp @@ -23,6 +23,8 @@ typedef CGAL::Delaunay_mesher_2 Mesher; typedef CDT::Vertex_handle Vertex_handle; typedef CDT::Point Point; +using namespace parameters; + int main() { CDT cdt; diff --git a/Mesh_2/include/CGAL/lloyd_optimize_mesh_2.h b/Mesh_2/include/CGAL/lloyd_optimize_mesh_2.h index a94838a108c..2b96fe0c832 100644 --- a/Mesh_2/include/CGAL/lloyd_optimize_mesh_2.h +++ b/Mesh_2/include/CGAL/lloyd_optimize_mesh_2.h @@ -12,6 +12,8 @@ #include #include +namespace parameters +{ BOOST_PARAMETER_NAME( cdt ) BOOST_PARAMETER_NAME( (max_iteration_number, tag) max_iteration_number_ ) BOOST_PARAMETER_NAME( (convergence, tag) convergence_) @@ -20,6 +22,9 @@ BOOST_PARAMETER_NAME( (freeze_bound, tag) freeze_bound_) BOOST_PARAMETER_NAME( (seeds_begin, tag) seeds_begin_) BOOST_PARAMETER_NAME( (seeds_end, tag) seeds_end_) BOOST_PARAMETER_NAME( (mark, tag) mark_) +} + +using namespace parameters; namespace CGAL { diff --git a/Mesh_2/test/Mesh_2/test_lloyd.cpp b/Mesh_2/test/Mesh_2/test_lloyd.cpp index 3a883e59198..9251561b5c1 100644 --- a/Mesh_2/test/Mesh_2/test_lloyd.cpp +++ b/Mesh_2/test/Mesh_2/test_lloyd.cpp @@ -16,6 +16,8 @@ typedef CGAL::Exact_predicates_inexact_constructions_kernel Epick; +using namespace parameters; + template struct Lloyd_tester {