[binvox]   3D mesh voxelizer


binvox     thinvox     viewvox     meshconv     —     binvox wiki    

Introduction

binvox is a straight-forward program that reads a 3D model file, rasterizes it into a binary 3D voxel grid, and writes the resulting voxel file.
It's a "spin-off" program of software I wrote while a graduate student at Princeton.

Features

Download

version 1.36, added 23 July 2023

Usage

Run binvox without parameters for a usage summary.

Note to Mac users: On newer version of OS X, X11 has disappeared. You'll have to install XQuartz before you can run binvox, unless you only intend to use it with the "exact voxelization method".
After installing, run XQuartz, select Applications → Terminal, and work from there, for example:
cd Downloads
mv binvox.dms binvox (if Safari renamed the file)
chmod 755 binvox
./binvox <model filename>

Note to Windows users: binvox is a commandline tool, which means it 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 and the model you want to voxelize.

Credits

If you use binvox for your (published) work, please add a reference to me, to this site (as a link, you could use http://www.google.com/search?q=binvox), and to the paper by F. Nooruddin and G. Turk (see next paragraph).
Click here for a BibTeX file with these references. Unfortunately I've already seen one recent scientific paper using my software without proper credit.

I'd love to hear what you use binvox for as well.

Note that binvox is free to download and use (in any environment). However, you are not allowed to charge others for the program. Type binvox -license for more information. You can support development by buying binvox: the paid version supports grids up to 4096×4096×4096, and output to a VRML 2.0 3D mesh.

Eric Haines contributed the code for the exact voxelization method.

Qingnan Zhou wrote the code for the Gmsh .msh output.

binvox uses the lib3ds library for reading .3ds files.

Related Software

References

binvox uses the parity count method and (a slight variation of) the ray stabbing method described by Fakir Nooruddin and Greg Turk in Simplification and Repair of Polygonal Models Using Volumetric Techniques, GVU technical report 99-37 (later published in IEEE Trans. on Visualization and Computer Graphics, vol. 9, nr. 2, April 2003, pages 191-205). To speed up the parity counting, a hardware z-buffer "slicing" method is used, based on an idea originally by Emil Praun.

Other references:

Feedback

Please send me e-mail (to patrick.n.min at gmail dot com) with your questions/comments/suggestions/bug reports. I'm also interested to hear about what you use binvox for.

Note that because of differences in hardware and software (drivers, the OpenGL implementation on your OS, etc.) the resulting voxel model will probably differ slightly from one setup to another.


Feature requests


Changelog

1.36: added support for output to a VRML 2.0 mesh (paid version only)(23 July 2023)
1.35: added -nf "normalization factor" option (useful if there are problems with surfaces close to the front clipping plane)(18 October 2022)
1.34: fixed bug that caused operations that came after downsampling to break (11 July 2021)
1.33: fixed several bugs related to grid dimensions over 1024 (24 March 2021)
1.32: fixed orientation and alignment issues for the NRRD format (7 March 2021)
1.31: fixed a bug when downsampling large voxel models (19 June 2020)
1.30: compiled a version that does not need the Xmu and Xxf86vm libraries (6 June 2020)
1.29: fixed bug with the -ignore parameter (26 January 2020)
1.28: intermediate version used for testing offscreen rendering (13 July 2019)
1.27: minor text updates (10 May 2019)
1.26: changed .vtk writer voxel ordering to conform to VTK standard (22 October 2017)
1.25: added -swapyz option, to support z, y, x voxel ordering (8 October 2017)
1.24: fix static linking of the lib3ds library under Linux (as done for 1.20)(September 6, 2017)
1.23: fixed bug that caused a crash when loading an .obj file missing a line terminator on the last line (August 20, 2017)
1.22: added -mb parameter for when voxelizing from .obj to .schematic (using the exact method) to specify block IDs in material names (March 6, 2016)
1.21: Windows 64 bit version
1.20: static linking of the lib3ds library
1.19: added support for .3ds files, thanks to the lib3ds library
1.18: fixed dimension ordering issue with .vtk output
1.17: fixed bug with -e method for triangles completely at max x/y/z
1.16: added support for writing .nrrd files
1.15: many fixes for large size (dimension > 1290) voxelizations (many thanks to Michelle Heller for debugging help)
1.14: Linux only: print information about maximum pbuffer size
1.13: added mesh memory usage info
1.12: added -ary parameter (for arbitary rotation around the y-axis)
1.11: fixed odd Windows-only memory allocation bug. Improved some error messages
1.10: fixed bug with -rotz parameter
1.09: fixed bug that limited voxel dimension to 1290
1.08: fixed hang on OBJ files with unterminated last line. Added VRML 1.0 support (still in alpha)
1.07: added support for writing Gmsh .msh files, code written by Qingnan Zhou
1.06: fixed handling of groups with empty names in OBJ files
1.05: use OpenGL custom clip planes for the -bb parameter (original implementation was buggy)
1.04: voxelizing inside entire unit cube now, to fix symmetry issues
1.03: bugfix for the .obj reader
1.02: bugfix for -e option in combination with fix for dimensions below the Windows minimum window size bug
1.01: bugfix for the -e option (triangles were voxelized too thick)
1.0: bumped version number to 1.0 :-). Workaround for Windows minimum window size bug. -aw re-enabled. Exact voxelization option -e added (written by Eric Haines, using triangle overlap code by Tomas Akenine-Möller)
0.48: carve voxelization rendering bug fix. -aw temporarily disabled.
0.47: added support for negative vertex indices in .obj files
0.46: added -bi parameter, for specifying .schematic block ID, fixed voxel ordering for .schematic files
0.45: fix for bug when using -fit together with -t schematic
0.44: support for writing of minecraft .schematic files. For doing the gzip compression, binvox uses the zlib library, version 1.2.5, © 1995-2010 Jean-loup Gailly and Mark Adler
0.43: -fit option, which crops the voxel model to its bounding box
0.42: the voxel bounding box (i.e. the filled area) is printed
0.41: added -aw option ("add wireframe"), which also renders the model in wireframe (useful for thin parts), and -dc option ("dilated carving") which stops carving in each direction 1 voxel before the intersection point.
0.4: added -rotx and -rotz options, to rotate object before voxelizing (useful for changing the up axis).
0.38: a bug fix of the .obj file reader.
0.37: the -bb parameter, which allows you to force a specific bounding box for the mesh.
0.35: the PLY reading code from the PLY tools was modified slightly to be able to handle Unix/Windows differences.


Patrick Min