# maudzung/yolo3d-yolov4-pytorch architecture

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

- Interactive diagram: https://gitdiagram.com/maudzung/yolo3d-yolov4-pytorch
- Repository: https://github.com/maudzung/yolo3d-yolov4-pytorch

## Overview

##### Project Type and Purpose
- This is a deep-learning application for real-time 3D object detection on LiDAR point clouds, based on the YOLO3D (ECCV 2018) algorithm enhanced with YOLOv4 features.

##### File-Structure Overview
- dataset/
- Stores KITTI data (point clouds, labels, calibration, splits)
- docs/
- src/
- config/ – all hyperparameter and model‐CFG definitions (YOLOv4 cfg, train and dataset configs)
- data_process/ – conversion of raw LiDAR to BEV, data augmentation, train/val split, DataLoader
- models/ – Darknet→PyTorch conversion, model‐building utilities, YOLO layers
- utils/ – logging, evaluation-metric functions (IoU, GIoU), visualization, distributed training helpers
- train.py, test.py, evaluate.py (+ .sh wrappers) – entrypoints for training, inference, evaluation
- requirements.txt, README.md, LICENSE, .gitignore

1. Data Storage
- Raw KITTI Velodyne, labels, calib, images
- Train/val/test split files
2. Data Processing Pipeline
- BEV Encoder (height, intensity, density channels)
- Augmentations (Mosaic, Cutout, random scale/rotation, flip)
- Dataset & DataLoader (PyTorch)
3. Model Definition
- Backbone: CSPDarknet with Mish activations, SPP, PAN (YOLOv4)
4. Training Engine
- Loss calculation (MSE or GIoU), optimizer (SGD/Adam), scheduler
- Distributed DataParallel (NCCL)
- Checkpoint save/load
- Tensorboard logging
5. Inference & Evaluation
- Pretrained checkpoint loader
- Forward pass, NMS, thresholding
- Metric computation (AP, IoU)
6. Visualization
- Tensorboard dashboards

1. Data Storage → Data Processing
2. Data Processing → DataLoader → Training Engine
3. Training Engine ↔ Model Definition
4. Training Engine → Checkpoints
5. Checkpoints → Inference/Evaluation
6. Inference/Evaluation → Visualization & Metrics
7. Training Engine → Tensorboard

C. Architectural Patterns & Principles
- Modular separation: config / data_process / models / utils
- Config-driven: `.cfg` files and Python config modules decouple hyperparameters
- Reusable utilities: common IoU, logging, visualization functions
- DDP pattern for multi-GPU/multi-node training

D. Key Technologies & Frameworks
- Python 3.6+, PyTorch 1.5 (DDP via NCCL)
- NumPy, OpenCV (BEV processing), Mayavi, Shapely (visualization)
- Tensorboard for logging
- Shell scripts (`train.sh`, `test.sh`) for reproducibility

