Это многостраничный печатный вид этого раздела. Нажмите что бы печатать.
Добро пожаловать в раздел туториалов.
Сейчас на сайте доступен полный гайд по реконструкции реальных объектов с помощью 3D Gaussian Splatting. В нём разобраны захват изображений, оценка поз камеры, обучение модели и постобработка. Всё делается на Windows и на базе инструментов с открытым исходным кодом.
В будущем будут добавлены новые туториалы.
Автор: Олег Боев
Реальная плюшевая игрушка (слева) и её реконструированная 3D Gaussian Splatting модель (справа).
Этот туториал объясняет, как реконструировать 3D‑сцену по реальным фотографиям с использованием Gaussian Splatting. Метод был представлен в работе 3D Gaussian Splatting for Real-Time Radiance Field Rendering (Kerbl et al., 2023).
Gaussian Splatting — это современная техника для синтеза новых ракурсов (novel view synthesis). Она реконструирует сцену, размещая в пространстве тысячи небольших 3D‑гауссиан и оптимизируя их внешний вид так, чтобы он согласовывался с входными изображениями. Этот подход особенно хорошо передаёт тонкие и «мягкие» детали (например, мех или тканевые текстуры), которые часто плохо восстанавливаются традиционными методами, основанными на поверхностях/мешах.
Туториал демонстрирует полный пайплайн на примере реальной плюшевой игрушки. Он включает следующие шаги:
Пример показывает, как получить воспроизводимый результат, используя только инструменты с открытым исходным кодом, настроенные под Windows.
Этот подход особенно хорошо подходит для сканирования физических продуктов или небольших реальных объектов, поэтому он полезен для задач визуализации продукта, оцифровки объектов и создания 3D‑контента.
В этом туториале используется репозиторий gsplat для 3D Gaussian Splatting. По сравнению с оригинальной реализацией авторов (graphdeco-inria/gaussian-splatting), gsplat даёт несколько практических преимуществ:
COLMAP оценивает позы камер и строит разреженную реконструкцию по входным изображениям. Эти результаты используются для обучения 3D Gaussian Splatting модели. Windows‑версия COLMAP включает графический интерфейс и инструменты командной строки.
Примечание: gsplat является частью проекта Nerfstudio, в котором есть обёртка над COLMAP (
ns-process-data), запускающая COLMAP с параметрами по умолчанию. Часто этого достаточно, но для некоторых наборов данных нужны нестандартные настройки. В одном из разделов ниже показано, как менять ключевые параметры, если настройки по умолчанию не работают.
Примечание: Аналогичные пайплайны можно строить и с помощью RealityCapture, Agisoft Metashape или Autodesk ReCap Pro. В этом туториале фокус на бесплатном и воспроизводимом процессе на базе COLMAP.
SuperSplat Editor это инструмент с открытым исходным кодом, работающий в браузере, для просмотра, редактирования и оптимизации 3D Gaussian Splatting моделей. Он поддерживает:
SuperSplat также можно установить как Progressive Web App (PWA) для более быстрого доступа и интеграции «как приложение».
Туториал ориентирован на Windows, потому что эта ОС широко используется начинающими, студентами и техническими пользователями. При этом многие инструменты с открытым исходным кодом разрабатываются под Linux, а пользователи Windows часто сталкиваются с дополнительными сложностями при установке из‑за платформенных различий.
Вопросы по установке и запуску COLMAP и gsplat на Windows регулярно появляются на форумах, в GitHub Issues и в сообществах. Этот туториал даёт понятный пошаговый процесс под Windows, чтобы сделать современные методы 3D‑реконструкции более доступными.
Туториал проходит полный пайплайн построения 3D Gaussian Splatting модели из реальных изображений. Процесс включает четыре основных этапа:
Схема пайплайна 3D Gaussian Splatting.
Далее каждый шаг разобран подробно. Если вас интересует только обучение, визуализация или другой этап, можно перейти сразу в нужный раздел.
Этот туториал разрабатывался и проверялся на Windows 11. Большинство шагов также применимы к Linux, но есть различия, которые будут разобраны в отдельном гайде.
Для эффективного обучения и воспроизводимости рекомендуется система со следующей конфигурацией:
Hardware
Software
Примечание: Небольшие отличия в версиях ПО или драйверов CUDA могут потребовать мелких правок.
Примечание: CUDA Toolkit нужно устанавливать отдельно от GPU‑драйвера, чтобы включить GPU‑ускорение. Без Toolkit инструменты вроде PyTorch не увидят поддержку CUDA. Инструкции и совместимость см. в документации CUDA Toolkit.
Туториал был проверен на следующей конфигурации:
Перейдите на официальную страницу релизов COLMAP в GitHub и скачайте ZIP‑архив для Windows:
https://github.com/colmap/colmap/releases
Распакуйте содержимое ZIP‑файла в удобное место, например:
C:\Tools\colmap
В туториале используется <COLMAP_PATH> как плейсхолдер пути установки COLMAP. Замените его на фактический путь в вашей системе.
Запустить COLMAP GUI можно одним из способов:
Вариант A
Дважды щёлкните COLMAP.bat в распакованной папке.
Вариант B
Откройте Command Prompt и выполните:
<COLMAP_PATH>\COLMAP.bat gui
Замените <COLMAP_PATH> на фактический путь установки.
Если всё установлено корректно, COLMAP GUI откроется без ошибок. Вы увидите главное окно, как на рисунке ниже:
Рисунок 3. Главное окно COLMAP GUI при запуске.
В этом туториале используется предсобранный Windows‑релиз. Другие варианты, включая сборку из исходников или установку через пакетные менеджеры на Linux/macOS, описаны в официальной инструкции: https://colmap.github.io/install.html
Microsoft Build Tools for Visual Studio предоставляет компилятор C++ и связанные инструменты, необходимые для сборки C++‑проектов на Windows. Это требуется, чтобы собрать gsplat из исходников.
Скачайте Build Tools for Visual Studio 2022 с официального сайта:
https://visualstudio.microsoft.com/downloads/#build-tools-for-visual-studio-2022
Во время установки выберите следующие опции:
Workload (рабочая нагрузка):
Individual components (убедитесь, что отмечены):
Рисунок 4. Необходимые компоненты, выбранные при установке Visual Studio Build Tools.
Проверить, что среда сборки настроена корректно, можно одним из двух способов.
Откройте меню «Пуск» и найдите:
Developer Command Prompt for VS 2022
Выполните команду:
cl
Ожидаемый вывод выглядит примерно так:
Microsoft (R) C/C++ Optimizing Compiler Version 19.43.34809 for x86
usage: cl [ option... ] filename... [ /link linkoption... ]
vcvars64.bat из обычного Command Prompt
cmd)."C:\Program Files (x86)\Microsoft Visual Studio\2022\BuildTools\VC\Auxiliary\Build\vcvars64.bat"
При необходимости скорректируйте путь.
Затем выполните:
cl
Если компилятор настроен правильно, вывод будет таким же, как в предыдущем варианте.
Перед установкой PyTorch или сборкой gsplat убедитесь, что CUDA Toolkit установлен и доступен. В Command Prompt выполните:
nvcc --version
Если всё установлено корректно, вывод будет примерно таким:
nvcc: NVIDIA (R) Cuda compiler driver
Copyright (c) 2005-2024 NVIDIA Corporation
Built on Fri_Jun_14_16:44:19_Pacific_Daylight_Time_2024
Cuda compilation tools, release 12.6, V12.6.20
Build cuda_12.6.r12.6/compiler.34431801_0
Если команда не распознаётся или версия не выводится, установите CUDA Toolkit с сайта NVIDIA. Более старые версии доступны в архиве CUDA Toolkit.
Чтобы собрать gsplat, используйте терминал, в котором инициализирована среда Visual C++.
Вариант A: Developer Command Prompt
Вариант B: вручную запустить vcvars64.bat
"C:\Program Files (x86)\Microsoft Visual Studio\2022\BuildTools\VC\Auxiliary\Build\vcvars64.bat"
После запуска скрипта терминал будет настроен с нужными переменными окружения.
Если у вас ещё нет Conda, установите Miniconda или Anaconda.
Создайте и активируйте новое окружение:
conda create -y -n gsplat python=3.10
conda activate gsplat
Откройте страницу установки PyTorch и выберите конфигурацию, соответствующую вашей версии Python и CUDA.
Для CUDA 12.6 выполните:
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu126
Проверьте, что PyTorch видит CUDA:
python -c "import torch; print(torch.cuda.is_available())"
Ожидаемый вывод:
True
git clone --recursive https://github.com/nerfstudio-project/gsplat.git
cd gsplat
Чтобы собрать gsplat, выполните:
set DISTUTILS_USE_SDK=1
pip install .
Команда устанавливает переменную окружения DISTUTILS_USE_SDK, чтобы избежать предупреждения:
UserWarning: It seems that the VC environment is activated but DISTUTILS_USE_SDK is not set...
Перейдите в папку examples и установите зависимости:
cd examples
pip install -r requirements.txt
Клонируйте репозиторий датасета:
git clone <URL_TO_EXAMPLE_DATA>
Замените <DATA_PATH> и <OUTPUT_PATH> на реальные пути в вашей системе.
Запустите обучение командой:
python simple_trainer.py default ^
--eval_steps -1 ^
--disable_viewer ^
--data_factor 4 ^
--data_dir <DATA_PATH> ^
--result_dir <OUTPUT_PATH>
Замените <DATA_PATH> и <OUTPUT_PATH> на корректные пути. Если всё настроено правильно, скрипт стартует и покажет прогресс обучения.
На Windows при запуске скрипта обучения может встретиться ошибка вида:
Error with pycolmap:
...
num\_cameras = struct.unpack('L', f.read(8))\[0]
Эта ошибка вызвана несоответствием логики struct.unpack в Windows‑сборке. На момент написания исправление ещё не было вмержено в официальный репозиторий pycolmap. Подробности см. в PR: https://github.com/rmbrualla/pycolmap/pull/2
В качестве обходного пути удалите исходный пакет и установите патч‑версию из форка сообщества:
pip uninstall pycolmap -y
pip install git+https://github.com/mathijshenquet/pycolmap
gsplat поддерживает разные форматы входных данных через механизмы подготовки датасетов в Nerfstudio. В этом туториале в качестве входа используется набор отдельных фотографий.
Практики съёмки зависят от типа сцены. Уличные сцены, помещения, люди и небольшие объекты требуют разных подходов. Тем не менее, следующие общие рекомендации подходят для большинства сценариев и помогают улучшить качество результата в 3D Gaussian Splatting.
Используйте ровный мягкий свет
Освещайте сцену равномерным рассеянным светом, чтобы уменьшить тени и блики. Избегайте жёсткого направленного света: он повышает шум и ухудшает качество реконструкции.
Снимайте качественные статичные фото
Фотографии обычно дают лучший результат, чем кадры из видео, потому что меньше смаза (motion blur) и стабильнее экспозиция. Если вы используете видео, снимайте с высоким FPS (минимум 60) при стабильном освещении.
Обеспечьте достаточное перекрытие кадров
Каждое изображение должно перекрываться с соседними ракурсами примерно на 20–30%. Перекрытие критично для сопоставления признаков в Structure‑from‑Motion (SfM). В видео такое перекрытие часто получается автоматически.
Создавайте параллакс перемещением камеры
Между кадрами меняйте физическое положение камеры. Не вращайтесь «на месте» без смещения: это снижает геометрическую информативность и может привести к провалу оценки поз.
Фиксируйте настройки камеры
Используйте ручной фокус и фиксированное фокусное расстояние, чтобы внутренние параметры камеры оставались стабильными. Отключите зум, автофокус и автоэкспозицию.
Избегайте смаза и искажений
Используйте штатив или стабилизатор. Избегайте условий с низкой освещённостью, где требуются длинные выдержки. Проверяйте, что изображения резкие и правильно сфокусированы.
Снимайте сцены с текстурой
В сцене должно быть достаточно текстуры, контрастных границ и деталей, чтобы признаки детектировались стабильно. Плоские, однородные или глянцевые поверхности снижают эффективность SfM.
Сцена должна быть статичной
Не допускайте движения во время съёмки. Движущиеся объекты, люди или изменения освещения мешают оценке поз.
Выбирайте подходящее разрешение
Высокое разрешение повышает детализацию, но увеличивает расход памяти и время обучения. Подберите компромисс между качеством и производительностью.
Снимайте достаточно ракурсов
Для небольших объектов/сцен хорошая отправная точка: 100–250 согласованных кадров. Для более крупных или полностью 360° моделей нужно больше покрытие. Следите, чтобы не «выпадали» зоны вроде нижней части объекта.
Используйте многокамерные установки, если это уместно
Многокамерная установка может ускорить съёмку, фиксируя несколько ракурсов одновременно. Это полезно для динамических сцен или ограниченного по времени процесса.
В этом туториале используется 84 входных изображения с разрешением 3000 × 2000, снятых камерой Canon M200 на штативе. Плюшевая игрушка была размещена на стуле, накрытом двумя скреплёнными листами белой бумаги 50 × 70 см, образующими изогнутый фон. Дополнительный лист снизу позволял удобно поворачивать объект во время съёмки, при этом камера оставалась неподвижной для каждого «бубликообразного» обхода.
Фотографии были сделаны в помещении при рассеянном фоновом освещении. На кадрах видны тени и элементы фона. Это сделано намеренно, чтобы смоделировать «реальные» условия и показать, что хороший результат возможен и без студийной постановки света. Освещение было неравномерным, а постобработка отдельных кадров не выполнялась. Это также демонстрирует, как инструменты вроде SuperSplat могут помочь скорректировать яркость и цвет уже после обучения. Цель: стимулировать практическое обучение даже на неидеальных данных.
Примечание: Похожий результат можно получить и с помощью современного смартфона, если освещения достаточно, а камера держится стабильно.
Примечание: Игрушка является личной собственностью автора и используется здесь исключительно для технической демонстрации.
Выбранные входные изображения, использованные для 3D‑реконструкции.
Схема съёмки: плюшевая игрушка, камера на штативе и изогнутый бумажный фон на стуле (слева); предпросмотр в реальном времени на экране камеры во время съёмки (справа).
Плюшевая игрушка выбрана, чтобы продемонстрировать одну из ключевых сильных сторон 3D Gaussian Splatting: способность передавать мягкие и детализированные поверхности. Традиционные меш‑пайплайны часто плохо справляются с материалами вроде меха и дают нереалистичную или неполную геометрию. В отличие от этого, представление сцены набором 3D‑гауссиан лучше сохраняет тонкую текстуру и мелкие вариации.
COLMAP обрабатывает входные изображения, чтобы оценить внутренние (intrinsics) и внешние (extrinsics) параметры камеры. Также он строит разреженное облако точек, которое служит геометрической основой для обучения 3D Gaussian Splatting модели.
В этом туториале COLMAP запускается напрямую из командной строки, чтобы получить полный контроль над извлечением признаков, сопоставлением и триангуляцией. Такой подход позволяет просматривать промежуточные результаты и проще диагностировать проблемы.
В Nerfstudio есть обёртка над COLMAP в виде команды ns-process-data, но она использует параметры по умолчанию, заданные в коде пайплайна. Во многих случаях этого достаточно, но на реальных сценах нередко требуются ручные настройки, иначе реконструкция может не получиться.
Например, при обработке датасета из примера через эту обёртку COLMAP зарегистрировал только 2 изображения из 84:
Starting with 84 images
Colmap matched 2 images
COLMAP only found poses for 2.38% of the images. This is low.
This can be caused by a variety of reasons, such as poor scene coverage,
blurry images, or large exposure changes.
Nerfstudio рекомендует увеличить перекрытие изображений или улучшить качество съёмки. Это полезные рекомендации, но во многих случаях можно получить рабочий результат, просто настроив параметры COLMAP напрямую.
В следующих разделах приведены точные шаги командной строки, которые использовались для успешной реконструкции этого датасета.
Процесс в COLMAP состоит из трёх основных стадий:
Хотя эти операции можно выполнить через графический интерфейс (GUI) COLMAP, в этом туториале предпочтительнее командная строка (CLI) по двум причинам:
Ниже приведён пример структуры датасета, ожидаемой COLMAP и gsplat:
<dataset_root>/
├── images/
│ ├── image_0001.jpg
│ ├── image_0002.jpg
│ └── ...
├── images_2/
│ ├── image_0001.jpg
│ └── ...
├── images_4/
│ ├── image_0001.jpg
│ └── ...
├── sparse/ # COLMAP sparse reconstruction outputs
│ └── 0/ # Подпапка по умолчанию для реконструированной сцены
│ ├── cameras.bin
│ ├── images.bin
│ ├── points3D.bin
│ └── project.ini
└── colmap.db # База данных COLMAP
image_0001.jpg приведены только для примера. Последовательные имена удобны, но строгих требований к именованию нет.images_2 и images_4 содержат уменьшенные в 2× и 4× версии исходных изображений. Они используются при обучении с --data_factor 2 или --data_factor 4. При необходимости можно добавить дополнительные папки (например, images_8/).sparse/0/ содержит результат разреженной реконструкции COLMAP. Если COLMAP построит несколько несвязанных моделей, появятся дополнительные подпапки sparse/1, sparse/2 и т. д.colmap.db — база данных, создаваемая на этапах извлечения и сопоставления признаков. В ней хранятся ключевые точки, соответствия и оценка внутренних параметров камеры.Датасет из примера с этой структурой находится в репозитории: datasets/plush-dog. Его можно использовать для тестов или как референс при подготовке своих сцен.
Сначала задайте нужные переменные окружения и создайте выходную папку:
set COLMAP_PATH=<Путь к установленному colmap.bat>
set DATA_PATH=<Путь к папке датасета, например plush-dog>
set IMAGE_PATH=%DATA_PATH%\images
set DB_PATH=%DATA_PATH%\colmap.db
set SPARSE_PATH=%DATA_PATH%\sparse
mkdir %SPARSE_PATH%
Используйте следующую команду, чтобы извлечь SIFT‑признаки из входных изображений:
%COLMAP_PATH% feature_extractor ^
--database_path %DB_PATH% ^
--image_path %IMAGE_PATH% ^
--ImageReader.single_camera 1 ^
--ImageReader.camera_model PINHOLE ^
--SiftExtraction.use_gpu 1
Команда извлекает SIFT‑признаки из изображений и сохраняет их в указанную базу COLMAP.
Справка по параметрам:
--database_path: путь к SQLite‑базе, куда будут записаны признаки--image_path: путь к папке с входными изображениями--ImageReader.single_camera 1: предположение, что все изображения сняты одной камерой--ImageReader.camera_model PINHOLE: использование pinhole‑модели камеры--SiftExtraction.use_gpu 1: включение GPU‑ускорения для извлечения признаковПример вывода:
==============================================================================
Feature extraction
==============================================================================
Creating SIFT GPU feature extractor
Processed file [1/84]
Name: IMG_3496.jpg
Dimensions: 3000 x 2000
Camera: #1 - PINHOLE
Focal Length: 5515.70px (Prior)
Features: 2400
Processed file [2/84]
Name: IMG_3497.jpg
Dimensions: 3000 x 2000
Camera: #1 - PINHOLE
Focal Length: 5515.70px (Prior)
Features: 2416
...
После извлечения признаков запустите exhaustive matcher, чтобы найти соответствия между парами изображений:
%COLMAP_PATH% exhaustive_matcher ^
--database_path %DB_PATH% ^
--SiftMatching.use_gpu 1
Команда выполняет сопоставление признаков для всех пар изображений с настройками по умолчанию.
Справка по параметрам:
--database_path: путь к базе COLMAP с извлечёнными признаками--SiftMatching.use_gpu 1: включает GPU‑ускорение для сопоставленияExhaustive matcher сравнивает признаки для каждой возможной пары изображений. Он подходит для небольших и средних датасетов (до нескольких сотен изображений). Для больших датасетов он становится вычислительно дорогим, поскольку число пар растёт квадратично.
COLMAP также поддерживает стратегии сопоставления, лучше подходящие для больших датасетов: sequential matching, spatial matching и vocab tree matching. Подробнее см. в документации COLMAP.
Пример вывода:
==============================================================================
Feature matching
==============================================================================
Creating SIFT GPU feature matcher
Generating exhaustive image pairs...
Matching block [1/2, 1/2]
...
Elapsed time: 0.044 [minutes]
После сопоставления запустите mapper в COLMAP, чтобы оценить позы камер и построить разреженную 3D‑реконструкцию:
%COLMAP_PATH% mapper ^
--database_path %DB_PATH% ^
--image_path %IMAGE_PATH% ^
--output_path %SPARSE_PATH%
Справка по параметрам:
--database_path: путь к базе COLMAP с признаками и соответствиями--image_path: путь к папке с входными изображениями--output_path: путь для сохранения моделей. Каждый результат будет в подпапке с номером (например, sparse/0)В некоторых случаях, включая датасет из этого туториала, COLMAP может не справиться с настройками по умолчанию. Сопоставление признаков может завершиться, но реконструкция может упасть на этапе инкрементального мэппинга (incremental mapping).
Пример лога при неудачном запуске:
Loading database
Loading cameras...
1 in 0.000s
Loading matches...
214 in 0.001s
Loading images...
84 in 0.008s (connected 84)
Loading pose priors...
0 in 0.000s
Building correspondence graph...
in 0.005s (ignored 0)
Elapsed time: 0.000 [minutes]
Finding good initial image pair
Initializing with image pair #57 and #83
Global bundle adjustment
Registering image #56 (3)
=> Image sees 52 / 299 points
Retriangulation and Global bundle adjustment
Registering image #84 (4)
=> Image sees 68 / 257 points
...
Registering image #43 (21)
=> Image sees 30 / 144 points
=> Could not register, trying another image.
Retriangulation and Global bundle adjustment
Finding good initial image pair
=> No good initial image pair found.
Finding good initial image pair
=> No good initial image pair found.
Повторяющееся сообщение "No good initial image pair found" означает, что COLMAP не смог найти геометрически корректную пару изображений для инициализации реконструкции. Это может произойти как при старте первой 3D‑модели, так и при попытках начать новую модель после того, как не удалось зарегистрировать дополнительные изображения.
Такие проблемы обычно связаны с тем, что совпадения признаков слабые, редкие или неравномерно распределены по датасету. Чтобы улучшить инициализацию, попробуйте настроить параметры извлечения и сопоставления признаков и повысить качество начальных соответствий.
Если настройка параметров не помогает, попробуйте снять больше кадров с большим перекрытием или экспериментируйте с альтернативными инструментами реконструкции.
В следующем разделе, Запуск COLMAP с настроенными параметрами, показано, как менять ключевые настройки для улучшения результата.
Пример batch‑скрипта со всеми командами из этого раздела доступен здесь: scripts/run_colmap_default.bat
В этом разделе показано, как настройка параметров COLMAP может улучшить реконструкцию. Шаги по заданию путей и созданию выходных папок такие же, как в разделе Запуск COLMAP с параметрами по умолчанию, поэтому здесь они не повторяются.
Команда извлечения признаков не отличается от конфигурации по умолчанию. Она использует GPU‑ускорение и предполагает одну камеру с pinhole‑моделью:
%COLMAP_PATH% feature_extractor ^
--database_path %DB_PATH% ^
--image_path %IMAGE_PATH% ^
--ImageReader.single_camera 1 ^
--ImageReader.camera_model PINHOLE ^
--SiftExtraction.use_gpu 1
Команда должна дать вывод, похожий на запуск по умолчанию, что подтверждает успешное извлечение SIFT‑признаков из каждого изображения.
Используйте следующую команду, чтобы запустить сопоставление признаков с изменёнными настройками:
%COLMAP_PATH% exhaustive_matcher ^
--database_path %DB_PATH% ^
--SiftMatching.use_gpu 1 ^
--SiftMatching.guided_matching 1
По сравнению с конфигурацией по умолчанию здесь добавлен параметр --SiftMatching.guided_matching 1, который включает guided matching (сопоставление с геометрическими ограничениями). Guided matching использует ограничения на базе двухвидовой геометрии (two‑view geometry), чтобы отфильтровать кандидатные соответствия. Это уменьшает число выбросов и повышает устойчивость, особенно в сценах со слабой текстурой или ограниченным перекрытием изображений.
Пример вывода:
==============================================================================
Feature matching
==============================================================================
Creating SIFT GPU feature matcher
Generating exhaustive image pairs...
Matching block [1/2, 1/2]
in 1.112s
Matching block [1/2, 2/2]
in 0.435s
Matching block [2/2, 1/2]
in 0.987s
Matching block [2/2, 2/2]
in 0.952s
Elapsed time: 0.059 [minutes]
Loading database
Loading cameras...
1 in 0.001s
Loading matches...
213 in 0.001s
Loading images...
84 in 0.009s (connected 84)
Loading pose priors...
0 in 0.001s
Building correspondence graph...
in 0.009s (ignored 0)
Elapsed time: 0.000 [minutes]
Чтобы повысить устойчивость реконструкции, используйте следующую команду с ослабленными порогами:
%COLMAP_PATH% mapper ^
--database_path %DB_PATH% ^
--image_path %IMAGE_PATH% ^
--output_path %SPARSE_PATH% ^
--Mapper.init_min_tri_angle 2 ^
--Mapper.init_min_num_inliers 4 ^
--Mapper.abs_pose_min_num_inliers 3 ^
--Mapper.abs_pose_max_error 8
Эти параметры ослабляют несколько порогов COLMAP по умолчанию:
--Mapper.init_min_tri_angle 2 (по умолчанию: 16)
Минимальный угол триангуляции (в градусах). Меньшие значения позволяют триангулировать больше точек, но могут снижать точность.
--Mapper.init_min_num_inliers 4 (по умолчанию: 100)
Минимальное число проверенных соответствий, необходимое для инициализации модели.
--Mapper.abs_pose_min_num_inliers 3 (по умолчанию: 30)
Минимальное число 2D–3D соответствий, необходимое для регистрации нового изображения.
--Mapper.abs_pose_max_error 8 (по умолчанию: 12)
Допустимая ошибка репроекции (в пикселях) на этапе регистрации.
Эти настройки помогают реконструировать сцены, где пороги по умолчанию слишком строгие. Для датасета из примера такие значения позволили получить успешную реконструкцию. Для других данных могут потребоваться другие значения, в зависимости от качества изображений и структуры сцены.
Примечание: Эти параметры подобраны специально под датасет, используемый в туториале. Они не являются универсальными значениями «по умолчанию». Скорее всего, вам придётся подстроить их под свою сцену, качество данных и цели реконструкции.
При успехе COLMAP покажет последовательную (incremental) регистрацию изображений:
Finding good initial image pair
Initializing with image pair #20 and #39
Global bundle adjustment
Registering image #19 (3)
=> Image sees 110 / 618 points
Retriangulation and Global bundle adjustment
Registering image #1 (4)
=> Image sees 167 / 689 points
...
В логе не должно быть сообщений вида:
=> No good initial image pair found.
Также папка %SPARSE_PATH% (обычно sparse/) должна содержать только одну подпапку, как правило 0.
Если появляются несколько подпапок (например 1 или 2), это означает, что COLMAP построил несколько несвязанных 3D‑сцен. Обычно это признак того, что не все изображения удалось зарегистрировать в одну модель.
После завершения реконструкции можно посмотреть результат в COLMAP GUI:
%SPARSE_PATH%\0 (обычно sparse/0).COLMAP отобразит разреженное облако точек и положения камер.
Чтобы улучшить читаемость визуализации:
В строке статуса внизу должно быть что‑то вроде:
84 Images - 5863 Points
Это означает, что все 84 изображения были успешно зарегистрированы, и получилась разреженная реконструкция с 5 863 3D‑точками.
Рисунок 6. COLMAP GUI: разреженное облако точек и позы камер.
Весь пайплайн COLMAP можно автоматизировать через batch‑файл. Пример .bat со всеми командами из раздела доступен здесь:
scripts/run_colmap_adjusted.bat
Перед запуском скрипта обновите пути под вашу локальную установку.
Референсный вывод COLMAP (разреженное облако точек и оценённые позы камер) доступен в репозитории датасета из примера: datasets/plush-dog.
Примечание: Параметры в этом туториале выбраны так, чтобы получить надёжный результат на датасете из примера. Они не оптимизированы ни по скорости, ни по точности и не предназначены как универсальные значения «по умолчанию». Для других данных подстройте значения под цели (скорость, полнота, визуальное качество). Подбор конфигурации обычно требует нескольких итераций.
Продвинутые пользователи могут обойти внутренние этапы извлечения и сопоставления признаков в COLMAP, подставляя собственные признаки или соответствия напрямую в базу COLMAP. Это позволяет интегрировать нейросетевые пайплайны или сторонние инструменты, продолжая использовать COLMAP для мэппинга.
Иногда собрать более полный или качественный датасет эффективнее, чем подбирать параметры реконструкции. Но это не всегда возможно. Например:
В таких случаях настройка параметров становится необходимой, чтобы компенсировать ограничения входных данных.
Чтобы обучить 3D Gaussian Splatting модель, выполните:
conda activate gsplat
cd <GSPLAT_REPOSITORY_FOLDER>\examples
python simple_trainer.py default ^
--eval_steps -1 ^
--disable_viewer ^
--data_factor 4 ^
--save_ply ^
--ply_steps 30000 ^
--data_dir <DATA_PATH> ^
--result_dir <OUTPUT_PATH>
Замените <GSPLAT_REPOSITORY_FOLDER> на путь к вашему клону репозитория gsplat.
Также обновите <DATA_PATH> и <OUTPUT_PATH> под пути в вашей системе.
default: профиль конфигурации по умолчанию в simple_trainer.py--eval_steps -1: отключает оценку во время обучения--disable_viewer: отключает встроенный вьювер Nerfstudio--data_factor 4: уменьшает входные изображения в 4 раза--save_ply: сохраняет модель в формате PLY--ply_steps 30000: сохраняет .ply на шаге обучения 30 000--data_dir: путь к датасету (тот же, что использовался в COLMAP)--result_dir: папка для результатов обученияЕсли обучение стартовало успешно, вы увидите индикатор прогресса. По завершении в логе будет сообщение вида:
Step: 29999 {'mem': 0.2915501594543457, 'ellipse_time': 708.7276656627655, 'num_GS': 167459}
Saving ply to <OUTPUT_PATH>/ply/point_cloud_29999.ply
В примере выше обучение заняло около 12 минут на системе из раздела «Проверенная конфигурация». Итоговая модель содержит 167 459 гауссиан. Финальный .ply сохраняется в:
<OUTPUT_PATH>\ply\point_cloud_29999.ply
Скачать модель, обученную на датасете из примера (без постобработки и удаления артефактов), можно из репозитория: results/plush-dog/ply/point_cloud_29999.ply
Чтобы визуализировать обученную модель во встроенном вьювере gsplat, выполните:
python simple_viewer.py --ckpt <OUTPUT_PATH>\ckpts\ckpt_29999_rank0.pt --port 8081
Команда поднимает локальный web‑сервер и выводит ссылку вида:
╭──────────────── viser ────────────────╮
│ ╷ │
│ HTTP │ http://localhost:8081 │
│ Websocket │ ws://localhost:8081 │
│ ╵ │
╰───────────────────────────────────────╯
Откройте выведенную ссылку (например, http://localhost:8081) в браузере.
Вьювер отображает обученную Gaussian Splatting модель. Вокруг основного объекта часто появляются «плавающие» артефакты. В следующем разделе, Редактирование 3D Gaussian Splatting модели в SuperSplat, показано, как очистить и постобработать модель для более удобной визуализации или дальнейшего использования.
«Плавающие» артефакты вокруг объекта во вьювере gsplat. Обычно такие артефакты присутствуют до очистки сцены.
Та же сцена при приближении: реконструированная плюшевая игрушка находится в центре.
После обучения и экспорта .ply вы можете открыть модель в SuperSplat Editor для визуальной проверки и ручной доработки.
Типичные задачи редактирования:
Полный список инструментов и опций см. в документации SuperSplat.
.ply (например, point_cloud_29999.ply) на canvas
Модель загружена в SuperSplat Editor.
Модель отображается как плотный кластер гауссиан, обычно окружённый «плавающими» артефактами.
Документация по инструментам редактирования доступна в SuperSplat Editing Guide.
Ниже приведён типовой порядок действий для очистки модели. Его можно адаптировать под ваш датасет и предпочтения.
Удаление внешних гауссиан с помощью сферического выделения и инверсии.
Используйте Brush, Lasso или Polygon, чтобы убрать оставшиеся «плавающие» точки вокруг объекта.
Эти инструменты удобны для точной зачистки областей вокруг границ и мелких деталей
Дополнительная очистка с помощью выделения кистью.
Инструмент Picker и включённый Splat View Mode для финальной очистки.
После завершения редактирования:
.ply.ply, который уменьшает размер без потери качестваЭкспортированную модель можно использовать для:
Итоговая очищенная модель после удаления артефактов в SuperSplat Editor.
Референсные версии для датасета из примера доступны в репозитории:
Следующие рекомендации помогают повысить качество реконструкции и сделать рабочий процесс более эффективным:
--data_factor (например, до 4), чтобы снизить потребление памяти и ускорить обучение. Для максимального качества финальные модели лучше обучать на более высоком разрешении.Датасет для этого туториала был снят преимущественно с куполообразных ракурсов камеры, охватывающих только верхнюю полусферу объекта. В результате нижняя часть модели выглядит неполной при просмотре снизу.
Вид модели снизу: разреженные гауссианы и неполная поверхность.
Для многих сценариев (например, демонстрация на поворотном столе или фронтальная визуализация) такого покрытия достаточно.
Но для полностью замкнутых 3D‑моделей нужно снять дополнительные кадры с нижних углов.
Если объект жёсткий, можно положить его на бок, чтобы снять нижнюю часть. Убедитесь, что есть достаточное перекрытие с другими ракурсами, чтобы сохранить корректное совмещение.
Таблица ниже показывает типичное время для каждого этапа пайплайна:
| Этап | Примерное время |
|---|---|
| Съёмка изображений | 20 минут |
| Обработка в COLMAP | 1 минута |
| Обучение модели в gsplat | 12 минут |
| Редактирование в SuperSplat | 10 минут |
Примечание: Время COLMAP указано только для успешного прогона реконструкции. Подбор параметров и повторные попытки могут добавить значительное время в зависимости от датасета.
Примечание: Эти ответы в первую очередь относятся к съёмке объектов/«настольным» сценам, как в этом туториале. Уличные сцены и большие пространства могут требовать других инструментов, процессов и настроек.
Да. Хотя в туториале использовалась камера со сменной оптикой, современные смартфоны могут дать похожий результат при достаточном освещении и при условии, что кадры резкие и стабильные.
Предпочтительнее фото: ими проще управлять фокусом и экспозицией. Видео тоже может работать, если снимать 60 FPS или выше и минимизировать смаз.
Для небольших объектов обычно достаточно 100–250 изображений. Для полного покрытия 360° может понадобиться больше.
По возможности избегайте. Используйте ручной фокус и фиксированное фокусное расстояние, чтобы внутренние параметры камеры оставались стабильными, так оценка поз получается точнее.
Не всегда. Для вывода в формате «поворотного стола» часто хватает верхних и боковых ракурсов. Для полноценной 360°‑модели также снимайте нижнюю часть.
Да, желательно. Поверхности с видимыми узорами, гранями и текстурой улучшают сопоставление признаков. Плоские, блестящие или безтекстурные объекты реконструировать сложнее.
Да, но учитывайте: