voxelmap
A lightweight Python library for building voxel models from NumPy arrays.
Simple to start, modular when you need more.
🚀 Installation
Minimal core (NumPy + Matplotlib only):
pip install voxelmap
Optional extras:
pip install voxelmap[io] # for I/O helpers (pandas, txt/obj conversions)
pip install voxelmap[mesh] # for meshing (scipy, scikit-image, pyvista)
pip install voxelmap[all] # everything
We recommend using a virtual environment:
python -m venv venv
source venv/bin/activate
pip install voxelmap
Deactivate with:
deactivate
🧩 Quickstart
1. Hello World (Matplotlib, core only)
import numpy as np
from voxelmap import Model
# Simple 3×3×3 cube
array = np.ones((3, 3, 3))
model = Model(array)
model.set_color(1, "red") # assign color
model.draw_mpl(coloring="custom") # static Matplotlib 3D plot
➡️ Produces a solid red cube in a Matplotlib 3D plot.
- Rotate = left mouse drag
- Pan = right mouse drag
- Zoom = scroll wheel
(Works with the minimal install, no extras required.)
2. Interactive 3D (PyVista, mesh extra)
For full trackball-style zoom, pan, and rotate, install with:
pip install voxelmap[mesh]
Then:
import numpy as np
from voxelmap import Model
array = np.ones((3, 3, 3)) # same cube
model = Model(array)
model.set_color(1, "red")
# Interactive PyVista window
model.draw(coloring="custom")
➡️ Opens an interactive window:
- Rotate freely (trackball)
- Smooth zoom with scroll/drag
- Pan and adjust camera in real time
3. Custom Palette (checkerboard)
import numpy as np
from voxelmap import Model
array = np.indices((3, 3, 3)).sum(axis=0) % 2 + 1
model = Model(array)
model.palette = {1: "black", 2: "white"}
model.draw_mpl(coloring="custom")
➡️ Produces a black/white checkerboard cube.
4. Gradient Coloring
import numpy as np
from voxelmap import Model
from matplotlib import cm
array = np.ones((10, 3, 3)) # tall column
model = Model(array)
model.colormap = cm.viridis
model.alphacm = 0.9
model.draw_mpl(coloring="linear")
➡️ Produces a column shaded with a viridis vertical gradient.
5. Mesh Export + Viewing Modes (OBJ+MTL)
You can export voxel arrays as geometry + materials with MarchingMesh, then reload them in MeshView for different visualization styles.
import numpy as np
from voxelmap import Model
from voxelmap.mesh import MarchingMesh, MeshView
arr = np.zeros((5, 5, 5))
arr[1:4, 1:4, 1:4] = 1 # cube
arr[2:3, 2:3, 4] = 2 # red voxel
m = Model(arr)
m.set_color(1, "gray") # cube body
m.set_color(2, "red") # highlight
# Export OBJ+MTL
MarchingMesh(m.array, palette=m.palette, out_file="cube.obj")
# 1. Solid (palette only)
MeshView("cube.obj", palette=m.palette, mode="solid")
# 2. Wireframe only (green edges)
MeshView("cube.obj", mode="wireframe", wireframe_color="green")
# 3. Both solid + edges
MeshView("cube.obj", palette=m.palette, mode="both", wireframe_color="magenta")
# 4. Flat fill (single color, ignore palette)
MeshView("cube.obj", mode="flat", flat_color="orange")
➡️ Modes available:
- solid: surfaces colored from
palette - wireframe: edges only, no fills
- both: filled faces + edges
- flat: single fill color, ignores palette
You can also set:
background_color="black"(hex or named color)background_image="starfield.png"(PNG/JPEG)wireframe_color="cyan"
📚 Documentation
Full usage and advanced examples can be found here: 👉 VoxelMap Documentation
⚖️ License
This program is free software. It comes without any warranty, to the extent permitted by applicable law. You can redistribute it and/or modify it under the terms of the MIT LICENSE.
MIT license © 2022–present Andrew Garcia
1 maintainer
Metadata
1 maintainer
Release files for voxelmap 5.1.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| voxelmap-5.1.1.tar.gz | 13.5 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| voxelmap-5.1.1-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 24.9 kB
Release files / voxelmap-5.1.1.tar.gz
| Download URL | voxelmap-5.1.1.tar.gz |
|---|---|
| Size | 13.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
475c920c2f275ca510269b9d95d9c39899dca668c34f1da02a5e4aee041895fc
|
|
BLAKE2b-256 checksum How to use checksums |
d8dfee44d31a8537fbd0b1b9a14e4f27788962c1b3fb7ce377cabde987915f1e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.12.3
|
Release files / voxelmap-5.1.1-py3-none-any.whl
| Download URL | voxelmap-5.1.1-py3-none-any.whl |
|---|---|
| Size | 11.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
e2a3e61f18f100344550d4a67c16384ae9768d6cd31ff45aa87003de78ba8c16
|
|
BLAKE2b-256 checksum How to use checksums |
ace871d54c3fcb435053b944609a3452d1823e00d37d7ef3e9e0ae139f7a4fdd
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.12.3
|
