# amirhertz/spaghetti architecture

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

- Interactive diagram: https://gitdiagram.com/amirhertz/spaghetti
- Repository: https://github.com/amirhertz/spaghetti

## Overview

##### File Structure Analysis
Top-level scripts and files
- demo.py           – Entry point that launches the GUI and ties it to model inference
- download_weights.py – Fetches pre‐trained model checkpoints
- options.py         – CLI argument parsing and configuration definitions
- environment.yml    – Specifies conda environment and dependencies
Directories
- models/            – Model definitions (MLP, transformer, OCC GMM, losses, utilities)
- ui/                – All GUI code: main window, controllers, interactors, status bar, inference bridge
- utils/             – Shared utilities: file I/O, meshing (mcubes), mesh transforms, CLI parsing, training helpers

##### Key Architectural Insights from README
- The demo loads pre‐trained weights, presents a mesh collection at the bottom panel, and lets users select mesh parts and apply transformations (G, R, X/Y/Z axes).
- The core inference cycle: UI events → ui/inference_processing → ui/occ_inference → models → utils/meshing → display.

##### Main Components
- ui/ui_main.py            – Bootstraps the Qt/OpenGL window
- ui/ui_controllers.py     – Handles user input, toolbar actions
- ui/interactors.py        – Maps keyboard/mouse events to GUI operations
- ui/gaussian_status.py    – Displays mixture status and editing tools
- ui/inference_processing.py & occ_inference.py – Converts GUI state into model inference calls
- models/transformer.py    – Neural network blocks for part generation
- models/mlp_models.py     – MLP backbones for occupancy prediction
- models/occ_loss.py       – Loss functions (used for inversion/training)
- models/models_utils.py, gm_utils.py – Model-specific utility routines
- assets/mesh/*.obj        – Sample meshes
- samples/ (runtime directory) – Inference output
- download_weights.py      – Populates weights/ directory
- utils/files_utils.py      – Disk I/O and path management
- utils/mcubes_meshing.py   – Marching cubes to turn occupancy grid into mesh
- utils/mesh_utils.py       – Mesh transformations and cleanup
- utils/rotation_utils.py   – Quaternion / Euler conversions
- utils/train_utils.py      – Training loop helpers (future use)
- utils/myparse.py          – CLI parsing support

##### Relationships and Data Flow
- demo.py initializes the UI layer and calls download_weights if needed.
- User selects a mesh → ui_controllers triggers inference_processing.
- inference_processing calls occ_inference, which loads the model weights and invokes the Model Inference Layer to predict occupancy or part latent codes.
- The resulting occupancy grid is sent to utils/mcubes_meshing, converted into a displayable mesh, and fed back to the UI for rendering.
- shape_inversion.py is a separate CLI tool: it uses options.py → models + utils → writes to samples/ for later demo loading.

##### Architectural Patterns & Design Principles
- Clear separation of concerns: GUI vs ML inference vs utilities.
- Modular model definitions: each model type and loss function lives in its own file.
- Script-based orchestration: demo.py and shape_inversion.py serve as “application” entry points, loading configuration and wiring modules together.
- Event-driven UI → inference calls → render cycle for interactive performance.

##### Detail
- How environment.yml captures all dependencies for reproducibility.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Entry-Point Scripts & Configuration
    subgraph "Entry-Point & Config"
        direction TB
        demo["demo.py"]:::script
        shapeInv["shape_inversion.py"]:::script
        options["options.py"]:::script
        env["environment.yml"]:::script
        downloadW["download_weights.py"]:::script
    end

    %% UI Layer
    subgraph "User Interface Layer"
        direction TB
        uiMain["ui/ui_main.py"]:::ui
        uiCtrl["ui/ui_controllers.py"]:::ui
        interactors["ui/interactors.py"]:::ui
        status["ui/gaussian_status.py"]:::ui
        infProc["ui/inference_processing.py"]:::ui
        occInf["ui/occ_inference.py"]:::ui
    end

    %% Model Inference Layer
    subgraph "Model Inference Layer"
        direction TB
        occGMM["models/occ_gmm.py"]:::model
        transformer["models/transformer.py"]:::model
        mlp["models/mlp_models.py"]:::model
        loss["models/occ_loss.py"]:::model
        utilsMod["models/models_utils.py"]:::model
        gmUtils["models/gm_utils.py"]:::model
    end

    %% Data & Asset Layer
    subgraph "Data & Asset Layer"
        direction TB
        mesh["assets/mesh/example.obj"]:::data
        samples["samples/"]:::data
        weightsDir["weights/"]:::data
    end

    %% Utility & Support Layer
    subgraph "Utility & Support Layer"
        direction TB
        filesUtil["utils/files_utils.py"]:::util
        meshing["utils/mcubes_meshing.py"]:::util
        meshUtil["utils/mesh_utils.py"]:::util
        rotUtil["utils/rotation_utils.py"]:::util
        trainUtil["utils/train_utils.py"]:::util
        parseUtil["utils/myparse.py"]:::util
    end

    %% Connections
    demo -->|"boots UI"| uiMain
    demo -->|"loads config"| options
    demo -->|"calls"| downloadW
    shapeInv -->|"uses config"| options
    shapeInv -->|"writes to"| samples
    uiMain --> uiCtrl
    uiCtrl --> interactors
    uiCtrl --> infProc
    infProc --> occInf
    occInf --> occGMM
    occInf --> transformer
    occInf --> mlp
    occInf --> loss
    occInf --> utilsMod
    occInf --> gmUtils
    occInf --> filesUtil
    occInf --> meshing
    meshing --> meshUtil
    meshUtil --> rotUtil
    demo --> mesh
    downloadW --> weightsDir
    filesUtil -->|"I/O support"| samples
    trainUtil --> options
    parseUtil --> options

    samples --> demo

    %% Click Events
    click uiMain "https://github.com/amirhertz/spaghetti/blob/master/ui/ui_main.py"
    click uiCtrl "https://github.com/amirhertz/spaghetti/blob/master/ui/ui_controllers.py"
    click interactors "https://github.com/amirhertz/spaghetti/blob/master/ui/interactors.py"
    click status "https://github.com/amirhertz/spaghetti/blob/master/ui/gaussian_status.py"
    click infProc "https://github.com/amirhertz/spaghetti/blob/master/ui/inference_processing.py"
    click occInf "https://github.com/amirhertz/spaghetti/blob/master/ui/occ_inference.py"
    click occGMM "https://github.com/amirhertz/spaghetti/blob/master/models/occ_gmm.py"
    click transformer "https://github.com/amirhertz/spaghetti/blob/master/models/transformer.py"
    click mlp "https://github.com/amirhertz/spaghetti/blob/master/models/mlp_models.py"
    click loss "https://github.com/amirhertz/spaghetti/blob/master/models/occ_loss.py"
    click utilsMod "https://github.com/amirhertz/spaghetti/blob/master/models/models_utils.py"
    click gmUtils "https://github.com/amirhertz/spaghetti/blob/master/models/gm_utils.py"
    click mesh "https://github.com/amirhertz/spaghetti/blob/master/assets/mesh/example.obj"
    click downloadW "https://github.com/amirhertz/spaghetti/blob/master/download_weights.py"
    click samples "https://github.com/amirhertz/spaghetti/tree/master/samples/"
    click filesUtil "https://github.com/amirhertz/spaghetti/blob/master/utils/files_utils.py"
    click meshing "https://github.com/amirhertz/spaghetti/blob/master/utils/mcubes_meshing.py"
    click meshUtil "https://github.com/amirhertz/spaghetti/blob/master/utils/mesh_utils.py"
    click rotUtil "https://github.com/amirhertz/spaghetti/blob/master/utils/rotation_utils.py"
    click trainUtil "https://github.com/amirhertz/spaghetti/blob/master/utils/train_utils.py"
    click parseUtil "https://github.com/amirhertz/spaghetti/blob/master/utils/myparse.py"

    %% Styles
    classDef ui fill:#B3DFFE,stroke:#0288D1,color:#000;
    classDef model fill:#C8E6C9,stroke:#388E3C,color:#000;
    classDef data fill:#FFE0B2,stroke:#F57C00,color:#000;
    classDef util fill:#E0E0E0,stroke:#616161,color:#000;
    classDef script fill:#F3E5F5,stroke:#6A1B9A,color:#000;
```
