Merge pull request #13 from colmap/shaohui/update-25-06-12

Update to the latest doc.

Author: ahojnnes

_sources/cli.rst.txt

@@ -117,25 +117,38 @@ The available commands can be listed using the command::
           automatic_reconstructor
           bundle_adjuster
           color_extractor
+          database_cleaner
           database_creator
+          database_merger
           delaunay_mesher
           exhaustive_matcher
           feature_extractor
           feature_importer
+          hierarchical_mapper
           image_deleter
+          image_filterer
           image_rectifier
           image_registrator
           image_undistorter
+          image_undistorter_standalone
           mapper
           matches_importer
           model_aligner
           model_analyzer
+          model_comparer
           model_converter
+          model_cropper
           model_merger
           model_orientation_aligner
+          model_splitter
+          model_transformer
           patch_match_stereo
+          point_filtering
           point_triangulator
+          pose_prior_mapper
           poisson_mesher
+          project_generator
+          rig_configurator
           rig_bundle_adjuster
           sequential_matcher
           spatial_matcher
@@ -209,6 +222,8 @@ available as ``colmap [command]``:
 - ``mapper``: Sparse 3D reconstruction / mapping of the dataset using SfM after
   performing feature extraction and matching.
 
+- ``pose_prior_mapper`` Sparse 3D reconstruction / mapping using pose priors.
+
 - ``hierarchical_mapper``: Sparse 3D reconstruction / mapping of the dataset
   using hierarchical SfM after performing feature extraction and matching.
   This parallelizes the reconstruction process by partitioning the scene into
@@ -254,6 +269,8 @@ available as ``colmap [command]``:
   e.g., when a refinement of the intrinsics is needed or
   after running the ``image_registrator``.
 
+- ``database_cleaner``: Clean specific or all database tables.
+
 - ``database_creator``: Create an empty COLMAP SQLite database with the
   necessary database schema information.
 
@@ -269,21 +286,27 @@ available as ``colmap [command]``:
 - ``model_orientation_aligner``: Align the coordinate axis of a model using a
   Manhattan world assumption.
 
+- ``model_comparer``: Compare statistics of two reconstructions.
+
 - ``model_converter``: Convert the COLMAP export format to another format,
   such as PLY or NVM.
 
 - ``model_cropper``: Crop model to specific bounding box described in GPS or
   model coordinate system.
 
+- ``model_merger``: Attempt to merge two disconnected reconstructions,
+  if they have common registered images.
+
 - ``model_splitter``: Divide model in rectangular sub-models specified from
   file containing bounding box coordinates, or max extent of sub-model, or
   number of subdivisions in each dimension.
 
-- ``model_merger``: Attempt to merge two disconnected reconstructions,
-  if they have common registered images.
+- ``model_transformer``: Transform coordinate frame of a model.
 
 - ``color_extractor``: Extract mean colors for all 3D points of a model.
 
+- ``rig_configurator``: Configure rigs and frames after feature extraction.
+
 - ``vocab_tree_builder``: Create a vocabulary tree from a database with
   extracted images. This is an offline procedure and can be run once, while the
   same vocabulary tree can be reused for other datasets. Note that, as a rule of

_sources/concepts.rst.txt

