ViPaq Protocol - ChrisMavrommatis/Binacle.Net GitHub Wiki

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

By leveraging binary-level encoding, it maximizes data compactness, making it ideal for:

  • βœ… Storage – Efficiently save packing data
  • βœ… Transfer – Minimize bandwidth usage
  • βœ… Copy-Pasting – Easily share data as a compact string

[!Warning] ViPaq is still experimental and may change in future versions.

🎯 Purpose

ViPaq was developed to offer a simple, copy-pasteable string format for storing and transferring bin packing data.

While Binacle.Net’s API returns detailed packing data, responses can become large when handling numerous items. ViPaq addresses this by compressing the packing information into a compact, manageable representation.

βš™οΈ How it works

ViPaq encodes the bin's dimensions along with each item's dimensions and coordinates in a serialized format. This ensures all essential data is preserved for visualization and decoding.

πŸ“Œ Data Structure

[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]

πŸ› οΈ Components

  • Header: Contains metadata for decoding.
  • Number of Items: Specifies how many items are encoded.
  • Bin: Stores the bin’s length, width, and height.
  • Items: Each item is represented by its:
    • Dimensions β†’ (Length, Width, Height)
    • Position β†’ (X, Y, Z)

πŸ”‘ Encoding & Compression

  • βœ… Base64 Encoding β†’ Converts the binary data into a transferable string format.
  • βœ… Variable Length Encoding (VLE) β†’ Optimizes storage by reducing unnecessary data.
  • βœ… Gzip Compression β†’ Automatically applied when the encoded data exceeds a size threshold.