Mesh Functions

VoxelMap provides optional mesh reconstruction utilities. Install with:

pip install voxelmap[mesh]

These tools use scipy, scikit-image, and pyvista for meshing and interactive viewing.

—

ImageMesh

ImageMesh converts 2D image arrays into convex-hull meshes.

import cv2
from voxelmap.mesh import ImageMesh, MeshView

img = cv2.imread("land.png", 0)  # grayscale
ImageMesh(img, out_file="land.obj", L_sectors=15)
MeshView("land.obj", mode="flat", flat_color="white", alpha=0.8)

➡ Produces land.obj and opens a 3D PyVista window.

—

MarchingMesh

MarchingMesh converts voxel arrays into detailed triangle meshes using the Marching Cubes algorithm.

import numpy as np
from voxelmap import Model
from voxelmap.mesh import MarchingMesh, MeshView

arr = np.random.randint(0, 2, (20, 20, 20))  # random voxel array
model = Model(arr)
model.set_color(1, "blue")

MarchingMesh(model.array, out_file="random.obj", palette=model.palette, pad=1)
MeshView("random.obj", palette=model.palette, mode="solid")

➡ Produces random.obj with colors preserved and displays it interactively.

—

MeshView

MeshView is a lightweight wrapper around PyVista for visualizing .obj meshes. It can be used after ImageMesh or MarchingMesh.

from voxelmap.mesh import MeshView

# Wireframe only
MeshView("random.obj", mode="wireframe", wireframe_color="green", background_color="black")

# Solid + edges
MeshView("random.obj", palette={1: "red"}, mode="both", wireframe_color="magenta")

Options: - mode="solid" → surfaces colored by palette - mode="wireframe" → only edges - mode="both" → fill + edges - mode="flat" → single solid color (ignores palette) - palette={id: "color"} → map voxel labels to colors - background_color="black" → set viewer background - wireframe_color="green" → change edge color - alpha=0.8 → transparency

—

When to use which?

ImageMesh → fast, low-poly meshes from 2D images (landscapes, silhouettes).
MarchingMesh → high-resolution meshes from 3D voxel data.
MeshView → universal visualization of .obj meshes with multiple viewing modes.