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

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.

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)

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

pip install pyLevelSet

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

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

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()

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

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()

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()

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

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

• If you spot any issue or need any help, please mail directly to [email protected].

V0.2 (April 18, 2024)

• Fix bugs when the principal axis of inertia is not aligned with coordinate axis
• Update README.md and provide some examples

V0.1 (April 15, 2024)

• First release pyLevelSet