README.md

---
license: mit
pipeline_tag: image-to-3d
tags:
  - image-to-3d
  - 3d-generation
  - mesh-generation
  - pbr
  - trellis
base_model:
  - microsoft/TRELLIS
---

# TRELLIS.2 4B — image-to-3D with PBR materials

Microsoft's TRELLIS.2 structured-latent 3D generator. **≈100 s** per asset on
an RTX 5090, and unlike most shape models it returns **material already baked
in** — no separate texturing pass.

> **What this repo is:** the TRELLIS.2 4B pipeline at FP16 — weights only, not
> a retrain. The samples below were generated with this build.

---

## Samples

Single image in, textured mesh out. Source images were rendered with Z-Image
Turbo; the meshes are Blender Workbench renders of the raw `.glb` — no
cleanup, no retopology, and **no separate paint stage**.

<table>
<tr><td><img src="https://huggingface.co/ChrisColeTech/TRELLIS.2-4B-FP16/resolve/main/samples/src-robot.png" width="330" alt="source photograph of a retro robot toy"></td><td><img src="https://huggingface.co/ChrisColeTech/TRELLIS.2-4B-FP16/resolve/main/samples/mesh-robot.png" width="330" alt="generated mesh with baked material"></td></tr>
<tr><td><sub>**source** — `a cute chunky retro robot toy standing upright, rounded metal body, simple friendly face, studio product photograph on a plain white background`</sub></td><td><sub>**mesh** — 26.3 MB `.glb`, generated in 98 s, seed 42</sub></td></tr>
<tr><td><img src="https://huggingface.co/ChrisColeTech/TRELLIS.2-4B-FP16/resolve/main/samples/src-teapot.png" width="330" alt="source photograph of a porcelain teapot"></td><td><img src="https://huggingface.co/ChrisColeTech/TRELLIS.2-4B-FP16/resolve/main/samples/mesh-teapot.png" width="330" alt="generated mesh with baked material"></td></tr>
<tr><td><sub>**source** — `an ornate ceramic teapot with a curved spout and handle, glazed blue and white porcelain, studio product photograph`</sub></td><td><sub>**mesh** — 26.3 MB `.glb`, seed 42</sub></td></tr>
</table>

### Turntable

Four views, 90° apart — the back is inferred, not copied from the source.

![robot turntable](https://huggingface.co/ChrisColeTech/TRELLIS.2-4B-FP16/resolve/main/samples/turntable-robot.png)

![teapot turntable](https://huggingface.co/ChrisColeTech/TRELLIS.2-4B-FP16/resolve/main/samples/turntable-teapot.png)

Note the level of preserved relief: the concentric ear knobs, the recessed
chest display, and the fastener detail across the back panel all survive, and
the surface reads as metal rather than flat clay because material comes out
with the geometry.

## Recommended settings

| Parameter | Production value | Meaning |
|---|---|---|
| `seed` | any | Deterministic per seed |
| input | one RGB(A) image | Centred subject, plain background |
| output | `.glb` | Mesh **with baked material** |

**Supported modes:** `img2mesh`, `txt2mesh`, and the `_textured` variants

### Notes and gotchas

- **Material comes for free.** `img2mesh` already returns a shaded mesh, so
  the separate paint stage other shape models need is unnecessary here. That
  is the main reason to pick TRELLIS.2 over a pure geometry model.
- **It is the slow tier** — ≈100 s versus ≈20–30 s for a 1.5B geometry-only
  model and ≈6 s for a 0.6B one. Use it for finals, not for iteration.
- **Sparse-conv backend.** The pipeline logs
  `[SPARSE] Conv backend: flex_gemm; Attention backend: flash_attn` on load
  and pulls a `valeoai/NAF` estimator from `torch.hub` the first time — the
  first run on a fresh machine needs network access and is slower.
- **Give the GPU to one model at a time.** At ≈4B plus sparse-conv working
  memory this wants the card to itself; sharing a GPU with another
  model-serving process produces failures that look like crashes rather than
  clean out-of-memory errors.
- Generated meshes come out facing the source image's front, so a fixed
  camera works across a batch.

---

## Provenance

- **Upstream base model:** [`microsoft/TRELLIS`](https://huggingface.co/microsoft/TRELLIS) family, TRELLIS.2 4B
- **This build:** FP16 redistribution of the TRELLIS.2 pipeline. Weights are not retrained here.
- **License:** MIT, per upstream.