# kakaxi314/bp-net architecture

> Architecture diagram of the GitHub repository kakaxi314/bp-net, 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/kakaxi314/bp-net
- Repository: https://github.com/kakaxi314/bp-net

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Configuration Layer
    subgraph "Configuration Manager"
        CFG["Hydra Configs"]:::config
    end

    %% Data Layer
    subgraph "Data Ingestion & Preprocessing"
        DS_RAW["Raw Data (KITTI, NYUv2)"]:::data
        KITTILOADER["KITTI Loader"]:::python
        NYULOADER["NYUv2 Loader"]:::python
        AUG["Augmentations"]:::python
    end

    %% Model Core
    subgraph "Model Core"
        BPNET["BPNet Architecture"]:::python
        MUTIL["Model Utilities"]:::python
    end

    %% CUDA Extension
    subgraph "Custom CUDA Extension"
        KERNEL["bp_cuda_kernel.cu"]:::cuda
        WRAPPER["bp_cuda.cpp / bp_cuda.h"]:::cuda
        SETUP["setup.py"]:::cuda
    end

    %% Training Orchestration
    subgraph "Training Orchestration"
        TRAIN["train.py"]:::python
        LOSS["Loss Computation"]:::python
        OPT["Optimizers"]:::python
        SCHED["Schedulers"]:::python
    end

    %% Evaluation Orchestration
    subgraph "Evaluation & Testing"
        TEST["test.py"]:::python
        METRICS["Metrics Computation"]:::python
    end

    %% Checkpoint & Logging
    CKPT["Checkpoint Storage"]:::storage

    %% Environment
    ENV["environment.yml"]:::config

    %% Data Flow
    DS_RAW --> KITTILOADER
    DS_RAW --> NYULOADER
    KITTILOADER --> AUG
    NYULOADER --> AUG
    AUG --> BPNET

    %% Model to CUDA
    BPNET -->|forward| KERNEL
    KERNEL -->|backward| BPNET
    BPNET --> MUTIL

    %% Config links
    CFG --> DS_RAW
    CFG --> KITTILOADER
    CFG --> NYULOADER
    CFG --> AUG
    CFG --> BPNET
    CFG --> LOSS
    CFG --> OPT
    CFG --> SCHED
    CFG --> METRICS

    %% Training flow
    TRAIN --> KITTILOADER
    TRAIN --> AUG
    TRAIN --> BPNET
    TRAIN --> LOSS
    TRAIN --> OPT
    TRAIN --> SCHED
    TRAIN --> CKPT

    %% Evaluation flow
    TEST --> KITTILOADER
    TEST --> AUG
    TEST --> BPNET
    TEST --> METRICS
    TEST --> CKPT

    %% Environment link
    ENV --> TRAIN
    ENV --> TEST

    %% Click Events
    click CFG "https://github.com/kakaxi314/bp-net/tree/main/configs/"
    click KITTILOADER "https://github.com/kakaxi314/bp-net/blob/main/datasets/kitti.py"
    click NYULOADER "https://github.com/kakaxi314/bp-net/blob/main/datasets/nyu.py"
    click AUG "https://github.com/kakaxi314/bp-net/blob/main/augs.py"
    click BPNET "https://github.com/kakaxi314/bp-net/blob/main/models/BPNet.py"
    click MUTIL "https://github.com/kakaxi314/bp-net/blob/main/models/utils.py"
    click KERNEL "https://github.com/kakaxi314/bp-net/blob/main/exts/bp_cuda_kernel.cu"
    click WRAPPER "https://github.com/kakaxi314/bp-net/blob/main/exts/bp_cuda.cpp"
    click SETUP "https://github.com/kakaxi314/bp-net/blob/main/exts/setup.py"
    click TRAIN "https://github.com/kakaxi314/bp-net/blob/main/train.py"
    click LOSS "https://github.com/kakaxi314/bp-net/blob/main/criteria.py"
    click OPT "https://github.com/kakaxi314/bp-net/blob/main/optimizers.py"
    click SCHED "https://github.com/kakaxi314/bp-net/blob/main/schedulers.py"
    click TEST "https://github.com/kakaxi314/bp-net/blob/main/test.py"
    click METRICS "https://github.com/kakaxi314/bp-net/blob/main/configs/metric/MetricALL.yaml"
    click CKPT "https://github.com/kakaxi314/bp-net/tree/main/checkpoints/"
    click ENV "https://github.com/kakaxi314/bp-net/blob/main/environment.yml"

    %% Styles
    classDef config fill:#e0f7fa,stroke:#0288d1,color:#000;
    classDef data fill:#c8e6c9,stroke:#2e7d32,color:#000;
    classDef python fill:#bbdefb,stroke:#1565c0,color:#000;
    classDef cuda fill:#ffe0b2,stroke:#ef6c00,color:#000;
    classDef storage fill:#d7ccc8,stroke:#5d4037,color:#000;
```
