（受 GitHub 大小限制，此处为压缩版本。完整画质的视频请查看我们的项目页面！）

TRELLIS.2 是一个先进的大型 3D 生成模型（拥有 40 亿参数），专为高保真图像到 3D 生成而设计。它采用一种名为 O-Voxel 的新型“无场”稀疏体素结构，可以重建和生成具有复杂拓扑、锐利特征以及完整 PBR 材质的任意 3D 资产。

1. 高质量、高分辨率与高效率

我们的 40 亿参数模型使用标准 DiT，以卓越的保真度和效率生成高分辨率、完整纹理的资产。该模型采用具有 16 倍空间下采样能力的稀疏 3D VAE，将资产编码到紧凑的潜在空间中。

*在 NVIDIA H100 GPU 上测试。

2. 支持任意拓扑

O-Voxel 表示突破了等值面场的限制。它能够稳健地处理复杂结构，无需进行有损转换：

✅ 开放曲面（例如服装、树叶）

✅ 非流形几何体

✅ 内部封闭结构

3. 丰富的纹理建模

除基础颜色外，TRELLIS.2 还可以建模任意表面属性，包括基础色、粗糙度、金属度和不透明度，从而支持照片级真实感渲染以及透明效果。

4. 极简处理流程

数据处理流程经过精简，可实现即时转换，全程无需渲染和优化。

< 10 秒（单 CPU）：纹理网格 → O-Voxel

< 100 毫秒（CUDA）：O-Voxel → 纹理网格

发布图像到 3D 推理代码

发布预训练检查点（40 亿参数）

Hugging Face Spaces 演示

发布以形状为条件的纹理生成推理代码

发布训练代码

系统：该代码目前仅在 Linux 上完成测试。

硬件：需要至少配备 24GB 显存的 NVIDIA GPU。该代码已在 NVIDIA A100 和 H100 GPU 上验证。

软件：编译某些软件包需要 CUDA Toolkit，推荐版本为 12.4。建议使用 Conda 管理依赖项。需要 Python 3.8 或更高版本。

编译某些软件包需要 CUDA Toolkit，推荐版本为 12.4。

建议使用 Conda 管理依赖项。

需要 Python 3.8 或更高版本。

克隆仓库：git clone -b main https://github.com/microsoft/TRELLIS.2.git --recursive cd TRELLIS.2

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

安装依赖项：运行以下命令前有一些注意事项：添加 --new-env 后，将创建一个名为 trellis2 的新 Conda 环境。如果要使用现有的 Conda 环境，请移除此标志。默认情况下，trellis2 环境将使用搭配 CUDA 12.4 的 pytorch 2.6.0。如果要使用其他版本的 CUDA，可以移除 --new-env 标志并手动安装所需依赖项。安装命令请参考 PyTorch。如果安装了多个 CUDA Toolkit 版本，应在运行命令前将 CUDA_HOME 设置为正确版本。例如，如果安装了 CUDA Toolkit 12.4 和 13.0，可以在运行命令前执行 export CUDA_HOME=/usr/local/cuda-12.4。默认情况下，代码使用 flash-attn 作为注意力后端。对于不支持 flash-attn 的 GPU（例如 NVIDIA V100），可以手动安装 xformers，并在运行代码前将 ATTN_BACKEND 环境变量设置为 xformers。更多细节请参阅最小示例。由于依赖项数量众多，安装可能需要一段时间，请耐心等待。如果遇到问题，可以尝试逐一安装依赖项，每次只指定一个标志。如果安装过程中遇到任何问题，欢迎提交 issue 或联系我们。创建名为 trellis2 的新 Conda 环境并安装依赖项：. ./setup.sh --new-env --basic --flash-attn --nvdiffrast --nvdiffrec --cumesh --o-voxel --flexgemm 运行 . ./setup.sh --help 可查看 setup.sh 的详细用法。用法：setup.sh [OPTIONS] 选项：-h, --help 显示此帮助信息 --new-env 创建新的 Conda 环境 --basic 安装基础依赖项 --flash-attn 安装 flash-attention --cumesh 安装 cumesh --o-voxel 安装 o-voxel --flexgemm 安装 flexgemm --nvdiffrast 安装 nvdiffrast --nvdiffrec 安装 nvdiffrec

安装依赖项：

运行以下命令前有一些注意事项：

添加 --new-env 后，将创建一个名为 trellis2 的新 Conda 环境。如果要使用现有的 Conda 环境，请移除此标志。

默认情况下，trellis2 环境将使用搭配 CUDA 12.4 的 pytorch 2.6.0。如果要使用其他版本的 CUDA，可以移除 --new-env 标志并手动安装所需依赖项。安装命令请参考 PyTorch。

如果安装了多个 CUDA Toolkit 版本，应在运行命令前将 CUDA_HOME 设置为正确版本。例如，如果安装了 CUDA Toolkit 12.4 和 13.0，可以在运行命令前执行 export CUDA_HOME=/usr/local/cuda-12.4。

