User manual improvements

Isosurfacing_3/doc/Isosurfacing_3/Doxyfile.in

@@ -7,5 +7,8 @@ HTML_EXTRA_FILES           =  ${CGAL_PACKAGE_DOC_DIR}/fig/isosurfacing_teaser.pn
                               ${CGAL_PACKAGE_DOC_DIR}/fig/MC_DC.png \
                               ${CGAL_PACKAGE_DOC_DIR}/fig/MC_DC_open.png \
                               ${CGAL_PACKAGE_DOC_DIR}/fig/DC.png \
+                              ${CGAL_PACKAGE_DOC_DIR}/fig/MC.png \
                               ${CGAL_PACKAGE_DOC_DIR}/fig/isosurfacing_inrimage.png \
+                              ${CGAL_PACKAGE_DOC_DIR}/fig/MC_TMC.png \
+                              ${CGAL_PACKAGE_DOC_DIR}/fig/MC_octree.png \
                               ${CGAL_PACKAGE_DOC_DIR}/fig/MC_DC_performance.png

Isosurfacing_3/doc/Isosurfacing_3/Isosurfacing_3.txt

@@ -57,7 +57,7 @@ All cells of the grid are processed individually using values of the value field
 Each cell corner is assigned a sign (+/-) to indicate whether its value field value is above
 or below the user-defined isovalue.
 A vertex is created along each grid edge where a sign change occurs, i.e., where the edge intersects the isosurface.
-More specifically, the vertex location is computed via linear interpolation of
+More specifically, the vertex location is computed using linear interpolation of
 the value field values evaluated at the cell corners forming the edge.
 These vertices are connected to form triangles within the cell, depending on the configuration
 of signs at the cell corners. \cgalFigureRef{IsosurfacingMCCases} illustrates the configurations in 2D.
@@ -84,7 +84,7 @@ that are not captured by the sampling of the value field.
 
 Compared to other meshing approaches such as Delaunay refinement, Marching Cubes is substantially faster,
 but often tends to generate more triangle facets for an equivalent desired sizing field.
-In addition, the quality of the triangle facets is in general poor, with many needle/cap shaped triangles.
+In addition, the quality of the triangle facets is in general poor, with many needle or cap-shaped triangles.
 
 Furthermore, Marching Cubes does not preserve the sharp features present in the isovalue of the input value field (see \cgalFigureRef{IsosurfacingMCDC}).
 
@@ -131,8 +131,8 @@ Comparison between a mesh of a CSG shape generated by Marching Cubes (left) and
 
 In addition to the 3D value field, %Dual Contouring requires knowledge about the gradient of the value field.
 
-The \cgal implementation uses a vertex positioning strategy based on *Quadric Error Metrics*: for
-a cell, the vertex location is computed by minimizing the error to the sum of the quadrics
+The \cgal implementation uses a vertex positioning strategy based on *Quadric Error Metrics* \cgalCite{gh-ssqem-97} :
+for a cell, the vertex location is computed by minimizing the error to the sum of the quadrics
 defined at each edge-isosurface intersection.
 Using this approach, the vertex may be located outside the cell, which is a desirable property
 to improve the odds of recovering sharp features, but it might also create self-intersections.
@@ -140,7 +140,7 @@ Users can choose to constrain the vertex location inside the cell.
 
 By default, %Dual Contouring generates quads, but using edge-isosurface intersections,
 one can "star" these quads to generate four triangles. Triangulating the quads is the default behavior in \cgal,
-but this can be changed via named parameters.
+but this can be changed using a named parameter.
 
 \subsection SubSecIsosurfacingComparison Comparisons
 
@@ -149,7 +149,7 @@ over the input 3D domain, the facets of the output surface mesh, and the propert
 of the output surface mesh.
 
 <center>
-|  Algorithm        | Facets      | 2-Manifold | Watertight*   | Topologically correct | Recovery of Sharp Features |
+|  Algorithm        | Facets      | 2-Manifold | Watertight*   | Topologically Correct | Recovery of Sharp Features |
 | ----              | ----        | ----       | ----          | ----                  | ----                       |
   MC                | Triangles   | no         | no            | no                    | no                         |
   TMC               | Triangles   | yes        | yes           | yes                   | no                         |
@@ -175,7 +175,7 @@ Output meshes can have boundaries when the isosurface intersects the domain boun
 
 \section SecInterface Interface
 
-The following functions are the main entry points to the isosurfacing algorithms:
+The following functions are the main entry points to the isosurfacing algorithms of this package:
 <ul>
  <li>Marching Cubes</li>: `CGAL::Isosurfacing::marching_cubes()`, using the named parameter: `use_topologically_correct_marching_cubes` set to `false`;
  <li>Topologically Correct Marching Cubes</li>: `CGAL::Isosurfacing::marching_cubes()`, using the named parameter: `use_topologically_correct_marching_cubes` set to `true`;
@@ -203,10 +203,10 @@ The `isovalue` scalar parameter is the value that defines the isosurface being a
 
 The output discrete surface is provided in the form of a polygon soup, which is stored into
 two containers: `points` and `polygons`. Depending on the algorithm, the polygon soup may
-store either unorganized polygons with no relationship to one another (ie, no connectivity is shared between them)
+store either unorganized polygons with no relationship to one another (i.e., no connectivity is shared between them)
 or polygons sharing points (the same point in adjacent polygons will be the same point in the point range).
 
-The isosurfacing algorithms can run either sequentially in one thread or in parallel via multithreading.
+All isosurfacing algorithms can run either sequentially in one thread or in parallel using multithreading.
 The template parameter `ConcurrencyTag` is used to specify how the algorithm is executed.
 To enable parallelism, \cgal must be linked with the <a href="https://github.com/oneapi-src/oneTBB">Intel TBB library</a> (see the CMakeLists.txt file in the examples folder).
 
@@ -342,11 +342,22 @@ negative inside the mesh.
 
 The following example shows the use of an octree as discretization instead of a %Cartesian grid
 for both %Dual Contouring and Marching Cubes. Note that in this configuration, all methods
-lose guarantees, and cracks can easily appear in the surface if the octree's surface is not
-correctly constructed.
+lose guarantees, and cracks can easily appear in the surface if the octree is not adapted
+to the surface being extracted.
 
 \cgalExample{Isosurfacing_3/contouring_octree.cpp}
 
+\cgalFigureAnchor{IsosurfacingMCOctree}
+<center>
+<img src="MC_octree.png" style="max-width:70%;"/>
+</center>
+\cgalFigureCaptionBegin{IsosurfacingMCOctree}
+Running Marching Cubes with an octree: left, the octree (blue wireframe) has been applied arbitrary
+refinement in one eighth of the domain and the resulting mesh exhibits cracks (boundaries) at
+the regions where octree levels are discontinuous. Right, the octree was constructed to be dense
+around the isosurface, and the surface is manifold.
+\cgalFigureCaptionEnd
+
 \section SecIsosurfacingHistory Design and Implementation History
 
 The development of this package started during the 2022 Google Summer of Code, with the contribution