Before you start
trellis.cpp reimplements the TRELLIS.2-4B image-to-3D pipeline in C++ on GGML. It removes the Python runtime, the CUDA-compiled custom extensions and the version pairing that breaks most AMD installs, and replaces them with prebuilt binaries and GGUF weights. That trade is the whole point: fewer moving parts, a separate implementation to verify against.
Prerequisites
- A GPU with a working CUDA, ROCm or Vulkan driver — Vulkan has the fewest prerequisites
- Disk space for GGUF weights: roughly 16.5 GB at f16, 9.5 GB at Q8, 6 GB at Q4
- A checksum tool, since releases publish SHA256 hashes
- A reference output from another route if you intend to compare fidelity
Step by step
Choose a backend before a download
CUDA for NVIDIA, ROCm for AMD on Linux or Windows, and Vulkan as the cross-vendor option that needs no compute stack installed. The project reports Vulkan as its fastest backend on some integrated GPUs, which makes it the sensible first try on Ryzen AI hardware rather than a fallback.
Verify the release archive
Releases ship SHA256 checksums. Check them. These are executable binaries running a model pipeline on your machine, and a hash comparison is the cheapest verification step available.
Pick a weight format
The default is f16 at roughly 16.5 GB. Q8 at roughly 9.5 GB is described by the project as visually near-lossless. Q4 at roughly 6 GB targets lower-VRAM systems and is described as showing slight texture graininess. The pipeline is split into components — the DINOv3 encoder, sparse-structure flow and decoder, shape flow at 512 and 1024, and texture flow and decoder — so a quantized set is several files, not one.
Run the CLI on a sample first
Every release archive includes the CLI binary. Use a supplied or simple sample image at default settings. A GPU flag is available to make the process fail loudly rather than silently fall back to CPU, which is documented as very slow and memory-hungry.
Decide between one-shot and resident
For repeated generation, the project ships an HTTP server that stays resident so the GPU is not reinitialized between requests. It exposes a health endpoint and a generate endpoint that accepts a multipart image upload with optional seed, resolution and background-removal fields. For a desktop workflow, the same pipeline is wrapped in the Trellis Studio application.
Known trade-offs
- This is an independent reimplementation, not the official pipeline; outputs will not be bit-identical to the reference implementation
- CPU fallback is documented as very slow and RAM-hungry — force GPU use rather than discovering this at runtime
- GGUF weights come from a community conversion; keep the original model licence and the conversion provenance together
- Prebuilt binaries execute on your machine — verify checksums and treat the release page as the only download source