From ee4c6dc7bf48b614ba8f3fbe9678a321d51cb71b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mael=20Rouxel-Labb=C3=A9?= Date: Thu, 4 Apr 2024 12:42:50 +0200 Subject: [PATCH] Misc doc fixes --- .../doc/Isosurfacing_3/Isosurfacing_3.txt | 56 +++++++++---------- .../doc/Isosurfacing_3/PackageDescription.txt | 23 +++++--- .../Isosurfacing_3/Dual_contouring_domain_3.h | 4 +- .../Finite_difference_gradient_3.h | 2 +- .../Interpolated_discrete_gradients_3.h | 4 +- .../Interpolated_discrete_values_3.h | 2 +- .../Isosurfacing_3/Marching_cubes_domain_3.h | 4 +- .../CGAL/Isosurfacing_3/Value_function_3.h | 2 +- .../edge_intersection_oracles_3.h | 2 + .../Isosurfacing_3/interpolation_schemes_3.h | 6 ++ 10 files changed, 58 insertions(+), 47 deletions(-) diff --git a/Isosurfacing_3/doc/Isosurfacing_3/Isosurfacing_3.txt b/Isosurfacing_3/doc/Isosurfacing_3/Isosurfacing_3.txt index 5638b0597cc..39ecf725370 100644 --- a/Isosurfacing_3/doc/Isosurfacing_3/Isosurfacing_3.txt +++ b/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. -In case of a conforming grid, the Marching Cubes algorithm generates -as output a surface triangle mesh that is 2-manifold in most scenarios. - -@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 +that consists of hexahedral cells. When the hexahedral grid is a conforming grid (meaning that the +intersection of two hexahedral cells is a face, and edge, or a vertex), the Marching Cubes algorithm +generates as output a surface triangle mesh that is almost always combinatorially 2-manifold, +but can also produce cracks in the surface. 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, -MC often generates more triangles, and more skinny triangles with small or large angles. -@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, -depicting the mesh edges in black in addition to the shaded facets. +Compared to other meshing approaches such as Delaunay refinement, Marching Cubes is much faster, +but often tends to generate more triangles for an equivalent desired sizing field. In addition, +the quality of the elements if generally poor, with many needles / caps shaped faces. -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) | -(* assuming the isosurface does not exit the specified bounding box of the input 3D domain)
-(** not guaranteed) +(* assuming the isosurface does not exit the specified bounding box of the input 3D domain) Note that the output mesh has boundaries when the isosurface intersects the domain boundaries, regardless of the method (see \cgalFigureRef{IsosurfacingOpen}). @@ -208,35 +204,35 @@ To enable parallelism, \cgal must be linked with the `, with `GeomTraits` a model of `IsosurfacingTraits_3` * \tparam InterpolationScheme must be a model of `IsosurfacingInterpolationScheme_3` diff --git a/Isosurfacing_3/include/CGAL/Isosurfacing_3/Interpolated_discrete_values_3.h b/Isosurfacing_3/include/CGAL/Isosurfacing_3/Interpolated_discrete_values_3.h index 19937a765d9..a6d8da8aeb0 100644 --- a/Isosurfacing_3/include/CGAL/Isosurfacing_3/Interpolated_discrete_values_3.h +++ b/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} * diff --git a/Isosurfacing_3/include/CGAL/Isosurfacing_3/Marching_cubes_domain_3.h b/Isosurfacing_3/include/CGAL/Isosurfacing_3/Marching_cubes_domain_3.h index 057d25380e3..11008340f41 100644 --- a/Isosurfacing_3/include/CGAL/Isosurfacing_3/Marching_cubes_domain_3.h +++ b/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 @@ -227,6 +232,7 @@ public: return m_gradient_fn(p); } }; +#endif } // namespace Isosurfacing } // namespace CGAL