# TRELLIS 3D Generation

TRELLIS by Microsoft Research converts a single RGB image into a high-quality 3D mesh, Gaussian splat, or radiance field in roughly 30 seconds on an RTX 3090. Released under the MIT license, it is fully free for commercial use.

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

## Key Features

* **Single image → 3D** — no multi-view captures, no text prompt required
* **Multiple output formats** — GLB mesh, Gaussian splat (.ply), radiance field
* **\~30 seconds per asset** on RTX 3090/4090
* **MIT license** — free for commercial use
* **Gradio web UI** included for browser-based interaction
* **Python API** for pipeline integration and batch processing
* **Zero-shot** — works on arbitrary images without fine-tuning

## Requirements

| Component | Minimum        | Recommended    |
| --------- | -------------- | -------------- |
| GPU       | RTX 3090 24 GB | RTX 4090 24 GB |
| VRAM      | 24 GB          | 24 GB          |
| RAM       | 32 GB          | 64 GB          |
| Disk      | 30 GB          | 60 GB          |
| CUDA      | 11.8           | 12.1+          |
| Python    | 3.10           | 3.10           |

**Clore.ai pricing:** RTX 4090 ≈ $0.5–2/day · RTX 3090 ≈ $0.3–1/day

TRELLIS requires **24 GB VRAM**. An RTX 3090 is the minimum viable GPU.

## Quick Start

### 1. Set Up the Environment

TRELLIS uses specific dependency versions — a conda environment is strongly recommended:

```bash
# Create and activate environment
conda create -n trellis python=3.10 -y
conda activate trellis

# Install PyTorch with CUDA
pip install torch torchvision --index-url https://download.pytorch.org/whl/cu121

# Clone TRELLIS
git clone https://github.com/microsoft/TRELLIS.git
cd TRELLIS

# Install dependencies
pip install -r requirements.txt

# Install additional packages for mesh export
pip install kaolin -f https://nvidia-kaolin.s3.us-east-2.amazonaws.com/torch-2.1.0_cu121.html
pip install spconv-cu121
```

### 2. Run the Gradio Web UI

```bash
python app.py --share
```

This launches a Gradio interface on `http://0.0.0.0:7860`. With `--share` you get a public URL accessible from any browser, useful when running on a headless Clore.ai server.

Upload an image, adjust generation parameters, and download the resulting 3D asset.

### 3. Use the Python API

```python
from trellis.pipelines import TrellisImageTo3DPipeline
from PIL import Image

# Load the pipeline (downloads model weights on first run, ~5 GB)
pipeline = TrellisImageTo3DPipeline.from_pretrained("JeffreyXiang/TRELLIS-image-large")
pipeline.cuda()

# Generate 3D from an image
image = Image.open("input.png")
outputs = pipeline.run(
    image,
    seed=42,
    sparse_structure_sampler_params={
        "steps": 12,
        "cfg_strength": 7.5,
    },
    slat_sampler_params={
        "steps": 12,
        "cfg_strength": 3.0,
    },
)
```

### 4. Export to Different Formats

```python
# Export as GLB mesh (game engines, web viewers)
glb = pipeline.to_glb(
    outputs["gaussian"][0],
    outputs["mesh"][0],
    simplify=0.95,          # reduce polygon count by 95%
    texture_size=1024,
)
glb.export("output.glb")

# Export Gaussian splat as PLY
outputs["gaussian"][0].save_ply("output.ply")

# Export mesh as OBJ
import trimesh
mesh = trimesh.Trimesh(
    vertices=outputs["mesh"][0].vertices.cpu().numpy(),
    faces=outputs["mesh"][0].faces.cpu().numpy(),
)
mesh.export("output.obj")
```

## Usage Examples

### Batch Processing Multiple Images

```python
import glob
from pathlib import Path

input_dir = Path("/workspace/input-images")
output_dir = Path("/workspace/3d-output")
output_dir.mkdir(exist_ok=True)

for img_path in sorted(input_dir.glob("*.png")):
    image = Image.open(img_path)
    outputs = pipeline.run(image, seed=42)

    glb = pipeline.to_glb(
        outputs["gaussian"][0],
        outputs["mesh"][0],
        simplify=0.95,
        texture_size=1024,
    )
    glb.export(str(output_dir / f"{img_path.stem}.glb"))
    print(f"Exported: {img_path.stem}.glb")
```

### Adjusting Generation Quality

```python
# Higher quality (slower, ~60 sec)
outputs = pipeline.run(
    image,
    seed=42,
    sparse_structure_sampler_params={
        "steps": 20,
        "cfg_strength": 9.0,
    },
    slat_sampler_params={
        "steps": 20,
        "cfg_strength": 4.5,
    },
)

# Fast preview (lower quality, ~15 sec)
outputs = pipeline.run(
    image,
    seed=42,
    sparse_structure_sampler_params={
        "steps": 6,
        "cfg_strength": 7.5,
    },
    slat_sampler_params={
        "steps": 6,
        "cfg_strength": 3.0,
    },
)
```

### Extract Gaussian Splat for 3D Viewers

```python
# Save as .ply for viewers like SuperSplat, Luma, or Three.js splat renderer
outputs["gaussian"][0].save_ply("scene.ply")
```

## Performance Reference

| GPU      | Steps (12/12) | Time     | Notes                  |
| -------- | ------------- | -------- | ---------------------- |
| RTX 4090 | 12 / 12       | \~25 sec | Best price/performance |
| RTX 3090 | 12 / 12       | \~35 sec | Minimum for TRELLIS    |
| A100 40G | 12 / 12       | \~20 sec | Datacenter option      |

## Tips

* **Use PNG with clean backgrounds** — remove background with `rembg` before feeding to TRELLIS for best mesh quality
* **`simplify=0.95`** in GLB export reduces polygon count by 95% while preserving visual quality — essential for web/game use
* **Set `--share`** when running the Gradio UI on Clore.ai to get a public URL
* **Seed consistency** — fix `seed` for reproducible outputs across runs
* **Texture resolution** — use `texture_size=2048` for print-quality textures, `1024` for real-time applications
* **First run downloads \~5 GB** of model weights — ensure enough disk space
* **Gaussian splats** are ideal for real-time rendering; GLB meshes are better for game engines and 3D printing

## Troubleshooting

| Problem                  | Solution                                                           |
| ------------------------ | ------------------------------------------------------------------ |
| `CUDA out of memory`     | TRELLIS needs 24 GB VRAM — use RTX 3090/4090 or A100               |
| `kaolin` install fails   | Match kaolin version to your PyTorch + CUDA version exactly        |
| `spconv` import error    | Install the correct CUDA version: `pip install spconv-cu121`       |
| Gradio UI not accessible | Use `--share` for a public tunnel, or expose port 7860 on Clore.ai |
| Poor mesh quality        | Ensure input image has a clean/removed background                  |
| Slow first generation    | Model weights download on first run — subsequent runs are fast     |
| Export GLB fails         | Ensure `trimesh` and `pygltflib` are installed                     |

## Resources

* [TRELLIS GitHub](https://github.com/microsoft/TRELLIS)
* [Paper: Structured 3D Latents for Scalable 3D Generation](https://arxiv.org/abs/2412.01506)
* [CLORE.AI Marketplace](https://clore.ai/marketplace)


---

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