more massage on the doc.

some comments/todo for Julian, to discuss

Isosurfacing_3/doc/Isosurfacing_3/Isosurfacing_3.txt

@@ -17,28 +17,30 @@ Different isovalues of a bunny.
 
 \section secmyintroduction Introduction
 
-This package provides algorithms to compute a surface mesh approximating an isosurface of a 3-dimensional scalar field defined over an input 3D domain.
-An isosurface is defined as the surface on which the value of this scalar field equates a given constant, i.e. a user-defined isovalue.
-Depending on the isosurfacing method and the input data structure, the output is either a triangular, quadrilateral, or higher degree polygonal surface mesh represented as an indexed face set. The output can be empty when the isosurface is absent from the input domain.
+TODO: stick to 'field' throughout the whole documentation, and leave the term 'function' for C++ function. This is valid for all terms: introduce them and do not interchange with others throughout the documentation.
+TODO: Make sure you you clearly state that the input field is sampled.
+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.
+
+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. 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.
 \section secmyalgorithms Algorithms
 
-There is a variety of algorithms to extract isosurfaces.
+There is a wide range of algorithms for extracting isosurfaces.
 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.
-Each cell corner gets a sign (+/-) to indicate if it is above or below the isovalue.
-A new vertex is created on every cell edge where the sign changes, i.e. where the edge intersects the isosurface.
-The vertex position is computed via linear interpolation of the scalar 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.
+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 gets a sign (+/-) to indicate if its field value is above or below the 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 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 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]
 If the mesh is manifold and the isosurface does not intersect the domain boundaries, then the output mesh is also watertight.
-As MC only proceeds by linear interpolation of the scalar field along the grid edges, it can miss details or components that are not captured by the said interpolation.
+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.
 
-Compared to other approaches such a Delaunay refinement (TODO: add link to component), and depending on the parameters, the MC algorithm often generates more triangles, and triangles with small angles.
+Compared to other approaches such a Delaunay refinement (TODO: add link to component), and depending on the parameters, the MC algorithm often generates more triangles, and triangles with small angles. [I would reformulate the statement, as this depends too much on the parameters. I would instead add a figure with different parameters and methods]
 MC does not preserve the sharp features present in the isovalue of the input scalar field.
 
 \cgalFigureAnchor{isosurfacing_mc_cases}
@@ -50,14 +52,13 @@ Outputs of Marching Cubes in 2D.
 \cgalFigureCaptionEnd
 
 \subsection subsectmc Topologically correct Marching Cubes (TMC)
-This algorithm is an extension to MC and provides additional guarantees for the output [add reference].
-It generates as output a mesh that is homeomorphic to the trilinear interpolant of the input function inside each cube.
+This algorithm is an extension to MC and provides additional guarantees for the output \cgalCite{g-ctcmi-16}.
+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 can be topologically resolved.
 Furthermore, the mesh is guaranteed to be 2-manifold and watertight, as long as the isosurface does not intersect the domain boundaries.
 
-This algorithm is based on the following paper:
-
+[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.
 
 \subsection subsecdc Dual Contouring (DC)
@@ -68,7 +69,7 @@ For a uniform hexahedral grid, this results into a quadrilateral mesh.
 As the original DC method requires the gradient of the scalar field,
 the provided domain must implement the concept `IsosurfacingDomainWithGradient` 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 to be null everywhere when it is not provided as an additional parameter.
-Alternatively, some default gradient functions are provided such as `Finite_difference_gradient` and `Explicit_cartesian_grid_gradient`.
+Alternatively, some default gradient fields are provided such as `Finite_difference_gradient` and `Explicit_cartesian_grid_gradient`.
 
 Variants of DC differ in the way they compute vertex positions.
 The vertex positioning is thus configurable with an optional parameter passed to the function.
@@ -128,24 +129,24 @@ Depending on the algorithm, the indexed face set may store either a polygon soup
 The isosurfacing algorithms can run either sequentially on one CPU core or in parallel on multicore architectures with shared memory.
 The Concurrency_tag is used to specify how the algorithm is executed: either Sequential_tag or Parallel_tag.
 To enable parallelism, CGAL must be linked with the Intel TBB library.
-When the parallel version is not available due to absent link with the TBB library, then the sequential version is always used as a fallback.
+When the parallel version is not available due to absent link with the TBB library, then the sequential version is utilized as a fallback.
 
 
 \section secmydomains Domains
-An domain is an object that provides functions to access the input data, its geometry, topology, and optionally its gradient.
+An domain is an object that provides functions to access the input data, its geometry, topology, and optionally its gradient. [I fail to understand how you specify the topology - for me the domain is support of the scalar field]
 For common representations, we offer a set of predefined domain classes that wrap the input data and provide a generalized interface for the algorithm.
 Users can also define new domains by implementing the `Isosurfacing_domain` or `IsosurfacingDomainWithGradient` concept.
 
 \subsection mysubsecimplicitdomain Implicit cartesian grid domain
-The `Implicit_cartesian_grid_domain` represents the input function in an implicit form without storing any values.
-It takes a function-object (functor) or lambda function that computes the value of the function from the position of a vertex query.
+The `Implicit_cartesian_grid_domain` represents the input scalar field in an implicit form without storing any values.
+It takes a function-object (functor) or lambda function that computes the value of the scalar field from the position of a vertex query.
 Additionally, the bounding box and spacing between the grid points must be provided.
 
 \subsection mysubseccartesiandomain ExplicitCcartesian grid domain
 The `Explicit_cartesian_grid_domain` only takes a `Cartesian_grid_3` as parameter.
-It represents a uniform grid of values that are either computed by the user or read from an `Image_3`.
+It represents a uniform grid of scalar field values that are either computed by the user or read from an `Image_3`.
 The constructor of `Cartesian_grid_3` requires the number of grid points in each dimension (x, y, z) and the bounding box.
-The values are read and written with `value(x, y, z)` where x, y, and z denote the coordinates of a grid point.
+The field values are read and written with `value(x, y, z)` where x, y, and z denote the coordinates of a grid point.
 Alternatively, all required data can be copied from an `Image_3`.