Introduction

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 Linux users: I assume you're familiar with the commandline :-) (but do send me a note if something is unclear)

Process

Step 1: voxelize it

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

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...

• the amazing Mineways tool, which makes it easy to create 3D prints (!) of parts of your world
  
  
• a Perl script for combining two minecraft stats/achievements files
• 
  try my Calcudoku puzzle site, which also has Killer Sudoku and Sudoku puzzles

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