benchmark on new Poisson_mesh_domain_3 (also with parallel make_mesh_3) work on documentation

Poisson_surface_reconstruction_3/doc/Poisson_surface_reconstruction_3/Poisson_surface_reconstruction_3.txt

@@ -13,7 +13,7 @@ This \cgal component implements a surface reconstruction method which
 takes as input point sets with oriented normals and computes an
 implicit function. We assume that the input points contain no outliers
 and little noise. The output surface mesh is generated by extracting
-an isosurface of this function with the \cgal Surface Mesh Generator
+an isosurface of this function with the \ref Chapter_3D_Mesh_Generation or \cgal Surface Mesh Generator
 \cgalCite{cgal:ry-gsddrm-06} or potentially with any other surface
 contouring algorithm.
 
@@ -120,10 +120,12 @@ The following example reads a point set, creates a Poisson implicit function and
 
 
 The computed implicit functions can be iso-contoured to reconstruct a
-surface by using the \cgal surface mesh generator
+surface by using the \ref Chapter_3D_Mesh_Generation or the \cgal surface mesh generator
 \cgalCite{cgal:ry-gsddrm-06} \cgalCite{cgal:bo-pgsms-05} :
 
-`make_surface_mesh()`
+`make_mesh_3()` for using parallel Mesh_3
+
+`make_surface_mesh()` of using the deprecated 3D Surface Mesh Generation
 
 The parameter `Tag` affects the behavior of `make_surface_mesh()`:
 - `Manifold_tag`: the output mesh is guaranteed to be a manifold surface without boundary.
@@ -132,7 +134,10 @@ The parameter `Tag` affects the behavior of `make_surface_mesh()`:
 
 \subsection Poisson_surface_reconstruction_3Output Output
 
-The surface reconstructed by `make_surface_mesh()` is required to be a
+The surface reconstructed by `make_mesh_3()` is required to be a model of the concept 
+`MeshComplex_3InTriangulation_3`, a data structure devised to represent a three dimensional complex embedded into a three dimensional triangulation. The surface facets can then be extracted into a face graph by `facets_in_complex_3_to_triangle_mesh()`.
+
+The surface reconstructed by `make_surface_mesh()` instead is required to be a
 model of the concept `SurfaceMeshComplex_2InTriangulation_3`, a data
 structure devised to represent a two dimensional complex embedded into
 a three dimensional triangulation.
