# yujeong-star/rl_3dod architecture

> Architecture diagram of the GitHub repository yujeong-star/rl_3dod, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/yujeong-star/rl_3dod
- Repository: https://github.com/yujeong-star/rl_3dod

## Overview

##### Project type and purpose
- This is a research-grade 3D object‐detection codebase (“RL_3DOD”) integrating LiDAR and 4D radar data.
- It provides end‐to‐end data ingestion, preprocessing, model definition (multiple backbones, heads), training stages (image classification pretrain + detection), inference, and evaluation.

##### File structure
- Top‐level:
- README.md & setup.py – project description and install entry point
- configs/ – YAML and Python config templates (general, UI, radar fusion)
- datasets/ – dataset loader for K-Radar detection
- pipelines/ – high‐level detection pipeline script
- models/ – modular network definitions:
– backbone_2d (image or radar BEV), backbone_3d (sparse conv & fusion), heads, preprocessors, ROI heads, skeletons
– img_cls/ for two‐stage pretraining (cls_train.py, cls_test.py)
- resources/ – raw radar/LiDAR data mats & train/test splits
- main_train_0.py & main_cond_0.py – entry points for detection training and conditional testing
- Notice modular pattern: each concern (data, model, training, evaluation) is in its own directory. Utilities are further subdivided by functionality.

##### README for additional insights
- Two‐stage training: Stage1 image classification pretrain, Stage2 detection training
- Single‐script inference (main_cond_0.py)
- Relies on PyTorch, spconv, Open3D, OpenCV, custom CUDA Ops (Rotated_IoU)
- Based on K-Radar dataset

