# TripoSR

Generate 3D models from single images in under a second.

{% hint style="success" %}
All examples can be run on GPU servers rented through [CLORE.AI Marketplace](https://clore.ai/marketplace).
{% endhint %}

## Renting on CLORE.AI

1. Visit [CLORE.AI Marketplace](https://clore.ai/marketplace)
2. Filter by GPU type, VRAM, and price
3. Choose **On-Demand** (fixed rate) or **Spot** (bid price)
4. Configure your order:
   * Select Docker image
   * Set ports (TCP for SSH, HTTP for web UIs)
   * Add environment variables if needed
   * Enter startup command
5. Select payment: **CLORE**, **BTC**, or **USDT/USDC**
6. Create order and wait for deployment

### Access Your Server

* Find connection details in **My Orders**
* Web interfaces: Use the HTTP port URL
* SSH: `ssh -p <port> root@<proxy-address>`

## What is TripoSR?

TripoSR by Stability AI and Tripo AI enables:

* Single image to 3D mesh generation
* Sub-second inference speed
* High-quality textured meshes
* Export to OBJ, GLB, and other formats

## Resources

* **GitHub:** [VAST-AI-Research/TripoSR](https://github.com/VAST-AI-Research/TripoSR)
* **HuggingFace:** [stabilityai/TripoSR](https://huggingface.co/stabilityai/TripoSR)
* **Paper:** [TripoSR Paper](https://arxiv.org/abs/2403.02151)
* **Demo:** [HuggingFace Space](https://huggingface.co/spaces/stabilityai/TripoSR)

## Recommended Hardware

| Component | Minimum       | Recommended   | Optimal       |
| --------- | ------------- | ------------- | ------------- |
| GPU       | RTX 3060 12GB | RTX 4080 16GB | RTX 4090 24GB |
| VRAM      | 8GB           | 12GB          | 16GB          |
| CPU       | 4 cores       | 8 cores       | 16 cores      |
| RAM       | 16GB          | 32GB          | 64GB          |
| Storage   | 20GB SSD      | 50GB NVMe     | 100GB NVMe    |
| Internet  | 100 Mbps      | 500 Mbps      | 1 Gbps        |

## Quick Deploy on CLORE.AI

**Docker Image:**

```
pytorch/pytorch:2.5.1-cuda12.4-cudnn9-devel
```

**Ports:**

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

**Command:**

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

## Accessing Your Service

After deployment, find your `http_pub` URL in **My Orders**:

1. Go to **My Orders** page
2. Click on your order
3. Find the `http_pub` URL (e.g., `abc123.clorecloud.net`)

Use `https://YOUR_HTTP_PUB_URL` instead of `localhost` in examples below.

## Installation

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

# Model downloads automatically on first run
```

## What You Can Create

### Gaming & VR

* Convert concept art to 3D assets
* Rapid prototyping for game objects
* Character model generation
* Environmental props

### E-Commerce

* Product 3D visualization
* AR try-on experiences
* 360-degree product views
* Virtual showrooms

### Architecture

* Quick 3D models from sketches
* Interior design visualization
* Furniture prototypes
* Building element generation

### Education

* 3D models for learning materials
* Scientific visualization
* Historical artifact recreation
* Anatomy models

### Creative Projects

* Digital art and NFTs
* Animation assets
* 3D printing preparation
* Meme and avatar creation

## Basic Usage

### Command Line

```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

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

# Load and preprocess image
image = Image.open("input.png")

# Generate 3D mesh
with torch.no_grad():
    scene_codes = model([image], device="cuda")

# Extract mesh
meshes = model.extract_mesh(scene_codes)

# Save mesh
meshes[0].export("output.obj")
```

### With Background Removal

```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")

# Load image and remove background
image = Image.open("photo.jpg")
image_no_bg = remove_background(image)

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

mesh = model.extract_mesh(scene_codes)[0]
mesh.export("model.glb")  # Export as GLB for web
```

## Batch Processing

```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)

# Process in batches
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}")
```

## Export Formats

```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]

# Different export formats
mesh.export("model.obj")   # Wavefront OBJ
mesh.export("model.glb")   # GLTF Binary (web-ready)
mesh.export("model.ply")   # PLY format
mesh.export("model.stl")   # STL (3D printing)
```

## Render Preview Video

```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")

# Render 360 degree video
render_images = model.render(
    scene_codes,
    n_views=30,
    return_type="pil"
)

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

## Gradio Interface

```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="Input 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="Generate 3D models from single images in seconds. Running on CLORE.AI GPU servers."
)

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

## With Mesh Refinement

```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")

# Extract with higher resolution
mesh = model.extract_mesh(
    scene_codes,
    resolution=256  # Higher = more detail, default is 128
)[0]

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

## Performance

| Resolution    | GPU      | Speed | Quality |
| ------------- | -------- | ----- | ------- |
| 128 (default) | RTX 3090 | 0.5s  | Good    |
| 128           | RTX 4090 | 0.3s  | Good    |
| 256           | RTX 4090 | 1.2s  | Better  |
| 256           | A100     | 0.8s  | Better  |

## Common Problems & Solutions

### Poor 3D Quality

**Problem:** Generated mesh looks wrong or distorted

**Solutions:**

* Use images with clear subject and simple background
* Remove background before processing
* Use front-facing view of object
* Ensure good lighting in source image

```python

# Always remove background for best results
from tsr.utils import remove_background

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

### Background Removal Fails

**Problem:** Background removal leaves artifacts

**Solutions:**

* Pre-process with dedicated tool like rembg
* Manually edit image background
* Use images with simple backgrounds

```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")
```

### Out of Memory

**Problem:** CUDA OOM on high resolution

**Solutions:**

```python

# Use lower resolution
mesh = model.extract_mesh(scene_codes, resolution=128)

# Or clear cache between batches
import torch
torch.cuda.empty_cache()
```

### Mesh Has Holes

**Problem:** Generated mesh has missing parts

**Solutions:**

* Use higher resolution extraction
* Try different viewing angle of subject
* Post-process mesh in Blender or MeshLab
* Use images with complete object visibility

### Slow Processing

**Problem:** Takes too long per image

**Solutions:**

* Use batch processing for multiple images
* Lower resolution for prototyping
* Use RTX 4090 or A100 GPU

## Troubleshooting

### 3D mesh quality poor

* Use images with clear object boundaries
* Remove or mask background
* Front-facing views work best

### Export fails

* Check output directory exists
* Verify mesh format is supported
* Ensure enough disk space

### Texture missing

* Some exports don't include texture
* Use GLB format for textured output
* Check material export settings

{% hint style="danger" %}
**Out of memory**
{% endhint %}

* TripoSR is efficient but needs 6GB+
* Reduce output resolution
* Process one image at a time

## Cost Estimate

Typical CLORE.AI marketplace rates (as of 2024):

| GPU       | Hourly Rate | Daily Rate | 4-Hour Session |
| --------- | ----------- | ---------- | -------------- |
| 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        |

*Prices vary by provider and demand. Check* [*CLORE.AI Marketplace*](https://clore.ai/marketplace) *for current rates.*

**Save money:**

* Use **Spot** market for flexible workloads (often 30-50% cheaper)
* Pay with **CLORE** tokens
* Compare prices across different providers

## Next Steps

* Stable Diffusion - Generate input images
* [IC-Light](/guides/image-processing/iclight.md) - Relight images before 3D
* ComfyUI - Workflow integration


---

# 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/3d-generation/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.