petal-power/hunyuan3d-sunnie
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
8c88adc4b1
hunyuan3d-sunnie/README.md
Travis Herbranson 8c88adc4b1 docs: add CLAUDE.md, expand README with hardware contract 
Repo previously had only a 36-line README and no CLAUDE.md.

README:
- Add Requirements section (NVIDIA GPU + nvidia runtime + CUDA 12.4)
- Clarify Hunyuan3D-2/ is gitignored / operator-managed, not a submodule
- Spell out why both the mini-turbo and full models download
- Cross-reference CLAUDE.md for agent gotchas

CLAUDE.md: hardware contract, the load-bearing compose flags (low_vram,
flashvdm), CUDA-12.4 pin reasoning, and the intentional |||| true on
pip -e . / flash-attn install steps.

Untracked Hunyuan3D-2/ subdir intentionally left out of this commit.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-20 07:20:46 -04:00

1.7 KiB
Raw Blame History

Hunyuan3D-2 + Sunnie Animation Pipeline

Self-hosted Hunyuan3D-2 (mini-turbo variant) for generating a 3D Sunnie mesh from a reference image, then rigging and animating in Blender via Mixamo.

Requirements

  • NVIDIA GPU with CUDA 12.4 support and ≥ 10 GB VRAM (tuned for RTX 3080).
  • Docker + the NVIDIA Container Toolkit (nvidia runtime exposed to compose).
  • Network egress to pull PyTorch wheels + Hugging Face model weights on first build / first run.

Quick Start

# Clone the upstream model repo into this directory (not a submodule —
# the Dockerfile COPYs it via the build context). This dir is gitignored.
git clone https://github.com/Tencent-Hunyuan/Hunyuan3D-2.git

# Build and run
cd docker
docker compose build
docker compose up

# Gradio UI at http://localhost:8080

Project Structure

hunyuan3d-sunnie/
  Hunyuan3D-2/          # cloned upstream — gitignored, operator-managed
  docker/
    Dockerfile          # custom build, CUDA 12.4, community-derived
    compose.yml         # GPU compose; pins mini-turbo + flashvdm + low_vram
    outputs/            # generated .glb meshes land here (gitignored)

Notes

  • First run downloads model weights (~several GB) to the hunyuan3d-models named volume — both the mini-turbo mesh model and the full Hunyuan3D-2 model for PBR texture generation.
  • Uses the mini-turbo variant with --low_vram_mode and --enable_flashvdm for the 10 GB VRAM ceiling on a 3080. Bigger card? Drop --low_vram_mode. Smaller card? Expect OOMs.
  • Outputs .glb with PBR textures, ready for Blender import → Mixamo rigging.
  • See CLAUDE.md for the agent-facing gotchas (don't-touch flags, CUDA pin rationale, etc.).