binvox

This is a fairly popular use case, for which I had promised to write a tutorial many years ago..

I constructed the example from this 3D model on Sketchfab and a sphere, combined using the blender 3D modeller (https://www.blender.org):

In blender I selected the “heart” sphere, deleted it, and saved the puppet as an .obj file (File → Export → Wavefront (.obj), then select Z as the up axis). Next, Edit → Undo, and the same step to save the sphere to an .obj file.

The resulting files: puppet.obj and heart.obj

The goal is to voxelize them such that after merging they end up in the same spot relative to each other.

For this we need to determine the smallest bounding box that contains both models. Since in our example the “heart” is inside the body, we can use the bounding box of the puppet.

binvox determines a model's bounding box and prints it to the terminal:

# > binvox -d 128 puppet.obj

--- [binvox] mesh voxelizer, version 1.36, build #889 on 2023/07/23 12:28:17, running on Linux

...

  Mesh::normalize, bounding box: [-0.768355, -0.313688, -0.034275, 1] - [0.658711, 0.407517, 2.04301, 1]
  
...

Make a note of these values, and pass them to binvox when voxelizing the heart:

# > binvox -d 128 -bb -0.768355 -0.313688 -0.034275 0.658711 0.407517 2.04301 heart.obj

I will update binvox such that it prints these -bb parameters so they can be copied and pasted.

Now both models have been voxelized such that they can be merged, and be the same relative size and in the same relative position.

For this, the binvox_merge tool was created. It takes two binvox files as input, and produces a single binvox file:

binvox_merge heart.binvox puppet.binvox -o puppet_with_heart.binvox

binvox_merge simply sets an output voxel to 1 if it is set in the first input file, and to 2 if it is set in the second input file.

The output file is in the binvox version 2 file format, which supports different values for a set voxel (in the range 1-255).

TODO: some explanation/options needed about what happens when a voxel is set in both input files

viewvox (from version 0.51 onwards) supports viewing this new binvox version 2 file format.

A useful new feature is the ability to toggle “point rendering” of each input component, using the number keys 1 through 9 (so in our example only keys 1 and 2 are useful).