@@ -339,15 +344,15 @@ Left: 5K points sampled on a mechanical piece with sharp features (creases, dart
 
 We provide some performance numbers for scanning data. We measure the Poisson implicit function computation time,
 the contouring time for a range of approximation distances, the memory occupancy as well as the influence of
-the point set simplification. The machine used is a PC running Windows 7 64 bits with an Intel CPU Core 2 Duo
+the point set simplification. The machine used is a PC running Windows 10 64 bits with an Intel CPU Core i7-11850H
-processor clocked at 2.81 GHz and with 8 GB of RAM. The software is compiled with Visual \CC 2010 (VC9) compiler
+processor with 8 cores and 32 GB of RAM. The software is compiled with Visual \CC 2022 compiler
 with the 03 option which maximizes speed.  All measurements were done using the \ref thirdpartyEigen "Eigen" library.
 
-
 \subsection SurfReconstPerfPIF Poisson Implicit Function
 
-The point set chosen for benchmarking the Poisson implicit function is the Bimba con Nastrino point set
+The point set chosen for benchmarking the Poisson implicit function is the Lucy statue point set from the 
-(1.6 million points) depicted by \cgalFigureRef{Poisson_surface_reconstruction_3-fig-contouring_bench}.
+<a href="https://graphics.stanford.edu/data/3Dscanrep/">The Stanford 3D Scanning Repository</a> 
+(originally 14 million points, here downscaled to 2.9 million points) depicted by \cgalFigureRef{Poisson_surface_reconstruction_3-fig-contouring_bench}.
 We measure the Poisson implicit function computation (i.e., the call to
 `Poisson_reconstruction_function::compute_implicit_function()` denoted by Poisson solve hereafter)
 for this point set as well as for simplified versions obtained through random simplification.
@@ -357,115 +362,213 @@ The following table provides Poisson solve computation times in seconds for an i
 <TR><TD ALIGN=LEFT NOWRAP COLSPAN=2><HR>
 <TR>
 <TD class="math" ALIGN=CENTER NOWRAP>
-
 Number of points (x1000)
 <TD class="math" ALIGN=CENTER NOWRAP>
 Poisson solve duration (in s)
 <TR><TD ALIGN=LEFT NOWRAP COLSPAN=2><HR>
 <TR>
 <TD class="math" ALIGN=CENTER NOWRAP>
+30
+<TD class="math" ALIGN=CENTER NOWRAP>
+3.3
+<TR>
+<TD class="math" ALIGN=CENTER NOWRAP>
 60
 <TD class="math" ALIGN=CENTER NOWRAP>
-15
+7.7
-<TR>
-<TD class="math" ALIGN=CENTER NOWRAP>
-100
-<TD class="math" ALIGN=CENTER NOWRAP>
-25
 <TR>
 
 <TD class="math" ALIGN=CENTER NOWRAP>
-250
+120
 <TD class="math" ALIGN=CENTER NOWRAP>
-96
+18.1
 <TR>
 <TD class="math" ALIGN=CENTER NOWRAP>
-500
+237.5
 <TD class="math" ALIGN=CENTER NOWRAP>
-150
+35.1
 <TR>
 <TD class="math" ALIGN=CENTER NOWRAP>
-1,000
+375
 <TD class="math" ALIGN=CENTER NOWRAP>
-249
+64
 <TR>
 
 <TD class="math" ALIGN=CENTER NOWRAP>
-1,800
+750
 <TD class="math" ALIGN=CENTER NOWRAP>
-478
+129
+<TR>
+<TD class="math" ALIGN=CENTER NOWRAP>
+1,500
+<TD class="math" ALIGN=CENTER NOWRAP>
+303
+<TR>
+<TD class="math" ALIGN=CENTER NOWRAP>
+2,900
+<TD class="math" ALIGN=CENTER NOWRAP>
+486
 <TR><TD ALIGN=LEFT NOWRAP COLSPAN=2><HR>
 </TABLE>
 
 
 \subsection SurfReconstPerfCont Contouring
 
-The point set chosen for benchmarking the contouring stage is the Bimba con Nastrino point
+The point set chosen for benchmarking the contouring stage is the Lucy point
-set simplified to 100k points. We measure the contouring (i.e.\ the call to `make_surface_mesh()`)
+set simplified to 2.9M points. We measure the contouring (i.e.\ the calls to `make_mesh_3()` and `facets_in_complex_3_to_triangle_mesh()`)
 duration and the reconstruction error for a range of approximation distances.
-The reconstruction error is expressed as the average distance from input points to the reconstructed surface
+The reconstruction error is expressed as the average distance from input points to the reconstructed surface in mm (the Lucy statue is 1597 mm tall).
-in mm (the Bimba con Nastrino statue is 324 mm tall).
 
 <TABLE CELLSPACING=5 >
-<TR><TD ALIGN=LEFT NOWRAP COLSPAN=3><HR>
+<TR><TD ALIGN=LEFT NOWRAP COLSPAN=4><HR>
 <TR>
 <TD class="math" ALIGN=CENTER NOWRAP>
 Approx. distance (*average spacing)
 <TD class="math" ALIGN=CENTER NOWRAP>
-Contouring duration (in s)
+Contouring duration single-thread (in s)
+<TD class="math" ALIGN=CENTER NOWRAP>
+Contouring duration parallel (in s)
 <TD class="math" ALIGN=CENTER NOWRAP>
 Reconstruction error (mm)
-<TR><TD ALIGN=LEFT NOWRAP COLSPAN=3><HR>
+<TR><TD ALIGN=LEFT NOWRAP COLSPAN=4><HR>
+<TR>
+
+<TD class="math" ALIGN=CENTER NOWRAP>
+0.05
+<TD class="math" ALIGN=CENTER NOWRAP>
+582
+<TD class="math" ALIGN=CENTER NOWRAP>
+112
+<TD class="math" ALIGN=CENTER NOWRAP>
+0.114
 <TR>
 
 <TD class="math" ALIGN=CENTER NOWRAP>
 0.1
 <TD class="math" ALIGN=CENTER NOWRAP>
-19.2
+221
 <TD class="math" ALIGN=CENTER NOWRAP>
-0.055
+26
+<TD class="math" ALIGN=CENTER NOWRAP>
+0.119
 <TR>
+
+<TD class="math" ALIGN=CENTER NOWRAP>
+0.15
+<TD class="math" ALIGN=CENTER NOWRAP>
+104
+<TD class="math" ALIGN=CENTER NOWRAP>
+25
+<TD class="math" ALIGN=CENTER NOWRAP>
+0.129
+<TR>
+
+<TD class="math" ALIGN=CENTER NOWRAP>
+0.2
+<TD class="math" ALIGN=CENTER NOWRAP>
+69.4
+<TD class="math" ALIGN=CENTER NOWRAP>
+9.2
+<TD class="math" ALIGN=CENTER NOWRAP>
+0.14
+<TR>
+
 <TD class="math" ALIGN=CENTER NOWRAP>
 0.25
 <TD class="math" ALIGN=CENTER NOWRAP>
-6.9
+53.6
 <TD class="math" ALIGN=CENTER NOWRAP>
-0.106
+7.0
+<TD class="math" ALIGN=CENTER NOWRAP>
+0.151
 <TR>
+
 <TD class="math" ALIGN=CENTER NOWRAP>
 0.5
 <TD class="math" ALIGN=CENTER NOWRAP>
-3.2
+25.2
 <TD class="math" ALIGN=CENTER NOWRAP>
-0.18
+3.6
+<TD class="math" ALIGN=CENTER NOWRAP>
+0.209
 <TR>
+
+<TD class="math" ALIGN=CENTER NOWRAP>
+0.75
+<TD class="math" ALIGN=CENTER NOWRAP>
+16.4
+<TD class="math" ALIGN=CENTER NOWRAP>
+4.9
+<TD class="math" ALIGN=CENTER NOWRAP>
+0.209
+<TR>
+
 <TD class="math" ALIGN=CENTER NOWRAP>
 1
 <TD class="math" ALIGN=CENTER NOWRAP>
-1.65
+12.4
 <TD class="math" ALIGN=CENTER NOWRAP>
-0.36
+2.3
+<TD class="math" ALIGN=CENTER NOWRAP>
+0.33
 <TR>
+
+<TD class="math" ALIGN=CENTER NOWRAP>
+1.5
+<TD class="math" ALIGN=CENTER NOWRAP>
+8.2
+<TD class="math" ALIGN=CENTER NOWRAP>
+1.4
+<TD class="math" ALIGN=CENTER NOWRAP>
+0.455
+<TR>
+
 <TD class="math" ALIGN=CENTER NOWRAP>
 2
 <TD class="math" ALIGN=CENTER NOWRAP>
+6.1
+<TD class="math" ALIGN=CENTER NOWRAP>
+1.1
+<TD class="math" ALIGN=CENTER NOWRAP>
+0.59
+<TR>
+
+<TD class="math" ALIGN=CENTER NOWRAP>
+3
+<TD class="math" ALIGN=CENTER NOWRAP>
+4.0
+<TD class="math" ALIGN=CENTER NOWRAP>
 0.8
 <TD class="math" ALIGN=CENTER NOWRAP>
-0.76
+0.87
-<TR><TD ALIGN=LEFT NOWRAP COLSPAN=3><HR>
+<TR>
+
+<TD class="math" ALIGN=CENTER NOWRAP>
+5
+<TD class="math" ALIGN=CENTER NOWRAP>
+2.3
+<TD class="math" ALIGN=CENTER NOWRAP>
+0.7
+<TD class="math" ALIGN=CENTER NOWRAP>
+1.50
+<TR>
+<TD ALIGN=LEFT NOWRAP COLSPAN=3><HR>
 </TABLE>
 
-
+\cgalFigureAnchor{Poisson_surface_reconstruction_3-fig-contouring_bench}
-\cgalFigureBegin{Poisson_surface_reconstruction_3-fig-contouring_bench,contouring_bench.jpg}
+<center>
+<img src="contouring_bench_4.jpg" style="max-width:80%;"/>
+</center>
+\cgalFigureCaptionBegin{Poisson_surface_reconstruction_3-fig-contouring_bench}
 Contouring duration (in s) and reconstruction error (mm)
 against several approximation distance parameters
-for the Bimba con Nastrino point set simplified to 100k points.
+for the Lucy point set simplified to 100k points.
-\cgalFigureEnd
+\cgalFigureCaptionEnd
 
 \subsection SurfReconstPerfMem Memory
 
-We measure the memory occupancy for the reconstruction of the full Bimba con Nastrino point
+We measure the memory occupancy for the reconstruction of the Lucy point
-set (1.8 millions points) as well as for simplified versions.\n
+set (2.9 millions points) as well as for further simplified versions.\n
 The Poisson implicit function computation has a memory peak when solving the Poisson linear
 system using the sparse linear solver.
 
@@ -479,34 +582,44 @@ Memory occupancy (MBytes)
 <TR><TD ALIGN=LEFT NOWRAP COLSPAN=2><HR>
 <TR>
 <TD class="math" ALIGN=CENTER NOWRAP>
+30
+<TD class="math" ALIGN=CENTER NOWRAP>
+128
+<TR>
+<TD class="math" ALIGN=CENTER NOWRAP>
 60
 <TD class="math" ALIGN=CENTER NOWRAP>
-180
+226
 <TR>
 <TD class="math" ALIGN=CENTER NOWRAP>
-100
+120
 <TD class="math" ALIGN=CENTER NOWRAP>
-270
+431
 <TR>
 <TD class="math" ALIGN=CENTER NOWRAP>
-250
+237.5
 <TD class="math" ALIGN=CENTER NOWRAP>
-790
+813
 <TR>
 <TD class="math" ALIGN=CENTER NOWRAP>
-500
+375
 <TD class="math" ALIGN=CENTER NOWRAP>
-1300
+1,232
 <TR>
 <TD class="math" ALIGN=CENTER NOWRAP>
-1,000
+750
 <TD class="math" ALIGN=CENTER NOWRAP>
-2200
+2,283
 <TR>
 <TD class="math" ALIGN=CENTER NOWRAP>
-1,800
+1,500
 <TD class="math" ALIGN=CENTER NOWRAP>
-3800
+4,042
+<TR>
+<TD class="math" ALIGN=CENTER NOWRAP>
+2,900
+<TD class="math" ALIGN=CENTER NOWRAP>
+6,868
 <TR><TD ALIGN=LEFT NOWRAP COLSPAN=2><HR>
 </TABLE>
 
@@ -514,11 +627,11 @@ Memory occupancy (MBytes)
 \subsection SurfReconstPerfPSS Point Set Simplification
 
 Due to the memory limitations described above, we recommend to simplify the point sets captured by laser scanners.\n
-We measure the reconstruction error for the Bimba con Nastrino point set (1.6M points) as well as for
+We measure the reconstruction error for the Lucy point set (2.9M points) as well as for
 simplified versions. All reconstructions use the recommended contouring parameter
 `approximation distance = 0.25 * the input point` set's average spacing.
 The reconstruction error is expressed as the average distance from input points to the reconstructed surface in mm
-(the Bimba con Nastrino statue is 324 mm tall).
+(the Lucy statue is 1597 mm tall).
 
 <TABLE CELLSPACING=5 >
 <TR><TD ALIGN=LEFT NOWRAP COLSPAN=2><HR>
@@ -530,46 +643,66 @@ Reconstruction error (mm)
 <TR><TD ALIGN=LEFT NOWRAP COLSPAN=2><HR>
 <TR>
 <TD class="math" ALIGN=CENTER NOWRAP>
+3.75
+<TD class="math" ALIGN=CENTER NOWRAP>
+9.88395
+<TR>
+<TD class="math" ALIGN=CENTER NOWRAP>
+7.5
+<TD class="math" ALIGN=CENTER NOWRAP>
+5.81843
+<TR>
+<TD class="math" ALIGN=CENTER NOWRAP>
+15
+<TD class="math" ALIGN=CENTER NOWRAP>
+3.13479
+<TR>
+<TD class="math" ALIGN=CENTER NOWRAP>
+30
+<TD class="math" ALIGN=CENTER NOWRAP>
+2.25391
+<TR>
+<TD class="math" ALIGN=CENTER NOWRAP>
 60
 <TD class="math" ALIGN=CENTER NOWRAP>
-0.27
+1.42965
 <TR>
 <TD class="math" ALIGN=CENTER NOWRAP>
 120
 <TD class="math" ALIGN=CENTER NOWRAP>
-0.15
+1.17589
 <TR>
 <TD class="math" ALIGN=CENTER NOWRAP>
-250
+237.5
 <TD class="math" ALIGN=CENTER NOWRAP>
-0.11
+0.99509
 <TR>
 <TD class="math" ALIGN=CENTER NOWRAP>
-500
+375
 <TD class="math" ALIGN=CENTER NOWRAP>
-0.079
+0.75215
 <TR>
 <TD class="math" ALIGN=CENTER NOWRAP>
-1,000
+750
 <TD class="math" ALIGN=CENTER NOWRAP>
-0.066
+0.344654
 <TR>
 <TD class="math" ALIGN=CENTER NOWRAP>
 1,500
 <TD class="math" ALIGN=CENTER NOWRAP>
-0.061
+0.225341
 <TR>
 <TD class="math" ALIGN=CENTER NOWRAP>
-1,600
+2,900
 <TD class="math" ALIGN=CENTER NOWRAP>
-0.06
+0.150947
 <TR><TD ALIGN=LEFT NOWRAP COLSPAN=2><HR>
 </TABLE>
 
 
-\cgalFigureBegin{Poisson_surface_reconstruction_3-fig-simplification_bench,simplification_bench.jpg}
+\cgalFigureBegin{Poisson_surface_reconstruction_3-fig-simplification_bench,simplification_bench_2.jpg}
 Reconstruction error (mm) against number of points
-for the Bimba con Nastrino point set with 1.6M points
+for the Lucy point set with 2.9M points
 as well as for simplified versions.
 \cgalFigureEnd
 

Poisson_surface_reconstruction_3/doc/Poisson_surface_reconstruction_3/dependencies

@@ -1,8 +1,11 @@
 Manual
 Kernel_23
+BGL
 STL_Extension
+Mesh_3
 Algebraic_foundations
 Circulator
 Stream_support
 Point_set_processing_3
 Solver_interface
+SMDS_3

Poisson_surface_reconstruction_3/include/CGAL/Poisson_mesh_domain_3.h

@@ -18,7 +18,7 @@
 #ifndef CGAL_POISSON_MESH_DOMAIN_3_H
 #define CGAL_POISSON_MESH_DOMAIN_3_H
 
-#include <CGAL/license/Mesh_3.h>
+#include <CGAL/license/Poisson_surface_reconstruction_3.h>
 
 #include <CGAL/Labeled_mesh_domain_3.h>
 #include <CGAL/Poisson_reconstruction_function.h>
@@ -26,13 +26,13 @@
 namespace CGAL {
 
 /*!
-\ingroup PkgMesh3Domains
+\ingroup PkgPoissonSurfaceReconstruction3Ref
 
 \brief The class `Poisson_mesh_domain_3` derives from `Labeled_mesh_domain_3` for the handling of `Poisson_reconstruction_function`.
 
  This class has a constructor taking a labeling function. It has also a static template member
  function that acts as named constructor:
- <ul><li>`create_Poisson_mesh_domain()`, to create a domain from a `Poisson_reconstruction_function`</ ul>
+ <ul><li>`create_Poisson_mesh_domain()`</li>, to create a domain from a `Poisson_reconstruction_function`</ul>
 
 \tparam BGT is a geometric traits class that provides
     the basic operations to implement intersection tests and intersection computations through a bisection
@@ -117,9 +117,10 @@ public:
 /// @{
   /*!  \brief Construction from a function, a bounding object and a relative error bound.
    *
-   * \tparam NamedParameters a sequence of \ref bgl_namedparameters "Named Parameters"
    * \tparam Bounding_object either a bounding sphere (of type `Sphere_3`), a bounding box (type `Bbox_3`),
    *                         or a bounding `Iso_cuboid_3`
+   * \tparam NamedParameters
+   *  a sequence of \ref bgl_namedparameters "Named Parameters"
    *
    * \param function the Poisson reconstruction function
    * \param bounding_object the bounding object bounding the meshable space.
@@ -145,6 +146,33 @@ public:
     : Base(make_implicit_to_labeling_function_wrapper<BGT>(function), bounding_object, np),
     poisson_function(function)
   {}
+
+  /*!  \brief Construction from a function, a bounding object and a relative error bound.
+   *
+   * \tparam NamedParameters a sequence of \ref bgl_namedparameters "Named Parameters"
+   *
+   * \param function the Poisson reconstruction function
+   * \param np an optional sequence of \ref bgl_namedparameters "Named Parameters" among the ones listed below:
+   *
+   * \cgalNamedParamsBegin
+   *   \cgalParamNBegin{relative_error_bound}
+   *      \cgalParamDescription{the relative error bound used to compute intersection points between the implicit surface and query segments.
+   *                            The bisection is stopped when the length of the intersected segment is less than the product
+   *                            of `relative_error_bound` by the diameter of the bounding object.}
+   *      \cgalParamDefault{FT(1e-3)}
+   *   \cgalParamNEnd
+   * \cgalNamedParamsEnd
+   */
+  template<typename CGAL_NP_TEMPLATE_PARAMETERS>
+  Poisson_mesh_domain_3(const Function & function,
+    const CGAL_NP_CLASS& np = parameters::default_values()
+#ifndef DOXYGEN_RUNNING
+    , typename std::enable_if<!is_named_function_parameter<Function>>::type * = nullptr
+#endif // DOXYGEN_RUNNING
+  )
+    : Base(make_implicit_to_labeling_function_wrapper<BGT>(function), function.bounding_sphere(), np),
+    poisson_function(function)
+  {}
 ///@}
 
 #ifndef DOXYGEN_RUNNING
@@ -185,7 +213,7 @@ public:
    *                         or a bounding `Iso_cuboid_3`
    *
    * \param function the Poisson reconstruction function
-   * \param bounding_object object boundint the meshable domain and its center is inside the domain.
+   * \param bounding_object object bounding the meshable domain and its center is inside the domain.
    * \param np an optional sequence of \ref bgl_namedparameters "Named Parameters" among the ones listed below:
    *
    * \cgalNamedParamsBegin

Poisson_surface_reconstruction_3/include/CGAL/Poisson_reconstruction_function.h

@@ -460,7 +460,7 @@ public:
       // Add a pass of Delaunay refinement.
       //
       // In that pass, the sizing field, of the refinement process of the
-      // triangulation, is based on the result of a poisson function with a
+      // triangulation, is based on the result of a Poisson function with a
       // sample of the input points. The ratio is 'approximation_ratio'.
       //
       // For optimization reasons, the cell criteria of the refinement

Poisson_surface_reconstruction_3/test/Poisson_surface_reconstruction_3/CMakeLists.txt

@@ -5,6 +5,8 @@ project(Poisson_surface_reconstruction_3_Tests)
 
 # Find CGAL
 find_package(CGAL REQUIRED)
+find_package(TBB REQUIRED)
+include(CGAL_TBB_support)
 
 # VisualC++ optimization for applications dealing with large data
 if(MSVC)
@@ -23,13 +25,13 @@ include(CGAL_Eigen3_support)
 if(TARGET CGAL::Eigen3_support)
   # Executables that require Eigen 3.1
   create_single_source_cgal_program("poisson_reconstruction_test_surface_mesher.cpp")
-  target_link_libraries(poisson_reconstruction_test_surface_mesher PRIVATE CGAL::Eigen3_support)
+  target_link_libraries(poisson_reconstruction_test_surface_mesher PRIVATE CGAL::Eigen3_support CGAL::TBB_support)
 
   create_single_source_cgal_program("poisson_reconstruction_test_mesh_3.cpp")
-  target_link_libraries(poisson_reconstruction_test_mesh_3 PRIVATE CGAL::Eigen3_support)
+  target_link_libraries(poisson_reconstruction_test_mesh_3 PRIVATE CGAL::Eigen3_support CGAL::TBB_support)
 
   create_single_source_cgal_program("compare_mesh_3_vs_Poisson_implicit_surface_3.cpp")
-  target_link_libraries(compare_mesh_3_vs_Poisson_implicit_surface_3  PRIVATE CGAL::Eigen3_support)
+  target_link_libraries(compare_mesh_3_vs_Poisson_implicit_surface_3  PRIVATE CGAL::Eigen3_support CGAL::TBB_support)
 
 else()
   message("NOTICE: Tests in this directory require Eigen 3.1 (or greater), and will not be compiled.")