Windows 一键安装程序：(Python 3.11, Cuda 12.8, Torch 2.7)

与免费 AI 纹理工具 StableProjectorz 集成的仓库。
我们的 Discord 服务器：这里

我已在管道中添加了对 float16（替代 float32）和 int32（替代 int64）的支持。
如果 8GB GPU 卡支持半精度，这可使整个算法在其显存中运行。
我还添加了 API 支持，可通过 FastAPI 从 c# 等环境进行生成。
FishWoWaters 添加了 Gradio 支持。

正在整合 Jonathan Clark 的分支，以移除导致 Trellis 非商业化的依赖项。

目前，我的分支使用 flexicubes 分支 https://github.com/IgorAherne/flexicubes-stable-projectorz
我已将其修改为使用 int32 而非 int64，在 SLAT 解码阶段将内存减少一半。

如果您想手动安装：

1. 使用 python 3.11
2. 安装 code/requirements.txt
3. 然后按照 code/install.py 中约 130 行的 install_dependencies() 方法中的步骤操作
4. 您需要 pip 安装 wheel 文件，可在 code/whl 文件夹中找到。仅安装步骤 3) 中提到的 whl。
5. 最后，在 code 文件夹内，执行 git submodule deinit -f --all，然后执行 git submodule update --init --recursive，以确保安装了 flexicubes 子仓库
6. 通过 python main_gradio.py --precision half 启动，或通过 python api_spz/main_api.py 启动以获得 API 支持

原始 Trellis 仓库说明：

结构化 3D 潜变量
用于可扩展和多功能 3D 生成

TRELLIS 是一个大型 3D 资产生成模型。它接收文本或图像提示，并生成各种格式的高质量 3D 资产，如辐射场、3D 高斯和网格。TRELLIS 的核心是统一的结构化潜变量（SLAT）表示，允许解码为不同的输出格式，以及为 SLAT 量身定制的整流流 Transformer 作为强大的主干网络。我们在包含 50 万个多样化对象的大型 3D 资产数据集上提供了高达 20 亿参数的大规模预训练模型。TRELLIS 显著超越了现有方法，包括近期类似规模的方法，并展示了灵活的输出格式选择和局部 3D 编辑能力，这些都是以前的模型所不具备的。

查看我们的 项目页面 获取更多视频和交互式演示！

🌟 特性

• 高质量：生成高质量、多样化的3D资产，具备复杂的形状和纹理细节。
• 多功能性：支持文本或图像提示，可生成多种最终3D表示形式，包括但不限于辐射场（Radiance Fields）、3D高斯（3D Gaussians） 和网格（meshes），以满足多样化的下游需求。
• 灵活编辑：支持对生成的3D资产进行便捷编辑，例如生成同一物体的变体或对3D资产进行局部编辑。

⏩ 更新

2024年12月26日

• 发布TRELLIS-500K数据集及数据准备工具包。

2024年12月18日

