# Generación 3D con 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)


---

# 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/guides_v2-es/generacion-3d/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.