b3dm

b3dm is a TypeScript library for building and parsing B3DM 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:

npm install b3dm

Usage Examples

Build a B3DM File

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

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).
  • header: File header information (B3dmHeader).
  • featureTable: Feature Table, containing JSON and optional binary data.
  • batchTable: Batch Table (optional), containing JSON and optional binary data.
  • glbData: Embedded GLB model data (Uint8Array).

Type Definitions

The following are the main interface definitions in the library:

/** 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.
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.

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