How Binacle.Net packs a box.

Two functions and three algorithms. Fit answers whether a set of items goes into a box. Pack answers the same thing and works out where each item sits.

Both are part of the same 3D bin packing API: one image, and you call whichever answer you need.

The two functions

Fit and pack

Fit is the pre-check. It takes your boxes and your items and returns a verdict per box, with the items that went in and the items that did not. Use it at checkout, where you need a yes or a no and nothing else.

Pack runs the same algorithms and returns the position of every item as well. Use it when someone downstream has to build the box, or when you want to draw the layout.

A fit response has no coordinates in it. If you need placement, call pack.

A worked example

A pack request, and where every item lands

Same shape as a fit request. The difference is in the response.

POST /api/v3/pack/by-custom

                  {
  "parameters": { "algorithm": "FFD" },
  "bins": [ { "id": "locker-M", "length": 40, "width": 30, "height": 20 } ],
  "items": [
    { "id": "box-a", "quantity": 2, "length": 10, "width": 10, "height": 10 },
    { "id": "box-b", "quantity": 1, "length": 25, "width": 18, "height": 12 }
  ]
}

                

RESPONSE

                  {
  "result": "Success",
  "data": [
    {
      "result": "FullyPacked",
      "bin": { "id": "locker-M", "length": 40, "width": 30, "height": 20 },
      "packedItems": [
        { "id": "box-b", "length": 25, "width": 18, "height": 12, "x": 0,  "y": 0,  "z": 0 },
        { "id": "box-a", "length": 10, "width": 10, "height": 10, "x": 25, "y": 0,  "z": 0 },
        { "id": "box-a", "length": 10, "width": 10, "height": 10, "x": 0,  "y": 18, "z": 0 }
      ],
      "unpackedItems": [],
      "packedItemsVolumePercentage": 100,
      "packedBinVolumePercentage": 30.83
    }
  ]
}

                

All three items are placed, and the response says exactly where each one sits.

The coordinates are the corner of each item inside the box, in the same units you sent. The first item sits at the origin; the two after it are placed against what is already there.

Algorithms

The three algorithms

All three sort the items by decreasing size and then differ in where they put each one. You pick one per request.

First Fit Decreasing

FFD

Does: Places each item in the first space it finds that holds it, without looking for a better one
Costs: May leave space unused that a slower search would have filled

Worst Fit Decreasing

WFD

Does: Places each item in the space that leaves the most room around it
Costs: Spreads items out, which helps with distribution more often than with space

Best Fit Decreasing

BFD

Does: Keeps the space left around each placement as small as it can
Costs: Examines the candidate spaces for each item rather than taking the first that fits

Which one is fastest, or packs tightest, depends on your data and on the version you run. These describe what each algorithm does, not how they rank against each other. If it matters to your workload, measure all three on your own boxes and items.

What the answer means

What a yes means, and what a no does not

All three are heuristics. They are built to run in the time a checkout page has, and that choice has a consequence in each direction.

A yes is reliable. When Binacle.Net says the items fit, they fit. It does not report a placement it could not make, and the pack endpoints will show you the placement it found.

A no is weaker. It means this algorithm did not find an arrangement, not that no arrangement exists. In rare cases another algorithm, or the same items in a different order, finds one. That is the trade the speed is bought with.

If a no is expensive for you, run a second algorithm before you act on it. If a yes is expensive to get wrong, you are on the safe side already.

Versions

Which version to call

Use v3. It is stable, it is what every example on this site uses, and it is what the docs cover.

v4 is experimental for the whole 3.0.x line. It ships in the same image, under /api/v4, and its routes and responses can change in a patch release. Do not integrate against it by accident.

The API reference covers both, and the v3 OpenAPI document is the contract itself.

Get started

Read the code

All of it is in one repository, under AGPL-3.0 - the packing engine, the API, and the tests that hold the algorithms to what this page says they do.

If you would rather watch it than read it, the packing demo runs the three algorithms in the browser on boxes and items you type in.

Or run the image and point your own data at it:

docker run -d --name binacle-net -p 8080:8080 -e SWAGGER_UI=True -e SCALAR_UI=True -e UI_MODULE=True binacle/binacle-net:3.0

Start with the quick start, or core concepts for the longer version of this page.