# geoai4cities/lid-lab-nerf architecture

> Architecture diagram of the GitHub repository geoai4cities/lid-lab-nerf, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-10-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/geoai4cities/lid-lab-nerf
- Repository: https://github.com/geoai4cities/lid-lab-nerf

## Overview

##### Main Components
- Data Ingestion & Preprocessing
– Raw KITTI-360 LiDAR point clouds and semantics (.ply)
– Bash script: preprocess_data.sh
– Python modules under data/preprocess/
- Dataset & Data Loader
– data/base_dataset.py, kitti360_dataset.py, kitti360_dataset_with_image.py
– Generates PyTorch Dataset objects & JSON transforms
- Configuration
– configs/kitti360_*.txt (hyperparameters, model settings)
– workspace/args.txt for record keeping
- Model Definition & Core Library
– model/*.py: NeRF fields (hash_field, planes_field, flow_field), renderer, darknet, unet, vgg, labelnerf
– model/runner.py: orchestrates training and evaluation loops
– model/simulator.py: LiDAR simulation after training
- External Dependencies & Extensions
– PyTorch & CUDA
– tiny-cuda-nn (binds into the renderer)
– utils/chamfer3D (custom CUDA kernels for Chamfer distance)
– Other utils: utils/metrics.py, utils/misc.py, utils/convert.py
- Training & Logging
– main_labelnerf.py: entry point for training
– run_kitti_labelnerf.sh: bash wrapper setting CUDA_VISIBLE_DEVICES, config, workspace
– workspace/run/lidar4d/events*.tfevents: TensorBoard logs
- Simulation & Visualization
– main_labelnerf_sim.py: entry point for dynamic scene replay & novel scan generation
– run_kitti_labelnerf_sim.sh: wrapper for simulation parameters
– Outputs: point clouds, intensity, depth, semantic labels in workspace

##### Data Flow & Relationships
- Preprocessing → Dataset
- Dataset → Model Runner
- Config Files → Runner & Model
- Model Runner → Workspace (Checkpoint + Logs)
- Saved Checkpoint + Simulator → Simulation Outputs

##### Architectural Patterns & Design Principles
- Modular Separation:
– Data layer, Model layer, Training orchestration, Simulation layer, Utilities
- Plugin-style fields (hash_field, planes_field, flow_field) that can be swapped via config
- Clear I/O boundary: raw data → preprocessing → standard JSON format → Dataset → NeRF training → checkpoint → simulation
- GPU-accelerated kernels (tiny-cuda-nn, chamfer3D) abstracted in utils

##### Technologies & Frameworks
- Core: Python, PyTorch (with torch.nn, CUDA backend)
- GPU kernels: tiny-cuda-nn, chamfer3D (written in CUDA/C++)
- Scripting: Bash for orchestrating preprocess, train, simulate
- Logging: TensorBoard (events.out.tfevents…)
- Optional Notebook: main.ipynb for interactive exploration

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data Ingestion & Preprocessing
    subgraph "Data Ingestion & Preprocessing"
        direction TB
        PreprocessSH["preprocess_data.sh"]:::data
        CalSeqConfig["cal_seq_config.py"]:::data
        GenRangeview["generate_rangeview.py"]:::data
        GenRangeviewImg["generate_rangeview_with_image.py"]:::data
        KITTI360Loader["kitti360_loader.py"]:::data
        ToNerf["kitti360_to_nerf.py"]:::data
        ToNerfImg["kitti360_to_nerf_with_image.py"]:::data
    end

    %% Dataset & Data Loader
    subgraph "Dataset & Data Loader"
        direction TB
        BaseDataset["base_dataset.py"]:::data
        KITTI360DS["kitti360_dataset.py"]:::data
        KITTI360DSImg["kitti360_dataset_with_image.py"]:::data
    end

    %% Configuration
    subgraph "Configuration"
        direction TB
        ConfigTXT["kitti360_4950.txt"]:::config
        ArgsTXT["args.txt"]:::config
    end

    %% Model Definition & Core Library
    subgraph "Model Definition & Core Library"
        direction TB
        HashField["hash_field.py"]:::compute
        PlanesField["planes_field.py"]:::compute
        FlowField["flow_field.py"]:::compute
        LabelNeRF["labelnerf.py"]:::compute
        Darknet["darknet.py"]:::compute
        UNet["unet.py"]:::compute
        VGG["vgg.py"]:::compute
        Renderer["renderer.py"]:::compute
        Runner["runner.py"]:::compute
        Simulator["simulator.py"]:::compute
        Activation["activation.py"]:::compute
    end

    %% External Dependencies & Utilities
    subgraph "External & Utilities"
        direction TB
        TinyCUDA["tiny-cuda-nn/"]:::external
        Chamfer3D["chamfer3D/"]:::external
        Metrics["metrics.py"]:::util
        Misc["misc.py"]:::util
        Convert["convert.py"]:::util
    end

    %% Training & Logging
    subgraph "Training & Logging"
        direction TB
        MainTrain["main_labelnerf.py"]:::compute
        RunTrainSH["run_kitti_labelnerf.sh"]:::compute
        TBLogs["events.out.tfevents.*"]:::workspace
    end

    %% Simulation & Visualization
    subgraph "Simulation & Visualization"
        direction TB
        MainSim["main_labelnerf_sim.py"]:::compute
        RunSimSH["run_kitti_labelnerf_sim.sh"]:::compute
        SimOutputs["workspace/run/lidar4d/"]:::workspace
    end

    %% Interactive Notebook
    Notebook["main.ipynb"]:::external

    %% Data Flow
    PreprocessSH -->|"outputs JSON transforms"| BaseDataset
    CalSeqConfig --> BaseDataset
    GenRangeview --> BaseDataset
    GenRangeviewImg --> BaseDataset
    KITTI360Loader --> BaseDataset
    ToNerf --> BaseDataset
    ToNerfImg --> BaseDataset

    BaseDataset -->|"PyTorch Dataset"| Runner
    KITTI360DS --> Runner
    KITTI360DSImg --> Runner

    ConfigTXT --> Runner
    ArgsTXT --> Runner
    ConfigTXT --> HashField
    ConfigTXT --> PlanesField
    ConfigTXT --> FlowField

    Runner -->|"checkpoints & logs"| TBLogs
    Runner -->|"checkpoint.pt"| Simulator

    Simulator -->|"simulated LiDAR scans"| SimOutputs
    MainSim --> Simulator
    RunSimSH --> MainSim

    RunTrainSH --> MainTrain
    MainTrain --> Runner

    %% External Integration
    Runner --> TinyCUDA
    Renderer --> TinyCUDA
    Runner --> Chamfer3D
    Metrics --> Runner
    Misc --> Runner
    Convert --> Runner

    %% Optional Notebook link
    Notebook --> BaseDataset
    Notebook --> Runner

    %% Click Events
    click PreprocessSH "https://github.com/geoai4cities/lid-lab-nerf/blob/main/preprocess_data.sh"
    click CalSeqConfig "https://github.com/geoai4cities/lid-lab-nerf/blob/main/data/preprocess/cal_seq_config.py"
    click GenRangeview "https://github.com/geoai4cities/lid-lab-nerf/blob/main/data/preprocess/generate_rangeview.py"
    click GenRangeviewImg "https://github.com/geoai4cities/lid-lab-nerf/blob/main/data/preprocess/generate_rangeview_with_image.py"
    click KITTI360Loader "https://github.com/geoai4cities/lid-lab-nerf/blob/main/data/preprocess/kitti360_loader.py"
    click ToNerf "https://github.com/geoai4cities/lid-lab-nerf/blob/main/data/preprocess/kitti360_to_nerf.py"
    click ToNerfImg "https://github.com/geoai4cities/lid-lab-nerf/blob/main/data/preprocess/kitti360_to_nerf_with_image.py"
    click BaseDataset "https://github.com/geoai4cities/lid-lab-nerf/blob/main/data/base_dataset.py"
    click KITTI360DS "https://github.com/geoai4cities/lid-lab-nerf/blob/main/data/kitti360_dataset.py"
    click KITTI360DSImg "https://github.com/geoai4cities/lid-lab-nerf/blob/main/data/kitti360_dataset_with_image.py"
    click ConfigTXT "https://github.com/geoai4cities/lid-lab-nerf/blob/main/configs/kitti360_4950.txt"
    click ArgsTXT "https://github.com/geoai4cities/lid-lab-nerf/blob/main/workspace/args.txt"
    click HashField "https://github.com/geoai4cities/lid-lab-nerf/blob/main/model/hash_field.py"
    click PlanesField "https://github.com/geoai4cities/lid-lab-nerf/blob/main/model/planes_field.py"
    click FlowField "https://github.com/geoai4cities/lid-lab-nerf/blob/main/model/flow_field.py"
    click LabelNeRF "https://github.com/geoai4cities/lid-lab-nerf/blob/main/model/labelnerf.py"
    click Darknet "https://github.com/geoai4cities/lid-lab-nerf/blob/main/model/darknet.py"
    click UNet "https://github.com/geoai4cities/lid-lab-nerf/blob/main/model/unet.py"
    click VGG "https://github.com/geoai4cities/lid-lab-nerf/blob/main/model/vgg.py"
    click Renderer "https://github.com/geoai4cities/lid-lab-nerf/blob/main/model/renderer.py"
    click Runner "https://github.com/geoai4cities/lid-lab-nerf/blob/main/model/runner.py"
    click Simulator "https://github.com/geoai4cities/lid-lab-nerf/blob/main/model/simulator.py"
    click Activation "https://github.com/geoai4cities/lid-lab-nerf/blob/main/model/activation.py"
    click TinyCUDA "https://github.com/geoai4cities/lid-lab-nerf/tree/main/tiny-cuda-nn/"
    click Chamfer3D "https://github.com/geoai4cities/lid-lab-nerf/tree/main/utils/chamfer3D/"
    click Metrics "https://github.com/geoai4cities/lid-lab-nerf/blob/main/utils/metrics.py"
    click Misc "https://github.com/geoai4cities/lid-lab-nerf/blob/main/utils/misc.py"
    click Convert "https://github.com/geoai4cities/lid-lab-nerf/blob/main/utils/convert.py"
    click MainTrain "https://github.com/geoai4cities/lid-lab-nerf/blob/main/main_labelnerf.py"
    click RunTrainSH "https://github.com/geoai4cities/lid-lab-nerf/blob/main/run_kitti_labelnerf.sh"
    click MainSim "https://github.com/geoai4cities/lid-lab-nerf/blob/main/main_labelnerf_sim.py"
    click RunSimSH "https://github.com/geoai4cities/lid-lab-nerf/blob/main/run_kitti_labelnerf_sim.sh"

    %% Styles
    classDef data fill:#D6EAF8,stroke:#3498DB
    classDef compute fill:#D5F5E3,stroke:#27AE60
    classDef external fill:#F2F3F4,stroke:#95A5A6
    classDef config fill:#FCF3CF,stroke:#F1C40F
    classDef util fill:#E8DAEF,stroke:#8E44AD
    classDef workspace fill:#FDEDEC,stroke:#E74C3C
```
