Tutorials/Programs and editors/Binvox

Binvox is a command-line program that turns 3D files into .binvox building plan files or into .schematic files for import using MCEdit. A .binvox output file can then be viewed by the interactive "viewvox" OpenGL program, provided by the same author. The main page for these programs is on Patrick Min's site.

The process of converting a set of 3D polygons to their equivalents in blocks is called "voxelization". Binvox voxelizes, viewvox shows the results. Voxelization is not a perfect process, in the sense that there are decisions to be made. Other than the output resolution, the most important decisions revolve around how much coverage of a voxel by a model for that voxel to be considered "filled" by the model. For this reason, there are many ways to control binvox's results.

Supported Systems
Binvox and viewvox run under Windows, Mac, and Linux systems. The viewvox viewing program uses OpenGL and GLUT.

Download
For Windows, download vox_package.zip and unzip to a directory. This distribution also includes two sample 3D files and .BAT files to voxelize them. See the README.txt in that distribution.

For other platforms, the binvox and viewvox programs and GLUT library must each be downloaded separately.

File Formats
The following 3D file formats can be read in: Wavefront OBJ, VRML 2.0, UG, OFF, DXF, XGL, POV, BREP, PLY, JOT. Only polygons are supported for most of these (VRML 2.0 is almost fully supported). In reality, Wavefront OBJ is probably best supported.

Models can be created or found on the web, e.g. at the Turbosquid website (tip: sort by cost). To convert from 3DS to OBJ, programs such as MeshLab can be used.

For output, the .binvox file format (the default) is viewable with the viewvox program. Simply type "viewvox .binvox" to run the viewer. A .schematic file can be output instead by using "-t schematic" when running binvox. Along with the "-bi " option, to specify what type of blocks are generated, the .schematic files generated can be imported into worlds by using MCEdit.

Gallery
A photo gallery of creations is maintained by the program's author. If you make anything, send him (address here) photos of your hand-made creations and he'll probably add them.

Binvox commands
Current options for binvox (find by running "binvox" without any arguments):

Usage: binvox [-d ] [-t ] [-c] [-v] -d: specify voxel grid size (default 256, max 1024) -t: specify voxel file type (default binvox, also supported: hips, mira, vtk, raw, schematic) -c: z-buffer based carving method only -dc: dilated carving, stop carving 1 voxel before intersection -v: z-buffer based parity voting method only (default is both -c and -v) -e: exact voxelization (any voxel with part of a triangle gets set)(does not use graphics card) Additional parameters: -bb     : force a different input model bounding box -ri: remove internal voxels -cb: center model inside unit cube -rotx: rotate object 90 degrees ccw around x-axis before voxelizing -rotz: rotate object 90 degrees ccw around z-axis before voxelizing both -rotx and -rotz can be used multiple times -aw: _also_ render the model in wireframe (helps with thin parts) -fit: only write the voxels in the voxel bounding box -bi : when converting to schematic, use block ID  -down: downsample voxels by a factor of 2 in each dimension (can be used multiple times) -dmin : when downsampling, destination voxel is on if >=  source voxels are (default 4) Supported 3D model file formats: VRML V2.0: almost fully supported UG, OBJ, OFF, DXF, XGL, POV, BREP, PLY, JOT: only polygons supported Example: binvox -c -d 200 -t mira plane.wrl

Viewvox controls
Tip: to see an plan view of the model's levels for building, type "pannntsy" (3 n's) when viewvox starts up. "j" and "k" then move through the horizontal levels of the model, and the underlying level's blocks are shown in semi-transparent gray and white.

Current controls for viewvox:

Mouse left button = rotate middle     = pan right      = zoom Key r          = reset view arrow keys = move 1 voxel step along x (left, right) or y (up, down) =,-        = move 1 voxel step along z

q          = quit

a          = toggle alternating colours p          = toggle between orthographic and perspective projection x, y, z    = set camera looking down X, Y, or Z axis X, Y, Z    = set camera looking up X, Y, or Z axis 1          = toggle show x, y, and z coordinates

s          = show single slice n          = show both/above/below slice neighbour(s) t          = toggle neighbour transparency j          = move slice down k          = move slice up      g           = toggle show grid at slice level

