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: #binvox 1 dim 128 128 128 translate -0.120158 -0.481158 -0.863158 scale 7.24632 data 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.: 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] 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):

  1. 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)
  2. 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): 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

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

Click here for a sample function for reading a .binvox file.

Click 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 page.

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