This library does 3D rectangular bin packing; it attempts to match a set of 3D items to one or more in a set of 3D containers. The result can be constrained to a maximum number of containers.
Projects using this library will benefit from:
with
Bugs, feature suggestions and help requests can be filed with the issue-tracker.
The project is implemented in Java and built using Maven. The project is available on the central Maven repository.
For the previous version, see the 3.x branch.
or
The units of measure is out-of-scope, be they cm, mm or inches.
Obtain a Packager
instance, then then compose your container and product list:
List<BoxItem> products = new ArrayList<>();
products.add(new BoxItem(Box.newBuilder().withId("Shoes").withSize(6, 10, 2).withRotate3D().withWeight(25).build(), 1));
products.add(new BoxItem(Box.newBuilder().withId("Pants").withSize(4, 10, 1).withRotate3D().withWeight(25).build(), 1));
products.add(new BoxItem(Box.newBuilder().withId("Hat").withSize(4, 10, 2).withRotate3D().withWeight(50).build(), 1));
// add a single container type
Container container = Container.newBuilder()
.withDescription("1")
.withSize(10, 10, 3)
.withEmptyWeight(1)
.withMaxLoadWeight(100)
.build();
// with unlimited number of containers available
List<ContainerItem> containerItems = ContainerItem
.newListBuilder()
.withContainer(container)
.build();
Pack all in a single container:
PackagerResult result = packager
.newResultBuilder()
.withContainerItems(containerItems)
.withBoxItems(products)
.build();
if(result.isSuccess()) {
Container match = result.get(0);
// ...
}
Use a maximum number of containers:
int maxContainers = ...; // maximum number of containers which can be used
PackagerResult result = packager
.newResultBuilder()
.withContainerItems(containerItems)
.withBoxItems(products)
.withMaxContainerCount(maxContainers)
.build();
Note that all packager
instances are thread-safe.
A simple packager
PlainPackager packager = PlainPackager
.newBuilder()
.build();
A packager using the LAFF algorithm
LargestAreaFitFirstPackager packager = LargestAreaFitFirstPackager
.newBuilder()
.build();
For a low number of packages (like <= 6) the brute force packager might be a good fit.
Packager packager = BruteForcePackager
.newBuilder()
.build();
See also the ParallelBoxItemBruteForcePackager
and FastBruteForcePackager
packagers.
Using a deadline is recommended whenever brute-forcing in a real-time application.
Make the packager account for non-rectangular packaging space, i.e. pillars or other obstacles within containers, by providing the container initial free space (i.e. points).
The packagers (excluding brute force) can be extended to handle specialized needs via various control
(plugins) types.
In a nutshell, the controls
are stateful objects which are handed various resources from the packagers during construction, and then notified and/or invoked at certain milestones within the packaging process.
Controls
must be provided as follows:
Determines which boxes go into which containers, i.e. in which combinations.
A classic example would to be to not package both lighters and dynamite in the same container.
Determines which points are relevant for a specific box.
For example, heavy items might be require only points at ground level or flammable items might be required to be stacked in a certain zone.
Determines the best placement for a box.
Can consider a range of options, like stability, stacking height, structural integrity and so on; even randomization is possible. Note that these features are not necessarily implemented in the packagers within this project.
There is a simple output visualizer included in this project, based of three.js. This visualizer is currently intended as a tool for developing better algorithms; not as stacking instructions.
cd visualizer/viewer
npm install
npm start
Note: To “hot reload” the visualizer during development, make your unit tests write directly to a file in the viewer (see the VisualizationTest
example).
If you have any questions, comments or improvement suggestions, please file an issue or submit a pull-request.
Note on bugs: Please follow shuairan’s example and file a test case with a visualization.
Apache 2.0. Social media preview by pch.vector on www.freepik.com.
BigInteger
to sanity-check max volume / max weight, calculate real remaining max volume.