8c88adc4b1
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>
52 lines
1.7 KiB
Markdown
52 lines
1.7 KiB
Markdown
# 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). 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.).
|