converting 3D models for building in minecraft using [binvox] and [viewvox]

binvox     viewvox    

(if you're looking for a free 3D model converter, try meshconv)


binvox and viewvox can be of help when trying to build a voxelized version of a 3D mesh in minecraft.
Executables are available for Linux, Mac OS X, and Windows.

Do send me screenshots of the models you have built!

Click on the image on the right to see the gallery in the picasa web album binvox/viewvox for minecraft.

Note to Windows users: binvox and viewvox are commandline tools, which means they must be run from a command shell. In Windows, start a command shell with Start → Run → cmd (enter), then use the cd command to change to the folder where you have binvox.exe, viewvox.exe, and the model you want to convert. Send me a note if anything is unclear. Eric Haines wrote a good step-by-step tutorial for Windows users, and has created a quickstart package of all software needed for Windows (including two sample models). Here is a tutorial in German (Tutorial auf Deutsch).

(I've had one report from a Windows user where the downloaded binvox and viewvox files had to be renamed to binvox.exe and viewvox.exe)

Note to Mac users: the same goes for the Mac, you should run binvox and viewvox from the Terminal: after downloading them into the same folder as your model, do:
  • chmod 755 binvox
  • chmod 755 viewvox
  • You can then run the programs like this:
    to get a summary of the commandline options.

Here is a Mac tutorial, written by Manic Miner. If you have questions about how to use the Terminal app, please search Google for "mac os x using terminal".

Note to Linux users: I assume you're familiar with the commandline :-) (but do send me a note if something is unclear)


Assume we have a 3D model like the one at the top left, in a file mug.wrl.

Step 1: voxelize it

./binvox -d 32 -c mug.wrl
which will create a file mug.binvox.

View the result with viewvox:
./viewvox mug.binvox
(the x, y, and z in the image were added afterwards):

In viewvox, the x axis is red, the y axis green, and the z axis blue. Some models (like this one) use the z axis as the up axis, whereas viewvox uses the y axis. You can fix this by passing -rotx parameter to binvox, which makes it rotate the object by 90 degrees counter-clockwise around the x axis, effectively changing the up axis from z to y:
./binvox -d 64 -c -rotx mug.wrl

How to voxelize thin features

If your model has no thin features, you can skip this section.

If the model has thin features that are lost in the voxelization, you may want to voxelize at a higher resolution and downsample:
./binvox -d 256 -down -down -c mug.wrl
You may also want to play with the -dmin parameter, which sets the minimum number of source voxels that have to be on in the 2x2x2 source cube for a destination voxel to be on. It defaults to 4, but for very thin features you could try 2, for example:
./binvox -d 256 -down -down -dmin 2 -c mug.wrl

If the model has features with zero width (e.g. a single triangle/quad/etc.), you could use both the -aw option ("add wireframe"), which also renders the model in wireframe (only when carving), which does render zero width triangles seen from the side, and -dc ("dilated carving"), which doesn't carve away as much (the carving stops one voxel before the intersection), for example:
./binvox -d 256 -down -down -c -dc -aw mug.wrl

How to voxelize only part of the model

Suppose you have a model of a gargoyle, and you want to voxelize just the head:

You can see from the axes in the image that this means we need to limit the voxelization in the z direction. You can crop the rendering of binvox with the -bb parameter, noting that your model will always be in the unit cube (i.e. the cube from (0, 0, 0) to (1, 1, 1)). Examine the whole voxel model (voxelized with binvox -d 64 -cb) to estimate approximately where you need to crop:

The bottom image shows the voxel model from the top (press y in viewvox to get the view straight from the top, and possibly p to switch to an orthographic projection). You can see the head ends approximately 25 voxels from the left. 25/64 is about 0.4, to we'll limit voxelization to 0.4 in the z direction:
binvox -d 64 -cb -bb 0 0 0 1 1 0.4 -fit gargoyle.ply
(-cb centers the model in the unit cube, -fit makes sure a voxel model is written with only the voxels in its bounding box). The result:

Note: because the exact voxelization method (select with -e) doesn't use OpenGL, the -bb parameter has no effect. Also, you may have to experiment with using the voting method only (select with -v) for example, because cropping a model is likely to make it hollow.

Step 2: visualize slice by slice

./viewvox mug.binvox

By default viewvox removes the internal voxels (creating a "hollow" model). If you want to keep the internal voxels, run it like this: ./viewvox -ki mug.binvox.

The keyboard and mouse commands available in viewvox are printed in the terminal window you run it from ("cmd" in Windows, "Terminal" in Mac OS X).

Now, typically you'd press s to show one slice of the voxel model, k and j to show the next slice up and down (the current slice index is shown in the terminal window), and a to show the voxels with alternating colours, for example:

To better examine the correspondence between successive slices, press n to show the slices above and below the current slice (optionally t to make these slices transparent). The right image shows a top view in orthographic projection.

To build the model in minecraft, I run minecraft and viewvox side-by-side so I can see where the blocks should go.

Obviously many improvements are possible, send me your suggestions.

Some recent additions:

  • show coordinate values in the image (press 1)
  • switch between orthographic and perspective projection (press p)
  • look straight down the X, Y, or Z axis (press x, y, or z) (X, Y, or Z to look from the other side)
  • store and restore settings (i.e. when you start viewvox again with the same voxel model, it uses the same camera and other settings)
  • use keys to step camera (left, right, etc.) one voxel at a time
  • the grid now has a cell for each voxel, and can be shown at the bottom or at the slice level (press g)
  • both binvox and viewvox will show the size of the area filled by the voxel model, and its bounding box (thanks to Eric Haines who submitted code for this). You can crop the voxel model by this bounding box (-fit commandline parameter)
  • support for writing .schematic files
  • thick lines in the grid every 5 blocks
  • single slice view cycles through none-above-below-both
  • single slice view in shows slice number

Still on the to do list are:

  • add option for 45 degree rotation
  • show (x, y) coordinates on voxels
  • bookmark and jump to camera positions
  • coloured meshes to convert to coloured voxels
  • support for reading .3ds files, and for writing .vxl files
  • center a slice in the view
  • better "trackball style" viewing
  • show number of voxels in slice
  • compile with freeglut instead of glut (to prevent mouse wheel crash)
  • viewvox option to write an image file for each slice

Do check out...

Any comments/suggestions are welcome at . Do send me screenshots of the models you have built!

Last modified: Mon Jul 17 17:19:44 2023