For all of the little projects I’ve done with voxels and Python, I’ve had to create some kind of custom representation of voxel entities on the back end. This was sloppy, but not really a problem until I started adding a bunch of custom features to voxygen (which I’ll be writing about soon). Every conversion, load, and render required conversions from one model to another, and they were beginning to get jumbled.

I needed a data model for Voxel data that is both flexible and fast, which could handle all of the most common tasks like reading and writing .vox files, but also open doors for complex custom operations.

Existing solution #1: py-vox-io uses a nifty data type called a namedtuple for Voxel representation. In this scheme, each Voxel object knows its own x, y, and z coordinates. The included coordinates could be handy, but it requires us to store an extra three ints per voxel, which quadruples the size of the model. On entities with hundreds of thousands of voxels, that’s a lot of fluff that we can probably cut out if we’re clever.

Existing solution #2: NumPy N-dimensional arrays (ndarrays). Fast and extremely memory efficient, there’s no denying NumPy arrays are an excellent choice for storing large numbers of objects of the same data type. However, ndarrays lack functionality specific to voxels. I wanted something fully featured so that I wouldn’t have to rewrite IO, conversions, or functions like flip.

I’ve created my own solution: VoxyPy.

VoxyPy is a high level data model for voxels. It has two main components: the Voxel class and the Entity class.

Voxel

Voxel is a small class representing one cell in an Entity.

Voxel colors are represented as indices from 0 to 255, where 0 means blank. These indices refer to actual RGB colors in a 1×255 .png file. So, for example, if the 10th pixel in the texture is red, then a voxel with value 10 will render as red.

It very thinly wraps a primitive int, allowing easy conversion and equality operations. Voxels and ints can be used interchangeably in most operations.

The Voxel class allows for a special addition/subtraction case: Adding 1 to 255 causes the color to wrap to 1 instead of 0. Similarly, subtracting 1 from 1 causes the color to go to 255 instead of 0. This is because 0 is blank in Voxel texture language, so if we wanted our color palette to repeat without a gap, we’d have to make a clever manual skip every time the index would be set to 0.

Entity

Entity basically functions as a space suit for a private ndarray called _voxels. It contains integer representations of each voxel within a model. By keeping _voxels private, we can manage user access, and also provide an efficient interface which gives and receives Voxel objects or integers on nearly even footing.

VoxyPy is currently available from PyPI/pip! Just install using

pip install voxypy

More documentation, including IO and example code, is located in the VoxyPy GitLab repo.

Til next time, happy voxeling.