# kaist-visual-ai-group/salad architecture

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

- Interactive diagram: https://gitdiagram.com/kaist-visual-ai-group/salad
- Repository: https://github.com/kaist-visual-ai-group/salad

## Overview

##### Project type and purpose
- It implements a two‐phase part‐level latent diffusion model, with training/inference CLI entry points, a Hydra‐driven config system, core model components, data loaders, and an interactive “SPAGHETTI” UI submodule.

##### File structure
- **Top level**
- `train.py` – CLI entry for training (unconditional/text‐guided).
- `setup.py` – package installation.
- `configs/` – Hydra YAML config hierarchy (model, trainer, paths, logger, callbacks).
- `environment.yml` – conda spec.
- `notebooks/` – Jupyter demos for generation and part completion.
- **Core library** (`salad/`)
- `data/` – dataset definition.
- `model_components/` – building blocks (transformer, LSTM, variance schedule).
- `models/` – high‐level model definitions (phase1, phase2, language phases).
- `spaghetti/` – interactive UI tool for mesh inference/editing, with own checkpoints, utils, and assets.
- `utils/` – shared utilities (logging, mesh I/O, path management, etc.).

##### README for additional insights
- Confirms two‐stage diffusion (low‐dim extrinsic then high‐dim intrinsic).
- Uses PyTorch + Hydra + CUDA pointnet2 ops.
- Provides training CLI examples and data/checkpoint layout.
- SPAGHETTI is an open‐source dependency embedded under `salad/spaghetti/`.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interfaces Layer
    subgraph "User Interfaces" 
        direction TB
        CLI["CLI Entry Point<br/>(train.py)"]:::ui
        NB["Jupyter Notebooks<br/>(notebooks/)"]:::ui
        GUI["SPAGHETTI UI<br/>(salad/spaghetti/)"]:::ui
    end

    %% Configuration Layer
    subgraph "Configuration System"
        direction TB
        Hydra["Hydra Core"]:::config
        CFG_DIR["YAML Configs<br/>(configs/)"]:::config
        subgraph "Config Subdirectories"
            direction TB
            LOGGER_CFG["Logger Hooks<br/>(configs/logger/)"]:::config
            CALLBACK_CFG["Callbacks<br/>(configs/callbacks/)"]:::config
            PATHS_CFG["Paths & Artifacts<br/>(configs/paths/)"]:::config
        end
    end

    %% Core Compute Components
    subgraph "Core Library"
        direction TB
        subgraph "Data Layer"
            direction TB
            DataLoader["Dataset Definition<br/>(salad/data/dataset.py)"]:::compute
        end
        subgraph "Model Components"
            direction TB
            Components["Building Blocks<br/>(salad/model_components/)"]:::compute
            subgraph "Diffusion Models"
                direction TB
                Phase1["Phase1 Model<br/>(phase1.py)"]:::compute
                Phase2["Phase2 Model<br/>(phase2.py)"]:::compute
                Lang1["Language Phase1<br/>(language_phase1.py)"]:::compute
                Lang2["Language Phase2<br/>(language_phase2.py)"]:::compute
                Base["Base Model<br/>(base_model.py)"]:::compute
            end
        end
        subgraph "Training Engine"
            direction TB
            Trainer["Trainer"]:::compute
            TrainUtil["Train Utils<br/>(salad/utils/train_util.py)"]:::compute
            LogUtil["Log Utils<br/>(salad/utils/logutil.py)"]:::compute
            PathsUtil["Paths Util<br/>(salad/utils/paths.py)"]:::compute
        end
        subgraph "SPAGHETTI Submodule"
            direction TB
            SPAG_MODELS["Models & Utils<br/>(salad/spaghetti/models/)"]:::compute
            SPAG_UTILS["Utils & Meshing<br/>(salad/spaghetti/utils/)"]:::compute
            ASSETS["Assets & Checkpoints<br/>(salad/spaghetti/assets/checkpoints/)"]:::storage
        end
    end

    %% External Ops & Utilities
    subgraph "External & Utilities"
        direction TB
        PointNet2["PointNet2 Ops Lib<br/>(notebooks/uncleaned_demo/pvd/modules/pointnet2_ops_lib/)"]:::external
        MeshUtil["Mesh I/O Util<br/>(salad/utils/meshutil.py)"]:::compute
        MCubes["MCubes Meshing<br/>(salad/spaghetti/utils/mcubes_meshing.py)"]:::compute
    end

    %% Storage & Artifacts
    subgraph "Storage & Artifacts"
        direction TB
        Checkpoints["Checkpoint Storage"]:::storage
        Logs["TensorBoard Logs"]:::storage
    end

    %% Environment & Package
    subgraph "Setup & Docs"
        direction TB
        ENV["Conda Env Spec<br/>(environment.yml)"]:::external
        SETUP["Package Install<br/>(setup.py)"]:::external
        DOCS["README & Docs<br/>(README.md & docs/)"]:::external
    end

    %% External Services
    GPU["GPU / CUDA Runtime"]:::external

    %% Connections
    User["User"]:::external -->|runs| CLI
    User -->|opens| NB
    User -->|launches| GUI

    CLI -->|loads config| Hydra
    NB -->|loads config| Hydra
    CLI -->|uses notebooks| NB

    Hydra -->|reads| CFG_DIR
    CFG_DIR -->|includes| LOGGER_CFG
    CFG_DIR -->|includes| CALLBACK_CFG
    CFG_DIR -->|includes| PATHS_CFG

    Hydra -->|instantiates| DataLoader
    Hydra -->|instantiates| Trainer
    Hydra -->|instantiates| Phase1
    Hydra -->|instantiates| Phase2

    DataLoader -->|feeds| Trainer
    Trainer -->|trains| Phase1
    Trainer -->|trains| Phase2
    Trainer -->|uses| Components
    Trainer -->|uses| Base

    Trainer -->|logs to| Logs
    Trainer -->|saves to| Checkpoints

    Phase1 -->|cascade to| Phase2

    GUI -->|loads weights| Checkpoints
    GUI -->|runs inference| Phase2
    GUI -->|uses mesh util| SPAG_UTILS

    NB -->|loads weights| Checkpoints
    NB -->|runs inference| Phase2
    NB -->|uses| PointNet2
    NB -->|uses mesh util| MeshUtil

    PointNet2 -->|accelerates| Phase1
    MeshUtil -->|used by| GUI
    MCubes -->|used by| GUI

    GPU -->|accelerates| Phase1
    GPU -->|accelerates| Phase2

    %% Click Events
    click CLI "https://github.com/kaist-visual-ai-group/salad/blob/main/train.py"
    click NB "https://github.com/kaist-visual-ai-group/salad/tree/main/notebooks/"
    click Hydra "https://github.com/kaist-visual-ai-group/salad/tree/main/configs/"
    click CFG_DIR "https://github.com/kaist-visual-ai-group/salad/tree/main/configs/"
    click LOGGER_CFG "https://github.com/kaist-visual-ai-group/salad/tree/main/configs/logger/"
    click CALLBACK_CFG "https://github.com/kaist-visual-ai-group/salad/tree/main/configs/callbacks/"
    click PATHS_CFG "https://github.com/kaist-visual-ai-group/salad/tree/main/configs/paths/"
    click DataLoader "https://github.com/kaist-visual-ai-group/salad/blob/main/salad/data/dataset.py"
    click Components "https://github.com/kaist-visual-ai-group/salad/tree/main/salad/model_components/"
    click Phase1 "https://github.com/kaist-visual-ai-group/salad/blob/main/salad/models/phase1.py"
    click Phase2 "https://github.com/kaist-visual-ai-group/salad/blob/main/salad/models/phase2.py"
    click Lang1 "https://github.com/kaist-visual-ai-group/salad/blob/main/salad/models/language_phase1.py"
    click Lang2 "https://github.com/kaist-visual-ai-group/salad/blob/main/salad/models/language_phase2.py"
    click Base "https://github.com/kaist-visual-ai-group/salad/blob/main/salad/models/base_model.py"
    click TrainUtil "https://github.com/kaist-visual-ai-group/salad/blob/main/salad/utils/train_util.py"
    click LogUtil "https://github.com/kaist-visual-ai-group/salad/blob/main/salad/utils/logutil.py"
    click PathsUtil "https://github.com/kaist-visual-ai-group/salad/blob/main/salad/utils/paths.py"
    click SPAG_MODELS "https://github.com/kaist-visual-ai-group/salad/tree/main/salad/spaghetti/models/"
    click SPAG_UTILS "https://github.com/kaist-visual-ai-group/salad/tree/main/salad/spaghetti/utils/"
    click ASSETS "https://github.com/kaist-visual-ai-group/salad/tree/main/salad/spaghetti/assets/checkpoints/"
    click PointNet2 "https://github.com/kaist-visual-ai-group/salad/tree/main/notebooks/uncleaned_demo/pvd/modules/pointnet2_ops_lib/"
    click MeshUtil "https://github.com/kaist-visual-ai-group/salad/blob/main/salad/utils/meshutil.py"
    click MCubes "https://github.com/kaist-visual-ai-group/salad/blob/main/salad/spaghetti/utils/mcubes_meshing.py"
    click ENV "https://github.com/kaist-visual-ai-group/salad/blob/main/environment.yml"
    click SETUP "https://github.com/kaist-visual-ai-group/salad/blob/main/setup.py"
    click DOCS "https://github.com/kaist-visual-ai-group/salad/blob/main/README.md"
    click GPU "https://github.com/kaist-visual-ai-group/salad/blob/main/environment.yml"

    %% Styles
    classDef compute fill:#D0E6FF,stroke:#004080,stroke-width:1px;
    classDef config fill:#DFFFE0,stroke:#237A00,stroke-width:1px;
    classDef ui fill:#FFF4C2,stroke:#C28700,stroke-width:1px;
    classDef storage fill:#FFE6CC,stroke:#CC6600,stroke-width:1px;
    classDef external fill:#E0E0E0,stroke:#666666,stroke-width:1px;
```
