This page lives at https://www.patrickmin.com/binvox/binvox.html, but is included in the wiki for completeness:

====== 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:

<code>
#binvox 1
dim 128 128 128
translate -0.120158 -0.481158 -0.863158
scale 7.24632
data
</code>

The first line (with ''#binvox 1'') is required (the '1' is a version number).

This can now (April 2024) also be a '2', i.e. binvox file format version 2. These files are produced by the new ''binvox_merge'' tool. The only difference with version 1 is that set voxels can have different values. In version 1 a set voxel would always be a 1 in the file, in version 2 this can be any number higher than 0 (up to 255).

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.

Three normalization transformation steps are printed to the terminal when you run ''binvox'', e.g.:

<code>
bounding box: [-4.26774, -4.46283, -3.51203, 1] - [3.73801, 4.85995, 3.53327, 1]
normalization transform:
(1) translate [4.26774, 4.46283, 3.51203, 1],
(2) scale 0.107264,
(3) translate [0, 0, 0]
</code>

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:

<code>
(x_n, y_n, z_n) = ((i + 0.5) / d, (j + 0.5) / d, (k + 0.5) / d)
</code>

(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):

<code>
translate <t_x> <t_y> <t_z>
scale <scale factor>
</code>

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.

===== Voxel ordering =====

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)'':

<code cpp>
int Voxels::get_index(int x, int y, int z)
{
    int index = x * wxh + z * width + y;
    // wxh = width * height = d * d
    return index;
}
// Voxels::get_index
</code>

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

In the new binvox format version 2, the value byte can of course be a number higher than 1. 


===== Sample code for reading a .binvox file =====

Click [[https://www.patrickmin.com/binvox/read_binvox.html|here]] for a sample function for reading a ''.binvox'' file.

Click [[https://www.patrickmin.com/binvox/read_binvox.cc|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 [[https://www.patrickmin.com/binvox/ReadBinvox.java|here]] for the same program in Java. Compile with ''javac ReadBinvox.java'', run it with ''java ReadBinvox <binvox filename>''.

Daniel Maturana wrote a [[https://github.com/dimatura/binvox-rw-py|reader/writer in Python]].

Click [[https://www.patrickmin.com/binvox/index.php|here]] to go back to the binvox page.

---

[[https://www.cs.princeton.edu/~min|Patrick Min]]

Last modified: Thu Dec 17 14:50:12 CET 2015