BINVOX voxel file format specification
This format uses simple compression (run-length encoding) to
reduce filesize. The format was put together by Michael Kazhdan.
A .binvox file has a short ASCII header, followed by binary data.
The ASCII header
The header looks like this:
dim 128 128 128
translate -0.120158 -0.481158 -0.863158
The first line (with #binvox 1) is required (the '1' is a
version number). The next line specifies the depth, width, and height
of the voxel grid, which should all be equal.
The next two lines specify the normalization transformation (see the next
section) that was used to normalize the input mesh.
The last header line
must read "data".
Normalization and Mesh Correspondence
Before voxelizing, binvox normalizes the mesh such that it fits
inside a 1.0×1.0×1.0 cube with its origin at (0.0, 0.0, 0.0).
This is done with a translation and a uniform scale.
The unit cube is then voxelized.
transformation steps are printed to the terminal when you run binvox, e.g.:
bounding box: [-4.26774, -4.46283, -3.51203, 1] - [3.73801, 4.85995, 3.53327, 1]
(1) translate [4.26774, 4.46283, 3.51203, 1], (2) scale 0.107264, (3) translate [0, 0, 0]
Note that the third one can be ignored (it used to be relevant when normalization
was not to the unit cube).
As a consequence, each voxel in the voxel model has coordinates inside
the unit cube, which can be obtained as follows:
- given a voxel at (i, j, k) (with voxel index coordinates starting at (0, 0, 0), and voxel model
dimension d, these coordinates are:
(x_n, y_n, z_n) = ((i + 0.5) / d, (j + 0.5) / d, (k + 0.5) / d)
(the 0.5 is added to get the coordinates of the center of the voxel cell).
Next, there are two methods to compute the corresponding mesh coordinates
from (x_n, y_n, z_n):
- first method:
binvox now includes two extra lines in the header (which may
be omitted, viewvox and thinvox don't need them):
translate <t_x> <t_y> <t_z>
scale <scale factor>
First scale (x_n, y_n, z_n) by the scale factor, then translate them
by (t_x, t_y, t_z)
- second method:
Note the normalization transformation steps from the output
of binvox, and apply these in reverse to (x_n, y_n, z_n)
The first and second method should have the same level of accuracy,
but I still have to run some tests to verify this.
The y-coordinate runs fastest, then the z-coordinate,
then the x-coordinate. To illustrate, here is the get_index
function that computes the index in the 1D array of voxels
of a voxel with indices (x, y, z):
Voxels::get_index(int x, int y, int z)
int index = x * wxh + z * width + y; // wxh = width * height = d * d
} // Voxels::get_index
The binary voxel data
The binary data consists of pairs of bytes. The first byte of each
pair is the value byte and is either 0 or 1 (1 signifies
the presence of a voxel). The second byte is the count byte
and specifies how many times the preceding voxel value should be repeated
(so obviously the minimum count is 1, and the maximum is 255).
Sample code for reading a .binvox file
for a sample function for
reading a .binvox file.
here for a sample C++ program that reads
a .binvox file using the previous sample function, and writes
all voxel data to an ASCII file. You can compile this file using
g++ read_binvox.cc -o read_binvox, and run it by typing
read_binvox <binvox filename>.
Click here for the same program in Java.
Compile with javac ReadBinvox.java, run it with
java ReadBinvox <binvox filename>.
Daniel Maturana wrote a
reader/writer in Python.
Click here to go back to the binvox
Last modified: Thu Dec 17 14:50:12 CET 2015