Doc add example +

Fix for initialize_triangulation_from_gray_image

Mesh_3/doc/Mesh_3/Mesh_3.txt

@@ -759,10 +759,10 @@ that call is replaced by:
 \snippet Mesh_3/mesh_3D_image_with_custom_initialization.cpp Meshing
 
 The code of the function `initialize_triangulation_from_labeled_image()` is
-in the non-documented header \ref
-CGAL/Mesh_3/initialize_triangulation_from_labeled_image.h. As it is
-undocumented and may be removed or modified at any time, if you wish to
-use it then you should copy-paste it to your user code. The code of that
+in the header \ref
+CGAL/Mesh_3/initialize_triangulation_from_labeled_image.h. It get points from
+\ref CGAL/Mesh_3/Construct_initial_points_labeled_image.h and insert them
+in the triangulation. The code of the Construct_initial_points_labeled_image
 function is rather complicated. The following lines show how to insert new
 points in the `%c3t3` object, with the calls to
 `MeshVertexBase_3::set_dimension()` and
@@ -830,11 +830,16 @@ the segmented image example above, the code consists in:
 \snippet Mesh_3/mesh_3D_gray_image_with_custom_initialization.cpp Meshing
 
 The code of the function `initialize_triangulation_from_gray_image()` is
-in the non-documented header \ref
-CGAL/Mesh_3/initialize_triangulation_from_gray_image.h. As it is
-undocumented and may be removed or modified at any time, if you wish to
-use it then you should copy-paste it to your user code.
+in the header \ref
+CGAL/Mesh_3/initialize_triangulation_from_gray_image.h.
 
+The example \ref Mesh_3/mesh_3D_image_with_initial_points.cpp is another
+way to achieve the same results. Instead of a custom initialization,
+it uses the parameter `CGAL::parameters::initial_points_generator` for the function
+`CGAL::make_mesh_3`. This parameter expect a functor that ouputs points for
+the mesh initialization (concept `InitialPointsGenerator`).
+
+\snippet Mesh_3/mesh_3D_image_with_initial_points.cpp Meshing
 
 \subsection Mesh_3UsingVariableSizingField Using Variable Sizing Field
 

Mesh_3/doc/Mesh_3/examples.txt

@@ -4,6 +4,7 @@
 \example Mesh_3/mesh_3D_gray_image_with_custom_initialization.cpp
 \example Mesh_3/mesh_3D_image_with_features.cpp
 \example Mesh_3/mesh_3D_image_with_custom_initialization.cpp
+\example Mesh_3/mesh_3D_image_with_initial_points.cpp
 \example Mesh_3/mesh_3D_image_with_detection_of_features.cpp
 \example Mesh_3/mesh_3D_image_with_input_features.cpp
 \example Mesh_3/mesh_3D_weighted_image.cpp

Mesh_3/examples/Mesh_3/mesh_3D_image_with_initial_points.cpp

@@ -47,6 +47,7 @@ int main()
                          .cell_radius_edge_ratio(3).cell_size(3)
   );
 
+  /// [Meshing]
   C3t3 c3t3 = CGAL::make_mesh_3<C3t3>(domain, criteria
     , params::initial_points_generator(CGAL::Construct_initial_points_labeled_image(image))
   );

Mesh_3/include/CGAL/Mesh_3/Construct_initial_points_labeled_image.h

@@ -89,7 +89,7 @@ struct Construct_initial_points_labeled_image
       : image(image_)
   { }
 
-  /*!
+    /*!
    * \brief operator () The points are constructed using the API of the mesh domain, as follows.
    * First the functor `construct_intersect` is created
    *
@@ -107,6 +107,13 @@ struct Construct_initial_points_labeled_image
    */
   template <typename OutputIterator, typename MeshDomain, typename C3t3>
   OutputIterator operator()(OutputIterator pts, const MeshDomain& domain, const C3t3& c3t3, int n = 20) const
+  {
+    CGAL_IMAGE_IO_CASE(image.image(), operator()(pts, domain, CGAL::Identity<Word>(), c3t3, n));
+    return pts;
+  }
+
+  template <typename OutputIterator, typename MeshDomain, typename C3t3, typename TransformOperator>
+  OutputIterator operator()(OutputIterator pts, const MeshDomain& domain, TransformOperator transform, const C3t3& c3t3, int n = 20) const
   {
     typedef typename MeshDomain::Subdomain     Subdomain;
     typedef typename MeshDomain::Point_3       Point_3;
@@ -146,7 +153,7 @@ struct Construct_initial_points_labeled_image
     CGAL_IMAGE_IO_CASE(image.image(), search_for_connected_components_in_labeled_image(image,
                                                      std::back_inserter(seeds),
                                                      CGAL::Emptyset_iterator(),
-                                                     CGAL::Identity<Word>(),
+                                                     transform,
                                                      Word()));
     std::cout << "  " << seeds.size() << " components were found." << std::endl;
     std::cout << "Construct initial points..." << std::endl;

Mesh_3/include/CGAL/Mesh_3/initialize_triangulation_from_gray_image.h

@@ -20,6 +20,16 @@
 
 #include <CGAL/tags.h>
 
+/**
+ * @brief initialize_triangulation_from_gray_image Initialize a c3t3 by detecting all connected components in the 3D gray image segmented around isovalue
+ * @param c3t3 The c3t3 to initialize (output)
+ * @param domain The domain, see concept `MeshDomain_3`
+ * @param image The gray image
+ * @param criteria The initial meshing criteria
+ * @param iso_value The surface's value
+ * @param image_values_to_subdomain_indices An optional functor used to segment the gray image (default is using isovalue).
+ * @param protect_features Whether protect_features is called or not (default is false)
+ */
 template<class C3T3, class MeshDomain, class MeshCriteria,
          typename FT,
          typename Image_word_type,

Mesh_3/include/CGAL/Mesh_3/initialize_triangulation_from_labeled_image.h

@@ -38,6 +38,15 @@ void init_tr_from_labeled_image_call_init_features(C3T3& c3t3,
             << " initial points on 1D-features" << std::endl;
 }
 
+/**
+ * @brief initialize_triangulation_from_labeled_image Initialize a c3t3 by detecting all connected components in the 3D segmented image
+ * @param c3t3 The c3t3 to initialize (output)
+ * @param domain The domain, see concept `MeshDomain_3`
+ * @param image The segmented image
+ * @param criteria The initial meshing criteria
+ * @param protect_features Whether protect_features is called or not (default is false)
+ * @param transform An optional functor used to transform the image's value (default is no transformation).
+ */
 template<class C3T3, class MeshDomain, class MeshCriteria,
          typename Image_word_type,
          typename TransformOperator = CGAL::Identity<Image_word_type> >
@@ -74,7 +83,7 @@ void initialize_triangulation_from_labeled_image(C3T3& c3t3,
   std::vector<ConstructedPoint> constructedPoints;
 
   CGAL::Construct_initial_points_labeled_image construct(image);
-  construct(std::back_inserter(constructedPoints), domain, c3t3);
+  construct(std::back_inserter(constructedPoints), domain, transform, c3t3);
 
   std::cout << "  " << constructedPoints.size() << " constructed points" << std::endl;