# 3D Gaussian Splatting

**3D Gaussian Splatting** — революционная технология реконструкции 3D-сцен в реальном времени с более чем **15 000 звёзд на GitHub**. В отличие от методов на основе NeRF, Gaussian Splatting представляет сцены как миллионы крошечных 3D-гауссианов, которые можно рендерить с **частотой кадров в реальном времени** (100+ FPS) при получении фотореалистичного качества. Разверните её в GPU-облаке Clore.ai, чтобы реконструировать и исследовать 3D-сцены по собственным фотографиям.

***

## Что такое 3D Gaussian Splatting?

Традиционные методы NeRF неявно кодируют сцену в нейронной сети, требуя построчной трассировки лучей при рендеринге. Gaussian Splatting использует принципиально другой подход:

1. **Инициализация:** Начинается с разреженного облака точек (из COLMAP)
2. **Представление:** Каждая точка расширяется в 3D-гауссиан с позицией, масштабом, вращением, непрозрачностью и цветом в виде сферических гармоник
3. **Оптимизация:** Дифференцируемо рендерить гауссианы и оптимизировать их относительно обучающих изображений
4. **Рендеринг:** Проецировать гауссианы на плоскость изображения с помощью альфа-композитинга (чрезвычайно быстро)

**Ключевые преимущества перед NeRF:**

* Рендеринг в реальном времени (100+ FPS при 1080p)
* Лучшее восстановление мелких деталей
* Явное 3D-представление (редактируемое, экспортируемое)
* Быстрое обучение (30–60 мин против часов)
* Работает на потребительских GPU

***

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

| Требование | Минимум       | Рекомендуется   |
| ---------- | ------------- | --------------- |
| VRAM GPU   | 12 ГБ         | 24 ГБ           |
| GPU        | RTX 3080 12GB | RTX 4090 / A100 |
| ОЗУ        | 16 ГБ         | 32 ГБ           |
| Хранилище  | 30 ГБ         | 60 ГБ           |
| CUDA       | 11.7+         | 12.1+           |

{% hint style="warning" %}
Gaussian Splatting предъявляет строгие требования к CUDA. Версия CUDA должна совпадать с `diff-gaussian-rasterization` скомпилированным расширением. Использование приведённого Dockerfile устраняет проблемы совместимости.
{% endhint %}

***

## Шаг 1 — Арендуйте GPU на Clore.ai

