Misc doc fixes

Isosurfacing_3/doc/Isosurfacing_3/Isosurfacing_3.txt

@@ -70,23 +70,20 @@ Examples of some configurations for 2D Marching Cubes.
 \cgalFigureCaptionEnd
 
 The implementation within \cgal is generic in the sense that it can process any grid-like data structure
-that consists of hexahedral cells.
+that consists of hexahedral cells. When the hexahedral grid is a conforming grid (meaning that the
-In case of a conforming grid, the Marching Cubes algorithm generates
+intersection of two hexahedral cells is a face, and edge, or a vertex), the Marching Cubes algorithm
-as output a surface triangle mesh that is 2-manifold in most scenarios.
+generates as output a surface triangle mesh that is almost always combinatorially 2-manifold,
-
+but can also produce cracks in the surface.
-@todo PA: reformulate, as it is either strict or not - precise in which cases it is not, and say
-whether you talk about just combinatorially 2-manifold, or truly 2-manifold with 3D embedding taken into account
 
 If the mesh is 2-manifold and the isosurface does not intersect the domain boundary, then the output mesh is watertight.
 As the Marching Cubes algorithm uses linear interpolation of the sampled scalar field along the grid edges,
 it can miss details or components that are not captured by the sampling of the scalar field.
 
-Compared to other approaches such as Delaunay refinement, and depending on the parameters,
+Compared to other meshing approaches such as Delaunay refinement, Marching Cubes is much faster,
-MC often generates more triangles, and more skinny triangles with small or large angles.
+but often tends to generate more triangles for an equivalent desired sizing field. In addition,
-@todo PA: The statement is too strong - I would largely reformulate it as this depends too much on the parameters. I recommend to add instead a figure with different parameters and methods,
+the quality of the elements if generally poor, with many needles / caps shaped faces.
-depicting the mesh edges in black in addition to the shaded facets.
 
-Furthermore, MC does not preserve the sharp features present in the isovalue of the input scalar field
+Furthermore, Marching Cubes does not preserve the sharp features present in the isovalue of the input scalar field
 (see \cgalFigureRef{IsosurfacingMCDC}).
 
 \subsection SubSecTMC Topologically Correct Marching Cubes (TMC)
@@ -128,7 +125,7 @@ Comparison between a mesh of a CSG shape generated by Marching Cubes (left) and
 
 In addition to the scalar field, %Dual Contouring requires knowledge of the gradient of said scalar field.
 
-The \cgal implementation uses a point positioning strategy based on Quadric Error Metrics: for
+The \cgal implementation uses a point positioning strategy based on *Quadric Error Metrics*: for
 a cell, the position of the vertex is computed by minimizing the error to the sum of the quadrics
 defined at each edge-isosurface intersection.
 Using this strategy, the position can in fact lie outside the cell, which is a desirable property
@@ -150,11 +147,10 @@ of the output surface mesh.
 | ----              | ----        | ----       | ----          | ----                  | ----                       |
   MC                | Triangles   | no         | no            | no                    | no                         |
   TMC               | Triangles   | yes        | yes           | yes                   | no                         |
-  DC                | Polygons    | no         | no            | no                    | yes**                      |
+  DC                | Polygons    | no         | no            | no                    | yes (not guaranteed)       |
 </center>
 
-(* assuming the isosurface does not exit the specified bounding box of the input 3D domain)<br>
+(* assuming the isosurface does not exit the specified bounding box of the input 3D domain)
-(** not guaranteed)
 
 Note that the output mesh has boundaries when the isosurface intersects the domain boundaries,
 regardless of the method (see \cgalFigureRef{IsosurfacingOpen}).
@@ -208,26 +204,26 @@ To enable parallelism, \cgal must be linked with the <a href="https://github.com
 \subsection SubSecIsosurfacingDomains Domains
 
 A domain is an object that provides functions to access the partition of the 3D volume,
-the scalar field, and - optionally - the gradient field at a given position.
+the scalar field, and, optionally, the gradient field at a given position.
 These requirements are described through two concepts: `IsosurfacingDomain_3` and `IsosurfacingDomainWithGradient_3`.
 
 Two domains, `CGAL::Isosurfacing::Marching_cubes_domain_3` and `CGAL::Isosurfacing::Dual_contouring_domain_3`,
 are provided as the respective default class models that fulfill the requirements of the concepts.
-Both these domain models are equipped with template parameters enabling the user to customize the domain:
+Both these domain models have template parameters enabling the user to customize the domain:
 - <b>Partition:</b> this must be a class that describes the partition of the 3D volume into cells.
                     The most basic example of such class is `CGAL::Isosurfacing::Cartesian_grid_3`, but users
-                    can provide their own partition, provided it meets the requirements described
+                    can pass their own partition, provided it meets the requirements described
                     by the concept `IsosurfacingPartition_3`.
 - <b>ValueField:</b> this must be a class that provides the scalar field at the vertices of the partition.
