How kakaxi314/bp-net works
Project Type and Purpose
• This is a research-oriented PyTorch deep learning project (“BP-Net”) for depth completion, implementing the “Bilateral Propagation Network” from a CVPR 2024 paper.
• It provides end-to-end pipelines for training (train.py), testing/inference (test.py), and supports two benchmark datasets (KITTI, NYUv2), plus a custom CUDA extension for performance.
File Structure Analysis
Top-level scripts and modules:
• train.py & test.py: orchestrate training and evaluation using torchrun + Hydra configs
• augs.py, criteria.py, optimizers.py, schedulers.py, utils.py: modular helpers for data augmentation, loss definitions, optimizers, learning-rate schedulers, general utilities
Directories:
• configs/: Hydra configuration hierarchy (data, net, optim, sched, metric, loss)
• datasets/: dataset wrappers for KITTI and NYU (kitti.py, nyu.py)
• datas/: placeholder/.gitignore for raw dataset files
• models/: PyTorch model definitions (BPNet in BPNet.py), plus model utilities
• exts/: C++/CUDA extension source for custom back-prop kernels, with setup.py
• checkpoints/: saved model weights
• environment.yml: conda environment specification
Key Insights from README
• Uses Hydra for configurable experiments: all hyperparameters, data paths, network variants, schedulers, metrics are driven by YAML under configs/.
• Requires building a custom CUDA extension (exts/) for the bilateral propagation operator.
• Data pipeline supports two formats: raw KITTI folder hierarchy, and preprocessed HDF5 for NYUv2.
• Multi-GPU training via torchrun, saving checkpoints for later test/evaluation.
a. Main Components
1. Configuration Manager (Hydra)
2. Data Ingestion & Preprocessing
• Dataset Loader (datasets/kitti.py, datasets/nyu.py)
• Augmentations (augs.py)
3. Model Core
• BPNet architecture (models/BPNet.py)
• Utility modules (models/utils.py)
4. Custom CUDA Extension
• C++/CUDA kernel (exts/bp_cuda_kernel.cu) wrapped via setup.py
5. Training Orchestration
• Training Loop (train.py)
• Loss Computation (criteria.py, configs/loss/*.yaml)
• Optimizer & Scheduler (optimizers.py, schedulers.py, configs/optim/*.yaml, configs/sched/*.yaml)
6. Evaluation & Testing
• Test Harness (test.py)
• Metrics Computation (configs/metric/*.yaml)
7. Checkpoint & Logging
• Checkpoint I/O (checkpoints/)
• Logging to console or external dashboards (not explicit but can be added)
8. External Services
• GPU cluster (torchrun multi-GPU)
• Data storage (local filesystem or network shares for KITTI/NYU)
b. Relationships & Data Flow
• Configuration Manager drives all parameters into each component.
• Data Ingestion → DataLoader → Augmentation → Batch fed into Model Core.
• Forward pass uses custom CUDA extension.
• Model outputs → Loss module → Backward pass → Optimizer updates model.
• Scheduler adjusts learning rate per epoch/step.
• At intervals: checkpoint saved, metrics logged.
• Test script loads checkpoints, runs inference pipeline, computes metrics, and optionally saves predictions.
c. Architectural Patterns & Design Principles
• Modular code organization: separate concerns (data, model, training, config)
• Config-driven experiments via Hydra: promotes reproducibility and fast hyperparameter sweeps
• Extension kernel isolation: performance-critical code in C++/CUDA
• Clear separation of training versus evaluation flows
d. Key Technologies & Frameworks
• Python 3.x, PyTorch
• Hydra for configuration
• CUDA/C++ for custom high-performance operators
• Conda environment for dependency management
• torchrun for distributed multi-GPU training