boxpacker-js

A TypeScript-based 3D bin packing library, inspired by the dvdoug/BoxPacker PHP library. This library aims to efficiently pack a list of items into a set of available boxes, considering dimensions, weight, and item rotation.

Features

• 3D Bin Packing: Efficiently places items within boxes in three dimensions.
• Weight Capacity: Considers the maximum weight capacity of each box.
• Item Rotation: Supports different item rotation policies (BestFit, KeepFlat, Never).
• Item Quantities: Easily add multiple instances of the same item type.
• Unpacked Items Tracking: Identifies items that could not be fitted into any available box.
• TypeScript Support: Provides strong typing for better development experience.

Installation

To install boxpacker-js in your project, use npm:

npm install boxpacker-js

Usage

1. Define your Boxes and Items

You need to implement the IBox and IItem interfaces for your specific box and item types.

src/interfaces/IBox.ts (Interface Definition)

export interface IBox {
    getReference(): string;
    getOuterWidth(): number;
    getOuterLength(): number;
    getOuterDepth(): number;
    getEmptyWeight(): number;
    getInnerWidth(): number;
    getInnerLength(): number;
    getInnerDepth(): number;
    getMaxWeight(): number;
    getInnerVolume(): number;
}

src/interfaces/IItem.ts (Interface Definition)

import { Rotation } from '../enums/Rotation';

export interface IItem {
    getDescription(): string;
    getWidth(): number;
    getLength(): number;
    getDepth(): number;
    getWeight(): number;
    getVolume(): number;
    getKeepFlat(): boolean;
    getAllowedRotation(): Rotation;
}

src/enums/Rotation.ts (Enum Definition)

export enum Rotation {
    Never = 0,
    KeepFlat = 1,
    BestFit = 2,
}

Example Concrete Implementations (MyBox.ts, MyItem.ts - similar to examples/basic-usage.ts)

// MyBox.ts (example)
import { IBox } from './IBox';

export class MyBox implements IBox {
    // ... (constructor and methods as seen in basic-usage.ts)
}

// MyItem.ts (example)
import { IItem } from './IItem';
import { Rotation } from '../enums/Rotation';

export class MyItem implements IItem {
    // ... (constructor and methods as seen in basic-usage.ts)
}

2. Use the Packer

import { Packer, Rotation } from 'boxpacker-js'; // Corrected import for Rotation
import { MyBox } from './MyBox'; // Your concrete Box implementation
import { MyItem } from './MyItem'; // Your concrete Item implementation

// 1. Initialize the Packer
const packer = new Packer();

// 2. Add available boxes
const smallBox = new MyBox('Small Box', 50, 50, 50, 100, 48, 48, 48, 1000);
const mediumBox = new MyBox('Medium Box', 100, 100, 100, 200, 98, 98, 98, 5000);
packer.addBox(smallBox);
packer.addBox(mediumBox);

// 3. Add items to be packed (with optional quantity)
const gadgetB = new MyItem('Gadget B', 40, 40, 40, 250);
const widgetA = new MyItem('Widget A', 30, 30, 30, 150);
const longToolD = new MyItem('Long Tool D', 80, 15, 15, 100, Rotation.BestFit);
const tinyItem = new MyItem('Tiny Item', 10, 10, 10, 5);

packer.addItem(gadgetB, 1);
packer.addItem(widgetA, 1);
packer.addItem(longToolD, 1);
packer.addItem(tinyItem, 50); // Add 50 instances of 'Tiny Item'

// 4. Perform the packing
const packedBoxes = packer.pack();
const unpackedItems = packer.getUnpackedItems();

// 5. Process Results
console.log(`Total boxes used: ${packedBoxes.length}`);
packedBoxes.forEach((packedBox, index) => {
    console.log(`\nBox ${index + 1}: ${packedBox.box.getReference()}`);
    console.log(`  Total Weight (Box + Items): ${packedBox.totalWeight}g`);
    console.log(`  Packed Items:`);
    packedBox.items.forEach(packedItem => {
        console.log(`    - ${packedItem.item.getDescription()} (Packed Dim: ${packedItem.width}x${packedItem.length}x${packedItem.depth}) at [x:${packedItem.x}, y:${packedItem.y}, z:${packedItem.z}] (Rotation: ${packedItem.rotation})`);
    });
});

if (unpackedItems.length > 0) {
    console.log(`\nUnpacked Items:`);
    unpackedItems.forEach(item => {
        console.log(`- ${item.getDescription()}`);
    });
} else {
    console.log(`\nAll items were successfully packed!`);
}

Inspired By

This library is heavily inspired by the excellent dvdoug/BoxPacker PHP library by David Dougal. Many of the core concepts and heuristics are ported from his work.

License

This project is licensed under the MIT License. See the LICENSE file for details.