# 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)


---

# 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-ru/generaciya-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.