Skip to content

Instantly share code, notes, and snippets.

@enjrolas
Last active August 29, 2015 14:08
Show Gist options
  • Save enjrolas/540e2f40602a51492ab3 to your computer and use it in GitHub Desktop.
Save enjrolas/540e2f40602a51492ab3 to your computer and use it in GitHub Desktop.
L3D file format specification

L3D format for color volumetric data

revision 1

The L3D format is a simple, bitmap-like format for representing volumetric color data. The color of each voxel is represented as an R,G,B triplet. This revision does not support compression, making it unfeasible for large volumes, but suitable for small volumes, like those seen in LED cubes.

File contents:

A sample file is shown below, and this document will go into detail on the different options for every line.


8X8X8
format:ascii
0,0,0:0,0,0:255,255,255:0,0,0:255,255,255:0,0,0:255,255,255:
0,0,0:255,255,255:0,0,0:255,255,255:0,0,0:255,255,255:.....

First line: dimensions The first line in the file lists the resolution of the volume, in voxels. These are integer numbers, separated by 'X' characters. The dimensions are specified in the order of width X height X depth, according to this coordinate system: coordinate system

In the example, the volume is 8 voxels wide by 8 voxels high by 8 voxels deep.

Second line: format This line is always written in the style

format:<format>

In this revision, there are two possible formats: ascii and binary. The example file is in ascii format, meaning that every color value is written out as an ascii number and uses character delimiters to separate color values and voxels, making it human-readable, but space-consuming. The binary format represents each color value as a single byte and uses no delimiters, making it more compressed, but harder to read.

ascii format

In the ascii format, color values are written as a Red, Green, Blue triplet, with each value separated by a ',' character. For example, the color 255,0,0 represents a red color the hex equivalent of #FF0000. The color 0,0,255 represents a blue color, the hex equivalent of #0000FF, and so on.

Color triplets are delimited by ':' characters, so the expession:

255,255,255:0,0,0

would represent a white voxel followed by a black voxel.

In the worst case, ASCII format can consume 12 bytes of memory per voxel, so the 8x8x8 example volume could use 6.1kB.

binary format

In binary format, there are no delimiters, and each color value is written as a single ascii byte. For example, the white color 255,255,255 is written as

ÿÿÿ

Each voxel is represented by exactly three bytes, so there is no need for a delimiter. A white voxel followed by a gray voxel would be represented as

ÿÿÿ€€€

Every voxel takes three bytes of memory, so our example 8x8x8 volume would use 1.5kB of storage.


voxel data

The voxel data itself is written out as a long string of voxels. The order of the voxels goes according to this pseudocode:

for x=0, x<width, x++
	for y=0, y<height, y++
		for z=0, z<depth, z++
			writeColor( colorValue(x,y,z) )
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment