# Generación 3D TRELLIS

TRELLIS de Microsoft Research convierte una sola imagen RGB en una malla 3D de alta calidad, un Gaussian splat o un campo de radiancia en aproximadamente 30 segundos en una RTX 3090. Lanzado bajo la licencia MIT, es totalmente gratuito para uso comercial.

{% hint style="success" %}
Todos los ejemplos se ejecutan en servidores GPU alquilados a través de [CLORE.AI Marketplace](https://clore.ai/marketplace).
{% endhint %}

## Características clave

* **Imagen única → 3D** — sin capturas multivista, no se requiere indicación de texto
* **Múltiples formatos de salida** — malla GLB, Gaussian splat (.ply), campo de radiancia
* **\~30 segundos por activo** en RTX 3090/4090
* **Licencia MIT** — gratis para uso comercial
* **Interfaz web Gradio** incluida para interacción basada en navegador
* **API de Python** para integración en pipelines y procesamiento por lotes
* **Zero-shot** — funciona con imágenes arbitrarias sin ajuste fino

## Requisitos

| Componente | Mínimo         | Recomendado    |
| ---------- | -------------- | -------------- |
| GPU        | RTX 3090 24 GB | RTX 4090 24 GB |
| VRAM       | 24 GB          | 24 GB          |
| RAM        | 32 GB          | 64 GB          |
| Disco      | 30 GB          | 60 GB          |
| CUDA       | 11.8           | 12.1+          |
| Python     | 3.10           | 3.10           |

**Precios de Clore.ai:** RTX 4090 ≈ $0.5–2/día · RTX 3090 ≈ $0.3–1/día

TRELLIS requiere **24 GB de VRAM**. Una RTX 3090 es la GPU mínima viable.

## Inicio rápido

### 1. Configurar el entorno

TRELLIS usa versiones específicas de dependencias — se recomienda encarecidamente un entorno conda:

```bash
# Crear y activar el entorno
conda create -n trellis python=3.10 -y
conda activate trellis

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

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

# Instalar dependencias
pip install -r requirements.txt

# Instalar paquetes adicionales para exportar mallas
pip install kaolin -f https://nvidia-kaolin.s3.us-east-2.amazonaws.com/torch-2.1.0_cu121.html
pip install spconv-cu121
```

### 2. Ejecutar la interfaz web Gradio

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

Esto lanza una interfaz Gradio en `http://0.0.0.0:7860`. Con `--share` obtienes una URL pública accesible desde cualquier navegador, útil cuando se ejecuta en un servidor Clore.ai sin interfaz gráfica.

Sube una imagen, ajusta los parámetros de generación y descarga el activo 3D resultante.

### 3. Usar la API de Python

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

# Cargar el pipeline (descarga los pesos del modelo en la primera ejecución, ~5 GB)
pipeline = TrellisImageTo3DPipeline.from_pretrained("JeffreyXiang/TRELLIS-image-large")
pipeline.cuda()

# Generar 3D a partir de una imagen
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. Exportar a diferentes formatos

```python
# Exportar como malla GLB (motores de juego, visores web)
glb = pipeline.to_glb(
    outputs["gaussian"][0],
    outputs["mesh"][0],
    simplify=0.95,          # reducir el recuento de polígonos en un 95%
    texture_size=1024,
)
glb.export("output.glb")

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

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

## Ejemplos de uso

### Procesamiento por lotes de múltiples imágenes

```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"Exportado: {img_path.stem}.glb")
```

### Ajuste de la calidad de generación

```python
# Calidad más alta (más lento, ~60 s)
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,
    },
)

# Vista previa rápida (calidad inferior, ~15 s)
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,
    },
)
```

### Extraer Gaussian Splat para visores 3D

```python
# Guardar como .ply para visores como SuperSplat, Luma o el renderizador splat de Three.js
outputs["gaussian"][0].save_ply("scene.ply")
```

## Referencia de rendimiento

| GPU      | Pasos (12/12) | Tiempo | Notas                             |
| -------- | ------------- | ------ | --------------------------------- |
| RTX 4090 | 12 / 12       | \~25 s | Mejor relación precio/rendimiento |
| RTX 3090 | 12 / 12       | \~35 s | Mínimo para TRELLIS               |
| A100 40G | 12 / 12       | \~20 s | Opción de centro de datos         |

## Consejos

* **Usa PNG con fondos limpios** — eliminar el fondo con `rembg` antes de alimentar a TRELLIS para la mejor calidad de malla
* **`simplify=0.95`** en la exportación GLB reduce el número de polígonos en un 95% preservando la calidad visual — esencial para uso web/juegos
* **Establecer `--share`** al ejecutar la UI de Gradio en Clore.ai para obtener una URL pública
* **Consistencia de la semilla** — fijar `seed` para salidas reproducibles entre ejecuciones
* **Resolución de textura** — usar `texture_size=2048` para texturas de calidad de impresión, `1024` para aplicaciones en tiempo real
* **La primera ejecución descarga \~5 GB** de pesos del modelo — asegúrate de tener suficiente espacio en disco
* **Gaussian splats** son ideales para renderizado en tiempo real; las mallas GLB son mejores para motores de juego e impresión 3D

## Solución de problemas

| Problema                           | Solución                                                                                       |
| ---------------------------------- | ---------------------------------------------------------------------------------------------- |
| `CUDA fuera de memoria`            | TRELLIS necesita 24 GB de VRAM — usa RTX 3090/4090 o A100                                      |
| `kaolin` la instalación falla      | Coincide la versión de kaolin con tu versión de PyTorch + CUDA exactamente                     |
| `spconv` error de importación      | Instala la versión correcta de CUDA: `pip install spconv-cu121`                                |
| La interfaz Gradio no es accesible | Usa `--share` para un túnel público, o expón el puerto 7860 en Clore.ai                        |
| Mala calidad de la malla           | Asegúrate de que la imagen de entrada tenga un fondo limpio/removido                           |
| Primera generación lenta           | Descarga de pesos del modelo en la primera ejecución — las ejecuciones posteriores son rápidas |
| Fallo al exportar GLB              | Asegúrate de `trimesh` y `pygltflib` estén instalados                                          |

## Recursos

* [TRELLIS en GitHub](https://github.com/microsoft/TRELLIS)
* [Artículo: Latentes 3D Estructurados para Generación 3D Escalable](https://arxiv.org/abs/2412.01506)
* [CLORE.AI Marketplace](https://clore.ai/marketplace)