-                      A few classes are provided by default, such as `CGAL::Isosurfacing::Value_function_3` and
+                     A few classes are provided, such as `CGAL::Isosurfacing::Value_function_3` and
-                      `CGAL::Isosurfacing::Interpolated_discrete_values_3`. Users can provide their own value class,
+                     `CGAL::Isosurfacing::Interpolated_discrete_values_3`. Users can pass their own value class,
                      provided it meets the requirements described by the concept `IsosurfacingValueField_3`.
 - <b>GradientField:</b> (`CGAL::Isosurfacing::Dual_contouring_domain_3` only) this must be a class that provides the gradient
                                                                               of the scalar field at the vertices of the partition.
                                                                               A few classes are provided by default, such as
                                                                               `CGAL::Isosurfacing::Finite_difference_gradient_3` and
                                                                               `CGAL::Isosurfacing::Interpolated_discrete_gradients_3`.
-                                                          Users can provide their own gradient class,
+                                                                              Users can pass their own gradient class,
                                                                               provided it meets the requirements described
                                                                               by the concept `IsosurfacingGradientField_3`.
 - <b>EdgeIntersectionOracle:</b> this must be a class that provides a function to compute the intersection
@@ -235,8 +231,8 @@ Both these domain models are equipped with template parameters enabling the user
                                  for `CGAL::Isosurfacing::Marching_cubes_domain_3`, and a dichotomy
                                  for `CGAL::Isosurfacing::Dual_contouring_domain_3`. This parameter should
                                  be adjusted depending on how your value field is defined: there is for
-                                 example no point doing a dichotomy in DC if the value field is defined
+                                 example no point doing a dichotomy in Dual Contouring if the value field is defined
-                                 through linear interpolation. Users can provide their own edge intersection
+                                 through linear interpolation. Users can pass their own edge intersection
                                  oracle, provided it meets the requirements described by the concept
                                  `IsosurfacingEdgeIntersectionOracle_3`.
 

Isosurfacing_3/doc/Isosurfacing_3/PackageDescription.txt

@@ -4,18 +4,28 @@
 
 /// \defgroup IS_Partitions_grp Space Partitioning Data Structures
 /// \ingroup PkgIsosurfacing3Ref
+///
+/// This group encapsulates classes that represent a spatial discretization of space,
+/// which will be the scaffolding for the construction of the isosurface.
 
 /// \defgroup IS_Partitions_helpers_grp Space Partitioning Data Structures Helpers
 /// \ingroup IS_Partitions_grp
 
 /// \defgroup IS_Fields_helpers_grp Value and Gradient Fields Helpers
 /// \ingroup PkgIsosurfacing3Ref
+///
+/// The following classes and functions are parameters or template parameters of value and gradient fields.
 
 /// \defgroup IS_Fields_grp Value and Gradient Fields
 /// \ingroup PkgIsosurfacing3Ref
+///
+/// The following classes represent the data that defines the isosurface.
 
 /// \defgroup IS_Domains_grp Isosurfacing Domains
 /// \ingroup PkgIsosurfacing3Ref
+///
+/// This group encapsulates the classes that can be used to represent a complete domain (partition
+/// and fields), to be used by the isosurfacing methods of this package.
 
 /// \defgroup IS_Domain_helpers_grp Isosurfacing Domain Helpers
 /// \ingroup IS_Domains_grp
@@ -32,24 +42,21 @@
 \cgalPkgPicture{isosurfacing3_ico.png}
 \cgalPkgSummaryBegin
 \cgalPkgAuthor{Mael Rouxel-Labbé, Julian Stahl, Daniel Zint, and Pierre Alliez}
