# The gallery was rendered by v0.4.3 and the newest tag is v0.8.1

> A C++ and GGML port of Microsoft's TRELLIS.2-4B image-to-3D pipeline with no Python at inference time, shipping a resident HTTP server, a Tauri desktop front end and one-command installers that pull about 16.5 GB of weights. MIT licensed, last pushed on 2026-09-25.

**pwilkin/trellis.cpp** — TRELLIS.2 image-to-3D in C++/GGML (CUDA + Vulkan), with a resident HTTP server

- Repository: https://github.com/pwilkin/trellis.cpp
- Stars: 329 · Forks: 37
- Language: C++
- License: MIT
- Published: 2026-09-18 · Updated: 2026-09-18 · Language: en
- Canonical page: https://hysenlabs.com/projects/pwilkin-trellis-cpp

## The gallery images were made by v0.4.3, four minor versions back

The gallery is described with unusual precision and one very stale number. Seven reconstructions, produced end to end by trellis.cpp v0.4.3, on a single Radeon 8060S, all at the 1024 cascade, seed 42, about 300 thousand faces, a 2048 squared atlas. Every parameter is pinned, which makes the provenance auditable and also freezes it in time. The newest tag is v0.8.1, published on 2026-09-25, so the pictures predate four minor releases. Nothing in the section says so. Two of the releases in between are named for changes that would plausibly alter output, one for CUDA geometry fixes and a more reliable background removal model, and another for a new backend and native quad retopology. A reader comparing the gallery to their own first run is comparing against a version that no longer exists on the releases page.

## Seven gallery anchors with nothing inside them

Below those parameters sit seven anchor elements, each pointing at a four-k resolution capture for one subject, and every one of them has an empty body. In a renderer that shows alt text there is nothing to show, and in one that does not there are seven unlabelled links in a row. The subjects are named only by their file paths: an axe, a chest, a cottage, a drone, a golem, a knight and a racer. The file does state that the models and their source images live in the directory of that name inside the repository, so the material exists and the reference to it does not render. The grid itself is described in more detail than the pictures: a 4096 by 4096 capture of four views, front, right, back and left at 75 degrees elevation at 2048 squared each, produced by a headless Playwright driver around a web component viewer, which serves a page, loads the model into a two by two grid of viewers, waits for automatic framing to settle, captures each view as a blob, and hands the pieces to a separate script that stitches the final image.

## The releases link resolves two levels above the repository

The paragraph announcing the prebuilt binaries contains one relative link, and it is the only relative link of its kind in the file. It points at the releases page through two levels of parent directories. Read from the repository root, which is where this file lives, that path climbs out of the repository entirely and lands somewhere on the hosting site that has nothing to do with the project. It would only resolve if the file were rendered from inside a subdirectory, which is the signature of a link written for a docs page and pasted into the root readme. Everything around it is absolute: the model weights on a model host, the reference implementation and the diffusion project on GitHub, the front end toolkit's own site. So the one link a new user is most apt to click is the one that does not work.

## Both installers pipe a script from the main branch straight into a shell

```bash
# Linux (x86-64)
curl -fsSL https://raw.githubusercontent.com/pwilkin/trellis.cpp/main/install/install.sh | bash
```

```powershell
# Windows (x64), in PowerShell
irm https://raw.githubusercontent.com/pwilkin/trellis.cpp/main/install/install.ps1 | iex
```

One line per platform, and both fetch a script over the network and hand it to an interpreter with no checksum, no pinned commit and no step in between. The URL points at the main branch, so the script that runs is whatever that branch holds at the moment you run it, which is not necessarily what the line said when you read it. What the script does is substantial: it detects whether you have CUDA, ROCm or Vulkan, downloads the matching server build, downloads roughly 16.5 GB of weights, writes a configuration file, and installs a desktop application. The file does describe each of those steps further down, but the install itself is the one thing offered without a way to inspect it first.

## The all-quad export is documented as absent from the prebuilt binaries

The optional path is the retopology route to an all-quad textured export, and it is enabled by two build options that have to be turned on at configure time. The file is explicit about who gets it: the prebuilt release binaries omit this optional path. So the feature exists, it is described down to its three numeric parameters, and it is reachable only by compiling. The parameters are the tetra remesh grid, an initial target for the decimation step where zero preserves the full shell, and a final target. Those three numbers appear in the example as 512, 0 and 900000. The configuration is reported as passing a full run on a Vulkan setup with a goblin subject, and a thin-feature humanoid with the same grid and no-weld preparation. One option in that list is not free: a dual material path requires a specific resolution pairing and decodes a second field at higher resolution when the lower one leaves holes in the atlas, at extra compute and storage.

## The Windows example creates one work directory and points at another

