# buaacyw/meshanything architecture

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

- Interactive diagram: https://gitdiagram.com/buaacyw/meshanything
- Repository: https://github.com/buaacyw/meshanything

## Overview

##### Project type and purpose
- MeshAnything is a Python-based research toolkit and library for 3D mesh generation from meshes or point clouds.
- It exposes both a CLI (`main.py`) and a local Gradio UI (`app.py`), and implements an autoregressive transformer pipeline (leveraging the Michelangelo codebase) plus VAE and diffusion submodules.

##### File structure
- Top level:
- `app.py` (Gradio UI)
- `main.py` (CLI entry)
- `mesh_to_pc.py` (mesh ↔ point-cloud converter)
- `MeshAnything/miche/…` (the Michelangelo-based model code)
- `MeshAnything/models/…` (model wrappers & optimization scripts)
- `requirements.txt` & `setup.py` (build/config)
- `examples/`, `demo/` (sample data/UI assets)
- Inside `MeshAnything/miche/michelangelo`:
- `data/` (templates, transforms, utils)
- `graphics/primitives/` (mesh/volume definitions)
- `models/` (ASL diffusion + TSAL modules)
- `utils/` (I/O, evaluation, visualization adapters)

##### README for insights
- The pipeline supports two input types: mesh and point-cloud with normals.
- Inference loads pre-trained weights from HuggingFace.
- Internally uses PyTorch, FlashAttention, HuggingFace Transformers and vector-quantize-pytorch.

##### Main components and interactions
a. Front-end/UI
- CLI layer: `main.py` parses flags (`--input_dir`, `--input_type`, `--mc`, etc.)
- Gradio UI: `app.py` exposes upload buttons and displays outputs
b. Data Ingestion & Preprocessing
- Input handler: mesh loader (`.obj`) or point-cloud loader (`.npy`)
- Normalization & Marching Cubes (optional)
- `mesh_to_pc.py` for mesh→point-cloud conversions
c. Encoder & Quantizer
- ShapeVAE config (`shapevae-256.yaml`)
- Embedding modules in `miche/michelangelo/models/modules`
- Conditional encoders (`clip`, factory)
d. Autoregressive Transformer
- Diffusion/TSAL pl_modules (`asl_diffusion`, `tsal`)
- Uses FlashAttention and HuggingFace Transformers under the hood
e. Post-processing & Output
- Token→mesh decoding (templates.json, primitives)
- 3D primitive stitching to produce `.obj` files
f. External services & storage
- Weights repository on HuggingFace
- Local file system for input/output directories

##### Architectural patterns & design principles
- Layered architecture: UI → Data → Model → Utils
- Modular plugin system for encoders & pl_modules (factory pattern)
- Separation of concerns: graphics primitives, data transforms, model logic, and I/O all live in distinct packages
- Leverages existing open-source modules (Michelangelo, vector-quantize-pytorch)

##### Essential elements
- Call out configuration files (`shapevae-256.yaml`) and data templates (`templates.json`) near the data store

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% UI Layer
    subgraph "UI Layer" 
        direction TB
        CLI["CLI Layer\nmain.py"]:::ui
        GR["Gradio UI\napp.py"]:::ui
    end

    %% Data Layer
    subgraph "Data Layer"
        direction TB
        M2P["Mesh↔Point-Cloud Converter\nmesh_to_pc.py"]:::data
        PRE["Preprocessor\nNormalization & Marching Cubes"]:::data
        SCFG["ShapeVAE Config\nshapevae-256.yaml"]:::data
        DTEMPL["Data Templates Store\ntemplates.json"]:::data
        DTRANS["Data Transforms & Utils\ntransforms.py\nutils.py"]:::data
        GPRIM["Graphics Primitives\nmesh.py\nvolume.py"]:::data
    end

    %% Model Layer
    subgraph "Model Layer"
        direction TB
        EQ["Embedding & Quantizer\nmodules/"]:::model
        CENC["Conditional Encoders & Factory\nconditional_encoders/"]:::model
        ADIFF["ASL Diffusion Modules\nasl_diffusion/"]:::model
        TSAL["TSAL Modules\ntsal/"]:::model
        MWRAP["Model Wrappers & Optimizers\nmeshanything.py\nshape_opt.py"]:::model
    end

    %% Decoder Layer
    subgraph "Post-Processing & Output"
        direction TB
        DEC["Decoder & Stitching\ntoken→mesh"]:::model
    end

    %% External Services
    subgraph "External"
        direction TB
        HF["HuggingFace Weights"]:::external
        FS["Local File System"]:::external
    end

    %% Flow
    CLI -->|".obj/.npy input"| M2P
    GR -->|"upload mesh/pc"| M2P

    M2P -->|"normalized mesh/pc"| PRE
    PRE -.->|"optional Marching Cubes"| PRE
    PRE -->|"tensor data"| EQ

    EQ -->|"embeddings"| CENC
    CENC -->|"conditioned tokens"| ADIFF
    CENC -->|"conditioned tokens"| TSAL

    ADIFF -->|"diffused tokens"| DEC
    TSAL -->|"transformed tokens"| DEC

    DEC -->|"mesh .obj"| FS

    HF -->|"load weights"| ADIFF
    HF -->|"load weights"| TSAL

    %% Data store links
    DTEMPL --> DEC
    DTRANS --> EQ
    GPRIM --> DEC
    SCFG --> EQ

    %% Click Events
    click CLI "https://github.com/buaacyw/meshanything/blob/main/main.py"
    click GR "https://github.com/buaacyw/meshanything/blob/main/app.py"
    click M2P "https://github.com/buaacyw/meshanything/blob/main/mesh_to_pc.py"
    click SCFG "https://github.com/buaacyw/meshanything/blob/main/MeshAnything/miche/shapevae-256.yaml"
    click DTEMPL "https://github.com/buaacyw/meshanything/blob/main/MeshAnything/miche/michelangelo/data/templates.json"
    click DTRANS "https://github.com/buaacyw/meshanything/blob/main/MeshAnything/miche/michelangelo/data/transforms.py"
    click DTRANS "https://github.com/buaacyw/meshanything/blob/main/MeshAnything/miche/michelangelo/data/utils.py"
    click GPRIM "https://github.com/buaacyw/meshanything/blob/main/MeshAnything/miche/michelangelo/graphics/primitives/mesh.py"
    click GPRIM "https://github.com/buaacyw/meshanything/blob/main/MeshAnything/miche/michelangelo/graphics/primitives/volume.py"
    click EQ "https://github.com/buaacyw/meshanything/tree/main/MeshAnything/miche/michelangelo/models/modules/"
    click CENC "https://github.com/buaacyw/meshanything/tree/main/MeshAnything/miche/michelangelo/models/conditional_encoders/"
    click ADIFF "https://github.com/buaacyw/meshanything/tree/main/MeshAnything/miche/michelangelo/models/asl_diffusion/"
    click TSAL "https://github.com/buaacyw/meshanything/tree/main/MeshAnything/miche/michelangelo/models/tsal/"
    click MWRAP "https://github.com/buaacyw/meshanything/blob/main/MeshAnything/models/meshanything.py"
    click MWRAP "https://github.com/buaacyw/meshanything/blob/main/MeshAnything/models/shape_opt.py"

    %% Styles
    classDef ui fill:#D0E6FF,stroke:#0366d6,color:#0366d6;
    classDef data fill:#DFF2BF,stroke:#4F8A10,color:#4F8A10;
    classDef model fill:#FFE599,stroke:#D87F0A,color:#D87F0A;
    classDef external fill:#EEEEEE,stroke:#888888,color:#666666;
```
