# hustvl/maptr architecture

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

- Interactive diagram: https://gitdiagram.com/hustvl/maptr
- Repository: https://github.com/hustvl/maptr

## Overview

This repository’s primary product is MapTR: a framework that constructs vectorized HD maps from driving-scene sensor data. Its main workflow is to load a configured dataset, train or run a map-prediction model, and produce vectorized map elements; documented variants include camera–LiDAR fusion and alternative BEV encoders. The graph also shows data preparation and prediction visualization as supporting workflows. The source index confirms the training entry point’s dataset/model imports and identifies the MapTR dataset and head; internal links not evidenced by the excerpts or README are omitted.

Main entry points: [`projects/mmdet3d_plugin/datasets/nuscenes_map_dataset.py`](https://github.com/hustvl/maptr/blob/main/projects/mmdet3d_plugin/datasets/nuscenes_map_dataset.py) (Map dataset), [`projects/mmdet3d_plugin/maptr/dense_heads/maptr_head.py`](https://github.com/hustvl/maptr/blob/main/projects/mmdet3d_plugin/maptr/dense_heads/maptr_head.py) (MapTR head), [`projects/mmdet3d_plugin/bevformer/modules/spatial_cross_attention.py`](https://github.com/hustvl/maptr/blob/main/projects/mmdet3d_plugin/bevformer/modules/spatial_cross_attention.py) (BEVFormer encoder), [`tools/train.py`](https://github.com/hustvl/maptr/blob/main/tools/train.py) (Training entry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Data handling"]
  node_dataset["Map dataset"]
  node_pipelines["3D input pipelines<br/>[loading.py]"]
end

subgraph group_learning["Map prediction"]
  node_backbone["Image backbone<br/>[swin.py]"]
  node_bevformer["BEVFormer encoder"]
  node_position["Position embedding"]
  node_map_head["MapTR head<br/>[maptr_head.py]"]
  node_map_loss["Map losses<br/>[map_loss.py]"]
  node_bevformer_config["BEVFormer config<br/>[bevformer_small.py]"]
  node_fusion_config["Fusion config"]
end

subgraph group_runtime["Execution and results"]
  node_training["Training entry<br/>[train.py]"]
  node_inference["Inference API<br/>[inference.py]"]
  node_visualize["Prediction visualization<br/>[vis_pred.py]"]
end

subgraph group_support["Supporting workflows"]
  node_prepare["Dataset preparation<br/>[create_data.py]"]
  node_converters["Dataset converters"]
end

node_user(("Engineer"))
node_driving_data[("Driving data")]
node_vector_map["Vector map"]

node_user -->|"prepares data"| node_prepare
node_driving_data -->|"converts"| node_prepare
node_prepare -->|"dispatches to"| node_converters
node_driving_data -->|"provides samples"| node_dataset
node_dataset -.->|"loads inputs"| node_pipelines
node_user -->|"starts training"| node_training
node_training -->|"builds dataset"| node_dataset
node_training -->|"builds model"| node_map_head
node_dataset -.->|"supplies sensor input"| node_backbone
node_backbone -.->|"encodes views"| node_bevformer
node_position -.->|"embeds positions"| node_bevformer
node_bevformer -.->|"provides BEV features"| node_map_head
node_map_head -.->|"optimizes with"| node_map_loss
node_map_head -->|"predicts elements"| node_vector_map
node_user -->|"requests prediction"| node_inference
node_inference -->|"returns predictions"| node_vector_map
node_user -->|"views predictions"| node_visualize
node_visualize -.->|"runs model"| node_inference
node_bevformer_config -.->|"configures encoder"| node_bevformer
node_fusion_config -.->|"configures fusion data"| node_dataset

click node_prepare "https://github.com/hustvl/maptr/blob/main/tools/create_data.py"
click node_converters "https://github.com/hustvl/maptr/blob/main/tools/data_converter/nuscenes_converter.py"
click node_dataset "https://github.com/hustvl/maptr/blob/main/projects/mmdet3d_plugin/datasets/nuscenes_map_dataset.py"
click node_pipelines "https://github.com/hustvl/maptr/blob/main/mmdetection3d/mmdet3d/datasets/pipelines/loading.py"
click node_training "https://github.com/hustvl/maptr/blob/main/tools/train.py"
click node_inference "https://github.com/hustvl/maptr/blob/main/mmdetection3d/mmdet3d/apis/inference.py"
click node_backbone "https://github.com/hustvl/maptr/blob/main/projects/mmdet3d_plugin/models/backbones/swin.py"
click node_bevformer "https://github.com/hustvl/maptr/blob/main/projects/mmdet3d_plugin/bevformer/modules/spatial_cross_attention.py"
click node_position "https://github.com/hustvl/maptr/blob/main/projects/mmdet3d_plugin/models/utils/position_embedding.py"
click node_map_head "https://github.com/hustvl/maptr/blob/main/projects/mmdet3d_plugin/maptr/dense_heads/maptr_head.py"
click node_map_loss "https://github.com/hustvl/maptr/blob/main/projects/mmdet3d_plugin/maptr/losses/map_loss.py"
click node_visualize "https://github.com/hustvl/maptr/blob/main/tools/maptr/vis_pred.py"
click node_bevformer_config "https://github.com/hustvl/maptr/blob/main/projects/configs/bevformer/bevformer_small.py"
click node_fusion_config "https://github.com/hustvl/maptr/blob/main/projects/configs/maptr/maptr_tiny_fusion_24e.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_dataset,node_pipelines toneBlue
class node_backbone,node_bevformer,node_position,node_map_head,node_map_loss,node_bevformer_config,node_fusion_config,node_driving_data toneAmber
class node_training,node_inference,node_visualize toneMint
class node_prepare,node_converters toneRose
class node_user,node_vector_map toneIndigo
```

## Components

### Data handling

- [Map dataset](https://github.com/hustvl/maptr/blob/main/projects/mmdet3d_plugin/datasets/nuscenes_map_dataset.py): `projects/mmdet3d_plugin/datasets/nuscenes_map_dataset.py`
- [3D input pipelines](https://github.com/hustvl/maptr/blob/main/mmdetection3d/mmdet3d/datasets/pipelines/loading.py): `mmdetection3d/mmdet3d/datasets/pipelines/loading.py`

### Map prediction

- [Image backbone](https://github.com/hustvl/maptr/blob/main/projects/mmdet3d_plugin/models/backbones/swin.py): `projects/mmdet3d_plugin/models/backbones/swin.py`
- [BEVFormer encoder](https://github.com/hustvl/maptr/blob/main/projects/mmdet3d_plugin/bevformer/modules/spatial_cross_attention.py): `projects/mmdet3d_plugin/bevformer/modules/spatial_cross_attention.py`
- [Position embedding](https://github.com/hustvl/maptr/blob/main/projects/mmdet3d_plugin/models/utils/position_embedding.py): `projects/mmdet3d_plugin/models/utils/position_embedding.py`
- [MapTR head](https://github.com/hustvl/maptr/blob/main/projects/mmdet3d_plugin/maptr/dense_heads/maptr_head.py): `projects/mmdet3d_plugin/maptr/dense_heads/maptr_head.py`
- [Map losses](https://github.com/hustvl/maptr/blob/main/projects/mmdet3d_plugin/maptr/losses/map_loss.py): `projects/mmdet3d_plugin/maptr/losses/map_loss.py`
- [BEVFormer config](https://github.com/hustvl/maptr/blob/main/projects/configs/bevformer/bevformer_small.py): `projects/configs/bevformer/bevformer_small.py`
- [Fusion config](https://github.com/hustvl/maptr/blob/main/projects/configs/maptr/maptr_tiny_fusion_24e.py): `projects/configs/maptr/maptr_tiny_fusion_24e.py`

### Execution and results

- [Training entry](https://github.com/hustvl/maptr/blob/main/tools/train.py): `tools/train.py`
- [Inference API](https://github.com/hustvl/maptr/blob/main/mmdetection3d/mmdet3d/apis/inference.py): `mmdetection3d/mmdet3d/apis/inference.py`
- [Prediction visualization](https://github.com/hustvl/maptr/blob/main/tools/maptr/vis_pred.py): `tools/maptr/vis_pred.py`

### Supporting workflows

- [Dataset preparation](https://github.com/hustvl/maptr/blob/main/tools/create_data.py): `tools/create_data.py`
- [Dataset converters](https://github.com/hustvl/maptr/blob/main/tools/data_converter/nuscenes_converter.py): `tools/data_converter/nuscenes_converter.py`

### Other components

- **Engineer**
- **Driving data**
- **Vector map**

## Connections

- Engineer → Dataset preparation: prepares data (evidence: `tools/create_data.py`)
- Driving data → Dataset preparation: converts (evidence: `tools/create_data.py`)
- Dataset preparation → Dataset converters: dispatches to (evidence: `tools/create_data.py`)
- Driving data → Map dataset: provides samples (evidence: `README.md`)
- Map dataset → 3D input pipelines: loads inputs
- Engineer → Training entry: starts training (evidence: `tools/train.py`)
- Training entry → Map dataset: builds dataset (evidence: `tools/train.py`)
- Training entry → MapTR head: builds model (evidence: `tools/train.py`)
- Map dataset → Image backbone: supplies sensor input
- Image backbone → BEVFormer encoder: encodes views
- Position embedding → BEVFormer encoder: embeds positions
- BEVFormer encoder → MapTR head: provides BEV features
- MapTR head → Map losses: optimizes with
- MapTR head → Vector map: predicts elements (evidence: `README.md`)
- Engineer → Inference API: requests prediction (evidence: `mmdetection3d/mmdet3d/apis/inference.py`)
- Inference API → Vector map: returns predictions (evidence: `README.md`)
- Engineer → Prediction visualization: views predictions (evidence: `tools/maptr/vis_pred.py`)
- Prediction visualization → Inference API: runs model
- BEVFormer config → BEVFormer encoder: configures encoder
- Fusion config → Map dataset: configures fusion data
