# TRELLIS 3D-Generierung

TRELLIS von Microsoft Research verwandelt ein einzelnes RGB-Bild in ungefähr 30 Sekunden auf einer RTX 3090 in ein hochwertiges 3D-Mesh, einen Gaussian-Splat oder ein Strahlungsfeld. Unter der MIT-Lizenz veröffentlicht, ist es vollständig kostenlos für kommerzielle Nutzung.

{% hint style="success" %}
Alle Beispiele laufen auf GPU-Servern, die über die [CLORE.AI Marketplace](https://clore.ai/marketplace).
{% endhint %}

## Hauptmerkmale

* **Einzelbild → 3D** — keine Mehrfachansichten erforderlich, kein Textprompt nötig
* **Mehrere Ausgabeformate** — GLB-Mesh, Gaussian Splat (.ply), Strahlungsfeld
* **\~30 Sekunden pro Asset** auf RTX 3090/4090
* **MIT-Lizenz** — kostenlos für kommerzielle Nutzung
* **Gradio Web-UI** enthalten für browserbasierte Interaktion
* **Python-API** für Pipeline-Integration und Stapelverarbeitung
* **Zero-shot** — funktioniert mit beliebigen Bildern ohne Feinabstimmung

## Anforderungen

| Komponente | Minimum        | Empfohlen      |
| ---------- | -------------- | -------------- |
| GPU        | RTX 3090 24 GB | RTX 4090 24 GB |
| VRAM       | 24 GB          | 24 GB          |
| RAM        | 32 GB          | 64 GB          |
| Festplatte | 30 GB          | 60 GB          |
| CUDA       | 11.8           | 12.1+          |
| Python     | 3.10           | 3.10           |

**Clore.ai-Preise:** RTX 4090 ≈ $0.5–2/Tag · RTX 3090 ≈ $0.3–1/Tag

TRELLIS benötigt **24 GB VRAM**. Eine RTX 3090 ist die minimal brauchbare GPU.

## Schnellstart

### 1. Umgebung einrichten

TRELLIS verwendet spezifische Abhängigkeitsversionen — eine conda-Umgebung wird dringend empfohlen:

```bash
# Umgebung erstellen und aktivieren
conda create -n trellis python=3.10 -y
conda activate trellis

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

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

# Abhängigkeiten installieren
pip install -r requirements.txt

# Zusätzliche Pakete für den Mesh-Export installieren
pip install kaolin -f https://nvidia-kaolin.s3.us-east-2.amazonaws.com/torch-2.1.0_cu121.html
pip install spconv-cu121
```

### 2. Gradio Web-UI starten

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

Dies startet eine Gradio-Oberfläche unter `http://0.0.0.0:7860`. Mit `--share` erhalten Sie eine öffentliche URL, die von jedem Browser aus zugänglich ist, nützlich beim Betrieb auf einem headless Clore.ai-Server.

Laden Sie ein Bild hoch, passen Sie die Generierungsparameter an und laden Sie das resultierende 3D-Asset herunter.

### 3. Die Python-API verwenden

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

# Pipeline laden (lädt Modellgewichte beim ersten Lauf herunter, ~5 GB)
pipeline = TrellisImageTo3DPipeline.from_pretrained("JeffreyXiang/TRELLIS-image-large")
pipeline.cuda()

# 3D aus einem Bild generieren
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. In verschiedene Formate exportieren

```python
# Als GLB-Mesh exportieren (Spiel-Engines, Web-Viewer)
glb = pipeline.to_glb(
    outputs["gaussian"][0],
    outputs["mesh"][0],
    simplify=0.95,          # Polygonanzahl um 95% reduzieren
    texture_size=1024,
)
glb.export("output.glb")

# Gaussian Splat als PLY exportieren
outputs["gaussian"][0].save_ply("output.ply")

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

## Beispielanwendungen

### Stapelverarbeitung mehrerer Bilder

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

### Anpassung der Generierungsqualität

```python
# Höhere Qualität (langsamer, ~60 Sek.)
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,
    },
)

# Schnelle Vorschau (niedrigere Qualität, ~15 Sek.)
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,
    },
)
```

### Gaussian Splat für 3D-Viewer extrahieren

```python
# Als .ply für Viewer wie SuperSplat, Luma oder Three.js Splat-Renderer speichern
outputs["gaussian"][0].save_ply("scene.ply")
```

## Performance-Referenz

| GPU      | Schritte (12/12) | Zeit      | Hinweise                          |
| -------- | ---------------- | --------- | --------------------------------- |
| RTX 4090 | 12 / 12          | \~25 Sek. | Bestes Preis-/Leistungsverhältnis |
| RTX 3090 | 12 / 12          | \~35 Sek. | Minimum für TRELLIS               |
| A100 40G | 12 / 12          | \~20 Sek. | Rechenzentrum-Option              |

## Tipps

* **Verwenden Sie PNG mit sauberem Hintergrund** — Hintergrund entfernen mit `rembg` vor dem Einspeisen in TRELLIS für beste Mesh-Qualität
* **`simplify=0.95`** im GLB-Export reduziert die Polygonanzahl um 95% bei Erhalt der visuellen Qualität — essenziell für Web-/Spielanwendungen
* **Setzen Sie `--share`** bei Ausführung der Gradio-UI auf Clore.ai, um eine öffentliche URL zu erhalten
* **Seed-Konsistenz** — festen `seed` für reproduzierbare Ergebnisse zwischen Läufen
* **Texturauflösung** — verwenden Sie `texture_size=2048` für druckqualitätsfähige Texturen, `1024` für Echtzeitanwendungen
* **Erster Lauf lädt \~5 GB herunter** an Modellgewichten — stellen Sie genügend Festplattenspeicher sicher
* **Gaussian Splats** sind ideal für Echtzeit-Rendering; GLB-Meshes sind besser für Spiel-Engines und 3D-Druck

## Fehlerbehebung

| Problem                            | Lösung                                                                                        |
| ---------------------------------- | --------------------------------------------------------------------------------------------- |
| `CUDA out of memory`               | TRELLIS benötigt 24 GB VRAM — verwenden Sie RTX 3090/4090 oder A100                           |
| `kaolin` Installation schlägt fehl | Passen Sie die kaolin-Version genau an Ihre PyTorch- + CUDA-Version an                        |
| `spconv` Importfehler              | Installieren Sie die korrekte CUDA-Version: `pip install spconv-cu121`                        |
| Gradio-UI nicht zugänglich         | Verwenden Sie `--share` für einen öffentlichen Tunnel, oder öffnen Sie Port 7860 auf Clore.ai |
| Schlechte Mesh-Qualität            | Stellen Sie sicher, dass das Eingabebild einen sauberen/entfernten Hintergrund hat            |
| Langsame erste Generierung         | Modellgewichte werden beim ersten Lauf heruntergeladen — nachfolgende Läufe sind schnell      |
| GLB-Export schlägt fehl            | Stellen Sie sicher, dass `trimesh` und `pygltflib` installiert sind                           |

## Ressourcen

* [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)