Manifold3d

3.4.1 · active · verified Sat Apr 11

Manifold3d is a Python library providing bindings to the Manifold C++ geometry kernel (v3.4.1). It specializes in creating and operating on topologically robust, manifold triangle meshes, making it ideal for applications in CAD, 3D printing, and simulations. The library guarantees manifold output and leverages parallelization for performance. It has an active development cycle with regular releases.

Warnings

breaking The `MeshIO` public API was removed in version 3.4.0. Users are advised to use external libraries like `trimesh` for Python (or `assimp` for C++) for 3D file input/output.
Fix: Migrate 3D file I/O operations to `trimesh` or similar libraries. Example: `pip install trimesh` and use `trimesh.Trimesh` for imports/exports.
gotcha Version 3.4.0 introduced a 'lazy collider change' which could lead to numerical issues in some cases. This change was reverted in version 3.4.1. If experiencing unexpected numerical instability or mesh artifacts, ensure you are using v3.4.1 or later.
Fix: Upgrade to `manifold3d==3.4.1` or a newer version.
gotcha Manifold3d's rotation API takes degrees, not radians. When performing rotations, it is critical to use exact degree values (e.g., 90, 45) rather than computed approximations (e.g., `math.degrees(math.pi / 2)` or `89.999999999999`) to guarantee precision and avoid mesh cracks due to floating-point errors. The library can optimize for exact degree values.
Fix: Always use integer or exact float degree values for rotations (e.g., `manifold.rotate([90, 0, 0])`) instead of converting from radians or using approximations.
gotcha While Manifold3d guarantees manifold output, it requires manifold meshes as input. If you provide non-manifold mesh data, the library will return an error status. Users may need to preprocess their meshes using external repair tools to ensure they are manifold before inputting them to Manifold3d.
Fix: Ensure input meshes are manifold. Consider using external mesh repair tools if starting with potentially non-manifold data.
gotcha Manifold3d's direct OBJ file I/O is limited in functionality and primarily intended for testing purposes. For robust handling of vertex properties (e.g., normals, UVs, colors) and materials, using the `trimesh` library for OBJ or other 3D format imports/exports is strongly advised.
Fix: For full-featured 3D file I/O, especially with vertex properties, use `trimesh` to handle mesh loading and saving.

Install

pip install manifold3d Install stable release

Imports

manifold3d
```
import manifold3d
```

Quickstart

This quickstart demonstrates creating basic 3D primitives (sphere, box) and performing common boolean operations like union and difference. It showcases the core functionality of combining and modifying manifold meshes. For saving or loading complex 3D file formats, integrating with a dedicated mesh I/O library like `trimesh` is recommended.

import manifold3d

# Create a sphere with radius 1 and 60 facets
sphere = manifold3d.Sphere(1, 60)

# Create a cube with dimensions [1, 1, 1]
box = manifold3d.Box([1, 1, 1])

# Translate the box to intersect the sphere
box_translated = box.translate([0.5, 0.5, 0.5])

# Perform a boolean union operation
union_result = sphere.union(box_translated)

# Perform a boolean difference operation
difference_result = sphere.difference(box_translated)

print(f"Sphere triangles: {sphere.num_triangles()}")
print(f"Union result triangles: {union_result.num_triangles()}")
print(f"Difference result triangles: {difference_result.num_triangles()}")

# To export, consider using the 'trimesh' library:
# import trimesh
# mesh_data = union_result.to_mesh()
# trimesh_mesh = trimesh.Trimesh(
#     vertices=mesh_data.vert_properties[:, :3], 
#     faces=mesh_data.tri_verts
# )
# trimesh_mesh.export('union_result.stl')

view raw JSON →