##### Detail Level
- Module (.cfg files, augmentations, YOLO layers, loss functions).
- How configurations branch into both data preprocessing and model instantiation.
- Don’t omit auxiliary utils (logger, misc, torch_utils) – they underpin the engine.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Data Layer"
        DS[(Data Storage)]:::data
    end

    subgraph "Preprocessing"
        BEV["BEV Encoder"]:::data
        AUG["Augmentations"]:::data
        SPLIT["Train/Val Split"]:::data
        DS2["Dataset"]:::data
        DL["DataLoader"]:::data
        UTIL_DP["Raw Data Utils"]:::data
    end

    subgraph "Config"
        CFGNET["Network CFG"]:::model
        CFGDATA["Dataset Config"]:::model
        CFGTRAIN["Train Config"]:::model
    end

    subgraph "Model"
        DC2P["Darknet2PyTorch"]:::model
        UTIL_M["Darknet Utils"]:::model
        BUILDER["Model Utils"]:::model
        YOLOL["YOLO Layer"]:::model
    end

    subgraph "Training Engine"
        TSScript["train.py / train.sh"]:::script
        TU["Train Utils"]:::train
        TUTIL["Torch DDP Utils"]:::train
        LOG["Logger"]:::train
        MISC["Misc Utils"]:::train
        CK[(Checkpoints)]:::train
    end

    subgraph "Inference/Evaluation"
        TESTS["test.py / test.sh"]:::script
        EVAL["evaluate.py"]:::train
        IOU1["IoU Rotated Boxes"]:::train
        IOU2["Cal Intersection"]:::train
        EVALUTIL["Eval Utils"]:::train
        CK2[(Pretrained Checkpoints)]:::train
    end

    subgraph "Visualization"
        VIS["Visualization Utils"]:::viz
        FA["Find Anchors"]:::viz
    end

    DS --> BEV
    BEV --> AUG
    AUG --> SPLIT
    SPLIT --> DS2
    DS2 --> DL

    CFGDATA --> DS2
    CFGNET --> DC2P
    CFGNET --> UTIL_M
    CFGNET --> BUILDER
    CFGTRAIN --> TSScript

    DL --> TSScript
    TSScript --> DC2P
    TSScript --> BUILDER
    TSScript --> YOLOL
    TSScript --> TU
    TSScript --> TUTIL
    TSScript --> LOG
    TSScript --> MISC
    TSScript --> CK

    CK --> TESTS
    TESTS --> DC2P
    TESTS --> YOLOL
    TESTS --> EVAL
    TESTS --> CK2

    EVAL --> IOU1
    EVAL --> IOU2
    EVAL --> EVALUTIL
    TESTS --> VIS
    TESTS --> FA

    classDef data fill:#ADD8E6,stroke:#000;
    classDef model fill:#90EE90,stroke:#000;
    classDef train fill:#FFA500,stroke:#000;
    classDef viz fill:#DDA0DD,stroke:#000;
    classDef script fill:#FFA500,stroke:#000,shape:parallelogram;

    click DS "https://github.com/maudzung/yolo3d-yolov4-pytorch/tree/master/dataset/kitti"
    click BEV "https://github.com/maudzung/yolo3d-yolov4-pytorch/blob/master/src/data_process/kitti_bev_utils.py"
    click AUG "https://github.com/maudzung/yolo3d-yolov4-pytorch/blob/master/src/data_process/transformation.py"
    click SPLIT "https://github.com/maudzung/yolo3d-yolov4-pytorch/blob/master/src/data_process/train_val_split.py"
    click DS2 "https://github.com/maudzung/yolo3d-yolov4-pytorch/blob/master/src/data_process/kitti_dataset.py"
    click DL "https://github.com/maudzung/yolo3d-yolov4-pytorch/blob/master/src/data_process/kitti_dataloader.py"
    click UTIL_DP "https://github.com/maudzung/yolo3d-yolov4-pytorch/blob/master/src/data_process/kitti_data_utils.py"
    click CFGNET "https://github.com/maudzung/yolo3d-yolov4-pytorch/blob/master/src/config/cfg/yolo3d_yolov4.cfg"
    click CFGDATA "https://github.com/maudzung/yolo3d-yolov4-pytorch/blob/master/src/config/kitti_config.py"
    click CFGTRAIN "https://github.com/maudzung/yolo3d-yolov4-pytorch/blob/master/src/config/train_config.py"
    click DC2P "https://github.com/maudzung/yolo3d-yolov4-pytorch/blob/master/src/models/darknet2pytorch.py"
    click UTIL_M "https://github.com/maudzung/yolo3d-yolov4-pytorch/blob/master/src/models/darknet_utils.py"
    click BUILDER "https://github.com/maudzung/yolo3d-yolov4-pytorch/blob/master/src/models/model_utils.py"
    click YOLOL "https://github.com/maudzung/yolo3d-yolov4-pytorch/blob/master/src/models/yolo_layer.py"
    click TSScript "https://github.com/maudzung/yolo3d-yolov4-pytorch/blob/master/src/train.py"
    click TU "https://github.com/maudzung/yolo3d-yolov4-pytorch/blob/master/src/utils/train_utils.py"
    click TUTIL "https://github.com/maudzung/yolo3d-yolov4-pytorch/blob/master/src/utils/torch_utils.py"
    click LOG "https://github.com/maudzung/yolo3d-yolov4-pytorch/blob/master/src/utils/logger.py"
    click MISC "https://github.com/maudzung/yolo3d-yolov4-pytorch/blob/master/src/utils/misc.py"
    click TESTS "https://github.com/maudzung/yolo3d-yolov4-pytorch/blob/master/src/test.py"
    click EVAL "https://github.com/maudzung/yolo3d-yolov4-pytorch/blob/master/src/evaluate.py"
    click IOU1 "https://github.com/maudzung/yolo3d-yolov4-pytorch/blob/master/src/utils/iou_rotated_boxes_utils.py"
    click IOU2 "https://github.com/maudzung/yolo3d-yolov4-pytorch/blob/master/src/utils/cal_intersection_rotated_boxes.py"
    click EVALUTIL "https://github.com/maudzung/yolo3d-yolov4-pytorch/blob/master/src/utils/evaluation_utils.py"
    click VIS "https://github.com/maudzung/yolo3d-yolov4-pytorch/blob/master/src/utils/visualization_utils.py"
    click FA "https://github.com/maudzung/yolo3d-yolov4-pytorch/blob/master/src/utils/find_anchors.py"
```
