README.md

---
license: apache-2.0
pipeline_tag: robotics
tags:
  - autoware
  - ros2
  - autonomous-driving
  - planning
  - trajectory-generation
  - diffusion
  - tensorrt
  - onnx
---

# Diffusion Planner for Autoware (`diffusion_planner`)

Trajectory generation models for autonomous driving, used by the
[`autoware_diffusion_planner`](https://github.com/autowarefoundation/autoware_universe/tree/main/planning/autoware_diffusion_planner)
node in [Autoware](https://github.com/autowarefoundation/autoware).

The models follow the **Diffusion Planner** [1] architecture from "Diffusion-Based Planning for Autonomous
Driving with Flexible Guidance" (Zheng et al.). The node generates smooth, feasible, and safe ego trajectories
by considering dynamic and static obstacles, vehicle kinematics, Lanelet2 map context, the route, and traffic
signals with speed limits. Models are distributed as ONNX and run with TensorRT (default) or ONNX Runtime.

## Model overview

| | |
| --- | --- |
| Task | Ego trajectory generation (plus candidate trajectories, predicted objects, and turn indicator commands) |
| Architecture | Diffusion Planner (diffusion-based trajectory generation) |
| Runtime | TensorRT (default, FP32) or ONNX Runtime (CPU, CUDA, or TensorRT execution provider) via the `autoware_diffusion_planner` ROS 2 node |
| Format | ONNX (Autoware builds the TensorRT engine locally on first launch) |
| License | Apache-2.0 |

## Versions in this repository

This is a multi-version repository. Each git tag contains exactly that version's file set at the repository
root; `main` always points to the newest tag (currently `v5.0`). Consumers must pin `--revision <tag>` and
never rely on `main`. Autoware installs each version side by side under
`~/autoware_data/ml_models/diffusion_planner/<tag>/`.

| Tag | Release date | Files | Notes (from the package's model version history) |
| --- | --- | --- | --- |
| `v3.0` | 2026/01/09 | `diffusion_planner.onnx`, `diffusion_planner.param.json`, `deploy_metadata.yaml` | Added `TURN_INDICATOR_OUTPUT_KEEP` output; supervised fine-tuning (SFT) with carefully filtered data; encoder layers increased from 3 to 6 |
| `v3.1` | 2026/03/05 | `diffusion_planner.onnx`, `diffusion_planner.param.json`, `deploy_metadata.yaml` | ONNX-simplified model for faster TensorRT engine build and reduced GPU memory; same weights as v3.0 (no retraining) |
| `v4.0` | 2026/03/23 | `diffusion_planner.onnx`, `diffusion_planner.param.json`, `deploy_metadata.yaml` | Added `delay` input for Real-Time Chunking (RTC); one-hot type encoding for polygons and line strings; `NUM_LINE_STRINGS` increased from 10 to 60; line string resampling |
| `v5.0` | not documented | v4.0 set plus `diffusion_planner_encoder.onnx`, `diffusion_planner_decoder.onnx`, `diffusion_planner_turn_indicator.onnx` | Adds separate encoder, decoder, and turn indicator sub-models used by the node's `multi_step` mode (configurable DPM solver steps) |

The model versioning scheme uses major and minor numbers: the major version changes when model inputs/outputs
or architecture change (models with a different major version are not compatible with the ROS node), and the
minor version changes when only the weights are updated. The package also documents older model versions
(0.1, 1.0, 2.0) that are not compatible with the current node; they are not distributed here.

## Files

Files at `main` / `v5.0` (earlier tags contain `diffusion_planner.onnx`, `diffusion_planner.param.json`,
and `deploy_metadata.yaml`):

| File | Description |
| --- | --- |
| `diffusion_planner.onnx` | Single-step model (full network in one ONNX graph) |
| `diffusion_planner_encoder.onnx` | Encoder sub-model for multi-step inference |
| `diffusion_planner_decoder.onnx` | Decoder sub-model for multi-step inference (run for a configurable number of DPM solver steps) |
| `diffusion_planner_turn_indicator.onnx` | Turn indicator sub-model |
| `diffusion_planner.param.json` | Model parameters consumed by the node alongside the ONNX files |
| `deploy_metadata.yaml` | Deployment metadata recording the artifact version of this repository |

> **TensorRT engines are not distributed here.** TensorRT engines are specific to the GPU architecture and
> TensorRT version they are built on and are not portable, so Autoware builds them locally from the ONNX files
> on first launch (or via `build_only:=true`).

## Inputs and outputs (as used by the node)

**Inputs**

| Topic | Message Type | Description |
| --- | --- | --- |
| `~/input/odometry` | `nav_msgs/msg/Odometry` | Ego vehicle odometry |
| `~/input/acceleration` | `geometry_msgs/msg/AccelWithCovarianceStamped` | Ego acceleration |
| `~/input/tracked_objects` | `autoware_perception_msgs/msg/TrackedObjects` | Detected dynamic objects |
| `~/input/traffic_signals` | `autoware_perception_msgs/msg/TrafficLightGroupArray` | Traffic light states |
| `~/input/vector_map` | `autoware_map_msgs/msg/LaneletMapBin` | Lanelet2 map |
| `~/input/route` | `autoware_planning_msgs/msg/LaneletRoute` | Route information |
| `~/input/turn_indicators` | `autoware_vehicle_msgs/msg/TurnIndicatorsReport` | Turn indicator information |

**Outputs**

| Topic | Message Type | Description |
| --- | --- | --- |
| `~/output/trajectory` | `autoware_planning_msgs/msg/Trajectory` | Planned trajectory for the ego vehicle |
| `~/output/trajectories` | `autoware_internal_planning_msgs/msg/CandidateTrajectories` | Multiple candidate trajectories |
| `~/output/predicted_objects` | `autoware_perception_msgs/msg/PredictedObjects` | Predicted future states of dynamic objects |
| `~/output/turn_indicators` | `autoware_vehicle_msgs/msg/TurnIndicatorsCommand` | Planned turn indicator command |
| `~/output/debug/traffic_signal` | `autoware_perception_msgs/msg/TrafficLightGroup` | First traffic light on route (ego forward) |
| `~/debug/lane_marker` | `visualization_msgs/msg/MarkerArray` | Lane debug markers |
| `~/debug/route_marker` | `visualization_msgs/msg/MarkerArray` | Route debug markers |

## Usage in Autoware

Autoware downloads these artifacts to `~/autoware_data/ml_models/diffusion_planner/<tag>/` (see
[Download artifacts](https://github.com/autowarefoundation/autoware/blob/main/ansible/roles/artifacts/README.md#download-artifacts)).
The node's config (`config/diffusion_planner.param.yaml`) points at one version directory, currently `v5.0`.

Launch the planning simulator with the diffusion planner selected:

```bash
ros2 launch autoware_launch planning_simulator.launch.xml \
  map_path:=/path/to/your/map \
  vehicle_model:=sample_vehicle \
  sensor_model:=sample_sensor_kit \
  planning_setting:=diffusion_planner
```

`planning_setting:=diffusion_planner` swaps the trajectory generator, the planning validator input topic, and
the diagnostics graph, so no additional launch-file edits are required. The node's own launch file
(`diffusion_planner.launch.xml`) accepts `build_only:=true` to shut the node down after model initialization,
which can be used to pre-build the TensorRT engine.
See the [package README](https://github.com/autowarefoundation/autoware_universe/tree/main/planning/autoware_diffusion_planner)
for the full parameter reference.

## Provenance

These artifacts were previously hosted at
`https://awf.ml.dev.web.auto/planning/models/diffusion_planner/<version>/` for versions `v3.0` through
`v5.0`. The HF tags map one-to-one to those source version directories, so traceability to the original
hosting is preserved.

## Training

- Training fork (used to train these models): <https://github.com/tier4/Diffusion-Planner>
- Original implementation: <https://github.com/ZhengYinan-AIR/Diffusion-Planner>
- Paper: "Diffusion-Based Planning for Autonomous Driving with Flexible Guidance", arXiv:2501.15564

The models were trained by TIER IV. The package's model version history records that training used TIER IV
synthetic and real driving data, with supervised fine-tuning on carefully filtered data introduced in v3.0; the
exact dataset composition per version is not publicly documented.

## Limitations

- Models with a major version different from the one the ROS node expects are not compatible with the node.
- The node is aimed at the proposed [Autoware new planning framework](https://github.com/tier4/new_planning_framework).
- Training data is TIER IV internal; performance on other vehicle platforms and operational domains is not
  publicly characterized.

## Citation

```bibtex
@article{zheng2025diffusionplanner,
  title   = {Diffusion-Based Planning for Autonomous Driving with Flexible Guidance},
  author  = {Zheng, Yinan and others},
  journal = {arXiv preprint arXiv:2501.15564},
  year    = {2025}
}
```

## References

- [1] Zheng et al., "Diffusion-Based Planning for Autonomous Driving with Flexible Guidance", arXiv:2501.15564, 2025.
- Original implementation: <https://github.com/ZhengYinan-AIR/Diffusion-Planner>
- Training fork: <https://github.com/tier4/Diffusion-Planner>
- Consuming package: <https://github.com/autowarefoundation/autoware_universe/tree/main/planning/autoware_diffusion_planner>
- Autoware: <https://github.com/autowarefoundation/autoware>