默认情况下，代码使用 flash-attn 作为注意力后端。对于不支持 flash-attn 的 GPU（例如 NVIDIA V100），可以手动安装 xformers，并在运行代码前将 ATTN_BACKEND 环境变量设置为 xformers。更多细节请参阅最小示例。

由于依赖项数量众多，安装可能需要一段时间，请耐心等待。如果遇到问题，可以尝试逐一安装依赖项，每次只指定一个标志。

如果安装过程中遇到任何问题，欢迎提交 issue 或联系我们。

创建名为 trellis2 的新 Conda 环境并安装依赖项：

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

运行 . ./setup.sh --help 可查看 setup.sh 的详细用法。

Usage: setup.sh [OPTIONS]
Options:
    -h, --help              Display this help message
    --new-env               Create a new conda environment
    --basic                 Install basic dependencies
    --flash-attn            Install flash-attention
    --cumesh                Install cumesh
    --o-voxel               Install o-voxel
    --flexgemm              Install flexgemm
    --nvdiffrast            Install nvdiffrast
    --nvdiffrec             Install nvdiffrec

📦 预训练权重

预训练模型 TRELLIS.2-4B 已在 Hugging Face 上提供。更多细节请参阅其中的模型卡片。

1. 图像到 3D 生成

以下示例展示了如何使用预训练模型生成 3D 资产。

import os
os.environ['OPENCV_IO_ENABLE_OPENEXR'] = '1'
os.environ["PYTORCH_CUDA_ALLOC_CONF"] = "expandable_segments:True"  # Can save GPU memory
import cv2
import imageio
from PIL import Image
import torch
from trellis2.pipelines import Trellis2ImageTo3DPipeline
from trellis2.utils import render_utils
from trellis2.renderers import EnvMap
import o_voxel

# 1. Setup Environment Map
envmap = EnvMap(torch.tensor(
    cv2.cvtColor(cv2.imread('assets/hdri/forest.exr', cv2.IMREAD_UNCHANGED), cv2.COLOR_BGR2RGB),
    dtype=torch.float32, device='cuda'
))

# 2. Load Pipeline
pipeline = Trellis2ImageTo3DPipeline.from_pretrained("microsoft/TRELLIS.2-4B")
pipeline.cuda()

# 3. Load Image & Run
image = Image.open("assets/example_image/T.png")
mesh = pipeline.run(image)[0]
mesh.simplify(16777216) # nvdiffrast limit

# 4. Render Video
video = render_utils.make_pbr_vis_frames(render_utils.render_video(mesh, envmap=envmap))
imageio.mimsave("sample.mp4", video, fps=15)

# 5. 导出为 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：一个可视化生成的 3D 资产的视频，包含 PBR 材质和环保光照。

sample.glb：以 GLB 格式提取的、可用于 PBR 的 3D 资产。

注意：.glb 文件默认以 OPAQUE 模式导出。虽然纹理贴图中保留了 alpha 通道，但初始状态下未激活。要启用透明度，请将资产导入您的 3D 软件，并手动将纹理的 alpha 通道连接到材质的不透明度或 alpha 输入。

app.py 提供了一个用于图像转 3D 资产生成的简易网页演示。您可以使用以下命令运行演示：

python app.py

之后，您可以在终端显示的地址访问演示。

## 2. PBR 纹理生成

请参考 example_texturing.py 查看如何为给定 3D 形状生成 PBR 纹理的示例。您也可以使用 app_texturing.py 运行 PBR 纹理生成的网页演示。

我们提供了完整的训练代码库，使用户能够从头开始训练 TRELLIS.2 或在自定义数据集上微调。

训练前，原始 3D 资产必须转换为 O-Voxel 表示。此过程包括网格转换、紧凑结构化潜空间生成和元数据准备。

📂 详细说明请参考 data_toolkit/README.md，了解数据预处理和数据集组织。

训练通过 train.py 脚本管理，该脚本接受多个命令行参数以配置实验：

--config：实验配置文件的路径。

--output_dir：训练输出目录。

--load_dir：加载检查点的目录（默认为 output_dir）。

--ckpt：要恢复的检查点步数（默认为最新）。

--data_dir：数据集路径或指定数据集位置的 JSON 字符串。

--auto_retry：失败时的自动重试次数。

--tryrun：执行试运行，不进行实际训练。

--profile：启用训练性能分析。

--num_nodes：分布式训练的节点数。

--node_rank：当前节点的排名。

--num_gpus：每个节点的 GPU 数量（默认为所有可用 GPU）。

--master_addr：分布式训练的主节点地址。

--master_port：分布式训练通信端口。

要训练形状 SC-VAE，运行：

python train.py
--config configs/scvae/shape_vae_next_dc_f16c32_fp16.json
--output_dir results/shape_vae_next_dc_f16c32_fp16
--data_dir "{"ObjaverseXL_sketchfab": {"base": "datasets/ObjaverseXL_sketchfab", "mesh_dump": "datasets/ObjaverseXL_sketchfab/mesh_dumps", "dual_grid": "datasets/ObjaverseXL_sketchfab/dual_grid_256", "asset_stats": "datasets/ObjaverseXL_sketchfab/asset_stats"}}"

