user manual

Isosurfacing_3/doc/Isosurfacing_3/Isosurfacing_3.txt

@@ -12,41 +12,30 @@ namespace CGAL {
 <img src="tractor_offset.gif" style="max-width:50%;"/>
 </center>
 \cgalFigureCaptionBegin{isosurfacing_tractor_offset}
-Isosurfacing with different isovalues for the tractor model (courtesy GrabCAD).
+Isosurfacing with different isovalues for the tractor model (courtesy the GrabCAD library).
 \cgalFigureCaptionEnd
 
 \section secmyintroduction Introduction
 
-[TODO: add a context and motivation: when do you need MC or dual contouring? what can represent
-the input scalar field ? illustrate this from eg density fields in medical imaging, or distance fields, etc.]
-[TODO: Introduce the terms and stick to them - do not interchange with others throughout the documentation.]
-[TODO: Make sure you you clearly state that the input field is sampled.]
+Isosurfacing, also referred to as isosurface extraction, involves the generation of an approximate isosurface from a sampled 3D scalar field. The output isosurface may consist of a single or of multiple, disjoint connected components. Isosurfacing is commonly required for volume visualization or simulation of physical phenomena. 
 
-This package provides isosurfacing algorithms that compute a surface mesh approximating an isosurface
-of a scalar field defined over an input 3D domain.
-An isosurface is defined as the points of constant value of this scalar field, i.e. a level-set.
+This package provides several isosurfacing algorithms that compute a surface mesh approximating an isosurface of a 3D scalar field defined over an input 3D domain.
+An isosurface is defined as the points of constant value of this scalar field, i.e. a level set.
 Such a constant value, referred to as isovalue, is user-defined. For well-behaved scalar fields
-(e.g., non-zero gradient), the above level-set is a surface.
-Depending on the isosurfacing method and the input data structure, the output is either a triangular,
-a quadrilateral, or a higher degree polygonal surface mesh represented as an indexed face set.
-The output may also be empty when the isosurface is absent from the sampled input scalar field.
+(e.g., non-zero gradient), the above level set is a surface. Depending on the isosurfacing method and the input data structure, the output is either a triangle, a quadrangle or a polygon surface mesh represented as an indexed face set. Note that the output may be empty when the isosurface is absent from the sampled input scalar field.
 
 \section secmyalgorithms Algorithms
 
-There is a wide range of existing algorithms for extracting isosurfaces.
+The scientific literature abounds with algorithms for extracting isosurfaces, each coming with different properties for the output and requirements for the input. 
+% add references to a recent survey or to a series of surveys
 This package offers Marching Cubes, topologically correct Marching Cubes and Dual Contouring.
 
 \subsection subsecmc Marching Cubes (MC)
-MC runs over a 3D grid, i.e. a 3D domain partitioned into hexahedral cells, and processes all cells
-of the input domain individually while sampling the input scalar field at the grid corners.
-Each cell corner is assigned a sign (+/-) to indicate if its field value is above or below the isovalue.
+MC runs over a 3D grid, i.e. a 3D domain partitioned into hexahedral cells, and processes all cells of the input 3D domain individually while sampling the input scalar field at the grid corners.
+Each cell corner is assigned a sign (+/-) to indicate whether its scalar field value is above or below the user-defined isovalue.
 MC creates a vertex for each grid edge with a sign change, i.e. where the edge intersects the isosurface.
-More specifically, the vertex position is computed via linear interpolation of the scalar field values
-evaluated at the cell corners forming the edge. Depending on the configuration of signs at the cell corners,
-the resulting vertices are connected to form triangles within the cell. The figure below illustrates
-the configurations in 2D.
-[ it would be better to show a subset of 3D cases, too, even if the figure is taken from a paper - it
- is probably possible to contact the authors and add a statement - figure courtesy from xxx]
+More specifically, the vertex position is computed via linear interpolation of the scalar field values evaluated at the cell corners forming the edge. Depending on the configuration of signs at the cell corners, the resulting vertices are connected to form triangles within the cell. The figure below illustrates the configurations in 2D. There is no less than 33 cases in 3D (not shown). 
+
 
 \cgalFigureAnchor{isosurfacing_mc_cases}
 <center>
@@ -59,10 +48,8 @@ Different configurations of Marching Cubes in 2D.
 
 The proposed implementation is generic in that it can process any grid-based data structure that consists of hexahedral cells.
 In case of a conforming grid, MC generates as output a surface triangle mesh that is 2-manifold in most scenarios.
-[TODO: 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 boundaries, then the output mesh
- is also watertight. [add a figure showing the two cases]
+% 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 boundaries, then the output mesh is also watertight. % PA : add a figure showing the two cases
 As MC only proceeds by linear interpolation of the sampled scalar field along the grid edges,
 it can miss details or components that are not captured by the said sampling and interpolation.
 
@@ -71,7 +58,8 @@ the MC algorithm often generates more triangles, and more skinny triangles with
 [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]
-MC does not preserve the sharp features present in the isovalue of the input scalar field [TODO add a figure].
+MC does not preserve the sharp features present in the isovalue of the input scalar field 
+% PA: add a figure
 
 
 \subsection subsectmc Topologically Correct Marching Cubes (TMC)
@@ -79,21 +67,17 @@ This algorithm is an extension to MC and provides additional guarantees for the
 It generates as output a mesh that is homeomorphic to the trilinear interpolant of the input scalar field inside each cube.
 This means that the output mesh can accurately represent small complex features.
 For example, a tunnel of the isosurface within a single cell is topologically resolved.
-Furthermore, the mesh is guaranteed to be 2-manifold and watertight, as long as the isosurface does
-not intersect the domain boundaries.
-[add a figure comparing without and with the option activated]
+Furthermore, the mesh is guaranteed to be 2-manifold and watertight, as long as the isosurface does not intersect the domain boundaries.
+% PA: add a figure comparing without and with the option activated
 
-[TODO: add following to CGAL list of references]
-Roberto Grosso: Construction of Topologically Correct and Manifold Isosurfaces. Computer Graphics Forum 35(5):187-196 - 2016.
+% PA: add following to CGAL list of references: Roberto Grosso: Construction of Topologically Correct and Manifold Isosurfaces. Computer Graphics Forum 35(5):187-196 - 2016.
 
 \subsection subsecdc Dual Contouring (DC)
-DC creates one vertex for each cell that is intersected by the isosurface.
-Next, a face is created for each edge that intersects the isosurface, by connecting the vertices of the incident cells.
-For a uniform hexahedral grid, this results into a quadrilateral surface mesh.
+The DC algorithm generates one vertex for each cell that is intersected by the isosurface. Next, a face is created for each edge that intersects the isosurface, by connecting the vertices of the incident cells. For a uniform hexahedral grid, this results into a quadrilateral surface mesh.
 
 As the original DC method requires the gradient of the scalar field, the domain must implement
 the concept `IsosurfacingDomainWithGradient_3` in order to provide a gradient field in addition to a scalar field.
-All default domain implementations also provide a gradient field, but assume the gradient
+All default domain implementations provide a gradient field, but assume the gradient
 to be null everywhere when it is not provided as an additional parameter.
 Alternatively, some default gradient fields are provided such as `Finite_difference_gradient_3`
 and `Explicit_Cartesian_grid_gradient_3`.
@@ -105,7 +89,7 @@ Some variants do not require the gradient and therefore run successfully even wh
 Dual Contouring can deal with any domain but guarantees neither a 2-manifold nor a watertight mesh.
 It generates fewer faces than Marching Cubes, in general.
 Its advantage over MC is its ability to recover sharp creases and corners.
-[TODO: add a figure.]
+% PA: add a figure.
 [what about tips, darts, cusps and corners? respectively adjacent to 0, 1, 2 and 3+ creases]
 
 \cgalFigureAnchor{isosurfacing_iwp_dc}
@@ -133,7 +117,7 @@ The following table compares the algorithms in terms of constraints over the inp
 <img src="cube_mc_dc.png" style="max-width:70%;"/>
 </center>
 \cgalFigureCaptionBegin{isosurfacing_compare_mc_dc}
-Comparison between a cube generated by %Dual Contouring (left) or by Marching Cubes (right).
+Comparison between a cube generated by Dual Contouring (left) or by Marching Cubes (right).
 \cgalFigureCaptionEnd
 
 
@@ -150,11 +134,9 @@ The input is provided in the form of a `domain` (see \ref secmydomains).
 
 The `isovalue` scalar parameter denotes the value used for sampling the input scalar field for generating the isosurface.
 
-[why using the term collection below ? how about containers? ]
-
-The output surface mesh is provided in the form of a indexed face set, which is written to the two collections `points` and `polygons`.
-The vertex positions are stored as `Point_3` in `points`. Each face in `polygons` is a list of indices pointing into the `points` collection.
-Depending on the algorithm, the indexed face set may store either a polygon soup or a mesh with connectivity.
+The output surface mesh is provided in the form of a indexed face set, which is written to the two containers of `points` and `polygons`.
+The vertex positions are stored as `Point_3` in `points`. Each face in `polygons` is a list of indices pointing into the `points` container.
+Depending on the algorithm, the indexed face set may store either a polygon soup (unorganized polygons with no relationship whatsoever, i.e. no connectivity between them) or a mesh with connectivity.
 
 The isosurfacing algorithms can run either sequentially on one CPU core or in parallel on multicore architectures with shared memory.
 The template parameter `ConcurrencyTag` is used to specify how the algorithm is executed: either Sequential_tag or Parallel_tag.