# richardminsoogo-ml/bible_3_42_pytorch_yolo_3d_yolov4 architecture

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

- Interactive diagram: https://gitdiagram.com/richardminsoogo-ml/bible_3_42_pytorch_yolo_3d_yolov4
- Repository: https://github.com/richardminsoogo-ml/bible_3_42_pytorch_yolo_3d_yolov4

## Overview

##### Project Type and Purpose
- This is a research‐oriented, open‐source ML pipeline implementing 3D object detection (YOLO3D with YoloV4) on LiDAR point clouds (KITTI dataset) in PyTorch.
- It supports data preparation, training, inference (detection), evaluation (mAP), and visualization.

##### File Structure Analysis
- Top‐level scripts:
- train.py, train_old.py – launch training pipelines
- detection.py – run inference on “detect_*” subsets
- eval_mAP.py – compute mAP metrics
- Jupyter notebooks for tutorials and demos
- Directories:
- config/ – model and training configuration (CFG files, train_config.py, kitti_config.py)
- data_process/ – data loaders, augmentation, BEV utilities for KITTI
- dataset/ – local copy of KITTI in structured subfolders (detect_1, detect_2, sampledata, training, testing)
- models/ – conversion from Darknet, YOLO layers, model utility wrappers
- utils/ – helper modules (anchors, IOU, evaluation, Mayavi viewer, misc, torch utilities, etc.)
- checkpoints/ – pre-trained and saved PyTorch weights
- logs/ – TensorBoard or console logs
- asset/ – scripts and images for demo (video→gif, caution image)

##### Key Insights from README
- Model definitions are CFG‐driven (darknet cfg files for v3, v4, tiny variants).
- Pretrained Darknet weights are converted and optionally fine-tuned.
- Data pipeline reads raw .bin, .txt (LiDAR, calibration, labels) → augmentation/BEV → PyTorch DataLoader.
- Training pipeline writes to checkpoints and logs; inference pipeline loads checkpoints and runs detection.
- Evaluation uses custom mAP script with 0.5 IoU threshold.

