Create hunyuan3d-sunnie-pipeline.md via n8n

Tech/Projects/hunyuan3d-sunnie-pipeline.md

@@ -0,0 +1,158 @@
+---
+project: hunyuan3d-sunnie-pipeline
+type: project-plan
+status: active
+path: Tech/Projects
+tags:
+  - homelab
+  - docker
+  - ai-ml
+  - gpu
+  - blender
+  - pbs
+  - sunnie
+created: 2026-04-27
+updated: 2026-04-27
+---
+# Hunyuan3D-2 + Sunnie Animation Pipeline
+
+Self-hosted deployment of [Tencent Hunyuan3D-2](
+https://github.com/Tencent-Hunyuan/Hunyuan3D-2) on the Manjaro tower (RTX
+3080), feeding into a Blender pipeline to produce a dancing 3D version of
+Sunnie for PBS content.
+
+## Why Hunyuan3D-2 over InstantMesh
+
+For stylized characters, open-source models (Hunyuan, Trellis) preserve
+cartoon aesthetics better than commercial tools (Tripo, Meshy) that
+over-detail. Hunyuan3D-2 also outputs PBR textures (not just vertex
+colors), which matters once Sunnie hits Blender for re-lighting.
+InstantMesh stays in flight as a comparison data point.
+
+## Stack
+
+- **Host:** Manjaro tower (i7 / 128GB / RTX 3080, 10GB VRAM)
+- **Runtime:** Docker + NVIDIA Container Toolkit
+- **Model variant:** `Hunyuan3D-2mini` with `hunyuan3d-dit-v2-mini-turbo`
+subfolder (10GB VRAM-friendly)
+- **Required flags:** `--low_vram_mode --enable_flashvdm`
+- **UI:** Gradio on `:8080`
+- **Downstream:** Blender 4.x, Mixamo for auto-rig + dance animations
+
+## VRAM reality check
+
+The full `Hunyuan3D-2` model wants more than 10GB. The `mini-turbo` variant
++ low-VRAM flags is the target config for the 3080. If quality is
+unacceptable, fallbacks: rent an A100/4090 hour on RunPod for final-quality
+renders, or move workload to a future GPU upgrade.
+
+## Known issues
+
+- No official Tencent Docker image — community Dockerfiles only (referenced
+in repo issues #125, #122)
+- First-run model download is large (multiple GB across HuggingFace repos)
+— persist to host volume
+- Hunyuan3D-2.1 exists with better PBR but Docker support is rougher;
+deferring until 2.0 baseline works
+
+## Phase 1 — Deploy Hunyuan3D-2
+
+- [ ] Verify NVIDIA Container Toolkit: `docker run --rm --gpus all
+nvidia/cuda:12.4.0-base-ubuntu22.04 nvidia-smi`
+- [ ] Clone repo: `git clone
+https://github.com/Tencent-Hunyuan/Hunyuan3D-2.git ~/projects/hunyuan3d-2`
+- [ ] Write Dockerfile (community-style, base
+`nvidia/cuda:12.4.0-devel-ubuntu22.04`)
+- [ ] Build image: `docker compose build`
+- [ ] Create model cache dir: `mkdir -p ~/hunyuan3d-models`
+- [ ] First run: `docker compose up` — weights download to mounted volume
+- [ ] Verify Gradio UI at `http://localhost:8080`
+- [ ] Smoke test with sample image, save `.glb` output
+
+## Phase 2 — Sunnie mesh generation
+
+- [ ] Prepare Sunnie reference image (front-facing, transparent or white
+background, clean lines)
+- [ ] Generate mesh via Gradio UI
+- [ ] Export as `.glb` or `.obj` with PBR textures
+- [ ] Iterate prompt/source image until mesh is acceptable
+
+## Phase 3 — Blender cleanup
+
+- [ ] Import mesh into Blender 4.x
+- [ ] Inspect topology — likely needs decimate or retopo for clean rig
+deformation
+- [ ] Verify UV maps and PBR material assignment
+- [ ] Pose into T-pose if not already (Mixamo requirement)
+- [ ] Export as `.fbx` for Mixamo upload
+
+## Phase 4 — Rig + animate via Mixamo
+
+- [ ] Upload `.fbx` to Mixamo, place rigging markers
+- [ ] Verify auto-rig deformation
+- [ ] Pick dance animation from Mixamo library
+- [ ] Download rigged `.fbx` with skin + animation
+- [ ] Re-import to Blender, verify playback
+
+## Phase 5 — Final render
+
+- [ ] Set up Blender scene (lighting, camera, background)
+- [ ] Render dance sequence (Cycles or Eevee depending on quality target)
+- [ ] Export video for PBS use
+
+## docker-compose.yml (starting point)
+
+yaml
+services:
+  hunyuan3d:
+    build:
+      context: ./Hunyuan3D-2
+      dockerfile: Dockerfile
+    image: hunyuan3d-2:local
+    container_name: hunyuan3d
+    ports:
+      - "8080:8080"
+    volumes:
+      - ~/hunyuan3d-models:/root/.cache/hy3dgen
+      - ./outputs:/workspace/outputs
+    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
+    deploy:
+      resources:
+        reservations:
+          devices:
+            - driver: nvidia
+              count: all
+              capabilities: [gpu]
+    restart: unless-stopped
+
+
+## Open questions
+
+- [ ] If `mini-turbo` quality is insufficient for Sunnie, escalate to
+Hunyuan3D-2.1 (more VRAM-hungry, rougher Docker) or RunPod cloud GPU?
+- [ ] Reverse-proxy through Traefik on `*.lab.herbylab.dev`, or keep
+local-only?
+- [ ] Worth integrating with InstantMesh deploy for side-by-side mesh
+comparison?
+- [ ] Long-term: candidate tool for OpenClaw to call as a 3D-gen capability?
+
+## References
+
+- Hunyuan3D-2 repo: https://github.com/Tencent-Hunyuan/Hunyuan3D-2
+- Hunyuan3D-2.1 (newer, PBR-focused):
+https://github.com/Tencent-Hunyuan/Hunyuan3D-2.1
+- Docker discussion:
+https://github.com/Tencent-Hunyuan/Hunyuan3D-2/issues/125
+- Mixamo: https://www.mixamo.com
+- Companion project: `instantmesh-docker`
+
+
+...sent from Jenny & Travis