# pySplashsurf
pySplashsurf provides Python bindings for `splashsurf`, an open source surface reconstruction library for particle data from SPH simulations.
Detailed information on the surface reconstruction and library itself and its API can be found on the [project website (splashsurf.physics-simulation.org)](https://splashsurf.physics-simulation.org/) or the [main repository](https://github.com/InteractiveComputerGraphics/splashsurf).
## Installation
Requires Python version 3.7+
```
pip install pysplashsurf
```
To install pysplashsurf with meshio support (which adds some additional IO functionality), use
```
pip install pysplashsurf[meshio]
```
This will add support for the `.bgeo` file extension to meshio, so that particle data in the `BGEOV` format can be read using meshio.
Meshio is also required for the `write_to_file` method from the bindings to work.
The rest of the package, including the CLI, will still work even if meshio is not installed.
## Usage
pySplashsurf can either be used as a library in Python scripts or as a command line tool that provides the same interface as the original Rust [`splashsurf`](https://github.com/InteractiveComputerGraphics/splashsurf) CLI itself.
### CLI
To use the CLI, you can use the `pysplashsurf` command after installing the package:
```bash
pysplashsurf --help
```
For example, to reconstruct a surface from particle data in a VTK file with some smoothing:
```bash
splashsurf reconstruct particles.vtk -r=0.025 -l=2.0 -c=0.5 -t=0.6 --mesh-smoothing-weights=on --mesh-smoothing-iters=15 --normals=on --normals-smoothing-iters=10
```
For more information on the CLI and its arguments, refer to the [splashsurf documentation](https://github.com/InteractiveComputerGraphics/splashsurf).
### Library
Example to reconstruct the surface from an input file, apply some post-processing methods and write the data back to a file:
```python
import meshio
import numpy as np
import pysplashsurf
mesh = meshio.read("input.vtk")
particles = np.array(mesh.points, dtype=np.float64)
mesh_with_data, reconstruction = pysplashsurf.reconstruction_pipeline(
particles,
particle_radius=0.025,
rest_density=1000.0,
smoothing_length=2.0,
cube_size=0.5,
iso_surface_threshold=0.6,
mesh_smoothing_weights=True,
mesh_smoothing_weights_normalization=13.0,
mesh_smoothing_iters=25,
normals_smoothing_iters=10,
mesh_cleanup=True,
compute_normals=True,
subdomain_grid=True,
subdomain_num_cubes_per_dim=64,
output_mesh_smoothing_weights=True
)
pysplashsurf.write_to_file(mesh_with_data, "output.vtk")
```
The `reconstruction_pipeline` method provides (mostly) the same arguments as the splashsurf binary CLI.
It may be necessary to specify the `dtype` of a function input (as done for `particles` in the example) so that the bindings know what data type to use internally.
The extension supports single (`np.float32`) and double precision floats (`np.float64`).
## Build instructions
You can also manually build the package from the source code:
1. Clone the repository
2. cd to the `pysplashsurf` directory
3. Create an environment from `python_environment.yaml` and activate it
- I recommend creating it in a subfolder, e.g.
```conda env create --prefix ./env -f python_environment.yaml```
- Then activate it using `conda activate ./env`
4. Now, to build the project, use maturin: `maturin develop`
- Maturin automatically installs the resulting binary in your python environment
- Set the release flag `-r` or `--release` to build an optimized binary, however, compilation time will be slightly longer
### Documentation Build
To generate the Sphinx documentation, make sure that the package is installed through, e.g., maturin, and then run `make html` in the `pysplashsurf/pysplashsurf/docs` directory.
The resulting HTML files will be in `pysplashsurf/pysplashsurf/docs/build/html`.
### Stub File Generation
To automatically generate a stub file for the package, run `cargo run --bin stub_gen` from the root project folder (from `pysplashsurf/`).
Raw data
{
"_id": null,
"home_page": null,
"name": "pysplashsurf",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "surface reconstruction, marching cubes, sph, fluid, particles, mesh, splashsurf, splishsplash",
"author": "Interactive Computer Graphics, Fabian L\u00f6schner",
"author_email": null,
"download_url": null,
"platform": null,
"description": "# pySplashsurf\n\n![splashsurf logo](https://raw.githubusercontent.com/InteractiveComputerGraphics/splashsurf/main/logos/logo_small.svg \"splashsurf\")\n\npySplashsurf provides Python bindings for `splashsurf`, an open source surface reconstruction library for particle data from SPH simulations.\nDetailed information on the surface reconstruction and library itself and its API can be found on the [project website (splashsurf.physics-simulation.org)](https://splashsurf.physics-simulation.org/) or the [main repository](https://github.com/InteractiveComputerGraphics/splashsurf).\n\n## Installation\nRequires Python version 3.7+\n```\npip install pysplashsurf\n```\n\nTo install pysplashsurf with meshio support (which adds some additional IO functionality), use\n```\npip install pysplashsurf[meshio]\n```\nThis will add support for the `.bgeo` file extension to meshio, so that particle data in the `BGEOV` format can be read using meshio.\nMeshio is also required for the `write_to_file` method from the bindings to work.\nThe rest of the package, including the CLI, will still work even if meshio is not installed.\n\n## Usage\npySplashsurf can either be used as a library in Python scripts or as a command line tool that provides the same interface as the original Rust [`splashsurf`](https://github.com/InteractiveComputerGraphics/splashsurf) CLI itself.\n\n### CLI\nTo use the CLI, you can use the `pysplashsurf` command after installing the package:\n```bash\npysplashsurf --help\n```\nFor example, to reconstruct a surface from particle data in a VTK file with some smoothing:\n```bash\nsplashsurf reconstruct particles.vtk -r=0.025 -l=2.0 -c=0.5 -t=0.6 --mesh-smoothing-weights=on --mesh-smoothing-iters=15 --normals=on --normals-smoothing-iters=10\n```\n\nFor more information on the CLI and its arguments, refer to the [splashsurf documentation](https://github.com/InteractiveComputerGraphics/splashsurf).\n\n### Library\nExample to reconstruct the surface from an input file, apply some post-processing methods and write the data back to a file:\n```python\nimport meshio\nimport numpy as np\nimport pysplashsurf\n\nmesh = meshio.read(\"input.vtk\")\nparticles = np.array(mesh.points, dtype=np.float64)\n\nmesh_with_data, reconstruction = pysplashsurf.reconstruction_pipeline(\n particles,\n particle_radius=0.025,\n rest_density=1000.0,\n smoothing_length=2.0,\n cube_size=0.5,\n iso_surface_threshold=0.6,\n mesh_smoothing_weights=True,\n mesh_smoothing_weights_normalization=13.0,\n mesh_smoothing_iters=25,\n normals_smoothing_iters=10,\n mesh_cleanup=True,\n compute_normals=True,\n subdomain_grid=True,\n subdomain_num_cubes_per_dim=64,\n output_mesh_smoothing_weights=True\n)\n \npysplashsurf.write_to_file(mesh_with_data, \"output.vtk\")\n```\nThe `reconstruction_pipeline` method provides (mostly) the same arguments as the splashsurf binary CLI.\nIt may be necessary to specify the `dtype` of a function input (as done for `particles` in the example) so that the bindings know what data type to use internally.\nThe extension supports single (`np.float32`) and double precision floats (`np.float64`).\n\n## Build instructions\nYou can also manually build the package from the source code:\n1. Clone the repository\n2. cd to the `pysplashsurf` directory\n3. Create an environment from `python_environment.yaml` and activate it\n - I recommend creating it in a subfolder, e.g.\n ```conda env create --prefix ./env -f python_environment.yaml```\n - Then activate it using `conda activate ./env`\n4. Now, to build the project, use maturin: `maturin develop`\n - Maturin automatically installs the resulting binary in your python environment\n - Set the release flag `-r` or `--release` to build an optimized binary, however, compilation time will be slightly longer\n\n### Documentation Build\nTo generate the Sphinx documentation, make sure that the package is installed through, e.g., maturin, and then run `make html` in the `pysplashsurf/pysplashsurf/docs` directory.\nThe resulting HTML files will be in `pysplashsurf/pysplashsurf/docs/build/html`.\n\n### Stub File Generation\nTo automatically generate a stub file for the package, run `cargo run --bin stub_gen` from the root project folder (from `pysplashsurf/`).\n\n",
"bugtrack_url": null,
"license": null,
"summary": "Python bindings for splashsurf, a surface reconstruction library for SPH simulations.",
"version": "0.12.0.2",
"project_urls": {
"Documentation": "https://pysplashsurf.readthedocs.io/",
"Homepage": "https://splashsurf.physics-simulation.org/",
"Repository": "https://github.com/InteractiveComputerGraphics/splashsurf.git"
},
"split_keywords": [
"surface reconstruction",
" marching cubes",
" sph",
" fluid",
" particles",
" mesh",
" splashsurf",
" splishsplash"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "464aa424a5cfa38fc8dfa4cfc9e5485e5a7dc4826e8b2ec63cf0101f6a5cc5bb",
"md5": "78a86d09c7899eda45b183bbf00bb7c9",
"sha256": "da3a50d2f744ef2d26098e71f49f9d71d2c72dde4f9e0636defb070e35a3f622"
},
"downloads": -1,
"filename": "pysplashsurf-0.12.0.2-cp37-abi3-macosx_13_0_x86_64.whl",
"has_sig": false,
"md5_digest": "78a86d09c7899eda45b183bbf00bb7c9",
"packagetype": "bdist_wheel",
"python_version": "cp37",
"requires_python": ">=3.7",
"size": 2849380,
"upload_time": "2025-08-12T20:14:22",
"upload_time_iso_8601": "2025-08-12T20:14:22.598339Z",
"url": "https://files.pythonhosted.org/packages/46/4a/a424a5cfa38fc8dfa4cfc9e5485e5a7dc4826e8b2ec63cf0101f6a5cc5bb/pysplashsurf-0.12.0.2-cp37-abi3-macosx_13_0_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "96d9c4da391a20c174440d9f5a61ee82c3cc201795cce7247e714e37735414b7",
"md5": "b8a5b35630f8fce853d05c0a267c7fe4",
"sha256": "fd2689afbfd187fbc4bfb41d5d5084a4ea751e30258802ee546a4b912832035b"
},
"downloads": -1,
"filename": "pysplashsurf-0.12.0.2-cp37-abi3-macosx_14_0_arm64.whl",
"has_sig": false,
"md5_digest": "b8a5b35630f8fce853d05c0a267c7fe4",
"packagetype": "bdist_wheel",
"python_version": "cp37",
"requires_python": ">=3.7",
"size": 2607189,
"upload_time": "2025-08-12T20:14:24",
"upload_time_iso_8601": "2025-08-12T20:14:24.343595Z",
"url": "https://files.pythonhosted.org/packages/96/d9/c4da391a20c174440d9f5a61ee82c3cc201795cce7247e714e37735414b7/pysplashsurf-0.12.0.2-cp37-abi3-macosx_14_0_arm64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "be6ce2645bd9570cfee935525f9d18ebcb488b1bf4f95c90977eecbb79ffe6e8",
"md5": "18be21c5be0975a8eb74664241faa7a9",
"sha256": "ee43f25207dd62b598a619ea1ced5627b88a48f2f3033b6f0c42b661110246ac"
},
"downloads": -1,
"filename": "pysplashsurf-0.12.0.2-cp37-abi3-manylinux2010_i686.manylinux2014_i686.manylinux_2_12_i686.manylinux_2_17_i686.whl",
"has_sig": false,
"md5_digest": "18be21c5be0975a8eb74664241faa7a9",
"packagetype": "bdist_wheel",
"python_version": "cp37",
"requires_python": ">=3.7",
"size": 2901598,
"upload_time": "2025-08-12T20:14:25",
"upload_time_iso_8601": "2025-08-12T20:14:25.732739Z",
"url": "https://files.pythonhosted.org/packages/be/6c/e2645bd9570cfee935525f9d18ebcb488b1bf4f95c90977eecbb79ffe6e8/pysplashsurf-0.12.0.2-cp37-abi3-manylinux2010_i686.manylinux2014_i686.manylinux_2_12_i686.manylinux_2_17_i686.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "cf68a537fff2a69049de8480a9ca642ad2d93a95dc4014231684d0b57c754ed7",
"md5": "63ab5301c819e28e7ba685f55fe7ae4e",
"sha256": "07b0517031f172bb9a412c0d2e44e9e692ba9c5e16829c4da93b4f9985bc7518"
},
"downloads": -1,
"filename": "pysplashsurf-0.12.0.2-cp37-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl",
"has_sig": false,
"md5_digest": "63ab5301c819e28e7ba685f55fe7ae4e",
"packagetype": "bdist_wheel",
"python_version": "cp37",
"requires_python": ">=3.7",
"size": 2647641,
"upload_time": "2025-08-12T20:14:26",
"upload_time_iso_8601": "2025-08-12T20:14:26.867008Z",
"url": "https://files.pythonhosted.org/packages/cf/68/a537fff2a69049de8480a9ca642ad2d93a95dc4014231684d0b57c754ed7/pysplashsurf-0.12.0.2-cp37-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "1c3b31eb509387b281c54dbe353cfa3c0f1d74a51a2ca623894d6604c58dfdba",
"md5": "ee9be6f1a92e9db96c0b1df12d46258a",
"sha256": "7663f0695614881806ff0ee3f773247a242c3d6dc5bda25dbe7f8aed09eba0ec"
},
"downloads": -1,
"filename": "pysplashsurf-0.12.0.2-cp37-abi3-manylinux2014_armv7l.manylinux_2_17_armv7l.whl",
"has_sig": false,
"md5_digest": "ee9be6f1a92e9db96c0b1df12d46258a",
"packagetype": "bdist_wheel",
"python_version": "cp37",
"requires_python": ">=3.7",
"size": 2710169,
"upload_time": "2025-08-12T20:14:28",
"upload_time_iso_8601": "2025-08-12T20:14:28.163681Z",
"url": "https://files.pythonhosted.org/packages/1c/3b/31eb509387b281c54dbe353cfa3c0f1d74a51a2ca623894d6604c58dfdba/pysplashsurf-0.12.0.2-cp37-abi3-manylinux2014_armv7l.manylinux_2_17_armv7l.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "be141cc7bc6e67e5779b8e6418d28a782cdd47f910ccc1f232d3388245f888c1",
"md5": "d6c95120ce13b4e0361832b4756a72c3",
"sha256": "f86676781e424b0b902354814aaac21de3a585b2e98e5162c778584f8a4c8925"
},
"downloads": -1,
"filename": "pysplashsurf-0.12.0.2-cp37-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl",
"has_sig": false,
"md5_digest": "d6c95120ce13b4e0361832b4756a72c3",
"packagetype": "bdist_wheel",
"python_version": "cp37",
"requires_python": ">=3.7",
"size": 2876821,
"upload_time": "2025-08-12T20:14:29",
"upload_time_iso_8601": "2025-08-12T20:14:29.258608Z",
"url": "https://files.pythonhosted.org/packages/be/14/1cc7bc6e67e5779b8e6418d28a782cdd47f910ccc1f232d3388245f888c1/pysplashsurf-0.12.0.2-cp37-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "db95cc72f44864487a3353624b51c436403f79589cdc14e0384c82e016a08fbc",
"md5": "f2cf2321463c54d061ffa5f5ce6fdc0f",
"sha256": "9d7206e5ac0fcd4703b4f5227b5e0acc4da68da8131e53516dfdf595b5a82798"
},
"downloads": -1,
"filename": "pysplashsurf-0.12.0.2-cp37-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl",
"has_sig": false,
"md5_digest": "f2cf2321463c54d061ffa5f5ce6fdc0f",
"packagetype": "bdist_wheel",
"python_version": "cp37",
"requires_python": ">=3.7",
"size": 2643982,
"upload_time": "2025-08-12T20:14:30",
"upload_time_iso_8601": "2025-08-12T20:14:30.736206Z",
"url": "https://files.pythonhosted.org/packages/db/95/cc72f44864487a3353624b51c436403f79589cdc14e0384c82e016a08fbc/pysplashsurf-0.12.0.2-cp37-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "7a16d8ace25fa5d0880e3fa2805ecdc4777ad1c3e7113cd0e9f051dfa130fbcd",
"md5": "e363c31d53ef7e58e455ce8c351b2fee",
"sha256": "bd3a1d7086ee264e5bfbd6b2881cf60ba21a6329c44392c078586823ebf4ed90"
},
"downloads": -1,
"filename": "pysplashsurf-0.12.0.2-cp37-abi3-manylinux_2_17_armv7l.manylinux2014_armv7l.whl",
"has_sig": false,
"md5_digest": "e363c31d53ef7e58e455ce8c351b2fee",
"packagetype": "bdist_wheel",
"python_version": "cp37",
"requires_python": ">=3.7",
"size": 2716316,
"upload_time": "2025-08-12T20:14:32",
"upload_time_iso_8601": "2025-08-12T20:14:32.080172Z",
"url": "https://files.pythonhosted.org/packages/7a/16/d8ace25fa5d0880e3fa2805ecdc4777ad1c3e7113cd0e9f051dfa130fbcd/pysplashsurf-0.12.0.2-cp37-abi3-manylinux_2_17_armv7l.manylinux2014_armv7l.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "30f3524c24d9bd91415ca06b1c20f0101a9ca184d68cc3921b2bf3db0792b2f1",
"md5": "2864837f805ce7f4295bc8f740696332",
"sha256": "9b50799044b1d2c6e574303eee05ca2f5cc10f50a85ef8bdd6560798545b0723"
},
"downloads": -1,
"filename": "pysplashsurf-0.12.0.2-cp37-abi3-manylinux_2_17_i686.manylinux2014_i686.whl",
"has_sig": false,
"md5_digest": "2864837f805ce7f4295bc8f740696332",
"packagetype": "bdist_wheel",
"python_version": "cp37",
"requires_python": ">=3.7",
"size": 2901680,
"upload_time": "2025-08-12T20:14:33",
"upload_time_iso_8601": "2025-08-12T20:14:33.877026Z",
"url": "https://files.pythonhosted.org/packages/30/f3/524c24d9bd91415ca06b1c20f0101a9ca184d68cc3921b2bf3db0792b2f1/pysplashsurf-0.12.0.2-cp37-abi3-manylinux_2_17_i686.manylinux2014_i686.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "974b756109f46d9e80b7be0aeac7b87c103c481ed682e343593e32f8068ed41c",
"md5": "0f027ecf025473601bc287248b89d414",
"sha256": "2ad8899eac7a2094d7e39e8d1e324a83ffbb24df1484df99452f12d30a668812"
},
"downloads": -1,
"filename": "pysplashsurf-0.12.0.2-cp37-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl",
"has_sig": false,
"md5_digest": "0f027ecf025473601bc287248b89d414",
"packagetype": "bdist_wheel",
"python_version": "cp37",
"requires_python": ">=3.7",
"size": 2875345,
"upload_time": "2025-08-12T20:14:35",
"upload_time_iso_8601": "2025-08-12T20:14:35.216456Z",
"url": "https://files.pythonhosted.org/packages/97/4b/756109f46d9e80b7be0aeac7b87c103c481ed682e343593e32f8068ed41c/pysplashsurf-0.12.0.2-cp37-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "b705148cae16f278b4de026e2d358f88bf722a6bd569f77fb4f8053bccf736dd",
"md5": "768d8ab806aa946d71c08077f6b6a91a",
"sha256": "e3bff4dad48c7e3adc1077bf25170a898f2062076979d4a6e108d8d0fa66841a"
},
"downloads": -1,
"filename": "pysplashsurf-0.12.0.2-cp37-abi3-win32.whl",
"has_sig": false,
"md5_digest": "768d8ab806aa946d71c08077f6b6a91a",
"packagetype": "bdist_wheel",
"python_version": "cp37",
"requires_python": ">=3.7",
"size": 2453659,
"upload_time": "2025-08-12T20:14:36",
"upload_time_iso_8601": "2025-08-12T20:14:36.322892Z",
"url": "https://files.pythonhosted.org/packages/b7/05/148cae16f278b4de026e2d358f88bf722a6bd569f77fb4f8053bccf736dd/pysplashsurf-0.12.0.2-cp37-abi3-win32.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "5158ff3618fe75f82711d35f275ffc36afb6c243bfda9ed407a8ba968720eaad",
"md5": "0480e941854ae2368fbd73952ba96cd8",
"sha256": "0f6c662b27c086fc3a7adcb86818fa5fef0e8c10f6e9691a311439c7423f8b37"
},
"downloads": -1,
"filename": "pysplashsurf-0.12.0.2-cp37-abi3-win_amd64.whl",
"has_sig": false,
"md5_digest": "0480e941854ae2368fbd73952ba96cd8",
"packagetype": "bdist_wheel",
"python_version": "cp37",
"requires_python": ">=3.7",
"size": 2703162,
"upload_time": "2025-08-12T20:14:37",
"upload_time_iso_8601": "2025-08-12T20:14:37.597813Z",
"url": "https://files.pythonhosted.org/packages/51/58/ff3618fe75f82711d35f275ffc36afb6c243bfda9ed407a8ba968720eaad/pysplashsurf-0.12.0.2-cp37-abi3-win_amd64.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-12 20:14:22",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "InteractiveComputerGraphics",
"github_project": "splashsurf",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "pysplashsurf"
}
JSON
