Documentation lives at https://nzfeng.github.io/signed-heat-docs/py
A Python library implementing the Signed Heat Method for computing robust signed distance fields (SDFs) to polygon meshes and point clouds in 3D.
- The original C++ code lives at signed-heat-3d.
- If you're interested in using the Signed Heat Method on 2D surface domains, rather than in 3D Euclidean space, check out the signed heat method implementation in
potpourri3d. (The overall organization of this repository was inspired by that ofpotpourri3d!)
The recommended way to install signedheat3d is via PyPI:
pip install signedheat3d
You can also clone the repository and install it from source:
git clone --recurse-submodules https://github.com/nzfeng/signed-heat-python.git
cd signed-heat-python
pip install .
If you do not clone recursively, some submodules or sub-submodules will not clone. Initialize/update these submodules by running git submodule update --init --recursive or git submodule update --recursive.
This project has the following submodules, which should have been installed in the previous step.
You may need to install Boost since signed-heat-3d depends on amgcl, which depends on Boost. Pip-installing signed-heat-3d should download Boost if it is not found on your system, but Boost can also be installed on macOS using brew install boost, and the necessary modules on Ubuntu using
sudo apt-get -y update
sudo apt-get -y install libboost-dev libboost-test-dev libboost-program-options-dev libboost-serialization-dev
Windows users would follow the instructions on the Boost website.
This repository also contains a demo Python program at test/demo.py, using Polyscope for visualization. The demo program at test/demo.py uses the following Python libraries, which can each be installed via pip install:
To run the demo program, pip-install the package using the instructions described above. Then cd into the top level of the directory, and run
python3 test/demo.py path/to/mesh/or/pointcloud
Input / output meshes can be any one of the following types ("Supported file types"), including OBJ, PLY, STL, and OFF.
Point clouds are currently assumed to have file extension .pc and consist of newline-separated 3D point positions (denoted by leading char v) and point normal vectors (denoted by leading char vn).
In addition to the mesh file, you can pass several flags.
| flag | default | purpose |
|---|---|---|
--g, --grid |
False |
Solve on a background grid. By default, the domain will be discretized as a tet mesh. |
--b |
np.array([1.0, 1.0, 1.0, -1.0, -1.0, -1.0], dtype=np.float64)) |
Set the 3D positions of the minimum & maximum corners of the rectangular domain. If the corner positions are not valid, a bounding box will automatically be computed. |
--v, --verbose |
Off | Verbose output. Off by default. |
--s |
np.array([32, 32, 32], dtype=np.int64)) |
Sets the resolution of the domain, by defining the number of nodes in each dimension. If solving on a tet mesh, only the first value is relevant. |
--l, --headless |
Off | Don't use the GUI, and automatically solve for & export the generalized SDF. |