diff --git a/Mesh_2/doc/Mesh_2/CGAL/Delaunay_mesh_face_base_2.h b/Mesh_2/doc/Mesh_2/CGAL/Delaunay_mesh_face_base_2.h index e8a1145fc15..3fe813eecfe 100644 --- a/Mesh_2/doc/Mesh_2/CGAL/Delaunay_mesh_face_base_2.h +++ b/Mesh_2/doc/Mesh_2/CGAL/Delaunay_mesh_face_base_2.h @@ -19,7 +19,7 @@ specific application. be the same as the one used for the Delaunay mesh. \tparam Fb is the base class from which `Delaunay_mesh_face_base_2` -derives. It must be a model of the `TriangulationFaceBase_2` concept. +derives. It must be a model of the `ConstrainedTriangulationFaceBase_2` concept. \cgalModels `DelaunayMeshFaceBase_2` diff --git a/Mesh_2/doc/Mesh_2/CGAL/Delaunay_mesh_vertex_base_2.h b/Mesh_2/doc/Mesh_2/CGAL/Delaunay_mesh_vertex_base_2.h new file mode 100644 index 00000000000..02894cb4e84 --- /dev/null +++ b/Mesh_2/doc/Mesh_2/CGAL/Delaunay_mesh_vertex_base_2.h @@ -0,0 +1,30 @@ + +namespace CGAL { + +/*! +\ingroup PkgMesh2 + +The class `Delaunay_mesh_vertex_base_2` is a model for the concept +`DelaunayMeshVertexBase_2`. + +This class can be used directly or it can serve as a base to derive other +classes with some additional attributes tuned to a +specific application. + +\tparam Traits is the geometric traits class. It must +be the same as the one used for the Delaunay mesh. + +\tparam Vb is the base class from which `Delaunay_mesh_vertex_base_2` +derives. It must be a model of the `TriangulationVertexBase_2` concept. + +\cgalModels `DelaunayMeshVertexBase_2` + +*/ +template< typename Traits, typename Vb > +class Delaunay_mesh_vertex_base_2 : Vb { +public: + +/// @} + +}; /* end Delaunay_mesh_vertex_base_2 */ +} /* end namespace CGAL */ diff --git a/Mesh_2/doc/Mesh_2/CGAL/Delaunay_mesher_2.h b/Mesh_2/doc/Mesh_2/CGAL/Delaunay_mesher_2.h index 2cc5ad97f9f..3126b838045 100644 --- a/Mesh_2/doc/Mesh_2/CGAL/Delaunay_mesher_2.h +++ b/Mesh_2/doc/Mesh_2/CGAL/Delaunay_mesher_2.h @@ -38,7 +38,7 @@ components including at least one seed, or the union of the bounded connected components that do no contain any seed. Note that the unbounded component of the plane is never meshed. -\sa `lloyd_optimize_mesh_2()` +\sa `CGAL::lloyd_optimize_mesh_2` */ template< typename CDT, typename Criteria > @@ -257,7 +257,7 @@ bool step_by_step_refine_mesh(); }; /* end Delaunay_mesher_2 */ /*! -\ingroup PkgMesh2 +\ingroup PkgMesh2Functions Refines the default domain defined by a constrained Delaunay triangulation without seeds into a mesh satisfying the criteria @@ -279,7 +279,7 @@ void refine_Delaunay_mesh_2 (CDT &t, const Criteria& criteria = Criteria()); /*! -\ingroup PkgMesh2 +\ingroup PkgMesh2Functions Refines the default domain defined by a constrained Delaunay triangulation into a mesh diff --git a/Mesh_2/doc/Mesh_2/CGAL/Triangulation_conformer_2.h b/Mesh_2/doc/Mesh_2/CGAL/Triangulation_conformer_2.h index 356ef933c76..b0ff428a78e 100644 --- a/Mesh_2/doc/Mesh_2/CGAL/Triangulation_conformer_2.h +++ b/Mesh_2/doc/Mesh_2/CGAL/Triangulation_conformer_2.h @@ -1,7 +1,7 @@ namespace CGAL { /*! -\ingroup PkgMesh2 +\ingroup PkgMesh2Functions @@ -19,7 +19,7 @@ template void make_conforming_Delaunay_2 (CDT &t); namespace CGAL { /*! -\ingroup PkgMesh2 +\ingroup PkgMesh2Functions 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 index 63b75dad08d..3e3b837fce2 100644 --- a/Mesh_2/doc/Mesh_2/CGAL/lloyd_optimize_mesh_2.h +++ b/Mesh_2/doc/Mesh_2/CGAL/lloyd_optimize_mesh_2.h @@ -1,7 +1,7 @@ namespace CGAL { /*! -\ingroup PkgMesh_2Functions +\ingroup PkgMesh2Functions The function `lloyd_optimize_mesh_2()` is a mesh optimization process based on the minimization of a global energy function. @@ -18,13 +18,15 @@ 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`. +\tparam CDT is required to be or derive from `CGAL::Constrained_Delaunay_triangulation_2`, +with vertex base and face base of its underlying `TriangulationDataStructure_2` +respectively implementing the concepts `DelaunayMeshFaceBase_2` and `DelaunayMeshVertexBase_2`. The argument `cdt`, passed by reference, provides the initial mesh and is modified by the algorithm to represent the final optimized mesh. +\tparam PointIterator must be an iterator with value type `CGAL::Kernel::Point_2` + + 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 @@ -36,24 +38,41 @@ provided that the names of the parameters are used - `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`. +measured using `CGAL::Timer`. The default value is 0 and means that there is no time limit. +\pre `time_limit` \f$ \geq\f$ 0 - `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. +\pre `max_iteration_number`\f$ \geq\f$ 0 - `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. +\pre 0 \f$ \leq\f$ `convergence` \f$ \leq\f$ 1 - `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. +\pre 0 \f$ \leq\f$ `freeze_bound` \f$ \leq\f$ 1 + +- `parameters::seeds_begin` and `parameters::seeds_end` +are begin and end input iterators to iterate on seed points. +The sequence [`parameters::seeds_begin`, `parameters::seeds_end`) +defines the domain in which the mesh was generated, and should be optimized. + +- `parameters::mark`. If `mark` is set to true, the mesh domain +is the union of the bounded connected components including at least one seed. +If `mark` is false, the domain is the union of the bounded components including +no seed. Note that the unbounded component of the plane is never optimized. +The default value is false. + + \return @@ -83,17 +102,19 @@ lloyd_optimize_mesh_2(cdt, \endcode \sa `CGAL::Mesh_optimization_return_code` -\sa `CGAL::refine_mesh_2()` +\sa `CGAL::refine_Delaunay_mesh_2()` */ -template +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); + double parameters::time_limit=0, + std::size_t parameters::max_iteration_number=0, + double parameters::convergence=0.001, + double parameters::freeze_bound = 0.001, + PointIterator parameters::seeds_begin = InputIterator(), + PointIterator parameters::seeds_end = InputIterator(), + bool parameters::mark = false); } /* namespace CGAL */ diff --git a/Mesh_2/doc/Mesh_2/Concepts/DelaunayMeshVertexBase_2.h b/Mesh_2/doc/Mesh_2/Concepts/DelaunayMeshVertexBase_2.h new file mode 100644 index 00000000000..94006a273e6 --- /dev/null +++ b/Mesh_2/doc/Mesh_2/Concepts/DelaunayMeshVertexBase_2.h @@ -0,0 +1,40 @@ + + + +/*! +\ingroup PkgMesh2Concepts +\cgalConcept + + +The concept `DelaunayMeshVertexBase_2` refines the concept +`TriangulationVertexBase_2`. It adds two functions giving access +to a `double` marker, that is useful for the mesh optimizers to keep +the mesh density everywhere while modifying the mesh. + +\cgalRefines `TriangulationVertexBase_2` + +\cgalHasModel `CGAL::Delaunay_mesh_vertex_base_2` + + +*/ + +class DelaunayMeshVertexBase_2 { +public: + +/// \name Access Functions +/// @{ + +/*! +returns the size requested locally around the vertex +*/ +const double& sizing_info() const; + +/*! +sets the size requested locally around the vertex +*/ +void set_sizing_info(const double& s); + +/// @} + +}; /* end DelaunayMeshVertexBase_2 */ + diff --git a/Mesh_2/doc/Mesh_2/Mesh_2.txt b/Mesh_2/doc/Mesh_2/Mesh_2.txt index e71d5ce71c6..fde138a77dc 100644 --- a/Mesh_2/doc/Mesh_2/Mesh_2.txt +++ b/Mesh_2/doc/Mesh_2/Mesh_2.txt @@ -51,9 +51,16 @@ to be Delaunay or Gabriel edges. Constrained Delaunay triangulations can be refined into conforming triangulations by the two following global functions: -\link make_conforming_Delaunay_2() `template void make_conforming_Delaunay_2 (CDT& t)`\endlink and - -\link make_conforming_Gabriel_2() `template void make_conforming_Gabriel_2 (CDT& t)`\endlink. +\code{.cpp} +template +void make_conforming_Delaunay_2 (CDT& t) +\endcode +and +\code{.cpp} +template +void make_conforming_Gabriel_2 (CDT& t) +\endcode +. In both cases, the template parameter `CDT` must be instantiated by a constrained Delaunay triangulation class (see Chapter \ref @@ -193,9 +200,12 @@ angle bound greater than \f$ 20.7\f$ degrees, but there is no such guarantee. \subsection secMesh_2_building_meshes Building Meshes Meshes are obtained from -constrained Delaunay triangulations by calling the global function +constrained Delaunay triangulations by calling the global function : -\link refine_Delaunay_mesh_2() `template void refine_Delaunay_mesh_2 (CDT &t, const Criteria& criteria)`\endlink. +\code{.cpp} +template +void refine_Delaunay_mesh_2 (CDT &t, const Criteria& criteria) +\endcode The template parameter `CDT` must be instantiated by a constrained Delaunay triangulation class. In order to override the domain, @@ -234,6 +244,28 @@ Once the mesh is constructed, one can determine which faces of the triangulation are in the mesh domain using the `is_in_domain()` member function of the face type (see the concept `DelaunayMeshFaceBase_2`). + +\subsection secMesh_2_optimization Optimization of Meshes with Lloyd + +The package also provides a global function that runs Lloyd optimization iterations on the +mesh generated by Delaunay refinement. + +\code{.cpp} + +template< class CDT > +Mesh_optimization_return_code lloyd_optimize_mesh_2(CDT& cdt); + +\endcode +Note that this global function has more parameters (see details in reference pages) to tune the optimization process. + +This optimization process alternates relocating vertices to the center of mass +of their Voronoi cells, and updating the Delaunay connectivity of the triangulation. +The center of mass is computed with respect to a sizing function that was designed to +preserve the local density of points in the mesh generated by Delaunay refinement. + + +\section Mesh_2Examples Examples + \subsection Mesh_2ExampleUsingtheGlobalFunction Example Using the Global Function The following example inserts several segments into a constrained @@ -268,6 +300,21 @@ faces is used to count them. \cgalExample{Mesh_2/mesh_with_seeds.cpp} + +\subsection Mesh_2ExampleLloyd Example Using the Lloyd optimizer + +This example uses the global function `lloyd_optimize_mesh_2()`. +The mesh is generated using the function `refine_mesh()` of `CGAL::Delaunay_mesher_2`, +and is then optimized using `lloyd_optimize_mesh_2()`. The optimization will stop +after 10 (set by `max_iteration_number`) iterations of alternating vertex relocations +and Delaunay connectivity updates. More termination conditions can be used and are detailed +in the Reference Manual. + + +\cgalExample{Mesh_2/mesh_optimization.cpp} + + + */ } /* namespace CGAL */ diff --git a/Mesh_2/doc/Mesh_2/PackageDescription.txt b/Mesh_2/doc/Mesh_2/PackageDescription.txt index afc573a707e..79733d285b8 100644 --- a/Mesh_2/doc/Mesh_2/PackageDescription.txt +++ b/Mesh_2/doc/Mesh_2/PackageDescription.txt @@ -2,6 +2,15 @@ /// \defgroup PkgMesh2Concepts Concepts /// \ingroup PkgMesh2 + +/// \defgroup PkgMesh2Functions Mesh Generation Functions +/// \ingroup PkgMesh2 +/// The main function to generate a mesh is `refine_Delaunay_mesh_2()`. +/// The function `lloyd_optimize_mesh_2()` allows to optimize an existing mesh. + +/// \defgroup PkgMesh2Enum Enumerations +/// \ingroup PkgMesh2 + /*! \addtogroup PkgMesh2 \cgalPkgDescriptionBegin{2D Conforming Triangulations and Meshes,PkgMesh2Summary} @@ -32,11 +41,13 @@ The package can handle intersecting input constraints and set no restriction on - `DelaunayMeshTraits_2` - `MeshingCriteria_2` - `DelaunayMeshFaceBase_2` +- `DelaunayMeshVertexBase_2` ## Classes## - `CGAL::Triangulation_conformer_2` - `CGAL::Delaunay_mesher_2` - `CGAL::Delaunay_mesh_face_base_2` +- `CGAL::Delaunay_mesh_vertex_base_2` - `CGAL::Delaunay_mesh_criteria_2` - `CGAL::Delaunay_mesh_size_criteria_2` - `CGAL::Mesh_2::Face_badness`