DOCSEARCHbyAlgolia
Submit Docs

PyMCubes Documentation

repository·master·Indexed 21 days ago

https://github.com/pmneila/pymcubes

A Python implementation of the marching cubes algorithm for extracting 3D iso-surfaces from volumetric data. It supports data provided as NumPy arrays via marching_cubes or mathematical functions via marching_cubes_func. The library includes utilities for smoothing binary masks with mcubes.smooth and exporting meshes to Collada (.dae) and OBJ (.obj) formats.

Tokens
1.1K
Snippets
5
Records
5
Agent score
24%

What's inside PyMCubes

  1. Smooth binary masks using `mcubes.smooth`

    master

    When extracting iso-surfaces from binary masks (segmentation results), the resulting mesh often appears jagged. mcubes.smooth can resolve this by taking a 2D or 3D binary embedding function and producing a smooth version.

    mcubes.smooth creates a smooth embedding array where areas that were 0 in the binary array become negative, and areas that were 1 become positive. This preserves fine details and thin structures better than standard smoothing methods.

    Workflow:

    1. Create/obtain your binary array.
    2. Apply smoothed_array = mcubes.smooth(binary_array).
    3. Extract the iso-surface from the smoothed array at level 0 (which corresponds to the 0.5 level-set of the original binary array).
    import numpy as np
import mcubes

x, y, z = np.mgrid[:100, :100, :100]
binary_sphere = (x - 50)**2 + (y - 50)**2 + (z - 50)**2 - 25**2 < 0

# Smooth the binary embedding
smoothed_sphere = mcubes.smooth(binary_sphere)

# Extract the 0-levelset of the smoothed array
vertices, triangles = mcubes.marching_cubes(smoothed_sphere, 0)

  3. Extract iso-surfaces from a NumPy array using `marching_cubes`

    master

    To extract an iso-surface from volumetric data stored in a 3D NumPy array, use mcubes.marching_cubes(u, isovalue).

    • u: A 3D NumPy array representing the volumetric data.
    • isovalue: The value at which the iso-surface is extracted.

    Returns a tuple of (vertices, triangles).

    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)

  4. Export meshes to Collada (.dae) or OBJ (.obj) formats

    master

    Once you have extracted vertices and triangles, you can export them to various mesh file formats.

    • Collada (.dae): Use mcubes.export_mesh(vertices, triangles, "filename.dae", "name"). This requires the PyCollada package.
    • OBJ (.obj): Use mcubes.export_obj(vertices, triangles, "filename.obj").
    # Export to Collada (requires PyCollada)
mcubes.export_mesh(vertices, triangles, "sphere.dae", "MySphere")

# Export to OBJ
mcubes.export_obj(vertices, triangles, 'sphere.obj')

  5. Extract iso-surfaces from a function using `marching_cubes_func`

    master

    If your volumetric data is defined by a mathematical function $f(x, y, z)$ rather than an array, use mcubes.marching_cubes_func. Note that this method is significantly slower than using a NumPy array.

    Signature: mcubes.marching_cubes_func(min_bounds, max_bounds, resolution_x, resolution_y, resolution_z, function, isovalue)

    • min_bounds: Tuple (x, y, z) representing the lower bounds.
    • max_bounds: Tuple (x, y, z) representing the upper bounds.
    • resolution_x, resolution_y, resolution_z: Integer resolutions for each axis.
    • function: A Python function f(x, y, z).
    • isovalue: The value at which the iso-surface is extracted.

    Returns a tuple of (vertices, triangles).

    import numpy as np
import mcubes

# Create the volume function
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)