项目简介
TRELLIS.2 是用于高保真图像转3D生成的大规模3D生成模型，引入名为 O-Voxel 的无场稀疏体素结构，支持任意拓扑和完整PBR材质建模，具备16倍空间下采样。
README 预览
\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.
常见问题 (5)
故障排除如何修复在 TRELLIS 中 Alpha 通道被忽略、导出的 GLB 显示为完全不透明的问题？
GLB 以 alphaMode='OPAQUE' 导出，这会导致 glTF 查看器忽略纹理的 alpha 通道。在 o-voxel/o_voxel/postprocess.py 中，将 PBR 材质配置修改为使用 alpha 混合和浮点型 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,
)如果需要硬边 alpha 裁剪效果而非平滑透明，请使用 'MASK' 替代 'BLEND'。修改完成后重新导出 GLB。
作为手动解决方案，可以将现有的 GLB 导入 Blender 或其他 3D 工具，并将基础颜色纹理的 alpha 输出连接到材质的 Alpha/Opacity 输入；alpha 数据已经存在于纹理中，只是 OPAQUE 模式不会使用它。
故障排除如何修复在 V100 GPU 上出现的 "LLVM ERROR: Failed to compute parent layout for slice layout" 错误？
此错误发生在 Ampere 架构之前的 GPU（如 V100 (sm_70)）上，使用的是默认的稀疏卷积 GEMM 算法。请编辑 trellis2/modules/sparse/conv/config.py，将：
FLEX_GEMM_ALGO = 'masked_implicit_gemm_splitk'改为：
FLEX_GEMM_ALGO = 'explicit_gemm'然后重新运行流水线。请勿通过设置 SPARSE_CONV_BACKEND=spconv 来绕过崩溃，因为这样虽然可能消除报错，但会静默损坏生成的输出。
故障排除为什么 Texture Flow Model 训练需要数十分钟才能启动，而 CPU 使用率很高？
出现延迟是因为 basic.py 中的 run 方法会在训练开始之前对训练数据集进行采样。这种受 CPU 限制的预处理可能需要很长时间，即使只有 100 个训练样本也不例外。减少启动采样过程所使用的 num_samples 设置，可以让训练更快开始。
故障排除为什么 O-Voxel 会将两个邻近或不相连的组件合并到同一个体素中？我该如何减少这种伪影？
O-Voxel 每个原始体素（primal voxel）仅估计一个对偶顶点（dual vertex）。当两个表面分量占据同一单元格时，QEF 解往往会将它们平均化，因此这些分量可能会被合并。这是一个已知的混叠/拓扑限制，而非对极端情况的稳健处理。变通方法：以更高的分辨率进行提取或体素化，例如 1024³ 或更高，这样分离的分量就不太可能落入同一体素中。当前实现中没有系统性的修复方案。
故障排除如何在 Windows 上运行 TRELLIS 2？
该 issue 中尚未有确认可行的原生 Windows 安装方案,但用户报告了以下变通方法:
1. Vision of Chaos(免费软件):使用其可正常运行的 Windows 实现,据报告适用于 RTX 4090/5090。请参阅 https://github.com/microsoft/TRELLIS.2/issues/4#issuecomment-3706875330 中提到的安装方法
2. ComfyUI 集成:对于 RTX 3090,使用 https://github.com/visualbruno/ComfyUI-Trellis2
3. 在 Windows 上使用 Docker:运行来自 https://github.com/camenduru/tostui?tab=readme-ov-file#-tostui---trellis-2 的容器化安装方案
请选择与你的 GPU 匹配的选项;如果原生或 ComfyUI 工作流程失败,Docker 是移植性最强的选择。