npm package: 3d-bin-packing-ts
Description: A TypeScript implementation of the EB AFIT algorithm for 3D container packing
Author: taherjerbi
Latest version: 1.0.1

# 3D Container Packing in TypeScript

[![npm version](https://img.shields.io/npm/v/3d-bin-packing-ts.svg)](https://www.npmjs.com/package/3d-bin-packing-ts)

This is a TypeScript port of the [3DContainerPacking C# library by davidmchapman](https://github.com/davidmchapman/3DContainerPacking).

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](./examples) folder for runnable code samples.

## Usage

### Installation

```bash
npm install 3d-bin-packing-ts
```

### Basic Usage

```typescript
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

```typescript
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

```typescript
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.

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

#### `Item`

Represents a 3D item to be packed.

```typescript
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