##### Main Components & Interactions
a. Dataset Storage (KITTI folder)
→ Data Loader & Preprocessor (data_process/kitti_*.py)
→ Model Definition (models/darknet2pytorch.py + yolo_layer.py)
→ Training Module (train.py + train_config.py)
→ Checkpoint Manager (save/load .pth in checkpoints/)
→ Inference Module (detection.py)
→ Evaluation Module (eval_mAP.py, utils/evaluation_utils.py)
→ Visualization (utils/mayavi_viewer.py, asset GIFs, logs/)
b. Config Layer
- All scripts read model CFGs (config/cfg/*.cfg), train parameters (train_config.py), and dataset paths (kitti_config.py).
c. Utilities

##### Architectural Patterns & Principles
- Pipeline Architecture: clear linear flow from raw data → preprocessing → model → postprocess → evaluation.
- Config‐first Design: model hyperparameters and dataset paths are externalized in config files.
- Modular Separation of Concerns:
- Data handling (data_process/)
- Model logic (models/)
- Utilities (utils/)
- Scripts orchestrate high‐level workflows.

##### Technologies & Frameworks
- Python 3, PyTorch, NumPy, OpenCV, mayavi for 3D visualization, Jupyter notebooks.
- Darknet weight compatibility via custom conversion in models/darknet2pytorch.py.
- KITTI dataset as external service (“external storage”).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Resources
    KITTI["KITTI Dataset"]:::external
    DarknetWeights["Pretrained Darknet Weights"]:::external

    %% Storage
    Dataset[(Dataset Storage)]:::storage
    Checkpoints[(Checkpoints)]:::storage
    Logs[(Logs)]:::storage

    %% Configuration Layer
    subgraph "Configuration Layer"
        YOLOv3Cfg[/yolo3d_yolov3.cfg/]:::config
        YOLOv3TinyCfg[/yolo3d_yolov3_tiny.cfg/]:::config
        YOLOv4Cfg[/yolo3d_yolov4.cfg/]:::config
        YOLOv4TinyCfg[/yolo3d_yolov4_tiny.cfg/]:::config
        KittiConfig[/kitti_config.py/]:::config
        TrainConfig[/train_config.py/]:::config
    end

    %% Compute Modules
    DataPreprocessor["Data Loader & Preprocessor"]:::compute
    ModelDef["Model Definition & Conversion"]:::compute
    Training["Training Module"]:::compute
    Inference["Inference Module"]:::compute
    Eval["Evaluation Module"]:::compute
    Viz["Visualization"]:::compute

    %% Data Flow - Training Path
    KITTI -->|"raw .bin, .txt"| Dataset
    Dataset -->|".bin→BEV image"| DataPreprocessor
    YOLOv3Cfg --> DataPreprocessor
    YOLOv3TinyCfg --> DataPreprocessor
    YOLOv4Cfg --> DataPreprocessor
    YOLOv4TinyCfg --> DataPreprocessor
    KittiConfig --> DataPreprocessor
    DataPreprocessor -->|"tensor batches"| Training
    ModelDef --> Training
    TrainConfig --> Training
    DarknetWeights --> ModelDef
    Training -->|"save .pth"| Checkpoints
    Training -->|"logs"| Logs

    %% Data Flow - Inference & Evaluation
    Checkpoints -->|".pth load"| Inference
    ModelDef --> Inference
    Inference -->|"detection boxes"| Eval
    Eval -->|"mAP metrics"| Logs
    Eval --> Viz
    Inference --> Viz

    %% Config feeds Model
    YOLOv3Cfg --> ModelDef
    YOLOv3TinyCfg --> ModelDef
    YOLOv4Cfg --> ModelDef
    YOLOv4TinyCfg --> ModelDef
    TrainConfig --> ModelDef

    %% Click Events
    click KITTI "https://github.com/richardminsoogo-ml/bible_3_42_pytorch_yolo_3d_yolov4/tree/main/dataset/kitti"
    click DataPreprocessor "https://github.com/richardminsoogo-ml/bible_3_42_pytorch_yolo_3d_yolov4/blob/main/data_process/kitti_dataloader.py"
    click DataPreprocessor "https://github.com/richardminsoogo-ml/bible_3_42_pytorch_yolo_3d_yolov4/blob/main/data_process/kitti_dataset.py"
    click DataPreprocessor "https://github.com/richardminsoogo-ml/bible_3_42_pytorch_yolo_3d_yolov4/blob/main/data_process/kitti_aug_utils.py"
    click DataPreprocessor "https://github.com/richardminsoogo-ml/bible_3_42_pytorch_yolo_3d_yolov4/blob/main/data_process/kitti_bev_utils.py"
    click DataPreprocessor "https://github.com/richardminsoogo-ml/bible_3_42_pytorch_yolo_3d_yolov4/blob/main/data_process/kitti_utils.py"
    click ModelDef "https://github.com/richardminsoogo-ml/bible_3_42_pytorch_yolo_3d_yolov4/blob/main/models/darknet2pytorch.py"
    click ModelDef "https://github.com/richardminsoogo-ml/bible_3_42_pytorch_yolo_3d_yolov4/blob/main/models/yolo_layer.py"
    click ModelDef "https://github.com/richardminsoogo-ml/bible_3_42_pytorch_yolo_3d_yolov4/blob/main/models/darknet_utils.py"
    click ModelDef "https://github.com/richardminsoogo-ml/bible_3_42_pytorch_yolo_3d_yolov4/blob/main/models/model_utils.py"
    click Training "https://github.com/richardminsoogo-ml/bible_3_42_pytorch_yolo_3d_yolov4/blob/main/train.py"
    click Training "https://github.com/richardminsoogo-ml/bible_3_42_pytorch_yolo_3d_yolov4/blob/main/train_old.py"
    click TrainConfig "https://github.com/richardminsoogo-ml/bible_3_42_pytorch_yolo_3d_yolov4/blob/main/config/train_config.py"
    click Inference "https://github.com/richardminsoogo-ml/bible_3_42_pytorch_yolo_3d_yolov4/blob/main/detection.py"
    click Eval "https://github.com/richardminsoogo-ml/bible_3_42_pytorch_yolo_3d_yolov4/blob/main/eval_mAP.py"
    click Eval "https://github.com/richardminsoogo-ml/bible_3_42_pytorch_yolo_3d_yolov4/blob/main/utils/evaluation_utils.py"
    click Checkpoints "https://github.com/richardminsoogo-ml/bible_3_42_pytorch_yolo_3d_yolov4/tree/main/checkpoints/"
    click YOLOv3Cfg "https://github.com/richardminsoogo-ml/bible_3_42_pytorch_yolo_3d_yolov4/blob/main/config/cfg/yolo3d_yolov3.cfg"
    click YOLOv3TinyCfg "https://github.com/richardminsoogo-ml/bible_3_42_pytorch_yolo_3d_yolov4/blob/main/config/cfg/yolo3d_yolov3_tiny.cfg"
    click YOLOv4Cfg "https://github.com/richardminsoogo-ml/bible_3_42_pytorch_yolo_3d_yolov4/blob/main/config/cfg/yolo3d_yolov4.cfg"
    click YOLOv4TinyCfg "https://github.com/richardminsoogo-ml/bible_3_42_pytorch_yolo_3d_yolov4/blob/main/config/cfg/yolo3d_yolov4_tiny.cfg"
    click KittiConfig "https://github.com/richardminsoogo-ml/bible_3_42_pytorch_yolo_3d_yolov4/blob/main/config/kitti_config.py"
    click Viz "https://github.com/richardminsoogo-ml/bible_3_42_pytorch_yolo_3d_yolov4/blob/main/utils/mayavi_viewer.py"
    click Viz "https://github.com/richardminsoogo-ml/bible_3_42_pytorch_yolo_3d_yolov4/blob/main/asset/convert_video_to_gif.py"
    click Logs "https://github.com/richardminsoogo-ml/bible_3_42_pytorch_yolo_3d_yolov4/tree/main/logs/"

    %% Styles
    classDef data fill:#E3F2FD,stroke:#2196F3,color:#0D47A1
    classDef compute fill:#E8F5E9,stroke:#4CAF50,color:#1B5E20
    classDef storage fill:#FFF3E0,stroke:#FB8C00,color:#E65100
    classDef external fill:#ECEFF1,stroke:#90A4AE,color:#455A64
    classDef config fill:#FAFAFA,stroke:#FDD835,color:#F57F17
```
