Functions

All functions infer float precision based on the input (np.float32 or np.float64).

pysplashsurf.barnacle_decimation(mesh, *, keep_vertices)

Performs specialized decimation on the given mesh to prevent “barnacles” when applying weighted Laplacian smoothing

The decimation is performed inplace and modifies the given mesh. Returns the vertex-vertex connectivity of the decimated mesh which can be used for other post-processing steps.

Parameters:

  • mesh – The triangle mesh to decimate.

  • keep_vertices – Flag to retain any vertices without connectivity resulting from decimation instead of filtering them out.

pysplashsurf.check_mesh_consistency(mesh, grid, *, check_closed=True, check_manifold=True, debug=False)

Checks the consistency of a reconstructed surface mesh (watertightness, manifoldness), optionally returns a string with details, if problems are found

Parameters:

  • mesh – The triangle mesh to check for consistency.

  • grid – The uniform grid that was used for the marching cubes triangulation of the input mesh.

  • check_closed – Flag to enable checking if the mesh is closed (watertight).

  • check_manifold – Flag to enable checking if the mesh is manifold (i.e. has no non-manifold vertices & edges).

  • debug – Flag to enable additional debug output during the consistency checks.

Returns:

  • An optional string with details about the problems found during the consistency checks.

  • If no problems are found, None is returned.

pysplashsurf.convert_tris_to_quads(mesh, *, non_squareness_limit=1.75, normal_angle_limit=10.0, max_interior_angle=135.0)

Converts triangles to quads by merging triangles sharing an edge if they fulfill the given criteria

This operation creates a new mesh and does not modify the input mesh. Angles are specified in degrees.

Parameters:

  • mesh – The triangle mesh to convert to a mixed triangle-quad mesh.

  • non_squareness_limit – Maximum allowed ratio of quad edge lengths to its diagonals to merge two triangles to a quad (inverse is used for minimum).

  • normal_angle_limit – Maximum allowed angle (in degrees) between triangle normals to merge them to a quad.

  • max_interior_angle – Maximum allowed vertex interior angle (in degrees) inside a quad to merge two triangles to a quad.

pysplashsurf.laplacian_smoothing_normals_parallel(normals, vertex_connectivity, *, iterations)

Laplacian smoothing of a normal field

The smoothing is performed inplace and modifies the given normal array.

Parameters:

  • normals – A two-dimensional array of shape (N, 3) containing the normals to smooth.

  • vertex_connectivity – The vertex-vertex connectivity of the mesh, required for efficient smoothing.

  • iterations – The number of smoothing iterations to perform.

pysplashsurf.laplacian_smoothing_parallel(mesh, vertex_connectivity, *, iterations, beta=1.0, weights)

Laplacian smoothing of mesh vertices with feature weights

The smoothing is performed inplace and modifies the vertices of the given mesh.

Parameters:

  • mesh – The triangle mesh to smooth.

  • vertex_connectivity – The vertex-vertex connectivity of the mesh, required for efficient smoothing.

  • iterations – The number of smoothing iterations to perform.

  • beta – Factor used for blending the original vertex position with the smoothed position.

  • weights – A one-dimensional array of weights per vertex that influence the smoothing. The weight is multiplied with beta.

pysplashsurf.marching_cubes(values, *, iso_surface_threshold, cube_size, translation=None, return_grid=False)

Performs a standard marching cubes triangulation of a 3D array of values

The array of values has to be a contiguous array with shape (nx, ny, nz). The iso-surface threshold defines which value is considered to be “on” the surface. The cube size and translation parameters define the scaling and translation of the resulting mesh. Without translation, the value values[0, 0, 0] is located at coordinates (0, 0, 0).

The values are interpreted as a “density field”, meaning that values higher than the iso-surface threshold are considered to be “inside” the surface and values lower than the threshold are considered to be “outside” the surface. This is the opposite convention to an SDF (signed distance field). However, even if values of an SDF are provided as an input, the marching cubes algorithm will still work and produce a watertight surface mesh (if the surface is fully contained in the array).

If return_grid is set to True, the function will return a tuple of the mesh and the uniform grid that was used for the triangulation. This can be used for other functions such as check_mesh_consistency(). Otherwise, only the mesh is returned.

The function is currently single-threaded. The SPH surface reconstruction functions reconstruction_pipeline() and reconstruct_surface() improve performance by processing multiple patches in parallel.

Parameters:

  • values (numpy.ndarray) – A three-dimensional numpy array of shape (nx, ny, nz) containing the scalar values at the vertices of the marching cubes grid.

  • iso_surface_threshold – The iso-surface threshold value used to determine the surface.

  • cube_size – The size of each cube/voxel of the marching cubes grid. Determines the scaling of the resulting mesh.

  • translation – An optional translation vector [tx, ty, tz] applied to the entire mesh after scaling.