@@ -0,0 +1,66 @@
+.. _concepts:
+
+Key Concepts
+============
+
+Starting from COLMAP 3.12, the concepts of rigs and frames have been introduced
+to enable a principled modeling of multi-sensor platforms as well as 360° panorama
+images. These concepts provide a structured framework to organize sensors and
+their measurements, enabling more flexible calibration and fusion of diverse
+data types (e.g., see :ref:`rig-support`).
+
+These additions are backward-compatible and do not affect the traditional, default usage
+of COLMAP for single-camera capture setups.
+
+
+.. _sensors:
+
+Sensors and Measurements
+------------------------
+
+A **sensor** is a device that captures data about the environment, producing
+measurements at specific timestamps. The most common sensor type is the camera,
+which captures images as its measurements. Other examples include IMUs
+(Inertial Measurement Units), which record acceleration and angular velocity,
+and GNSS receivers, which provide absolute position data. 
+
+Currently, COLMAP supports only cameras and their image measurements, though the
+sensor concept is designed to extend to other types such as IMUs and GNSS for
+future support of multi-modal data fusion.
+
+
+.. _rigs:
+
+Rigs
+----
+
+A **rig** models a platform composed of multiple sensors with fixed relative poses,
+enabling synchronized and consistent multi-sensor data collection. Examples
+include stereo camera setups, headworn AR/VR devices, and autonomous driving
+sensor suites. It can also be virtual — for example, a rig modeling multiple
+virtual cameras arranged to capture overlapping views used to create seamless
+360° panoramic images.
+
+In COLMAP, each sensor must be uniquely associated with exactly one rig. Each rig
+has a single reference sensor that defines its origin. For example, in a stereo
+camera rig, one camera is designated as the reference sensor with an identity
+`sensor_from_rig` pose, while the second camera’s pose is defined relative to
+this reference. In a single-camera setup, the camera itself serves as the sole
+reference sensor for its rig.
+
+
+.. _frames:
+
+Frames
+------
+
+A **frame** represents a rig captured at a single timestamp, containing measurements
+from one or more sensors within that rig. For example, if a rig consists of
+three sensors, a frame may include measurements from all three sensors, or only
+a subset, depending on availability. This concept allows association of multi-sensor 
+data at specific points in time.
+
+For instance, in a stereo camera rig recording video, each frame corresponds to a
+set of two images—one from each camera—captured at the same moment.
+
+

_sources/database.rst.txt

@@ -5,12 +5,14 @@ Database Format
 
 COLMAP stores all extracted information in a single SQLite database file. The
 database can be accessed with the database management toolkit in the COLMAP GUI,
-the provided C++ database API (see ``src/colmap/scene/database.h``), or with a scripting
-language of your choice (see ``scripts/python/database.py``).
+the provided C++ database API (see ``src/colmap/scene/database.h``), or using
+Python with pycolmap.
 
 The database contains the following tables:
 
+- rigs
 - cameras
+- frames
 - images
 - keypoints
 - descriptors
@@ -20,6 +22,22 @@ The database contains the following tables:
 To initialize an empty SQLite database file with the required schema, you can
 either create a new project in the GUI or execute `src/colmap/exe/database_create.cc`.
 
+
+Rigs and Sensors
+----------------
+
+The relation between rigs and sensors (cameras, etc.) is 1-to-N with one sensor
+being chosen as the reference sensor to define the origin of the rig. Each sensor
+must only be part of one rig.
+
+
+Rigs and Frames
+---------------
+
+The relation between rigs and frames is 1-to-N, where a frame defines a specific
+instance of the rig with all or a subset of sensors exposed at the same time.
+
+
 Cameras and Images
 ------------------
 
@@ -68,8 +86,8 @@ only X and Y must be provided and the other keypoint columns can be set to zero.
 The rest of the reconstruction pipeline only uses the keypoint locations.
 
 
-Matches
--------
+Matches and two-view geometries
+-------------------------------
 
 Feature matching stores its output in the `matches` table and geometric
 verification in the `two_view_geometries` table. COLMAP only uses the data in

_sources/faq.rst.txt

@@ -290,7 +290,6 @@ new images within this reconstruction, you can follow these steps::
 
     colmap vocab_tree_matcher \
         --database_path $PROJECT_PATH/database.db \
-        --VocabTreeMatching.vocab_tree_path /path/to/vocab-tree.bin \
         --VocabTreeMatching.match_list_path /path/to/image-list.txt
 
     colmap image_registrator \

_sources/format.rst.txt

@@ -9,7 +9,9 @@ Binary File Format
 
 Note that all binary data is stored using little endian byte ordering. All x86
 processors are little endian and thus no special care has to be taken when
