# linjohnss/frugalnerf architecture

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

- Interactive diagram: https://gitdiagram.com/linjohnss/frugalnerf
- Repository: https://github.com/linjohnss/frugalnerf

## Overview

##### Project Type & Purpose
- This is a machine-learning research codebase (PyTorch) for **few-shot novel-view synthesis** using NeRF.
- It provides data-loading pipelines, model definitions, training/rendering routines, utility scripts, and a custom CUDA loss extension.

##### File Structure
Top-level directories/files and their roles:
- configs/
– Text files encoding hyperparameters for different datasets (DTU, LLFF, RealEstate10K, custom).
- dataLoader/
– Dataset-specific loading and preprocessing modules (colmap2nerf, dtu, llff, realestate10k, your_own_data) and ray tracing utilities.
- extra/
– Helper scripts for batch experiments (auto_run_paramsets), metric computation, Colmap preprocessing.
- models/
– Radiance-field architectures: `tensoRF.py`, `sh.py`, base classes.
- torch_efficient_distloss/
– Custom PyTorch CUDA extension implementing an efficient distance-based loss.
- train.py & renderer.py
– Entry point for training and rendering loops.
- opt.py & utils.py
– Configuration parsing and shared utilities.
- scripts/
– Shell scripts for launching full experiments.
- assets/, README, LICENSE, .gitignore – ancillary.

##### Pull Architecture Insights from README
- Core workflow:
– **train.py** reads a config, loads images (few views), constructs a NeRF model, runs fast training, optionally renders.
- Dependencies: PyTorch, CUDA, configargparse, image I/O libs, tensorboard, custom `torch-efficient-distloss`.
- Supports multiple datasets via dataLoader modules.
- Uses shell scripts to automate batch runs.

##### Main Components & Their Interactions
a. CLI & Configuration Layer
– Components: `train.py`, `opt.py`, config files (`configs/*.txt`), shell scripts (`scripts/*.sh`).
– Responsibility: parse arguments, select hyperparameters, invoke training or rendering.
b. Data Ingestion & Preprocessing
– Components: `dataLoader/*` and `colmap2nerf.py`.
c. Model Definition
– Components: `models/tensorBase.py`, `models/tensoRF.py`, `models/sh.py`.
– Encapsulates scene representation (tensor decomposition, spherical harmonics).
d. Renderer & Training Loop
– Components: `renderer.py`, part of `train.py`.
e. Loss Computation
– Components: `torch_efficient_distloss/`, `utils.py`.
– Computes photometric loss, efficient distance loss via custom CUDA kernels.
f. Optimization & Logging
– Components: inside `train.py` and `utils.py`.
– Runs backprop, updates model, logs metrics to TensorBoard, saves checkpoints.
g. Evaluation & Rendering Only Mode
– Triggered via flags (`--render_only`, `--render_test/train/path`), reuses renderer to generate images.
h. Experiment Automation
– Components: `extra/`, `scripts/`.
– Batch-runs multiple configs, computes evaluation metrics, aggregates results.

