How elevatormusic/modly-hunyuan3d-2-1-shape-extension works
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 Generation orchestrator · sal_perceiver.py TSAL model blocks · finishing.py Texture finishing · model.py BPT transformer
Components 27
Shape generation
- Generation orchestrator
generator.py - Shape model
generator.py - Mesh extraction
bpt_runner/_bpt_src/miche/michelangelo/models/tsal/inference_utils.py - VRAM planner
capacity.py
Mesh retopology
- Mesh cleanup
mesh_cleanup.py - BPT retopology
bpt_runner/__init__.py - BPT provisioning
bpt_runner/provision.py - BPT inference
bpt_runner/infer.py
Texture and finishing
- PBR paint pass
generator.py - Texture finishing
finishing.py - Seam correction
seam_fix.py - Normal-map bake
normal_bake.py - Game-ready output
game_ready.py
Model internals
- BPT transformer
bpt_runner/_bpt_src/model/model.py - Mesh data utilities
bpt_runner/_bpt_src/model/data_utils.py - Point-cloud conditioning
bpt_runner/_bpt_src/model/miche_conditioner.py - Mesh serialization
bpt_runner/_bpt_src/model/serializaiton.py - TSAL base
bpt_runner/_bpt_src/miche/michelangelo/models/tsal/tsal_base.py - TSAL model blocks
bpt_runner/_bpt_src/miche/michelangelo/models/tsal/sal_perceiver.py - Attention blocks
bpt_runner/_bpt_src/miche/michelangelo/models/modules/transformer_blocks.py - Embedding modules
bpt_runner/_bpt_src/miche/michelangelo/models/modules/embedder.py - Latent distributions
bpt_runner/_bpt_src/miche/michelangelo/models/modules/distributions.py - Checkpoint utilities
bpt_runner/_bpt_src/miche/michelangelo/models/modules/checkpoint.py - Model utilities
bpt_runner/_bpt_src/miche/michelangelo/utils/misc.py
Other components
- Modly user
- Input image
- GLB model
Connections 25
- Modly user → Input image: provides
- Input image → Generation orchestrator: starts generation
- Generation orchestrator → Shape model: generates shape
generator.py - Shape model → Mesh extraction: extracts mesh
bpt_runner/_bpt_src/miche/michelangelo/models/tsal/inference_utils.py - Generation orchestrator → VRAM planner: plans memory
generator.py - Generation orchestrator → Mesh cleanup: cleans mesh
generator.py - Mesh cleanup → BPT retopology: runs BPT
mesh_cleanup.py - BPT retopology → BPT provisioning: ensures setup
bpt_runner/__init__.py - BPT retopology → BPT inference: runs inference
bpt_runner/__init__.py - BPT inference → BPT transformer: executes model
bpt_runner/infer.py - BPT transformer → Mesh data utilities: uses mesh data
bpt_runner/_bpt_src/model/model.py - BPT transformer → Point-cloud conditioning: uses conditioning
bpt_runner/_bpt_src/model/model.py - BPT transformer → Mesh serialization: serializes meshes
bpt_runner/_bpt_src/model/serializaiton.py - TSAL model blocks → TSAL base: extends base
bpt_runner/_bpt_src/miche/michelangelo/models/tsal/sal_perceiver.py - TSAL model blocks → Attention blocks: uses attention
bpt_runner/_bpt_src/miche/michelangelo/models/tsal/sal_perceiver.py - TSAL model blocks → Embedding modules: uses embeddings
bpt_runner/_bpt_src/miche/michelangelo/models/tsal/sal_perceiver.py - TSAL model blocks → Latent distributions: uses distributions
bpt_runner/_bpt_src/miche/michelangelo/models/tsal/sal_perceiver.py - TSAL model blocks → Checkpoint utilities: uses checkpointing
bpt_runner/_bpt_src/miche/michelangelo/models/tsal/sal_perceiver.py - Generation orchestrator → PBR paint pass: paints textures
generator.py - Generation orchestrator → Texture finishing: finishes output
generator.py - Texture finishing → Seam correction: fixes seams
finishing.py - Texture finishing → Normal-map bake: bakes normals
finishing.py - Generation orchestrator → Game-ready output: converts output
generator.py - Texture finishing → GLB model: writes GLB
- Game-ready output → GLB model: replaces mesh