> 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/triposr.md).

# TripoSR

在 Clore.ai 上使用 TripoSR 从单张图像生成 3D 模型

在不到一秒内从单张图像生成 3D 模型。

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

## 在 CLORE.AI 上租用

1. 访问 [CLORE.AI 市场](https://clore.ai/marketplace)
2. 按 GPU 类型、VRAM 和价格筛选
3. 选择 **按需** （固定费率）或 **竞价** （出价）
4. 配置你的订单：
   * 选择 Docker 镜像
   * 设置端口（SSH 用 TCP，Web UI 用 HTTP）
   * 如有需要，添加环境变量
   * 输入启动命令
5. 选择支付方式： **CLORE**, **BTC**，或 **USDT/USDC**
6. 创建订单并等待部署

### 访问你的服务器

* 在以下位置查找连接信息 **我的订单**
* Web 界面：使用 HTTP 端口 URL
* SSH： `ssh -p <port> root@<proxy-address>`

## 什么是 TripoSR？

Stability AI 和 Tripo AI 的 TripoSR 可实现：

* 从单张图像生成 3D 网格
* 亚秒级推理速度
* 高质量纹理网格
* 导出为 OBJ、GLB 和其他格式

## 资源

* **GitHub：** [VAST-AI-Research/TripoSR](https://github.com/VAST-AI-Research/TripoSR)
* **HuggingFace：** [stabilityai/TripoSR](https://huggingface.co/stabilityai/TripoSR)
* **论文：** [TripoSR 论文](https://arxiv.org/abs/2403.02151)
* **演示：** [HuggingFace Space](https://huggingface.co/spaces/stabilityai/TripoSR)

## 推荐硬件

| 组件  | 最低            | 推荐            | 最佳            |
| --- | ------------- | ------------- | ------------- |
| GPU | RTX 3060 12GB | RTX 4080 16GB | RTX 4090 24GB |
| 显存  | 8GB           | 12GB          | 16GB          |
| CPU | 4 核           | 8 核           | 16 核          |
| 内存  | 16GB          | 32GB          | 64GB          |
| 存储  | 20GB SSD      | 50GB NVMe     | 100GB NVMe    |
| 网络  | 100 Mbps      | 500 Mbps      | 1 Gbps        |

## 在 CLORE.AI 上快速部署

**Docker 镜像：**

```
pytorch/pytorch:2.11.0-cuda12.8-cudnn9-devel
```

**端口：**

```
22/tcp
7860/http
```

**命令：**

```bash
cd /workspace && \
git clone https://github.com/VAST-AI-Research/TripoSR.git && \\
cd TripoSR && \\
pip install -r requirements.txt && \
python gradio_app.py
```

## 访问你的服务

部署后，找到你的 `http_pub` URL 在 **我的订单**:

1. 前往 **我的订单** 页面
2. 点击你的订单
3. 找到 `http_pub` URL（例如， `abc123.clorecloud.net`)

使用 `https://YOUR_HTTP_PUB_URL` 替代 `localhost` 在下面的示例中。

## 安装

```bash
git clone https://github.com/VAST-AI-Research/TripoSR.git
cd TripoSR
pip install -r requirements.txt

# 模型会在首次运行时自动下载
```

## 你可以创建什么

### 游戏与 VR

* 将概念图转为 3D 资源
* 游戏物体的快速原型制作
* 角色模型生成
* 环境道具

### 电子商务

* 产品 3D 可视化
* AR 试穿体验
* 360 度产品视图
* 虚拟展厅

### 架构

* 从草图快速生成 3D 模型
* 室内设计可视化
* 家具原型
* 建筑构件生成

### 教育

* 用于学习材料的 3D 模型
* 科学可视化
* 历史文物复原
* 解剖模型

### 创意项目

* 数字艺术和 NFT
* 动画资源
* 3D 打印准备
* 表情包和头像创建

## 基础用法

### 命令行

```bash
python run.py input_image.png \\
    --output-dir output/ \\
    --render
```

### Python API

```python
import torch
from PIL import Image
from tsr.system import TSR
from tsr.utils import remove_background, save_video

# 加载模型
model = TSR.from_pretrained(
    "stabilityai/TripoSR",
    config_name="config.yaml",
    weight_name="model.ckpt"
)
model.to("cuda")

# 加载并预处理图像
image = Image.open("input.png")

# 生成 3D 网格
with torch.no_grad():
    scene_codes = model([image], device="cuda")

# 提取网格
meshes = model.extract_mesh(scene_codes)

# 保存网格
meshes[0].export("output.obj")
```

### 配合背景移除使用

```python
from tsr.system import TSR
from tsr.utils import remove_background
from PIL import Image

model = TSR.from_pretrained("stabilityai/TripoSR")
model.to("cuda")

# 加载图像并移除背景
image = Image.open("photo.jpg")
image_no_bg = remove_background(image)

# 生成 3D
with torch.no_grad():
    scene_codes = model([image_no_bg], device="cuda")

mesh = model.extract_mesh(scene_codes)[0]
mesh.export("model.glb")  # 导出为 GLB 以用于网页
```

## 批量处理

```python
import os
from PIL import Image
import torch
from tsr.system import TSR
from tsr.utils import remove_background

model = TSR.from_pretrained("stabilityai/TripoSR")
model.to("cuda")

input_dir = "./images"
output_dir = "./3d_models"
os.makedirs(output_dir, exist_ok=True)

images_to_process = []
filenames = []

for filename in os.listdir(input_dir):
    if not filename.endswith(('.jpg', '.png')):
        continue

    image = Image.open(os.path.join(input_dir, filename))
    image_no_bg = remove_background(image)
    images_to_process.append(image_no_bg)
    filenames.append(filename)

# 分批处理
batch_size = 4
for i in range(0, len(images_to_process), batch_size):
    batch = images_to_process[i:i+batch_size]
    batch_names = filenames[i:i+batch_size]

    with torch.no_grad():
        scene_codes = model(batch, device="cuda")

    meshes = model.extract_mesh(scene_codes)

    for mesh, name in zip(meshes, batch_names):
        output_name = name.rsplit('.', 1)[0] + '.obj'
        mesh.export(os.path.join(output_dir, output_name))
        print(f"已生成：{output_name}")
```

## 导出格式

```python
from tsr.system import TSR
from PIL import Image

model = TSR.from_pretrained("stabilityai/TripoSR")
model.to("cuda")

image = Image.open("input.png")

with torch.no_grad():
    scene_codes = model([image], device="cuda")

mesh = model.extract_mesh(scene_codes)[0]

# 不同的导出格式
mesh.export("model.obj")   # Wavefront OBJ
mesh.export("model.glb")   # GLTF 二进制格式（适合网页）
mesh.export("model.ply")   # PLY 格式
mesh.export("model.stl")   # STL（3D 打印）
```

## 渲染预览视频

```python
from tsr.system import TSR
from tsr.utils import save_video
from PIL import Image
import torch

model = TSR.from_pretrained("stabilityai/TripoSR")
model.to("cuda")

image = Image.open("input.png")

with torch.no_grad():
    scene_codes = model([image], device="cuda")

# 渲染 360 度视频
render_images = model.render(
    scene_codes,
    n_views=30,
    return_type="pil"
)

save_video(render_images[0], "preview.mp4", fps=30)
```

## Gradio 界面

```python
import gradio as gr
import torch
from PIL import Image
from tsr.system import TSR
from tsr.utils import remove_background
import tempfile

model = TSR.from_pretrained("stabilityai/TripoSR")
model.to("cuda")

def generate_3d(image, remove_bg, output_format):
    if remove_bg:
        image = remove_background(image)

    with torch.no_grad():
        scene_codes = model([image], device="cuda")

    mesh = model.extract_mesh(scene_codes)[0]

    with tempfile.NamedTemporaryFile(suffix=f".{output_format}", delete=False) as f:
        mesh.export(f.name)
        return f.name, image

demo = gr.Interface(
    fn=generate_3d,
    inputs=[
        gr.Image(type="pil", label="输入图像"),
        gr.Checkbox(label="移除背景", value=True),
        gr.Dropdown(choices=["obj", "glb", "ply", "stl"], value="glb", label="输出格式")
    ],
    outputs=[
        gr.File(label="3D 模型"),
        gr.Image(label="处理后的输入")
    ],
    title="TripoSR - 图像转 3D",
    description="从单张图像在数秒内生成 3D 模型。在 CLORE.AI GPU 服务器上运行。"
)

demo.launch(server_name="0.0.0.0", server_port=7860)
```

## 带网格细化

```python
from tsr.system import TSR
from PIL import Image
import torch

model = TSR.from_pretrained("stabilityai/TripoSR")
model.to("cuda")

image = Image.open("input.png")

with torch.no_grad():
    scene_codes = model([image], device="cuda")

# 以更高分辨率提取
mesh = model.extract_mesh(
    scene_codes,
    resolution=256  # 数值越高细节越多，默认值为 128
)[0]

mesh.export("high_detail.obj")
```

## 性能

| 分辨率     | GPU      | 速度   | 质量 |
| ------- | -------- | ---- | -- |
| 128（默认） | RTX 3090 | 0.5秒 | 好  |
| 128     | RTX 4090 | 0.3秒 | 好  |
| 256     | RTX 4090 | 1.2秒 | 更好 |
| 256     | A100     | 0.8秒 | 更好 |

## 常见问题与解决方案

### 较差的 3D 质量

**问题：** 生成的网格看起来不正确或已变形

**解决方案：**

* 使用主体清晰、背景简单的图像
* 在处理前移除背景
* 使用物体的正面视角
* 确保源图像有良好的光照

```python

# 始终移除背景以获得最佳结果
from tsr.utils import remove_background

image = Image.open("photo.jpg")
clean_image = remove_background(image)
```

### 背景移除失败

**问题：** 背景移除留下了瑕疵

**解决方案：**

* 使用 rembg 之类的专用工具预处理
* 手动编辑图像背景
* 使用背景简单的图像

```bash
pip install rembg
```

```python
from rembg import remove
from PIL import Image

image = Image.open("photo.jpg")
image_no_bg = remove(image)
image_no_bg.save("clean.png")
```

### 内存不足

**问题：** 高分辨率下 CUDA 内存不足

**解决方案：**

```python

# 使用更低的分辨率
mesh = model.extract_mesh(scene_codes, resolution=128)

# 或在批次之间清空缓存
import torch
torch.cuda.empty_cache()
```

### 网格有孔洞

**问题：** 生成的网格缺少部分

**解决方案：**

* 使用更高分辨率提取
* 尝试主体的不同视角
* 在 Blender 或 MeshLab 中后处理网格
* 使用物体完整可见的图像

### 处理缓慢

**问题：** 每张图像耗时过长

**解决方案：**

* 对多张图像使用批处理
* 原型阶段使用较低分辨率
* 使用 RTX 4090 或 A100 GPU

## 故障排查

### 3D 网格质量较差

* 使用物体边界清晰的图像
* 移除或遮罩背景
* 正面视角效果最佳

### 导出失败

* 检查输出目录是否存在
* 验证网格格式是否受支持
* 确保有足够的磁盘空间

### 纹理缺失

* 某些导出不包含纹理
* 使用 GLB 格式导出带纹理的结果
* 检查材质导出设置

{% hint style="danger" %}
**内存不足**
{% endhint %}

* TripoSR 很高效，但需要 6GB 以上
* 降低输出分辨率
* 一次处理一张图像

## 成本估算

CLORE.AI 市场常见费率（截至 2024 年）：

| GPU       | 小时费率    | 日费率     | 4 小时会话  |
| --------- | ------- | ------- | ------- |
| RTX 3060  | \~$0.03 | \~$0.70 | \~$0.12 |
| RTX 3090  | \~$0.06 | \~$1.50 | \~$0.25 |
| RTX 4090  | \~$0.10 | \~$2.30 | \~$0.40 |
| A100 40GB | \~$0.17 | \~$4.00 | \~$0.70 |
| A100 80GB | \~$0.25 | \~$6.00 | \~$1.00 |

*价格因提供商和需求而异。请查看* [*CLORE.AI 市场*](https://clore.ai/marketplace) *以获取当前费率。*

**节省费用：**

* 使用 **竞价** 可中断工作市场——约三分之一的服务器将现货价格定得低于按需价格（中位数约优惠 13%），其余则与按需价格持平
* 使用 **CLORE** 代币支付
* 比较不同提供商的价格

## 下一步

* Stable Diffusion - 生成输入图像
* [IC-Light](/guides/guides_v2-zh/tu-xiang-chu-li/iclight.md) - 在 3D 之前为图像重新打光
* ComfyUI - 工作流集成


---

# 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/triposr.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.