I/O Helpers

VoxelMap supports saving and loading models in lightweight formats. Install extras if you want I/O utilities:

pip install voxelmap[io]

—

Saving and Loading JSON

The simplest way to persist a model is with JSON.

import numpy as np
from voxelmap import Model

arr = np.ones((3, 3, 3))
model = Model(arr)
model.set_color(1, "red")

model.save("cube.json")   # saves array + palette
loaded = Model()
loaded.load("cube.json")

loaded.draw_mpl("custom")

➡ This saves both the voxel array and its palette, so your colors are preserved.

—

Saving and Loading TXT

VoxelMap can also export voxel arrays to a plain text format (.txt). This is useful for interoperability with voxel editors like Goxel.

model.save("cube.txt")   # export
model2 = Model()
model2.load("cube.txt")

—

OBJ Export (with Meshing)

VoxelMap does not directly save .obj from the core. Instead, use the mesh extras (ImageMesh or MarchingMesh) to create .obj files:

from voxelmap import Model
import numpy as np

arr = np.random.randint(0, 2, (10, 10, 10))
model = Model(arr)

model.MarchingMesh("random.obj")  # requires voxelmap[mesh]
model.MeshView("random.obj")

—

When to use what?

JSON → best for full reproducibility (stores array + palette).
TXT → good for interchange with voxel editors.
OBJ → polygonal mesh, use when exporting to Blender / 3D tools.