pyvista-manifold

A PyVista accessor for Manifold, a fast and reliable boolean / CSG library for triangle meshes.

Every frame is a real tpms.manifold.intersection(sphere) against a gyroid iso-surface — the wireframe is the live cutter, the gold is the result. Three function calls build the whole thing: level_set for the gyroid field, pv.Sphere for the cutter, mesh.manifold.intersection to combine them.

From left: a machined aluminum bracket built by chaining union and difference; a real mesh intersected with a gyroid TPMS lattice; a cube fractured by repeated plane cuts. The gold sphere lives in the animation above.

Once the package is installed, every pv.PolyData exposes a .manifold accessor. There is nothing to import.

import pyvista as pv

cube = pv.Cube()
sphere = pv.Sphere(radius=0.7, center=(0.4, 0.4, 0.4))
cube.manifold.difference(sphere).plot()

Why

PyVista's built-in boolean filters wrap VTK's vtkBooleanOperationPolyDataFilter, which produces non-manifold or self-intersecting output on non-trivial inputs. Manifold solves the same problem with exact arithmetic and topology tracking. This package is the smallest reasonable bridge between the two: a single .manifold accessor that converts on demand, caches the default Manifold conversion on the dataset accessor, and always returns a fresh pv.PolyData.

Install

pip install pyvista-manifold

Requires Python 3.10+ and PyVista 0.48+. The accessor registers itself via PyVista's plugin entry-point system; you don't import the package to use it.

Quick start

import pyvista as pv

# Boolean ops chain through PyVista's filter pipeline
cube = pv.Cube(x_length=2.0, y_length=2.0, z_length=2.0)
sphere = pv.Sphere(radius=0.9)
diff = cube.manifold.difference(sphere)
print(diff.manifold.volume, diff.manifold.is_valid)

# Drill three orthogonal cylinders out of a cube in one call
holes = [pv.Cylinder(radius=0.4, height=3, direction=d) for d in [(1, 0, 0), (0, 1, 0), (0, 0, 1)]]
from pyvista_manifold import OpType

drilled = cube.manifold.batch_boolean(holes, op=OpType.Subtract)

# Intersect with an iso-surface from a callable scalar field
import math
from pyvista_manifold import level_set


def gyroid(x, y, z):
    return -(
        math.sin(2 * x) * math.cos(2 * y)
        + math.sin(2 * y) * math.cos(2 * z)
        + math.sin(2 * z) * math.cos(2 * x)
    )


iso = level_set(gyroid, bounds=(-2, -2, -2, 2, 2, 2), edge_length=0.1)
infilled = pv.Sphere(radius=1.5).manifold.intersection(iso)

# Anything you build chains naturally with PyVista filters
finished = drilled.clean().smooth(n_iter=20).compute_normals()

A worked walkthrough lives in examples/showcase.ipynb: mechanical CSG, TPMS infill of a real mesh, topographic slicing, Voronoi-style fracture, Minkowski filleting.

Gallery

Mechanical CSG. Stack union and difference to build a real-looking part.
TPMS lattice infill. Intersect a closed mesh with a gyroid field, the standard 3D-printer infill, computed in two lines.
Topographic slicing. slice_z at many heights stacks into a contour map of the silhouette.
Iso-surface from a callable. level_set extracts a TPMS surface from a Python function, no marching-cubes plumbing.
Voronoi-style fracture. Repeated split_by_plane calls turn a cube into a stack of polyhedral cells.

The accessor

mesh.manifold is a per-instance accessor that converts the PolyData into a manifold3d.Manifold on demand, caches the default clean=True conversion until the dataset is modified, runs the operation, and converts the result back. The input is left untouched.

mesh.manifold                      # accessor instance, cached on the dataset
mesh.manifold.to_manifold()        # raw manifold3d.Manifold (drop down when needed)
mesh.manifold.<operation>(...)     # any method below; always returns pv.PolyData

The conversion runs pyvista.PolyData.clean() and triangulates the input by default, so PyVista primitives like pv.Cube and pv.Cylinder (which ship with seam-duplicated vertices) work directly. Pass clean=False to mesh.manifold.to_manifold() if you need to preserve every input vertex.

If your mesh isn't a closed, outward-facing manifold solid, the conversion still returns a Manifold, but every accessor method that returns geometry raises a ValueError naming the cause, as does min_gap, which also requires valid solids. The other queries never raise: check mesh.manifold.is_valid (returns True when Manifold's status is NoError and the volume is not negative).

Boolean operations

other is either a pv.PolyData or a manifold3d.Manifold. Mixing is fine.

Transforms

Hulls

Refinement and smoothing

Splits and decomposition

Minkowski

3D to 2D

Properties and queries

Tolerance, simplification, properties

Module-level helpers

For things that don't start from an existing mesh:

from pyvista_manifold import level_set, extrude, revolve, hull_points

# Iso-surface from a scalar field
iso = level_set(f, bounds=(xmin, ymin, zmin, xmax, ymax, zmax), edge_length=0.1)

# Extrude / revolve a 2D polygon
solid = extrude(polygons, height, n_divisions=0, twist_degrees=0, scale_top=(1, 1))
solid = revolve(polygons, segments=0, revolve_degrees=360.0)

# Convex hull of a raw point cloud
hull = hull_points(points)  # (N, 3) array

polygons is a single (N, 2) array or a list of such arrays representing a polygon-with-holes set.

For everything that has an obvious PyVista equivalent (pv.Cube, pv.Sphere, pv.Cylinder, etc.), use PyVista directly and chain through .manifold.

Conversion utilities

The accessor handles conversion automatically. Reach for these only when the accessor isn't enough:

import pyvista as pv
from pyvista_manifold import to_manifold, from_manifold

m = to_manifold(polydata, point_data_keys=['scalar'])  # PolyData -> Manifold
poly = from_manifold(m, property_names=['scalar'])  # Manifold -> PolyData

Per-vertex point arrays can be passed through Manifold as extra property channels via point_data_keys. Manifold linearly interpolates them across boolean cuts, and from_manifold unpacks them back into point_data.

Caveats

• Inputs must be manifold solids (closed, non-self-intersecting). Run pv.PolyData.clean() and check mesh.manifold.is_valid if you're unsure. PyVista's downloaded example meshes vary: download_cow, download_horse, download_armadillo are manifold; download_bunny (the Stanford scan) is not.
• All faces are triangulated and merged during conversion. The roundtrip preserves vertex coordinates for triangulated, deduplicated input but does not preserve cell-data arrays, except that union, difference and intersection carry each cell array both inputs hold onto the faces cut from it.
• Output points and point-data property arrays are float64: conversion goes through Manifold's Mesh64 in both directions, so meshes far from the origin keep their precision.
• Manifold has no built-in I/O. Use PyVista's readers and writers on the resulting PolyData.

Development

git clone https://github.com/pyvista/pyvista-manifold
cd pyvista-manifold
just sync          # uv sync --extra dev
just test          # pytest with coverage
just lint          # pre-commit run --all-files
just typecheck     # mypy

Image-regression tests run via pytest-pyvista. To re-seed the cache after intentional visual changes:

uv run pytest tests/test_image_regression.py --reset_image_cache

The hero images at the top of this README are produced by assets/render_hero.py.

Acknowledgements

• Manifold by Emmett Lalish and contributors.
• PyVista for the accessor system and the rest of the visualization stack.

License

MIT.