hunyuan3d-sunnie/CLAUDE.md

Claude notes — hunyuan3d-sunnie

Agent context for this repo. Read before non-trivial changes.

What this is

One-off pipeline to generate a 3D mesh of Sunnie from a reference image using Tencent's Hunyuan3D-2 (mini-turbo variant), then rig + animate in Blender via Mixamo. This repo owns the docker wrapper around upstream Hunyuan3D-2 — it is not a fork of the model code itself.

Repo shape

hunyuan3d-sunnie/
  Hunyuan3D-2/        # UNTRACKED — upstream clone. Cloned by the operator
                      # before `docker compose build`. Not a git submodule.
  docker/
    Dockerfile        # community-derived (per repo issues #125, #122)
    compose.yml       # GPU compose; pins the mini-turbo model + flashvdm
    outputs/          # generated .glb meshes land here (untracked)
  README.md
  CLAUDE.md

Hunyuan3D-2/ is intentionally untracked. Operators run git clone https://github.com/Tencent-Hunyuan/Hunyuan3D-2.git once; the Dockerfile then COPYs it in via the build context. Don't add it as a submodule or vendor it into source control — keep the upstream boundary clean.

Hardware contract

• NVIDIA GPU required, exposed through Docker via the nvidia runtime (deploy.resources.reservations.devices with the nvidia driver). The compose command is tuned for RTX 3080 / 10 GB VRAM with --low_vram_mode + --enable_flashvdm. Move to a bigger card → drop --low_vram_mode. Smaller card → expect OOMs.
• CUDA 12.4. The Dockerfile pulls nvidia/cuda:12.4.0-devel-ubuntu22.04 and installs PyTorch from the cu124 wheels index. Don't switch CUDA versions without re-aligning the PyTorch index URL.

Compose command — don't casually edit

command: >
  python3 gradio_app.py
  --model_path tencent/Hunyuan3D-2mini
  --subfolder hunyuan3d-dit-v2-mini-turbo
  --texgen_model_path tencent/Hunyuan3D-2
  --low_vram_mode
  --enable_flashvdm
  --host 0.0.0.0
  --port 8080  

• --model_path + --subfolder together select the mini-turbo variant. The full Hunyuan3D-2 model won't fit in 10 GB.
• --texgen_model_path uses the full Hunyuan3D-2 model for PBR texture generation only (texture-gen has a lower VRAM ceiling than mesh-gen).
• Removing --low_vram_mode or --enable_flashvdm will likely produce OOM on a 3080.

Model weights

First run downloads weights to the hunyuan3d-models named volume (mounted at /root/.cache/hy3dgen). Both the mini-turbo mesh model and the full texgen model need to come down — several GB total. Don't prune that volume between sessions unless you're ready to wait through the re-download.

Where outputs land

./docker/outputs/ is bind-mounted into the container at /workspace/outputs/. The Gradio app drops .glb files there with PBR textures embedded — ready for Blender import → Mixamo rigging. The dir is untracked; nothing in it is meant to be committed.

Don't-touch zones

• The untracked Hunyuan3D-2/ directory — let operators reclone if they need to update.
• The --low_vram_mode + --enable_flashvdm flags — load-bearing for the 3080.
• The Dockerfile's PyTorch index URL — pinned to cu124 to match the base image.
• pip install -e . and flash-attn are wrapped in || true because they're known-flaky on this base image; that's intentional. Don't "fix" by making them required.

Bigger picture

This is a personal/one-off project, not part of the homelab production stack. It only runs on the dev tower (which has the GPU) — never on the herbydev Proxmox host or the NAS.