Surface reconstruction library and CLI for particle data from SPH simulations, written in Rust.

This repository contains of the following components:

• 🛠️ splashsurf: Binary crate with a CLI (command line interface) to quickly run surface reconstructions of SPH particle data files from the terminal. Install with cargo install splashsurf.
• 🧰 splashsurf_lib: Rust library that implements the reconstruction method used by the CLI. Allows integrating the reconstruction procedure directly into other Rust applications. Furthermore, it resembles a framework providing access to individual building blocks to create your own surface reconstruction pipeline.
• 🐍 pysplashsurf: Bindings to the CLI and library for Python. Install with pip install splashsurf and see the README for more details.
• 🎬 splashsurf_studio: Blender add-on built on top of the Python bindings for on-the-fly surface reconstruction. Available from the official Blender extension repository.

This page provides an overview of the CLI's features and high-level notes on implementation of the reconstruction method.

<p align="center"> <img src="example_particles.png" alt="Image of the original particle data" width="32%"> <img src="example_coarse.png" alt="Image of a coarse reconstructed surface mesh" width="32%"> <img src="example_fine.png" alt="Image of a fine reconstructed surface mesh" width="32%"> </p>

splashsurf is a tool designed to reconstruct surface meshes from SPH particle data. The first image illustrates the visualization of a set of particles from an SPH fluid simulation made using SPlisHSPlasH. The particle radius is 0.025. To ensure that the rendering of a fluid does not resemble a ball pit, a surface mesh must be reconstructed from this particle data. The second image displays a reconstructed surface mesh of the fluid produced by splashsurf, utilizing a "smoothing length" of 2.2 times the particle radius and a cell size of 1.1 times the particle radius. The third image showcases a finer reconstruction with a cell size of 0.45 times the particle radius. These surface meshes can then be imported into 3D rendering software such as Blender to create stunning water animations. The result may resemble the following:

<p align="center"> <img src="https://raw.githubusercontent.com/w1th0utnam3/w1th0utnam3.github.io/master/splashsurf.gif" alt="Rendered water animation" width="96%"> </p>

---

Contents

• The splashsurf CLI
  • Introduction
  • Domain decomposition
    • Subdomain grid-based decomposition
  • Notes
  • Installation
  • Usage
    • Recommended settings
    • Weighted surface smoothing
    • Benchmark example
    • Sequences of files
  • Input file formats
    • VTK
    • VTU
    • BGEO
    • PLY
    • XYZ
    • JSON
  • Output file formats
  • All command line options
    • The reconstruct command
    • The convert subcommand
  • Citation
  • Acknowledgements
• License

The splashsurf CLI

The following sections mainly focus on the CLI of splashsurf. For more information on the library, see the corresponding readme in the splashsurf_lib subfolder or the splashsurf_lib crate on crates.io.

Introduction

The splashsurf CLI provides a "fast" marching cubes based surface reconstruction for particle data from SPH fluid simulations (e.g., performed with SPlisHSPlasH). The output of this tool is a (closed) triangle mesh of the fluid's surface. At the moment, it supports computing normals on the surface using SPH gradients and interpolating scalar and vector attributes defined on the particles to the surface. To get rid of the typical bumps from SPH simulations, it supports a weighted Laplacian smoothing approach detailed below. As input, it supports reading particle positions from .vtk/.vtu, .bgeo, .ply, .json and binary .xyz (i.e., files containing a binary dump of a particle position array) files. Required parameters to perform a reconstruction are the kernel radius (its compact support) and particle radius (to compute the volume of particles) used for the original SPH simulation as well as the marching cubes resolution (a default iso-surface threshold is pre-configured).

Domain decomposition

A naive dense marching cubes reconstruction allocating a full 3D array over the entire fluid domain quickly becomes infeasible for larger simulations. Instead, one could use a global hashmap where only cubes that contain non-zero fluid density values are allocated. This approach is used in splashsurf if domain decomposition is disabled completely. However, a global hashmap does not lead to good cache locality and is not well suited for parallelization (even specialized parallel map implementations like dashmap have their performance limitations). To improve on this situation splashsurf utilizes a domain decomposition approach.

Subdomain grid-based decomposition

Since version 0.10.0, splashsurf implements a domain decomposition approach called the "subdomain grid" approach, toggled with the --subdomain-grid=on flag (default since version 0.11.0). Here, the goal is to divide the fluid domain into subdomains with a fixed number of marching cubes cells, by default 64x64x64 cubes. For each subdomain, a dense 3D array is allocated for the marching cubes cells. Of course, only subdomains that contain any fluid particles are actually allocated. For subdomains that contain only a tiny number of fluid particles (less than 5% of the largest subdomain), a hashmap is used instead to not waste too much storage. As most domains are dense, however, the marching cubes triangulation per subdomain is very fast as it can make full use of cache locality. The triangulation per subdomain can be performed in parallel. To stitch the resulting meshes together, we ensure that we perform floating point operations in the same order at the subdomain boundaries, thus guaranteeing identical values (this is possible without additional synchronization). If the field values on the subdomain boundaries are identical from both sides, the marching cubes triangulations will be topologically compatible and can be merged in a post-processing step that can also run in parallel. Overall, this approach should almost always be faster than the octree-based approach used before version 0.10.0.

Notes

For small numbers of fluid particles (i.e., in the low thousands or less) the domain decomposition may have worse performance due to the task-based parallelism and the additional overhead of domain decomposition and stitching. In this case, you can try to disable the domain decomposition. The reconstruction will then use a global approach parallelized using thread-local hashmaps. For larger quantities of particles, the decomposition approach is always expected to be faster.

Due to the use of hash maps and multi-threading (if enabled), the output of this implementation is not deterministic.

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. If you experience problems, please report them together with your input data.

Installation

The command-line tool can be built from this repository but is also available on crates.io. If you have a Rust toolchain installed you can install splashsurf with the command

cargo install splashsurf

Alternatively you can install the Python bindings using pip:

pip install pysplashsurf

Please see the README of the Python bindings for more details.

Usage

Recommended settings

"Good" settings for the surface reconstru