signedheat3d 1.0.0

Python bindings for the signed-heat-3d library, which implements the Signed Heat Method for generalized signed distance.

signedheat3d (Python package)

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 of potpourri3d!)

Installation

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.

Dependencies

This project has the following submodules, which should have been installed in the previous step.

• nanobind
• signed-heat-3d

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.

Demo program

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:

• NumPy
• polyscope

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

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

Command line arguments

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.