herbygitea/pbs-projects
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
49b1b4272c
pbs-projects/Tech/Projects/hunyuan3d-sunnie-pipeline.md

4.9 KiB
Raw Blame History

project type status path tags created updated
hunyuan3d-sunnie-pipeline project-plan active Tech/Projects
homelab
docker
ai-ml
gpu
blender
pbs
sunnie
2026-04-27 2026-04-27

Hunyuan3D-2 + Sunnie Animation Pipeline

Self-hosted deployment of Tencent 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

...sent from Jenny & Travis