Fast Mesh Booleans in Python

trueform is the fastest Python mesh boolean library for real-world meshes — performing exact boolean union, intersection, and difference at interactive speed. One pip install. NumPy arrays in, NumPy arrays out. This tutorial covers the basics: loading meshes, running booleans, and working with results. It then shows how to precompute spatial and topological structures and use shared views to avoid rebuilding them, enabling boolean operations on moving geometry at real-time rates.

We will use the Stanford Dragon to demonstrate boolean union, intersection, and difference between two offset copies of the same mesh.

Each boolean under 14ms on 2×500K polygons. Let's begin by installing trueform.

Install

pip install trueform

See the installation guide for all options.

Loading the mesh

import trueform as tf
import numpy as np

Load from a file:

faces, points = tf.read_stl("stanford_dragon.stl")
dragon = tf.Mesh(faces, points)

Or in one line:

dragon = tf.Mesh(*tf.read_stl("stanford_dragon.stl"))

If you already have vertex and face data as NumPy arrays, pass them directly:

faces = np.array([[0, 1, 2], [1, 3, 2]], dtype=np.int32)
points = np.array([
    [0, 0, 0], [1, 0, 0],
    [0, 1, 0], [1, 1, 0]
], dtype=np.float32)

dragon = tf.Mesh(faces, points)

The Mesh form wraps your arrays with geometric semantics — spatial queries, topology, and boolean operations all work directly on it.

Transformations

To perform a boolean between two copies of the dragon at different positions, set a transformation on the mesh. The underlying data is shared — no vertices are copied.

T = np.eye(4, dtype=np.float32)
T[:3, 3] = [0.0, 1.0, 0.0]  # translate by [0, 1, 0]

dragon.transformation = T

The spatial tree and topology structures stay valid across transformations — they are applied on-the-fly during queries.

Boolean operations

Three operations. Same two inputs. Full documentation.

To boolean two separate meshes at different positions, create a shared view. The view shares all underlying data and structures but carries its own transformation:

dragon = tf.Mesh(*tf.read_stl("stanford_dragon.stl"))

translated = dragon.shared_view()
T = np.eye(4, dtype=np.float32)
T[:3, 3] = [0.0, 1.0, 0.0]
translated.transformation = T

Union

(result_faces, result_points), labels, face_labels = 
    tf.boolean_union(dragon, translated)

Difference

(result_faces, result_points), labels, face_labels = 
    tf.boolean_difference(dragon, translated)

Intersection

(result_faces, result_points), labels, face_labels = 
    tf.boolean_intersection(dragon, translated)

Working with results

Every boolean returns three values. (result_faces, result_points) is the output mesh as NumPy arrays. labels marks each output face — 0 for faces originating from the first input, 1 from the second. face_labels maps each output face back to the index of its source face in the input, enabling attribute transfer.

To split the result into separate meshes by label:

result_mesh = tf.Mesh(result_faces, result_points)
components, component_labels = \
    tf.split_into_components(result_mesh, labels)

Write to file:

tf.write_stl((result_faces, result_points), "result.stl")
tf.write_obj((result_faces, result_points), "result.obj")

Precomputed structures

When running multiple booleans on the same geometry, build the spatial and topological structures once. The build_tree, face_membership, and manifold_edge_link are computed lazily on first use, but explicit precomputation avoids paying the cost during the boolean itself:

dragon = tf.Mesh(*tf.read_stl("stanford_dragon.stl"))
dragon.build_tree()
dragon.build_face_membership()
dragon.build_manifold_edge_link()

Now create shared views at different positions. Each view shares the same data and structures — only the transformation differs:

for t in np.arange(0.1, 1.1, 0.1):
    view = dragon.shared_view()
    T = np.eye(4, dtype=np.float32)
    T[:3, 3] = [0.0, t, 0.0]
    view.transformation = T

    (result_faces, result_points), labels, face_labels = \
        tf.boolean_difference(dragon, view)

10 booleans on 2×500K polygon meshes in under 140ms total. Spatial and topological structures computed once.

Extracting intersection curves

Any boolean can also return the intersection boundary as polylines embedded on the surface. Pass return_curves=True:

(result_faces, result_points), labels, face_labels, (paths, curve_points) = \
    tf.boolean_difference(dragon, translated, return_curves=True)

If only the intersection curves are needed without the boolean itself:

paths, curve_points = tf.intersection_curves(dragon, translated)

Performance and robustness

All operations run at interactive speed on million-polygon meshes.

Apple M4 Max 16 threads

Real meshes are not ideal manifolds. trueform handles them directly — no preprocessing, no manifold requirement.

trueform is a robust CGAL alternative — and the fastest mesh boolean library available — for exact mesh boolean operations in C++, Python, and TypeScript.

Full benchmarks and methodology · How the algorithm works

@article{polydera:fast-mesh-booleans-in-python,
  title={Fast Mesh Booleans in Python},
  author={Sajovic, {\v{Z}}iga, Polydera},
  year={2026},
  url={https://polydera.com/tutorials/fast-mesh-booleans-in-python},
  organization={Polydera}
}