# yuudengg/distilldrive_3090 architecture

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

- Interactive diagram: https://gitdiagram.com/yuudengg/distilldrive_3090
- Repository: https://github.com/yuudengg/distilldrive_3090

## Overview

DistillDrive is an end-to-end autonomous-driving research system for training annotation-driven teacher models and camera-based student models, then distilling multi-mode planning behavior. The workflow spans nuScenes data preparation, scene perception, motion and planning, staged training, and open-/closed-loop evaluation; visualization supports inspection. The README documents the teacher-to-student and multi-stage distillation workflow. Source excerpts show selected training, dataset, and model interactions; unsampled subsystem links are omitted where their callers are not evidenced.

Main entry points: [`projects/mmdet3d_plugin/models/sparsedrive.py`](https://github.com/yuudengg/distilldrive_3090/blob/dev/projects/mmdet3d_plugin/models/sparsedrive.py) (SparseDrive student), [`projects/mmdet3d_plugin/datasets/nuscenes_3d_dataset_light.py`](https://github.com/yuudengg/distilldrive_3090/blob/dev/projects/mmdet3d_plugin/datasets/nuscenes_3d_dataset_light.py) (nuScenes datasets), [`projects/mmdet3d_plugin/models/distilldrive.py`](https://github.com/yuudengg/distilldrive_3090/blob/dev/projects/mmdet3d_plugin/models/distilldrive.py) (DistillDrive teacher), [`projects/mmdet3d_plugin/models/motion/motion_planning_head.py`](https://github.com/yuudengg/distilldrive_3090/blob/dev/projects/mmdet3d_plugin/models/motion/motion_planning_head.py) (Motion and planning)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Data and evaluation"]
  node_converter["nuScenes conversion"]
  node_dataset["nuScenes datasets"]
  node_pipelines["Data pipelines"]
  node_evaluation["Task evaluation"]
  node_boxutils["3D box utilities<br/>[utils.py]"]
end

subgraph group_perception["Perception models"]
  node_student["SparseDrive student<br/>[sparsedrive.py]"]
  node_detection["3D detection"]
  node_mapmodel["Map prediction"]
  node_attention["Feature aggregation<br/>[blocks.py]"]
  node_instancebank["Temporal instance bank<br/>[instance_bank.py]"]
end

subgraph group_planning["Distillation and planning"]
  node_teacher["DistillDrive teacher<br/>[distilldrive.py]"]
  node_dlp["DLP planning<br/>[dlp_head.py]"]
  node_motionplan["Motion and planning"]
  node_diffusion["Distribution modeling<br/>[distributions.py]"]
  node_stageconfigs["Distillation stages"]
end

subgraph group_runtime["Training and inspection"]
  node_traincli["Training entry<br/>[train.py]"]
  node_trainapi["Training orchestration<br/>[mmdet_train.py]"]
  node_bev["BEV visualization<br/>[bev_render.py]"]
  node_camera["Camera visualization<br/>[cam_render.py]"]
end

node_engineer(("Research engineer"))

node_engineer -.->|"prepares data"| node_converter
node_converter -.->|"creates annotations"| node_dataset
node_dataset -.->|"loads samples"| node_pipelines
node_dataset -->|"evaluates results"| node_evaluation
node_dataset -->|"uses geometry"| node_boxutils
node_engineer -->|"starts training"| node_traincli
node_traincli -->|"dispatches training"| node_trainapi
node_trainapi -->|"builds datasets"| node_dataset
node_traincli -.->|"builds configured model"| node_student
node_student -.->|"predicts objects"| node_detection
node_student -.->|"predicts maps"| node_mapmodel
node_detection -->|"aggregates features"| node_attention
node_student -.->|"retains temporal state"| node_instancebank
node_teacher -.->|"uses planning head"| node_dlp
node_student -.->|"predicts motion and plans"| node_motionplan
node_motionplan -->|"reads temporal state"| node_instancebank
node_motionplan -->|"models distributions"| node_diffusion
node_stageconfigs -.->|"configures stages"| node_teacher
node_teacher -->|"distills knowledge"| node_student
node_engineer -.->|"inspects predictions"| node_bev
node_engineer -.->|"inspects cameras"| node_camera
node_camera -->|"reuses render constants"| node_bev

click node_converter "https://github.com/yuudengg/distilldrive_3090/blob/dev/tools/data_converter/nuscenes_converter.py"
click node_dataset "https://github.com/yuudengg/distilldrive_3090/blob/dev/projects/mmdet3d_plugin/datasets/nuscenes_3d_dataset_light.py"
click node_pipelines "https://github.com/yuudengg/distilldrive_3090/tree/dev/projects/mmdet3d_plugin/datasets/pipelines"
click node_evaluation "https://github.com/yuudengg/distilldrive_3090/tree/dev/projects/mmdet3d_plugin/datasets/evaluation"
click node_boxutils "https://github.com/yuudengg/distilldrive_3090/blob/dev/projects/mmdet3d_plugin/datasets/utils.py"
click node_student "https://github.com/yuudengg/distilldrive_3090/blob/dev/projects/mmdet3d_plugin/models/sparsedrive.py"
click node_teacher "https://github.com/yuudengg/distilldrive_3090/blob/dev/projects/mmdet3d_plugin/models/distilldrive.py"
click node_detection "https://github.com/yuudengg/distilldrive_3090/blob/dev/projects/mmdet3d_plugin/models/detection3d/detection3d_head.py"
click node_mapmodel "https://github.com/yuudengg/distilldrive_3090/tree/dev/projects/mmdet3d_plugin/models/map"
click node_attention "https://github.com/yuudengg/distilldrive_3090/blob/dev/projects/mmdet3d_plugin/models/blocks.py"
click node_instancebank "https://github.com/yuudengg/distilldrive_3090/blob/dev/projects/mmdet3d_plugin/models/instance_bank.py"
click node_dlp "https://github.com/yuudengg/distilldrive_3090/blob/dev/projects/mmdet3d_plugin/models/dlp/dlp_head.py"
click node_motionplan "https://github.com/yuudengg/distilldrive_3090/blob/dev/projects/mmdet3d_plugin/models/motion/motion_planning_head.py"
click node_diffusion "https://github.com/yuudengg/distilldrive_3090/blob/dev/projects/mmdet3d_plugin/models/diffusion/distributions.py"
click node_stageconfigs "https://github.com/yuudengg/distilldrive_3090/blob/dev/projects/configs/stage0/distilldrive_stage0_distribution.py"
click node_traincli "https://github.com/yuudengg/distilldrive_3090/blob/dev/tools/train.py"
click node_trainapi "https://github.com/yuudengg/distilldrive_3090/blob/dev/projects/mmdet3d_plugin/apis/mmdet_train.py"
click node_bev "https://github.com/yuudengg/distilldrive_3090/blob/dev/tools/visualization/bev_render.py"
click node_camera "https://github.com/yuudengg/distilldrive_3090/blob/dev/tools/visualization/cam_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_pipelines,node_evaluation,node_boxutils toneBlue
class node_student,node_detection,node_mapmodel,node_attention,node_instancebank toneAmber
class node_teacher,node_dlp,node_motionplan,node_diffusion,node_stageconfigs toneMint
class node_traincli,node_trainapi,node_bev,node_camera toneRose
class node_engineer toneIndigo
```

## Components

### Data and evaluation

- [nuScenes conversion](https://github.com/yuudengg/distilldrive_3090/blob/dev/tools/data_converter/nuscenes_converter.py): `tools/data_converter/nuscenes_converter.py`
- [nuScenes datasets](https://github.com/yuudengg/distilldrive_3090/blob/dev/projects/mmdet3d_plugin/datasets/nuscenes_3d_dataset_light.py): `projects/mmdet3d_plugin/datasets/nuscenes_3d_dataset_light.py`
- [Data pipelines](https://github.com/yuudengg/distilldrive_3090/tree/dev/projects/mmdet3d_plugin/datasets/pipelines): `projects/mmdet3d_plugin/datasets/pipelines`
- [Task evaluation](https://github.com/yuudengg/distilldrive_3090/tree/dev/projects/mmdet3d_plugin/datasets/evaluation): `projects/mmdet3d_plugin/datasets/evaluation`
- [3D box utilities](https://github.com/yuudengg/distilldrive_3090/blob/dev/projects/mmdet3d_plugin/datasets/utils.py): `projects/mmdet3d_plugin/datasets/utils.py`

### Perception models

- [SparseDrive student](https://github.com/yuudengg/distilldrive_3090/blob/dev/projects/mmdet3d_plugin/models/sparsedrive.py): `projects/mmdet3d_plugin/models/sparsedrive.py`
- [3D detection](https://github.com/yuudengg/distilldrive_3090/blob/dev/projects/mmdet3d_plugin/models/detection3d/detection3d_head.py): `projects/mmdet3d_plugin/models/detection3d/detection3d_head.py`
- [Map prediction](https://github.com/yuudengg/distilldrive_3090/tree/dev/projects/mmdet3d_plugin/models/map): `projects/mmdet3d_plugin/models/map`
- [Feature aggregation](https://github.com/yuudengg/distilldrive_3090/blob/dev/projects/mmdet3d_plugin/models/blocks.py): `projects/mmdet3d_plugin/models/blocks.py`
- [Temporal instance bank](https://github.com/yuudengg/distilldrive_3090/blob/dev/projects/mmdet3d_plugin/models/instance_bank.py): `projects/mmdet3d_plugin/models/instance_bank.py`

### Distillation and planning

- [DistillDrive teacher](https://github.com/yuudengg/distilldrive_3090/blob/dev/projects/mmdet3d_plugin/models/distilldrive.py): `projects/mmdet3d_plugin/models/distilldrive.py`
- [DLP planning](https://github.com/yuudengg/distilldrive_3090/blob/dev/projects/mmdet3d_plugin/models/dlp/dlp_head.py): `projects/mmdet3d_plugin/models/dlp/dlp_head.py`
- [Motion and planning](https://github.com/yuudengg/distilldrive_3090/blob/dev/projects/mmdet3d_plugin/models/motion/motion_planning_head.py): `projects/mmdet3d_plugin/models/motion/motion_planning_head.py`
- [Distribution modeling](https://github.com/yuudengg/distilldrive_3090/blob/dev/projects/mmdet3d_plugin/models/diffusion/distributions.py): `projects/mmdet3d_plugin/models/diffusion/distributions.py`
- [Distillation stages](https://github.com/yuudengg/distilldrive_3090/blob/dev/projects/configs/stage0/distilldrive_stage0_distribution.py): `projects/configs/stage0/distilldrive_stage0_distribution.py`

### Training and inspection

- [Training entry](https://github.com/yuudengg/distilldrive_3090/blob/dev/tools/train.py): `tools/train.py`
- [Training orchestration](https://github.com/yuudengg/distilldrive_3090/blob/dev/projects/mmdet3d_plugin/apis/mmdet_train.py): `projects/mmdet3d_plugin/apis/mmdet_train.py`
- [BEV visualization](https://github.com/yuudengg/distilldrive_3090/blob/dev/tools/visualization/bev_render.py): `tools/visualization/bev_render.py`
- [Camera visualization](https://github.com/yuudengg/distilldrive_3090/blob/dev/tools/visualization/cam_render.py): `tools/visualization/cam_render.py`

### Other components

- **Research engineer**

## Connections

- Research engineer → nuScenes conversion: prepares data
- nuScenes conversion → nuScenes datasets: creates annotations
- nuScenes datasets → Data pipelines: loads samples
- nuScenes datasets → Task evaluation: evaluates results (evidence: `projects/mmdet3d_plugin/datasets/nuscenes_3d_dataset_light.py`)
- nuScenes datasets → 3D box utilities: uses geometry (evidence: `projects/mmdet3d_plugin/datasets/utils.py`)
- Research engineer → Training entry: starts training (evidence: `tools/train.py`)
- Training entry → Training orchestration: dispatches training (evidence: `tools/train.py`)
- Training orchestration → nuScenes datasets: builds datasets (evidence: `projects/mmdet3d_plugin/apis/mmdet_train.py`)
- Training entry → SparseDrive student: builds configured model
- SparseDrive student → 3D detection: predicts objects
- SparseDrive student → Map prediction: predicts maps
- 3D detection → Feature aggregation: aggregates features (evidence: `projects/mmdet3d_plugin/models/detection3d/detection3d_head.py`)
- SparseDrive student → Temporal instance bank: retains temporal state
- DistillDrive teacher → DLP planning: uses planning head
- SparseDrive student → Motion and planning: predicts motion and plans
- Motion and planning → Temporal instance bank: reads temporal state (evidence: `projects/mmdet3d_plugin/models/motion/motion_planning_head.py`)
- Motion and planning → Distribution modeling: models distributions (evidence: `projects/mmdet3d_plugin/models/motion/motion_planning_head.py`)
- Distillation stages → DistillDrive teacher: configures stages
- DistillDrive teacher → SparseDrive student: distills knowledge (evidence: `README.md`)
- Research engineer → BEV visualization: inspects predictions
- Research engineer → Camera visualization: inspects cameras
- Camera visualization → BEV visualization: reuses render constants (evidence: `tools/visualization/cam_render.py`)