3d-bin-container-packing

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:

• short and predictable calculation time,
• fairly good use of container space,
• brute-force support for low number of boxes (ideal for small orders)

Bugs, feature suggestions and help requests can be filed with the issue-tracker.

Obtain

The project is implemented in Java and built using Maven. The project is available on the central Maven repository.

<3d-bin-container-packing.version>3.0.9</3d-bin-container-packing.version>

<dependency>
    <groupId>com.github.skjolber.3d-bin-container-packing</groupId>
    <artifactId>core</artifactId>
    <version>${3d-bin-container-packing.version}</version>
</dependency>

or

ext {
  containerBinPackingVersion = '3.0.9'
}

api("com.github.skjolber.3d-bin-container-packing:core:${containerBinPackingVersion}")

Java 11+ projects please use module com.github.skjolber.packing.core.

Usage

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<StackableItem> products = new ArrayList<StackableItem>();

products.add(new StackableItem(Box.newBuilder().withId("Foot").withSize(6, 10, 2).withRotate3D().withWeight(25).build(), 1));
products.add(new StackableItem(Box.newBuilder().withId("Leg").withSize(4, 10, 1).withRotate3D().withWeight(25).build(), 1));
products.add(new StackableItem(Box.newBuilder().withId("Arm").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()
    .withContainers(containerItems)
    .withStackables(products)
    .build();

if(result.isSuccess()) {
    Container match = result.get(0);
    
    // ...
}

Pack all in a maximum number of containers:

int maxContainers = ...; // maximum number of containers which can be used

PackagerResult result = packager
    .newResultBuilder()
    .withContainers(containerItems)
    .withStackables(products)
    .withMaxContainerCount(maxContainers)
    .build();

Note that all packager instances are thread-safe.

Plain packager

A simple packager

PlainPackager packager = PlainPackager
    .newBuilder()
    .build();

Largest Area Fit First (LAFF) packager

A packager using the LAFF algorithm

LargestAreaFitFirstPackager packager = LargestAreaFitFirstPackager
    .newBuilder()
    .build();

Brute-force packager

For a low number of packages (like <= 6) the brute force packager might be a good fit.

Packager packager = BruteForcePackager
    .newBuilder()
    .build();

Using a deadline is recommended whenever brute-forcing in a real-time application.

Visualizer

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).

To use the visualizer during development, make your unit tests write directly to a file in the project (see VisualizationTest example).

Customization

The code has been structured so it is possible to extend and adapt to specialized needs. See AbstractPackager class, the extreme-points and test artifacts.

Get involved

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.

Feel free to connect with me on LinkedIn, see also my Github page.

License

Apache 2.0. Social media preview by pch.vector on www.freepik.com.

History

• 3.0.9: Fix point support bug which resulted in invalid packaging result
• 3.0.8: Visualization fix
• 3.0.4-3.0.6: Fix issue #689
• 3.0.3: Fix module info
• 3.0.2: Make Plain Packager prefer low z coordinate over supported area.
• 3.0.1: Various performance improvements.
• 3.0.0: Support max number of containers (i.e. per container type). Use builders from now on. Various optimizations.
• 2.1.4: Fix issue #574
• 2.1.3: Fix nullpointer
• 2.1.2: Tidy up, i.e. remove warnings, nuke some dependencies.
• 2.1.1: Improve free space calculation performance
• 2.1.0: Improve brute force iterators, respect deadlines in brute for packagers.