# opendrivelab/uniad architecture

> Architecture diagram of the GitHub repository opendrivelab/uniad, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/opendrivelab/uniad
- Repository: https://github.com/opendrivelab/uniad

## Overview

UniAD is a planning-oriented autonomous-driving model that hierarchically combines perception, prediction, occupancy reasoning, and planning. Its principal workflow prepares nuScenes examples, trains or evaluates a staged model, and produces task predictions and planning outputs; visualization tools can render results. The README explicitly identifies the end-to-end detector as the task-module coordinator. Other links below are limited to relationships documented in the README or visible in the SOURCE INDEX; unsampled implementation details are not assumed.

Main entry points: [`projects/mmdet3d_plugin/uniad/detectors/uniad_e2e.py`](https://github.com/opendrivelab/uniad/blob/v2.0/projects/mmdet3d_plugin/uniad/detectors/uniad_e2e.py) (Task coordinator), [`projects/mmdet3d_plugin/datasets/nuscenes_e2e_dataset.py`](https://github.com/opendrivelab/uniad/blob/v2.0/projects/mmdet3d_plugin/datasets/nuscenes_e2e_dataset.py) (E2E dataset), [`tools/analysis_tools/visualize/run.py`](https://github.com/opendrivelab/uniad/blob/v2.0/tools/analysis_tools/visualize/run.py) (Visualization runner), [`projects/mmdet3d_plugin/uniad/dense_heads/panseg_head.py`](https://github.com/opendrivelab/uniad/blob/v2.0/projects/mmdet3d_plugin/uniad/dense_heads/panseg_head.py) (Map segmentation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Data preparation"]
  node_converter["Dataset converter"]
  node_dataset["E2E dataset"]
  node_trajectory["Trajectory labels<br/>[trajectory_api.py]"]
  node_vector_map["Vector maps<br/>[vector_map.py]"]
end

subgraph group_model["Perception model"]
  node_bev["BEV encoder<br/>[bevformer.py]"]
  node_tracking["Tracking<br/>[modules.py]"]
  node_mapping["Map segmentation<br/>[panseg_head.py]"]
  node_segmentation["Segmentation components<br/>[seg_detr_head.py]"]
end

subgraph group_prediction["Prediction and planning"]
  node_motion["Motion prediction<br/>[motion_head.py]"]
  node_occupancy["Occupancy prediction<br/>[occ_head.py]"]
  node_planning["Planning<br/>[planning_head.py]"]
  node_e2e["Task coordinator<br/>[uniad_e2e.py]"]
end

subgraph group_runtime["Training and evaluation"]
  node_train_cli["Training entry<br/>[train.py]"]
  node_train_api["Training API<br/>[train.py]"]
  node_train_engine["Model training<br/>[mmdet_train.py]"]
  node_eval["nuScenes evaluation<br/>[nuscenes_eval.py]"]
  node_motion_eval["Motion evaluation"]
end

subgraph group_inspection["Result inspection"]
  node_visualizer["Visualization runner<br/>[run.py]"]
  node_bev_render["BEV renderer<br/>[bev_render.py]"]
  node_camera_render["Camera renderer<br/>[cam_render.py]"]
  node_render_base["Render base<br/>[base_render.py]"]
end

node_user(("Engineer"))
node_nuscenes[("nuScenes data")]

node_user -->|"prepares data"| node_converter
node_nuscenes -->|"converts samples"| node_converter
node_user -->|"starts training"| node_train_cli
node_train_cli -->|"invokes"| node_train_api
node_train_api -->|"delegates"| node_train_engine
node_train_engine -->|"builds dataset"| node_dataset
node_dataset -->|"gets labels"| node_trajectory
node_dataset -->|"uses map data"| node_vector_map
node_dataset -->|"runs evaluation"| node_eval
node_dataset -->|"runs motion metrics"| node_motion_eval
node_e2e -->|"coordinates tasks"| node_tracking
node_e2e -->|"coordinates tasks"| node_mapping
node_e2e -->|"coordinates tasks"| node_motion
node_e2e -->|"coordinates tasks"| node_occupancy
node_e2e -->|"coordinates tasks"| node_planning
node_mapping -->|"inherits head"| node_segmentation
node_user -->|"renders results"| node_visualizer
node_visualizer -->|"uses renderer"| node_bev_render
node_visualizer -->|"uses renderer"| node_camera_render
node_bev_render -->|"inherits"| node_render_base
node_camera_render -->|"inherits"| node_render_base

click node_converter "https://github.com/opendrivelab/uniad/blob/v2.0/tools/data_converter/uniad_nuscenes_converter.py"
click node_dataset "https://github.com/opendrivelab/uniad/blob/v2.0/projects/mmdet3d_plugin/datasets/nuscenes_e2e_dataset.py"
click node_trajectory "https://github.com/opendrivelab/uniad/blob/v2.0/projects/mmdet3d_plugin/datasets/data_utils/trajectory_api.py"
click node_vector_map "https://github.com/opendrivelab/uniad/blob/v2.0/projects/mmdet3d_plugin/datasets/data_utils/vector_map.py"
click node_bev "https://github.com/opendrivelab/uniad/blob/v2.0/projects/mmdet3d_plugin/uniad/detectors/bevformer.py"
click node_tracking "https://github.com/opendrivelab/uniad/blob/v2.0/projects/mmdet3d_plugin/uniad/dense_heads/track_head_plugin/modules.py"
click node_mapping "https://github.com/opendrivelab/uniad/blob/v2.0/projects/mmdet3d_plugin/uniad/dense_heads/panseg_head.py"
click node_segmentation "https://github.com/opendrivelab/uniad/blob/v2.0/projects/mmdet3d_plugin/uniad/dense_heads/seg_head_plugin/seg_detr_head.py"
click node_motion "https://github.com/opendrivelab/uniad/blob/v2.0/projects/mmdet3d_plugin/uniad/dense_heads/motion_head.py"
click node_occupancy "https://github.com/opendrivelab/uniad/blob/v2.0/projects/mmdet3d_plugin/uniad/dense_heads/occ_head.py"
click node_planning "https://github.com/opendrivelab/uniad/blob/v2.0/projects/mmdet3d_plugin/uniad/dense_heads/planning_head.py"
click node_e2e "https://github.com/opendrivelab/uniad/blob/v2.0/projects/mmdet3d_plugin/uniad/detectors/uniad_e2e.py"
click node_train_cli "https://github.com/opendrivelab/uniad/blob/v2.0/tools/train.py"
click node_train_api "https://github.com/opendrivelab/uniad/blob/v2.0/projects/mmdet3d_plugin/uniad/apis/train.py"
click node_train_engine "https://github.com/opendrivelab/uniad/blob/v2.0/projects/mmdet3d_plugin/uniad/apis/mmdet_train.py"
click node_eval "https://github.com/opendrivelab/uniad/blob/v2.0/projects/mmdet3d_plugin/datasets/eval_utils/nuscenes_eval.py"
click node_motion_eval "https://github.com/opendrivelab/uniad/blob/v2.0/projects/mmdet3d_plugin/datasets/eval_utils/nuscenes_eval_motion.py"
click node_visualizer "https://github.com/opendrivelab/uniad/blob/v2.0/tools/analysis_tools/visualize/run.py"
click node_bev_render "https://github.com/opendrivelab/uniad/blob/v2.0/tools/analysis_tools/visualize/render/bev_render.py"
click node_camera_render "https://github.com/opendrivelab/uniad/blob/v2.0/tools/analysis_tools/visualize/render/cam_render.py"
click node_render_base "https://github.com/opendrivelab/uniad/blob/v2.0/tools/analysis_tools/visualize/render/base_render.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_converter,node_dataset,node_trajectory,node_vector_map toneBlue
class node_bev,node_tracking,node_mapping,node_segmentation,node_nuscenes toneAmber
class node_motion,node_occupancy,node_planning,node_e2e toneMint
class node_train_cli,node_train_api,node_train_engine,node_eval,node_motion_eval toneRose
class node_visualizer,node_bev_render,node_camera_render,node_render_base,node_user toneIndigo
```

## Components

### Data preparation

- [Dataset converter](https://github.com/opendrivelab/uniad/blob/v2.0/tools/data_converter/uniad_nuscenes_converter.py): `tools/data_converter/uniad_nuscenes_converter.py`
- [E2E dataset](https://github.com/opendrivelab/uniad/blob/v2.0/projects/mmdet3d_plugin/datasets/nuscenes_e2e_dataset.py): `projects/mmdet3d_plugin/datasets/nuscenes_e2e_dataset.py`
- [Trajectory labels](https://github.com/opendrivelab/uniad/blob/v2.0/projects/mmdet3d_plugin/datasets/data_utils/trajectory_api.py): `projects/mmdet3d_plugin/datasets/data_utils/trajectory_api.py`
- [Vector maps](https://github.com/opendrivelab/uniad/blob/v2.0/projects/mmdet3d_plugin/datasets/data_utils/vector_map.py): `projects/mmdet3d_plugin/datasets/data_utils/vector_map.py`

### Perception model

- [BEV encoder](https://github.com/opendrivelab/uniad/blob/v2.0/projects/mmdet3d_plugin/uniad/detectors/bevformer.py): `projects/mmdet3d_plugin/uniad/detectors/bevformer.py`
- [Tracking](https://github.com/opendrivelab/uniad/blob/v2.0/projects/mmdet3d_plugin/uniad/dense_heads/track_head_plugin/modules.py): `projects/mmdet3d_plugin/uniad/dense_heads/track_head_plugin/modules.py`
- [Map segmentation](https://github.com/opendrivelab/uniad/blob/v2.0/projects/mmdet3d_plugin/uniad/dense_heads/panseg_head.py): `projects/mmdet3d_plugin/uniad/dense_heads/panseg_head.py`
- [Segmentation components](https://github.com/opendrivelab/uniad/blob/v2.0/projects/mmdet3d_plugin/uniad/dense_heads/seg_head_plugin/seg_detr_head.py): `projects/mmdet3d_plugin/uniad/dense_heads/seg_head_plugin/seg_detr_head.py`

### Prediction and planning

- [Motion prediction](https://github.com/opendrivelab/uniad/blob/v2.0/projects/mmdet3d_plugin/uniad/dense_heads/motion_head.py): `projects/mmdet3d_plugin/uniad/dense_heads/motion_head.py`
- [Occupancy prediction](https://github.com/opendrivelab/uniad/blob/v2.0/projects/mmdet3d_plugin/uniad/dense_heads/occ_head.py): `projects/mmdet3d_plugin/uniad/dense_heads/occ_head.py`
- [Planning](https://github.com/opendrivelab/uniad/blob/v2.0/projects/mmdet3d_plugin/uniad/dense_heads/planning_head.py): `projects/mmdet3d_plugin/uniad/dense_heads/planning_head.py`
- [Task coordinator](https://github.com/opendrivelab/uniad/blob/v2.0/projects/mmdet3d_plugin/uniad/detectors/uniad_e2e.py): `projects/mmdet3d_plugin/uniad/detectors/uniad_e2e.py`

### Training and evaluation

- [Training entry](https://github.com/opendrivelab/uniad/blob/v2.0/tools/train.py): `tools/train.py`
- [Training API](https://github.com/opendrivelab/uniad/blob/v2.0/projects/mmdet3d_plugin/uniad/apis/train.py): `projects/mmdet3d_plugin/uniad/apis/train.py`
- [Model training](https://github.com/opendrivelab/uniad/blob/v2.0/projects/mmdet3d_plugin/uniad/apis/mmdet_train.py): `projects/mmdet3d_plugin/uniad/apis/mmdet_train.py`
- [nuScenes evaluation](https://github.com/opendrivelab/uniad/blob/v2.0/projects/mmdet3d_plugin/datasets/eval_utils/nuscenes_eval.py): `projects/mmdet3d_plugin/datasets/eval_utils/nuscenes_eval.py`
- [Motion evaluation](https://github.com/opendrivelab/uniad/blob/v2.0/projects/mmdet3d_plugin/datasets/eval_utils/nuscenes_eval_motion.py): `projects/mmdet3d_plugin/datasets/eval_utils/nuscenes_eval_motion.py`

### Result inspection

- [Visualization runner](https://github.com/opendrivelab/uniad/blob/v2.0/tools/analysis_tools/visualize/run.py): `tools/analysis_tools/visualize/run.py`
- [BEV renderer](https://github.com/opendrivelab/uniad/blob/v2.0/tools/analysis_tools/visualize/render/bev_render.py): `tools/analysis_tools/visualize/render/bev_render.py`
- [Camera renderer](https://github.com/opendrivelab/uniad/blob/v2.0/tools/analysis_tools/visualize/render/cam_render.py): `tools/analysis_tools/visualize/render/cam_render.py`
- [Render base](https://github.com/opendrivelab/uniad/blob/v2.0/tools/analysis_tools/visualize/render/base_render.py): `tools/analysis_tools/visualize/render/base_render.py`

### Other components

- **Engineer**
- **nuScenes data**

## Connections

- Engineer → Dataset converter: prepares data
- nuScenes data → Dataset converter: converts samples (evidence: `tools/data_converter/uniad_nuscenes_converter.py`)
- Engineer → Training entry: starts training (evidence: `tools/train.py`)
- Training entry → Training API: invokes (evidence: `tools/train.py`)
- Training API → Model training: delegates (evidence: `projects/mmdet3d_plugin/uniad/apis/train.py`)
- Model training → E2E dataset: builds dataset (evidence: `projects/mmdet3d_plugin/uniad/apis/mmdet_train.py`)
- E2E dataset → Trajectory labels: gets labels (evidence: `projects/mmdet3d_plugin/datasets/nuscenes_e2e_dataset.py`)
- E2E dataset → Vector maps: uses map data (evidence: `projects/mmdet3d_plugin/datasets/nuscenes_e2e_dataset.py`)
- E2E dataset → nuScenes evaluation: runs evaluation (evidence: `projects/mmdet3d_plugin/datasets/nuscenes_e2e_dataset.py`)
- E2E dataset → Motion evaluation: runs motion metrics (evidence: `projects/mmdet3d_plugin/datasets/nuscenes_e2e_dataset.py`)
- Task coordinator → Tracking: coordinates tasks
- Task coordinator → Map segmentation: coordinates tasks
- Task coordinator → Motion prediction: coordinates tasks
- Task coordinator → Occupancy prediction: coordinates tasks
- Task coordinator → Planning: coordinates tasks
- Map segmentation → Segmentation components: inherits head (evidence: `projects/mmdet3d_plugin/uniad/dense_heads/panseg_head.py`)
- Engineer → Visualization runner: renders results (evidence: `tools/analysis_tools/visualize/run.py`)
- Visualization runner → BEV renderer: uses renderer (evidence: `tools/analysis_tools/visualize/run.py`)
- Visualization runner → Camera renderer: uses renderer (evidence: `tools/analysis_tools/visualize/run.py`)
- BEV renderer → Render base: inherits (evidence: `tools/analysis_tools/visualize/render/bev_render.py`)
- Camera renderer → Render base: inherits (evidence: `tools/analysis_tools/visualize/render/cam_render.py`)
