# waymo-research/waymo-open-dataset architecture

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

- Interactive diagram: https://gitdiagram.com/waymo-research/waymo-open-dataset
- Repository: https://github.com/waymo-research/waymo-open-dataset

## Overview

##### Project type and purpose
- This is an open-source evaluation library and toolkit for the Waymo Open Dataset. It defines the dataset format (via Protobuf), provides data-conversion utilities, implements core math and common routines, exposes evaluation metrics (in C++ with Python bindings), a latency-evaluation workflow, pip packaging scripts, and end-user tutorials/examples.

##### File structure
- Top-level:
- docs/            → design, labeling and metric specifications, Docker usage
- src/             → main codebase, Bazel workspace, build configuration
- tutorial/        → Jupyter notebooks and Dockerfile for hands-on demos
- Under src/waymo_open_dataset/:
- protos/         → all .proto definitions for data and submission formats
- common/, math/  → low-level C++ helpers and utilities
- data_conversion/→ convert raw scenario to internal TFRecord format
- metrics/        →
– core C++ metric implementations and tests
– ops/         → custom TensorFlow/PyTorch ops in C++ + Python wrappers
– python/      → high-level Python metric APIs and tests
– tools/       → CLI tools for batch metric computation and submission generation
- latency/        → scripts and examples (TF/PyTorch, Docker) to measure model inference time
- v2/             → a pandas-style DataFrame API for dataset access and “compat_v1” adapters
- wdl_limited/    → licensed submodules for camera, segmentation, sim_agent metrics
- pip_pkg_scripts/→ Dockerized build and packaging for PyPI distribution

##### Insights from README
- Confirms three dataset families (Perception, Motion, End-to-End)
- Evaluation code and helper functions in TensorFlow and Python
- Licensing constraints on wdl_limited subfolders

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data Format Layer
    subgraph "Data Format Layer"
        Protos["Protobuf Definitions\n(protos/)"]:::dataformat
        DataConv["Data Conversion Pipeline\n(data_conversion/)"]:::dataformat
        V2["v2 DataFrame API\n(v2/)"]:::dataformat
    end

    %% Core Libraries
    subgraph "Core Libraries"
        Common["Common Utilities\n(common/)"]:::core
        Math["Math Utilities\n(math/)"]:::core
        Utils["Python Utilities\n(utils/)"]:::core
    end

    %% Evaluation Modules
    subgraph "Evaluation Modules"
        subgraph "Metrics Evaluation"
            CppEngines["C++ Metric Engines\n(metrics/)"]:::eval
            CustomOps["Custom Ops Module\n(metrics/ops/)"]:::eval
            PyAPI["Python Metric APIs\n(metrics/python/)"]:::eval
            CLITools["CLI Tools\n(metrics/tools/)"]:::eval
        end
        Latency["Latency Evaluation Module\n(latency/)"]:::eval
    end

    %% Packaging & Build
    subgraph "Packaging & Build"
        BazelCfg["Bazel Workspace & Config\n(WORKSPACE, .bazelrc, BUILD)"]:::pack
        PipPkg["PyPI Packaging Scripts\n(pip_pkg_scripts/)"]:::pack
    end

    Tutorial["Tutorials & Examples\n(tutorial/)"]:::tutorial
    Docs["Documentation & Specifications\n(docs/)"]:::docs
    ExternalData["Raw Dataset"]:::external
    ExternalModel["Model Inference Containers\n(Docker)"]:::external

    %% Data Flow
    ExternalData -->|"raw data"| DataConv
    Protos --> DataConv
    DataConv -->|"TFRecord"| CppEngines
    CppEngines --> PyAPI
    CustomOps --> PyAPI
    PyAPI --> CLITools
    CLITools -->|"Evaluation Reports"| Tutorial

    ExternalModel --> Latency
    Latency -->|"Latency Results"| CLITools

    %% Dependencies
    Protos --> Common
    Protos --> Math
    Protos --> Utils
    Common --> BazelCfg
    Math --> BazelCfg
    Utils --> BazelCfg
    Protos --> BazelCfg
    BazelCfg --> PipPkg
    PipPkg --> Tutorial

    %% Documentation links
    Docs --> Protos
    Docs --> DataConv
    Docs --> CppEngines
    Docs --> Latency
    Docs --> Tutorial

    %% Click Events
    click Protos "https://github.com/waymo-research/waymo-open-dataset/tree/master/src/waymo_open_dataset/protos"
    click Common "https://github.com/waymo-research/waymo-open-dataset/tree/master/src/waymo_open_dataset/common"
    click Math "https://github.com/waymo-research/waymo-open-dataset/tree/master/src/waymo_open_dataset/math"
    click Utils "https://github.com/waymo-research/waymo-open-dataset/tree/master/src/waymo_open_dataset/utils"
    click DataConv "https://github.com/waymo-research/waymo-open-dataset/tree/master/src/waymo_open_dataset/data_conversion"
    click CppEngines "https://github.com/waymo-research/waymo-open-dataset/tree/master/src/waymo_open_dataset/metrics"
    click CustomOps "https://github.com/waymo-research/waymo-open-dataset/tree/master/src/waymo_open_dataset/metrics/ops"
    click PyAPI "https://github.com/waymo-research/waymo-open-dataset/tree/master/src/waymo_open_dataset/metrics/python"
    click CLITools "https://github.com/waymo-research/waymo-open-dataset/tree/master/src/waymo_open_dataset/metrics/tools"
    click Latency "https://github.com/waymo-research/waymo-open-dataset/tree/master/src/waymo_open_dataset/latency"
    click V2 "https://github.com/waymo-research/waymo-open-dataset/tree/master/src/waymo_open_dataset/v2"
    click PipPkg "https://github.com/waymo-research/waymo-open-dataset/tree/master/src/waymo_open_dataset/pip_pkg_scripts"
    click BazelCfg "https://github.com/waymo-research/waymo-open-dataset/tree/master/src/WORKSPACE"
    click Tutorial "https://github.com/waymo-research/waymo-open-dataset/tree/master/tutorial/"
    click Docs "https://github.com/waymo-research/waymo-open-dataset/tree/master/docs/"

    %% Styles
    classDef dataformat fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef core fill:#D3D3D3,stroke:#000,stroke-width:1px
    classDef eval fill:#90EE90,stroke:#000,stroke-width:1px
    classDef pack fill:#FFA500,stroke:#000,stroke-width:1px
    classDef tutorial fill:#DDA0DD,stroke:#000,stroke-width:1px
    classDef docs fill:#F5F5DC,stroke:#000,stroke-width:1px
    classDef external fill:#F0E68C,stroke:#000,stroke-width:1px
```
