# cesiumgs/3d-tiles architecture

> Architecture diagram of the GitHub repository cesiumgs/3d-tiles, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/cesiumgs/3d-tiles
- Repository: https://github.com/cesiumgs/3d-tiles

## Overview

##### Project Type and Purpose
- This is an open‐specification repository for “3D Tiles,” an OGC-style standard defining file formats and schemas for streaming massive heterogeneous 3D geospatial content.
- It provides:
- Core specification in AsciiDoc under `specification/`
- Extension registry under `extensions/`
- Reference cards under `reference-cards/`
- Release PDFs and change logs.
- It’s not a runtime application but a documentation, schema, and extension management system for spec authors and implementers.

##### Key Components
A. Specification Sources
- `specification/`
- AsciiDoc files (`.adoc`) for chapters, figures, build instructions.
- JSON Schema under `specification/schema/`
B. Extension Registry
- `extensions/3DTILES_*` directories, each with its README, schema, and figures.
- Registry index at `extensions/README.md`
C. Reference Cards
- Concise PDF/ODT cheat sheets under `reference-cards/1.0` and `1.1`.
D. Builds & Artifacts
- Build scripts (e.g., `specification/BUILDING.md`)
- Published PDFs under `releases/`
E. Resources & Ecosystem
- `RESOURCES.md` links implementations, tools, and demos.
- Integration points with Cesium, glTF, OGC community.

##### Relationships and Data Flow
- Authors write AsciiDoc + JSON schemas → fed into build system (Antora, Asciidoctor, custom scripts) → generates HTML site, PDF spec, JSON Schema artifacts, reference cards.
- Consumers (app devs, data providers) reference generated spec and schemas to implement readers, writers, and runtime engines.
- Extension authors add new directories under `extensions/`; these feed into spec and registry outputs.
- Reference cards are derived from spec content to produce concise quick‐start guides.

##### Architectural Patterns and Principles
- Modular documentation: Core spec + plug-in extensions.
- Single source of truth: AsciiDoc + JSON Schema are authoritative; multiple output formats derive from them.
- Clear separation of concerns: `specification/` vs. `extensions/` vs. `reference-cards/`.

## Diagram (Mermaid)

```mermaid
flowchart TD
  subgraph "Documentation Layer"
    direction TB
    SpecSources["AsciiDoc Source (specification/)"]:::source
    click SpecSources "https://github.com/cesiumgs/3d-tiles/tree/main/specification/"
    JSONSchema["JSON Schema (specification/schema/)"]:::source
    click JSONSchema "https://github.com/cesiumgs/3d-tiles/tree/main/specification/schema/"
    ExtIndex["Extension Registry Index (extensions/README.md)"]:::source
    click ExtIndex "https://github.com/cesiumgs/3d-tiles/blob/main/extensions/README.md"
    subgraph "Extensions"
      direction TB
      Ext1["Batch Table Hierarchy"]:::source
      click Ext1 "https://github.com/cesiumgs/3d-tiles/tree/main/extensions/3DTILES_batch_table_hierarchy/"
      Ext2["Bounding Volume S2"]:::source
      click Ext2 "https://github.com/cesiumgs/3d-tiles/tree/main/extensions/3DTILES_bounding_volume_S2/"
      Ext3["glTF Content"]:::source
      click Ext3 "https://github.com/cesiumgs/3d-tiles/tree/main/extensions/3DTILES_content_gltf/"
      Ext4["Draco Point Compression"]:::source
      click Ext4 "https://github.com/cesiumgs/3d-tiles/tree/main/extensions/3DTILES_draco_point_compression/"
      Ext5["Ellipsoid"]:::source
      click Ext5 "https://github.com/cesiumgs/3d-tiles/tree/main/extensions/3DTILES_ellipsoid/"
      Ext6["Implicit Tiling"]:::source
      click Ext6 "https://github.com/cesiumgs/3d-tiles/tree/main/extensions/3DTILES_implicit_tiling/"
      Ext7["Metadata"]:::source
      click Ext7 "https://github.com/cesiumgs/3d-tiles/tree/main/extensions/3DTILES_metadata/"
      Ext8["Multiple Contents"]:::source
      click Ext8 "https://github.com/cesiumgs/3d-tiles/tree/main/extensions/3DTILES_multiple_contents/"
    end
  end

  subgraph "Build Layer"
    direction TB
    BuildSystem["Build System\n(Antora/Asciidoctor/CMake)"]:::build
    BuildInstr["Build Instructions (specification/BUILDING.md)"]:::build
    click BuildInstr "https://github.com/cesiumgs/3d-tiles/blob/main/specification/BUILDING.md"
  end

  subgraph "Output Layer"
    direction TB
    HTMLSite["HTML Site"]:::output
    PDFv1["Core Spec PDF v1.0"]:::output
    click PDFv1 "https://github.com/cesiumgs/3d-tiles/blob/main/releases/3d-tiles-specification-1.0.pdf"
    PDFv1_1["Core Spec PDF v1.1"]:::output
    click PDFv1_1 "https://github.com/cesiumgs/3d-tiles/blob/main/releases/3d-tiles-specification-1.1.pdf"
    RefCard1["Reference Cards v1.0"]:::output
    click RefCard1 "https://github.com/cesiumgs/3d-tiles/tree/main/reference-cards/1.0/"
    RefCard1_1["Reference Cards v1.1"]:::output
    click RefCard1_1 "https://github.com/cesiumgs/3d-tiles/tree/main/reference-cards/1.1/"
    JSONArtifacts["JSON Schema Packages"]:::output
    ReleaseDir["Release Artifacts (releases/)"]:::output
    click ReleaseDir "https://github.com/cesiumgs/3d-tiles/tree/main/releases/"
  end

  subgraph "Consumption Layer"
    direction TB
    Consumers["Consumers/Implementers\n(CesiumJS, Viewers, Tools)"]:::external
    Resources["Resources & Ecosystem Links\n(RESOURCES.md)"]:::external
    click Resources "https://github.com/cesiumgs/3d-tiles/blob/main/RESOURCES.md"
    ExternalDeps["External Dependencies\n(glTF Spec, OGC, Forums)"]:::external
  end

  %% Relationships
  SpecSources -->|feeds| BuildSystem
  JSONSchema -->|feeds| BuildSystem
  Ext1 -->|contributes to| SpecSources
  Ext2 -->|contributes to| SpecSources
  Ext3 -->|contributes to| SpecSources
  Ext4 -->|contributes to| SpecSources
  Ext5 -->|contributes to| SpecSources
  Ext6 -->|contributes to| SpecSources
  Ext7 -->|contributes to| SpecSources
  Ext8 -->|contributes to| SpecSources
  ExtIndex -->|indexes| Extensions
  BuildSystem -->|generates| HTMLSite
  BuildSystem -->|generates| PDFv1
  BuildSystem -->|generates| PDFv1_1
  BuildSystem -->|generates| RefCard1
  BuildSystem -->|generates| RefCard1_1
  BuildSystem -->|generates| JSONArtifacts
  HTMLSite -->|consumed by| Consumers
  PDFv1 -->|consumed by| Consumers
  RefCard1 -->|consumed by| Consumers
  JSONArtifacts -->|consumed by| Consumers
  ExternalDeps -->|integrates with| SpecSources
  ExternalDeps -->|informs| Consumers

  classDef source fill:#bbdefb,stroke:#2196f3,color:#000;
  classDef build fill:#c8e6c9,stroke:#388e3c,color:#000;
  classDef output fill:#fff9c4,stroke:#fbc02d,color:#000;
  classDef external fill:#ffe0b2,stroke:#f57c00,color:#000;
```