pysplashsurf.marching_cubes_cleanup(mesh, grid, *, max_rel_snap_dist=None, max_iter=5, keep_vertices=False)

Performs simplification on the given mesh inspired by the “Compact Contouring”/”Mesh displacement” approach by Doug Moore and Joe Warren

The simplification is performed inplace and modifies the given mesh. The method is designed specifically for meshes generated by Marching Cubes. See Moore and Warren: Mesh Displacement: An Improved Contouring Method for Trivariate Data (1991) or Moore and Warren: “Compact Isocontours from Sampled Data” in “Graphics Gems III” (1992).

Parameters:

  • mesh – The triangle mesh to simplify.

  • grid – The uniform grid that was used for the marching cubes triangulation of the input mesh.

  • max_rel_snap_dist – Optional maximum relative snapping distance (relative to the grid cell size) to merge close vertices.

  • max_iter – The maximum number of iterations of cleanup to perform.

  • keep_vertices – Flag to retain any vertices without connectivity resulting from simplification instead of filtering them out.

pysplashsurf.neighborhood_search_spatial_hashing_parallel(particle_positions, domain, search_radius)

Performs a neighborhood search using spatial hashing (multithreaded implementation)

Parameters:

  • particles (numpy.ndarray) – A two-dimensional numpy array of shape (N, 3) containing the positions of the particles.

  • domain – An axis-aligned bounding box (AABB) of the particles used for spatial hashing. The neighborhood search fails if particles are outside the domain.

  • search_radius – The radius per particle where other particles are considered neighbors.

pysplashsurf.reconstruct_surface(particles, *, particle_radius, rest_density=1000.0, smoothing_length, cube_size, iso_surface_threshold=0.6, aabb_min=None, aabb_max=None, multi_threading=True, simd=True, global_neighborhood_list=False, subdomain_grid=True, subdomain_grid_auto_disable=True, subdomain_num_cubes_per_dim=64)

Performs a surface reconstruction from the given particles without additional post-processing

Note that all parameters use absolute distance units and are not relative to the particle radius.

Parameters:

  • particles (numpy.ndarray) – A two-dimensional numpy array of shape (N, 3) containing the positions of the particles.

  • particle_radius – Particle radius.

  • rest_density – Rest density of the fluid.

  • smoothing_length – Smoothing length of the SPH kernel in absolute distance units (compact support radius of SPH kernel will be twice the smoothing length).

  • cube_size – Size of the cubes (voxels) used for the marching cubes grid in absolute distance units.

  • iso_surface_threshold – Threshold of the SPH interpolation of the “color field” where the iso surface should be extracted.

  • aabb_min – Lower corner of the AABB of particles to consider in the reconstruction.

  • aabb_max – Upper corner of the AABB of particles to consider in the reconstruction.

  • multi_threading – Flag to enable multi-threading for the reconstruction and post-processing steps.

  • simd – Flag to enable SIMD vectorization for the reconstruction if supported by the CPU architecture.

  • subdomain_grid – Flag to enable spatial decomposition by dividing the domain into subdomains with dense marching cube grids for efficient multi-threading.

  • subdomain_grid_auto_disable – Flag to automatically disable the subdomain grid if the global domain is too small.

  • subdomain_num_cubes_per_dim – Number of marching cubes voxels along each coordinate axis in each subdomain if the subdomain grid is enabled.

pysplashsurf.reconstruction_pipeline(particles, *, attributes_to_interpolate=None, particle_radius, rest_density=1000.0, smoothing_length, cube_size, iso_surface_threshold=0.6, aabb_min=None, aabb_max=None, multi_threading=True, simd=True, subdomain_grid=True, subdomain_grid_auto_disable=True, subdomain_num_cubes_per_dim=64, check_mesh_closed=False, check_mesh_manifold=False, check_mesh_orientation=False, check_mesh_debug=False, mesh_cleanup=False, mesh_cleanup_snap_dist=None, decimate_barnacles=False, keep_vertices=False, compute_normals=False, sph_normals=False, normals_smoothing_iters=None, mesh_smoothing_iters=None, mesh_smoothing_weights=True, mesh_smoothing_weights_normalization=13.0, generate_quads=False, quad_max_edge_diag_ratio=1.75, quad_max_normal_angle=10.0, quad_max_interior_angle=135.0, output_mesh_smoothing_weights=False, output_raw_normals=False, output_raw_mesh=False, mesh_aabb_min=None, mesh_aabb_max=None, mesh_aabb_clamp_vertices=True)

Runs the surface reconstruction pipeline for the given particle positions with optional post-processing

Note that smoothing length and cube size are given in multiples of the particle radius.

