add documentation for lloyd_optimize_mesh_2

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`

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 */

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

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<class CDT> void make_conforming_Delaunay_2 (CDT &t);
 namespace CGAL {
 
 /*!
-\ingroup PkgMesh2
+\ingroup PkgMesh2Functions
 
 
 

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`,
-
+with vertex base and face base of its underlying  `TriangulationDataStructure_2` 
-\tparam CDT is required to be or derive from 
+respectively implementing the concepts `DelaunayMeshFaceBase_2` and `DelaunayMeshVertexBase_2`.
-`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. 
 
+\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
 - <b>`parameters::time_limit`</b>
 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
 
 - <b>`parameters::%max_iteration_number`</b> 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
 
 - <b>`parameters::%convergence`</b> 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
 
 - <b>`parameters::freeze_bound`</b> 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 
+
+- <b>`parameters::seeds_begin`</b> and <b>`parameters::seeds_end`</b>
+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.
+
+- <b>`parameters::mark`</b>. 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<typename CDT>
+template<typename CDT, typename PointIterator>
 Mesh_optimization_return_code
 lloyd_optimize_mesh_2(CDT& cdt,
-double parameters::time_limit=0,
+  double parameters::time_limit=0,
-std::size_t parameters::max_iteration_number=0,
+  std::size_t parameters::max_iteration_number=0,
-double parameters::convergence=0.02,
+  double parameters::convergence=0.001,
-double parameters::freeze_bound = 0.01,
+  double parameters::freeze_bound = 0.001,
-bool parameters::do_freeze=true);
+  PointIterator parameters::seeds_begin = InputIterator(),
+  PointIterator parameters::seeds_end = InputIterator(),
+  bool parameters::mark = false);
 
 } /* namespace CGAL */

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<Traits, Vb>` 
+
+
+*/
+
+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 */
+

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<class CDT> void make_conforming_Delaunay_2 (CDT& t)`\endlink and
+\code{.cpp}
-
+template<class CDT> 
-\link make_conforming_Gabriel_2() `template<class CDT> void make_conforming_Gabriel_2 (CDT& t)`\endlink.
+void make_conforming_Delaunay_2 (CDT& t)
+\endcode
+and
+\code{.cpp}
+template<class CDT> 
+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<class CDT, class Criteria> void refine_Delaunay_mesh_2 (CDT &t, const Criteria& criteria)`\endlink. 
+\code{.cpp}
+template<class CDT, class Criteria>
+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 */
 

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<CDT>`
 - `CGAL::Delaunay_mesher_2<CDT, Criteria>`
 - `CGAL::Delaunay_mesh_face_base_2<Traits, Fb>`
+- `CGAL::Delaunay_mesh_vertex_base_2<Traits, Vb>`
 - `CGAL::Delaunay_mesh_criteria_2<CDT>`
 - `CGAL::Delaunay_mesh_size_criteria_2<CDT>`
 - `CGAL::Mesh_2::Face_badness`