# Claude notes — hunyuan3d-sunnie

Agent context for this repo. Read before non-trivial changes.

## What this is

One-off pipeline to generate a 3D mesh of *Sunnie* from a reference
image using Tencent's [Hunyuan3D-2](https://github.com/Tencent-Hunyuan/Hunyuan3D-2)
(`mini-turbo` variant), then rig + animate in Blender via Mixamo. This
repo owns the **docker wrapper** around upstream Hunyuan3D-2 — it is
**not** a fork of the model code itself.

## Repo shape

```
hunyuan3d-sunnie/
  Hunyuan3D-2/        # UNTRACKED — upstream clone. Cloned by the operator
                      # before `docker compose build`. Not a git submodule.
  docker/
    Dockerfile        # community-derived (per repo issues #125, #122)
    compose.yml       # GPU compose; pins the mini-turbo model + flashvdm
    outputs/          # generated .glb meshes land here (untracked)
  README.md
  CLAUDE.md
```

`Hunyuan3D-2/` is intentionally untracked. Operators run
`git clone https://github.com/Tencent-Hunyuan/Hunyuan3D-2.git` once;
the Dockerfile then COPYs it in via the build context. Don't add it
as a submodule or vendor it into source control — keep the upstream
boundary clean.

## Hardware contract

- **NVIDIA GPU required**, exposed through Docker via the nvidia
  runtime (`deploy.resources.reservations.devices` with the `nvidia`
  driver). The compose `command` is tuned for **RTX 3080 / 10 GB
  VRAM** with `--low_vram_mode` + `--enable_flashvdm`. Move to a
  bigger card → drop `--low_vram_mode`. Smaller card → expect OOMs.
- **CUDA 12.4**. The Dockerfile pulls `nvidia/cuda:12.4.0-devel-ubuntu22.04`
  and installs PyTorch from the cu124 wheels index. Don't switch CUDA
  versions without re-aligning the PyTorch index URL.

## Compose command — don't casually edit

```yaml
command: >
  python3 gradio_app.py
  --model_path tencent/Hunyuan3D-2mini
  --subfolder hunyuan3d-dit-v2-mini-turbo
  --texgen_model_path tencent/Hunyuan3D-2
  --low_vram_mode
  --enable_flashvdm
  --host 0.0.0.0
  --port 8080
```

- `--model_path` + `--subfolder` together select the **mini-turbo**
  variant. The full Hunyuan3D-2 model won't fit in 10 GB.
- `--texgen_model_path` uses the full Hunyuan3D-2 model **for PBR
  texture generation only** (texture-gen has a lower VRAM ceiling
  than mesh-gen).
- Removing `--low_vram_mode` or `--enable_flashvdm` will likely
  produce OOM on a 3080.

## Model weights

First run downloads weights to the `hunyuan3d-models` named volume
(mounted at `/root/.cache/hy3dgen`). Both the mini-turbo mesh model
and the full texgen model need to come down — several GB total. Don't
prune that volume between sessions unless you're ready to wait through
the re-download.

## Where outputs land

`./docker/outputs/` is bind-mounted into the container at
`/workspace/outputs/`. The Gradio app drops `.glb` files there with
PBR textures embedded — ready for Blender import → Mixamo rigging.
The dir is untracked; nothing in it is meant to be committed.

## Don't-touch zones

- The untracked `Hunyuan3D-2/` directory — let operators reclone if
  they need to update.
- The `--low_vram_mode` + `--enable_flashvdm` flags — load-bearing for
  the 3080.
- The Dockerfile's PyTorch index URL — pinned to cu124 to match the
  base image.
- `pip install -e .` and `flash-attn` are wrapped in `|| true` because
  they're known-flaky on this base image; that's intentional. Don't
  "fix" by making them required.

## Bigger picture

This is a personal/one-off project, not part of the homelab production
stack. It only runs on the dev tower (which has the GPU) — never on
the herbydev Proxmox host or the NAS.