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