用于 3D 生成的原生紧凑结构化潜空间 trellis2.mp4因 GitHub 大小限制此为压缩版。请在我们的项目页面查看高质量视频TRELLIS.2 是款先进的大型 3D 生成模型拥有 40 亿参数专为高保真图像到 3D 生成设计。它采用新颖“无场”稀疏体素结构 O-Voxel能重建和生成具复杂拓扑结构、尖锐特征和完整 PBR 材质的任意 3D 资产。特性1.高质量、高分辨率与高效率有 40 亿参数的模型借助普通的 DiTs能高效且高质量生成高分辨率全纹理资产。它利用空间下采样率为 16 倍的稀疏 3D VAE将资产编码到紧凑潜空间中。不同分辨率下的总时间*分解形状 材质如下512³约 3 秒2 秒 1 秒1024³约 17 秒10 秒 7 秒1536³约 60 秒35 秒 25 秒*在 NVIDIA H100 GPU 上测试所得。2.任意拓扑结构处理O-Voxel 表示法突破等值面场限制能稳健处理复杂结构无需有损转换可处理的结构有开放表面如衣物、树叶非流形几何结构内部封闭结构3.丰富的纹理建模除基本颜色外TRELLIS.2 还能对包括基础颜色、粗糙度、金属度和不透明度在内的任意表面属性建模支持逼真渲染和透明效果。4.极简处理流程数据处理流程简化可即时转换无需渲染和优化。纹理网格转换为 O-Voxel 10 秒单 CPUO-Voxel 转换为纹理网格 100 毫秒CUDA路线图发布论文发布图像到 3D 推理代码发布预训练检查点40 亿参数在 Hugging Face Spaces 上进行演示发布形状条件纹理生成推理代码发布训练代码安装前提条件系统目前代码仅在 Linux 系统上测试过。硬件需要至少 24GB 内存的 NVIDIA GPU代码已在 NVIDIA A100 和 H100 GPU 上验证。软件需要 CUDA Toolkit 编译某些包推荐版本为 12.4。建议用 Conda 管理依赖项Python 版本需 3.8 或更高。安装步骤1. 克隆仓库git clone -b main https://github.com/microsoft/TRELLIS.2.git --recursivecd TRELLIS.22. 安装依赖项运行以下命令前需注意添加 --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 选项-h, --help显示此帮助信息--new-env创建新的 Conda 环境--basic安装基本依赖项--flash-attn安装 flash-attention--cumesh安装 cumesh--o-voxel安装 o-voxel--flexgemm安装 flexgemm--nvdiffrast安装 nvdiffrast--nvdiffrec安装 nvdiffrec预训练权重预训练模型 TRELLIS.2-4B 可在 Hugging Face 上获取更多详情参考该平台上的模型卡片。模型参数分辨率链接TRELLIS.2-4B40 亿512³ - 1536³Hugging Face使用方法1. 图像到 3D 生成最小示例以下是用预训练模型进行 3D 资产生成的示例代码import osos.environ[OPENCV_IO_ENABLE_OPENEXR] 1os.environ[PYTORCH_CUDA_ALLOC_CONF] expandable_segments:True # 可节省 GPU 内存import cv2import imageiofrom PIL import Imageimport torchfrom trellis2.pipelines import Trellis2ImageTo3DPipelinefrom trellis2.utils import render_utilsfrom trellis2.renderers import EnvMapimport o_voxel# 1. 设置环境映射envmap EnvMap(torch.tensor(cv2.cvtColor(cv2.imread(assets/hdri/forest.exr, cv2.IMREAD_UNCHANGED),cv2.COLOR_BGR2RGB), dtypetorch.float32, devicecuda))# 2. 加载管道pipeline Trellis2ImageTo3DPipeline.from_pretrained(microsoft/TRELLIS.2-4B)pipeline.cuda()# 3. 加载图像并运行image Image.open(assets/example_image/T.png)mesh pipeline.run(image)[0]mesh.simplify(16777216) # nvdiffrast 限制# 4. 渲染视频video render_utils.make_pbr_vis_frames(render_utils.render_video(mesh, envmapenvmap))imageio.mimsave(sample.mp4, video, fps15)# 5. 导出为 GLBglb o_voxel.postprocess.to_glb(verticesmesh.vertices,facesmesh.faces,attr_volumemesh.attrs,coordsmesh.coords,attr_layoutmesh.layout,voxel_sizemesh.voxel_size,aabb[[-0.5, -0.5, -0.5], [0.5, 0.5, 0.5]],decimation_target1000000,texture_size4096,remeshTrue,remesh_band1,remesh_project0,verboseTrue)glb.export(sample.glb, extension_webpTrue)执行脚本后将生成以下文件sample.mp4可视化生成 3D 资产的视频含 PBR 材质和环境光照效果。sample.glb提取的 PBR 就绪的 3D 资产格式为 GLB。注意.glb 文件默认以不透明模式导出尽管纹理图中保留了 alpha 通道但初始时未激活。若启用透明度需将资产导入 3D 软件并手动将纹理的 alpha 通道连接到材质的不透明度或 alpha 输入。app.py 提供简单的 Web 演示用于图像到 3D 资产的生成用以下命令运行演示python app.py然后在终端显示的地址访问演示页面。2. PBR 纹理生成若了解如何为给定 3D 形状生成 PBR 纹理参考 example_texturing.py。此外可用 app_texturing.py 运行 PBR 纹理生成的 Web 演示。训练我们提供完整的训练代码库用户可从头开始训练 TRELLIS.2 或在自定义数据集上微调。1. 数据准备训练前需将原始 3D 资产转换为 O-Voxel 表示此过程包括网格转换、紧凑结构化潜空间生成和元数据准备。详细的数据预处理和数据集组织说明参考 data_toolkit/README.md。2. 运行训练训练通过 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 训练-形状 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包含条件渲染图像的目录。形状和纹理生成的第二阶段和第三阶段流模型可用以下配置训练-形状流模型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.jsonslat_flow_imgshape2tex_dit_1_3B_512_bf16_ft1024.json相关包TRELLIS.2 基于我们团队开发的几个专业高性能包构建O-Voxel核心库处理纹理网格和 O-Voxel 表示之间的转换逻辑确保即时双向转换。FlexGEMM基于 Triton 的高效稀疏卷积实现可快速处理稀疏体素结构。CuMeshCUDA 加速的网格实用工具用于高速后处理、重新网格化、简化和 UV 展开。许可证此模型和代码遵循 MIT 许可证发布。注意某些依赖项遵循单独的许可条款nvdiffrast用于渲染生成的 3D 资产该包遵循其自身的许可证。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}}