Box solver¶
The Box solver solves three-dimensional bin packing problems where items are rectangular parallelepipeds (boxes) that must be packed into rectangular bins without overlapping. Unlike the BoxStacks solver, items are placed freely in 3D space — they are not restricted to vertical stacks and do not need to share a footprint.
These problems occur for example in container loading, truck loading, and warehouse picking.
Features:
Objectives:
Knapsack
Bin packing
Bin packing with leftovers
Open dimension X
Open dimension Y
Variable-sized bin packing
Item types
3D rotations (up to 6 orientations per item)
Weight
Bin types
Maximum weight
Basic usage¶
The Box solver takes as input:
an item CSV file; option:
--items items.csva bin CSV file; option:
--bins bins.csvoptionally a parameter CSV file; option:
--parameters parameters.csv
It outputs:
a solution CSV file; option:
--certificate solution.csv
The item file contains:
The X dimension of the item type (mandatory)
column
XInteger value
The Y dimension of the item type (mandatory)
column
YInteger value
The Z dimension of the item type (mandatory) — the vertical dimension in the default orientation
column
ZInteger value
The number of copies of the item type
column
COPIESdefault value:
1
The profit of an item of this type (for a knapsack objective)
column
PROFITdefault value: item volume (
X * Y * Z)
The weight of the item
column
WEIGHTdefault value:
0
The allowed orientations, encoded as a bitmask
column
ROTATIONSdefault value:
1(default orientation only)See Rotations below
The bin file contains:
The X dimension of the bin type (mandatory)
column
XInteger value
The Y dimension of the bin type (mandatory)
column
YInteger value
The Z dimension of the bin type (mandatory) — the height of the bin
column
ZInteger value
The number of copies of the bin type
column
COPIESdefault value:
1
The minimum number of copies that must be used
column
COPIES_MINdefault value:
0
The cost of a bin of this type (for a variable-sized bin packing objective)
column
COSTdefault value: bin volume
The maximum total weight allowed in a bin of this type
column
MAXIMUM_WEIGHTdefault value: no limit
The parameter file has two columns: NAME and VALUE. The possible entries are:
The objective; name:
objective; possible values:knapsackbin-packingbin-packing-with-leftoversopen-dimension-xopen-dimension-yvariable-sized-bin-packing
Example
Inputs:
X,Y,Z,ROTATIONS,COPIES
20,15,10,1,15
X,Y,Z
100,30,20
NAME,VALUE
objective,bin-packing-with-leftovers
Solve:
packingsolver_box \
--items items.csv \
--bins bins.csv \
--parameters parameters.csv \
--certificate solution.csv
=================================
PackingSolver
=================================
Problem type
------------
Box
Instance
--------
Objective: BinPackingWithLeftovers
Number of item types: 1
Number of items: 15
Number of bin types: 1
Number of bins: 1
Number of defects: 0
Total item volume: 45000
Total item profit: 45000
Largest item profit: 3000
Total item weight: 0
Largest item copies: 15
Total bin volume: 60000
Total bin weight: inf
Largest bin cost: 3000
Time Waste Waste (%) Comment
---- ----- --------- -------
0.000 15000 25.00 TS g 0 d X q 1
Final statistics
----------------
Time (s): 0.000636844
Solution
--------
Number of items: 15 / 15 (100%)
Item volume: 45000 / 45000 (100%)
Item weight: 0 / 0 (-nan%)
Item profit: 45000 / 45000 (100%)
Number of stacks: 0
Stack area: 0
Number of bins: 1 / 1 (100%)
Bin volume: 60000 / 60000 (100%)
Bin area: 3000 / 3000 (100%)
Bin weight: inf / inf (-nan%)
Bin cost: 3000
Waste: 15000
Waste (%): 25
Full waste: 15000
Full waste (%): 25
Volume load: 0.75
Area load: 0
Weight load: 0
X max: 100
Y max: 30
Z max: 20
Visualize:
python3 scripts/visualize_box.py solution.csv
Command-line options¶
packingsolver_box --items items.csv [options]
Mandatory option:
--items, -i: path to the items CSV file (or path prefix when files follow the<prefix>items.csvnaming convention)
Other input options:
--bins, -b: bins CSV file--parameters: parameters CSV file
Instance modifier options:
--objective, -f: objective (overrides the parameters file)--no-item-rotation: fix all items in their default orientation--bin-infinite-x,--bin-infinite-y: make bins infinite in one direction (for open-dimension objectives)--bin-infinite-copies: make all bin types available in unlimited copies--unweighted: set all item profits to 1--bin-unweighted: set all bin costs to 1
Output options:
--certificate, -c: solution CSV file--output, -o: JSON statistics file--time-limit, -t: time limit in seconds--verbosity-level, -v: verbosity level (0–3)
Rotations¶
The six possible 3D orientations of a box are:
Rotation id |
X direction |
Y direction |
Z direction (vertical) |
|---|---|---|---|
0 |
x |
y |
z |
1 |
y |
x |
z |
2 |
z |
y |
x |
3 |
y |
z |
x |
4 |
x |
z |
y |
5 |
z |
x |
y |
The ROTATIONS column is a bitmask: bit k (value 2^k) is set if rotation k is allowed. Common values:
1(= 2^0): only the default orientation3(= 2^0 + 2^1): Z face always on top; both XY rotations allowed15(= 2^0 + 2^1 + 2^2 + 2^3): Y face cannot be on top51(= 2^0 + 2^1 + 2^4 + 2^5): X face cannot be on top63(= all 6 bits): all six orientations allowed
Comparison with BoxStacks¶
The Box and BoxStacks solvers both handle 3D rectangular bin packing. The key difference is in how items are arranged vertically:
Box: items can be placed anywhere in 3D space; any item can rest on top of any other item regardless of their footprints.
BoxStacks: items are organized into vertical stacks; an item can only be placed on top of another item if they share the same footprint and stackability identifier.
Use Box when items can be placed freely in 3D and there are no stacking-compatibility constraints. Use BoxStacks when items must be organized into vertical stacks with matching footprints, or when stacking constraints (maximum weight above, nesting height, etc.) are needed.