How richardminsoogo-ml/bible_3_42_pytorch_yolo_3d_yolov4 works
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”).