Trellis2 Apple MLX Image to 3D

This is the middle of the Trellis2Apple chain: pipeline in one side, your image in the other, and a 3D mesh out. It's the node that actually does image-to-3D, and on a Mac it's quietly remarkable - standard TRELLIS.2 won't run on Apple Silicon at all (CUDA-hardcoded, nvidia wheels that can't build on arm64), so this MLX backend is one of the few real paths to running Microsoft's TRELLIS.2 locally on an M-series chip.

If you're new to 3D generation, the 30-second map: image-to-3D is the part that works today, and TRELLIS.2 is the technically elegant option - MIT-licensed, uses a compact sparse-voxel latent called O-Voxel, and in ComfyUI's 3D world it's the clean second fiddle to Hunyuan3D. The catch everyone has to hear once: the geometry you get is triangle soup, not rig-ready topology. Great for static props, background filler, and 3D printing; expect to retopo if you need it to animate.

How it works

The node hands your image to the trellis2-apple MLX backend, which runs generation in three stages - sparse structure, shape slat, then texture slat - at 12 steps each with guidance 7.5 / 7.5 / 1.0. Those are the "simple mode" defaults the author smoke-tested, and they're deliberately the safe settings. No sampler knobs here; that's what the Advanced sibling node is for.

The inputs that matter

• pipeline - wire in the pipeline output from Trellis2AppleLoader.
• image - any IMAGE, e.g. straight from LoadImage. Clean subject, simple background, object roughly centered: that's the sweet spot for image-to-3D.
• seed - defaults to 42. Same seed + same image = same mesh, so set it when you want to reproduce a result or compare tweaks.
• pipeline_type - the one you'll actually change:
  • 512 - fast - the direct-tested default and where you should start. Fastest, safest.
  • 1024_cascade - higher quality - bigger pipeline, better detail, slower and hungrier.
  • 1536_cascade - experimental - exactly what it says on the tin. Expect rougher edges.

The output, mesh (type TRELLIS2_APPLE_MESH), feeds the mesh input of Trellis2AppleExport. The graph is four nodes long: LoadImage → Trellis2AppleLoader → this → Trellis2AppleExport → Preview3D.

Installing it

The pack is a symlink-plus-installer situation, not Manager:

git clone https://github.com/pedronaugusto/trellis2-apple /path/to/trellis2-apple
ln -s /path/to/ComfyUI-Trellis2Apple /path/to/ComfyUI/custom_nodes/ComfyUI-Trellis2Apple
/path/to/ComfyUI/.venv/bin/python custom_nodes/ComfyUI-Trellis2Apple/install.py \
  --trellis2-apple /path/to/trellis2-apple --download-weights
/path/to/ComfyUI/.venv/bin/python custom_nodes/ComfyUI-Trellis2Apple/doctor.py

Run everything with ComfyUI's own Python, and expect the install to be heavy: mlx, o-voxel, and three Metal packages compiled from source. Restart after, then check doctor.py for a clean bill before you blame the node.

Troubleshooting

• It's slow. You're running a 4B model on local hardware. "A few minutes per render" is the honest range; step down to 512 - fast if you're waiting forever.
• Crashing / out of memory. These Apple ports are memory-hungry - community reports on the Mac port family put the comfortable floor around 24 GB of unified memory. Drop to the 512 pipeline and smaller export settings before buying new hardware.
• You can't tune guidance. Correct - the simple node hides the sampler params on purpose. Use Trellis2AppleGenerateAdvanced when the defaults aren't giving you what you want.
• Ugly topology. Not a bug. That's every image-to-3D model right now. If it's for a print or a static prop, send it; if it must deform, budget for cleanup.

If you're on a Windows box with an NVIDIA card, you don't need any of this - standard TRELLIS.2 wrappers will serve you better. This pack exists for the people CUDA forgot.