# pnnnnnnn/uni-prevpredmap architecture

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

- Interactive diagram: https://gitdiagram.com/pnnnnnnn/uni-prevpredmap
- Repository: https://github.com/pnnnnnnn/uni-prevpredmap

## Overview

##### Project Type and Purpose
- Uni-PrevPredMap is a research-grade, open-source framework for online vectorized HD map construction.
- It builds on two foundations: the mmdetection3d core library (for 3D object detection pipelines) and MapTRv2 (for BEV-based map prediction).
- The key innovation is a unified, prior-informed modeling pipeline that fuses previous model predictions and simulated outdated HD maps in three modes (non-prior, temporal-prior, temporal-map-fusion).

##### High-Level File Structure and Architectural Choices
- Top-level directories:
- assets, docs, figs – static assets and documentation
- mmdetection3d – core library (datasets, models, ops, apis, training/test scripts, CI, docs)
- projects – research projects (MapTR, MapTRv2, Uni-PrevPredMap configs and plugin code)
- tools – utility scripts (data conversion, training wrappers, benchmarking, visualization)
- Patterns:
- Config-driven design: almost every experiment or model is defined by a .py config under mmdetection3d/configs and projects/configs.
- Plugin architecture: new detectors, dataset loaders, loss functions, and ops are registered via mmdet hooks and the projects/mmdet3d_plugin folder.
- Modular data pipeline: raw data → data_converter scripts → mmdet3d Dataset classes → pipeline transforms → model input tensors.

