Hunyuan3D-2.2-mrp-MLX

One-command image → textured 3D on Apple Silicon. A tuned, packaged build of Tencent's Hunyuan3D 2.1, running natively on Mac GPUs via Apple MLX — no NVIDIA, no CUDA, no cloud.

python generate_e2e.py your_image.png --output out/mymesh
# → out/mymesh.glb   (PBR-textured mesh)  +  out/mymesh_shape.glb (untextured)

---

What this is (provenance & credit)

A fork of a fork — three layers, credited honestly:

1. Tencent Hunyuan3D 2.1 — the actual models: Hunyuan3D-Shape-v2-1 (3.3B, image→mesh) + Hunyuan3D-Paint-v2-1 (2B, PBR texture). Originally CUDA/NVIDIA only.
2. dgrauet/Hunyuan3D-2.1-mlx — the hard part: a native MLX (Metal) port of both stages. fp16, no bf16 dependency → runs on any Apple Silicon Mac (M1–M5). This is what made it work on a Mac at all.
3. This build (MODELBEAST / mrp) — the usability + tuning layer on top of dgrauet (below).

What we added over upstream

• generate_e2e.py — a single command chaining Stage 1 (shape) → Stage 2 (PBR texture). Upstream only shipped a test script. Flags: --steps --guidance --octree-resolution --max-num-view --view-resolution --texture-size --remesh-faces --seed --no-texture; prints per-stage timings + peak memory.
• Env-tunable bake mesh — HY3D_REMESH_FACES (upstream hard-coded 40k). The single biggest quality lever — it's what un-melts faces.
• Studio-quality defaults — octree 384 / texture 4096 / remesh 120k, verified watchdog-free on M3 and M1 Ultra. Upstream capped texture at 2048 because laptop GPUs hit a Metal command-buffer limit; Studio-class GPUs don't, and the existing tiling handles 4096².
• HARDWARE.md — exact RAM needs per precision and per Mac.
• Slimmed for inference — upstream training data (mini_trainset) + demo images stripped (~165 MB → ~9 MB). Recover any time via git fetch upstream (github.com/dgrauet).

Quick start

Python 3.11 (the ML stack pins old numpy; 3.12+ won't build it).

uv venv --python 3.11 .venv && source .venv/bin/activate      # or: python3.11 -m venv .venv
uv pip install mlx mlx-arsenal torch torchvision transformers timm \
  huggingface_hub safetensors numpy scipy scikit-image PyMCubes \
  trimesh pygltflib xatlas opencv-python pillow pymeshlab \
  einops omegaconf pyyaml tqdm torchdiffeq diffusers accelerate fast_simplification

export HF_HUB_DISABLE_XET=1
python generate_e2e.py your_image.png --output out/mymesh

Weights (~13 GB, fp16 MLX, public — no HF login) auto-download on first run from dgrauet/hunyuan3d-2.1-mlx. Override with HUNYUAN3D_MLX_WEIGHTS_DIR. Best results: feed a background-removed cutout.

Quality vs speed (generate_e2e.py flags)

	fast draft	default (studio)	max
--texture-size	2048	4096	4096
--remesh-faces	40000	120000	200000
--octree-resolution	256	384	384
--max-num-view	6	6	8–12
time (M3 Ultra)	~260 s	~380 s	longer
output	7.6 MB / 40k faces	21.5 MB / 120k faces	larger

--no-texture = Stage 1 only (geometry, ~2.5 min, ~10 GB RAM).

Hardware (full table in HARDWARE.md)

Peak ~20 GB fp16 for the full textured pipeline (measured). Min 16 GB (INT8/INT4) or 24 GB (fp16, tight) · 32 GB recommended. Any M1→M5 — fp16-MLX path, no bf16 gotcha.

Measured full textured gen: M3 Ultra ~380 s, M1 Ultra ~750 s (4096 / 120k).

⚠️ License

Inherits the Tencent Hunyuan Non-Commercial License (see LICENSE / Notice.txt). Non-commercial use only — share and use accordingly.

Credits

Tencent Hunyuan3D team (models) · @dgrauet (MLX port) · MODELBEAST (this build). Original upstream README preserved as README_UPSTREAM.md.