Tutorial


There is a Mac-centric tutorial.

Here is the original tutorial and thread. The tutorial is repeated and updated here, so that users can improve it over time.

Get the software and some models. To make it easy on you, I've bundled up the latest binvox and viewvox programs, the GLUT DLL, and two models with batch files to display them. Get it all HERE and unzip it to somewhere. Read the README.TXT in there if you just want to quickstart without reading further. Mondeus' video showing how it's used may also help you - basically, double-click a .bat file and the corresponding model is converted and displayed.

If you want to do it the hard way, but are assured of getting the latest versions, do the following. You should know about Patrick's minecraft page. First, download binvox and viewvox into some directory. You could put them on the desktop, if that's how you roll. You will also need to download GLUT and put the DLL in that zip file into either the same directory as binvox, or if you know what you're doing, your Windows system DLL directory (e.g. on Windows 7, C:\Windows\SysWOW64).

Second, find a model to convert and put it in the binvox directory, for simplicity. The previous post has a number of sites for free models, and there are more out there, e.g. TurboSquid's, 3dvia's, Princeton's, and Nasa's. You can use any model directly that is in one of these formats: VRML, OBJ, OFF, DXF, PLY and STL.

If you have a model in another format, you can use Milkshape[/url], Blender, or another model converter and convert it from your format to something binvox will read.

Anyway, let's take a nice simple model from Aim*SHAPE, a hand model. You don't need to get the high-res model, a low-resolution mesh is fine - after all, it'll become blocks. So pick the third one from the left, in the bottom row. Once you've downloaded it, unzip it to wherever you put binvox and viewvox, for simplicity. The only file you'll actually need is gipshand2-3k.obj, which is actually a text file of the model's data.

Now, click the Start menu button (lower-left corner of your screen) and in the search line at the bottom of the screen type:

cmd

A black text window will open up. Go to wherever you put your binvox file and model, e.g. for my desktop it's:

cd C:\Users\Eric\Desktop

