> For the complete documentation index, see [llms.txt](https://docs.clore.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.clore.ai/guides/guides_v2-zh/3d-sheng-cheng/trellis-3d.md).

# TRELLIS 3D 生成

在 Clore.ai 上使用 Microsoft TRELLIS 将图像转换为 3D 网格和 Gaussian splats

微软研究院的 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 Web UI** 用于基于浏览器的交互
* **Python API** 用于流水线集成和批量处理
* **零样本** — 无需微调即可处理任意图像

## 需求

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

**Clore.ai 价格：** RTX 4090 ≈ $0.14–0.42/小时 · RTX 3090 ≈ $0.07–0.21/小时

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/cu128

# 克隆 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 Web UI

```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） | 时间     | 备注            |
| -------- | --------- | ------ | ------------- |
| RTX 4090 | 12 / 12   | 约 25 秒 | 最佳性价比         |
| RTX 3090 | 12 / 12   | 约 35 秒 | TRELLIS 的最低配置 |
| A100 40G | 12 / 12   | 约 20 秒 | 数据中心选项        |

## 提示

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

## 故障排查

| 问题             | 解决方案                                          |
| -------------- | --------------------------------------------- |
| `CUDA 内存不足`    | TRELLIS 需要 24 GB 显存——请使用 RTX 3090/4090 或 A100 |
| `kaolin` 安装失败  | 将 kaolin 版本与你的 PyTorch + CUDA 版本完全匹配          |
| `spconv` 导入错误  | 安装正确的 CUDA 版本： `pip install spconv-cu121`     |
| Gradio UI 无法访问 | 使用 `--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
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.