##### Key Components
a. Data Sources & Conversion
- Raw HD map datasets (nuScenes, ArgoVerse2, KITTI, Waymo, etc.)
- tools/data_converter & mmdetection3d/tools/create_data.py
- Output: tile-indexed 3D vectorized prior databases
b. Data Loading & Preprocessing
- mmdetection3d/datasets + pipelines (loading, augment, formatting)
- projects/mmdet3d_plugin datasets for map data (e.g., av2_map_dataset.py)
c. Core Library (mmdetection3d)
- Model registry (builder.py, backbones, heads, detectors, losses, middle_encoders, voxel_encoders)
- Ops (custom CUDA kernels: spconv, voxelization, ball_query, etc.)
- Training/Evaluation APIs (mmdet3d/apis/train.py, test.py, inference.py)
d. Uni-PrevPredMap Plugin
- projects/mmdet3d_plugin (bevformer, maptr, uniprevpredmap modules)
- Tile-indexed 3D vectorized global map processor
- Temporal fusion modules (custom hooks, fusion_layers, modules under plugin)
e. Configuration Manager
- experiments defined in projects/configs/uniprevpredmap/*.py
- Base configs inherited from mmdetection3d/configs/_base_
f. Training & Evaluation Workflow
- CLI wrappers: tools/train.py, tools/dist_train.sh, mmdet3d/tools/train.py
- Multi-GPU launcher, Slurm scripts (tools/slurm_train.sh)
- Benchmarking & flops analysis (tools/analysis_tools)
g. Inference & Visualization
- Demo scripts: mmdetection3d/demo/*.py, tools/misc/visualize_results.py
- Visualization of vectorized HD maps (Open3D, matplotlib)
h. External Dependencies
- PyTorch, MMCV, MMDetection3D, spconv, CUDA, Open3D, numpy, OpenCV

##### Relationships and Data Flow
- Raw data → data_converter → Dataset class → pipeline transforms → model input
- Model input → backbone → middle encoder → neck → dense heads + decode heads → predicted map tokens
- Predictions + previous-frame prior + outdated HD map → fusion modules → refined predictions
- Loss computation → backprop → weight update
- Trained model → inference API → vectorized HD map output → visualization

##### Architectural Patterns & Principles
- Config-first, plugin-based modularity: new research modules register seamlessly with the mmdetection3d core.
- Separation of concerns: data conversion, data loading, model definition, training loops, and visualization are decoupled.
- Layered design:
- Data layer (conversion, loading)
- Core compute layer (ops, backbones, detectors)
- Research layer (plugin modules, prior-informed fusion)
- Application layer (training scripts, inference demos)

##### Final Advice
- Break the system into as many logical components as needed to reveal data, control, and module dependencies.
- Be explicit about the interplay between mmdetection3d core and the Uni-PrevPredMap research plugin.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Data Conversion & Sources
    subgraph "Data Conversion & Sources"
        direction TB
        RawData["Raw HD Map Datasets"]:::green
        DataConverter["Data Converter Tools"]:::green
        CreateData["Create Data Script"]:::green
        TileDB["Tile-Indexed HD Map DB"]:::green
    end

    %% Data Loading & Preprocessing
    subgraph "Data Loading & Preprocessing"
        direction TB
        MMD3DDatasets["mmdetection3d Datasets"]:::green
        MMD3DPipelines["Pipeline Transforms"]:::green
        PluginDatasets["Plugin Map Datasets"]:::green
    end

    %% Core Library
    subgraph "Core Library (mmdetection3d)"
        direction TB
        Builder["Model Registry (builder.py)"]:::blue
        Backbones["Backbones"]:::blue
        MiddleEnc["Middle Encoders"]:::blue
        VoxelEnc["Voxel Encoders"]:::blue
        DenseHeads["Dense Heads"]:::blue
        Ops["Custom Ops (spconv, voxelization)"]:::blue
        TrainAPI["Training API"]:::blue
        TestAPI["Test API"]:::blue
        InferAPI["Inference API"]:::blue
    end

    %% Uni-PrevPredMap Plugin
    subgraph "Uni-PrevPredMap Plugin"
        direction TB
        GlobalMapTile["Global Map Vec Tile"]:::orange
        GlobalMap["Global Map"]:::orange
        GlobalMapVec["Global Map Vec"]:::orange
        HooksEpoch["Set Epoch Info Hook"]:::orange
        HooksIter["Set Iter Info Hook"]:::orange
        subgraph "MapTR Modules"
            direction TB
            MapTRDet["MapTR Detector"]:::orange
            MapTRV2Det["MapTRv2 Detector"]:::orange
            MapTRHead["MapTR Head"]:::orange
            MapTRV2Head["MapTRv2 Head"]:::orange
            Encoder["MapTR Encoder"]:::orange
            Decoder["MapTR Decoder"]:::orange
        end
    end

    %% Configuration Manager
    subgraph "Configuration Manager"
        direction TB
        BaseConfigs["Base Configs"]:::grey
        ProjectConfigs["Project Configs"]:::grey
    end

    %% Training & Evaluation Workflow
    subgraph "Training & Evaluation Workflow"
        direction TB
        ToolsTrain["tools/train.py"]:::purple
        DistTrain["tools/dist_train.sh"]:::purple
        SlurmTrain["tools/slurm_train.sh"]:::purple
        MMD3DTrain["mmdetection3d/tools/train.py"]:::purple
        MMD3DDist["mmdetection3d/tools/dist_train.sh"]:::purple
    end

    %% Inference & Visualization
    subgraph "Inference & Visualization"
        direction TB
        MonoDemo["mono_det_demo.py"]:::purple
        PCDDemo["pcd_demo.py"]:::purple
        Visualize["visualize_results.py"]:::purple
        MapTRVis["maptr/vis_pred.py"]:::purple
        MapTRV2Vis["maptrv2/av2_vis_pred.py"]:::purple
    end

    %% Data Flow
    RawData -->|ingest| DataConverter
    DataConverter -->|process| CreateData
    CreateData -->|output| TileDB
    TileDB -->|load| MMD3DDatasets
    TileDB -->|load| PluginDatasets
    MMD3DDatasets -->|transform| MMD3DPipelines
    MMD3DPipelines -->|feed| Builder
    BaseConfigs -->|inherit| ProjectConfigs
    ProjectConfigs -->|configures| Builder
    Builder -->|builds| Backbones
    Backbones --> MiddleEnc --> VoxelEnc --> DenseHeads
    DenseHeads -->|predict| GlobalMapTile
    GlobalMapTile -->|fusion| GlobalMap
    GlobalMap --> GlobalMapVec --> HooksEpoch & HooksIter
    HooksEpoch -->|hook| Builder
    HooksIter -->|hook| Builder
    Builder -->|register| MapTRDet & MapTRV2Det
    MapTRDet --> Encoder --> Decoder --> MapTRHead
    MapTRV2Det --> Encoder --> Decoder --> MapTRV2Head
    Builder -->|train| TrainAPI
    TrainAPI -->|update| Builder
    Builder -->|test| TestAPI
    Builder -->|infer| InferAPI
    InferAPI -->|output| MonoDemo & PCDDemo
    InferAPI -->|output| Visualize & MapTRVis & MapTRV2Vis
    ToolsTrain & DistTrain & SlurmTrain -->|launch| TrainAPI
    MMD3DTrain & MMD3DDist -->|launch| TrainAPI

    %% Click Events
    click DataConverter "https://github.com/pnnnnnnn/uni-prevpredmap/tree/main/mmdetection3d/tools/data_converter/"
    click CreateData "https://github.com/pnnnnnnn/uni-prevpredmap/blob/main/mmdetection3d/tools/create_data.py"
    click RawData "https://github.com/pnnnnnnn/uni-prevpredmap/tree/main/tools/data_converter/"
    click RawData "https://github.com/pnnnnnnn/uni-prevpredmap/blob/main/tools/uniprevpredmap/generate_av2_global_map.py"
    click RawData "https://github.com/pnnnnnnn/uni-prevpredmap/blob/main/tools/uniprevpredmap/generate_nusc_global_map.py"
    click MMD3DDatasets "https://github.com/pnnnnnnn/uni-prevpredmap/tree/main/mmdetection3d/mmdet3d/datasets/"
    click MMD3DPipelines "https://github.com/pnnnnnnn/uni-prevpredmap/tree/main/mmdetection3d/mmdet3d/datasets/pipelines/"
    click PluginDatasets "https://github.com/pnnnnnnn/uni-prevpredmap/blob/main/projects/mmdet3d_plugin/datasets/av2_map_dataset.py"
    click PluginDatasets "https://github.com/pnnnnnnn/uni-prevpredmap/blob/main/projects/mmdet3d_plugin/datasets/av2_offlinemap_dataset.py"
    click PluginDatasets "https://github.com/pnnnnnnn/uni-prevpredmap/blob/main/projects/mmdet3d_plugin/datasets/av2_offlinemap_dataset_v2.py"
    click Builder "https://github.com/pnnnnnnn/uni-prevpredmap/blob/main/mmdetection3d/mmdet3d/models/builder.py"
    click Backbones "https://github.com/pnnnnnnn/uni-prevpredmap/tree/main/mmdetection3d/mmdet3d/models/backbones/"
    click MiddleEnc "https://github.com/pnnnnnnn/uni-prevpredmap/tree/main/mmdetection3d/mmdet3d/models/middle_encoders/"
    click DenseHeads "https://github.com/pnnnnnnn/uni-prevpredmap/tree/main/mmdetection3d/mmdet3d/models/dense_heads/"
    click VoxelEnc "https://github.com/pnnnnnnn/uni-prevpredmap/tree/main/mmdetection3d/mmdet3d/models/voxel_encoders/"
    click Ops "https://github.com/pnnnnnnn/uni-prevpredmap/tree/main/mmdetection3d/mmdet3d/ops/"
    click TrainAPI "https://github.com/pnnnnnnn/uni-prevpredmap/blob/main/mmdetection3d/mmdet3d/apis/train.py"
    click TestAPI "https://github.com/pnnnnnnn/uni-prevpredmap/blob/main/mmdetection3d/mmdet3d/apis/test.py"
    click InferAPI "https://github.com/pnnnnnnn/uni-prevpredmap/blob/main/mmdetection3d/mmdet3d/apis/inference.py"
    click GlobalMapTile "https://github.com/pnnnnnnn/uni-prevpredmap/blob/main/projects/mmdet3d_plugin/hrmap/global_map_vec_tile.py"
    click GlobalMap "https://github.com/pnnnnnnn/uni-prevpredmap/blob/main/projects/mmdet3d_plugin/hrmap/global_map.py"
    click GlobalMapVec "https://github.com/pnnnnnnn/uni-prevpredmap/blob/main/projects/mmdet3d_plugin/hrmap/global_map_vec.py"
    click HooksEpoch "https://github.com/pnnnnnnn/uni-prevpredmap/blob/main/projects/mmdet3d_plugin/hrmap/set_epoch_info_hook.py"
    click HooksIter "https://github.com/pnnnnnnn/uni-prevpredmap/blob/main/projects/mmdet3d_plugin/hrmap/set_iter_info_hook.py"
    click MapTRDet "https://github.com/pnnnnnnn/uni-prevpredmap/blob/main/projects/mmdet3d_plugin/maptr/detectors/maptr.py"
    click MapTRV2Det "https://github.com/pnnnnnnn/uni-prevpredmap/blob/main/projects/mmdet3d_plugin/maptr/detectors/maptrv2.py"
    click MapTRHead "https://github.com/pnnnnnnn/uni-prevpredmap/blob/main/projects/mmdet3d_plugin/maptr/dense_heads/maptr_head.py"
    click MapTRV2Head "https://github.com/pnnnnnnn/uni-prevpredmap/blob/main/projects/mmdet3d_plugin/maptr/dense_heads/maptrv2_head.py"
    click Encoder "https://github.com/pnnnnnnn/uni-prevpredmap/blob/main/projects/mmdet3d_plugin/maptr/modules/encoder.py"
    click Decoder "https://github.com/pnnnnnnn/uni-prevpredmap/blob/main/projects/mmdet3d_plugin/maptr/modules/decoder.py"
    click BaseConfigs "https://github.com/pnnnnnnn/uni-prevpredmap/tree/main/mmdetection3d/configs/_base_/"
    click ProjectConfigs "https://github.com/pnnnnnnn/uni-prevpredmap/tree/main/projects/configs/uniprevpredmap/"
    click ProjectConfigs "https://github.com/pnnnnnnn/uni-prevpredmap/tree/main/projects/configs/_base_/models/"
    click ToolsTrain "https://github.com/pnnnnnnn/uni-prevpredmap/blob/main/tools/train.py"
    click DistTrain "https://github.com/pnnnnnnn/uni-prevpredmap/blob/main/tools/dist_train.sh"
    click SlurmTrain "https://github.com/pnnnnnnn/uni-prevpredmap/blob/main/tools/slurm_train.sh"
    click MMD3DTrain "https://github.com/pnnnnnnn/uni-prevpredmap/blob/main/mmdetection3d/tools/train.py"
    click MMD3DDist "https://github.com/pnnnnnnn/uni-prevpredmap/blob/main/mmdetection3d/tools/dist_train.sh"
    click MonoDemo "https://github.com/pnnnnnnn/uni-prevpredmap/blob/main/mmdetection3d/demo/mono_det_demo.py"
    click PCDDemo "https://github.com/pnnnnnnn/uni-prevpredmap/blob/main/mmdetection3d/demo/pcd_demo.py"
    click Visualize "https://github.com/pnnnnnnn/uni-prevpredmap/blob/main/tools/misc/visualize_results.py"
    click MapTRVis "https://github.com/pnnnnnnn/uni-prevpredmap/blob/main/tools/maptr/vis_pred.py"
    click MapTRV2Vis "https://github.com/pnnnnnnn/uni-prevpredmap/blob/main/tools/maptrv2/av2_vis_pred.py"

    %% Styles
    classDef green fill:#e0f7e9,stroke:#2f8f4e,color:#2f8f4e
    classDef blue fill:#e0e7f7,stroke:#2f348f,color:#2f348f
    classDef orange fill:#f7e4d0,stroke:#f38f2f,color:#f38f2f
    classDef purple fill:#f0e0f7,stroke:#8f2f8f,color:#8f2f8f
    classDef grey fill:#f7f7f7,stroke:#888888,color:#555555
```
