Installation

Supported Python

voxelmap supports Python 3.8+ (tested on 3.8–3.12).

Quick install (core only)

The core library only requires NumPy and Matplotlib.

pip install voxelmap

Optional extras

Install extras depending on what you need:

I/O helpers (JSON/TXT utilities):
```
pip install "voxelmap[io]"
```
Meshing & interactive 3D (scipy, scikit-image, PyVista):
```
pip install "voxelmap[mesh]"
```
Everything:
```
pip install "voxelmap[all]"
```

Virtual environment (recommended)

Create and activate a virtual environment:

python -m venv venv
source venv/bin/activate        # Windows: venv\Scripts\activate
pip install "voxelmap[all]"

Deactivate anytime with deactivate.

Developer install (editable)

If you’re working on the package locally:

git clone https://github.com/andrewrgarcia/voxelmap.git
cd voxelmap
python -m venv venv
source venv/bin/activate
pip install -e ".[all]"         # or .[mesh], .[io], or just .

Upgrading / Uninstalling

pip install -U voxelmap
pip uninstall voxelmap

Verify your install

Run a quick smoke test:

python - <<'PY'
import numpy as np
from voxelmap import Model
a = np.ones((3,3,3))
m = Model(a)
m.set_color(1, "red")
# Should render a red 3x3x3 cube in a Matplotlib window:
m.draw_mpl(coloring="custom")
print("voxelmap OK")
PY

Notes for interactive 3D (PyVista)

Install the mesh extra: pip install "voxelmap[mesh]".
On headless servers/CI, prefer Matplotlib renders or configure an offscreen VTK backend.
Some Linux desktops may require system OpenGL/VTK packages for full PyVista interactivity.

Building the documentation (optional)

If you want to preview the docs locally:

pip install sphinx sphinx-rtd-theme
# (optional live reload) pip install sphinx-autobuild
make -C docs html
# open docs/build/html/index.html in your browser

# Live preview:
sphinx-autobuild docs/source docs/build/html  # visit http://127.0.0.1:8000

Troubleshooting

Matplotlib window doesn’t zoom/rotate: basic 3D axes support is limited; install the mesh extra and use PyVista for fully interactive 3D viewers.
ImportError for optional deps: install the appropriate extra ([io], [mesh], or [all]).
Editable install discovers extra folders: ensure only package dirs are included (e.g., use a src/ layout or restrict package discovery in pyproject.toml).