# 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

```bash
# 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.).