Here's the quick (?) tutorial, for people not familiar with "cmd", etc. This tutorial is also now
Minepedia, so go there to improve it.
Get the software and some models. To make it easy on you, I've bundled up the latest (as of 11/17/2010) 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 - bookmark it. 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,
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
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
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") 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 here or PM me or, better yet, Patrick.
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 all the time, so keep downloading them if you're using them. You can always check the version and options supported in binvox by just typing "binvox" (no arguments) into the CMD window.
Eric
26
).
