COLMAP обрабатывает входные изображения, чтобы оценить внутренние (intrinsics) и внешние (extrinsics) параметры камеры. Также он строит разреженное облако точек, которое служит геометрической основой для обучения 3D Gaussian Splatting модели.
В этом туториале COLMAP запускается напрямую из командной строки, чтобы получить полный контроль над извлечением признаков, сопоставлением и триангуляцией. Такой подход позволяет просматривать промежуточные результаты и проще диагностировать проблемы.
Почему не использовать пайплайн Nerfstudio по умолчанию?
В 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
Процесс в COLMAP состоит из трёх основных стадий:
Извлечение признаков (feature extraction): детектирует устойчивые визуальные признаки (например, ключевые точки SIFT) на каждом изображении.
Сопоставление признаков (feature matching): находит надёжные соответствия между признаками на парах изображений.
Имена файлов вроде 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. Его можно использовать для тестов или как референс при подготовке своих сцен.
1 - Запуск COLMAP с параметрами по умолчанию
Предупреждение
В этом разделе показано, как запустить COLMAP с параметрами по умолчанию. На датасете из примера такая конфигурация не даёт валидной реконструкции, хотя на других данных может сработать.
Если вас интересует только конфигурация, которая работает с датасетом из туториала, переходите сразу к разделу Запуск COLMAP с настроенными параметрами.
Задайте пути и создайте выходные папки
Сначала задайте нужные переменные окружения и создайте выходную папку:
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%
Команда выполняет сопоставление признаков для всех пар изображений с настройками по умолчанию.
Справка по параметрам:
--database_path: путь к базе COLMAP с извлечёнными признаками
--SiftMatching.use_gpu 1: включает GPU‑ускорение для сопоставления
Exhaustive matcher сравнивает признаки для каждой возможной пары изображений. Он подходит для небольших и средних датасетов (до нескольких сотен изображений). Для больших датасетов он становится вычислительно дорогим, поскольку число пар растёт квадратично.
COLMAP также поддерживает стратегии сопоставления, лучше подходящие для больших датасетов: sequential matching, spatial matching и vocab tree matching. Подробнее см. в документации COLMAP.
--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 может улучшить реконструкцию. Шаги по заданию путей и созданию выходных папок такие же, как в разделе Запуск COLMAP с параметрами по умолчанию, поэтому здесь они не повторяются.
По сравнению с конфигурацией по умолчанию здесь добавлен параметр --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 по умолчанию:
--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
После завершения реконструкции можно посмотреть результат в COLMAP GUI:
Запустите COLMAP.
Выберите File → Import Model.
В диалоге выбора папки перейдите в %SPARSE_PATH%\0 (обычно sparse/0).
Нажмите Select Folder.
COLMAP отобразит разреженное облако точек и положения камер.
Чтобы улучшить читаемость визуализации:
Откройте Render → Render Options
Настройте Point size и Camera size
В строке статуса внизу должно быть что‑то вроде:
84 Images - 5863 Points
Это означает, что все 84 изображения были успешно зарегистрированы, и получилась разреженная реконструкция с 5 863 3D‑точками.
Рисунок 6. COLMAP GUI: разреженное облако точек и позы камер.
Опционально: запуск всего пайплайна через batch‑скрипт
Весь пайплайн COLMAP можно автоматизировать через batch‑файл. Пример .bat со всеми командами из раздела доступен здесь:
scripts/run_colmap_adjusted.bat
Перед запуском скрипта обновите пути под вашу локальную установку.
Референсные результаты
Референсный вывод COLMAP (разреженное облако точек и оценённые позы камер) доступен в репозитории датасета из примера: datasets/plush-dog.
Замечания о подборе параметров и качестве датасета
Примечание: Параметры в этом туториале выбраны так, чтобы получить надёжный результат на датасете из примера. Они не оптимизированы ни по скорости, ни по точности и не предназначены как универсальные значения «по умолчанию». Для других данных подстройте значения под цели (скорость, полнота, визуальное качество). Подбор конфигурации обычно требует нескольких итераций.
Продвинутые пользователи могут обойти внутренние этапы извлечения и сопоставления признаков в COLMAP, подставляя собственные признаки или соответствия напрямую в базу COLMAP. Это позволяет интегрировать нейросетевые пайплайны или сторонние инструменты, продолжая использовать COLMAP для мэппинга.
Иногда собрать более полный или качественный датасет эффективнее, чем подбирать параметры реконструкции. Но это не всегда возможно. Например:
Датасет может быть снят в неконтролируемых условиях
Освещение, текстура или настройки камеры могут быть не под вашим контролем
В сцене могут быть большие безтекстурные области или отражающие поверхности
В таких случаях настройка параметров становится необходимой, чтобы компенсировать ограничения входных данных.
