Add "Splashsurf Studio" Blender add-on

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

Author: w1th0utnam3

splashsurf_studio/README.md

@@ -0,0 +1,73 @@
+# Splashsurf Studio
+Splashsurf Studio is a Blender add-on for on-the-fly surface reconstruction of fluid simulation data. It leverages the `pySplashsurf` Python library, which is based on the [`splashsurf`](https://splashsurf.physics-simulation.org/) tool and library.
+
+The add-on interface can be found in the 3D Viewport toolbar (accessible via the `N` key) while in Object Mode.
+
+Splashsurf Studio interprets the vertex positions of any Blender object as particle coordinates to perform surface reconstruction using `pySplashsurf`.
+A common workflow involves loading particle data from SPH (Smoothed Particle Hydrodynamics) simulations using the [Sequence Loader add-on](https://extensions.blender.org/add-ons/sequence-loader/).
+As the Sequence Loader updates the input file on each frame change, Splashsurf Studio automatically refreshes the surface reconstruction to reflect the new data.
+
+### Note on Geometry Nodes
+
+Currently, the add-on cannot use geometry generated by Geometry Nodes as input for surface reconstruction due to Blender's execution order.
+Only base geometry or geometry loaded via tools like the Sequence Loader add-on is supported.
+However, the reconstructed surface itself can be used as an input for Geometry Nodes.
+If you are interested in contributing to improve the flexibility of the add-on, please contact us via our [GitHub repository](https://github.com/InteractiveComputerGraphics/splashsurf).
+
+If you want to use both, Geometry Nodes *and* Splashsurf, on the same input geometry (e.g. to render particles and surfaces in the same scene) it is recommended to create a separate object with a placeholder mesh (e.g. a cube) for Geometry Nodes.
+Inside the Geometry Nodes of this new object you can refer to the common input geometry object and ignore the placeholder geometry.
+
+## Basic Workflow
+Assuming you have already imported your particle data (e.g., using the [Sequence Loader add-on](https://extensions.blender.org/add-ons/sequence-loader/)), you can set up the surface reconstruction as follows:
+
+1. Select your particle data in the Outliner.  
+   ![](img/select_input.jpg)
+1. Click the "+" button in the "Select Input" panel to use the currently selected object's vertices for reconstruction.  
+   ![](img/register_input.jpg)
+2. Edit the reconstruction parameters in the "Viewport Settings" and "Render Settings" panels. 
+   Viewport settings are used when reconstructions are updated in the 3D Viewport, while render settings are applied to update reconstructions during rendering.
+   Typically, you would use a low-resolution reconstruction in the viewport for better performance and high-resolution settings for renders.
+1. Activate automatic reconstruction in the 'Select Input' panel to start the process.  
+   ![](img/addon_activate.jpg)
+
+The add-on will now reconstruct a surface from the input vertices and automatically update it on frame changes (e.g., when the input data changes via the [Sequence Loader add-on](https://extensions.blender.org/add-ons/sequence-loader/)).
+
+## Caching
+You can cache reconstructions for specific frames using the 'Cached Frames' panel.
+For frames added to the cache list, the surface reconstruction is performed once and then loaded from the cache when you switch to that frame.
+This allows you to quickly switch between specific frames to check camera and light settings, for example, without waiting for a new reconstruction.
+Changing reconstruction settings does not affect cached frames unless you manually regenerate them.
+
+![Cached Frames Panel](img/cached_frames.png)
+
+The "Cache Settings" property determines whether the viewport or render settings are used for the cache.
+
+Add frames to the cache by clicking the "+" button.
+This opens a window where you can input a string of frames to be cached: 
+
+![Add Frames Window](img/add_frames.png)
+
+This string adds frames 4, 10, 11, 12, 13, 14, 15, and 23 to the cache list.
+To remove frames, select them and click the "-" button, or use the "Clear Cache" operator to remove all frames.
+
+Reconstructions for newly added frames are generated the next time the frame is changed.
+All cached reconstructions can be updated manually using the "Regenerate Cache" button.
+
+## Other Operators
+- **Parse CLI String**: Extracts parameters from a `splashsurf` CLI command (e.g., `splashsurf reconstruct input_{}.vtk -r=0.025 ...`).
+- **Get CLI String**: Performs the reverse operation, creating a CLI option string from the selected parameters and printing it to the Blender console.
+- **Test Render Params**: Runs the surface reconstruction using the render settings without modifying the mesh. It outputs the reconstruction time, vertex and triangle counts, and approximate memory usage.
+
+## Notes
+ - When using the [Sequence Loader add-on](https://extensions.blender.org/add-ons/sequence-loader/), Splashsurf Studio requires the particle data object's global visibility to be enabled. However, it can be hidden in the viewport (by clicking the eye icon in the Outliner) without issues.
+ - By default, a `COPY_TRANSFORMS` constraint is added to the surface reconstruction, matching its transform to the particle data. This prevents the surface from being moved independently. If this is not desired, simply remove the constraint.
+ - If an error occurs during surface reconstruction, it will be displayed in a dedicated error panel:  
+    ![Error log panel](img/error_log.png)
+ - The add-on automatically enables `Render > Lock Interface` to prevent crashes during rendering.
+
+## Acknowledgements
+
+This add-on contains notable contributions from the following people:
+ - [Felix Kern](https://github.com/Fek04) ([@Fek04](https://github.com/Fek04)) contributed the initial implementation of the Blender add-on and the `pySplashsurf` bindings
+ - [Fabian Löschner](https://www.floeschner.de/) ([@w1th0utnam3](https://github.com/w1th0utnam3)) is the main author of `splashsurf` itself and current maintainer of the extension and Python bindings
+

splashsurf_studio/__init__.py

@@ -0,0 +1,81 @@
+import bpy
+from .handlers import generate_mesh, toggle_rendering_off, toggle_rendering_on, ensure_frame_change_handlers
+from .properties import *
+from .operators import *
+from .panels import *
+from .updater import cached_meshes
+
+classes = [
+    SPSF_Frame_Properties,
+    SPSF_Data_Obj_Properties,
+    SPSF_Attribute_Properties,
+    SPSF_Error_Message_Properties,
+    SPSF_Reconstruction_Properties,
+    SPSF_Scene_Properties,
+    SPSF_OT_Activate,
+    SPSF_OT_Deactivate,
+    SPSF_OT_Copy_To_Render,
+    SPSF_OT_Copy_To_Viewport,
+    SPSF_OT_Get_CLI_String,
+    SPSF_OT_Parse_CLI_Args,
+    SPSF_OT_Register,
+    SPSF_OT_Unregister,
+    SPSF_OT_Test_Render_Params,
+    SPSF_OT_Clear_Errors,
+    SPSF_OT_Show_Error,
+    SPSF_OT_Add_Frames,
+    SPSF_OT_Remove_Frame,
+    SPSF_OT_Clear_Cache,
+    SPSF_OT_Regenerate_Cache,
+    SPSF_OT_Jump_To_Frame,
+    SPSF_UL_Attribute_List,
+    SPSF_UL_Data_Object_List,
+    SPSF_UL_Error_List,
+    SPSF_Selection_Panel,
+    SPSF_UL_Frame_List,
+    SPSF_Caching_Panel,
+    SPSF_Error_Log_Panel,
+    SPSF_Viewport_Settings_Panel,
+    SPSF_Viewport_Attributes_Panel,
+    SPSF_Viewport_Params_Panel,
+    SPSF_Render_Settings_Panel,
+    SPSF_Render_Attributes_Panel,
+    SPSF_Render_Params_Panel
+]
+
+def register():
+    for cls in classes:
+        bpy.utils.register_class(cls)
+    
+    bpy.types.Object.viewport_reconstruction_properties = bpy.props.PointerProperty(type=SPSF_Reconstruction_Properties)
+    bpy.types.Object.render_reconstruction_properties = bpy.props.PointerProperty(type=SPSF_Reconstruction_Properties)
+    bpy.types.Scene.splashsurf_studio = bpy.props.PointerProperty(type=SPSF_Scene_Properties)
+    bpy.types.Mesh.cached = bpy.props.BoolProperty(default=False)
+    
+    bpy.app.handlers.load_post.append(ensure_frame_change_handlers)
+
+    # Run once to ensure handlers are added when script is reloaded
+    ensure_frame_change_handlers(None)
+    
+def unregister():
+    for cls in classes:
+        bpy.utils.unregister_class(cls)
+    
+    bpy.app.handlers.load_post.remove(ensure_frame_change_handlers)
+    
+    if generate_mesh in bpy.app.handlers.frame_change_post:
+        bpy.app.handlers.frame_change_post.remove(generate_mesh)
+    if toggle_rendering_on in bpy.app.handlers.render_init:
+        bpy.app.handlers.render_init.remove(toggle_rendering_on)
+    if toggle_rendering_off in bpy.app.handlers.render_complete:
+        bpy.app.handlers.render_complete.remove(toggle_rendering_off)
+    if toggle_rendering_off in bpy.app.handlers.render_cancel:
+        bpy.app.handlers.render_cancel.remove(toggle_rendering_off)
+    
+    del bpy.types.Object.viewport_reconstruction_properties
+    del bpy.types.Object.render_reconstruction_properties
+    del bpy.types.Scene.splashsurf_studio
+    del bpy.types.Mesh.cached
+
+    # Unload cached meshes, only relevant if addon is reloaded
+    clear_cache(cached_meshes)

splashsurf_studio/blender_manifest.toml

@@ -0,0 +1,75 @@
+schema_version = "1.0.0"
+
+# Example of manifest file for a Blender extension
+# Change the values according to your extension
+id = "splashsurf_studio"
+version = "1.0.0"
+name = "Splashsurf Studio"
+tagline = "Surface reconstruction for particle-based fluid simulations"
+maintainer = "Fabian Löschner"
+# Supported types: "add-on", "theme"
+type = "add-on"
+
+# Optional link to documentation, support, source files, etc
+website = "https://splashsurf.physics-simulation.org/"
+
+# Optional list defined by Blender and server, see:
+# https://docs.blender.org/manual/en/dev/advanced/extensions/tags.html
+tags = ["Add Mesh", "Mesh", "Object"]
+
+blender_version_min = "4.5.0"
+# # Optional: Blender version that the extension does not support, earlier versions are supported.
+# # This can be omitted and defined later on the extensions platform if an issue is found.
+# blender_version_max = "5.1.0"
+
+# License conforming to https://spdx.org/licenses/ (use "SPDX: prefix)
+# https://docs.blender.org/manual/en/dev/advanced/extensions/licenses.html
+license = [
+  "SPDX:GPL-3.0-or-later",
+]
+# Optional: required by some licenses.
+# copyright = [
+#   "2002-2024 Developer Name",
+#   "1998 Company Name",
+# ]
+
+# Optional list of supported platforms. If omitted, the extension will be available in all operating systems.
+platforms = ["windows-x64", "macos-arm64", "linux-x64", "windows-arm64", "macos-x64"]
+
+# Optional: bundle 3rd party Python modules.
+# https://docs.blender.org/manual/en/dev/advanced/extensions/python_wheels.html
+wheels = [
+  "./wheels/pysplashsurf-0.14.0.0-cp310-abi3-macosx_14_0_arm64.whl",
+  "./wheels/pysplashsurf-0.14.0.0-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl",
+  "./wheels/pysplashsurf-0.14.0.0-cp310-abi3-win_amd64.whl",
+  "./wheels/pysplashsurf-0.14.0.0-cp310-abi3-win_arm64.whl",
+  "./wheels/pysplashsurf-0.14.0.0-cp310-abi3-macosx_13_0_x86_64.whl"
+]
+
+# Optional: add-ons can list which resources they will require:
+# * files (for access of any filesystem operations)
+# * network (for internet access)
+# * clipboard (to read and/or write the system clipboard)
+# * camera (to capture photos and videos)
+# * microphone (to capture audio)
+#
+# If using network, remember to also check `bpy.app.online_access`
+# https://docs.blender.org/manual/en/dev/advanced/extensions/addons.html#internet-access
+#
+# For each permission it is important to also specify the reason why it is required.
+# Keep this a single short sentence without a period (.) at the end.
+# For longer explanations use the documentation or detail page.
+#
+# [permissions]
+# network = "Need to sync motion-capture data to server"
+# files = "Import/export FBX from/to disk"
+# clipboard = "Copy and paste bone transforms"
+
+# Optional: build settings.
+# https://docs.blender.org/manual/en/dev/advanced/extensions/command_line_arguments.html#command-line-args-extension-build
+# [build]
+# paths_exclude_pattern = [
+#   "__pycache__/",
+#   "/.git/",
+#   "/*.zip",
+# ]

splashsurf_studio/handlers.py

@@ -0,0 +1,106 @@
+import bpy
+from bpy.app.handlers import persistent
+
+from .utils import get_selected_data_object
+from .updater import update_entries, update_reconstruction, cached_meshes
+
+def generate_mesh(scene):
+    if not scene.splashsurf_studio.active:
+        return
+    
+    update_entries(scene)
+
+def toggle_rendering_on(scene):
+    scene.splashsurf_studio.rendering = True
+
+def toggle_rendering_off(scene):
+    scene.splashsurf_studio.rendering = False
+
+@persistent
+def ensure_frame_change_handlers(_):
+    if generate_mesh not in bpy.app.handlers.frame_change_post:
+        bpy.app.handlers.frame_change_post.append(generate_mesh)
+    if toggle_rendering_on not in bpy.app.handlers.render_init:
+        bpy.app.handlers.render_init.append(toggle_rendering_on)
+    if toggle_rendering_off not in bpy.app.handlers.render_complete:
+        bpy.app.handlers.render_complete.append(toggle_rendering_off)
+    if toggle_rendering_off not in bpy.app.handlers.render_cancel:
+        bpy.app.handlers.render_cancel.append(toggle_rendering_off)
+
+def property_callback(self, context):
+    if context.scene.splashsurf_studio.update_on_change and context.scene.splashsurf_studio.active:
+        obj = get_selected_data_object(context)
+        scene = context.scene
+        frame = scene.frame_current
+        
+        cache_frame = False
+        for part in scene.splashsurf_studio.cached_frames:
+            if frame == part.frame:
+                cache_frame = True
+                break
+        
+        # Only regenerate if edited property would get used for current reconstruction
+        if cache_frame:
+            if scene.splashsurf_studio.cache_settings != self.type:
+                return
+        elif (scene.splashsurf_studio.use_render_for_viewport and self.type == 'VIEWPORT') or (not scene.splashsurf_studio.use_render_for_viewport and self.type == 'RENDER'):
+            return
+        
+        # Find the corresponding data object entry
+        for entry in scene.splashsurf_studio.data_objs:
+            if entry.data_pointer == obj:
+                
+                # Use correct reconstruction properties
+                use_render_props = scene.splashsurf_studio.use_render_for_viewport or scene.splashsurf_studio.rendering
+                if cache_frame:
+                    match scene.splashsurf_studio.cache_settings:
+                        case 'VIEWPORT':
+                            use_render_props = False
+                        case 'RENDER':
+                            use_render_props = True
+                    
+                    # Set cached flag to false so that update_reconstruction reuses the mesh data object
+                    if entry.surface_pointer is not None and entry.surface_pointer.data.cached:
+                        entry.surface_pointer.data.cached = False
+                
+                update_reconstruction(scene, entry, use_render_props)
+                
+                if cache_frame:
+                    if frame not in cached_meshes:
+                        cached_meshes[frame] = {}
+                    
+                    entry.surface_pointer.data.cached = True
+                    cached_meshes[frame][entry.data_pointer] = entry.surface_pointer.data
+                
+                break
+
+# Callback to update the reconstruction once when the "Update on Change" property is turned on
+def update_callback(_, context):
+    # Call property callback for both reconstruction properties, property_callback will abort for the not used type
+    property_callback(get_selected_data_object(context).viewport_reconstruction_properties, context)
+    property_callback(get_selected_data_object(context).render_reconstruction_properties, context)
+    
+def update_copy_transforms_constraints(self, context):
+    if self.match_transforms:
+        # Add constraint to all data objects
+        for entry in context.scene.splashsurf_studio.data_objs:
+            if entry.surface_pointer is not None:
+                # Check if constraint already exists
+                exists = False
+                for constraint in entry.surface_pointer.constraints:
+                    if constraint.type == 'COPY_TRANSFORMS' and constraint.target == entry.data_pointer:
+                        exists = True
+                        break
+                
+                if not exists:
+                    constraint = entry.surface_pointer.constraints.new(type='COPY_TRANSFORMS')
+                    constraint.target = entry.data_pointer     
+    else:
+        # Remove constraints from all data objects
+        for entry in context.scene.splashsurf_studio.data_objs:
+            if entry.surface_pointer is not None:
+                for constraint in entry.surface_pointer.constraints:
+                    if constraint.type == 'COPY_TRANSFORMS' and constraint.target == entry.data_pointer:
+                        entry.surface_pointer.constraints.remove(constraint)
+                        break
+