TRELLIS 开源项目使用与启动教程

TRELLIS 开源项目使用与启动教程

TRELLIS Official repo for paper "Structured 3D Latents for Scalable and Versatile 3D Generation". 项目地址: https://gitcode.com/gh_mirrors/trell/TRELLIS

1. 项目介绍

TRELLIS 是一个由微软开发的3D资产生成模型，它能够接受文本或图像提示，生成高质量的3D资产，格式包括辐射场、3D高斯分布和网格等。TRELLIS 的核心是一个统一的结构化潜变量（SLAT）表示，支持解码为不同的输出格式，并采用针对SLAT优化的Rectified Flow Transformers作为强大的基础模型。该项目提供大规模预训练模型，参数可达20亿，基于一个包含50万个多样化物体的3D资产数据集。

2. 项目快速启动

系统要求

• 操作系统：目前代码仅在 Linux 系统上测试。Windows 设置可参考 issue #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. 安装依赖：

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

   如果遇到安装问题，可以尝试逐个安装依赖，指定一个flag。

使用预训练模型

提供以下预训练模型：

• TRELLIS-image-large：大型图像到3D模型，参数量为1.2B。
• TRELLIS-text-base：基础文本到3D模型，参数量为342M。
• TRELLIS-text-large：大型文本到3D模型，参数量为1.1B。
• TRELLIS-text-xlarge：超大型文本到3D模型，参数量为2.0B。

推荐使用图像条件版本的模型以获得更好的性能。所有VAEs都包含在TRELLIS-image-large模型仓库中。模型托管在Hugging Face上，可以直接在代码中加载模型。

import os
# os.environ['ATTN_BACKEND'] = 'xformers'   # 可选 'flash-attn' 或 'xformers'，默认为 'flash-attn'
os.environ['SPCONV_ALGO'] = 'native'  # 可选 'native' 或 'auto'，默认为 'auto'。'auto' 速度更快，但会在开始时进行基准测试。推荐如果只运行一次，设置为 'native'。

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

# 从模型文件夹或Hugging Face模型仓库加载一个pipeline
pipeline = TrellisImageTo3DPipeline.from_pretrained("JeffreyXiang/TRELLIS-image-large")

3. 应用案例和最佳实践

生成3D资产

以下是一个使用预训练模型生成3D资产的简单示例：

# 加载图像
image = Image.open("path/to/image.jpg")

# 生成3D资产
asset = pipeline(image)

# 保存结果
imageio.imsave("output.jpg", asset)

生成3D资产的变体

可以通过对生成的3D资产进行编辑，来创建同一物体的不同变体：

# 生成变体
variant = pipeline(image, variant=True)

# 保存变体
imageio.imsave("variant.jpg", variant)

4. 典型生态项目

TRELLIS 可以与文本到图像模型结合使用，以实现更丰富的3D生成。此外，社区中也有许多基于TRELLIS的项目，例如：

• 使用TRELLIS模型进行虚拟现实内容创建。
• 结合游戏引擎，实现实时3D渲染。
• 在教育领域，利用TRELLIS创建交互式3D模型。

这些项目展示了TRELLIS在多个领域的应用潜力。

TRELLIS Official repo for paper "Structured 3D Latents for Scalable and Versatile 3D Generation". 项目地址: https://gitcode.com/gh_mirrors/trell/TRELLIS