##### Architectural Patterns & Principles
- Modular layering: clear separation of CLI, data layer, model layer, training/rendering, extensions.
- Plugin design: any new dataset or model variant can be added to `dataLoader/` or `models/`.
- Custom extension for performance: CUDA kernels in `torch_efficient_distloss`.
- Config-driven reproducibility: all hyperparams in text files, shell scripts orchestrate runs.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% CLI & Configuration Layer
    subgraph "CLI & Configuration Layer"
        direction TB
        CFG_FILES["configs/"]:::io
        TRAIN_CLI["train.py"]:::orchestr
        OPT["opt.py"]:::orchestr
        SCRIPTS_DIR["scripts/"]:::orchestr
    end

    %% Data Ingestion & Preprocessing
    subgraph "Data Ingestion & Preprocessing"
        direction TB
        COLMAP2NERF["colmap2nerf.py"]:::compute
        DTU["dtu.py"]:::compute
        LLFF["llff.py"]:::compute
        RE10K["realestate10k.py"]:::compute
        OWN_DATA["your_own_data.py"]:::compute
        RAY_UTILS["ray_utils.py"]:::compute
        SPARSE_LLFF["sparsedepth_llff.py"]:::compute
        COLMAP_UTILS["colmapUtils/"]:::compute
    end

    %% Model Definition
    subgraph "Model Definition"
        direction TB
        TENSOR_BASE["tensorBase.py"]:::compute
        TENSORF["tensoRF.py"]:::compute
        SH["sh.py"]:::compute
    end

    %% Renderer & Training Loop
    subgraph "Renderer & Training Loop"
        direction TB
        RENDERER["renderer.py"]:::compute
        TRAIN_LOOP["train.py"]:::orchestr
    end

    %% Loss Computation (Custom CUDA Extension)
    subgraph "Loss Computation (CUDA)"
        direction TB
        EFF_LOSS["eff_distloss.py"]:::compute
        SEG_CSUM_CPP["segment_cumsum.cpp"]:::compute
        SEG_CSUM_CU["segment_cumsum_kernel.cu"]:::compute
    end

    %% Optimization & Logging
    subgraph "Optimization & Logging"
        direction TB
        OPT_UTILS["utils.py"]:::compute
    end

    %% Experiment Automation & Metrics
    subgraph "Experiment Automation & Scripts"
        direction TB
        AUTO_RUN["auto_run_paramsets.py"]:::orchestr
        COLMAP_LLFF["colmap_llff.py"]:::orchestr
        COMPUTE_METRICS["compute_metrics.py"]:::compute
        READ_METRICS["read_metrics.py"]:::compute
    end

    %% Core Data Flow
    CFG_FILES -->|reads| TRAIN_LOOP
    OPT -->|parses args| TRAIN_LOOP
    SCRIPTS_DIR -->|launches| TRAIN_LOOP

    TRAIN_LOOP -->|loads data| COLMAP2NERF
    TRAIN_LOOP -->|loads data| DTU
    TRAIN_LOOP -->|loads data| LLFF
    TRAIN_LOOP -->|loads data| RE10K
    TRAIN_LOOP -->|loads data| OWN_DATA
    TRAIN_LOOP -->|utils| RAY_UTILS
    TRAIN_LOOP -->|utils| SPARSE_LLFF
    TRAIN_LOOP -->|utils| COLMAP_UTILS

    COLMAP2NERF -->|produces rays| RENDERER
    DTU --> RENDERER
    LLFF --> RENDERER
    RE10K --> RENDERER
    OWN_DATA --> RENDERER

    TRAIN_LOOP -->|defines model| TENSOR_BASE
    TRAIN_LOOP --> TENSORF
    TRAIN_LOOP --> SH

    RENDERER -->|renders| TRAIN_LOOP
    RENDERER -->|calls| EFF_LOSS
    EFF_LOSS -->|uses| SEG_CSUM_CPP
    EFF_LOSS --> SEG_CSUM_CU

    TRAIN_LOOP -->|backprop| OPT_UTILS
    OPT_UTILS -->|logs/checkpoints| TRAIN_LOOP

    SCRIPTS_DIR -->|batch runs| AUTO_RUN
    AUTO_RUN --> TRAIN_LOOP
    AUTO_RUN --> COLMAP_LLFF
    COLMAP_LLFF --> TRAIN_LOOP
    AUTO_RUN --> COMPUTE_METRICS
    AUTO_RUN --> READ_METRICS

    %% Click Events
    click TRAIN_CLI "https://github.com/linjohnss/frugalnerf/blob/main/train.py"
    click OPT "https://github.com/linjohnss/frugalnerf/blob/main/opt.py"
    click CFG_FILES "https://github.com/linjohnss/frugalnerf/tree/main/configs/"
    click SCRIPTS_DIR "https://github.com/linjohnss/frugalnerf/tree/main/scripts/"
    click COLMAP2NERF "https://github.com/linjohnss/frugalnerf/blob/main/dataLoader/colmap2nerf.py"
    click DTU "https://github.com/linjohnss/frugalnerf/blob/main/dataLoader/dtu.py"
    click LLFF "https://github.com/linjohnss/frugalnerf/blob/main/dataLoader/llff.py"
    click RE10K "https://github.com/linjohnss/frugalnerf/blob/main/dataLoader/realestate10k.py"
    click OWN_DATA "https://github.com/linjohnss/frugalnerf/blob/main/dataLoader/your_own_data.py"
    click RAY_UTILS "https://github.com/linjohnss/frugalnerf/blob/main/dataLoader/ray_utils.py"
    click SPARSE_LLFF "https://github.com/linjohnss/frugalnerf/blob/main/dataLoader/sparsedepth_llff.py"
    click COLMAP_UTILS "https://github.com/linjohnss/frugalnerf/tree/main/dataLoader/colmapUtils/"
    click TENSOR_BASE "https://github.com/linjohnss/frugalnerf/blob/main/models/tensorBase.py"
    click TENSORF "https://github.com/linjohnss/frugalnerf/blob/main/models/tensoRF.py"
    click SH "https://github.com/linjohnss/frugalnerf/blob/main/models/sh.py"
    click RENDERER "https://github.com/linjohnss/frugalnerf/blob/main/renderer.py"
    click EFF_LOSS "https://github.com/linjohnss/frugalnerf/blob/main/torch_efficient_distloss/eff_distloss.py"
    click SEG_CSUM_CPP "https://github.com/linjohnss/frugalnerf/blob/main/torch_efficient_distloss/cuda/segment_cumsum.cpp"
    click SEG_CSUM_CU "https://github.com/linjohnss/frugalnerf/blob/main/torch_efficient_distloss/cuda/segment_cumsum_kernel.cu"
    click OPT_UTILS "https://github.com/linjohnss/frugalnerf/blob/main/utils.py"
    click AUTO_RUN "https://github.com/linjohnss/frugalnerf/blob/main/extra/auto_run_paramsets.py"
    click COLMAP_LLFF "https://github.com/linjohnss/frugalnerf/blob/main/extra/colmap_llff.py"
    click COMPUTE_METRICS "https://github.com/linjohnss/frugalnerf/blob/main/extra/compute_metrics.py"
    click READ_METRICS "https://github.com/linjohnss/frugalnerf/blob/main/extra/read_metrics.py"

    %% Styles
    classDef io fill:#D0E6F6,stroke:#0366D6,stroke-width:1px
    classDef compute fill:#DFF6DD,stroke:#22863A,stroke-width:1px
    classDef orchestr fill:#FFF5B1,stroke:#DBAB09,stroke-width:1px
```
