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 data 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 last header line must read "data".

Normalization and Mesh Correspondence

Before voxelizing, binvox normalizes the mesh such that it fits inside a 0.95x0.95x0.95 cube with its origin at (0.025, 0.025, 0.025). The unit cube with origin at (0, 0, 0) is then voxelized, ensuring an empty "shell" around the voxel model (unless you voxelize at low resolution). The three normalization transformation steps are printed to the terminal when you run binvox, e.g.: bounding box: [-0.0174716, 0.493843, 0.0618374, 1] - [0.0154136, 0.613638, 0.340182, 1] normalization transform: (1) translate [0.0174716, -0.493843, -0.0618374, 1], (2) scale 3.41304, (3) translate [0.025, 0.025, 0.025] 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 three 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 to go back to the binvox page.

Patrick Min
Last modified: Mon Oct 9 21:06:17 CEST 2006