trellis.cpp: TRELLIS.2 image-to-3D as a native C++/GGML pipeline with a desktop app

What trellis.cpp ports, and why that matters

TRELLIS.2 is Microsoft's image-to-3D model, and trellis.cpp is a standalone C++ implementation of the whole pipeline on top of GGML. The README lists what it covers: background removal, image conditioning, the three flow transformers, the VAE decoders, mesh extraction and UV-textured GLB export, all in native C++ with no Python at runtime. It ports the reference implementation at microsoft/TRELLIS.2 and targets the TRELLIS.2-4B weights. Builds are published for Linux and Windows across Vulkan, ROCm and CUDA, and the project serves as the trellis backend of Lemonade. If you have used the Python reference and wanted it to run as a single binary on your own GPU, that is the gap this fills.

From a flat image to a UV-textured GLB

The default path is the 1024 cascade: a low resolution flow_512 pass, an upsample, a high resolution flow_1024 pass, then a res-1024 decode, which the README says gives sharper geometry. Passing --res 512 selects the lighter res-512 path with no cascade, and 1536 is offered as a high option in the desktop app. Before the transformers run, the subject is separated from its background. The --bg-removal flag defaults to auto, so pre-matted images keep their alpha and everything else gets a BiRefNet matte that the README puts at roughly 13 seconds on a GPU. The threshold keyer is opt-in only, because a plain white-background keyer cuts specular highlights out of the alpha and the flow then generates holes there. After decoding, the postprocess is described as matching the reference op for op: the raw dual-grid mesh is welded and hole-filled, remeshed with narrow-band UDF dual contouring into a single clean manifold, quadric-simplified to the face budget, clustered with the reference bottom-up normal-cone merge, unwrapped with stock xatlas per cluster, and shaded per texel by trilinear sampling of the voxel PBR volume.

Installing Trellis Studio on Linux and Windows

New users are pointed at Trellis Studio, a Tauri desktop app that a one-command installer sets up. The installer auto-detects your GPU runtime across CUDA, ROCm and Vulkan, downloads the matching trellis-server build plus roughly 16.5 GB of weights, and installs the app, which then starts and supervises the server for you.

curl -fsSL https://raw.githubusercontent.com/pwilkin/trellis.cpp/main/install/install.sh | bash

The README gives the Windows equivalent in PowerShell.

irm https://raw.githubusercontent.com/pwilkin/trellis.cpp/main/install/install.ps1 | iex

Inside the app you add an image by drag-and-drop, by browsing, or by pasting from the clipboard, optionally set resolution, seed, background removal and UV unwrap, then generate, which the README says takes a few minutes with a live stage line showing progress. Results land in a local gallery backed by IndexedDB, so clicking a thumbnail reloads the model, its input image and its settings even after a restart. The desktop app is not the only way in: the UI is a plain web bundle you can open in a browser against a trellis-server you started yourself, and portable archives unzip anywhere, keep configuration and generated GLBs in ./data/ next to the app, and auto-detect a ./runtime/ server with ./models/ weights.

The CLI and the flags that change the result

For scripted use the project ships a CLI binary, and since v0.5.4 every release archive includes trellis-cli alongside trellis-server.

./build/trellis-cli assets/goblin.png out/goblin.glb
python tools/render_glb.py out/goblin.glb out/view.png

The first line turns an image into a UV-textured GLB with an atlas and PBR materials, and the second renders a quick multi-view preview PNG from it. Resolution is --res 512, 1024 or 1536, and --no-texture drops the texture work for geometry only. Geometry controls are --decim GRID for the legacy cluster-grid decimation, which is otherwise replaced by a quadric simplify to 300K faces at 1024 and 150K at 512 with 0 keeping the full-resolution mesh, and --atlas PX for the UV atlas size, defaulting to 2048 at 1024 and 1024 at 512. --box-uv swaps the default xatlas unwrap for a voxel-native six-way box projection that scales with face count and is faster but packs more loosely. --seed N fixes the RNG, and --require-gpu makes the run fail instead of falling back to what the README calls a very slow, RAM-hungry CPU path.

