# rsenatorov/ridev1 architecture

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

- Interactive diagram: https://gitdiagram.com/rsenatorov/ridev1
- Repository: https://github.com/rsenatorov/ridev1

## Overview

##### Project Type and Purpose
- This is a research-grade deep-learning framework for single-image depth estimation.
- It comprises a data pipeline (loading, augmentation), a two-stage neural network (ResNeXt encoder + custom RIDE decoder), training infrastructure (losses, optimizer, scheduler, logging), and multiple inference/visualization tools.

##### File Structure
Top-level components:
- dataset/         ← contains test set (used by data loader)
- logs/            ← training metrics and ASPP feature maps
- src/             ← all Python source: data loader, model definition, training & inference scripts
- src/network/     ← core model code (encoder, decoder, building blocks, loss)
- extract_aspp_feature_maps.py ← feature-map visualization utility
- train.py         ← orchestrates training
- inference_example.py, inference_webcam.py ← offline and real-time inference

##### README for Architectural Insights
- Encoder: ResNeXt-101, pretrained, extracts multi-scale features.
- Decoder: combines upsampling, ASPP+strip-pooling, hybrid skip, LPG, auxiliary refinement.
- Loss: composite L1 + SSIM with learnable weights.
- Data Pipeline: RIDEDataset handles loading, resizing/cropping, augmentations, normalization.
- Inference & Visualization modules hook into model to produce depth maps and ASPP feature images.

##### Main Components & Their Relationships
A. Data Layer
– RIDEDataset (dataset.py)
– Preprocessing & Augmentations
B. Model Layer
– Encoder (ResNeXt-101)
– Decoder (RIDE)
- ASPPModule
- UpsampleConv
- HybridSkipBlock
- EdgeAttentionBlock
- LPG
- AuxRefinementBlock
– Loss Function (CompositeLoss)
C. Training Pipeline
– train.py
– Optimizer & Scheduler
– Logging & Checkpoints → logs/ & checkpoints/
D. Inference Pipeline
– inference_example.py (batch)
– inference_webcam.py (real-time)
– Post-processing & Visualization
E. Feature Visualization
– extract_aspp_feature_maps.py → logs/features/
F. External Dependencies
– PyTorch, torchvision, OpenCV, torchmetrics, matplotlib, tqdm

- Data → Model (Encoder+Decoder)
- Model + Loss → Training Loop → Checkpoints & Logs
- Saved Checkpoint → Inference Scripts → Depth Map Output
- Model Hooks → Feature-Map Extraction Utility → PNGs

##### Architectural Patterns
- Encoder–Decoder with skip connections
- Atrous Spatial Pyramid Pooling + strip convolutions for multi-scale context
- Attention gating & SE blocks for feature fusion
- Composite multi-term loss with learnable weights

##### Detailed Capturing
– Show multi-scale side outputs feeding into intermediate supervision.

## Diagram (Mermaid)