(though I decided to use another directory, since I don't like to clutter my desktop). To run binvox, you then type:

binvox gipshand2-3k.obj

For a minute or so you'll see a bunch of hand renderings in the upper left of your screen. This is binvox slicing the model up and finding the voxels. This creates a file called "gipshand2-3k.binvox" - this name gets mentioned in the CMD window, looking like this:

Voxels::print_filled_area area filled: 185 x 92 x 243 integer bounding box: [6,6,7] - [190,97,249] writing voxel file... VoxelFile::write_file(gipshand2-3k.binvox) Wrote 426642 set voxels out of 16777216, in 148528 bytes[/code]

The top part shows how large the model is; the third value is the height, 243 blocks high. Too high for a Minecraft world, but we'll get to size in a minute.

''If you didn't get anything, make sure you are in the same directory! That is, "cd" is "change directory" - look carefully for how I used it above. If you don't know DOS commands, make your life simple and put the binvox.exe program (and related files) and your model file in the same directory, the same location. This is the #1 problem people have with running binvox, not understanding that binvox needs to know where your file is located.''

To view that output file, type:

viewvox gipshand2-3k.binvox

Tip: you can use the up-arrow in the CMD window to bring up the command you just typed (you can press it multiple times) and the left and right arrows and delete keys to change what's on the line. So in this case, instead of typing "gipshand2-3k.obj" again, you could up-arrow and change "obj" to "binvox" and "bin" to "view". Your call.

You should get something like this (the CMD window is scrolled up a bit, to show the command line I typed in, though oops I cut off the end of my command line):



Viewvox shows some very useful info for minecrafters, e.g.

Voxels::remove_internal_voxels removing 383513 voxels, which leaves 43129 voxels[/code]

This tells you how many blocks you'll need to build something. To close viewvox's window, click on the CMD window and type Control-C. Don't ask me why. You should get a ">" prompt when you're really done.

However, by default, binvox makes models into block sets that are 256 blocks high (or long, or deep, whatever's largest). We'd like say 64. Now, you could type this:

binvox gipshand2-3k.obj -d 64

"-d 64" says how many blocks high you'd like the scan. Technical note: On Windows machines there's a GLUT bug that the window cannot be smaller than around 120 voxels (Linux doesn't have this problem). We added some code internally to increase the resolution and then downsample, so it sort of works the same. The manual way around this problem is:

binvox gipshand2-3k.obj -down -down

What each "-down" does is halve the resolution. We start at 256 by default, so divide by 2, and 2 again, i.e. 4, gives 64. Another way around this problem is to use the "-e" option, which does an "exact" (any voxel overlapped gets tagged) voxelization:

binvox gipshand2-3k.obj -d 64 -e

Exact voxelization avoids any precision problems that come from using the GPU to compute the voxelization. The downside of exact voxelization is that there is no further control. All voxels that are touched by any polygon are flagged, which can sometimes look bad. There are numerous options to control the density, whether edges get emphasized, etc.

Whichever you use, a new binvox model is output. Use viewvox on this new model, which you'll notice is called gipshand2-3k_1.binvox. So type:

viewvox gipshand2-3k_1.binvox

You can control the view of the object by using the mouse. Left-mouse button held down rotates, middle mouse pans, right mouse zooms (in a funky way). Here's a view of our model, rotated:



Looks pretty good, and viewvox says the hollow shell has 2471 blocks. At say 5 seconds a block, that's about 3.5 hours of building time. But, how to build it? Very easy (other than all the heavy lifting):

First, press the S key. This toggles between showing the whole model and just a horizontal slice. It's still hard to count blocks off, so press the A key. This causes checkerboard coloring to be used. You want to see the slices above and below? Hit N to toggle these neighbors on, then T to make them semitransparent. Hitting 1 toggles the coordinate numbers on. Note that in the CMD window all of these options are listed at startup.

Here's a view after all that, a horizontal slice through the middle of the model.



Pro tip: Personally, now that I'm used to the program, I always type "antspy" (think "ant spy", or "pantsy" if that works for you) when starting up viewvox. This gets me into an overhead view, showing one layer, with transparency above and below. I usually hit N again two more times, to show just the neighboring layer below.

You of course want to start at the bottom of the model and build up. Hitting the J key takes you to the slice below, K above. You can see what number slice you're on (numbering starts at 0) by looking in the CMD window.

That's the basics, and that's only if everything goes really well. First, I picked a model that was "watertight", that would not leak water if you filled it, and had no "hanging edges". Most models you find on the internet will not be like this, they're usually surfaces just glued together to get an effect. So, you'll need to try out various options on the command line. Here are the vital ones for binvox.

-c - If your model is not watertight, this is the option you really must use. It actually renders much faster, but can miss nooks and crannies.

-dc - small features can be missed when voxelizing. This option attempts to thicken the model.

-aw - draw all the edges of the model. This is another thickening technique for very thin features.

-dmin 1 - when using "-down", make the smaller model's voxel get filled if any voxel in the larger model is filled. Another thickening technique.

-rotx - rotate the model 90 degrees along the X axis. In viewvox the X axis is red, Y green, Z blue (RGB). You can do this multiple times.

-rotz - rotate 90 degrees along the Z axis. Many models come in with their "up" direction different than what binvox expects. Just keep trying -rotx and -rotz commands to get the thing oriented correctly.

-cb - this isn't critical, but I always use it (except in the tutorial above, just to keep things simple). The model is usually shifted so that it is in the lower left hand bottom corner of the cube formed. This option puts the model in the middle, making it easier to read the coordinate axes. It's up to you.

-t schematic - instead of outputting to a .binvox file, output to a .schematic file. This type of file can be imported directly into a Minecraft world by using MCEdit or other tools.

You can see more command options if you type just "binvox". After fussing with these options awhile, the voxelizations are usually about 98% correct - I find I'd need to trim a block here, add a block there.

As an example, here's a knight model that I converted with:

binvox chevalier.obj -d 536 -aw -c -dc -cb -dmin 1 -down -down -down



Have fun, and post any problems on the forums.

If you want to import models directly into a Minecraft world, which to me is entirely unimpressive without all the sweat and tears of actually building it, read about that option here.

New binvox and viewvox versions and options are being added fairly frequently, so keep checking for the latest download. You can always check the version and options supported in binvox by just typing "binvox" (no arguments) into the CMD window.