# 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 - 工作流集成