|
| 1 | +# Discregrid |
| 2 | + |
| 3 | +**Discregrid** is a static C++ library for the parallel discretization of (preferably smooth) functions on regular grids. Given a box-shaped domain, a grid resolution and a function mapping a three-dimensional position in space to a scalar real value a polynomial discretization is computed. In the current implementation cubic polynomials of Serendipity type are employed for the cell-wise discretization. The coefficient vector for the discrete polynomial basis is computed using regular sampling of the input function at the higher-order grid's nodes. However, I plan to provide a spatially adaptive version of the cubic discretization and moreover an implementation of the hp-adaptive discretization algorithm described in [KDBB17]. The algorithm to generate the discretization is moreover *fully parallelized** using OpenMP is especially well-suited for the discretization of signed distance functions. The library moreover provides the functionality to serialize and deserialize the a generated discrete grid. |
| 4 | + |
| 5 | +Besides the library the project includes three executable programs that serve the following purposes: |
| 6 | +* *GenerateSDF*: Computes a discrete (cubic) signed distance field from a triangle mesh in OBJ format. |
| 7 | +* *DiscreteFieldToBitmap*: Generates an image in bitmap format of a two-dimensional slice of a previously computed discretization. |
| 8 | +* *GenerateDensityMap*: Generates a density map according to the approach presented in [KB17] from a previously generated discrete signed distance field. |
| 9 | + |
| 10 | +**Author**: Dan Koschier, **License**: MIT |
| 11 | + |
| 12 | +## Libraries using CompactNSearch |
| 13 | +* [PBD] - A C++ library for physically-based simulation of rigid bodies, deformables, cloth and fluids using Position-Based Dynamics. Discregrid is used to compute discrete signed distance fields of rigid objects for collision handling purposes. |
| 14 | +* [SPlisHSPlasH] - A C++ library for the physically-based simulation of fluids using Smoothed Particle Hydrodynamics. Discregrid is used to compute density maps according to my paper [KB17] for boundary handling. |
| 15 | + |
| 16 | +## Build Instructions |
| 17 | + |
| 18 | +This project is based on [CMake](https://cmake.org/). Simply generate project, Makefiles, etc. using [CMake](https://cmake.org/) and compile the project with the compiler of your choice. The code was tested with the following configurations: |
| 19 | +- Windows 10 64-bit, CMake 3.8, Visual Studio 2017 |
| 20 | +- Debian 8 64-bit, CMake 3.8, GCC 4.9.2. |
| 21 | + |
| 22 | +## Usage |
| 23 | +In order to use the library the main header has to be included and the static library has to be compiled and linked against the client program. |
| 24 | +In this regard a find script for CMake is provided, i.e. FindDiscregrid.cmake. |
| 25 | +The main header can be included as follows: |
| 26 | +```c++ |
| 27 | +#include <Discregrid/All> |
| 28 | +``` |
| 29 | + |
| 30 | +A base class for the data structure that generates and holds a discretization a function f: R -> R^3 can be constructed as follows: |
| 31 | +```c++ |
| 32 | +// Firstly, create a domain on which a discretization will be generated. |
| 33 | +Eigen::AlignedBox3d domain; |
| 34 | +// Then specify domain extents using e.g. domain.extend(...). |
| 35 | +// Secondly, specify a grid resolution. |
| 36 | +std::array<unsigned int, 3> resolution = {{10, 10, 10}} |
| 37 | +// Finally, instantiate the grid. |
| 38 | +Discregrid::CubicLagrangeDiscreteGrid discrete_grid(domain, resolution); |
| 39 | +``` |
| 40 | +Then, an arbitrary number of functions can be discretized on the initiated grid: |
| 41 | +```c++ |
| 42 | +Discregrid::DiscreteGrid::ContinuousFunction func1 = ...; |
| 43 | +Discregrid::DiscreteGrid::ContinuousFunction func2 = ...; |
| 44 | +
|
| 45 | +auto df_index1 = discrete_grid.addFunction(func1); |
| 46 | +auto df_index2 = discrete_grid.addFunction(func2); |
| 47 | +``` |
| 48 | +Optionally, only coefficients at nodes fulfilling a certain predicate can be generated by specifying the predicate: |
| 49 | +```c++ |
| 50 | +Discregrid::DiscreteGrid::ContinuousFunction func3 = ...; |
| 51 | +auto df_index3 = discrete_grid.addFunction(func3, false, [&](Vector3d const& x) |
| 52 | +{ |
| 53 | + ... |
| 54 | + // Return true if a certain criterion for the node location x is fulfilled, e.g. |
| 55 | + return x.y() > 0.0; |
| 56 | +}); |
| 57 | +``` |
| 58 | +A value of a discrete field can be evaluated by interpolation. |
| 59 | +Additionally, the gradient at the given query point can be computed if desired. |
| 60 | +```c++ |
| 61 | +auto val1 = sdf->interpolate(df_index1, {0.1, 0.2, 0.3}); |
| 62 | +auto grad2 = Eigen::Vector3d{}; |
| 63 | +auto val2 = sdf->interpolate(df_index2, {0.3, 0.2, 0.1}, &grad2); |
| 64 | +``` |
| 65 | +
|
| 66 | +If a discretization of the input function is only required in certain regions of the given domain, the discretization can be reduced resulting in a sparsely populated grid to save memory: |
| 67 | +```c++ |
| 68 | +discrete_grid.reduce_field(df_index1, [](Eigen::Vector3d const& x, double v) |
| 69 | + { |
| 70 | + // E.g. |
| 71 | + return x.x() < 0.0 && v > 0.0; |
| 72 | + }); |
| 73 | +``` |
| 74 | +Here x represents the location of sample point in the grid and v represents the sampled value of the input function. If the predicated function evaluates to true the sample point is kept but discarded otherwise. |
| 75 | + |
| 76 | +Optionally, the data structure can be serialized and deserialized via |
| 77 | +```c++ |
| 78 | +discrete_grid.save(filename); |
| 79 | +discrete_grid.load(filename); // or |
| 80 | +discrete_grid = Discregrid::CubicLagrangeDiscreteGrid(filename); |
| 81 | +``` |
| 82 | + |
| 83 | +## References |
| 84 | + |
| 85 | +* [KDBB17] D. Koschier, C. Deul, M. Brand and J. Bender, 2017. "An hp-Adaptive Discretization Algorithm for Signed Distance Field Generation", IEEE Transactions on Visualiztion and Computer Graphics 23, 10, 2208-2221. |
| 86 | +* [KB17] D. Koschier and J. Bender, 2017. "Density Maps for Improved SPH Boundary Handling", ACM SIGGRAPH/Eurographics Symposium on Computer Animation, 1-10. |
| 87 | + |
| 88 | +[PBD]: <https://github.com/InteractiveComputerGraphics/PositionBasedDynamics> |
| 89 | +[SPlisHSPlasH]: <https://github.com/InteractiveComputerGraphics/SPlisHSPlasH> |
0 commit comments