cmpt/README.zh.md

A TypeScript library for parsing and building B3DM (Batched 3D Model) files

# b3dm

**b3dm** 是一个用于构建和解析 B3DM 格式文件的 TypeScript 库。B3DM 是 Cesium 3D Tiles 中的一种瓦片格式，用于存储带有批量表（Batch Table）和特征表（Feature Table）的 3D 模型数据。

## 功能特点
- **构建 B3DM 文件**：从 GLB 数据和元数据生成符合 B3DM 规范的二进制文件。
- **解析 B3DM 文件**：从 B3DM 文件中提取 GLB 数据、特征表和批量表。
- **类型安全**：基于 TypeScript 开发，提供完整的类型声明支持。
- **轻量高效**：专注于核心功能，易于集成到 3D 地理信息系统（GIS）项目中。

---


## 安装

通过 npm 安装：

```bash
npm install b3dm
```

---


## 使用示例

### 构建 B3DM 文件

```typescript
import { buildB3dm } from 'b3dm';

// 输入 GLB 数据和元数据
const glbData = new Uint8Array([...]); // GLB 的二进制数据
const featureTableJSON = { BATCH_LENGTH: 10 };
const batchTableJSON = { name: 'Building A', height: 50 };

// 构建 B3DM 文件
const b3dmBuffer = buildB3dm({
  glbData,
  featureTableJSON,
  batchTableJSON,
});

// 将结果保存为文件
require('fs').writeFileSync('output.b3dm', Buffer.from(b3dmBuffer));
```

---


### 解析 B3DM 文件

```typescript
import { parseB3dm } from 'b3dm';

// 读取 B3DM 文件
const b3dmData = require('fs').readFileSync('example.b3dm');
const parsedData = parseB3dm(b3dmData.buffer);

console.log('Header:', parsedData.header);
console.log('Feature Table JSON:', parsedData.featureTable.json);
console.log('Batch Table JSON:', parsedData.batchTable?.json);
console.log('GLB Data Length:', parsedData.glbData.byteLength);
```

---


## API 文档

### 构建 B3DM 文件

#### `buildB3dm(options: B3dmBuildOptions): ArrayBuffer`
- **参数**：
  - `options`: 构建选项
    - `glbData`: 输入的 GLB 二进制数据（`Uint8Array`）。
    - `featureTableJSON`: 特征表的 JSON 数据（可选，默认为空对象）。
    - `featureTableBinary`: 特征表的二进制数据（可选，默认为空数组）。
    - `batchTableJSON`: 批量表的 JSON 数据（可选，默认为空对象）。
    - [batchTableBinary](file://d:\hub\代码测试\proj4ts\b3dm\src\types.ts#L31-L31): 批量表的二进制数据（可选，默认为空数组）。
- **返回值**：生成的 B3DM 二进制数据（`ArrayBuffer`）。

---


### 解析 B3DM 文件

#### `parseB3dm(arrayBuffer: ArrayBuffer): B3dmData`
- **参数**：
  - `arrayBuffer`: B3DM 文件的二进制数据（`ArrayBuffer`）。
- **返回值**：解析后的 B3DM 数据结构（[B3dmData](file://d:\hub\代码测试\proj4ts\b3dm\src\types.ts#L12-L23)）。
  - [header](file://d:\hub\代码测试\proj4ts\b3dm\src\types.ts#L13-L13): 文件头信息（[B3dmHeader](file://d:\hub\代码测试\proj4ts\b3dm\src\types.ts#L1-L9)）。
  - [featureTable](file://d:\hub\代码测试\proj4ts\b3dm\src\types.ts#L14-L17): 特征表，包含 JSON 和可选的二进制数据。
  - [batchTable](file://d:\hub\代码测试\proj4ts\b3dm\src\types.ts#L18-L21): 批量表（可选），包含 JSON 和可选的二进制数据。
  - [glbData](file://d:\hub\代码测试\proj4ts\b3dm\src\types.ts#L22-L22): 内嵌的 GLB 模型数据（`Uint8Array`）。

---


## 类型定义

以下是库中的主要接口定义：

```typescript
/** B3DM 文件头结构 */
export interface B3dmHeader {
    magic: string;          // 固定为 "b3dm"
    version: number;        // 版本号（通常为 1）
    byteLength: number;     // 文件总长度
    featureTableJSONByteLength: number; // 特征表 JSON 长度
    featureTableBinaryByteLength: number; // 特征表二进制长度
    batchTableJSONByteLength: number; // 批量表 JSON 长度
    batchTableBinaryByteLength: number; // 批量表二进制长度
}

/** B3DM 完整数据结构 */
export interface B3dmData {
    header: B3dmHeader;
    featureTable: {
      json: Record<string, any>;
      binary?: Uint8Array;
    };
    batchTable?: {
      json: Record<string, any>;
      binary?: Uint8Array;
    };
    glbData: Uint8Array;    // 内嵌的 GLB 模型数据
}

/** 构建 B3DM 的选项 */
export interface B3dmBuildOptions {
    glbData: Uint8Array;    // 输入的 GLB 二进制数据
    featureTableJSON?: Record<string, any>; // 特征表 JSON
    featureTableBinary?: Uint8Array; // 特征表二进制
    batchTableJSON?: Record<string, any>; // 批量表 JSON
    batchTableBinary?: Uint8Array; // 批量表二进制
}
```

---


## 贡献指南

欢迎为 `b3dm` 提交问题或 Pull Request！以下是一些贡献建议：

1. **报告问题**：如果发现任何 Bug 或有改进建议，请在 [GitHub Issues](https://github.com/your-repo/b3dm/issues) 中提交。
2. **开发环境**：
   - 克隆仓库：`git clone https://github.com/cesiumjs/b3dm.git`
   - 安装依赖：`npm install`
   - 运行测试：`npm test`
3. **代码风格**：遵循 TypeScript 的最佳实践，确保代码格式化一致。
4. **提交 PR**：请在提交前运行 `npm run build` 确保代码能够正常构建。

---


## 许可证

`b3dm` 遵循 [MIT License](https://opensource.org/licenses/MIT)。

希望这个库能帮助你更轻松地处理 B3DM 文件！如果有任何问题，欢迎随时联系我们。