-\cgalPkgDesc{This package implements several isosurfacing algorithms (Marching Cubes,
+\cgalPkgDesc{This package implements several grid-based isosurfacing algorithms (Marching Cubes,
 its topologically correct variant, and Dual Contouring) that enable generating meshes
-from value and gradient fields.}
+from value and gradient fields. The methods are generic with respect to the definition
+of the grid and the fields, and all methods offer parallel implementations.
+The output is a polygon soup (i.e., a container of point coordinates and indexed faces).}
 \cgalPkgManuals{Chapter_Isosurfacing3,PkgIsosurfacing3Ref}
 \cgalPkgSummaryEnd
 \cgalPkgShortInfoBegin
-\cgalPkgSince{5.6}
+\cgalPkgSince{6.1}
 \cgalPkgBib{cgal:sz-mc}
 \cgalPkgLicense{\ref licensesGPL "GPL"}
 \cgalPkgDemo{Polyhedron demo,polyhedron_3.zip}
 \cgalPkgShortInfoEnd
 \cgalPkgDescriptionEnd
 
-This package provides algorithms to extract isosurfaces: Marching Cubes, topologically correct Marching Cubes,
-and Dual Contouring.
-The input is represented as a space partitioning data structure coupled with a 3D scalar field.
-The output is a polygon soup (i.e., a container of point coordinates and indexed faces).
-
 \cgalClassifedRefPages
 
 \cgalCRPSection{Concepts}

Isosurfacing_3/include/CGAL/Isosurfacing_3/Dual_contouring_domain_3.h

@@ -63,7 +63,7 @@ public:
    * \param intersection_oracle the oracle for edge-isosurface intersection computation
    *
    * \warning the domain class keeps a reference to the `partition`, `values` and `gradients` objects.
-   * As such, users must ensure that the lifetime of these objects exceeds that of the domain object.
+   * As such, users must ensure that the lifetimes of these objects exceed that of the domain object.
    */
   Dual_contouring_domain_3(const Partition& partition,
                            const ValueField& values,
@@ -89,7 +89,7 @@ public:
  * \param intersection_oracle the oracle for edge-isosurface intersection computation
  *
  * \warning the domain class keeps a reference to the `partition`, `values` and `gradients` objects.
- * As such, users must ensure that the lifetime of these objects exceeds that of the domain object.
+ * As such, users must ensure that the lifetimes of these objects exceed that of the domain object.
  */
 template <typename Partition,
           typename ValueField,

Isosurfacing_3/include/CGAL/Isosurfacing_3/Finite_difference_gradient_3.h

@@ -53,7 +53,7 @@ public:
   /**
    * \brief creates a new instance of this gradient class.
    *
-   * \tparam ValueFunction must be a model of `ValueFunction_3`.
+   * \tparam ValueFunction must be a model of `IsosurfacingValueField_3`.
    *
    * \param function the function giving the scalar value at each point
    * \param delta the distance between samples for calculating the finite differences

Isosurfacing_3/include/CGAL/Isosurfacing_3/Interpolated_discrete_gradients_3.h

@@ -25,11 +25,11 @@ namespace CGAL {
 namespace Isosurfacing {
 
 /**
- * \ingroup IS_Domain_helpers_grp
+ * \ingroup IS_Fields_grp
  *
  * \cgalModels{IsosurfacingValueField_3}
  *
- * \brief Class template for a gradient that is calculated using discrete values and trilinear interpolation.
+ * \brief Class template for a gradient field that is computed using discrete values and interpolation.
  *
  * \tparam Grid must be `CGAL::Isosurfacing::Cartesian_grid_3<GeomTraits>`, with `GeomTraits` a model of `IsosurfacingTraits_3`
  * \tparam InterpolationScheme must be a model of `IsosurfacingInterpolationScheme_3`

Isosurfacing_3/include/CGAL/Isosurfacing_3/Interpolated_discrete_values_3.h

@@ -26,7 +26,7 @@ namespace CGAL {
 namespace Isosurfacing {
 
 /**
- * \ingroup IS_Domain_helpers_grp
+ * \ingroup IS_Fields_grp
  *
  * \cgalModels{IsosurfacingValueField_3}
  *

Isosurfacing_3/include/CGAL/Isosurfacing_3/Marching_cubes_domain_3.h

@@ -60,7 +60,7 @@ public:
    * \param intersection_oracle the oracle for edge-isosurface intersection computation
    *
    * \warning the domain class keeps a reference to the `partition`, `values` and `gradients` objects.
-   * As such, users must ensure that the lifetime of these objects exceeds that of the domain object.
+   * As such, users must ensure that the lifetimes of these objects exceed that of the domain object.
    */
   Marching_cubes_domain_3(const Partition& partition,
                           const ValueField& values,
@@ -83,7 +83,7 @@ public:
  * \param intersection_oracle the oracle for edge-isosurface intersection computation
  *
  * \warning the domain class keeps a reference to the `partition`, `values` and `gradients` objects.
- * As such, users must ensure that the lifetime of these objects exceeds that of the domain object.
+ * As such, users must ensure that the lifetimes of these objects exceed that of the domain object.
  */
 template <typename Partition,
           typename ValueField,

Isosurfacing_3/include/CGAL/Isosurfacing_3/Value_function_3.h

@@ -23,7 +23,7 @@ namespace CGAL {
 namespace Isosurfacing {
 
 /**
- * \ingroup IS_Domain_helpers_grp
+ * \ingroup IS_Fields_grp
  *
  * \cgalModels{IsosurfacingValueField_3}
  *

Isosurfacing_3/include/CGAL/Isosurfacing_3/edge_intersection_oracles_3.h

@@ -174,6 +174,7 @@ struct Linear_interpolation_edge_intersection
   }
 };
 
+#ifndef DOXYGEN_RUNNING
 /*
  * \ingroup IS_Domain_helpers_grp
  *
@@ -199,6 +200,7 @@ struct Ray_marching_edge_intersection
                   const typename Domain::Geom_traits::FT isovalue,
                   typename Domain::Geom_traits::Point_3& p) const;
 };
+#endif // DOXYGEN_RUNNING
 
 } // namespace Isosurfacing
 } // namespace CGAL

Isosurfacing_3/include/CGAL/Isosurfacing_3/interpolation_schemes_3.h

@@ -195,6 +195,11 @@ public:
   }
 };
 
+#ifndef DOXYGEN_RUNNING
+// [undocumented]
+//
+// \ingroup IS_Fields_helpers_grp
+//
 // This can be used for example when we have implicit functions for data (values & gradients),
 // but use an interpolated values field as to store data.
 template <typename Grid>
@@ -227,6 +232,7 @@ public:
     return m_gradient_fn(p);
   }
 };
+#endif
 
 } // namespace Isosurfacing
 } // namespace CGAL