##### Components
a. Main components:
1. Data Sources:
- LiDAR point clouds (resources/*.mat)
- 4D Radar data (resources/*.mat)
- Train/Test splits (resources/split/)
2. Data Loader & Pre‐processor:
- datasets/kradar_detection_v1_0.py
- models/pre_processor/rdr_sparse_processor*.py
3. Configuration Manager:
- configs/*.yml, configs/*.py
4. Model Zoo:
- Backbone2D, Backbone3D (rl_3df.py), Fusion skeletons
- ROI & detection heads (rdr_spcube_head.py)
- Classification branch (img_cls/cls_model.py)
5. Training Pipelines:
- Stage1: img_cls/cls_train.py → produce pretrained weights
- Stage2: main_train_0.py & pipelines/pipeline_detection_v1_0.py
6. Inference & Evaluation:
- main_cond_0.py
- utils/kitti_eval/ for metrics
7. Utilities (shared):
- utils/Rotated_IoU CUDA ops
- utils/box_*, util_geometry, util_pipeline, util_point_cloud, UI vis
b. Relationships & data flows:
- Configs feed Data Loader & Model definitions
- Data Loader + Pre‐processor → Batch Tensors → Model
- Pretrained weights from Stage1 injected into Detection model in Stage2
- During inference, model outputs → post‐processing (NMS, RotatedIoU) → Evaluation
c. Architectural patterns and design principles:
- Modularity: each layer of the ML pipeline is its own package
- Two‐stage training flow (pretrain → fine‐tune)
- Separation of concerns: data, model, training, evaluation, utilities
d. Key technologies, frameworks, libraries:
- Python 3.8, PyTorch 1.10.1, spconv-cu111
- Open3D, OpenCV, numba
- Custom CUDA (rotate IoU)
- KittiEval scripts for metrics

## Diagram (Mermaid)

```mermaid
flowchart TD
    classDef data fill:#aed6f1,stroke:#2980b9,color:#1b2631
    classDef model fill:#abebc6,stroke:#27ae60,color:#1b2631
    classDef pipeline fill:#f9e79f,stroke:#d68910,color:#1b2631
    classDef util fill:#d5dbdb,stroke:#7f8c8d,color:#1b2631
    classDef config fill:#e8daef,stroke:#8e44ad,color:#1b2631

    subgraph "Data Sources"
        LiDAR["LiDAR Point Clouds\n(arr_doppler.mat)"]:::data
        Radar["4D Radar Data\n(info_arr.mat)"]:::data
        Splits["Train/Test Splits\n(train.txt/test.txt)"]:::data
    end

    subgraph "Configuration Manager"
        CFG_YML["YAML Config\n(cfg_rl_3df_gate.yml)"]:::config
        CFG_GEN["General Config Script\n(config_general.py)"]:::config
        CFG_UI["UI Config Script\n(config_ui.py)"]:::config
    end

    subgraph "Data Loader & Pre-processor"
        Loader["Dataset Loader\n(kradar_detection_v1_0.py)"]:::data
        Pre1["Sparse Preprocessor v1\n(rdr_sparse_processor.py)"]:::data
        Pre2["Sparse Preprocessor v2\n(rdr_sparse_processor2.py)"]:::data
    end

    subgraph "Model Zoo"
        subgraph "Backbones & Fusion"
            BB2D["Backbone2D\n(__init__.py)"]:::model
            BB3D["Backbone3D & Fusion\n(rl_3df.py)"]:::model
            SKELETON["Fusion Skeleton\n(rl_3df_gate.py)"]:::model
        end
        HEAD["Detection Head\n(rdr_spcube_head.py)"]:::model
        CLS_MODEL["Classification Model\n(cls_model.py)"]:::model
    end

    subgraph "Training Pipelines"
        Stage1["Stage1: ImgCls Pretrain\n(cls_train.py)"]:::pipeline
        Stage1Test["Stage1 Test\n(cls_test.py)"]:::pipeline
        Stage2["Stage2: Detection Train\n(main_train_0.py)"]:::pipeline
        PipelineDet["Detection Pipeline\n(pipeline_detection_v1_0.py)"]:::pipeline
    end

    subgraph "Inference & Evaluation"
        Inference["Conditional Inference\n(main_cond_0.py)"]:::pipeline
        KITTI["KITTI Eval Utils\n(utils/kitti_eval/)"]:::util
    end

    subgraph "Utilities"
        RotIoU["Rotated IoU CUDA Ops\n(utils/Rotated_IoU/)"]:::util
        BoxUtils["Box Coding & Geometry\n(box_coder_utils.py,\nbox_utils.py, util_geometry.py)"]:::util
        PipelineU["Pipeline Helpers\n(util_pipeline.py)"]:::util
        PCU["Point Cloud Helpers\n(util_point_cloud.py)"]:::util
        UIU["UI Labeling & Vis\n(util_ui_labeling.py,\nutil_ui_vis.py)"]:::util
        CFAR["CFAR & Dataset Utils\n(util_cfar.py,\nutil_dataset.py)"]:::util
        Common["Common & Config Utils\n(common_utils.py,\nutil_config.py)"]:::util
        Loss["Loss Utilities\n(loss_utils.py)"]:::util
    end

    %% Data flow
    LiDAR -->|loads| Loader
    Radar -->|loads| Loader
    Splits -->|provides| Loader
    CFG_YML --> Loader
    CFG_GEN --> Loader
    CFG_UI --> Loader

    Loader -->|raw batch| Pre1
    Loader -->|raw batch| Pre2
    Pre1 -->|processed batch| BB2D
    Pre1 -->|processed batch| BB3D
    Pre2 -->|processed batch| BB2D
    Pre2 -->|processed batch| BB3D

    CFG_YML --> BB2D
    CFG_GEN --> BB3D
    CFG_GEN --> SKELETON
    CFG_GEN --> HEAD
    CFG_GEN --> CLS_MODEL

    Stage1 -->|uses| CFG_YML
    Stage1Test -->|uses| CFG_YML
    Stage1 -->|trains| CLS_MODEL
    Stage1 -->|outputs weights| BB2D

    Stage2 -->|uses| CFG_YML
    PipelineDet -->|orchestrates| BB2D
    PipelineDet -->|orchestrates| BB3D
    PipelineDet -->|orchestrates| SKELETON
    PipelineDet -->|orchestrates| HEAD
    Stage2 --> PipelineDet
    BB2D --> Stage2
    CLS_MODEL --> Stage2

    PipelineDet -->|inference| Inference
    Inference -->|post-process| RotIoU
    Inference -->|eval| KITTI

    %% Utilities connections
    PipelineDet --> PipelineU
    Inference --> PipelineU
    HEAD --> BoxUtils
    BB3D --> BoxUtils
    Loader --> PCU
    Loader --> CFAR
    UIU --> Inference
    Common --> CFG_GEN
    Common --> Stage1
    Loss --> Stage1
    Loss --> Stage2

    %% Click events
    click LiDAR "https://github.com/yujeong-star/rl_3dod/blob/main/resources/arr_doppler.mat"
    click Radar "https://github.com/yujeong-star/rl_3dod/blob/main/resources/info_arr.mat"
    click Splits "https://github.com/yujeong-star/rl_3dod/blob/main/resources/split/train.txt"
    click Loader "https://github.com/yujeong-star/rl_3dod/blob/main/datasets/kradar_detection_v1_0.py"
    click Pre1 "https://github.com/yujeong-star/rl_3dod/blob/main/models/pre_processor/rdr_sparse_processor.py"
    click Pre2 "https://github.com/yujeong-star/rl_3dod/blob/main/models/pre_processor/rdr_sparse_processor2.py"
    click CFG_YML "https://github.com/yujeong-star/rl_3dod/blob/main/configs/cfg_rl_3df_gate.yml"
    click CFG_GEN "https://github.com/yujeong-star/rl_3dod/blob/main/configs/config_general.py"
    click CFG_UI "https://github.com/yujeong-star/rl_3dod/blob/main/configs/config_ui.py"
    click BB2D "https://github.com/yujeong-star/rl_3dod/blob/main/models/backbone_2d/__init__.py"
    click BB3D "https://github.com/yujeong-star/rl_3dod/blob/main/models/backbone_3d/rl_3df.py"
    click SKELETON "https://github.com/yujeong-star/rl_3dod/blob/main/models/skeletons/rl_3df_gate.py"
    click HEAD "https://github.com/yujeong-star/rl_3dod/blob/main/models/head/rdr_spcube_head.py"
    click CLS_MODEL "https://github.com/yujeong-star/rl_3dod/blob/main/models/img_cls/cls_model.py"
    click Stage1 "https://github.com/yujeong-star/rl_3dod/blob/main/models/img_cls/cls_train.py"
    click Stage1Test "https://github.com/yujeong-star/rl_3dod/blob/main/models/img_cls/cls_test.py"
    click Stage2 "https://github.com/yujeong-star/rl_3dod/blob/main/main_train_0.py"
    click PipelineDet "https://github.com/yujeong-star/rl_3dod/blob/main/pipelines/pipeline_detection_v1_0.py"
    click Inference "https://github.com/yujeong-star/rl_3dod/blob/main/main_cond_0.py"
    click KITTI "https://github.com/yujeong-star/rl_3dod/tree/main/utils/kitti_eval/"
    click RotIoU "https://github.com/yujeong-star/rl_3dod/tree/main/utils/Rotated_IoU/"
    click BoxUtils "https://github.com/yujeong-star/rl_3dod/blob/main/utils/box_coder_utils.py"
    click PipelineU "https://github.com/yujeong-star/rl_3dod/blob/main/utils/util_pipeline.py"
    click PCU "https://github.com/yujeong-star/rl_3dod/blob/main/utils/util_point_cloud.py"
    click UIU "https://github.com/yujeong-star/rl_3dod/blob/main/utils/util_ui_labeling.py"
    click CFAR "https://github.com/yujeong-star/rl_3dod/blob/main/utils/util_cfar.py"
    click Common "https://github.com/yujeong-star/rl_3dod/blob/main/utils/common_utils.py"
    click Loss "https://github.com/yujeong-star/rl_3dod/blob/main/utils/loss_utils.py"
```
