# authoritywang/videogs architecture

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

- Interactive diagram: https://gitdiagram.com/authoritywang/videogs
- Repository: https://github.com/authoritywang/videogs

## Overview

##### Project Type and Purpose
- This is a research-oriented processing pipeline (not a web app) for generating, compressing, and viewing volumetric videos on mobile devices using 2D dynamic Gaussians.
- It comprises four main phases: Data Preprocessing, Model Training, Compression, and Rendering/Serving.

##### Break Out the Main Components
A. Data Sources & Storage
- Raw Datasets (ReRF, HiFi4G, HumanRF)
- File-based storage for “processed” datasets (`datasets/…`)
- Output folder (`output/…`)
- Configuration store (`config/config_hash.json`)
B. External Tools & Libraries
- COLMAP (for calibration & undistortion)
- NeuS2_K (key-frame point cloud generator)
- Submodules: diff-gaussian-rasterization, simple-knn
- LPIPS (perceptual loss)
C. Preprocessing Subsystem
- Scripts in `preprocess/` (calibration.py, undistortion.py, colmap2k.py, hifi4g_process.py)
- Utilities from `utils/` (camera_utils, general_utils)
- CLI entry point: none (invoked via explicit python commands)
D. Training Subsystem
- Entry scripts: `train_sequence.py`, `train_dynamic.py`, `train_prune.py`, `train.py`
- Core modules in `scene/` (gaussian_model, global_t_field, dataset_readers)
- Loss modules: `lpipsPyTorch` + `utils/loss_utils.py`
- Arguments parsing: `arguments/`
- Output: Gaussian checkpoint folders + NeuS2 outputs
E. Compression & Serving Subsystem
- Scripts in `compress/` (compress_ckpt_2_image_precompute.py, compress_image_2_video.py, decompress_video_2_ckpt.py)
- Viewer/rendering: `gaussian_renderer/network_gui.py` + `run.py`, `convert.py`
- Web Server (nginx) hosting the compressed videos + viewer front-end assets (`assets/`)

##### Architectural Patterns & Key Technologies
- Pipelines: clearly separate each phase into its own lane.
- Modular CLI: show Python scripts as rectangles calling into underlying modules.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Data Sources & Storage
    subgraph "Data Sources & Storage"
        direction TB
        RawDatasets(("Raw Datasets")):::storage
        ProcessedDatasets(("Processed Datasets\ndatasets/…")):::storage
        OutputFolder(("Output Folder\noutput/…")):::storage
        ConfigStore(("config/config_hash.json")):::storage
    end

    %% External Tools & Libraries
    subgraph "External Tools & Libraries"
        direction TB
        COLMAP{{"COLMAP"}}:::external
        NeuS2K{{"NeuS2_K"}}:::external
        LPIPS{{"LPIPS"}}:::external
        DiffRaster{{"diff-gaussian-rasterization"}}:::external
        SimpleKNN{{"simple-knn"}}:::external
    end

    %% Preprocessing Subsystem
    subgraph "Preprocessing Subsystem"
        direction TB
        Calibration["preprocess/calibration.py"]:::compute
        Undistortion["preprocess/undistortion.py"]:::compute
        Colmap2K["preprocess/colmap2k.py"]:::compute
        HiFi4G["preprocess/hifi4g_process.py"]:::compute
        CamUtils["utils/camera_utils.py"]:::util
        GenUtils["utils/general_utils.py"]:::util
    end

    %% Training Subsystem
    subgraph "Training Subsystem"
        direction TB
        TrainMain["train.py"]:::compute
        TrainSeq["train_sequence.py"]:::compute
        TrainDyn["train_dynamic.py"]:::compute
        TrainPrune["train_prune.py"]:::compute
        subgraph "scene/"
            direction TB
            GaussianModel["scene/gaussian_model.py"]:::compute
            GlobalT["scene/global_t_field.py"]:::compute
            GlobalRT["scene/global_rt_field.py"]:::compute
            GlobalRTC["scene/global_rtc_field.py"]:::compute
            GlobalTNoHash["scene/global_t_field_wo_hash.py"]:::compute
            DatasetReaders["scene/dataset_readers.py"]:::compute
            Cameras["scene/cameras.py"]:::compute
            ColmapLoader["scene/colmap_loader.py"]:::compute
        end
        LossUtils["utils/loss_utils.py"]:::util
        Arguments["arguments/__init__.py"]:::util
    end

    %% Compression & Serving Subsystem
    subgraph "Compression & Serving Subsystem"
        direction TB
        Precompute["compress/compress_ckpt_2_image_precompute.py"]:::compute
        CompressCKPT2Img["compress/compress_ckpt_2_image.py"]:::compute
        Img2Vid["compress/compress_image_2_video.py"]:::compute
        Decompress["compress/decompress_video_2_ckpt.py"]:::compute
        Renderer["gaussian_renderer/network_gui.py"]:::compute
        RunViewer["run.py"]:::compute
        Convert["convert.py"]:::compute
        Assets(("assets/")):::storage
    end

    %% Data Flows
    RawDatasets -->|"files"| Calibration
    RawDatasets --> Undistortion
    Calibration --> COLMAP
    Undistortion --> COLMAP
    COLMAP --> Colmap2K
    Colmap2K --> NeuS2K
    NeuS2K --> ProcessedDatasets
    HiFi4G --> ProcessedDatasets
    CamUtils --> Calibration
    GenUtils --> Undistortion
    ProcessedDatasets --> TrainMain
    ProcessedDatasets --> TrainSeq
    ProcessedDatasets --> TrainDyn
    ProcessedDatasets --> TrainPrune
    TrainMain --> GaussianModel
    TrainMain --> GlobalT
    TrainMain --> GlobalRT
    TrainMain --> GlobalRTC
    TrainMain --> GlobalTNoHash
    TrainMain --> DatasetReaders
    TrainMain --> Cameras
    TrainMain --> ColmapLoader
    TrainMain --> LossUtils
    TrainMain --> Arguments
    TrainSeq --> TrainMain
    TrainDyn --> TrainMain
    TrainPrune --> TrainMain
    TrainMain --> OutputFolder
    OutputFolder --> Precompute
    Precompute --> CompressCKPT2Img
    CompressCKPT2Img --> Img2Vid
    Img2Vid --> Assets
    Assets --> Renderer
    Assets --> RunViewer
    Assets --> Convert
    OutputFolder --> Decompress
    Decompress --> OutputFolder

    %% Config read
    ConfigStore --> Calibration
    ConfigStore --> TrainMain
    ConfigStore --> Precompute

    %% Submodule calls
    TrainMain -.-> DiffRaster
    TrainMain -.-> SimpleKNN
    TrainMain -.-> LPIPS

    %% Click Events
    click ConfigStore "https://github.com/authoritywang/videogs/blob/main/config/config_hash.json"
    click Calibration "https://github.com/authoritywang/videogs/blob/main/preprocess/calibration.py"
    click Undistortion "https://github.com/authoritywang/videogs/blob/main/preprocess/undistortion.py"
    click Colmap2K "https://github.com/authoritywang/videogs/blob/main/preprocess/colmap2k.py"
    click HiFi4G "https://github.com/authoritywang/videogs/blob/main/preprocess/hifi4g_process.py"
    click CamUtils "https://github.com/authoritywang/videogs/blob/main/utils/camera_utils.py"
    click GenUtils "https://github.com/authoritywang/videogs/blob/main/utils/general_utils.py"
    click TrainMain "https://github.com/authoritywang/videogs/blob/main/train.py"
    click TrainSeq "https://github.com/authoritywang/videogs/blob/main/train_sequence.py"
    click TrainDyn "https://github.com/authoritywang/videogs/blob/main/train_dynamic.py"
    click TrainPrune "https://github.com/authoritywang/videogs/blob/main/train_prune.py"
    click GaussianModel "https://github.com/authoritywang/videogs/blob/main/scene/gaussian_model.py"
    click GlobalT "https://github.com/authoritywang/videogs/blob/main/scene/global_t_field.py"
    click GlobalRT "https://github.com/authoritywang/videogs/blob/main/scene/global_rt_field.py"
    click GlobalRTC "https://github.com/authoritywang/videogs/blob/main/scene/global_rtc_field.py"
    click GlobalTNoHash "https://github.com/authoritywang/videogs/blob/main/scene/global_t_field_wo_hash.py"
    click DatasetReaders "https://github.com/authoritywang/videogs/blob/main/scene/dataset_readers.py"
    click Cameras "https://github.com/authoritywang/videogs/blob/main/scene/cameras.py"
    click ColmapLoader "https://github.com/authoritywang/videogs/blob/main/scene/colmap_loader.py"
    click LossUtils "https://github.com/authoritywang/videogs/blob/main/utils/loss_utils.py"
    click Arguments "https://github.com/authoritywang/videogs/blob/main/arguments/__init__.py"
    click Precompute "https://github.com/authoritywang/videogs/blob/main/compress/compress_ckpt_2_image_precompute.py"
    click CompressCKPT2Img "https://github.com/authoritywang/videogs/blob/main/compress/compress_ckpt_2_image.py"
    click Img2Vid "https://github.com/authoritywang/videogs/blob/main/compress/compress_image_2_video.py"
    click Decompress "https://github.com/authoritywang/videogs/blob/main/compress/decompress_video_2_ckpt.py"
    click Renderer "https://github.com/authoritywang/videogs/blob/main/gaussian_renderer/network_gui.py"
    click RunViewer "https://github.com/authoritywang/videogs/blob/main/run.py"
    click Convert "https://github.com/authoritywang/videogs/blob/main/convert.py"
    click DiffRaster "https://github.com/authoritywang/videogs/tree/main/submodules/diff-gaussian-rasterization/"
    click SimpleKNN "https://github.com/authoritywang/videogs/tree/main/submodules/simple-knn/"

    %% Styles
    classDef storage fill:#BBDEFB,stroke:#1E88E5,color:#0D47A1;
    classDef compute fill:#C8E6C9,stroke:#2E7D32,color:#1B5E20;
    classDef external fill:#FFE0B2,stroke:#EF6C00,color:#E65100;
    classDef util fill:#E0E0E0,stroke:#9E9E9E,color:#424242;
```
