# @cratefit/pack

[![npm version](https://img.shields.io/npm/v/@cratefit/pack.svg)](https://www.npmjs.com/package/@cratefit/pack)

A powerful 3D bin packing library for optimizing container, pallet, and truck loading.

## Features

- **Multiple Algorithms**: Extreme Point, Layer Building, Wall Building, EB-AFIT
- **Metaheuristic Optimization**: Simulated Annealing, Tabu Search, Genetic Algorithm
- **Industry Standards**: Built-in pallet and container specifications (EUR, ISO, etc.)
- **Advanced Constraints**: Weight limits, stacking rules, rotation restrictions, support checking
- **Real-time Packing**: Online packing mode for dynamic item placement
- **Exclude Zones**: Support for irregular container shapes

## Installation

```bash
npm install @cratefit/pack
```

For visualization support:

```bash
npm install @cratefit/pack @cratefit/viz three
```

## Quick Start

```typescript
import { pack, createBin, createItem } from '@cratefit/pack';

// Define a bin (container)
const bin = createBin({
  id: 'bin-1',
  width: 1200,
  height: 1000,
  depth: 800,
  maxWeight: 1000,
});

// Define items to pack
const items = [
  createItem({ id: 'item-1', width: 400, height: 300, depth: 200, weight: 10, quantity: 5 }),
  createItem({ id: 'item-2', width: 300, height: 200, depth: 150, weight: 5, quantity: 8 }),
];

// Pack items
const result = pack({
  bins: [bin],
  items,
  options: {
    algorithm: 'auto',
  },
});

console.log(`Utilization: ${(result.stats.avgUtilization * 100).toFixed(1)}%`);
console.log(`Packed: ${result.stats.packedItems}/${result.stats.totalItems} items`);
```

## Pallet Packing

```typescript
import { packPallet, PALLET_STANDARDS } from '@cratefit/pack';

const result = packPallet({
  pallet: PALLET_STANDARDS.EUR1,
  items: [...],
  options: {
    maxStackHeight: 1800,
    stackingRules: true,
  },
});
```

## Container Loading

```typescript
import { packContainer, CONTAINER_STANDARDS } from '@cratefit/pack';

const result = packContainer({
  container: CONTAINER_STANDARDS['20ft'],
  items: [...],
  options: {
    optimizeForWeight: true,
  },
});
```

## Visualization

Use `@cratefit/viz` for 2D/3D rendering:

```typescript
import { pack } from '@cratefit/pack';
import { renderTopView, create3DScene, renderPackedBin3D } from '@cratefit/viz';

// 2D Canvas
renderTopView(canvas, result.packed[0], { showLabels: true });

// 3D Three.js
const { scene, camera, renderer } = await create3DScene(container);
await renderPackedBin3D(scene, result.packed[0]);
```

See [@cratefit/viz](https://www.npmjs.com/package/@cratefit/viz) for more details.

## API Reference

### Core Functions

- `pack(options)` - Main packing function
- `createBin(spec)` - Create a bin specification
- `createItem(spec)` - Create an item specification

### Scenario Functions

- `packPallet(options)` - Pallet-specific packing
- `packContainer(options)` - Container-specific packing
- `packTruck(options)` - Truck-specific packing with axle weight calculation

### Algorithm Options

```typescript
type Algorithm =
  | 'extreme-point'   // Fast, good for uniform items
  | 'layer-building'  // Best for stable stacking
  | 'wall-building'   // Good for varied sizes
  | 'eb-afit'         // Human-like heuristic
  | 'auto';           // Automatic selection
```