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