3D Tiles Tools

The demos repository provides examples for various functional areas of the 3D Tiles tools. Use these as a reference for how to interact with the following capabilities:

Metadata and Data Types

• BinaryMetadataDemos: Creating and accessing BinaryPropertyTableModel instances with different property types.
• MetadataDemos: Working with MetadataEntityModel instances for JSON-based metadata entities.
• ContentDataTypeChecksDemo: Using ContentDataTypeChecks to verify content data types.
• ContentDataTypeRegistryDemo: Querying content data types via ContentDataTypeRegistry.
• SubtreeInfoDemos: Using the SubtreeInfo class to access binary subtree data.

Package and Format Management

• PackageConversion: CLI tool for converting between formats (e.g., files/3TZ/3DTILES/ZIP to files/3TZ/3DTILES).
• PackagesDemo: Reading, creating, and writing 3D Tiles packages.
• PackageServer: A basic server for serving data from an arbitrary 3D Tiles package (intended for use with PackageSandcastle).
• TileFormatsDemoBasic: Basic usage of the TileFormats class.
• TileFormatsDemoConversions: Using TileFormats for conversions, such as extracting GLB from B3DM.

Tileset Processing and Traversal

• TilesetProcessingDemos: Using combine, merge, and upgrade functions.
• TilesetProcessorExamples: Basic usage of BasicTilesetProcessor functions.
• TilesetUpgraderDemos: Fine-grained demonstrations of upgrade functionality.
• TraversalDemo: Basic tileset traversal.
• TraversalStatsDemo: Traversing a tileset while collecting statistical information.

Spatial and Pipeline

• SpatialDemos: Using quadtree and octree classes in the spatial module.
• Pipeline...: Preliminary drafts for upcoming pipelines functionalities.

There are three primary ways to merge tilesets, depending on whether you want to inline content or maintain external references:

1. combine: Takes a tileset that refers to external tilesets and "inlines" them, creating a single tileset without external references.
2. merge: Creates a new tileset that refers to the input tilesets as external tilesets. The resulting tileset is incomplete without the original input files.
3. mergeJson: Similar to merge, but only creates the JSON file. It does not copy input tilesets to the output directory; instead, it uses relative paths to refer to them. This is useful for organizing tilesets in subdirectories.
4. mergeJson3tz: Merges tilesets packaged as .3tz files into a single tileset JSON using the MAXAR_content_3tz extension. If a directory is provided, it recursively includes all .3tz files within it.

# Combine (inline external tilesets)
npx 3d-tiles-tools combine -i ./specs/data/combineTilesets/input -o ./specs/data/combineTilesets/output

# Merge (create new tileset with external references)
npx 3d-tiles-tools merge -i ./specs/data/mergeTilesets/TilesetA -i ./specs/data/mergeTilesets/sub/TilesetA -o ./specs/data/mergeTilesets/output

# Merge JSON only (relative paths, no file copying)
npx 3d-tiles-tools mergeJson -i ./example/TilesetA/tileset.json -i ./example/TilesetB/tileset.json -o ./example/mergedTileset.json

# Merge 3TZ files
npx 3d-tiles-tools mergeJson3tz -i ./example/tilesetA.3tz -i ./example/tilesetB.3tz -o ./example/tileset.json

When testing tileset processing operations (such as converting B3DM to GLB), the tools must correctly resolve paths for both internal tile content and external tilesets. The following directory structures represent common scenarios for testing path resolution:

• Same Directory: tileset.json refers to tile.b3dm and externalA.json where all files reside in the same folder.
• Subdirectory External Tileset: externalA.json refers to tileA.b3dm and ExternalB/externalB.json, where the external tileset is located in a subdirectory.
• Parent and Sibling Directories: externalB.json refers to tileB.b3dm, ../tileX.b3dm, and ../ExternalC/externalC.json. This tests resolution of content in the parent directory and external tilesets in sibling directories.
• Relative Parent Content: externalC.json refers to tileC0.b3dm and ../tileC1.b3dm to test content located in the parent directory.

Note on Deduplication: In complex structures, a single content file (e.g., tileX.b3dm) may be referred to by multiple tilesets. The processing engine should identify these and ensure the content is processed only once.

The pipeline feature (preliminary) allows you to execute a sequence of operations defined in a JSON file. A pipeline consists of an input, an output, and an array of tilesetStages and contentStages.

Pipeline Structure:

• Tileset Stages: Operations applied to the tileset structure (e.g., upgrade, combine, gzip, ungzip).
• Content Stages: Operations applied to individual tile contents (e.g., glbToB3dm, b3dmToGlb, optimizeB3dm, optimizeI3dm).

If a stage name is not a predefined operation, it should start with an underscore (_) to indicate a custom operation.

Example Pipeline JSON:

{
  "input": "./specs/data/TilesetOfTilesetsWithUris",
  "output": "./output/TilesetOfTilesetsWithUris.3tz",
  "tilesetStages": [
    {
      "name": "_b3dmToGlb",
      "description": "Convert B3DM to GLB",
      "contentStages": [
        {
          "name": "b3dmToGlb",
          "description": "Convert each B3DM content into GLB"
        }
      ]
    }
  ]
}

A Subtree JSON object defines how availability information for tiles, content, and child subtrees is encoded and stored. It uses buffers and bufferViews to point to binary data that represents availability bitstreams.

Key availability fields include:

• tileAvailability: Indicates which tiles are available. Can be defined by a constant value or a bitstream (referencing a buffer).
• contentAvailability: An array of availability objects (one per content type) indicating if content is available for specific tiles. Can be defined by constant or bitstream.
• childSubtreeAvailability: Indicates the availability of child subtrees. Can be defined by constant or bitstream.

When constant is used, the availability is uniform across the specified availableCount. When bitstream is used, the availability is determined by reading bits from the specified bufferViews.

{
  "buffers" : [
    {
      "byteLength" : 8
    }
  ],
  "bufferViews" : [
    {
      "buffer" : 0,
      "byteOffset" : 0,
      "byteLength" : 2
    }
  ],
  "tileAvailability" : {
    "availableCount" : 5,
    "constant" : 1
  },
  "contentAvailability" : [
    {
      "availableCount" : 5,
      "constant" : 1
    }
  ],
  "childSubtreeAvailability" : {
    "bitstream" : 0,
    "availableCount" : 4
  }
}