PyMCubes is an implementation of the marching cubes algorithm to extract
iso-surfaces from volumetric data. The volumetric data can be given as a
three-dimensional NumPy array or as a Python function f(x, y, z).
PyMCubes also provides functions to export the results of the marching cubes
in a number of mesh file formats.
Use pip:
$ pip install --upgrade PyMCubes
The following example creates a NumPy volume with spherical iso-surfaces and
extracts one of them (i.e., a sphere) with mcubes.marching_cubes. The result
is exported to sphere.dae:
>>> import numpy as np
>>> import mcubes
# Create a data volume (30 x 30 x 30)
>>> X, Y, Z = np.mgrid[:30, :30, :30]
>>> u = (X-15)**2 + (Y-15)**2 + (Z-15)**2 - 8**2
# Extract the 0-isosurface
>>> vertices, triangles = mcubes.marching_cubes(u, 0)
# Export the result to sphere.dae
>>> mcubes.export_mesh(vertices, triangles, "sphere.dae", "MySphere")Alternatively, you can use a Python function to represent the volume instead of
a NumPy array:
>>> import numpy as np
>>> import mcubes
# Create the volume
>>> f = lambda x, y, z: x**2 + y**2 + z**2
# Extract the 16-isosurface
>>> vertices, triangles = mcubes.marching_cubes_func((-10,-10,-10), (10,10,10),
... 100, 100, 100, f, 16)
# Export the result to sphere.dae (requires PyCollada)
>>> mcubes.export_mesh(vertices, triangles, "sphere.dae", "MySphere")
# Or export to an OBJ file
>>> mcubes.export_obj(vertices, triangles, 'sphere.obj')Note that using a function to represent the volumetric data is much slower
than using a NumPy array.
Many segmentation methods build binary masks to separate inside and outside areas of the segmented object. When passing these binary mask to the marching cubes algorithm the resulting mesh looks jagged. The following code shows an example with a binary array embedding a sphere.
x, y, z = np.mgrid[:100, :100, :100]
binary_sphere = (x - 50)**2 + (y - 50)**2 + (z - 50)**2 - 25**2 < 0
# Extract the 0.5-levelset since the array is binary
vertices, triangles = mcubes.marching_cubes(binary_sphere, 0.5)
PyMCubes provides the function mcubes.smooth that takes a 2D or 3D binary
embedding function and produces a smooth version of it.
smoothed_sphere = mcubes.smooth(binary_sphere)
# Extract the 0-levelset (the 0-levelset of the output of mcubes.smooth is the
# smoothed version of the 0.5-levelset of the binary array).
vertices, triangles = mcubes.marching_cubes(smoothed_sphere, 0)
mcubes.smooth builds a smooth embedding array with negative values in the
areas where the binary embedding array is 0, and positive values in the areas
where it is 1. In this way, mcubes.smooth keeps all the information from the
original embedding function, including fine details and thin structures that
are commonly eroded by other standard smoothing methods.