TRELLIS.2

项目概述

TRELLIS.2 是一个面向图像到三维生成的大规模生成模型，参数量为 40 亿。它采用一种被称为 O-Voxel 的新型"无场"稀疏体素结构，能够对任意拓扑、复杂几何细节与完整 PBR 材质的三维资产进行高质量重建与生成。

核心特性

高分辨率与高效率

模型基于标准 DiT（Diffusion Transformer）架构，结合 16 倍空间下采样的稀疏三维 VAE，将资产编码到紧凑的潜空间中。在 NVIDIA H100 上的实测性能如下：

分辨率	总耗时	形状生成	材质生成
512³	约 3 秒	2 秒	1 秒
1024³	约 17 秒	10 秒	7 秒
1536³	约 60 秒	35 秒	25 秒

任意拓扑支持

O-Voxel 表示突破了传统等值面场的限制，可在不进行有损转换的前提下稳健处理开放曲面（如衣物、叶片）、非流形几何以及内部封闭结构。

丰富的材质建模

除基础颜色外，模型还可对表面属性进行建模，包括基础色、粗糙度、金属度与不透明度，从而实现照片级真实感渲染与透明效果支持。

极简处理流程

数据处理无需任何渲染或优化步骤。在单核 CPU 上完成纹理网格到 O-Voxel 的转换耗时低于 10 秒；在 CUDA 环境下，O-Voxel 回转到纹理网格仅需不到 100 毫秒。

技术架构

TRELLIS.2 依赖若干团队自研的高性能组件：

• O-Voxel：负责纹理网格与 O-Voxel 表示之间的双向即时转换。
• FlexGEMM：基于 Triton 的高效稀疏卷积实现，用于加速稀疏体素结构的处理。
• CuMesh：基于 CUDA 的网格处理工具集，提供网格简化、重网格化与 UV 展开等高速后处理能力。

模型权重 TRELLIS.2-4B 已发布于 Hugging Face 平台，支持 512³ 至 1536³ 分辨率范围的推理。

安装与环境要求

环境要求如下：

• 系统仅在 Linux 上经过测试；
• 至少配备 24GB 显存的 NVIDIA GPU（已在 A100 与 H100 上验证）；
• CUDA Toolkit 推荐使用 12.4 版本；
• Python 3.8 及以上，并建议使用 Conda 管理依赖。

克隆并初始化子模块：

git clone -b main https://github.com/microsoft/TRELLIS.2.git --recursive
cd TRELLIS.2

执行安装脚本，默认会自动创建 trellis2 Conda 环境，并安装 PyTorch 2.6.0、CUDA 12.4、flash-attention、nvdiffrast、nvdiffrec、cumesh、o-voxel 与 flexgemm 等依赖：

. ./setup.sh --new-env --basic --flash-attn --nvdiffrast --nvdiffrec --cumesh --o-voxel --flexgemm

若 GPU 不支持 flash-attention（例如 V100），可手动安装 xformers，并通过设置环境变量 ATTN_BACKEND=xformers 切换后端。

推理用法

图像到三维生成

下面示例展示如何使用预训练模型从单张图像生成带 PBR 材质的网格资产，并导出 GLB 文件：

import os
os.environ['OPENCV_IO_ENABLE_OPENEXR'] = '1'
os.environ["PYTORCH_CUDA_ALLOC_CONF"] = "expandable_segments:True"

from PIL import Image
from trellis2.pipelines import Trellis2ImageTo3DPipeline
from trellis2.utils import render_utils
from trellis2.renderers import EnvMap
import o_voxel

# 加载环境贴图
envmap = EnvMap(torch.tensor(cv2.cvtColor(...), dtype=torch.float32, device='cuda'))

# 加载推理管线
pipeline = Trellis2ImageTo3DPipeline.from_pretrained("microsoft/TRELLIS.2-4B")
pipeline.cuda()

# 从图像生成网格
image = Image.open("assets/example_image/T.png")
mesh = pipeline.run(image)[0]
mesh.simplify(16777216)  # 受 nvdiffrast 顶点上限约束

# 渲染预览视频
video = render_utils.make_pbr_vis_frames(render_utils.render_video(mesh, envmap=envmap))
imageio.mimsave("sample.mp4", video, fps=15)

# 导出带 PBR 材质的 GLB
glb = o_voxel.postprocess.to_glb(
    vertices=mesh.vertices, faces=mesh.faces,
    attr_volume=mesh.attrs, coords=mesh.coords,
    attr_layout=mesh.layout, voxel_size=mesh.voxel_size,
    aabb=[[-0.5, -0.5, -0.5], [0.5, 0.5, 0.5]],
    decimation_target=1000000, texture_size=4096,
    remesh=True, remesh_band=1, remesh_project=0, verbose=True
)
glb.export("sample.glb", extension_webp=True)

执行脚本后会生成 sample.mp4（带环境光照的 PBR 渲染视频）和 sample.glb（可直接用于三维软件的资产文件）。GLB 默认以不透明模式导出，纹理通道中保留的 alpha 信息可在三维软件中手动连接至材质的透明度输入。

启动 Web 演示界面：

python app.py

形状条件纹理生成

可参考 example_texturing.py 为已有三维形状生成 PBR 纹理，或运行 app_texturing.py 启动对应的 Web 演示。

训练

项目提供了完整训练代码，支持从零训练或在自定义数据集上进行微调。训练前需将原始三维资产转换为 O-Voxel 表示，具体预处理流程详见 data_toolkit/README.md。

训练入口为 train.py，常用参数包括 --config（实验配置文件）、--output_dir（输出目录）、--data_dir（数据集路径或 JSON 字符串）、--num_gpus、--num_nodes 等。训练包含四个主要阶段：

1. 形状 SC-VAE：使用 configs/scvae/shape_vae_next_dc_f16c32_fp16.json 在 Objaverse-XL 上训练，并通过 *_ft_512.json 配置进行高分辨率微调。
2. 纹理 SC-VAE：使用 configs/scvae/tex_vae_next_dc_f16c32_fp16.json 进行训练。
3. 稀疏结构流模型：使用 configs/gen/ss_flow_img_dit_1_3B_64_bf16.json 训练。
4. 形状与纹理流模型：分别使用 slat_flow_img2shape_dit_1_3B_512_bf16.json 与 slat_flow_imgshape2tex_dit_1_3B_512_bf16.json，并可借助 *_ft1024.json 配置进行更高分辨率的微调。

下方为稀疏结构流模型的训练命令示例：

python train.py \
  --config configs/gen/ss_flow_img_dit_1_3B_64_bf16.json \
  --output_dir results/ss_flow_img_dit_1_3B_64_bf16 \
  --data_dir "{\"ObjaverseXL_sketchfab\": {\"base\": \"datasets/ObjaverseXL_sketchfab\", \"ss_latent\": \"datasets/ObjaverseXL_sketchfab/ss_latents/ss_enc_conv3d_16l8_fp16_64\", \"render_cond\": \"datasets/ObjaverseXL_sketchfab/renders_cond\"}}"

许可证

TRELLIS.2 模型与代码以 MIT 协议发布。需要注意的是，第三方依赖 nvdiffrast 与 nvdiffrec 分别遵循各自独立的许可条款。