# yihangchen-ee/hac architecture

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

- Interactive diagram: https://gitdiagram.com/yihangchen-ee/hac
- Repository: https://github.com/yihangchen-ee/hac

## Overview

##### Project Type and Purpose
- This project is a research-oriented Pytorch implementation for compressing 3D Gaussian Splatting representations. Its goal is to achieve significant compression (up to 75X) without rendering fidelity loss by using a hash‑grid assisted context model.
- The README emphasizes components such as training, encoding, decoding, and testing – and the experimental results are organized by different datasets/training scripts (e.g., Tanks&Temples, MipNeRF360, BungeeNeRF, etc.).

##### File Structure for Architectural Insights
- Top-level directories and files:
- "arguments": likely a module for handling command-line parameters.
- "assets": contains images (teasers and performance figures) for documentation and visualization.
- "gaussian_renderer": includes Python modules for the rendering and GUI aspects, showing the project’s capacity to display or interact with the 3D representations.
- "lpipsPyTorch": holds the modules for LPIPS perceptual loss computation, suggesting its role in maintaining visual fidelity.
- "scene": contains data loaders, camera handling, Colmap integration, and the Gaussian model – these underpin data preprocessing and scene construction.
- "utils": a comprehensive collection of helper functions for camera processing, encodings (both CPU and CUDA), general graphics, image processing, and system utilities.
- "submodules": contains zipped external libraries for arithmetic coding, diff‑gaussian rasterization, grid encoding, and simple k‑nearest neighbors which are essential for the compression pipeline.
- “results”: stores evaluation CSVs for different datasets and experimental runs.
- "run_shell_*.py" scripts: separate entry points for training/testing with different datasets.
- "train.py": the central script orchestrating the training process.
- The well‑segmented structure (modules for data preparation, core computations, rendering, evaluations, and utilities) is a clear indicator of a modular design where each component is responsible for discrete functions in the pipeline.

##### Components
- Main Components:
- Data Ingestion/Preprocessing: Represented by the “scene” module (cameras, colmap_loader, dataset_readers) and the external “data” folder (created by users according to prescribed structure).
- Training & Compression Pipeline: Driven by the training scripts (train.py & run_shell_xxx.py) that handle the stages of training, encoding, decoding, and evaluation.
- Core Compression and Rendering Modules:
- HAC Compression Core – integrates the innovative hash-grid aided context model, adaptive quantization, and context-based entropy coding.
- Gaussian Renderer (in gaussian_renderer) – visualizes the results.
- Perceptual Loss Module (lpipsPyTorch) – ensures fidelity through LPIPS metrics.
- Utility modules: “utils” for system support (graphics, camera, and encoding utilities) and “arguments” for command-line interfaces.
- External Dependencies: “submodules” containing zipped libraries (for diff‑gaussian rasterization, grid encoding, arithmetic operations, etc.) that perform specialized tasks.
- Result Handling: “results” directory for storing CSV logs and evaluation metrics.

##### Relationships and Interactions
- Data Flow:
- Data originates from custom or public datasets stored under “data/” (not in the repository but referenced in the README).
- The “scene” module ingests and processes the data (images, sparse point clouds, camera parameters), providing input for training.
- Training Workflow:
- The training scripts (run_shell_*.py) call “train.py”, which in turn orchestrates the flow: it retrieves scene data, invokes the Gaussian model for representing 3D structures, and passes data to the compression modules.
- The compression modules leverage the external “submodules” for specialized processing (such as rasterization and grid encoding) and use “lpipsPyTorch” to calculate perceptual losses if required.
- Rendering & Evaluation:
- The “gaussian_renderer” module generates visual outputs.
- The results from training (logs, encoded bitstreams, rendered test images) are organized and saved in the output directories and “results/” folder.
- Utility Layer:
- “utils” functions support data transformation, visualization, system calls, and GPU integrations.
- Configuration & Execution:
- “arguments” encapsulates command-line input handling while environment requirements are defined in “environment.yml” and installation instructions in the README.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data Preprocessing Layer
    subgraph "Data Preprocessing Layer"
        DInput("Data (User-provided datasets)"):::data
        subgraph "Scene Module: Data Ingestion & Camera Management"
            CAM("Cameras"):::data
            COL("COLMAP Loader"):::data
            DSR("Dataset Readers"):::data
            GM("Gaussian Model"):::data
        end
    end

    %% Training & Compression Layer
    subgraph "Training & Compression Layer"
        TS("Train Script (train.py)"):::train
        subgraph "Run Shell Scripts"
            RS1("Shell: Blender (run_shell_blender.py)"):::train
            RS2("Shell: Bungee (run_shell_bungee.py)"):::train
            RS3("Shell: DB (run_shell_db.py)"):::train
            RS4("Shell: Mip360 (run_shell_mip360.py)"):::train
            RS5("Shell: Tanks&Temples (run_shell_tnt.py)"):::train
        end
        HAC("HAC Compression Core"):::train
        subgraph "Perceptual Loss Module (LPIPS)"
            LP1("LPIPS Loss"):::loss
            LP2("LPIPS Networks"):::loss
            LP3("LPIPS Utils"):::loss
        end
    end

    %% Rendering & Evaluation Layer
    subgraph "Rendering & Evaluation Layer"
        GR("Gaussian Renderer"):::render
        subgraph "Results"
            R1("DeepBlending"):::render
            R2("MipNeRF360"):::render
            R3("SyntheticNeRF"):::render
            R4("TanksAndTemples"):::render
        end
    end

    %% Supporting Utilities Layer
    subgraph "Utilities"
        U1("Camera Utils"):::util
        U2("Encodings"):::util
        U3("Encodings CUDA"):::util
        U4("Entropy Models"):::util
        U5("Arguments"):::util
    end

    %% External Dependencies Layer
    subgraph "External Modules"
        E1("Arithmetic"):::external
        E2("Diff-Gaussian Rasterization"):::external
        E3("Grid Encoder"):::external
        E4("Simple-KNN"):::external
    end

    %% Connections - Data to Training
    DInput --> CAM
    CAM --> COL
    COL --> DSR
    DSR --> GM
    GM --> TS

    %% Connections within Training & Compression
    TS --> HAC
    RS1 --> HAC
    RS2 --> HAC
    RS3 --> HAC
    RS4 --> HAC
    RS5 --> HAC
    HAC --> GR
    HAC --> LP1
    HAC --> LP2
    HAC --> LP3

    %% Rendering & Evaluation
    GR --> R1
    GR --> R2
    GR --> R3
    GR --> R4

    %% Supporting connections
    U1 --> TS
    U2 --> TS
    U3 --> TS
    U4 --> TS
    U5 --> TS
    E1 --> HAC
    E2 --> HAC
    E3 --> HAC
    E4 --> HAC

    %% Click Events for Data Ingestion/Preprocessing (scene)
    click CAM "https://github.com/yihangchen-ee/hac/blob/main/scene/cameras.py"
    click COL "https://github.com/yihangchen-ee/hac/blob/main/scene/colmap_loader.py"
    click DSR "https://github.com/yihangchen-ee/hac/blob/main/scene/dataset_readers.py"
    click GM "https://github.com/yihangchen-ee/hac/blob/main/scene/gaussian_model.py"

    %% Click Events for Training & Compression Pipeline
    click TS "https://github.com/yihangchen-ee/hac/blob/main/train.py"
    click RS1 "https://github.com/yihangchen-ee/hac/blob/main/run_shell_blender.py"
    click RS2 "https://github.com/yihangchen-ee/hac/blob/main/run_shell_bungee.py"
    click RS3 "https://github.com/yihangchen-ee/hac/blob/main/run_shell_db.py"
    click RS4 "https://github.com/yihangchen-ee/hac/blob/main/run_shell_mip360.py"
    click RS5 "https://github.com/yihangchen-ee/hac/blob/main/run_shell_tnt.py"

    %% Click Event for Core Compression and Rendering Module
    click GR "https://github.com/yihangchen-ee/hac/blob/main/gaussian_renderer/network_gui.py"

    %% Click Events for Perceptual Loss Module (LPIPS)
    click LP1 "https://github.com/yihangchen-ee/hac/blob/main/lpipsPyTorch/modules/lpips.py"
    click LP2 "https://github.com/yihangchen-ee/hac/blob/main/lpipsPyTorch/modules/networks.py"
    click LP3 "https://github.com/yihangchen-ee/hac/blob/main/lpipsPyTorch/modules/utils.py"

    %% Click Events for Utility Modules
    click U1 "https://github.com/yihangchen-ee/hac/blob/main/utils/camera_utils.py"
    click U2 "https://github.com/yihangchen-ee/hac/blob/main/utils/encodings.py"
    click U3 "https://github.com/yihangchen-ee/hac/blob/main/utils/encodings_cuda.py"
    click U4 "https://github.com/yihangchen-ee/hac/blob/main/utils/entropy_models.py"
    click U5 "https://github.com/yihangchen-ee/hac/blob/main/arguments/__init__.py"

    %% Click Events for External Dependencies
    click E1 "https://github.com/yihangchen-ee/hac/blob/main/submodules/arithmetic.zip"
    click E2 "https://github.com/yihangchen-ee/hac/blob/main/submodules/diff-gaussian-rasterization.zip"
    click E3 "https://github.com/yihangchen-ee/hac/blob/main/submodules/gridencoder.zip"
    click E4 "https://github.com/yihangchen-ee/hac/blob/main/submodules/simple-knn.zip"

    %% Click Events for Result Handling
    click R1 "https://github.com/yihangchen-ee/hac/tree/main/results/DeepBlending"
    click R2 "https://github.com/yihangchen-ee/hac/tree/main/results/MipNeRF360"
    click R3 "https://github.com/yihangchen-ee/hac/tree/main/results/SyntheticNeRF"
    click R4 "https://github.com/yihangchen-ee/hac/tree/main/results/TanksAndTemples"

    %% Class Definitions for Colors
    classDef data fill:#AED6F1,stroke:#1B4F72,stroke-width:2px;
    classDef train fill:#A9DFBF,stroke:#196F3D,stroke-width:2px;
    classDef render fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
    classDef util fill:#F5B7B1,stroke:#922B21,stroke-width:2px;
    classDef external fill:#D2B4DE,stroke:#6C3483,stroke-width:2px;
    classDef loss fill:#85C1E9,stroke:#2471A3,stroke-width:2px;
```
