pyLevelSet

Brief description

Generate 3D level set particles, including surface mesh and signed distance field (SDF) with pure Python API. Developed by Multiscale Geomechanics Lab, Zhejiang University.

Overview

The library have a series of user-friendly features:

1. Given a set of point cloud, the library can reconstruct the surface mesh and generate the signed distance field.
2. Given a triangle mesh (e.g., STL, PLY, OBJ, GLB, GLTF ...), the library can generate the signed distance field.
3. Given a surface function (e.g., poly-super-quadric, poly-super-ellipsoid or a user-defined function), the library can generate surface node, constrcut surface mesh and generate signed distance field.
4. The library is capable of generating level-set particles from several SDF primitives, including the use of boolean operations to create more intricate particle shapes.

Example

Here is an example of a level-set particles contructed from SDF primitives. Special credits to sdf.

import pyLevelSet as pls
sf = pls.sphere(1) & pls.box(1.5)
cy = pls.cylinder(0.5)
sf -= cy.orient([1, 0, 0]) | cy.orient([0, 1, 0]) | cz.orient([0, 0, 1])
sf.grids(space=0.1).reset(False).visualize(samples=10002)

Quick start

Dependencies

Note that the dependencies will be automatically installed by setup.py when following the directions below.

Package name	Version	Features
numpy	lastest version	Pre-processing
scipy	lastest version	Find roots
scikit-image	lastest version	Marching cube method
open3d	lastest version	Reconstruct surface mesh
trimesh	lastest version	Import stl/obj files
rtree	lastest version	Neighbor search
pyevtk	lastest version	Postprocessing on Paraview
matplotlib	lastest version	Visualization

Installation

Install from pip (recommended)

pip install pyLevelSet

Install from source code

git clone https://github.com/Yihao-Shi/pyLevelSet.git
cd pyLevelSet-main
pip install .

Check Installation

python -c "import pyLevelSet as pls; print('pyLevelSet version is:', pls.__version__)"

Visualization

Several built-in functions support visualize the final result through 3D mesh viewer, such as gmsh, MeshLab or Paraview. The related function are listed as follows:

1. pyLevelSet.save()
2. pyLevelSet.visualize()
3. pyLevelSet.show()
4. pyLevelSet.show_slice()
5. pyLevelSet.dump_files()

API

Primitives

PointCloud

Polyhedron

f = pl.polyhedron(file='../assets/sand.stl')
f = f.grids(space=5)
f.save('sand.stl')
f.visualize()

SurfaceFunction

PolySuperQuadrics

f = pl.polysuperquadrics(xrad1=0.35, yrad1=0.75, zrad1=0.65, xrad2=0.25, yrad2=0.65, zrad2=0.5, epsilon_x=1.8, epsilon_y=1.2, epsilon_z=0.7)
f = f.grids(space=0.05)
f.save('ellipsoid.stl', samples=10002, sparse=False)
f.visualize()

PolySuperEllipsoid

f = pl.polysuperellipsoid(xrad1=0.5, yrad1=0.25, zrad1=0.75, xrad2=0.25, yrad2=0.75, zrad2=0.5, epsilon_e=1.5, epsilon_n=1.5)
f = f.grids(space=0.05)
f.save('ellipsoid.stl', samples=2502, sparse=False)
f.visualize()

Sphere

Variables

License

This project is licensed under the GNU General Public License v3 - see the LICENSE for details.

Acknowledgements

The project is inspired by sdf. Besides, we deliver special thanks to the excellent documentation on signed distance functions: 3D and 2D.

Contributors

Contact us

• If you spot any issue or need any help, please mail directly to syh-1999@outlook.com.

Release Notes

V0.1 (April 15, 2024)

• First release pyLevelSet