# 3d-bin-packing-ts 中文文档

规范地址：https://npmcn.com/package/3d-bin-packing-ts/

版本：1\.0\.1
npm 元数据更新时间：2025-09-17T15:53:31.957Z
中文译文更新时间：2026-11-08T10:58:09.282Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/3d-bin-packing-ts
原文对照：https://npmcn.com/package/3d-bin-packing-ts/?lang=original
项目主页：https://github.com/taherjerbi/3d-bin-packing-ts#readme
源码仓库：https://github.com/taherjerbi/3d-bin-packing-ts

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：103 kB，14 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：1 个
- 首次发布：2025-09-17T15:42:33.985Z
- 最新版本发布：2025-09-17T15:53:31.782Z
- 近 30 天下载量：1795（2026-10-04 至 2026-11-02，npm 官方下载统计）
- 已发布版本数：2（近 12 个月 0 个）

## 中文简介

3D 容器包装 EB AFIT 算法的 TypeScript 执行

## 安装

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

也可以使用：`pnpm add 3d-bin-packing-ts`、`yarn add 3d-bin-packing-ts`、`bun add 3d-bin-packing-ts`

## README

# 类型脚本中的 三维容器包装

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

这是 TypeScript 端口 [3DC 集装箱包 C#图书馆,由Davidmchapman编写](https://github.com/davidmchapman/3DContainerPacking)。 。 。 .

它包含一个EB-AFIT算法的实现,一种以解决三维托盘包装问题为目的的heuristic方法,也称为3D bin包装. 它是由美国空军技术学院(AFIT)的埃尔汉·巴尔塔克奥克卢(EB)于2001年作为其硕士论文的一部分所开发,后来在2006年与詹姆斯·T·摩尔和小雷蒙德·R·希尔(英语:Raymond R. Hill Jr.)合著的论文中被描述. 如果您想更多地了解该算法及其历史, 请访问参考执行仓库: [https://github.com/wknechtel/3d-bin-pack (中文(简体) )](https://github.com/wknechtel/3d-bin-pack)。 。 。 .

这个TypeScript端口包括了所有原始功能外加一个新的包 Incremental功能,它自动将物品分出在多个相同尺寸的容器上.

## 特征

-   将物品装入容器,实现最佳空间利用.
-   \* 递增包装,在大小相同的多个集装箱间分发物品.
-   有完整类型定义的 TypeScript 支持 .

看看这个 [实例](https://npmcn.com/package/3d-bin-packing-ts/examples) 可操作代码样本的文件夹.

## 使用量

### 安装

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

### 基本用途

```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);
```

### 包装多容器

```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}%`);
});
```

### 递增包装

```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 参考

### 类

#### `Container`

代表装入物品的三维容器.

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

#### `Item`

代表要打包的三维项目.

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

#### `PackingService`

包装业务的静态服务.

方法:

-   `packSingle(container, items, algorithmTypeIDs?)`: 将物品装入单个容器
-   `pack(containers, items, algorithmTypeIDs?)`: 将物品装入多个容器
-   `packIncremental(items, containerDimensions, maxVolumePercentage?, idGenerator?)`: 视需要将物品装入尽可能多的容器

### 接口和类型

#### `AlgorithmPackingResult`

包含包装作业的结果.

属性 :

-   `packedItems`: 组装物品及其位置
-   `unpackedItems`: 无法打包的物品组
-   `isCompletePacked`:布尔表示所有项目是否被包装
-   `packTimeMilliseconds`: 包装所需时间
-   `percentContainerVolumePacked`使用集装箱量的百分比
-   `percentItemVolumePacked`: 包装物品总量的百分比

## 常见问题

### 3d-bin-packing-ts 是什么？

3D 容器包装 EB AFIT 算法的 TypeScript 执行

### 如何安装 3d-bin-packing-ts？

在项目目录运行 npm install 3d-bin-packing-ts，或使用 pnpm add / yarn add / bun add。

### 3d-bin-packing-ts 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### 3d-bin-packing-ts 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### 3d-bin-packing-ts 可以商用吗？

3d-bin-packing-ts 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### 3d-bin-packing-ts 的下载量有多少？

根据 npm 官方下载统计，3d-bin-packing-ts 在 2026/10/04 – 2026/11/02 这 30 天内被下载 1,795 次，日均约 60 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### 3d-bin-packing-ts 还在维护吗？

最新版本 1\.0\.1 发布于 2025/09/17（1\.1 年前）；至今共发布 2 个版本，其中过去 12 个月发布了 0 个；首次发布于 2025/09/17。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。