How Cubrim compresses, step by step

The input bytes become a sequence of values. Each position in the file carries one value in the range 0–255. This is the raw material the cube is built from.

Every value lands at a coordinate inside an N-dimensional cube. By default N=2 and the edge is 256, so the file becomes a 256×256 grid: position i maps to (i mod 256, i ÷ 256) via the mixed-radix φ function. The value at each cell is its height and colour.

Only the cells that actually hold data are kept. Along each axis Cubrim records the distance from one populated point to the next — the gaps — instead of absolute coordinates. Sparse data turns into a short list of gaps.

The gap streams are run-length encoded: a run of identical gaps collapses into a single (value, count) pair. Regular, clustered layouts shrink dramatically here.

The value stream is packed. The default packs each value into the fewest fixed bits; clustered streams use run-length codes; and the entropy scheme assigns short canonical-Huffman codewords to frequent values and long ones to rare values.

A compact header (the parameters needed to rebuild everything) is prepended and the streams are concatenated into the final archive. If the cube path would not beat storing the input verbatim, Cubrim falls back to raw-store — so output never grows. Decoding reverses every step exactly: lossless, byte for byte.