ViPaq Protocol - ChrisMavrommatis/Binacle.Net GitHub Wiki

ViPaq is a protocol designed to efficiently encode packing information for one bin.

By using binary-level encoding, it maximizes data compactness, making it ideal for storage, transfer, and easy copy-pasting.

[!Warning] This feature is still experimental and can change at any time.

Purpose

ViPaq was developed with users in mind, offering a simple, copy-pasteable string format to easily store and transfer bin packing data. While Binacle.Net’s API returns packing data for each bin, the response can become quite large, especially with numerous items. ViPaq addresses this challenge by providing a more compact and manageable representation of the packing information.

How it works

ViPaq encodes the dimensions of the bin nd the dimensions and coordinates of each item in a serialized format that maintains the necessary data for visualization and decoding. The structure is straightforward, focusing only on the essential details:

[Header] [Number of Items] [Bin: Length, Width, Height] [Item 1: Length, Width, Height, X, Y, Z] [Item 2: Length, Width, Height, X, Y, Z] ... [Item N: Length, Width, Height, X, Y, Z]

• Header: Contains information necessary for decoding the data.
• Number of Items: Indicates how many items are encoded.
• Bin: Includes the bin's length, width, and height.
• Items: Each item is represented by its dimensions (Length, Width, Height) and its coordinates (X, Y, Z), listed in the order they were packed.

The resulting data is then Base64-encoded, which further simplifies transfer and storage, as it can be handled as a standard string.

ViPaq uses Variable Length Encoding (VLE) to optimize space and compress the data as efficiently as possible. For larger data sets, gzip compression is automatically applied once the encoded data exceeds a certain size threshold.