• 实现TRELLIS-image模型的多图像条件控制。(#7)。此功能基于免调优算法，无需训练专门模型，因此可能无法在所有输入图像上达到最佳效果。
• 在app.py和example.py中添加高斯导出功能。(#40)

🚧 待办清单

• 发布推理代码和TRELLIS-image-large模型
• 发布数据集和数据集工具包
• 发布TRELLIS-text模型系列
• 发布训练代码

📦 安装

先决条件

• 系统：目前代码仅在Linux上测试通过。对于Windows系统的设置，可参考#3（未完全测试）。
• 硬件：需要至少16GB内存的NVIDIA GPU。代码已在NVIDIA A100和A6000 GPU上验证通过。
• 软件：
  • 需要CUDA Toolkit来编译某些子模块。代码已在CUDA 11.8和12.2版本上测试通过。
  • 推荐使用Conda管理依赖项。
  • 需要Python 3.8或更高版本。

安装步骤

1. 克隆仓库：

   git clone --recurse-submodules https://github.com/microsoft/TRELLIS.git
   cd TRELLIS
   

2. 安装依赖项：

   运行以下命令前请注意：

   • 添加 --new-env 会创建一个名为 trellis 的新 conda 环境。如果想使用现有 conda 环境，请移除该标志。
   • 默认情况下，trellis 环境将使用 PyTorch 2.4.0 和 CUDA 11.8。如果想使用其他版本的 CUDA（例如，已安装 CUDA Toolkit 12.2，不想为子模块编译再安装 11.8 版本），可以移除 --new-env 标志并手动安装所需依赖。有关安装命令，请参考 PyTorch。
   • 如果安装了多个 CUDA Toolkit 版本，运行命令前应将 PATH 设置为正确的版本。例如，若安装了 CUDA Toolkit 11.8 和 12.2，应在运行命令前执行 export PATH=/usr/local/cuda-11.8/bin:$PATH。
   • 默认情况下，代码使用 flash-attn 作为注意力后端。对于不支持 flash-attn 的 GPU（如 NVIDIA V100），可以移除 --flash-attn 标志，仅安装 xformers，并在运行代码前将 ATTN_BACKEND 环境变量设置为 xformers。更多详情请参见 最小示例。
   • 由于依赖项数量较多，安装过程可能需要一段时间，请耐心等待。如果遇到问题，可以尝试逐个安装依赖项，每次指定一个标志。
   • 如果在安装过程中遇到任何问题，欢迎提交 issue 或与我们联系。

   创建名为 trellis 的新 conda 环境并安装依赖项：

   . ./setup.sh --new-env --basic --xformers --flash-attn --diffoctreerast --spconv --mipgaussian --kaolin --nvdiffrast
   

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

   用法：setup.sh [选项]
   选项：
       -h, --help              显示此帮助信息
       --new-env               创建新的 conda 环境
       --basic                 安装基本依赖项
       --xformers              安装 xformers
       --flash-attn            安装 flash-attn
       --diffoctreerast        安装 diffoctreerast
       --vox2seq               安装 vox2seq
       --spconv                安装 spconv
       --mipgaussian           安装 mip-splatting
       --kaolin                安装 kaolin
       --nvdiffrast            安装 nvdiffrast
       --demo                  安装演示所需的所有依赖项
   

🤖 预训练模型

我们提供以下预训练模型：

模型	描述	参数数量	下载
TRELLIS-image-large	大型图像转3D模型	12亿	下载
TRELLIS-text-base	基础文本转3D模型	3.42亿	即将推出
TRELLIS-text-large	大型文本转3D模型	11亿	即将推出
TRELLIS-text-xlarge	超大型文本转3D模型	20亿	即将推出

模型托管在 Hugging Face 上。您可以在代码中直接使用模型的仓库名称加载模型：

TrellisImageTo3DPipeline.from_pretrained("jetx/TRELLIS-image-large")

如果您倾向于从本地加载模型，可以从上述链接下载模型文件，并通过文件夹路径加载模型（需保持文件夹结构）：

TrellisImageTo3DPipeline.from_pretrained("/path/to/TRELLIS-image-large")

💡 用法

最简示例

以下是一个示例，展示如何使用预训练模型进行 3D 资产生成。

import os
# os.environ['ATTN_BACKEND'] = 'xformers'   # Can be 'flash-attn' or 'xformers', default is 'flash-attn'
os.environ['SPCONV_ALGO'] = 'native'        # Can be 'native' or 'auto', default is 'auto'.
                                            # 'auto' is faster but will do benchmarking at the beginning.
                                            # Recommended to set to 'native' if run only once.

import imageio
from PIL import Image
from trellis.pipelines import TrellisImageTo3DPipeline
from trellis.utils import render_utils, postprocessing_utils

# Load a pipeline from a model folder or a Hugging Face model hub.
pipeline = TrellisImageTo3DPipeline.from_pretrained("jetx/TRELLIS-image-large")
pipeline.cuda()

# Load an image
image = Image.open("assets/example_image/T.png")

# Run the pipeline
outputs = pipeline.run(
    image,
    seed=1,
    # Optional parameters
    # sparse_structure_sampler_params={
    #     "steps": 12,
    #     "cfg_strength": 7.5,
    # },
    # slat_sampler_params={
    #     "steps": 12,
    #     "cfg_strength": 3,
    # },
)
# outputs is a dictionary containing generated 3D assets in different formats:
# - outputs['gaussian']: a list of 3D Gaussians
# - outputs['radiance_field']: a list of radiance fields
# - outputs['mesh']: a list of meshes

# Render the outputs
video = render_utils.render_video(outputs['gaussian'][0])['color']
imageio.mimsave("sample_gs.mp4", video, fps=30)
video = render_utils.render_video(outputs['radiance_field'][0])['color']
imageio.mimsave("sample_rf.mp4", video, fps=30)
video = render_utils.render_video(outputs['mesh'][0])['normal']
imageio.mimsave("sample_mesh.mp4", video, fps=30)

# GLB files can be extracted from the outputs
glb = postprocessing_utils.to_glb(
    outputs['gaussian'][0],
    outputs['mesh'][0],
    # Optional parameters
    simplify=0.95,          # Ratio of triangles to remove in the simplification process
    texture_size=1024,      # Size of the texture used for the GLB
)
glb.export("sample.glb")

# Save Gaussians as PLY files
outputs['gaussian'][0].save_ply("sample.ply")

运行代码后，您将获得以下文件：

• sample_gs.mp4：展示 3D 高斯表示的视频
• sample_rf.mp4：展示辐射场表示的视频
• sample_mesh.mp4：展示网格表示的视频
• sample.glb：包含提取的带纹理网格的 GLB 文件
• sample.ply：包含 3D 高斯表示的 PLY 文件

Web 演示

app.py 提供了一个用于 3D 资产生成的简单 Web 演示。由于此演示基于 Gradio，因此需要额外的依赖项：

. ./setup.sh --demo

安装依赖后，您可以使用以下命令运行演示：

python app.py

然后，您可以通过终端中显示的地址访问演示。

网页演示也可在 Hugging Face Spaces 上获取！

📚 数据集

我们提供了 TRELLIS-500K，这是一个大规模数据集，包含 500K 个 3D 资产，这些资产是从 Objaverse(XL)、ABO、3D-FUTURE、HSSD 和 Toys4k 中精选出来的，并基于美学分数进行了筛选。更多详情请参考 数据集 README。

⚖️ 许可证

TRELLIS 模型和大部分代码均采用 MIT 许可证。以下子模块可能具有不同的许可证：

• diffoctreerast：我们开发了一个基于 CUDA 的实时可微分八叉树渲染器，用于渲染辐射场，这是本项目的一部分。该渲染器源自 diff-gaussian-rasterization 项目，可在 LICENSE 下获取。

• Modified Flexicubes：在本项目中，我们使用了 Flexicubes 的修改版本，以支持顶点属性。此修改版本采用 LICENSE 许可证。

📜 引用

如果您觉得本研究有帮助，请考虑引用我们的论文：

@article{xiang2024structured,
    title   = {Structured 3D Latents for Scalable and Versatile 3D Generation},
    author  = {Xiang, Jianfeng and Lv, Zelong and Xu, Sicheng and Deng, Yu and Wang, Ruicheng and Zhang, Bowen and Chen, Dong and Tong, Xin and Yang, Jiaolong},
    journal = {arXiv preprint arXiv:2412.01506},
    year    = {2024}
}