# TRELLIS 3D 生成

微软研究院的 TRELLIS 可以将单张 RGB 图像转换为高质量的 3D 网格、Gaussian splat 或辐射场，在 RTX 3090 上约需 30 秒。以 MIT 许可证发布，完全可用于商业用途。

{% hint style="success" %}
所有示例均在通过以下方式租用的 GPU 服务器上运行： [CLORE.AI 市场](https://clore.ai/marketplace).
{% endhint %}

## 主要特性

* **单张图像 → 3D** — 无需多视角拍摄，无需文本提示
* **多种输出格式** — GLB 网格、Gaussian splat (.ply)、辐射场
* **每个资源约 \~30 秒** 在 RTX 3090/4090 上
* **MIT 许可证** — 可免费用于商业用途
* **Gradio 网页界面** 包含以便在浏览器中交互
* **Python API** 用于流水线集成和批处理
* **零样本** — 在任意图像上工作，无需微调

## 要求

| 组件     | 最低             | 推荐             |
| ------ | -------------- | -------------- |
| GPU    | RTX 3090 24 GB | RTX 4090 24 GB |
| 显存     | 24 GB          | 24 GB          |
| 内存     | 32 GB          | 64 GB          |
| 磁盘     | 30 GB          | 60 GB          |
| CUDA   | 11.8           | 12.1+          |
| Python | 3.10           | 3.10           |

**Clore.ai 价格：** RTX 4090 ≈ $0.5–2/天 · RTX 3090 ≈ $0.3–1/天

TRELLIS 需求 **24 GB 显存**。RTX 3090 是最低可行的 GPU。

## 快速开始

### 1. 设置环境

TRELLIS 使用特定的依赖版本 — 强烈建议使用 conda 环境：

```bash
# 创建并激活环境
conda create -n trellis python=3.10 -y
conda activate trellis

# 安装带 CUDA 的 PyTorch
pip install torch torchvision --index-url https://download.pytorch.org/whl/cu121

# 克隆 TRELLIS
git clone https://github.com/microsoft/TRELLIS.git
cd TRELLIS

# 安装依赖
pip install -r requirements.txt

# 安装用于网格导出的附加包
pip install kaolin -f https://nvidia-kaolin.s3.us-east-2.amazonaws.com/torch-2.1.0_cu121.html
pip install spconv-cu121
```

### 2. 运行 Gradio 网页界面

```bash
python app.py --share
```

这将在以下地址启动 Gradio 界面 `http://0.0.0.0:7860`。使用 `--share` 您将获得一个任何浏览器都可访问的公开 URL，在无头 Clore.ai 服务器上运行时很有用。

上传图像，调整生成参数，然后下载生成的 3D 资源。

### 3. 使用 Python API

```python
from trellis.pipelines import TrellisImageTo3DPipeline
from PIL import Image

# 加载流水线（首次运行时下载模型权重，约 5 GB）
pipeline = TrellisImageTo3DPipeline.from_pretrained("JeffreyXiang/TRELLIS-image-large")
pipeline.cuda()

# 从图像生成 3D
image = Image.open("input.png")
outputs = pipeline.run(
    image,
    seed=42,
    sparse_structure_sampler_params={
        "steps": 12,
        "cfg_strength": 7.5,
    },
    slat_sampler_params={
        "steps": 12,
        "cfg_strength": 3.0,
    },
)
```

### 4. 导出为不同格式

```python
# 导出为 GLB 网格（游戏引擎、网页查看器）
glb = pipeline.to_glb(
    outputs["gaussian"][0],
    outputs["mesh"][0],
    simplify=0.95,          # 将多边形数量减少 95%
    texture_size=1024,
)
glb.export("output.glb")

# 将 Gaussian splat 导出为 PLY
outputs["gaussian"][0].save_ply("output.ply")

# 将网格导出为 OBJ
import trimesh
mesh = trimesh.Trimesh(
    vertices=outputs["mesh"][0].vertices.cpu().numpy(),
    faces=outputs["mesh"][0].faces.cpu().numpy(),
)
mesh.export("output.obj")
```

## 使用示例

### 批量处理多张图像

```python
import glob
from pathlib import Path

input_dir = Path("/workspace/input-images")
output_dir = Path("/workspace/3d-output")
output_dir.mkdir(exist_ok=True)

for img_path in sorted(input_dir.glob("*.png")):
    image = Image.open(img_path)
    outputs = pipeline.run(image, seed=42)

    glb = pipeline.to_glb(
        outputs["gaussian"][0],
        outputs["mesh"][0],
        simplify=0.95,
        texture_size=1024,
    )
    glb.export(str(output_dir / f"{img_path.stem}.glb"))
    print(f"Exported: {img_path.stem}.glb")
```

### 调整生成质量

```python
# 更高质量（更慢，约 ~60 秒）
outputs = pipeline.run(
    image,
    seed=42,
    sparse_structure_sampler_params={
        "steps": 20,
        "cfg_strength": 9.0,
    },
    slat_sampler_params={
        "steps": 20,
        "cfg_strength": 4.5,
    },
)

# 快速预览（质量较低，约 ~15 秒）
outputs = pipeline.run(
    image,
    seed=42,
    sparse_structure_sampler_params={
        "steps": 6,
        "cfg_strength": 7.5,
    },
    slat_sampler_params={
        "steps": 6,
        "cfg_strength": 3.0,
    },
)
```

### 提取用于 3D 查看器的 Gaussian Splat

```python
# 保存为 .ply 以供 SuperSplat、Luma 或 Three.js splat 渲染器等查看器使用
outputs["gaussian"][0].save_ply("scene.ply")
```

## 性能参考

| GPU      | 步骤（12/12） | 时间     | 注意事项          |
| -------- | --------- | ------ | ------------- |
| 512x512  | 12 / 12   | \~25 秒 | 最佳性价比         |
| 速度       | 12 / 12   | \~35 秒 | TRELLIS 的最低要求 |
| A100 40G | 12 / 12   | \~20 秒 | 数据中心选项        |

## 提示

* **使用带干净背景的 PNG** — 在输入 TRELLIS 之前使用以下方法移除背景 `rembg` 以获得最佳网格质量
* **`simplify=0.95`** 在 GLB 导出中将多边形数量减少 95% 的同时保留视觉质量 — 对网页/游戏 使用至关重要
* **设置 `--share`** 在 Clore.ai 上运行 Gradio UI 时以获取公开 URL
* **种子一致性** — 固定 `seed` 以在多次运行中获得可重现的输出
* **纹理分辨率** — 使用 `texture_size=2048` 以获得打印质量的纹理， `1024` 用于实时应用
* **首次运行将下载约 5 GB** 的模型权重 — 请确保有足够的磁盘空间
* **Gaussian splat** 适合实时渲染；GLB 网格更适合游戏引擎和 3D 打印

## # 使用固定种子以获得一致结果

| 问题                         | 解决方案                                          |
| -------------------------- | --------------------------------------------- |
| `CUDA 内存不足（out of memory）` | TRELLIS 需要 24 GB 显存 — 使用 RTX 3090/4090 或 A100 |
| `kaolin` 安装失败              | 将 kaolin 版本与您的 PyTorch + CUDA 版本严格匹配          |
| `spconv` 导入错误              | 安装正确的 CUDA 版本： `pip install spconv-cu121`     |
| Gradio 界面不可访问              | 使用 `--share` 用于公共隧道，或在 Clore.ai 上暴露端口 7860    |
| 网格质量差                      | 确保输入图像具有干净/已移除的背景                             |
| 首次生成缓慢                     | 首次运行时会下载模型权重 — 之后的运行会很快                       |
| 导出 GLB 失败                  | 确保已安装 `trimesh` 和 `pygltflib` 已安装             |

## 资源

* [TRELLIS GitHub](https://github.com/microsoft/TRELLIS)
* [论文：用于可扩展 3D 生成的结构化 3D 潜表示](https://arxiv.org/abs/2412.01506)
* [CLORE.AI 市场](https://clore.ai/marketplace)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.clore.ai/guides/guides_v2-zh/3d-sheng-cheng/trellis-3d.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.