ViPaq Protocol

ViPaq packs one bin and its items into a single copy-pastable string. Binacle.Net’s packing responses get large with many items; ViPaq condenses one result - a single bin plus the items packed into it - into a string that is small to store, cheap to send and easy to share.

It carries:

That is everything needed to redraw the packing, and nothing else. Items come back in the order they were sent. This page is the wire format as Binacle.Net v3.1.1 writes and reads it.

🚨 The format changed in v3.0.0. Strings produced by v2.1.1 and earlier do not decode here, and strings produced here do not decode there. There is no fallback reader. An old string is rejected with a format error rather than misread, so the failure is visible - but stored strings are worth regenerating after the upgrade.

πŸ“Œ Structure

A ViPaq blob is a two byte header followed by a body:

[ Header: 2 bytes ][ Body ]

🧾 Header

Two bytes, one job each. Byte 0 says how to read the body, byte 1 says how wide its integers are.

Byte 0 - form
Bits Field Values
7-6 Version 0 for this format. 1-3 are reserved.
5 Compressed 0 the body is raw, 1 the body is compressed
4 Layout 0 row-major, 1 columnar
3-0 reserved always 0, a decoder rejects anything else
Byte 1 - integer widths
Bits Field
7-6 BinDimensionsWidth
5-4 ItemDimensionsWidth
3-2 ItemCoordinatesWidth
1-0 reserved, always 0

Compressed and Layout describe that one blob, not the format. An encoder picks them per blob and a decoder obeys them, so two blobs from the same version can differ in both.

πŸ“¦ Body

The body carries the item count, the bin dimensions, then the items:

[ Item count: uint16 ][ Bin L, W, H ][ Items ]

Layout decides only how the items are arranged. The count and the bin dimensions are the same either way.

Row-major (Layout = 0)

Each item is written whole - its three dimensions, then its three coordinates - before the next item.

L W H X Y Z | L W H X Y Z | L W H X Y Z | ...
Columnar (Layout = 1)

Each field is written for every item before moving on to the next field. Six runs, each as long as the item count.

L L L ... | W W W ... | H H H ... | X X X ... | Y Y Y ... | Z Z Z ...

Columnar puts values of similar size next to each other, which usually compresses better. Row-major is easier to read in a hex dump. Neither is required - the header bit says which was used.

πŸ”’ Integer Widths

Each of the three sections - bin dimensions, item dimensions, item coordinates - is stored at one width, chosen independently:

Code Bytes per integer Largest value
0 1 255
1 2 65,535
2, 3 reserved a decoder rejects these

Widths are fixed per section, not per value: every item shares one dimensions width and one coordinates width. An encoder picks the smallest width that holds the largest value in the section.

The three sections are sized separately because real data needs them to be. A bin of 5000x2000x2000 holding items no larger than 200 gives 16 bit bin dimensions, 8 bit item dimensions and 16 bit coordinates.

πŸ—œοΈ Compression

The Compressed header bit records what the encoder did. It is not a hint to guess at.

The codec is raw DEFLATE (RFC 1951), with no zlib or gzip wrapper. The compressed stream is the DEFLATE bit stream and nothing else.

Compression is not applied by size. The encoder compresses the body, keeps whichever of the two is shorter, and sets the bit to say which it kept - so a blob is never made larger by compressing it. A decoder accepts both.

πŸ”€ Text Form

The stored and shared artifact is base64, and the format is optimized for it.

πŸ“ Limits

Field Rule
Bin dimensions L, W, H 1 to 65,535
Item dimensions L, W, H 1 to 65,535
Item coordinates X, Y, Z 0 to 65,535. Zero is valid - an item flush to the bin origin.
Item count up to 65,535

A value outside these ranges is an error when encoding. Nothing is clamped or widened silently.

πŸ§ͺ Example

A bin of 10x20x30 holding one item 1x2x3 at (4,5,6).

Every value fits in a byte, so all three sections use the 1 byte width, and the encoder wrote it row-major and uncompressed. Both header bytes are therefore 0x00:

00 00  01 00  0A 14 1E  01 02 03  04 05 06
^byte0 ^count ^bin      ^dims     ^coords
   ^byte1

πŸ–₯️ Try it

Five known-good strings, ready to paste. Each is the viPaqData field of a pack response for one of the demo’s own worked examples, packed with First Fit Decreasing. Paste one into the ViPaq Decoder and it draws the bin with the items in it.

Five boxes, packed full

Bin 30x20x20, holding one 20x20x20 and four 10x10x10. 100% full.

AAAFAB4UFBQUFAAAAAoKChQAAAoKChQKAAoKChQACgoKChQKCg==
Ten boxes, two sizes

Bin 60x35x25, holding six 25x8x25, two 16x10x25 and two 10x16x25. 88% full.

AAAKADwjGRkIGQAAABkIGRkAABkIGQAIABkIGRkIABkIGQAQABkIGRkQABAKGQAYABAKGRkYAAoQGTIAAAoQGTIQAA==
Twenty-four cubes

Bin 40x30x25, holding twenty-four 10x10x10. 80% full.

AAAYACgeGQoKCgAAAAoKCgoAAAoKCgAKAAoKCgAACgoKChQAAAoKCgoKAAoKCgoACgoKCgAUAAoKCgAKCgoKCh4AAAoKChQKAAoKChQACgoKCgoUAAoKCgoKCgoKCgAUCgoKCh4KAAoKCh4ACgoKChQUAAoKChQKCgoKCgoUCgoKCh4UAAoKCh4KCgoKChQUCgoKCh4UCg==
Thirteen boxes, mixed sizes

Bin 35x30x25, holding one 20x18x16, four 15x15x10 and eight 10x10x8. 81% full.

AAANACMeGRQSEAAAAA8PChQAAA8PChQPAA8PChQACg8PChQPCgoKCAASAAoKCAAAEAoKCAoSAAoKCAASCAoKCAoAEAoKCAoSCAoKCAASEAoKCAoSEA==
Eight flat items

Bin 50x50x12, holding eight 24x24x5. 77% full.

AAAIADIyDBgYBQAAABgYBRgAABgYBQAYABgYBQAABRgYBRgYABgYBRgABRgYBQAYBRgYBRgYBQ==

πŸ“– Full Specification

The normative wire specification, including the decoding order, everything a decoder must reject, and further worked examples, lives with the source: