From 49b1b4272c9573ca1fe48145700c836a46f05a1f Mon Sep 17 00:00:00 2001 From: herbygitea Date: Tue, 28 Apr 2026 01:29:31 +0000 Subject: [PATCH] Create hunyuan3d-sunnie-pipeline.md via n8n --- Tech/Projects/hunyuan3d-sunnie-pipeline.md | 158 +++++++++++++++++++++ 1 file changed, 158 insertions(+) create mode 100644 Tech/Projects/hunyuan3d-sunnie-pipeline.md diff --git a/Tech/Projects/hunyuan3d-sunnie-pipeline.md b/Tech/Projects/hunyuan3d-sunnie-pipeline.md new file mode 100644 index 0000000..b1bca91 --- /dev/null +++ b/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 \ No newline at end of file