# 3D-генерация TRELLIS

TRELLIS от Microsoft Research преобразует одиночное RGB-изображение в высококачественную 3D-сетку, гауссов сплат или поле излучения примерно за 30 секунд на RTX 3090. Выпущен под лицензией MIT, полностью бесплатен для коммерческого использования.

{% hint style="success" %}
Все примеры запускаются на GPU-серверах, арендованных через [CLORE.AI Marketplace](https://clore.ai/marketplace).
{% endhint %}

## Ключевые особенности

* **Одиночное изображение → 3D** — не требуются многовидовые съемки, не нужен текстовый подсказ
* **Несколько форматов вывода** — GLB-сетка, Gaussian splat (.ply), поле излучения
* **≈30 секунд на актив** на RTX 3090/4090
* **Лицензия MIT** — бесплатно для коммерческого использования
* **Веб-интерфейс Gradio** включен для взаимодействия через браузер
* **Python API** для интеграции в конвейер и пакетной обработки
* **Zero-shot** — работает с произвольными изображениями без дообучения

## Требования

| Компонент | Минимум        | Рекомендуется  |
| --------- | -------------- | -------------- |
| GPU       | RTX 3090 24 ГБ | RTX 4090 24 ГБ |
| VRAM      | 24 ГБ          | 24 ГБ          |
| ОЗУ       | 32 ГБ          | 64 ГБ          |
| Диск      | 30 GB          | 60 ГБ          |
| CUDA      | 11.8           | 12.1+          |
| Python    | 3.10           | 3.10           |

**Цены Clore.ai:** RTX 4090 ≈ $0.5–2/день · RTX 3090 ≈ $0.3–1/день

TRELLIS требует **24 ГБ VRAM**. RTX 3090 — минимально пригодный GPU.

## Быстрый старт

### 1. Настройте окружение

TRELLIS использует определенные версии зависимостей — настоятельно рекомендуется conda-окружение:

```bash
# Создать и активировать окружение
conda create -n trellis python=3.10 -y
conda activate trellis

# Установить PyTorch с CUDA
pip install torch torchvision --index-url https://download.pytorch.org/whl/cu121

# Клонировать TRELLIS
git clone https://github.com/microsoft/TRELLIS.git
cd TRELLIS

# Установить зависимости
pip install -r requirements.txt

# Установить дополнительные пакеты для экспорта сетки
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

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

Это запустит интерфейс Gradio на `http://0.0.0.0:7860`. С `--share` вы получите публичный URL, доступный из любого браузера, полезно при запуске на безголовом сервере Clore.ai.

Загрузите изображение, настройте параметры генерации и скачайте полученный 3D-актив.

### 3. Использование Python API

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

# Загрузить конвейер (при первом запуске скачиваются веса модели, ~5 ГБ)
pipeline = TrellisImageTo3DPipeline.from_pretrained("JeffreyXiang/TRELLIS-image-large")
pipeline.cuda()

# Сгенерировать 3D из изображения
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. Экспорт в разные форматы

```python
# Экспорт в формате GLB (игровые движки, веб-просмотры)
glb = pipeline.to_glb(
    outputs["gaussian"][0],
    outputs["mesh"][0],
    simplify=0.95,          # уменьшить количество полигонов на 95%
    texture_size=1024,
)
glb.export("output.glb")

# Экспорт Gaussian splat в PLY
outputs["gaussian"][0].save_ply("output.ply")

# Экспорт сетки в OBJ
import trimesh
mesh = trimesh.Trimesh(
    vertices=outputs["mesh"][0].vertices.cpu().numpy(),
    faces=outputs["mesh"][0].faces.cpu().numpy(),
)
mesh.export("output.obj")
```

## Примеры использования

### Пакетная обработка нескольких изображений

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

### Настройка качества генерации

```python
# Более высокое качество (медленнее, ≈60 с)
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,
    },
)

# Быстрый предпросмотр (ниже качество, ≈15 с)
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 для 3D-просмотровщиков

```python
# Сохранить в .ply для просмотрщиков вроде SuperSplat, Luma или рендерера splat для Three.js
outputs["gaussian"][0].save_ply("scene.ply")
```

## Справка по производительности

| GPU      | Шаги (12/12) | Время | Примечания                                 |
| -------- | ------------ | ----- | ------------------------------------------ |
| RTX 4090 | 12 / 12      | ≈25 с | Лучшее соотношение цена/производительность |
| RTX 3090 | 12 / 12      | ≈35 с | Минимум для TRELLIS                        |
| A100 40G | 12 / 12      | ≈20 с | Вариант для дата-центра                    |

## Советы

* **Используйте PNG с чистым фоном** — удалите фон с помощью `rembg` перед подачей в TRELLIS для лучшего качества сетки
* **`simplify=0.95`** в экспорте GLB уменьшает количество полигонов на 95% при сохранении визуального качества — важно для веба/игр
* **Установите `--share`** при запуске Gradio UI на Clore.ai, чтобы получить публичный URL
* **Консистентность seed** — зафиксируйте `seed` для воспроизводимых результатов между запусками
* **Разрешение текстуры** — используйте `texture_size=2048` для текстур печатного качества, `1024` для приложений реального времени
* **При первом запуске скачивается \~5 ГБ** весов модели — убедитесь, что достаточно места на диске
* **Gaussian splats** идеальны для рендеринга в реальном времени; GLB-сетки лучше подходят для игровых движков и 3D-печати

## Устранение неполадок

| Проблема                      | Решение                                                                         |
| ----------------------------- | ------------------------------------------------------------------------------- |
| `CUDA — недостаточно памяти`  | TRELLIS требует 24 ГБ VRAM — используйте RTX 3090/4090 или A100                 |
| `kaolin` установка не удалась | Точно сопоставьте версию kaolin с вашей версией PyTorch + CUDA                  |
| `spconv` ошибка импорта       | Установите правильную версию CUDA: `pip install spconv-cu121`                   |
| Gradio UI недоступен          | Используйте `--share` для публичного туннеля или откройте порт 7860 на Clore.ai |
| Плохое качество сетки         | Убедитесь, что у входного изображения чистый/удаленный фон                      |
| Медленная первая генерация    | Скачивание весов модели при первом запуске — последующие запуски быстрые        |
| Экспорт GLB не удался         | Убедитесь, что установлены `trimesh` и `pygltflib` установлены                  |

## Ресурсы

* [TRELLIS на GitHub](https://github.com/microsoft/TRELLIS)
* [Статья: Structured 3D Latents for Scalable 3D Generation](https://arxiv.org/abs/2412.01506)
* [CLORE.AI Marketplace](https://clore.ai/marketplace)