117f06c055
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>
53 lines
1.7 KiB
Markdown
53 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). 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.).
|