Creating 3D meshes programmatically often involves verbose APIs or complex geometry libraries. The sdf library takes a different route by letting you express shapes and their combinations as simple Python expressions, turning mesh generation into something that feels closer to math than boilerplate.
What sdf does and how it works
sdf is a Python library designed to generate 3D meshes from signed distance functions (SDFs) using the Marching Cubes algorithm. Signed distance functions represent shapes by defining, for any point in space, the shortest distance to the surface of the shape—negative values inside the shape and positive outside. This implicit representation allows compact and flexible descriptions of complex geometries.
The library ships with basic shapes like spheres, boxes, and cylinders, each represented as an SDF. What sets it apart is how it uses Python’s operator overloading to combine these shapes via constructive solid geometry (CSG) operations: the & operator for intersection, | for union, and - for difference. This lets you write expressions like sphere & box to get a shape that’s the intersection of a sphere and a box, making the code intuitive and concise.
Under the hood, sdf evaluates these SDFs on a batched 3D grid of points using numpy arrays. It parallelizes the computation across multiple worker threads, which helps offset the performance cost of using pure Python. Once the distance field is sampled, sdf applies the Marching Cubes algorithm to extract a mesh surface.
Output meshes are saved in the binary STL format by default, but thanks to integration with the meshio library, you can export to over 20 formats including OBJ and PLY. This makes sdf compatible with many 3D tools and workflows.
Beyond 3D, the library also supports 2D signed distance functions and features utilities for converting text into SDFs, converting meshes back into SDFs via OpenVDB, and visualizing 2D slices using matplotlib for debugging.
Technical strengths and design tradeoffs
The standout feature of sdf is its minimal yet expressive API. Operator overloading for CSG operations is a clever design choice that dramatically improves developer experience. Instead of managing verbose function calls or constructing explicit mesh operations, you compose shapes like mathematical expressions, which feels natural and reduces boilerplate.
Relying heavily on numpy for vectorized distance evaluations means the code is surprisingly fast for a pure Python library. The use of multiple worker threads to batch computations is a practical tradeoff to improve throughput without resorting to native extensions or compiled code. However, this approach still has limitations when dealing with very high-resolution grids or extremely complex shapes compared to fully compiled libraries.
The architecture is clean and modular. Core shape primitives are defined via SDF functions, while CSG operations are implemented through Python’s operator overloading. The Marching Cubes extraction is straightforward, relying on well-understood algorithms.
Support for multiple mesh export formats via meshio adds flexibility not often found in similar minimal SDF libraries. This makes it easier to integrate the output into various pipelines without extra conversion steps.
On the downside, since it’s pure Python, sdf won’t match the raw speed of C++ or GPU-based libraries for very large or real-time scenes. Also, while the API is minimal, users still need some understanding of SDF concepts and CSG operations to get the most out of it.
Finally, the built-in visualization is basic but effective for debugging, relying on matplotlib to render 2D slices of the SDF fields.
Quick start
The repository provides a straightforward setup process. Here’s the exact installation and test commands from the README:
git clone https://github.com/fogleman/sdf.git
cd sdf
virtualenv env
. env/bin/activate
pip install -e .
To confirm the installation works, run the example script:
python examples/example.py # should generate a file named out.stl
If you prefer not to install, you can run scripts that import sdf directly from the root folder.
Using operator overloading for shape composition
Here’s a minimal example of combining a sphere and a box using the overloaded operators:
from sdf import Sphere, Box
shape = Sphere(1.0) & Box([1.0, 1.0, 1.0]) # intersection of sphere and box
mesh = shape.to_mesh()
mesh.save_stl_binary('output.stl')
This concise syntax makes defining complex shapes feel natural and readable.
Verdict
sdf is a well-crafted Python library for generating 3D meshes via signed distance functions, with a particular strength in expressive, operator-overloaded constructive solid geometry. It’s a solid choice if you want to prototype or experiment with shape modeling in Python without diving into heavy dependencies or complex geometry toolkits.
The tradeoff is raw performance; for high-resolution or real-time applications, native or GPU-based alternatives will be faster. But for many offline modeling tasks, procedural generation, or educational purposes, sdf strikes a good balance between simplicity, clarity, and capability.
If your workflow involves Python and you appreciate clear APIs that feel like math, sdf is worth exploring.
Its support for multiple mesh output formats and 2D/3D SDF utilities adds practical value beyond a basic distance function library. Overall, it’s an elegant tool for anyone interested in signed distance function modeling and mesh generation.
Related Articles
- WorldGrow: Hierarchical infinite 3D world synthesis with block-wise growth and coarse-to-fine refinement — WorldGrow generates infinite 3D worlds via hierarchical block-wise synthesis with coarse-to-fine refinement, ensuring se
- AniGen: GPU-accelerated 3D animation generation with Python and CUDA — AniGen is a Linux-only Python project for 3D animation generation using NVIDIA GPUs and CUDA. It integrates PyTorch, spc
- Inside the ZED SDK: GPU-accelerated spatial perception for stereo cameras — Explore the ZED SDK, a C++ library for real-time stereo vision, SLAM, and spatial mapping with GPU acceleration and zero
- Recreating the 3dfx Voodoo GPU in SpinalHDL for FPGA and cycle-accurate simulation — SpinalVoodoo rebuilds the classic 3dfx Voodoo Graphics GPU in SpinalHDL, targeting FPGA synthesis and cycle-accurate sim
- PAT3D: orchestrating text-to-3D simulation-ready scenes through a multi-stage AI and physics pipeline — PAT3D composes a 9-stage pipeline combining LLMs, vision models, 3D asset generators, and physics simulation to produce
→ GitHub Repo: fogleman/sdf ⭐ 1,967 · Python