```bash
# Linux
cmake -S . -B build -DGGML_VULKAN=ON \
  -DTRELLIS_RETOPO_MATCHING=ON -DTRELLIS_RETOPO_COLLISION=ON
cmake --build build --target trellis-cli -j
mkdir -p out/retopo-work
TMPDIR="$PWD/out/retopo-work" ./build/trellis-cli assets/goblin.png out/goblin-quads.glb \
  --models /path/to/gguf --seed 42 --res 1024 --tex-res 512 \
  --retopo 512 0 900000 --retopo-no-weld-fill --retopo-dual-pbr \
  --retopo-atlas 4096 --retopo-workdir out/retopo-work
```

The Linux sequence prepares a scratch directory and then names that same directory twice, once as an environment variable and once as the work directory flag. The Windows sequence prepares out/retopo-work and then passes out/retopo-w as the work directory. Two names, one of them not created by the preceding line. The surrounding prose says the configuration was validated on Linux, which is the platform where the two names agree, so the Windows command is the untested copy. The same section also says building the command line tool builds the retopology driver and its helper executables, which is why the target name covers more than one binary.

## Two dependency mechanisms are declared and only one is described

The build section makes a strong claim about dependency handling: no separate dependency paths or installs are needed, because the build system fetches pinned sources for the matching and collision libraries itself, and additionally compiles two arbitrary precision libraries on Linux while Windows uses the geometry library's own multiprecision backend. The top-level listing complicates that. It contains a submodule configuration file and a third-party directory, which is the shape of a repository that vendors or references external code rather than fetching it at configure time. So there are two mechanisms present in the tree and the file describes only one. The consequence for a reader is specific: because versions are chosen by flags in a build script rather than by a lockfile, there is no single place to look to find out which revision of each dependency a given binary was built against.

## The app offers three resolutions and the command line documents two

The desktop app lists three resolution choices for its optional settings panel, described as light, cascade and high. The usage section documents the cascade as the default, explaining it as a low-resolution pass upsampled into a high-resolution pass and decoded, and it names the lighter path for the lowest setting. There is no third option in the command line documentation. The rest of the app's state has the same split character. Results are kept in a gallery held in the browser's own local database rather than as files on disk, which is why a thumbnail reload brings back the model, the input image and the settings after a restart, and why the same gallery is reachable from a plain browser against a server you started yourself. The configuration that decides which models directory, GPU and port to use comes from a file the installer writes, editable from a gear panel.

## Conclusion

trellis.cpp earns its place if you want image-to-3D without a Python environment, because the whole pipeline runs as a native server you can keep resident and point a script or a web front end at, and the desktop app supervises that server for you. It is the wrong choice if you want the all-quad textured export from a download, because that path is documented as source-only while the newest release is named for portable retopology builds, so read that line before you plan around it. It is also the wrong choice if 16.5 GB of weights and a driver-specific runtime are a problem, since the installer picks your GPU backend for you. Before you start, confirm your GPU runtime is one of the three it detects, decide whether the CLI or the web bundle is your front end, and check the retopology work directory on Windows, where the documented example creates one name and passes another.

## FAQ

### Can I run TRELLIS.2 locally without Python?

Yes. The whole pipeline, from background removal through the flow transformers, the decoders, mesh extraction and textured export, runs as native C++ against GGML with no Python at runtime, and the repository ships prebuilt Linux and Windows binaries for Vulkan, ROCm and CUDA. One helper script for rendering a quick multi-view preview is Python, and so is the script that stitches the four-view grids.

### Who owns TRELLIS.2 and what is this repository's relationship to it?

The model weights are Microsoft's TRELLIS.2-4B and the reference implementation is a separate Microsoft repository. pwilkin/trellis.cpp is an independent C++ and GGML port of that reference pipeline, and the file describes itself as a standalone implementation rather than an official one.

### How do I get the all-quad textured export from trellis.cpp?

By building from source with both retopology options enabled, because the file states the prebuilt release binaries omit this optional path. The Linux configure line turns on the Vulkan backend and the matching and collision options together, then builds the command line target, which also builds the retopology driver and its helpers.

### How much does the Trellis Studio installer download?

The matching server build plus roughly 16.5 GB of weights. The installer detects whether you have CUDA, ROCm or Vulkan, downloads the build that matches, writes a configuration file, and installs the desktop app, which then starts and supervises the server on launch.

### Which version produced the gallery images in the trellis.cpp readme?

Version 0.4.3, on a single Radeon 8060S, all at the 1024 cascade with seed 42, about 300 thousand faces and a 2048 squared atlas. The newest tag at the time of writing is v0.8.1, so the gallery predates four minor releases.

## Sources

- [Issues](https://github.com/pwilkin/trellis.cpp/issues)
- [License: MIT](https://github.com/pwilkin/trellis.cpp/blob/main/LICENSE)
- [pwilkin/trellis.cpp on GitHub](https://github.com/pwilkin/trellis.cpp)
- [README](https://github.com/pwilkin/trellis.cpp/blob/main/README.md)
- [Releases](https://github.com/pwilkin/trellis.cpp/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/pwilkin-trellis-cpp