petal-power/hunyuan3d-sunnie
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
31b0802046
hunyuan3d-sunnie/README.md
Travis Herbranson 117f06c055 docs: correct "gitignored" wording — repo has no .gitignore 
README + CLAUDE.md previously claimed Hunyuan3D-2/ and docker/outputs/
were "gitignored". The repo has no .gitignore at all; those paths are
just untracked. Use "untracked" / "not committed" wording instead so
the operator contract (clone upstream, don't add) is clear without
implying a gitignore safety net.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-20 07:21:55 -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). Operator-managed; not
# committed.
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 — operator-managed, not committed
  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 (not committed)

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.).