CLAUDE.md

@@ -1,97 +0,0 @@
-# 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.

Hunyuan3D-2

@@ -1 +0,0 @@
-Subproject commit f8db63096c8282cb27354314d896feba5ba6ff8a

README.md

@@ -4,19 +4,10 @@ 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.
+# Clone the model repo
 git clone https://github.com/Tencent-Hunyuan/Hunyuan3D-2.git
 
 # Build and run
@@ -31,22 +22,15 @@ docker compose up
 
 ```
 hunyuan3d-sunnie/
-  Hunyuan3D-2/          # cloned upstream — operator-managed, not committed
+  Hunyuan3D-2/          # cloned repo (git submodule or manual clone)
   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)
+    Dockerfile           # custom build with CUDA 12.4
+    compose.yml          # GPU-enabled compose with model volume
+    outputs/             # generated meshes land here
 ```
 
 ## 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.).
+- First run downloads model weights (~several GB) to the named volume
+- Uses mini-turbo variant with --low_vram_mode for RTX 3080 (10GB VRAM)
+- Outputs .glb with PBR textures for Blender import