Parameters:

  • particles (numpy.ndarray) – A two-dimensional numpy array of shape (N, 3) containing the positions of the particles.

  • attributes_to_interpolate – Dictionary containing all attributes to interpolate. The keys are the attribute names and the values are the corresponding 1D/2D arrays. The arrays must have the same length as the number of particles. Supported array types are 2D float32/float64 arrays for vector attributes and 1D uint64/float32/float64 arrays for scalar attributes.

  • particle_radius – Particle radius.

  • rest_density – Rest density of the fluid.

  • smoothing_length – Smoothing length of the SPH kernel in multiples of the particle radius (compact support radius of SPH kernel will be twice the smoothing length).

  • cube_size – Size of the cubes (voxels) used for the marching cubes grid in multiples of the particle radius.

  • iso_surface_threshold – Threshold of the SPH interpolation of the “color field” where the iso surface should be extracted.

  • aabb_min – Lower corner [x,y,z] of the AABB of particles that are active in the reconstruction.

  • aabb_max – Upper corner [x,y,z] of the AABB of particles to consider in the reconstruction.

  • multi_threading – Flag to enable multi-threading for the reconstruction and post-processing steps.

  • simd – Flag to enable SIMD vectorization for the reconstruction if supported by the CPU architecture.

  • subdomain_grid – Flag to enable spatial decomposition by dividing the domain into subdomains with dense marching cube grids for efficient multi-threading.

  • subdomain_grid_auto_disable – Flag to automatically disable the subdomain grid if the global domain is too small.

  • subdomain_num_cubes_per_dim – Number of marching cubes voxels along each coordinate axis in each subdomain if the subdomain grid is enabled.

  • check_mesh_closed – Flag to enable checking the final mesh for holes.

  • check_mesh_manifold – Flag to enable checking the final mesh for non-manifold edges and vertices.

  • check_mesh_orientation – Flag to enable checking the final mesh for inverted triangles (compares angle between vertex normals and adjacent face normals).

  • check_mesh_debug – Flag to enable additional debug output for the check-mesh operations (has no effect if no other check-mesh option is enabled).

  • mesh_cleanup – Flag to enable marching cubes mesh cleanup. This implements the method from “Compact isocontours from sampled data” (Moore, Warren; 1992).

  • mesh_cleanup_snap_dist – If marching cubes mesh cleanup is enabled, this limits vertex snapping to the specified distance relative to the MC edge length (should be in range of [0.0,0.5]).

  • decimate_barnacles – Flag to perform barnacle decimation. For details see “Weighted Laplacian Smoothing for Surface Reconstruction of Particle-based Fluids” (Löschner, Böttcher, Jeske, Bender; 2023).

  • keep_vertices – Flag to retain any vertices without connectivity resulting from mesh cleanup or decimation step instead of filtering them out.

  • compute_normals – Flag to enable computation of vertex normals on the final mesh.

  • sph_normals – Flag to enable computation of normals using SPH interpolation (gradient of the color field) instead of geometry-based normals.

  • normals_smoothing_iters – Number of Laplacian smoothing iterations to perform on the normal field.

  • mesh_smoothing_iters – Number of Laplacian smoothing iterations to perform on the mesh vertices.

  • mesh_smoothing_weights – Flag to enable computation and usage of mesh smoothing weights according to “Weighted Laplacian Smoothing for Surface Reconstruction of Particle-based Fluids” (Löschner, Böttcher, Jeske, Bender; 2023).

  • mesh_smoothing_weights_normalization – Normalization value for the mesh smoothing weights.

  • generate_quads – Flag to enable conversion of triangles to quads depending on geometric criteria.

  • quad_max_edge_diag_ratio – Maximum allowed ratio of quad edge lengths to its diagonals to merge two triangles to a quad (inverse is used for minimum).

  • quad_max_normal_angle – Maximum allowed angle (in degrees) between triangle normals to merge them to a quad.

  • quad_max_interior_angle – Maximum allowed vertex interior angle (in degrees) inside a quad to merge two triangles to a quad.

  • output_mesh_smoothing_weights – Flag to attach and return the smoothing weights as a mesh attribute if smoothing weights are computed.

  • output_raw_normals – Flag to output the raw normals in addition to smoothed normals if smoothing of normals is enabled.

  • output_raw_mesh – Flag to return a copy of the raw mesh before any post-processing steps (inside the returned reconstruction object).

  • mesh_aabb_min – Lower corner [x,y,z] of the axis-aligned bounding box for the mesh, triangles fully outside this box will be removed.

  • mesh_aabb_max – Upper corner [x,y,z] of the axis-aligned bounding box for the mesh, triangles fully outside this box will be removed.

  • mesh_aabb_clamp_vertices – Flag to clamp the vertices of the mesh to the AABB in addition to removing triangles outside the AABB.