Metadata-Version: 2.4
Name: marching-cubes-numpy
Version: 0.1.0
Summary: Marching cubes isosurface extraction
Project-URL: Homepage, https://github.com/Volumental/marching-cubes
Project-URL: Issues, https://github.com/Volumental/marching-cubes/issues
Author: Volumental
License-Expression: MIT
License-File: LICENSE
Keywords: isosurface,marching cubes,mesh,volume,voxel
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Multimedia :: Graphics :: 3D Modeling
Classifier: Topic :: Scientific/Engineering :: Image Processing
Classifier: Typing :: Typed
Requires-Python: >=3.9
Requires-Dist: numpy>=1.21
Provides-Extra: dev
Requires-Dist: mypy; extra == 'dev'
Requires-Dist: pytest; extra == 'dev'
Description-Content-Type: text/markdown

# marching-cubes

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

| the samples | the surface |
|:---:|:---:|
| ![A sphere sampled on a 16³ grid, every voxel below the isovalue drawn as a block](https://raw.githubusercontent.com/Volumental/marching-cubes/master/docs/volume.png) | ![The triangle mesh marching cubes extracts from those same samples](https://raw.githubusercontent.com/Volumental/marching-cubes/master/docs/surface.png) |

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`.

```python
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](https://github.com/Volumental/marching-cubes/blob/master/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](https://github.com/Volumental/marching-cubes/blob/master/tools/render_readme_images.py), which needs
Blender on the path.
