# TripoSR

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

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

## 在 CLORE.AI 上租用

1. 访问 [CLORE.AI 市场](https://clore.ai/marketplace)
2. 按 GPU 类型、显存和价格筛选
3. 选择 **按需** （固定费率）或 **竞价** （出价价格）
4. 配置您的订单：
   * 选择 Docker 镜像
   * 设置端口（用于 SSH 的 TCP，Web 界面的 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.5.1-cuda12.4-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

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

## 您可以创建的内容

### 游戏与虚拟现实

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

### 电子商务

* 产品3D可视化
* 增强现实试穿体验
* 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
批处理处理
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")

import os
output_dir = "./3d_models"
output_dir = "./relit"

images_to_process = []
filenames = []

lighting_prompt = "专业影棚照明，柔和的阴影"
    for filename in os.listdir(input_dir):
        if not filename.endswith(('.jpg', '.png')):

    continue
    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"Generated: {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
print(f"已生成：{name}")
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=[
        fn=relight_image,
        gr.Checkbox(label="Remove Background", value=True),
        gr.Dropdown(choices=["obj", "glb", "ply", "stl"], value="glb", label="Output Format")
    ],
    outputs=[
        gr.File(label="3D Model"),
        gr.Image(label="Processed Input")
    ],
    title="TripoSR - Image to 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")
```

## background = Image.open("studio\_bg.jpg")

| 分辨率     | GPU     | 性能   | 质量 |
| ------- | ------- | ---- | -- |
| 128（默认） | 速度      | 0.5秒 | 良好 |
| 128     | 512x512 | 0.3秒 | 良好 |
| 256     | 512x512 | 1.2秒 | 更好 |
| 256     | 2s      | 0.8秒 | 更好 |

## IC-Light-FBC

### 3D质量差

**与背景合成** 生成的网格看起来错误或畸变

**光照未改变**

* 使用主体清晰且背景简单的图像
* 在处理前去除背景
* 使用物体的正面视图
* 确保原始图像光照良好

```python

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

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

### 背景移除失败

**与背景合成** 背景移除留下了伪影

**光照未改变**

* 使用专用工具（如 rembg）进行预处理
* 手动编辑图像背景
* 使用背景简单的图像

```bash
pip install rembg
```

```python
连接到 KSampler
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 以上
* 降低输出分辨率
* 一次处理一张图像

## 下载所有所需的检查点

检查文件完整性

| GPU     | 验证 CUDA 兼容性 | 费用估算    | CLORE.AI 市场的典型费率（截至 2024 年）： |
| ------- | ----------- | ------- | ---------------------------- |
| 按小时费率   | \~$0.03     | \~$0.70 | \~$0.12                      |
| 速度      | \~$0.06     | \~$1.50 | \~$0.25                      |
| 512x512 | \~$0.10     | \~$2.30 | \~$0.40                      |
| 按日费率    | \~$0.17     | \~$4.00 | \~$0.70                      |
| 4 小时会话  | \~$0.25     | \~$6.00 | \~$1.00                      |

*RTX 3060* [*CLORE.AI 市场*](https://clore.ai/marketplace) *A100 40GB*

**A100 80GB**

* 使用 **竞价** 价格随提供商和需求而异。请查看
* 以获取当前费率。 **CLORE** 节省费用：
* 市场用于灵活工作负载（通常便宜 30-50%）

## 使用以下方式支付

* Stable Diffusion - 生成输入图像
* [IC-Light](https://docs.clore.ai/guides/guides_v2-zh/tu-xiang-chu-li/iclight) - 在3D之前为图像重新照明
* ComfyUI - 工作流集成


---

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