# elevatormusic/modly-hunyuan3d-2-1-shape-extension architecture

> Architecture diagram of the GitHub repository elevatormusic/modly-hunyuan3d-2-1-shape-extension, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/elevatormusic/modly-hunyuan3d-2-1-shape-extension
- Repository: https://github.com/elevatormusic/modly-hunyuan3d-2-1-shape-extension

## Overview

This repository is a Modly extension that turns an input image into a 3D mesh, with optional PBR painting and post-processing. The documented flow is image input → shape generation → mesh cleanup → optional texture painting and finishing → GLB output. The graph also shows the BPT retopology path and its model internals, plus the VRAM-planning and finishing layers. Some relationships are documented in the README; sampled source references support the implementation links. Unsampled modules are represented only where the README or source index establishes their role.

Main entry points: [`generator.py`](https://github.com/elevatormusic/modly-hunyuan3d-2-1-shape-extension/blob/main/generator.py) (Generation orchestrator), [`bpt_runner/_bpt_src/miche/michelangelo/models/tsal/sal_perceiver.py`](https://github.com/elevatormusic/modly-hunyuan3d-2-1-shape-extension/blob/main/bpt_runner/_bpt_src/miche/michelangelo/models/tsal/sal_perceiver.py) (TSAL model blocks), [`finishing.py`](https://github.com/elevatormusic/modly-hunyuan3d-2-1-shape-extension/blob/main/finishing.py) (Texture finishing), [`bpt_runner/_bpt_src/model/model.py`](https://github.com/elevatormusic/modly-hunyuan3d-2-1-shape-extension/blob/main/bpt_runner/_bpt_src/model/model.py) (BPT transformer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_generation["Shape generation"]
  node_generator["Generation orchestrator<br/>[generator.py]"]
  node_shape_model["Shape model<br/>[generator.py]"]
  node_geometry["Mesh extraction<br/>[inference_utils.py]"]
  node_capacity["VRAM planner<br/>[capacity.py]"]
end

subgraph group_retopology["Mesh retopology"]
  node_mesh_cleanup["Mesh cleanup<br/>[mesh_cleanup.py]"]
  node_bpt["BPT retopology<br/>[__init__.py]"]
  node_provision["BPT provisioning<br/>[provision.py]"]
  node_bpt_infer["BPT inference<br/>[infer.py]"]
end

subgraph group_painting["Texture and finishing"]
  node_texture_paint["PBR paint pass<br/>[generator.py]"]
  node_finishing["Texture finishing<br/>[finishing.py]"]
  node_seam_fix["Seam correction<br/>[seam_fix.py]"]
  node_normal_bake["Normal-map bake<br/>[normal_bake.py]"]
  node_game_ready["Game-ready output<br/>[game_ready.py]"]
end

subgraph group_internals["Model internals"]
  node_bpt_model["BPT transformer<br/>[model.py]"]
  node_bpt_data["Mesh data utilities<br/>[data_utils.py]"]
  node_bpt_conditioner["Point-cloud conditioning"]
  node_serialization["Mesh serialization<br/>[serializaiton.py]"]
  node_tsal_base["TSAL base<br/>[tsal_base.py]"]
  node_tsal_blocks["TSAL model blocks<br/>[sal_perceiver.py]"]
  node_attention_blocks["Attention blocks"]
  node_embedder["Embedding modules<br/>[embedder.py]"]
  node_distributions["Latent distributions<br/>[distributions.py]"]
  node_checkpoint["Checkpoint utilities<br/>[checkpoint.py]"]
  node_misc["Model utilities<br/>[misc.py]"]
end

node_user(("Modly user"))
node_image["Input image"]
node_output["GLB model"]

node_user -->|"provides"| node_image
node_image -->|"starts generation"| node_generator
node_generator -->|"generates shape"| node_shape_model
node_shape_model -->|"extracts mesh"| node_geometry
node_generator -->|"plans memory"| node_capacity
node_generator -->|"cleans mesh"| node_mesh_cleanup
node_mesh_cleanup -->|"runs BPT"| node_bpt
node_bpt -->|"ensures setup"| node_provision
node_bpt -->|"runs inference"| node_bpt_infer
node_bpt_infer -->|"executes model"| node_bpt_model
node_bpt_model -->|"uses mesh data"| node_bpt_data
node_bpt_model -->|"uses conditioning"| node_bpt_conditioner
node_bpt_model -->|"serializes meshes"| node_serialization
node_tsal_blocks -->|"extends base"| node_tsal_base
node_tsal_blocks -->|"uses attention"| node_attention_blocks
node_tsal_blocks -->|"uses embeddings"| node_embedder
node_tsal_blocks -->|"uses distributions"| node_distributions
node_tsal_blocks -->|"uses checkpointing"| node_checkpoint
node_generator -->|"paints textures"| node_texture_paint
node_generator -->|"finishes output"| node_finishing
node_finishing -->|"fixes seams"| node_seam_fix
node_finishing -->|"bakes normals"| node_normal_bake
node_generator -->|"converts output"| node_game_ready
node_finishing -->|"writes GLB"| node_output
node_game_ready -->|"replaces mesh"| node_output

click node_generator "https://github.com/elevatormusic/modly-hunyuan3d-2-1-shape-extension/blob/main/generator.py"
click node_shape_model "https://github.com/elevatormusic/modly-hunyuan3d-2-1-shape-extension/blob/main/generator.py"
click node_geometry "https://github.com/elevatormusic/modly-hunyuan3d-2-1-shape-extension/blob/main/bpt_runner/_bpt_src/miche/michelangelo/models/tsal/inference_utils.py"
click node_capacity "https://github.com/elevatormusic/modly-hunyuan3d-2-1-shape-extension/blob/main/capacity.py"
click node_mesh_cleanup "https://github.com/elevatormusic/modly-hunyuan3d-2-1-shape-extension/blob/main/mesh_cleanup.py"
click node_bpt "https://github.com/elevatormusic/modly-hunyuan3d-2-1-shape-extension/blob/main/bpt_runner/__init__.py"
click node_provision "https://github.com/elevatormusic/modly-hunyuan3d-2-1-shape-extension/blob/main/bpt_runner/provision.py"
click node_bpt_infer "https://github.com/elevatormusic/modly-hunyuan3d-2-1-shape-extension/blob/main/bpt_runner/infer.py"
click node_texture_paint "https://github.com/elevatormusic/modly-hunyuan3d-2-1-shape-extension/blob/main/generator.py"
click node_finishing "https://github.com/elevatormusic/modly-hunyuan3d-2-1-shape-extension/blob/main/finishing.py"
click node_seam_fix "https://github.com/elevatormusic/modly-hunyuan3d-2-1-shape-extension/blob/main/seam_fix.py"
click node_normal_bake "https://github.com/elevatormusic/modly-hunyuan3d-2-1-shape-extension/blob/main/normal_bake.py"
click node_game_ready "https://github.com/elevatormusic/modly-hunyuan3d-2-1-shape-extension/blob/main/game_ready.py"
click node_bpt_model "https://github.com/elevatormusic/modly-hunyuan3d-2-1-shape-extension/blob/main/bpt_runner/_bpt_src/model/model.py"
click node_bpt_data "https://github.com/elevatormusic/modly-hunyuan3d-2-1-shape-extension/blob/main/bpt_runner/_bpt_src/model/data_utils.py"
click node_bpt_conditioner "https://github.com/elevatormusic/modly-hunyuan3d-2-1-shape-extension/blob/main/bpt_runner/_bpt_src/model/miche_conditioner.py"
click node_serialization "https://github.com/elevatormusic/modly-hunyuan3d-2-1-shape-extension/blob/main/bpt_runner/_bpt_src/model/serializaiton.py"
click node_tsal_base "https://github.com/elevatormusic/modly-hunyuan3d-2-1-shape-extension/blob/main/bpt_runner/_bpt_src/miche/michelangelo/models/tsal/tsal_base.py"
click node_tsal_blocks "https://github.com/elevatormusic/modly-hunyuan3d-2-1-shape-extension/blob/main/bpt_runner/_bpt_src/miche/michelangelo/models/tsal/sal_perceiver.py"
click node_attention_blocks "https://github.com/elevatormusic/modly-hunyuan3d-2-1-shape-extension/blob/main/bpt_runner/_bpt_src/miche/michelangelo/models/modules/transformer_blocks.py"
click node_embedder "https://github.com/elevatormusic/modly-hunyuan3d-2-1-shape-extension/blob/main/bpt_runner/_bpt_src/miche/michelangelo/models/modules/embedder.py"
click node_distributions "https://github.com/elevatormusic/modly-hunyuan3d-2-1-shape-extension/blob/main/bpt_runner/_bpt_src/miche/michelangelo/models/modules/distributions.py"
click node_checkpoint "https://github.com/elevatormusic/modly-hunyuan3d-2-1-shape-extension/blob/main/bpt_runner/_bpt_src/miche/michelangelo/models/modules/checkpoint.py"
click node_misc "https://github.com/elevatormusic/modly-hunyuan3d-2-1-shape-extension/blob/main/bpt_runner/_bpt_src/miche/michelangelo/utils/misc.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_generator,node_shape_model,node_geometry,node_capacity,node_user toneBlue
class node_mesh_cleanup,node_bpt,node_provision,node_bpt_infer toneAmber
class node_texture_paint,node_finishing,node_seam_fix,node_normal_bake,node_game_ready toneMint
class node_bpt_model,node_bpt_data,node_bpt_conditioner,node_serialization,node_tsal_base,node_tsal_blocks,node_attention_blocks,node_embedder,node_distributions,node_checkpoint,node_misc toneRose
class node_image,node_output toneIndigo
```

## Components

### Shape generation

- [Generation orchestrator](https://github.com/elevatormusic/modly-hunyuan3d-2-1-shape-extension/blob/main/generator.py): `generator.py`
- [Shape model](https://github.com/elevatormusic/modly-hunyuan3d-2-1-shape-extension/blob/main/generator.py): `generator.py`
- [Mesh extraction](https://github.com/elevatormusic/modly-hunyuan3d-2-1-shape-extension/blob/main/bpt_runner/_bpt_src/miche/michelangelo/models/tsal/inference_utils.py): `bpt_runner/_bpt_src/miche/michelangelo/models/tsal/inference_utils.py`
- [VRAM planner](https://github.com/elevatormusic/modly-hunyuan3d-2-1-shape-extension/blob/main/capacity.py): `capacity.py`

### Mesh retopology

- [Mesh cleanup](https://github.com/elevatormusic/modly-hunyuan3d-2-1-shape-extension/blob/main/mesh_cleanup.py): `mesh_cleanup.py`
- [BPT retopology](https://github.com/elevatormusic/modly-hunyuan3d-2-1-shape-extension/blob/main/bpt_runner/__init__.py): `bpt_runner/__init__.py`
- [BPT provisioning](https://github.com/elevatormusic/modly-hunyuan3d-2-1-shape-extension/blob/main/bpt_runner/provision.py): `bpt_runner/provision.py`
- [BPT inference](https://github.com/elevatormusic/modly-hunyuan3d-2-1-shape-extension/blob/main/bpt_runner/infer.py): `bpt_runner/infer.py`

### Texture and finishing

- [PBR paint pass](https://github.com/elevatormusic/modly-hunyuan3d-2-1-shape-extension/blob/main/generator.py): `generator.py`
- [Texture finishing](https://github.com/elevatormusic/modly-hunyuan3d-2-1-shape-extension/blob/main/finishing.py): `finishing.py`
- [Seam correction](https://github.com/elevatormusic/modly-hunyuan3d-2-1-shape-extension/blob/main/seam_fix.py): `seam_fix.py`
- [Normal-map bake](https://github.com/elevatormusic/modly-hunyuan3d-2-1-shape-extension/blob/main/normal_bake.py): `normal_bake.py`
- [Game-ready output](https://github.com/elevatormusic/modly-hunyuan3d-2-1-shape-extension/blob/main/game_ready.py): `game_ready.py`

### Model internals

- [BPT transformer](https://github.com/elevatormusic/modly-hunyuan3d-2-1-shape-extension/blob/main/bpt_runner/_bpt_src/model/model.py): `bpt_runner/_bpt_src/model/model.py`
- [Mesh data utilities](https://github.com/elevatormusic/modly-hunyuan3d-2-1-shape-extension/blob/main/bpt_runner/_bpt_src/model/data_utils.py): `bpt_runner/_bpt_src/model/data_utils.py`
- [Point-cloud conditioning](https://github.com/elevatormusic/modly-hunyuan3d-2-1-shape-extension/blob/main/bpt_runner/_bpt_src/model/miche_conditioner.py): `bpt_runner/_bpt_src/model/miche_conditioner.py`
- [Mesh serialization](https://github.com/elevatormusic/modly-hunyuan3d-2-1-shape-extension/blob/main/bpt_runner/_bpt_src/model/serializaiton.py): `bpt_runner/_bpt_src/model/serializaiton.py`
- [TSAL base](https://github.com/elevatormusic/modly-hunyuan3d-2-1-shape-extension/blob/main/bpt_runner/_bpt_src/miche/michelangelo/models/tsal/tsal_base.py): `bpt_runner/_bpt_src/miche/michelangelo/models/tsal/tsal_base.py`
- [TSAL model blocks](https://github.com/elevatormusic/modly-hunyuan3d-2-1-shape-extension/blob/main/bpt_runner/_bpt_src/miche/michelangelo/models/tsal/sal_perceiver.py): `bpt_runner/_bpt_src/miche/michelangelo/models/tsal/sal_perceiver.py`
- [Attention blocks](https://github.com/elevatormusic/modly-hunyuan3d-2-1-shape-extension/blob/main/bpt_runner/_bpt_src/miche/michelangelo/models/modules/transformer_blocks.py): `bpt_runner/_bpt_src/miche/michelangelo/models/modules/transformer_blocks.py`
- [Embedding modules](https://github.com/elevatormusic/modly-hunyuan3d-2-1-shape-extension/blob/main/bpt_runner/_bpt_src/miche/michelangelo/models/modules/embedder.py): `bpt_runner/_bpt_src/miche/michelangelo/models/modules/embedder.py`
- [Latent distributions](https://github.com/elevatormusic/modly-hunyuan3d-2-1-shape-extension/blob/main/bpt_runner/_bpt_src/miche/michelangelo/models/modules/distributions.py): `bpt_runner/_bpt_src/miche/michelangelo/models/modules/distributions.py`
- [Checkpoint utilities](https://github.com/elevatormusic/modly-hunyuan3d-2-1-shape-extension/blob/main/bpt_runner/_bpt_src/miche/michelangelo/models/modules/checkpoint.py): `bpt_runner/_bpt_src/miche/michelangelo/models/modules/checkpoint.py`
- [Model utilities](https://github.com/elevatormusic/modly-hunyuan3d-2-1-shape-extension/blob/main/bpt_runner/_bpt_src/miche/michelangelo/utils/misc.py): `bpt_runner/_bpt_src/miche/michelangelo/utils/misc.py`

### Other components

- **Modly user**
- **Input image**
- **GLB model**

## Connections

- Modly user → Input image: provides
- Input image → Generation orchestrator: starts generation
- Generation orchestrator → Shape model: generates shape (evidence: `generator.py`)
- Shape model → Mesh extraction: extracts mesh (evidence: `bpt_runner/_bpt_src/miche/michelangelo/models/tsal/inference_utils.py`)
- Generation orchestrator → VRAM planner: plans memory (evidence: `generator.py`)
- Generation orchestrator → Mesh cleanup: cleans mesh (evidence: `generator.py`)
- Mesh cleanup → BPT retopology: runs BPT (evidence: `mesh_cleanup.py`)
- BPT retopology → BPT provisioning: ensures setup (evidence: `bpt_runner/__init__.py`)
- BPT retopology → BPT inference: runs inference (evidence: `bpt_runner/__init__.py`)
- BPT inference → BPT transformer: executes model (evidence: `bpt_runner/infer.py`)
- BPT transformer → Mesh data utilities: uses mesh data (evidence: `bpt_runner/_bpt_src/model/model.py`)
- BPT transformer → Point-cloud conditioning: uses conditioning (evidence: `bpt_runner/_bpt_src/model/model.py`)
- BPT transformer → Mesh serialization: serializes meshes (evidence: `bpt_runner/_bpt_src/model/serializaiton.py`)
- TSAL model blocks → TSAL base: extends base (evidence: `bpt_runner/_bpt_src/miche/michelangelo/models/tsal/sal_perceiver.py`)
- TSAL model blocks → Attention blocks: uses attention (evidence: `bpt_runner/_bpt_src/miche/michelangelo/models/tsal/sal_perceiver.py`)
- TSAL model blocks → Embedding modules: uses embeddings (evidence: `bpt_runner/_bpt_src/miche/michelangelo/models/tsal/sal_perceiver.py`)
- TSAL model blocks → Latent distributions: uses distributions (evidence: `bpt_runner/_bpt_src/miche/michelangelo/models/tsal/sal_perceiver.py`)
- TSAL model blocks → Checkpoint utilities: uses checkpointing (evidence: `bpt_runner/_bpt_src/miche/michelangelo/models/tsal/sal_perceiver.py`)
- Generation orchestrator → PBR paint pass: paints textures (evidence: `generator.py`)
- Generation orchestrator → Texture finishing: finishes output (evidence: `generator.py`)
- Texture finishing → Seam correction: fixes seams (evidence: `finishing.py`)
- Texture finishing → Normal-map bake: bakes normals (evidence: `finishing.py`)
- Generation orchestrator → Game-ready output: converts output (evidence: `generator.py`)
- Texture finishing → GLB model: writes GLB
- Game-ready output → GLB model: replaces mesh
