marching-cubes

Isosurface extraction from 3D volumes. Numpy in, indexed triangle mesh out.

the samples	the surface

A sphere sampled on a 16³ grid. On the left every voxel below the isovalue is drawn as a block, which is all the surface a volume gives you on its own. On the right is what marching_cubes reads out of the same numbers, interpolating each crossing to place vertices between the samples.

pip install marching-cubes-numpy

The distribution is named marching-cubes-numpy; the import is marching_cubes.

import numpy as np
from marching_cubes import marching_cubes

x, y, z = np.indices((64, 64, 64)) - 32
volume = np.sqrt(x**2 + y**2 + z**2) - 20.0

vertices, faces = marching_cubes(volume, 0.0)

vertices is an (n, 3) array of float64 positions in index coordinates, so vertices[:, 0] runs along the first axis of volume. faces is an (m, 3) array of int32 indices into vertices.

Corners with a value below the isovalue are inside the surface, and triangles are wound so that their normals point outwards, towards the higher values. Vertices are shared between adjacent triangles, and the surface is closed and manifold wherever it does not run off the edge of the volume.

Only numpy is required. The package is annotated and ships a py.typed marker, so type checkers see the shapes and dtypes above without any stub package.

Development

The 256-entry triangulation table is derived rather than transcribed; see tools/generate_tri_table.py.

pip install -e ".[dev]"
pytest
mypy
python bench/benchmark.py

The images above are rendered by tools/render_readme_images.py, which needs Blender on the path.