Add the reconstruct pipeline to public API (#226)

* Refactored pipeline to use a method that does not work with I/O directly

* Merge rebase conflict

* New pipeline method now only takes reference to the particle positions

* cargo fmt

* Added references to the rust documentation for the python classes

* Renamed public pipeline method

* ReconstructionRunnerPostprocessingArgs struct docstrings

* Made return type of public pipeline method its own struct

* Rename reconstruction module to reconstruct

* Small refactoring

* Update pysplashsurf_CI.yml

---------

Co-authored-by: Felix Kern <[email protected]>

Author: w1th0utnam3

.github/workflows/pysplashsurf_CI.yml

@@ -1,12 +1,10 @@
-# This file is autogenerated by maturin v1.8.2
-# To update, run
-#
-#    maturin generate-ci github
-#
 name: Python bindings
 
 on:
   push:
+    branches: [main]
+  pull_request:
+    branches: [main]
   workflow_dispatch:
   release:
     types: [published]

pysplashsurf/pysplashsurf/__init__.py

@@ -523,11 +523,15 @@ def convert_tris_to_quads(
 def reconstruction_pipeline(
     particles, *, attributes_to_interpolate={}, particle_radius,
     rest_density=1000.0, smoothing_length=2.0, cube_size,
-    iso_surface_threshold=0.6, enable_multi_threading=True, mesh_smoothing_weights=False, sph_normals=False, 
+    iso_surface_threshold=0.6, enable_multi_threading=True,
+    check_mesh_closed=False, check_mesh_manifold=False,
+    check_mesh_orientation=False, check_mesh_debug=False,
+    mesh_smoothing_weights=False, sph_normals=False,
     mesh_smoothing_weights_normalization=13.0, mesh_smoothing_iters=None, normals_smoothing_iters=None,
-    mesh_cleanup=False, decimate_barnacles=False, keep_vertices=False,
-    compute_normals=False, output_raw_normals=False, output_mesh_smoothing_weights=False, mesh_aabb_clamp_vertices=False,
-    subdomain_grid=True, subdomain_num_cubes_per_dim=64, aabb_min=None, aabb_max=None, mesh_aabb_min=None, mesh_aabb_max=None
+    mesh_cleanup=False, mesh_cleanup_snap_dist=None, decimate_barnacles=False, keep_vertices=False,
+    compute_normals=False, output_raw_normals=False, output_raw_mesh=False, output_mesh_smoothing_weights=False, mesh_aabb_clamp_vertices=False,
+    subdomain_grid=True, subdomain_num_cubes_per_dim=64, aabb_min=None, aabb_max=None, mesh_aabb_min=None, mesh_aabb_max=None,
+    generate_quads=False, quad_max_edge_diag_ratio=1.75, quad_max_normal_angle=10.0, quad_max_interior_angle=135.0
 ):
     """Surface reconstruction based on particle positions with subsequent post-processing
     
@@ -558,6 +562,18 @@ def reconstruction_pipeline(
         
     enable_multi_threading: bool
         Multi-threading flag
+        
+    check_mesh_closed: bool
+        Enable checking the final mesh for holes
+        
+    check_mesh_manifold: bool
+        Enable checking the final mesh for non-manifold edges and vertices
+    
+    check_mesh_orientation: bool
+        Enable checking the final mesh for inverted triangles (compares angle between vertex normals and adjacent face normals)
+    
+    check_mesh_debug: bool
+        Enable additional debug output for the check-mesh operations (has no effect if no other check-mesh option is enabled)
 
     sph_normals: bool
         Flag to compute normals using SPH interpolation instead of geometry-based normals.
@@ -578,6 +594,9 @@ def reconstruction_pipeline(
     mesh_cleanup: bool
         Flag to perform mesh cleanup\n
         This implements the method from “Compact isocontours from sampled data” (Moore, Warren; 1992)
+
+    mesh_cleanup_snap_dist: float
+        If MC mesh cleanup is enabled, vertex snapping can be limited to this distance relative to the MC edge length (should be in range of [0.0,0.5])
         
     decimate_barnacles: bool
         Flag to perform barnacle decimation\n
@@ -590,11 +609,14 @@ def reconstruction_pipeline(
         Flag to compute normals\n
         If set to True, the normals will be computed and stored in the mesh.
     
+    output_mesh_smoothing_weights: bool
+        Flag to store the mesh smoothing weights if smoothing weights are computed.
+    
     output_raw_normals: bool
         Flag to output the raw normals in addition to smoothed normals if smoothing of normals is enabled
     
-    output_mesh_smoothing_weights: bool
-        Flag to store the mesh smoothing weights if smoothing weights are computed.
+    output_raw_mesh: bool
+        When true, also return the SurfaceReconstruction object with no post-processing applied
     
     mesh_aabb_clamp_vertices: bool
         Flag to clamp the vertices of the mesh to the AABB
@@ -616,29 +638,58 @@ def reconstruction_pipeline(
         
     mesh_aabb_max: np.ndarray
         Largest corner of the axis-aligned bounding box for the mesh
+    
+    generate_quads: bool
+        Enable trying to convert triangles to quads if they meet quality criteria
+        
+    quad_max_edge_diag_ratio: float
+        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: float
+        Maximum allowed angle (in degrees) between triangle normals to merge them to a quad
+    
+    quad_max_interior_angle: float
+        Maximum allowed vertex interior angle (in degrees) inside a quad to merge two triangles to a quad
         
     Returns
     -------
-    tuple[TriMeshWithDataF32 | TriMeshWithDataF64, SurfaceReconstructionF32 | SurfaceReconstructionF64]
+    tuple[TriMeshWithDataF32 | TriMeshWithDataF64 | MixedTriQuadMeshWithDataF32 | MixedTriQuadMeshWithDataF64, Optional[SurfaceReconstructionF32] | Optional[SurfaceReconstructionF64]]
         Mesh with data object and SurfaceReconstruction object containing the reconstructed mesh and used grid
     """
     if particles.dtype == 'float32':
-        return reconstruction_pipeline_f32(particles, attributes_to_interpolate=attributes_to_interpolate, particle_radius=particle_radius, rest_density=rest_density, 
-                                smoothing_length=smoothing_length, cube_size=cube_size, iso_surface_threshold=iso_surface_threshold, 
-                                aabb_min=aabb_min, aabb_max=aabb_max, enable_multi_threading=enable_multi_threading, 
-                                use_custom_grid_decomposition=subdomain_grid, subdomain_num_cubes_per_dim=subdomain_num_cubes_per_dim,
-                                global_neighborhood_list=False, mesh_cleanup=mesh_cleanup, decimate_barnacles=decimate_barnacles,
-                                keep_vertices=keep_vertices, compute_normals=compute_normals, sph_normals=sph_normals, normals_smoothing_iters=normals_smoothing_iters,
-                                mesh_smoothing_iters=mesh_smoothing_iters, mesh_smoothing_weights=mesh_smoothing_weights, mesh_smoothing_weights_normalization=mesh_smoothing_weights_normalization,
-                                output_mesh_smoothing_weights=output_mesh_smoothing_weights, output_raw_normals=output_raw_normals, mesh_aabb_min=mesh_aabb_min, mesh_aabb_max=mesh_aabb_max, mesh_aabb_clamp_vertices=mesh_aabb_clamp_vertices)   
+        tri_mesh, tri_quad_mesh, reconstruction = reconstruction_pipeline_f32(particles, attributes_to_interpolate=attributes_to_interpolate, particle_radius=particle_radius, rest_density=rest_density, 
+                                                                              smoothing_length=smoothing_length, cube_size=cube_size, iso_surface_threshold=iso_surface_threshold, 
+                                                                              aabb_min=aabb_min, aabb_max=aabb_max, enable_multi_threading=enable_multi_threading, 
+                                                                              use_custom_grid_decomposition=subdomain_grid, subdomain_num_cubes_per_dim=subdomain_num_cubes_per_dim,
+                                                                              check_mesh_closed=check_mesh_closed, check_mesh_manifold=check_mesh_manifold, check_mesh_orientation=check_mesh_orientation, check_mesh_debug=check_mesh_debug,
+                                                                              mesh_cleanup=mesh_cleanup, max_rel_snap_dist=mesh_cleanup_snap_dist, decimate_barnacles=decimate_barnacles,
+                                                                              keep_vertices=keep_vertices, compute_normals=compute_normals, sph_normals=sph_normals, normals_smoothing_iters=normals_smoothing_iters,
+                                                                              mesh_smoothing_iters=mesh_smoothing_iters, mesh_smoothing_weights=mesh_smoothing_weights, mesh_smoothing_weights_normalization=mesh_smoothing_weights_normalization,
+                                                                              output_mesh_smoothing_weights=output_mesh_smoothing_weights, output_raw_normals=output_raw_normals, output_raw_mesh=output_raw_mesh,
+                                                                              mesh_aabb_min=mesh_aabb_min, mesh_aabb_max=mesh_aabb_max, mesh_aabb_clamp_vertices=mesh_aabb_clamp_vertices,
+                                                                              generate_quads=generate_quads, quad_max_edge_diag_ratio=quad_max_edge_diag_ratio, quad_max_normal_angle=quad_max_normal_angle, quad_max_interior_angle=quad_max_interior_angle)  
+        
+        if tri_mesh == None:
+            return (tri_quad_mesh, reconstruction)
+        else:
+            return (tri_mesh, reconstruction)
+        
     elif particles.dtype == 'float64':
-        return reconstruction_pipeline_f64(particles, attributes_to_interpolate=attributes_to_interpolate, particle_radius=particle_radius, rest_density=rest_density, 
-                                smoothing_length=smoothing_length, cube_size=cube_size, iso_surface_threshold=iso_surface_threshold, 
-                                aabb_min=aabb_min, aabb_max=aabb_max, enable_multi_threading=enable_multi_threading, 
-                                use_custom_grid_decomposition=subdomain_grid, subdomain_num_cubes_per_dim=subdomain_num_cubes_per_dim,
-                                global_neighborhood_list=False, mesh_cleanup=mesh_cleanup, decimate_barnacles=decimate_barnacles,
-                                keep_vertices=keep_vertices, compute_normals=compute_normals, sph_normals=sph_normals, normals_smoothing_iters=normals_smoothing_iters,
-                                mesh_smoothing_iters=mesh_smoothing_iters, mesh_smoothing_weights=mesh_smoothing_weights, mesh_smoothing_weights_normalization=mesh_smoothing_weights_normalization,
-                                output_mesh_smoothing_weights=output_mesh_smoothing_weights, output_raw_normals=output_raw_normals, mesh_aabb_min=mesh_aabb_min, mesh_aabb_max=mesh_aabb_max, mesh_aabb_clamp_vertices=mesh_aabb_clamp_vertices)   
+        tri_mesh, tri_quad_mesh, reconstruction = reconstruction_pipeline_f64(particles, attributes_to_interpolate=attributes_to_interpolate, particle_radius=particle_radius, rest_density=rest_density,
+                                                                              smoothing_length=smoothing_length, cube_size=cube_size, iso_surface_threshold=iso_surface_threshold,
+                                                                              aabb_min=aabb_min, aabb_max=aabb_max, enable_multi_threading=enable_multi_threading,
+                                                                              use_custom_grid_decomposition=subdomain_grid, subdomain_num_cubes_per_dim=subdomain_num_cubes_per_dim,
+                                                                              check_mesh_closed=check_mesh_closed, check_mesh_manifold=check_mesh_manifold, check_mesh_orientation=check_mesh_orientation, check_mesh_debug=check_mesh_debug,
+                                                                              mesh_cleanup=mesh_cleanup, max_rel_snap_dist=mesh_cleanup_snap_dist, decimate_barnacles=decimate_barnacles,
+                                                                              keep_vertices=keep_vertices, compute_normals=compute_normals, sph_normals=sph_normals, normals_smoothing_iters=normals_smoothing_iters,
+                                                                              mesh_smoothing_iters=mesh_smoothing_iters, mesh_smoothing_weights=mesh_smoothing_weights, mesh_smoothing_weights_normalization=mesh_smoothing_weights_normalization,
+                                                                              output_mesh_smoothing_weights=output_mesh_smoothing_weights, output_raw_normals=output_raw_normals, output_raw_mesh=output_raw_mesh,
+                                                                              mesh_aabb_min=mesh_aabb_min, mesh_aabb_max=mesh_aabb_max, mesh_aabb_clamp_vertices=mesh_aabb_clamp_vertices,
+                                                                              generate_quads=generate_quads, quad_max_edge_diag_ratio=quad_max_edge_diag_ratio, quad_max_normal_angle=quad_max_normal_angle, quad_max_interior_angle=quad_max_interior_angle)
+
+        if tri_mesh == None:
+            return (tri_quad_mesh, reconstruction)
+        else:
+            return (tri_mesh, reconstruction)
     else:
         raise ValueError("Invalid data type (only float32 and float64 are supported, consider explicitly specifying the dtype for particles)")

pysplashsurf/pysplashsurf/docs/source/classes.rst

@@ -1,24 +1,42 @@
 Classes
 =======
 
-Additionally, there exists a F64 version for every class which is otherwise identical to the F32 version.
+Additionally to the classes on this page, there exists a F64 version for every class which is otherwise identical to the F32 version.
+
+For more information on the classes, refer to the `Rust documentation <https://docs.rs/splashsurf_lib/latest/splashsurf_lib/index.html>`_ of splashsurf_lib.
 
 .. currentmodule:: pysplashsurf
 
 .. autoclass:: Aabb3dF32
 
+    See `Aabb3d <https://docs.rs/splashsurf_lib/latest/splashsurf_lib/type.Aabb3d.html>`_ for more information.
+
 .. autoclass:: MixedTriQuadMesh3dF32
 
+    See `MixedTriQuadMesh3d <https://docs.rs/splashsurf_lib/latest/splashsurf_lib/mesh/struct.MixedTriQuadMesh3d.html>`_ for more information.
+
 .. autoclass:: MixedTriQuadMeshWithDataF32
     :exclude-members: push_point_attribute_scalar_u64, push_point_attribute_scalar_real, push_point_attribute_vector_real, push_cell_attribute_scalar_real, push_cell_attribute_scalar_u64, push_cell_attribute_vector_real
 
+    See `MeshWithData <https://docs.rs/splashsurf_lib/latest/splashsurf_lib/mesh/struct.MeshWithData.html>`_ for more information.
+
 .. autoclass:: SphInterpolatorF32
 
+    See `SphInterpolator <https://docs.rs/splashsurf_lib/latest/splashsurf_lib/sph_interpolation/struct.SphInterpolator.html>`_ for more information.
+
 .. autoclass:: SurfaceReconstructionF32
 
+    See `SurfaceReconstruction <https://docs.rs/splashsurf_lib/latest/splashsurf_lib/struct.SurfaceReconstruction.html>`_ for more information.
+
 .. autoclass:: TriMesh3dF32
 
+    See `TriMesh3d <https://docs.rs/splashsurf_lib/latest/splashsurf_lib/mesh/struct.TriMesh3d.html>`_ for more information.
+
 .. autoclass:: TriMeshWithDataF32
     :exclude-members: push_point_attribute_scalar_u64, push_point_attribute_scalar_real, push_point_attribute_vector_real, push_cell_attribute_scalar_real, push_cell_attribute_scalar_u64, push_cell_attribute_vector_real
 
-.. autoclass:: UniformGridF32
+    See `MeshWithData <https://docs.rs/splashsurf_lib/latest/splashsurf_lib/mesh/struct.MeshWithData.html>`_ for more information.
+
+.. autoclass:: UniformGridF32
+
+    See `UniformGrid <https://docs.rs/splashsurf_lib/latest/splashsurf_lib/uniform_grid/type.UniformGrid.html>`_ for more information.