```mermaid
graph TD
    %% Data Layer
    subgraph "Data Layer"
        direction TB
        DatasetFolder(("Test Dataset")):::data
        RIDEDataset["RIDEDataset"]:::data
        Preprocessing["Preprocessing & Augmentations"]:::data
    end

    %% Model Layer
    subgraph "Model Layer"
        direction TB
        Encoder["Encoder (ResNeXt-101)"]:::model
        Decoder["Decoder (RIDE)"]:::model
        CompositeLoss["CompositeLoss (L1+SSIM)"]:::model
        ModelAssembly["Model Assembly"]:::model

        subgraph "Decoder Blocks"
            direction TB
            ASPP["ASPPModule"]:::model
            UpsampleConv["UpsampleConv"]:::model
            HybridSkip["HybridSkipBlock"]:::model
            EdgeAttention["EdgeAttentionBlock"]:::model
            LPG["LPG"]:::model
            AuxRefine["AuxRefinementBlock"]:::model
            SELayer["SELayer"]:::model
            ResidualBlock["ResidualBlock"]:::model
        end
    end

    %% Training Pipeline
    subgraph "Training Pipeline"
        direction TB
        TrainScript[/train.py/]:::train
        Optimizer["Optimizer & Scheduler"]:::train
        LogsStore(("Logs & Metrics")):::train
        Checkpoints(("Checkpoints")):::train
    end

    %% Inference & Visualization
    subgraph "Inference & Visualization"
        direction TB
        BatchScript[/inference_example.py/]:::infer
        WebcamScript[/inference_webcam.py/]:::infer
        PostProcessing["Post-processing & Visualization"]:::infer
        FeatureViz[/extract_aspp_feature_maps.py/]:::infer
        FeatureLogs(("Feature Maps Store")):::infer
    end

    %% External Dependencies
    subgraph "External Dependencies"
        direction TB
        PyTorch["PyTorch"]:::ext
        Torchvision["torchvision"]:::ext
        OpenCV["OpenCV"]:::ext
        TorchMetrics["torchmetrics"]:::ext
        Matplotlib["matplotlib"]:::ext
        TQDM["tqdm"]:::ext
    end

    %% Connections
    DatasetFolder -->|"images"| RIDEDataset
    RIDEDataset -->|"augmented tensors"| Preprocessing
    Preprocessing -->|"img_tensor"| Encoder
    Encoder -->|"features"| Decoder
    Decoder -->|"depth_tensor"| CompositeLoss
    CompositeLoss -->|"loss value"| TrainScript
    ModelAssembly -->|"model & loss"| TrainScript
    TrainScript -->|"save logs"| LogsStore
    TrainScript -->|"save ckpt"| Checkpoints
    Checkpoints -->|"load model"| BatchScript
    Checkpoints -->|"load model"| WebcamScript
    BatchScript -->|"depth_maps"| PostProcessing
    WebcamScript -->|"depth_maps"| PostProcessing
    Encoder -->|"hooked features"| FeatureViz
    FeatureViz -->|"ASPP feature PNGs"| FeatureLogs

    %% Click Events
    click RIDEDataset "https://github.com/rsenatorov/ridev1/blob/main/src/data/dataset.py"
    click Encoder "https://github.com/rsenatorov/ridev1/blob/main/src/network/encoder.py"
    click Decoder "https://github.com/rsenatorov/ridev1/blob/main/src/network/decoder.py"
    click ASPP "https://github.com/rsenatorov/ridev1/blob/main/src/network/blocks/aspp.py"
    click UpsampleConv "https://github.com/rsenatorov/ridev1/blob/main/src/network/blocks/upsample_conv.py"
    click HybridSkip "https://github.com/rsenatorov/ridev1/blob/main/src/network/blocks/hybrid_skip_block.py"
    click EdgeAttention "https://github.com/rsenatorov/ridev1/blob/main/src/network/blocks/edge_attention_block.py"
    click LPG "https://github.com/rsenatorov/ridev1/blob/main/src/network/blocks/lpg.py"
    click AuxRefine "https://github.com/rsenatorov/ridev1/blob/main/src/network/blocks/aux_refinement_block.py"
    click SELayer "https://github.com/rsenatorov/ridev1/blob/main/src/network/blocks/se_layer.py"
    click ResidualBlock "https://github.com/rsenatorov/ridev1/blob/main/src/network/blocks/residual_block.py"
    click CompositeLoss "https://github.com/rsenatorov/ridev1/blob/main/src/network/losses.py"
    click ModelAssembly "https://github.com/rsenatorov/ridev1/blob/main/src/network/model.py"
    click TrainScript "https://github.com/rsenatorov/ridev1/blob/main/src/train.py"
    click LogsStore "https://github.com/rsenatorov/ridev1/tree/main/logs/"
    click FeatureViz "https://github.com/rsenatorov/ridev1/blob/main/src/extract_aspp_feature_maps.py"
    click BatchScript "https://github.com/rsenatorov/ridev1/blob/main/src/inference_example.py"
    click WebcamScript "https://github.com/rsenatorov/ridev1/blob/main/src/inference_webcam.py"
    click DatasetFolder "https://github.com/rsenatorov/ridev1/tree/main/dataset/test"

    %% Styles
    classDef data fill:#D6EAF8,stroke:#1B4F72
    classDef model fill:#D5F5E3,stroke:#145A32
    classDef train fill:#FAD7A0,stroke:#B97A00
    classDef infer fill:#E8DAEF,stroke:#6C3483
    classDef ext fill:#F2F4F4,stroke:#7B7D7D
```
