# 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](https://docs.clore.ai/guides/image-processing/iclight) - Relight images before 3D
* ComfyUI - Workflow integration