Image → Mesh on Your Own Box: Turn 2D Assets into 3D GLBs with Hunyuan3D (macOS & Linux CPU)

Imagine a demand-gen platform of the future. The twist? The future is already here.

If you’ve got folders full of beautiful 2D creatives, there’s now a dead-simple way to reimagine them as 3D — locally, privately, and for free.

This post shows a working, minimal pipeline that takes any image and returns a downloadable GLB you can spin in the browser, drop into AR, or feed into your ad/commerce stack. No cloud accounts. No per-asset fees. Just a Flask app, a single 3D model (Hunyuan3D), and a clean UI powered by <model-viewer>.

What it does

• Upload an image → get a GLB (with vertex/face counts + file size).
• Works offline (Hugging Face hub disabled; weights loaded from disk).
• Runs on macOS (MPS) or Linux CPU (surprisingly usable for fast iterations).
• Modern viewer with camera controls, AR button, exposure slider, rotate toggle, and background switch.
• Robustness baked in (graceful retry if a scheduler step count gets frisky).

You’ll see a progress line like “Diffusion Sampling…” → “Exporting GLB…”, then a link to Download GLB and an instant preview in the page.

Why it’s useful

• Accelerate creative ops: repurpose existing 2D brand assets as lightweight, interactive 3D.
• E-commerce & ads: richer engagement, AR try-ons, 360° product spins — without a 3D artist every time.
• Own your pipeline: run behind the firewall; no data leaves your machine or server.

The stack (at a glance)

• Backend: Flask + Gunicorn (gevent), endpoints for job start, status, result, and secure asset serving.
• 3D generation: hy3dgen (Hunyuan3D DiT Flow Matching) — using the v2 mini weights by default.
• Viewer: Google’s <model-viewer> with camera controls, AR, exposure slider, and a simple toolbar.
• Storage: GLBs stored per-user; list view with stats (verts/faces/size).

Your core Python snippet handles device forcing (MPS/CPU), preloading the model from disk, and safe call semantics so the common off-by-one scheduler error auto-recovers.

How to run it locally (no subscriptions)

1) Clone & create a venv

python3 -m venv venv
source venv/bin/activate
pip install -U pip wheel
pip install -r requirements.txt

2) Put the Hunyuan3D model weights on disk (offline)

Folder layout expected by the code:

models/
└── Hunyuan3D-2mini/
    └── hunyuan3d-dit-v2-mini/
        ├── config.yaml
        └── model.fp16.safetensors

If you’ve already got the weights on another machine, copy them over in one go (adjust the SSH port as needed):

rsync -azP -e 'ssh -p 18021' \
  --rsync-path='mkdir -p /var/www/other/moved/flaboy.com/flaskapp/models/Hunyuan3D-2mini && rsync' \
  models/Hunyuan3D-2mini/ \
  root@yolo.cx:/var/www/other/moved/flaboy.com/flaskapp/models/Hunyuan3D-2mini/

Prefer downloading once and reusing the same local folder across environments — saves time and bandwidth.

3) Pick your device

• macOS with Apple Silicon: export HY3D_DEVICE=mps
• Linux (CPU-only): export HY3D_DEVICE=cpu

4) Run the app

FLASK_ENV=production gunicorn \
  --workers 1 \
  --worker-class gevent \
  --bind 127.0.0.1:5056 \
  wsgi:app

Visit: http://127.0.0.1:5056/image2mesh Drop in an image → Generate GLB → preview + download.

Model-viewer perks (built into the template)

• AR button (WebXR / Scene Viewer / Quick Look where supported)
• Auto-rotate toggle
• Reset camera to initial orbit
• Exposure slider to brighten/darken the scene
• Background toggle (black/white) for clean screenshots

Pro tip: swap environment-image to any studio HDR you like for different vibes. If you don’t want HDRs, drop the attribute to keep it neutral.

Performance notes

• MPS (macOS) is the sweet spot for developer iteration. It’s fast and doesn’t eat your discrete GPU drivers.
• CPU mode (Linux) is perfectly fine for back-office batch jobs and demos.
• Threading: torch.set_num_threads(1) makes the CPU runs more predictable under Gunicorn.
• Steps: the pipeline uses sensible defaults, and your _run_shape wrapper auto-retries with one fewer step if the scheduler ever tries to index past the last sigma.
• Point cloud size: the loader gently caps pc_size where available to keep memory in check.

Server ops tip: keep Gunicorn timeouts generous for CPU runs (e.g., --timeout 120), and don’t over-parallelize. One worker is often better than many when the heavy lift is inside a single inference.

Troubleshooting (quick hits)

• “Missing weights in …/Hunyuan3D-2mini/hunyuan3d-dit-v2-mini” Ensure the folder contains model.fp16.safetensors and config.yaml. The code runs offline (HF_HUB_OFFLINE=1).
• “Job not found” after it starts That usually means a worker restart or timeout killed the in-memory job map. Increase Gunicorn --timeout, and avoid restarting the service mid-job.
• Scheduler IndexError (e.g., size 13) Already handled by the _run_shape retry—no extra work needed.
• AR not showing That’s user-agent/platform dependent. The viewer auto-picks WebXR / Scene Viewer / Quick Look if available.

Privacy & control

• All inference runs locally; the code sets HF_HUB_OFFLINE=1.
• No outbound calls for generation.
• Access control on downloads (per-user check before serving GLBs).

Great screenshots to include

1. Generate tab mid-progress (“Diffusion Sampling… 42%”) with the blue bar.
2. Result preview in <model-viewer> with toolbar visible (exposure slider / rotate toggle).
3. List tab showing a few generated models with verts/faces/size + “Download GLB” links.

Where this goes next

• Batch ingest of an entire creative library.
• Automatic SKU → 3D previews in PDPs.
• Simple prompt + mask to guide geometry emphasis.
• Export to USDZ/Draco for lighter delivery.

TL;DR

A tiny Flask app + Hunyuan3D turns your 2D images into shareable GLB models — locally, on macOS (MPS) or Linux CPU. It’s fast to set up, private by default, and perfect for creative teams who want 3D without the overhead.

Gist

[embed]