Binary Cubical Sets

This page describes a suggested standard for encoding cubical sets in binary files, designed on March 11-13, 2006, by Pawel Pilarczyk, based on some ideas used in the BMP file format. Note that this is not the official standard, yet, it is still under construction, so any remarks and suggestions are most welcome.

Supported Sets

full cubical sets - sets which are unions of unitary cubes of full dimension
cubical sets - sets which are unions or elementary cubes of dimension possibly smaller than the dimension of the space
subdivided [full] cubical sets - sets which are the union of two or more full cubical sets with respect to the grid obtained by subdivisions of the original unitary cubical grid (see the rightmost picture below)

a full cubical set with respect to a uniform grid
a set of elementary cubes, not necessary of the maximal dimension
a set of cubes with respect to different grid sizes; smaller cubes come from subdivided bigger ones

General Suggestions

flexible word size in the header for small file size in case of small bitmaps and for virtually no limit in the size of large bitmaps
alignment of lines of pixels to the word boundary for fast processing
network order of bytes (big endian) in the header for portability
flexible order of bytes (bit or little endian) in the binary bitmap data to maximize the speed
concatenating files corresponds to taking the union of sets
possible compression of the binary data (bzip2, for instance)

The File Structure

OFFSET
(in bytes) LENGTH
(in bytes) MEANING

0 4 file signature (either "CUBE", or "CELL")

4 4 the size of the header in bytes, including the signature

8 8 the size of the binary data in the file in bytes (possibly compressed); further referred to as datasize

16 8 option flags: each bit set to 1 indicates that the given option is turned on, set to 0 - turned off:
– bit 0: the data is compressed using the bzip2 library
– bit 1: little endian bitmap data (set to 0: big endian)
– bit 2: the offset information is present (see below)
– bit 3: the downscaling information is present (see below)
– bit 4: the wrapping information is present (see below)

24 4 the dimension of the space (dim)

28 2 the size wd of the words in the dimensions below (in bytes)

30 2 the size bd of the words in the bitmap area (in bytes); note that each line is padded to the word boundaries

32 dim * wd the size of the bitmap in bits in each direction

32 + dim * wd dim * wd the offset of the bitmap in the full image (the coordinates of the lower left pixel in the full bitmap)

32 + (1 or 2) dim * wd dim * wd the downscaling factor in each direction (e.g., 4 means that the grid size is 1/4)

32 + (1 or 2 or 3) dim * wd dim * wd wrapping in each direction, a.k.a. periodic boundary conditions (0 means no wrapping, negative indicates a twist)

32 + (1 or 2 or 3 or 4) dim * wd datasize the binary data of the cubical set: bits set to 1 indicate that the cube is present in the set, bits set to 0 mean that the corresponding bit is not present in the set; for elementary cubes, use the idea by M. Mrozek (see the CAPD software) to store faces, edges and vertices in a bitmap

OFFSET (in bytes)	LENGTH (in bytes)	MEANING
0	4	file signature (either "CUBE", or "CELL")
4	4	the size of the header in bytes, including the signature
8	8	the size of the binary data in the file in bytes (possibly compressed); further referred to as datasize
16	8	option flags: each bit set to 1 indicates that the given option is turned on, set to 0 - turned off: – bit 0: the data is compressed using the bzip2 library – bit 1: little endian bitmap data (set to 0: big endian) – bit 2: the offset information is present (see below) – bit 3: the downscaling information is present (see below) – bit 4: the wrapping information is present (see below)
24	4	the dimension of the space (dim)
28	2	the size wd of the words in the dimensions below (in bytes)
30	2	the size bd of the words in the bitmap area (in bytes); note that each line is padded to the word boundaries
32	dim * wd	the size of the bitmap in bits in each direction
32 + dim * wd	dim * wd	the offset of the bitmap in the full image (the coordinates of the lower left pixel in the full bitmap)
32 + (1 or 2) dim * wd	dim * wd	the downscaling factor in each direction (e.g., 4 means that the grid size is 1/4)
32 + (1 or 2 or 3) dim * wd	dim * wd	wrapping in each direction, a.k.a. periodic boundary conditions (0 means no wrapping, negative indicates a twist)
32 + (1 or 2 or 3 or 4) dim * wd	datasize	the binary data of the cubical set: bits set to 1 indicate that the cube is present in the set, bits set to 0 mean that the corresponding bit is not present in the set; for elementary cubes, use the idea by M. Mrozek (see the CAPD software) to store faces, edges and vertices in a bitmap