-reading COLMAP binary data on most platforms.
+reading COLMAP binary data on most platforms. The data can be most conveniently
+parsed using the C++ reconstruction API under `src/colmap/scene/reconstruction_io.h`
+or using the Python API provided by pycolmap.
 
 
 =======================
@@ -34,11 +36,19 @@ Sparse Reconstruction
 By default, COLMAP uses a binary file format (machine-readable, fast) for
 storing sparse models. In addition, COLMAP provides the option to store the
 sparse models as text files (human-readable, slow). In both cases, the
-information is split into three files for the information about `cameras`,
-`images`, and `points`. Any directory containing those three files constitutes a
-sparse model. The binary files have the file extension `.bin` and the text files
-the file extension `.txt`. Note that when loading a model from a directory which
-contains both binary and text files, COLMAP prefers the binary format.
+information is split into multiples files for the information about `rigs`,
+`cameras`, `frames`, `images`, and `points`. Any directory containing these
+files constitutes a sparse model. The binary files have the file extension
+`.bin` and the text files the file extension `.txt`. Note that when loading a
+model from a directory which contains both binary and text files, COLMAP prefers
+the binary format.
+
+Note that older versions of COLMAP had no rig support and thus the `rigs` and
+`frames` files may be missing. The reconstruction I/O routines in COLMAP are
+fully backwards compatible in that models without these files can be read and
+trivial rigs and frames will be automatically initialized. Furthermore, newer
+output reconstructions' `cameras` and `images` files are fully compatible with
+old outputs.
 
 To export the currently selected model in the GUI, choose ``File > Export
 model``. To export all reconstructed models in the current dataset, choose
@@ -66,9 +76,25 @@ Text Format
 -----------
 
 COLMAP exports the following three text files for every reconstructed model:
-`cameras.txt`, `images.txt`, and `points3D.txt`. Comments start with a leading
-"#" character and are ignored. The first comment lines briefly describe the
-format of the text files, as described in more detailed on this page.
+`rigs.txt`, `cameras.txt`, `frames.txt`, `images.txt`, and `points3D.txt`.
+Comments start with a leading "#" character and are ignored. The first comment
+lines briefly describe the format of the text files, as described in more
+detailed on this page.
+
+
+rigs.txt
+-----------
+
+This file contains the configured rigs and sensors, e.g.::
+
+    # Rig calib list with one line of data per calib:
+    #   RIG_ID, NUM_SENSORS, REF_SENSOR_TYPE, REF_SENSOR_ID, SENSORS[] as (SENSOR_TYPE, SENSOR_ID, HAS_POSE, [QW, QX, QY, QZ, TX, TY, TZ])
+    # Number of rigs: 1
+    1 2 CAMERA 1 CAMERA 2 1 -0.9999701516465348 -0.0011120266840749639 -0.0075347911527510894 0.0012985125893421306 -0.19316906391350164 0.00085222218993398979 0.0070758955539026785
+    2 1 CAMERA 3
+
+Here, the dataset contains two rigs: the first rig has two cameras and the second
+one has 1 camera.
 
 
 cameras.txt
@@ -93,6 +119,22 @@ camera can be shared by multiple images, which refer to cameras using the unique
 identifier `CAMERA_ID`.
 
 
+frames.txt
+----------
+
+This file contains the frames, where a frame defines a specific
+instance of a rig with all or a subset of sensors exposed at the same time, e.g.::
+
+    # Frame list with one line of data per frame:
+    #   FRAME_ID, RIG_ID, RIG_FROM_WORLD[QW, QX, QY, QZ, TX, TY, TZ], NUM_DATA_IDS, DATA_IDS[] as (SENSOR_TYPE, SENSOR_ID, DATA_ID)
+    # Number of frames: 151
+    1 1 0.99801363919752195 0.040985139360073107 0.041890917712361225 -0.023111584553400576 -5.2666546897987896 -0.17120007823690631 0.12300519697527648 2 CAMERA 1 1 CAMERA 2 2
+    2 2 0.99816472047267968 0.037605501383281774 0.043101511724657163 -0.019881568259519072 -5.1956060695789192 -0.20794508616745555 0.14967533910764824 1 CAMERA 3 3
+
+Here, the dataset contains two frames, where frame 1 is an instance of rig 1 and
+frame 2 an instance of rig 2. 
+
+
 images.txt
 ----------
 

_sources/index.rst.txt

@@ -105,8 +105,10 @@ support (special credits to `Torsten Sattler <https://tsattler.github.io>`_).
 
    install
    tutorial
+   concepts
    database
    cameras
+   rigs
    format
    datasets
    gui

_sources/install.rst.txt

@@ -41,6 +41,12 @@ are not officially signed. The provided COLMAP binaries are automatically built
 from GitHub Actions CI machines. If you do not trust them, you can build from
 source as described below.
 
+Docker
+------
+
+COLMAP provides a pre-built Docker image with CUDA support. For detailed
+instructions on how to build and run COLMAP using Docker, please refer to the
+`Docker documentation <https://github.com/colmap/colmap/tree/main/docker>`__.
 
 -----------------
 Build from Source
@@ -75,7 +81,6 @@ Dependencies from the default Ubuntu repositories::
         libboost-graph-dev \
         libboost-system-dev \
         libeigen3-dev \
-        libflann-dev \
         libfreeimage-dev \
         libmetis-dev \
         libgoogle-glog-dev \
@@ -86,7 +91,12 @@ Dependencies from the default Ubuntu repositories::
         qtbase5-dev \
         libqt5opengl5-dev \
         libcgal-dev \
-        libceres-dev
+        libceres-dev \
+        libcurl4-openssl-dev \
+        libopenblas-openmp-dev
+
+Notice that compiling against OpenBLAS requires the OpenMP version
+under Debian/Ubuntu because of `this issue <https://github.com/facebookresearch/faiss/wiki/Troubleshooting#surprising-faiss-openmp-and-openblas-interaction>`__.
 
 To compile with **CUDA support**, also install Ubuntu's default CUDA package::
 
@@ -138,8 +148,9 @@ Dependencies from `Homebrew <http://brew.sh/>`__::
         ninja \
         boost \
         eigen \
-        flann \
         freeimage \
+        curl \
+        libomp \
         metis \
         glog \
         googletest \
@@ -148,14 +159,17 @@ Dependencies from `Homebrew <http://brew.sh/>`__::
         glew \
         cgal \
         sqlite3
+    brew link --force libomp
 
 Configure and compile COLMAP::
 
     git clone https://github.com/colmap/colmap.git
     cd colmap
     mkdir build
     cd build
-    cmake .. -GNinja -DCMAKE_PREFIX_PATH="$(brew --prefix qt@5)"
+    cmake .. \
+        -GNinja \
+        -DQt5_DIR="$(brew --prefix qt@5)/lib/cmake/Qt5"
     ninja
     sudo ninja install
 
@@ -268,7 +282,7 @@ with the source code ``hello_world.cc``::
         options.AddRequiredOption("message", &message);
         options.Parse(argc, argv);
 
-        std::cout << colmap::StringPrintf("Hello %s!", message.c_str()) << std::endl;
+        std::cout << colmap::StringPrintf("Hello %s!\n", message.c_str());
 
         return EXIT_SUCCESS;
     }

_sources/license.rst.txt

@@ -8,7 +8,7 @@ dependencies may affect the resulting COLMAP license.
 
 .. code-block:: text
 
-    Copyright (c) 2023, ETH Zurich and UNC Chapel Hill.
+    Copyright (c), ETH Zurich and UNC Chapel Hill.
     All rights reserved.
 
     Redistribution and use in source and binary forms, with or without