# mczhi/gameformer-planner architecture

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

- Interactive diagram: https://gitdiagram.com/mczhi/gameformer-planner
- Repository: https://github.com/mczhi/gameformer-planner

## Overview

GameFormer-Planner is an autonomous-driving prediction and planning framework evaluated in nuPlan. Its main workflow converts scenario data into model features, predicts interactive futures and an ego plan, and uses a map-aware planner to produce a refined driving trajectory. The README describes feature processing, path planning, model query, and trajectory refinement; the tree supports those subsystems, though excerpts do not establish every runtime connection. Training and benchmark evaluation are represented as separate product workflows.

Main entry points: [`Planner/planner.py`](https://github.com/mczhi/gameformer-planner/blob/main/Planner/planner.py) (nuPlan planner), [`run_nuplan_test.py`](https://github.com/mczhi/gameformer-planner/blob/main/run_nuplan_test.py) (Benchmark runner), [`data_process.py`](https://github.com/mczhi/gameformer-planner/blob/main/data_process.py) (Scenario processing), [`train_predictor.py`](https://github.com/mczhi/gameformer-planner/blob/main/train_predictor.py) (Model training)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Data preparation"]
  node_data_process["Scenario processing<br/>[data_process.py]"]
  node_data_utils["Feature utilities<br/>[data_utils.py]"]
  node_processed["Processed scenarios"]
end

subgraph group_model["Prediction and planning model"]
  node_predictor["GameFormer model<br/>[predictor.py]"]
  node_predictor_modules["Model components"]
end

subgraph group_runtime["Simulation planning"]
  node_observation["Runtime features<br/>[observation.py]"]
  node_lattice["Lattice path search"]
  node_planner_utils["Planning utilities<br/>[planner_utils.py]"]
  node_refinement["Trajectory refinement<br/>[refinement.py]"]
  node_smoother["Motion smoother<br/>[smoother.py]"]
  node_occupancy["Occupancy adapter"]
  node_planner["nuPlan planner<br/>[planner.py]"]
end

subgraph group_evaluation["Training and evaluation"]
  node_trainer["Model training<br/>[train_predictor.py]"]
  node_test_runner["Benchmark runner<br/>[run_nuplan_test.py]"]
  node_common["Metrics and reports<br/>[common_utils.py]"]
end

node_dataset["nuPlan data"]
node_maps["nuPlan maps"]
node_simulation(("nuPlan simulation"))
node_checkpoint["Trained model"]

node_dataset -->|"scenario input"| node_data_process
node_maps -->|"map input"| node_data_process
node_data_process -->|"uses features"| node_data_utils
node_data_process -->|"writes features"| node_processed
node_processed -->|"training data"| node_trainer
node_trainer -->|"trains model"| node_predictor
node_trainer -->|"saves weights"| node_checkpoint
node_planner -->|"builds features"| node_observation
node_planner -->|"requests path"| node_lattice
node_planner -->|"queries model"| node_predictor
node_predictor -->|"uses modules"| node_predictor_modules
node_planner -->|"refines trajectory"| node_refinement
node_planner -->|"uses occupancy"| node_occupancy
node_planner -->|"uses utilities"| node_planner_utils
node_lattice -->|"uses utilities"| node_planner_utils
node_refinement -->|"smooths path"| node_smoother
node_simulation -->|"requests plans"| node_planner
node_test_runner -->|"runs scenarios"| node_simulation
node_test_runner -->|"configures planner"| node_planner
node_test_runner -->|"loads weights"| node_checkpoint
node_test_runner -->|"builds metrics"| node_common
node_simulation -->|"provides results"| node_common

click node_data_process "https://github.com/mczhi/gameformer-planner/blob/main/data_process.py"
click node_data_utils "https://github.com/mczhi/gameformer-planner/blob/main/GameFormer/data_utils.py"
click node_observation "https://github.com/mczhi/gameformer-planner/blob/main/Planner/observation.py"
click node_predictor "https://github.com/mczhi/gameformer-planner/blob/main/GameFormer/predictor.py"
click node_predictor_modules "https://github.com/mczhi/gameformer-planner/blob/main/GameFormer/predictor_modules.py"
click node_lattice "https://github.com/mczhi/gameformer-planner/blob/main/Planner/state_lattice_path_planner.py"
click node_planner_utils "https://github.com/mczhi/gameformer-planner/blob/main/Planner/planner_utils.py"
click node_refinement "https://github.com/mczhi/gameformer-planner/blob/main/Planner/refinement.py"
click node_smoother "https://github.com/mczhi/gameformer-planner/blob/main/Planner/smoother.py"
click node_occupancy "https://github.com/mczhi/gameformer-planner/blob/main/Planner/occupancy_adapter.py"
click node_planner "https://github.com/mczhi/gameformer-planner/blob/main/Planner/planner.py"
click node_trainer "https://github.com/mczhi/gameformer-planner/blob/main/train_predictor.py"
click node_test_runner "https://github.com/mczhi/gameformer-planner/blob/main/run_nuplan_test.py"
click node_common "https://github.com/mczhi/gameformer-planner/blob/main/common_utils.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_data_process,node_data_utils,node_processed toneBlue
class node_predictor,node_predictor_modules toneAmber
class node_observation,node_lattice,node_planner_utils,node_refinement,node_smoother,node_occupancy,node_planner toneMint
class node_trainer,node_test_runner,node_common toneRose
class node_dataset,node_maps,node_simulation,node_checkpoint toneIndigo
```

## Components

### Data preparation

- [Scenario processing](https://github.com/mczhi/gameformer-planner/blob/main/data_process.py): `data_process.py`
- [Feature utilities](https://github.com/mczhi/gameformer-planner/blob/main/GameFormer/data_utils.py): `GameFormer/data_utils.py`
- **Processed scenarios**

### Prediction and planning model

- [GameFormer model](https://github.com/mczhi/gameformer-planner/blob/main/GameFormer/predictor.py): `GameFormer/predictor.py`
- [Model components](https://github.com/mczhi/gameformer-planner/blob/main/GameFormer/predictor_modules.py): `GameFormer/predictor_modules.py`

### Simulation planning

- [Runtime features](https://github.com/mczhi/gameformer-planner/blob/main/Planner/observation.py): `Planner/observation.py`
- [Lattice path search](https://github.com/mczhi/gameformer-planner/blob/main/Planner/state_lattice_path_planner.py): `Planner/state_lattice_path_planner.py`
- [Planning utilities](https://github.com/mczhi/gameformer-planner/blob/main/Planner/planner_utils.py): `Planner/planner_utils.py`
- [Trajectory refinement](https://github.com/mczhi/gameformer-planner/blob/main/Planner/refinement.py): `Planner/refinement.py`
- [Motion smoother](https://github.com/mczhi/gameformer-planner/blob/main/Planner/smoother.py): `Planner/smoother.py`
- [Occupancy adapter](https://github.com/mczhi/gameformer-planner/blob/main/Planner/occupancy_adapter.py): `Planner/occupancy_adapter.py`
- [nuPlan planner](https://github.com/mczhi/gameformer-planner/blob/main/Planner/planner.py): `Planner/planner.py`

### Training and evaluation

- [Model training](https://github.com/mczhi/gameformer-planner/blob/main/train_predictor.py): `train_predictor.py`
- [Benchmark runner](https://github.com/mczhi/gameformer-planner/blob/main/run_nuplan_test.py): `run_nuplan_test.py`
- [Metrics and reports](https://github.com/mczhi/gameformer-planner/blob/main/common_utils.py): `common_utils.py`

### Other components

- **nuPlan data**
- **nuPlan maps**
- **nuPlan simulation**
- **Trained model**

## Connections

- nuPlan data → Scenario processing: scenario input
- nuPlan maps → Scenario processing: map input
- Scenario processing → Feature utilities: uses features
- Scenario processing → Processed scenarios: writes features
- Processed scenarios → Model training: training data
- Model training → GameFormer model: trains model
- Model training → Trained model: saves weights
- nuPlan planner → Runtime features: builds features
- nuPlan planner → Lattice path search: requests path
- nuPlan planner → GameFormer model: queries model
- GameFormer model → Model components: uses modules
- nuPlan planner → Trajectory refinement: refines trajectory
- nuPlan planner → Occupancy adapter: uses occupancy
- nuPlan planner → Planning utilities: uses utilities
- Lattice path search → Planning utilities: uses utilities
- Trajectory refinement → Motion smoother: smooths path
- nuPlan simulation → nuPlan planner: requests plans
- Benchmark runner → nuPlan simulation: runs scenarios
- Benchmark runner → nuPlan planner: configures planner
- Benchmark runner → Trained model: loads weights
- Benchmark runner → Metrics and reports: builds metrics
- nuPlan simulation → Metrics and reports: provides results