此命令使用 shape_vae_next_dc_f16c32_fp16.json 配置在 Objaverse-XL 数据集上训练形状 SC-VAE。训练输出将保存至 results/shape_vae_next_dc_f16c32_fp16。

数据集指定为 JSON 字符串，每个数据集条目包含：

base：数据集的根目录。

mesh_dump：包含预处理网格转储的目录。

dual_grid：包含预计算对偶网格表示的目录。

asset_stats：包含预计算资产统计的目录。

要在更高分辨率下微调模型，使用 shape_vae_next_dc_f16c32_fp16_ft_512.json 配置。记得更新 finetune_ckpt 字段并相应调整数据集路径。

要训练纹理 SC-VAE，运行：

python train.py
--config configs/scvae/tex_vae_next_dc_f16c32_fp16.json
--output_dir results/tex_vae_next_dc_f16c32_fp16
--data_dir "{"ObjaverseXL_sketchfab": {"base": "datasets/ObjaverseXL_sketchfab", "pbr_dump": "datasets/ObjaverseXL_sketchfab/pbr_dumps", "pbr_voxel": "datasets/ObjaverseXL_sketchfab/pbr_voxels_256", "asset_stats": "datasets/ObjaverseXL_sketchfab/asset_stats"}}"

要训练稀疏结构流模型，运行：

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"}}"

此命令使用指定的配置文件在 Objaverse-XL 数据集上训练稀疏结构流模型。输出保存至 results/ss_flow_img_dit_1_3B_64_bf16。

数据集配置包含：

base：根数据集目录。

ss_latent：包含预计算稀疏结构潜空间的目录。

render_cond：包含条件渲染图像的目录。

用于形状和纹理生成的第二阶和第三阶流模型可使用以下配置进行训练：

形状流：slat_flow_img2shape_dit_1_3B_512_bf16.json

纹理流：slat_flow_imgshape2tex_dit_1_3B_512_bf16.json

形状流模型

python train.py
--config configs/gen/slat_flow_img2shape_dit_1_3B_512_bf16.json
--output_dir results/slat_flow_img2shape_dit_1_3B_512_bf16
--data_dir "{"ObjaverseXL_sketchfab": {"base": "datasets/ObjaverseXL_sketchfab", "shape_latent": "datasets/ObjaverseXL_sketchfab/shape_latents/shape_enc_next_dc_f16c32_fp16_512", "render_cond": "datasets/ObjaverseXL_sketchfab/renders_cond"}}"

纹理流模型

python train.py
--config configs/gen/slat_flow_imgshape2tex_dit_1_3B_512_bf16.json
--output_dir results/slat_flow_imgshape2tex_dit_1_3B_512_bf16
--data_dir "{"ObjaverseXL_sketchfab": {"base": "datasets/ObjaverseXL_sketchfab", "shape_latent": "datasets/ObjaverseXL_sketchfab/shape_latents/shape_enc_next_dc_f16c32_fp16_512", "pbr_latent": "datasets/ObjaverseXL_sketchfab/pbr_latents/tex_enc_next_dc_f16c32_fp16_512", "render_cond": "datasets/ObjaverseXL_sketchfab/renders_cond"}}"

可通过更新以下配置文件中的 finetune_ckpt 字段并相应调整数据集路径，执行更高分辨率微调：

slat_flow_img2shape_dit_1_3B_512_bf16_ft1024.json

slat_flow_imgshape2tex_dit_1_3B_512_bf16_ft1024.json

TRELLIS.2 构建在本团队开发的多个专业化高性能软件包之上：

O-Voxel：处理纹理网格与 O-Voxel 表示之间转换逻辑的核心库，确保即时双向变换。

FlexGEMM：基于 Triton 的高效稀疏卷积实现，可快速处理稀疏体素结构。

CuMesh：CUDA 加速网格工具，用于高速后处理、重网格化、简化和 UV 展开。

此模型和代码在 MIT 许可证下发布。

请注意，某些依赖项受各自单独的许可证条款管理：

nvdiffrast：用于渲染生成的 3D 资产。此软件包受其自身许可证管理。

nvdiffrast：用于渲染生成的 3D 资产。此软件包受其自身许可证管理。

nvdiffrec：为 PBR 材质实现分割求和渲染器。此软件包受其自身许可证管理。

nvdiffrec：为 PBR 材质实现分割求和渲染器。此软件包受其自身许可证管理。

若您发现此模型对研究有帮助，请引用我们的工作：

@article{ xiang2025trellis2, title={Native and Compact Structured Latents for 3D Generation}, author={Xiang, Jianfeng and Chen, Xiaoxue and Xu, Sicheng and Wang, Ruicheng and Lv, Zelong and Deng, Yu and Zhu, Hongyuan and Dong, Yue and Zhao, Hao and Yuan, Nicholas Jing and Yang, Jiaolong}, journal={Tech report}, year={2025} }