# Génération 3D TRELLIS

TRELLIS de Microsoft Research convertit une seule image RGB en un maillage 3D de haute qualité, en un splat gaussien ou en un champ de radiance en environ 30 secondes sur une RTX 3090. Publié sous licence MIT, il est entièrement gratuit pour un usage commercial.

{% hint style="success" %}
Tous les exemples s'exécutent sur des serveurs GPU loués via le [CLORE.AI Marketplace](https://clore.ai/marketplace).
{% endhint %}

## Principales caractéristiques

* **Image unique → 3D** — pas de captures multi-vues, pas d'invite textuelle requise
* **Formats de sortie multiples** — maillage GLB, splat gaussien (.ply), champ de radiance
* **\~30 secondes par asset** sur RTX 3090/4090
* **Licence MIT** — gratuit pour un usage commercial
* **Interface web Gradio** incluse pour l'interaction via navigateur
* **API Python** pour l'intégration en pipeline et le traitement par lot
* **Zéro-shot** — fonctionne sur des images arbitraires sans affinement

## Exigences

| Composant | Minimum        | Recommandé     |
| --------- | -------------- | -------------- |
| GPU       | RTX 3090 24 Go | RTX 4090 24 Go |
| VRAM      | 24 Go          | 24 Go          |
| RAM       | 32 Go          | 64 Go          |
| Disque    | 30 Go          | 60 Go          |
| CUDA      | 11.8           | 12.1+          |
| Python    | 3.10           | 3.10           |

**Tarifs Clore.ai :** RTX 4090 ≈ 0,5–2 $/jour · RTX 3090 ≈ 0,3–1 $/jour

TRELLIS nécessite **24 Go de VRAM**. Une RTX 3090 est le GPU viable minimum.

## Démarrage rapide

### 1. Configurer l'environnement

TRELLIS utilise des versions spécifiques des dépendances — un environnement conda est fortement recommandé :

```bash
# Créer et activer l'environnement
conda create -n trellis python=3.10 -y
conda activate trellis

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

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

# Installer les dépendances
pip install -r requirements.txt

# Installer des paquets supplémentaires pour l'export de maillage
pip install kaolin -f https://nvidia-kaolin.s3.us-east-2.amazonaws.com/torch-2.1.0_cu121.html
pip install spconv-cu121
```

### 2. Lancer l'interface web Gradio

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

Cela lance une interface Gradio sur `http://0.0.0.0:7860`. Avec `--share` vous obtenez une URL publique accessible depuis n'importe quel navigateur, utile lors d'une exécution sur un serveur Clore.ai sans tête.

Téléchargez une image, ajustez les paramètres de génération et téléchargez l'asset 3D résultant.

### 3. Utiliser l'API Python

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

# Charger le pipeline (télécharge les poids du modèle lors de la première exécution, ~5 Go)
pipeline = TrellisImageTo3DPipeline.from_pretrained("JeffreyXiang/TRELLIS-image-large")
pipeline.cuda()

# Générer du 3D à partir d'une 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. Exporter vers différents formats

```python
# Exporter en maillage GLB (moteurs de jeu, visionneuses web)
glb = pipeline.to_glb(
    outputs["gaussian"][0],
    outputs["mesh"][0],
    simplify=0.95,          # réduire le nombre de polygones de 95%
    texture_size=1024,
)
glb.export("output.glb")

# Exporter le splat gaussien en PLY
outputs["gaussian"][0].save_ply("output.ply")

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

## Exemples d'utilisation

### Traitement par lot de plusieurs 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")
```

### Ajustement de la qualité de génération

```python
# Qualité supérieure (plus lent, ~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,
    },
)

# Prévisualisation rapide (qualité inférieure, ~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,
    },
)
```

### Extraire le splat gaussien pour les visionneuses 3D

```python
# Enregistrer en .ply pour des visionneuses comme SuperSplat, Luma ou le rendu splat de Three.js
outputs["gaussian"][0].save_ply("scene.ply")
```

## Référence de performance

| GPU      | Étapes (12/12) | Temps    | Remarques                         |
| -------- | -------------- | -------- | --------------------------------- |
| RTX 4090 | 12 / 12        | \~25 sec | Meilleur rapport prix/performance |
| RTX 3090 | 12 / 12        | \~35 sec | Minimum pour TRELLIS              |
| A100 40G | 12 / 12        | \~20 sec | Option datacenter                 |

## Conseils

* **Utilisez PNG avec des arrière-plans propres** — supprimer l'arrière-plan avec `rembg` avant de l'alimenter à TRELLIS pour une meilleure qualité de maillage
* **`simplify=0.95`** dans l'export GLB réduit le nombre de polygones de 95 % tout en préservant la qualité visuelle — essentiel pour une utilisation web/jeu
* **Définir `--share`** lors de l'exécution de l'UI Gradio sur Clore.ai pour obtenir une URL publique
* **Consistance du seed** — fixer `seed` pour des sorties reproductibles entre exécutions
* **Résolution des textures** — utiliser `texture_size=2048` pour des textures de qualité imprimable, `1024` pour des applications temps réel
* **Le premier lancement télécharge \~5 Go** de poids de modèle — assurez-vous d'avoir suffisamment d'espace disque
* **Les splats gaussiens** sont idéaux pour le rendu en temps réel ; les maillages GLB sont mieux adaptés aux moteurs de jeu et à l'impression 3D

## Dépannage

| Problème                         | Solution                                                                                                 |
| -------------------------------- | -------------------------------------------------------------------------------------------------------- |
| `CUDA out of memory`             | TRELLIS nécessite 24 Go de VRAM — utilisez RTX 3090/4090 ou A100                                         |
| `kaolin` échec de l'installation | Faites correspondre la version de kaolin exactement à votre version de PyTorch + CUDA                    |
| `spconv` erreur d'importation    | Installez la bonne version de CUDA : `pip install spconv-cu121`                                          |
| UI Gradio inaccessible           | Utilisez `--share` pour un tunnel public, ou exposez le port 7860 sur Clore.ai                           |
| Mauvaise qualité de maillage     | Assurez-vous que l'image d'entrée a un arrière-plan propre/supprimé                                      |
| Première génération lente        | Téléchargement des poids du modèle lors de la première exécution — les exécutions suivantes sont rapides |
| Échec de l'export GLB            | Assurez-vous que `trimesh` et `pygltflib` sont installés                                                 |

## Ressources

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