Add detailed description of the reconstruction algorithm

Author: w1th0utnam3

README.md

@@ -20,10 +20,14 @@ As input, it supports particle positions from .vtk files and binary .xyz files (
 The implementation first computes the density of each particle using the typical SPH approach with a cubic kernel. 
 This density is then evaluated or mapped onto a sparse grid using spatial hashing in the support radius of each particle.
 This implies that memory is only allocated in areas where the fluid density is non-zero. This is in contrast to a naive approach where the marching cubes background grid is allocated for the whole domain. 
-Finally, the marching cubes reconstruction is performed only in those grid cells where the density values cross the surface threshold. Cells completely in the interior of the fluid are skipped.
+Finally, the marching cubes reconstruction is performed only in those grid cells where the density values cross the surface threshold. Cells completely in the interior of the fluid are skipped. For more details, please refer to the [readme of the library]((https://github.com/w1th0utnam3/splashsurf/blob/master/splashsurf_lib/README.md)).
+
+## Notes
 
 Due the use of hash maps and multi-threading (if enabled), the output of this implementation is not deterministic.
-In the future, flags may be added to switch the internally data structures to use binary trees for debugging.
+In the future, flags may be added to switch the internal data structures to use binary trees for debugging purposes.
+
+Note that for small numbers of fluid particles (i.e. in the low thousands or less) the multi-threaded implementation may have worse performance due to the worker pool overhead and looks on the map data structures (even though the library uses [`dashmap`](https://crates.io/crates/dashmap) which is more optimized for multi-threaded usage).
 
 As shown below, the tool can handle the output of large simulations.
 However, it was not tested with a wide range of parameters and may not be totally robust against corner-cases or extreme parameters.
@@ -39,6 +43,8 @@ cargo install splashsurf
 
 ## Usage
 
+### Basic usage
+
 ```
 USAGE:
     splashsurf.exe [FLAGS] [OPTIONS] <input-file> --cube-size <cube-size> --kernel-radius <kernel-radius> --particle-radius <particle-radius> --surface-threshold <surface-threshold>
@@ -130,6 +136,10 @@ With these parameters, a scene with 13353401 particles is reconstructed in nearl
 [2020-08-25T15:52:59.879171+02:00][splashsurf][INFO]   write surface mesh to file: 2.02%, 511.21ms/call @ 0.04Hz
 ```
 
+### Sequences of files
+
+*TODO: Describe syntax to reconstruct a sequence of files*
+
 ## Input file formats
 
 *TODO: Document more details about the expected format of supported file extensions*
@@ -138,7 +148,7 @@ With these parameters, a scene with 13353401 particles is reconstructed in nearl
 
 The ply format expects an element definition 'vertex', with element properties of 'x,y,z'
 
-## License
+# License
 
 For license information of this project, see the LICENSE file.
 The splashsurf logo is based on two graphics ([1](https://www.svgrepo.com/svg/295647/wave), [2](https://www.svgrepo.com/svg/295652/surfboard-surfboard)) published on SVG Repo under a CC0 ("No Rights Reserved") license.

splashsurf/README.md

@@ -20,10 +20,14 @@ As input, it supports particle positions from .vtk files and binary .xyz files (
 The implementation first computes the density of each particle using the typical SPH approach with a cubic kernel. 
 This density is then evaluated or mapped onto a sparse grid using spatial hashing in the support radius of each particle.
 This implies that memory is only allocated in areas where the fluid density is non-zero. This is in contrast to a naive approach where the marching cubes background grid is allocated for the whole domain. 
-Finally, the marching cubes reconstruction is performed only in those grid cells where the density values cross the surface threshold. Cells completely in the interior of the fluid are skipped.
+Finally, the marching cubes reconstruction is performed only in those grid cells where the density values cross the surface threshold. Cells completely in the interior of the fluid are skipped. For more details, please refer to the [readme of the library]((https://github.com/w1th0utnam3/splashsurf/blob/master/splashsurf_lib/README.md)).
+
+## Notes
 
 Due the use of hash maps and multi-threading (if enabled), the output of this implementation is not deterministic.
-In the future, flags may be added to switch the internally data structures to use binary trees for debugging.
+In the future, flags may be added to switch the internal data structures to use binary trees for debugging purposes.
+
+Note that for small numbers of fluid particles (i.e. in the low thousands or less) the multi-threaded implementation may have worse performance due to the worker pool overhead and looks on the map data structures (even though the library uses [`dashmap`](https://crates.io/crates/dashmap) which is more optimized for multi-threaded usage).
 
 As shown below, the tool can handle the output of large simulations.
 However, it was not tested with a wide range of parameters and may not be totally robust against corner-cases or extreme parameters.
@@ -39,6 +43,8 @@ cargo install splashsurf
 
 ## Usage
 
+### Basic usage
+
 ```
 USAGE:
     splashsurf.exe [FLAGS] [OPTIONS] <input-file> --cube-size <cube-size> --kernel-radius <kernel-radius> --particle-radius <particle-radius> --surface-threshold <surface-threshold>
@@ -130,6 +136,10 @@ With these parameters, a scene with 13353401 particles is reconstructed in nearl
 [2020-08-25T15:52:59.879171+02:00][splashsurf][INFO]   write surface mesh to file: 2.02%, 511.21ms/call @ 0.04Hz
 ```
 
+### Sequences of files
+
+*TODO: Describe syntax to reconstruct a sequence of files*
+
 ## Input file formats
 
 *TODO: Document more details about the expected format of supported file extensions*
@@ -138,7 +148,7 @@ With these parameters, a scene with 13353401 particles is reconstructed in nearl
 
 The ply format expects an element definition 'vertex', with element properties of 'x,y,z'
 
-## License
+# License
 
 For license information of this project, see the LICENSE file.
 The splashsurf logo is based on two graphics ([1](https://www.svgrepo.com/svg/295647/wave), [2](https://www.svgrepo.com/svg/295652/surfboard-surfboard)) published on SVG Repo under a CC0 ("No Rights Reserved") license.

splashsurf_lib/README.md

@@ -23,4 +23,27 @@ For each of the features, `splashsurf_lib` re-exports the corresponding dependen
 
 ## The surface reconstruction procedure
 
-*TODO: Describe the surface reconstruction "algorithm" implemented in this crate*
+Currently, only one method based on a "spatial hashing" strategy is implemented.
+
+**Short summary**: The fluid density is evaluated or mapped onto a sparse grid using spatial hashing in the support radius of each fluid particle. This implies that memory is only allocated in areas where the fluid density is non-zero. This is in contrast to a naive approach where the marching cubes background grid is allocated for the whole domain. Finally, the marching cubes reconstruction is performed only in those grid cells where an edge crosses the surface threshold. Cells completely in the interior of the fluid are skipped in the marching cubes phase.
+
+**Individual steps**:
+ 1. Construct a "virtual background grid" with the desired resolution of the marching cubes algorithm. In the end, the procedure will place a single surface mesh vertex on each edge of this virtual grid, where the fluid surface crosses the edge (or rather, where the fluid density crosses the specified threshold). Virtual means that no storage is actually allocated for this grid yet; only its topology is used implicitly later.
+ 2. Compute the density of each fluid particle
+   - Perform a neighborhood search
+   - Per particle, evaluate an SPH sum over the neighbors to compute its density (based on input parameters of kernel radius and particle rest mass)
+ 3. Optional: filter out (or rather mask as inactive) single particles if the user provided a "splash detection radius". This is done by performing an additional neighborhood search using this splash detection radius instead of the kernel radius.
+ 4. Compute a "sparse density map": a map from the index of a vertex of the virtual background grid to the corresponding fluid density value. The map will only contain entries for vertices where the fluid density is non-zero. Construction of the map:
+    - Iterate over all active particles
+    - For each particle evaluate its kernel at all virtual background vertices that can be influenced by it (i.e. vertices inside its kernel radius)
+    - Add-assign the corresponding density contribution (kernel value times particle density) to the vertex entry in the density map
+ 5. Interpolate the density values at the vertices of each virtual background cell to points on the edges where the edge crosses the fluid surface
+    - Iterate over all vertices in the sparse density map
+    - Skip vertices where the density value is above the threshold to be considered inside of the fluid
+    - For each of the remaining vertices, check if any neighboring vertex (i.e. a vertex that is directly connected with it by an edge of the virtual background grid) is above the threshold
+    - If this is the case, an edge that crosses the fluid surface was found and the position of the surface on the edge can be calculated using linear interpolation
+    - This interpolated position is stored in a new map that maps indices of virtual background cells to structs containing the surface crossing points per edge. Entries are only created for cells with edges that actually cross the surface
+ 6. Triangulate the points on the edges using a marching cubes case table
+    - Iterate over all cells in the cell data map
+    - For each cell, look up the corresponding triangulation in a marching cubes LUT
+    - Emit the required triangles into the final mesh data structure