1. Войдите в [clore.ai](https://clore.ai).
2. Нажмите **Маркетплейс** и отфильтруйте по видеопамяти VRAM ≥ 16 ГБ.
3. Выберите сервер — RTX 4090 предлагает лучшее соотношение цена/производительность.
4. Установите Docker-образ на ваш кастомный образ (см. Шаг 2).
5. Установите открытые порты: `22` (SSH) и `8080` (веб-просмотрщик).
6. Нажмите **Арендовать**.

***

## Шаг 2 — Dockerfile

Соберите собственный Docker-образ со всеми зависимостями:

```dockerfile
FROM pytorch/pytorch:2.1.2-cuda12.1-cudnn8-devel

ENV DEBIAN_FRONTEND=noninteractive
ENV TORCH_CUDA_ARCH_LIST="6.0;6.1;7.0;7.5;8.0;8.6;8.9;9.0+PTX"

RUN apt-get update && apt-get install -y \
    git wget curl cmake build-essential \
    libboost-program-options-dev libboost-filesystem-dev \
    libboost-graph-dev libboost-system-dev libboost-test-dev \
    libeigen3-dev libflann-dev libfreeimage-dev \
    libmetis-dev libgoogle-glog-dev libgflags-dev \
    libsqlite3-dev libglew-dev qtbase5-dev libqt5opengl5-dev \
    libcgal-dev libceres-dev \
    ffmpeg libgl1 libglib2.0-0 \
    openssh-server \
    python3-pip python3-dev \
    && rm -rf /var/lib/apt/lists/*

# Установить COLMAP
RUN apt-get update && apt-get install -y colmap && rm -rf /var/lib/apt/lists/*

# Настроить SSH
RUN mkdir /var/run/sshd && \
    echo 'root:clore123' | chpasswd && \
    sed -i 's/#PermitRootLogin prohibit-password/PermitRootLogin yes/' /etc/ssh/sshd_config

WORKDIR /workspace

# Клонировать оригинальный репозиторий 3DGS
RUN git clone https://github.com/graphdeco-inria/gaussian-splatting /workspace/gaussian-splatting \
    --recursive

# Установить зависимости Python
RUN cd /workspace/gaussian-splatting && \
    pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121 && \
    pip install -r requirements.txt

# Собрать CUDA-расширения
RUN cd /workspace/gaussian-splatting && \
    pip install submodules/diff-gaussian-rasterization && \
    pip install submodules/simple-knn

# Установить зависимости веб-просмотрщика
RUN pip install viser==0.1.29 nerfview==0.0.4 trimesh

EXPOSE 22 8080

CMD service ssh start && tail -f /dev/null
```

### Сборка и отправка

Соберите образ и отправьте его в ваш аккаунт Docker Hub (замените `YOUR_DOCKERHUB_USERNAME` на ваш фактический логин):

```bash
docker build -t YOUR_DOCKERHUB_USERNAME/gaussian-splatting:latest .
docker push YOUR_DOCKERHUB_USERNAME/gaussian-splatting:latest
```

{% hint style="info" %}
Официального предсобранного Docker-образа для 3D Gaussian Splatting на Docker Hub нет. Официальный репозиторий [graphdeco-inria/gaussian-splatting](https://github.com/graphdeco-inria/gaussian-splatting) не предоставляет его — собирайте из приведённого Dockerfile. Образ должен быть собран с правильными флагами архитектуры CUDA, соответствующими целевому GPU.
{% endhint %}

Используйте `YOUR_DOCKERHUB_USERNAME/gaussian-splatting:latest` в вашей конфигурации Clore.ai.

***

## Шаг 3 — Подключитесь по SSH

```bash
ssh root@<clore-host> -p <assigned-ssh-port>
```

Проверьте сборку:

```bash
cd /workspace/gaussian-splatting
python -c "from diff_gaussian_rasterization import GaussianRasterizationSettings; print('CUDA extension OK')"
```

***

## Шаг 4 — Подготовьте ваш набор данных

### Вариант A: Использовать набор данных Tandt (Tanks and Temples)

Классический эталонный набор для быстрого тестирования:

```bash
mkdir -p /workspace/data && cd /workspace/data

# Скачать небольшой тестовый сцену
wget https://repo-sam.inria.fr/fungraph/3d-gaussian-splatting/datasets/input/tandt.zip
unzip tandt.zip
```

### Вариант B: Обработать собственные фотографии

```bash
# Загрузить фотографии
scp -P <port> -r ./my_photos/ root@<clore-host>:/workspace/data/

# Запустить скрипт обработки COLMAP (входит в комплект 3DGS)
cd /workspace/gaussian-splatting

python convert.py \
    -s /workspace/data/my_photos \
    --no_gpu   # опционально: если решатель COLMAP на GPU конфликтует
```

{% hint style="info" %}
Параметр `convert.py` скрипт запускает полный конвейер COLMAP: извлечение признаков, сопоставление, разреженную реконструкцию и устранение искажений. Это занимает 5–30 минут в зависимости от количества изображений.
{% endhint %}

### Вариант C: Обработка из видео

```bash
# Извлечь кадры из видео с частотой 2 кадра в секунду
ffmpeg -i /workspace/data/my_video.mp4 \
    -vf fps=2 \
    /workspace/data/frames/frame_%04d.jpg

# Затем запустить обработку COLMAP на кадрах
python convert.py -s /workspace/data/frames
```

***

## Шаг 5 — Обучение Gaussian Splat

### Стандартное обучение

```bash
cd /workspace/gaussian-splatting

python train.py \
    -s /workspace/data/my_photos \
    -m /workspace/output/my_scene \
    --iterations 30000 \
    --eval
```

### Обучение на наборе Tandt

```bash
python train.py \
    -s /workspace/data/tandt/truck \
    -m /workspace/output/truck \
    --iterations 30000 \
    --eval
```

### Быстрое обучение (быстрый предварительный просмотр)

```bash
python train.py \
    -s /workspace/data/my_photos \
    -m /workspace/output/my_scene_fast \
    --iterations 7000
```

{% hint style="info" %}
Обучение до 7 000 итераций занимает примерно 10 минут на RTX 4090 и даёт качественный предварительный просмотр. Полные 30 000 итераций занимают \~30–40 минут и дают итоговое качество.
{% endhint %}

### Прогресс обучения

Отслеживайте вывод обучения — вы увидите такие метрики, как:

```
[ITER 1000] Evaluating train: L1 0.04, PSNR 26.12 dB
[ITER 7000] Evaluating train: L1 0.02, PSNR 29.45 dB
[ITER 30000] Evaluating train: L1 0.01, PSNR 32.80 dB
```

PSNR выше 30 дБ указывает на высококачественную реконструкцию.

***

## Шаг 6 — Рендеринг и визуализация

### Рендеринг из обученной модели

```bash
python render.py \
    -m /workspace/output/my_scene \
    --skip_train
```

Рендеры сохраняются в `/workspace/output/my_scene/test/ours_30000/renders/`.

### Создать видео пролёта (Flythrough)

```bash
# Конвертировать отрендеренные кадры в видео
ffmpeg -framerate 24 \
    -pattern_type glob \
    -i '/workspace/output/my_scene/test/ours_30000/renders/*.png' \
    -c:v libx264 \
    -pix_fmt yuv420p \
    /workspace/output/flythrough.mp4
```

### Оценить метрики

```bash
python metrics.py -m /workspace/output/my_scene
```

Ожидаемый вывод:

```
SSIM : 0.8324
PSNR : 32.81
LPIPS: 0.1893
```

***

## Шаг 7 — Интерактивный веб-просмотрщик

Чтобы интерактивно исследовать обученную сцену:

### С использованием nerfview/viser

```python
# /workspace/view_splat.py
import viser
import numpy as np
from plyfile import PlyData
import torch

server = viser.ViserServer(host="0.0.0.0", port=8080)
print("Просмотрщик запущен по адресу http://0.0.0.0:8080")

# Загрузить PLY-файл
ply_path = "/workspace/output/my_scene/point_cloud/iteration_30000/point_cloud.ply"
plydata = PlyData.read(ply_path)

xyz = np.stack([
    plydata['vertex']['x'],
    plydata['vertex']['y'],
    plydata['vertex']['z'],
], axis=-1)

# Добавить облако точек в просмотрщик
server.add_point_cloud(
    name="/splat",
    points=xyz,
    colors=np.ones((len(xyz), 3)) * 0.7,
    point_size=0.003,
)

import time
while True:
    time.sleep(0.01)
```

```bash
python /workspace/view_splat.py &
```

Затем откройте: `http://<clore-host>:<public-port-8080>`

### Альтернатива: Использовать SuperSplat (просмотрщик в браузере)

Скачать `.ply` файл и открыть его в [SuperSplat](https://playcanvas.com/super-splat):

```bash
# Скачать на вашу локальную машину
scp -P <port> root@<clore-host>:/workspace/output/my_scene/point_cloud/iteration_30000/point_cloud.ply ./
```

Затем перетащите `.ply` в браузер SuperSplat по адресу: `https://playcanvas.com/super-splat`

***

## Расширенные опции

### Управление количеством гауссианов

```bash
# Бóльшая денсификация для более детализированных сцен
python train.py \
    -s /workspace/data/my_photos \
    -m /workspace/output/my_scene \
    --densify_until_iter 15000 \
    --densify_grad_threshold 0.0002
```

### Белый фон (для объектов)

```bash
python train.py \
    -s /workspace/data/my_object \
    -m /workspace/output/my_object \
    --white_background
```

### Сцены большого масштаба

```bash
# Увеличить интервал сброса непрозрачности для уличных сцен
python train.py \
    -s /workspace/data/outdoor \
    -m /workspace/output/outdoor \
    --opacity_reset_interval 5000 \
    --iterations 50000
```

***

## Альтернатива: Gaussian Splatting с gsplat

`gsplat` — более быстрая, экономящая память реализация:

```bash
pip install gsplat

# Обучение с gsplat
python examples/simple_trainer.py \
    --data_dir /workspace/data/my_photos \
    --result_dir /workspace/gsplat_output
```

***

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

### Сборка CUDA-расширения завершается с ошибкой

```
error: no kernel image is available for execution on the device
```

**Решение:** Пересоберите для архитектуры вашего GPU:

```bash
export TORCH_CUDA_ARCH_LIST="8.6"  # Для RTX 3090/4090
cd /workspace/gaussian-splatting
pip install submodules/diff-gaussian-rasterization --force-reinstall
```

### COLMAP не может реконструировать

**Решения:**

* Убедитесь в перекрытии изображений ≥ 50%
* Используйте больше фотографий (рекомендуется 100+)
* Попробуйте последовательное сопоставление для кадров видео: добавьте `--match sequential` в convert.py

### Недостаточно памяти во время обучения

```bash
# Уменьшите максимальное число гауссианов
python train.py \
    -s /workspace/data/my_photos \
    -m /workspace/output/my_scene \
    --max_num_splats 2000000  # по умолчанию ~6M
```

### Плавающие артефакты в сцене

Артефакты, возникающие при инициализации гауссианов:

* Увеличьте `--densify_grad_threshold` чтобы быть более избирательным
* Используйте `--prune_opacity_threshold 0.005` чтобы раньше удалять гауссианы с низкой непрозрачностью

***

## Рекомендации Clore.ai по GPU

Обучение Gaussian Splatting интенсивно использует GPU и часто вызывает CUDA-ядра. Объём VRAM определяет максимальную сложность сцены (число гауссианов); вычисления определяют скорость обучения.

| GPU           | VRAM  | Цена Clore.ai | Обучение 30K итераций | Максимум гауссианов |
| ------------- | ----- | ------------- | --------------------- | ------------------- |
| RTX 3090      | 24 ГБ | \~$0.12/ч     | \~45–55 мин           | \~6M                |
| RTX 4090      | 24 ГБ | \~$0.70/ч     | \~30–35 мин           | \~6M                |
| A100 40GB     | 40 ГБ | \~$1.20/ч     | \~12–18 мин           | \~10M+              |
| RTX 3080 12GB | 12 ГБ | \~$0.08/час   | \~70 мин              | \~3M (ограничено)   |

{% hint style="info" %}
**RTX 3090 примерно за $0.12/час — лучший выбор** для Gaussian Splatting. Полный прогон обучения на 30K итераций стоит примерно $0.09–0.11 времени на GPU. Для нескольких сцен в одной сессии стоимость незначительна.

Для быстрых экспериментов: сначала обучитесь до 7 000 итераций (\~15 мин на RTX 3090, ≈ $0.03). Проверьте качество в веб-просмотрщике. Полные 30K итераций запускать только для финального результата.
{% endhint %}

**Заметка по препроцессингу COLMAP:** COLMAP (Structure from Motion) работает на CPU/GPU, но основная нагрузка приходится на CPU. Большинство серверов Clore.ai имеют достаточные CPU для сцен до 200 изображений. Для наборов из 500+ изображений ищите серверы с 16+ ядрами CPU.

***

## Полезные ресурсы

* [3D Gaussian Splatting на GitHub](https://github.com/graphdeco-inria/gaussian-splatting)
* [Оригинальная статья (SIGGRAPH 2023)](https://repo-sam.inria.fr/fungraph/3d-gaussian-splatting/)
* [gsplat — быстрая реализация](https://github.com/nerfstudio-project/gsplat)
* [SuperSplat — просмотрщик в браузере](https://playcanvas.com/super-splat)
* [Сообщество Gaussian Splatting (Reddit)](https://www.reddit.com/r/gaussiansplatting/)
* [Awesome Gaussian Splatting](https://github.com/MrNeRF/awesome-3D-gaussian-splatting)


---

# 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/gaussian-splatting.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.