Imported from reshmabanu2823/SIH26158 (colmap/AGENTS.md). Install upstream with npx skills add reshmabanu2823/SIH26158 --skill colmap. Copyright stays with the author.

AGENTS.md — COLMAP Guide

Project Overview

COLMAP is a general-purpose Structure-from-Motion (SfM) and Multi-View Stereo (MVS) pipeline that reconstructs 3D models from 2D image collections. Written in C++17 with optional CUDA support. Single binary (colmap) with many subcommands, a Qt GUI, and Python bindings (pycolmap).

Directory Structure

Module Dependency Layers (bottom → top)

Key Classes & Files

CLI entry point: exe/colmap.cc (subcommand dispatcher).

Build Instructions

mkdir build && cd build
cmake .. -GNinja -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=../install
ninja

# No GUI, no CUDA (minimal)
cmake .. -GNinja -DCMAKE_BUILD_TYPE=Release -DGUI_ENABLED=OFF -DCUDA_ENABLED=OFF

# With tests
cmake .. -GNinja -DCMAKE_BUILD_TYPE=Release -DTESTS_ENABLED=ON

Build pycolmap

First build and install the C++ code:

mkdir build && cd build
cmake .. -GNinja -DCMAKE_INSTALL_PREFIX=../install
ninja install

Then build pycolmap (from the repo root):

colmap_DIR=./install ./python/incremental_build.sh  # Fast incremental build
colmap_DIR=./install ./python/build.sh              # Clean build (slower)

If there is a local .python-version file, use pyenv/uv for Python commands, pip install, and building pycolmap.

Testing

Follow C++ and Python build instructions above.

Run ctest from the build directory:

cd build
ctest --output-on-failure          # All C++ tests
ctest -R "util/cache_test"         # Specific test
ctest -E "(feature/sift_test)"     # Exclude GPU tests

Run Python tests from the repo root:

pytest                             # All Python tests (config in pyproject.toml)

• Test files (*_test.cc) across all modules, created via COLMAP_ADD_TEST() macro
• Framework: GTest/GMock with custom main (util/gtest_main.cc)
• Test utilities: util/testing.h, Eigen matchers: util/eigen_matchers.h, transform matchers: geometry/rigid3_matchers.h, geometry/sim3_matchers.h
• CTest names: module/test_name (e.g., estimators/alignment_test)

Code Style & Conventions

Naming

• Classes: PascalCase
• Methods/functions: PascalCase (e.g., FindNextImages())
• Member variables: snake_case_ (trailing underscore)
• Local variables: snake_case
• Constants/enums: kPascalCase or UPPER_SNAKE_CASE
• Files: snake_case.h / snake_case.cc / snake_case_test.cc
• Transforms: target_from_source (e.g., cam_from_world)
• Coordinates: x_in_y (e.g., point3D_in_world)

Index and Identifier Types (util/types.h)

• Generic indexes: int, size_t
• Special identifiers: camera_t, image_t, image_pair_t, frame_t, rig_t, point2D_t, point3D_t, sensor_t, data_t, pose_prior_t

Hash containers (util/hash_containers.h)

Use the colmap::{Flat,Node}Hash{Map,Set} aliases, not std::unordered_map/set.

• FlatHashMap/FlatHashSet — default; fastest, but invalidate element references/iterators on insert/erase, so no iterator-erase loops (erase by key).
• NodeHashMap/NodeHashSet — reference-stable; use when a reference/pointer/ iterator to an element is held across a mutation of the same container (e.g. Reconstruction::points3D_).

Custom keys reuse the std::hash specializations / PairHash in util/types.h. Keep std::map/std::set only when sorted iteration is required (deterministic output, Ceres block order, lower_bound).

Formatting

scripts/format/c++.sh
scripts/format/python.sh

External Dependencies

Core

Optional

Bundled (src/thirdparty/)