TRELLIS.2
Dataset & Modelmicrosoft/TRELLIS.2
State-of-the-art image-to-3D generative model with 4B parameters and O-Voxel representation.
Overview
TRELLIS.2 is a large 3D generative model for high-fidelity image-to-3D generation. It introduces a novel field-free sparse voxel structure called O-Voxel, enabling arbitrary topology handling and full PBR material modeling with 16x spatial downsampling.
README Preview
\n\n# Native and Compact Structured Latents for 3D Generation\n\n\n\n\n\n\n\nhttps://github.com/user-attachments/assets/63b43a7e-acc7-4c81-a900-6da450527d8f\n\n*(Compressed version due to GitHub size limits. See the full-quality video on our project page!)*\n\n**TRELLIS.2** is a state-of-the-art large 3D generative model (4B parameters) designed for high-fidelity **image-to-3D** generation. It leverages a novel "field-free" sparse voxel structure termed **O-Voxel** to reconstruct and generate arbitrary 3D assets with complex topologies, sharp features, and full PBR materials.\n\n\n## ✨ Features\n\n### 1. High Quality, Resolution & Efficiency\nOur 4B-parameter model generates high-resolution fully textured assets with exceptional fidelity and efficiency using vanilla DiTs. It utilizes a Sparse 3D VAE with 16× spatial downsampling to encode assets into a compact latent space.\n\n| Resolution | Total Time* | Breakdown (Shape + Mat) |\n| :--- | :--- | :--- |\n| **512³** | **~3s** | 2s + 1s |\n| **1024³** | **~17s** | 10s + 7s |\n| **1536³** | **~60s** | 35s + 25s |\n\n*Tested on NVIDIA H100 GPU.\n\n### 2. Arbitrary Topology Handling\nThe **O-Voxel** representation breaks the limits of iso-surface fields. It robustly handles complex structures without lossy conversion:\n* ✅ **Open Surfaces** (e.g., clothing, leaves)\n* ✅ **Non-manifold Geometry**\n* ✅ **Internal Enclosed Structures**\n\n### 3. Rich Texture Modeling\nBeyond basic colors, TRELLIS.2 models arbitrary surface attributes including **Base Color, Roughness, Metallic, and Opacity**, enabling photorealistic rendering and transparency support.\n\n### 4. Minimalist Processing\nData processing is streamlined for instant conversions that are fully **rendering-free** and **optimization-free**.\n* ** 📂 **Please refer to [data_toolkit/README.md](data_toolkit/README.md) for detailed instructions on data preprocessing and dataset organization.**\n\n### 2. Running Training\n\nTraining is managed through the `train.
FAQ (5)
TroubleshootingHow do I fix the alpha channel being ignored and the exported GLB appearing fully opaque in TRELLIS?
The GLB is exported with alphaMode='OPAQUE', which causes glTF viewers to ignore the texture's alpha channel. In o-voxel/o_voxel/postprocess.py, change the PBR material configuration to use alpha blending and a float baseColorFactor:
alpha_mode = 'BLEND'
material = trimesh.visual.material.PBRMaterial(
baseColorTexture=Image.fromarray(np.concatenate([base_color, alpha], axis=-1)),
baseColorFactor=np.array([1.0, 1.0, 1.0, 1.0], dtype=np.float32),
metallicRoughnessTexture=Image.fromarray(
np.concatenate([np.zeros_like(metallic), roughness, metallic], axis=-1)
),
metallicFactor=1.0,
roughnessFactor=1.0,
alphaMode=alpha_mode,
doubleSided=True if not remesh else False,
)Use 'MASK' instead of 'BLEND' if you want hard alpha cutouts rather than smooth transparency. Re-export the GLB after making the change.
As a manual workaround, import the existing GLB into Blender or another 3D tool and connect the base-color texture's alpha output to the material's Alpha/Opacity input; the alpha data is already present in the texture, but OPAQUE mode does not use it.
TroubleshootingHow do I fix "LLVM ERROR: Failed to compute parent layout for slice layout" on a V100 GPU?
This error occurs on pre-Ampere GPUs such as V100 (sm_70) with the default sparse convolution GEMM algorithm. Edit trellis2/modules/sparse/conv/config.py and change:
FLEX_GEMM_ALGO = 'masked_implicit_gemm_splitk'to:
FLEX_GEMM_ALGO = 'explicit_gemm'Then rerun the pipeline. Do not work around the crash by setting SPARSE_CONV_BACKEND=spconv, because that may stop the error but silently corrupt the generated output.
TroubleshootingWhy does Texture Flow Model training take tens of minutes to start while CPU usage is high?
The delay occurs because the run method in basic.py samples the training dataset before training begins. This CPU-bound preprocessing can take a long time, even with only 100 training samples. Reduce the num_samples setting used by the startup sampling process to make training begin faster.
TroubleshootingWhy does O-Voxel merge two nearby or disconnected components inside one voxel, and how can I reduce this artifact?
O-Voxel estimates only one dual vertex per primal voxel. When two surface components occupy the same cell, the QEF solution tends to average them, so the components may be merged. This is a known aliasing/topology limitation, not a robust handling of the extreme case. Workaround: extract or voxelize at a higher resolution, such as 1024³ or higher, so separate components are less likely to fall into the same voxel. There is no systematic fix in the current implementation.
TroubleshootingHow do I run TRELLIS 2 on Windows?
There is no confirmed native Windows setup in the issue, but users report these workarounds:
1. **Vision of Chaos (freeware)**: Use its working Windows implementation, reported for RTX 4090/5090. See the setup referenced in https://github.com/microsoft/TRELLIS.2/issues/4#issuecomment-3706875330
2. **ComfyUI integration**: For an RTX 3090, use https://github.com/visualbruno/ComfyUI-Trellis2
3. **Docker on Windows**: Run the containerized setup from https://github.com/camenduru/tostui?tab=readme-ov-file#-tostui---trellis-2
Choose the option matching your GPU; Docker is the most portable if the native or ComfyUI workflows fail.