TRELLIS.2-4B — GGUF quantizations (Lux3D)

Standalone GGUF builds of the TRELLIS.2-4B image-to-3D model (DINOv3 conditioning -> sparse-structure flow DiT -> shape SLAT flow DiT -> sparse VAE / O-Voxel dual-grid mesh, optional texture SLAT + PBR vertex colors), quantized from the canonical oxide-lab/TRELLIS.2-4B package by Lux3D.

Each file is a complete package: resolved_config.json is embedded in the GGUF metadata, so --model-path accepts the file directly. No sibling manifest.json, checksums.json or safetensors file is required.

Quantization policy (DiT-only)

TRELLIS.2 mixes two loader styles:

the five flow transformers (ss_flow, shape_dit_512, shape_dit_1024, tex_dit_512, tex_dit_1024) load every linear layer through Lux3D's nn_blocks::Linear, which keeps GGUF-packed weights in a QMatMul;
DINOv3 (image_cond), the sparse VAE decoders (shape_dec, tex_dec) and the dense structure decoder (ss_dec) read tensors as dense matrices (3D convolution kernels and layer norms), so quantizing them would only add dequantize overhead.

Only rank-2 *.weight matrices under the five DiT prefixes are therefore block-quantized; everything else (DINOv3, VAEs/decoders, convolution kernels, norms, biases, embeddings) stays in the F16 fallback. Per variant:

q8_0: 1074 of the 1075 DiT linear matrices quantized (ss_flow.input_layer.weight has row length 8 and cannot divide into 32-wide blocks);
q6_k / q5_k / q4_k: 1070 matrices (256-wide K-quant blocks also skip the four input_layer matrices with row length 32/64);
f16: straight precision conversion of every tensor, no QMatMul.

The GGUF container stores 3D convolution kernels (rank 5) as flat vectors; the Lux3D loaders reshape them after dequantization.

Files

file	dtype	size	status
`trellis2-f16.gguf`	F16 (all tensors)	14.50 GiB	maximum fidelity
`trellis2-q8_0.gguf`	Q8_0, F16 fallback	8.87 GiB	recommended
`trellis2-q6_k.gguf`	Q6_K, F16 fallback	7.41 GiB	usable
`trellis2-q5_k.gguf`	Q5_K, F16 fallback	6.61 GiB	usable
`trellis2-q4_k.gguf`	Q4_K, F16 fallback	5.86 GiB	most aggressive

Canonical package size: 15.07 GiB (mixed BF16/F16/F32, 4265 tensors). SHA-256 and exact byte sizes are in checksums.json.

Evaluation

Reference: the same CUDA backend (RTX 3060 12 GiB) running the canonical F32 package. Input: the mesh-input.png RGBA test image, 512 pipeline (sparse-structure + shape SLAT at 512), 12 Euler steps per sampler, seed 42, texture stages off, OBJ output. Metrics are drift against F32, not ground-truth accuracy: Chamfer-L1 relative to the reference bbox diagonal, F-score at 0.5%/1% of that diagonal, surface voxel IoU and normal consistency.

Measured on the same CUDA run (12 steps, seed 42, mesh-input.png):

variant	CD rel	F@0.5%	F@1%	voxel IoU	normal	vertices (ref 914,470)	infer wall
f16	0.0027%	0.9999	1.000	0.996	0.993	914,157	142.8 s
q8_0	0.187%	0.9139	0.9835	0.623	0.904	943,514	98.7 s
q6_k	0.199%	0.9181	0.9813	0.609	0.905	952,678	100.5 s
q5_k	0.274%	0.8839	0.9729	0.445	0.890	893,909	96.3 s
q4_k	0.311%	0.8331	0.9625	0.400	0.885	887,078	95.7 s

The F16 build is the fidelity reference: it reproduces the F32 mesh (914,470 vertices / 1,830,028 faces) almost exactly. Q8_0/Q6_K keep Chamfer drift near 0.19% of the bbox diagonal and F@1% around 0.98, but the O-Voxel dual-grid surface is discrete, so a small latent shift flips some voxel occupancies: surface voxel IoU (128^3 resample) lands around 0.61 with ~3% more/fewer vertices. That is topology drift, not positional drift — normals still agree at 0.90+. Q5_K/Q4_K are usable for previews (F@1% ≥ 0.96) with clearly visible topology drift (IoU 0.40–0.45); prefer Q8_0 for production. Standalone GGUF load is mmap-fast (<0.1 s to first tensor; the canonical safetensors package takes ~27 s of validation at startup).

Usage

# download one variant
hf download oxide-lab/TRELLIS.2-4B-GGUF trellis2-q8_0.gguf --local-dir .

# geometry preview (512 pipeline, OBJ)
lux3d-cli run trellis2 --device cuda \
  --model-path trellis2-q8_0.gguf \
  --source ./input.png \
  --output mesh.obj \
  --pipeline-type 512 --steps 12 --texture false --seed 42

# full quality: 1024 cascade with texture + PBR vertex colors (GLB + sidecar)
lux3d-cli run trellis2 --device cuda \
  --model-path trellis2-q8_0.gguf \
  --source ./input.png \
  --output mesh.glb

Mesh output dispatches on the extension: .glb (primary), .obj, .ply (no .stl for trellis2). Textured runs additionally write a <stem>.pbrvox.bin + <stem>.pbr.json sidecar pair with the 6-channel per-voxel PBR attributes. The input must carry a usable alpha channel: RMBG/BiRefNet background removal is not part of this pipeline, and RGB-only images are treated as fully opaque. Sequential stage loading keeps the 1024_cascade run inside ~8 GiB VRAM; CPU inference works but is slow.

Conversion

lux3d-cli weights quantize trellis2 \
  --source /path/to/canonical-trellis2/model.safetensors \
  --output trellis2-q8_0.gguf \
  --dtype q8_0 --fallback-dtype f16 \
  --prefix ss_flow. --prefix shape_dit_512. --prefix shape_dit_1024. \
  --prefix tex_dit_512. --prefix tex_dit_1024.

Build the canonical package first with lux3d-cli weights normalize --repo-root <runtime-root> --raw-model-dir <raw-TRELLIS.2-4B-dir> --output-dir <canonical-trellis2-dir> trellis2. The F16 build uses --dtype f16 --fallback-dtype f16 and no prefixes.

Limitations

Background removal (RMBG-2.0/BiRefNet) is excluded: supply RGBA inputs.
Texture atlas / UV unwrap is out of scope; PBR attributes are exported as vertex colors + sidecar, not a texture map.
Single-resolution 1024 sampling and the 1536 cascade are not implemented in Lux3D; use 512 or 1024_cascade.
One mesh per image (num_samples=1).
DINOv3 weights are embedded as distributed by the upstream TRELLIS.2-4B repository; DINOv3 itself is a separately licensed gated model (see LICENSE).

License

TRELLIS.2 code and weights are distributed by Microsoft under the MIT License; see LICENSE. The DINOv3 encoder bundled upstream is a separately licensed gated model — verify its terms before redistribution.