3D Container Packing in TypeScript

This is a TypeScript port of the 3DContainerPacking C# library by davidmchapman.

It contains an implementation of the EB-AFIT algorithm, a heuristic approach designed to solve the three-dimensional pallet-packing problem, also known as 3D bin packing. It was developed by Erhan Baltacıoğlu (EB) at the U.S. Air Force Institute of Technology (AFIT) as part of his master's thesis in 2001, and later described in a paper co-authored with James T. Moore and Raymond R. Hill Jr. in 2006. If you want to learn more about the algorithm and its' history, visit reference implementation repository: https://github.com/wknechtel/3d-bin-pack.

This TypeScript port includes all the original functionality plus a new packIncremental feature that automatically distributes items across multiple containers of the same dimensions.

Features

• Pack items into containers with optimal space utilization.
• Incremental packing to distribute items across multiple containers of the same size.
• TypeScript support with full type definitions.

Check out the examples folder for runnable code samples.

Usage

Installation

npm install 3d-bin-packing-ts

Basic Usage

import { Container, Item, PackingService, PackingAlgorithmType } from '3d-bin-packing-ts';

// Create a container
const container = new Container('container1', 100, 100, 100);

// Create items to pack
const items = [
  new Item('item1', 30, 40, 50, 1),
  new Item('item2', 20, 30, 40, 2),
  new Item('item3', 10, 20, 30, 3)
];

// Pack items into the container
const result = PackingService.packSingle(container, items);

// Check if all items were packed
console.log(`All items packed: ${result.algorithmPackingResults[0].isCompletePacked}`);

// Get packed items with their positions
const packedItems = result.algorithmPackingResults[0].packedItems;
console.log('Packed items:', packedItems);

// Get unpacked items
const unpackedItems = result.algorithmPackingResults[0].unpackedItems;
console.log('Unpacked items:', unpackedItems);

Packing Multiple Containers

import { Container, Item, PackingService } from '3d-bin-packing-ts';

// Create multiple containers
const containers = [
  new Container('container1', 100, 100, 100),
  new Container('container2', 150, 150, 150)
];

// Create items to pack
const items = [
  new Item('item1', 30, 40, 50, 1),
  new Item('item2', 20, 30, 40, 2),
  new Item('item3', 10, 20, 30, 3)
];

// Pack items into containers
const results = PackingService.pack(containers, items);

// Process results for each container
results.forEach(result => {
  console.log(`Container ${result.containerId}:`);
  console.log(`- Packed items: ${result.algorithmPackingResults[0].packedItems.length}`);
  console.log(`- Unpacked items: ${result.algorithmPackingResults[0].unpackedItems.length}`);
  console.log(`- Volume utilization: ${result.algorithmPackingResults[0].percentContainerVolumePacked}%`);
});

Incremental Packing

import { Item, PackingService } from '3d-bin-packing-ts';

// Create items to pack
const items = [
  new Item('item1', 30, 40, 50, 1),
  new Item('item2', 20, 30, 40, 2),
  new Item('item3', 10, 20, 30, 3)
];

// Define container dimensions
const containerDimensions = { length: 100, width: 100, height: 100 };

// Pack items incrementally (creates as many containers as needed)
const result = PackingService.packIncremental(items, containerDimensions);

// Get information about containers and item distribution
console.log(`Number of containers needed: ${result.containers.length}`);

// Get aggregated results (which items went into which container)
result.aggregatedResults.forEach(aggResult => {
  console.log(`Container ${aggResult.containerId}:`);
  aggResult.itemQuantities.forEach(itemQty => {
    console.log(`- Item ${itemQty.itemId}: ${itemQty.quantity} units`);
  });
});

API Reference

Classes

Container

Represents a 3D container to pack items into.

new Container(id: string, length: number, width: number, height: number)

Item

Represents a 3D item to be packed.

new Item(id: string, dim1: number, dim2: number, dim3: number, quantity: number)

PackingService

Static service for packing operations.

Methods:

• packSingle(container, items, algorithmTypeIDs?): Pack items into a single container
• pack(containers, items, algorithmTypeIDs?): Pack items into multiple containers
• packIncremental(items, containerDimensions, maxVolumePercentage?, idGenerator?): Pack items into as many containers as needed

Interfaces and Types

AlgorithmPackingResult

Contains the results of a packing operation.

Properties:

• packedItems: Array of packed items with their positions
• unpackedItems: Array of items that couldn't be packed
• isCompletePacked: Boolean indicating if all items were packed
• packTimeMilliseconds: Time taken for packing
• percentContainerVolumePacked: Percentage of container volume utilized
• percentItemVolumePacked: Percentage of total item volume packed