cmpt/README.md

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

# b3dm

**b3dm** is a TypeScript library for building and parsing [B3DM](https://github.com/CesiumGS/3d-tiles/tree/main/specification/TileFormats/BatchTable) format files. B3DM is a tile format in Cesium 3D Tiles, used to store 3D model data with Batch Tables and Feature Tables.

## Key Features
- **Build B3DM Files**: Generate binary B3DM files from GLB data and metadata.
- **Parse B3DM Files**: Extract GLB data, Feature Table, and Batch Table from B3DM files.
- **Type-Safe**: Fully developed in TypeScript with complete type declarations.
- **Lightweight & Efficient**: Focuses on core functionality and is easy to integrate into 3D GIS projects.

---


## Installation

Install via npm:

```bash
npm install b3dm
```

---


## Usage Examples

### Build a B3DM File

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

// Input GLB data and metadata
const glbData = new Uint8Array([...]); // Binary GLB data
const featureTableJSON = { BATCH_LENGTH: 10 };
const batchTableJSON = { name: 'Building A', height: 50 };

// Build the B3DM file
const b3dmBuffer = buildB3dm({
  glbData,
  featureTableJSON,
  batchTableJSON,
});

// Save the result as a file
require('fs').writeFileSync('output.b3dm', Buffer.from(b3dmBuffer));
```

---


### Parse a B3DM File

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

// Read the B3DM file
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 Documentation

### Build a B3DM File

#### `buildB3dm(options: B3dmBuildOptions): ArrayBuffer`
- **Parameters**:
  - `options`: Build options
    - [glbData]: Input GLB binary data (`Uint8Array`).
    - [featureTableJSON]: Feature Table JSON data (optional, defaults to an empty object).
    - [featureTableBinary]: Feature Table binary data (optional, defaults to an empty array).
    - [batchTableJSON]: Batch Table JSON data (optional, defaults to an empty object).
    - [batchTableBinary]: Batch Table binary data (optional, defaults to an empty array).
- **Returns**: The generated B3DM binary data (`ArrayBuffer`).

---


### Parse a B3DM File

#### `parseB3dm(arrayBuffer: ArrayBuffer): B3dmData`
- **Parameters**:
  - `arrayBuffer`: The binary data of the B3DM file (`ArrayBuffer`).
- **Returns**: The parsed B3DM data structure ([B3dmData](file://d:\hub\代码测试\proj4ts\b3dm\src\types.ts#L12-L23)).
  - [header](file://d:\hub\代码测试\proj4ts\b3dm\src\types.ts#L13-L13): File header information ([B3dmHeader](file://d:\hub\代码测试\proj4ts\b3dm\src\types.ts#L1-L9)).
  - [featureTable](file://d:\hub\代码测试\proj4ts\b3dm\src\types.ts#L14-L17): Feature Table, containing JSON and optional binary data.
  - [batchTable](file://d:\hub\代码测试\proj4ts\b3dm\src\types.ts#L18-L21): Batch Table (optional), containing JSON and optional binary data.
  - [glbData](file://d:\hub\代码测试\proj4ts\b3dm\src\types.ts#L22-L22): Embedded GLB model data (`Uint8Array`).

---


## Type Definitions

The following are the main interface definitions in the library:

```typescript
/** B3DM Header Structure */
export interface B3dmHeader {
    magic: string;          // Fixed as "b3dm"
    version: number;        // Version number (usually 1)
    byteLength: number;     // Total file length
    featureTableJSONByteLength: number; // Length of Feature Table JSON
    featureTableBinaryByteLength: number; // Length of Feature Table binary
    batchTableJSONByteLength: number; // Length of Batch Table JSON
    batchTableBinaryByteLength: number; // Length of Batch Table binary
}

/** Complete B3DM Data Structure */
export interface B3dmData {
    header: B3dmHeader;
    featureTable: {
      json: Record<string, any>;
      binary?: Uint8Array;
    };
    batchTable?: {
      json: Record<string, any>;
      binary?: Uint8Array;
    };
    glbData: Uint8Array;    // Embedded GLB model data
}

/** Options for Building B3DM */
export interface B3dmBuildOptions {
    glbData: Uint8Array;    // Input GLB binary data
    featureTableJSON?: Record<string, any>; // Feature Table JSON
    featureTableBinary?: Uint8Array; // Feature Table binary
    batchTableJSON?: Record<string, any>; // Batch Table JSON
    batchTableBinary?: Uint8Array; // Batch Table binary
}
```

---


## Contribution Guidelines

Contributions to `b3dm` are welcome! Here are some guidelines for contributing:

1. **Report Issues**: If you find any bugs or have improvement suggestions, please submit them in [GitHub Issues](https://github.com/your-repo/b3dm/issues).
2. **Development Environment**:
   - Clone the repository: `git clone https://github.com/cesiumjs/b3dm.git`
   - Install dependencies: `npm install`
   - Run tests: `npm test`
3. **Code Style**: Follow TypeScript best practices and ensure consistent code formatting.
4. **Submit PRs**: Before submitting a pull request, run `npm run build` to ensure the code builds successfully.

---


## License

`b3dm` is released under the [MIT License](https://opensource.org/licenses/MIT).

We hope this library helps you work with B3DM files more easily! If you have any questions, feel free to contact us.