Native MLX backend for TRELLIS.2 on Apple Silicon, with practical 1024^3 image-to-3D generation and textured GLB export.

Tested on a MacBook Pro with an M4 Max and 128 GB of unified memory.

TRELLIS.2 is Microsoft's 4B-parameter image-to-3D model. This project brings the generation pipeline to Apple Silicon with MLX model execution, Metal-accelerated processing, and a Gradio interface focused on usable high-resolution exports.

• Stable 1024^3 generation using chunked sparse texture sampling on MPS
• 512^3 dense MPS mode for faster generation with lower memory requirements
• Textured GLB export with base color, metallic, roughness, and alpha data
• Opaque material mode by default, avoiding the transparent point-cloud-like appearance produced by unintended alpha blending
• Fast Repair for conservative mesh cleanup without joining distant surfaces
• Optional Watertight Voxel Remesh at 384 or 512 grid resolution
• Topology diagnostics for watertightness, boundary edges, and non-manifold edges
• CPU dense fallback for 1024^3 texture sampling

Input image	GLB rendered in Blender

• Apple Silicon Mac (M-series)
• macOS
• Conda or Miniconda
• Python 3.10
• About 15 GB of free disk space for the TRELLIS.2 model weights

The current release was tested with 128 GB of unified memory. Lower-memory configurations may work, especially at 512^3, but have not been validated yet.

git clone https://github.com/gtrg55/trellis2-mlx.git
cd trellis2-mlx

conda create -n trellis2-mlx python=3.10 -y
conda activate trellis2-mlx

python -m pip install --upgrade pip setuptools wheel
python -m pip install "torch>=2.11.0" "torchvision>=0.26.0"
python -m pip install --no-build-isolation -r requirements_macos.txt
python -m pip install --no-build-isolation ./o-voxel

Download the official TRELLIS.2 weights:

python scripts/download_weights.py

The weights are stored in weights/TRELLIS.2-4B and are excluded from Git. The first launch may also download the image encoder and background-removal models from Hugging Face.

conda activate trellis2-mlx
python app_mlx.py

Open the local Gradio URL printed in the terminal.

For the best balance of speed and output quality:

Resolution 512 always uses dense MPS texture sampling. At resolution 1024, the UI provides experimental sparse MPS sampling and a slower dense CPU fallback.

The default mode. It merges coincident vertices, removes duplicate geometry and small disconnected fragments, fixes winding and normals, and closes simple holes. It deliberately avoids proximity-based welding, which could create long triangles between unrelated parts of a model.

Reconstructs the surface on a 384 or 512 voxel grid before UV unwrapping and texture baking. It is useful when a closed surface matters more than preserving every small geometric detail. It is slower and may smooth thin structures.

• Fast Repair does not guarantee a watertight or manifold mesh.
• Complex intersecting surfaces may retain visible seams or open boundaries.
• Watertight Voxel Remesh can smooth thin or highly detailed geometry.
• The TRELLIS.2 texture model can occasionally generate isolated color outliers.
• 1024^3 generation is compute-intensive and can take several minutes.
• Sparse MPS texture sampling is experimental.

The Gradio result panel reports boundary-edge and non-manifold-edge counts so export quality can be checked before using the asset downstream.

python -m unittest -v test_sparse_batched_sampling.py test_mesh_repair.py

The sparse sampler tests compare the MPS implementation against the original flex_gemm interpolation behavior.

• Microsoft TRELLIS.2 and the TRELLIS.2-4B model
• Pedro Naugusto for the foundational Apple Silicon and MLX port

This repository is released under the MIT License. Model weights and third-party dependencies may be subject to their own license terms.

Made with love for the Apple Silicon community.