trellis-cli --help

The release notes add flags the README table does not list: --webp on|off for the texture format, --dump-bg and --bg-only for writing or stopping at the background-removal cutout, and --band for overriding the narrow-band remesh offset.

Weight size is the real hardware constraint

The default weights are f16 at about 16.5 GB, which is the number that decides whether this runs on your machine at all. The installer gained --quant q8 and --quant q4 for lower-VRAM cards. The release notes put q8 at roughly 9.5 GB and describe it as visually near-lossless, and q4 at about 6 GB as still good with slight texture graininess. The quantized weights live under q8/ and q4/ in the Hugging Face repository and tools/quantize_gguf.py reproduces them, so you can build your own rather than trusting the published files. v0.6.0 also added separate cuda12 packages built with CUDA 12.9 for Pascal and Volta GPUs at compute capability 6.0, 6.1 and 7.0, including cards such as the Tesla P100, with the Linux and Windows installers detecting those cards.

Failure modes the release notes document

This project is below 1.0 and the release notes are unusually direct about what has been broken. The v0.5.4 CUDA build produced severe holes and corrupted geometry, fixed in v0.6.0 by power-of-two scaling FlashAttention values around the tensor-core path, pinning a GGML revision with 64-bit mask strides for attention masks larger than 2 GiB, and making sparse subdivision detect non-finite or empty results and retry or fail with a diagnostic instead of silently producing a broken mesh. Before that, v0.5.4 fixed res-1024 speckle, where the decoder's outer-skin noise survived as a cloud of floating speckles because the narrow-band remesh offset did not scale with resolution. BiRefNet stretched non-square inputs until v0.6.0 resized the predicted matte back to the original image dimensions before cropping, and it now evaluates its final high-resolution convolutions in bounded-height stripes to cut peak allocations. One more, worth knowing before you trust the app: the packaged preview was broken from v0.5.0 to v0.5.3 because the content security policy blocked model-viewer from fetching a blob URL, and a preview error could discard a generation that had already succeeded.

The Python reference is the other option

The obvious alternative is the reference implementation at microsoft/TRELLIS.2 that this ports. Running that means a Python environment with PyTorch and the model's own dependencies, and it is where new research and new model versions land first. trellis.cpp gives up that immediacy for a native binary with no Python at runtime, prebuilt packages, a resident HTTP server and a desktop app, which matters more if you are generating assets on a workstation than if you are experimenting in a notebook. There is also a text-prompt route: the README notes that trellis.cpp can be driven end-to-end from a prompt with stable-diffusion.cpp producing the input image, chaining two GGML projects and keeping the whole thing off Python.

Licence, backends and upgrade cost

trellis.cpp is MIT licensed and written in C++. The last push was on 2026-08-31 and the newest release in the notes is v0.6.0, published on 2026-08-19, with v0.5.4 on 2026-07-27 and v0.5.3 on 2026-07-21 before it, so releases have been arriving every few weeks. The repository carries a .gitmodules file, so a recursive clone is part of building from source, and there is a ROADMAP.md at the root. The version is still 0.6.0 and the release notes are dominated by geometry and backend fixes, which is the honest signal here: the full pipeline is implemented and usable, and the GPU backends are still being made to agree with each other. If you depend on it for production assets, pin a release and archive the GLBs it produced.

Editorial conclusion

Use trellis.cpp if you want image-to-3D running as a local binary on your own GPU and you would rather not maintain a Python environment, and start with Trellis Studio so the installer picks the backend and pulls the weights for you. Do not treat it as an unattended production generator yet, because v0.6.0 exists mainly to fix severe CUDA geometry holes from v0.5.4 and the version is still 0.6.0. Decide the weights before you install: if your card cannot hold the 16.5 GB f16 default, install with --quant q8 at about 9.5 GB rather than letting a run fall back to the CPU path, which the README describes as very slow and RAM-hungry.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. pwilkin/trellis.cpp on GitHub
4. README
5. Releases