Update dev documentation

Author: ahojnnes

_sources/bibliography.rst.txt

@@ -8,6 +8,10 @@ Bibliography
     "Accurate, dense, and robust multiview stereopsis."
     Transactions on Pattern Analysis and Machine Intelligence, 2010.
 
+.. [garland1997] Garland, Michael, and Heckbert, Paul S.
+    "Surface simplification using quadric error metrics."
+    Proceedings of SIGGRAPH, 1997.
+
 .. [hofer16] Hofer, M., Maurer, M., and Bischof, H.
     Efficient 3D Scene Abstraction Using Line Segments,
     Computer Vision and Image Understanding, 2016.
@@ -37,5 +41,9 @@ Bibliography
 .. [lowe04] Lowe, David G. "Distinctive image features from scale-invariant
     keypoints". International journal of computer vision 60.2 (2004): 91-110.
 
+.. [waechter2014] Waechter, Michael and Moehrle, Nils and Goesele, Michael.
+    "Let there be color! Large-scale texturing of 3D reconstructions."
+    European Conference on Computer Vision, 2014.
+
 .. [wu13] Wu, Changchang. "Towards linear-time incremental structure from
     motion." International Conference 3D Vision, 2013.

_sources/cli.rst.txt

@@ -46,14 +46,14 @@ of commands as an alternative to the automatic reconstruction command::
     $ colmap exhaustive_matcher \
        --database_path $DATASET_PATH/database.db
 
-    $ mkdir $DATASET_PATH/sparse
+    $ mkdir -p $DATASET_PATH/sparse
 
     $ colmap mapper \
         --database_path $DATASET_PATH/database.db \
         --image_path $DATASET_PATH/images \
         --output_path $DATASET_PATH/sparse
 
-    $ mkdir $DATASET_PATH/dense
+    $ mkdir -p $DATASET_PATH/dense
 
     $ colmap image_undistorter \
         --image_path $DATASET_PATH/images \
@@ -81,6 +81,48 @@ of commands as an alternative to the automatic reconstruction command::
         --input_path $DATASET_PATH/dense \
         --output_path $DATASET_PATH/dense/meshed-delaunay.ply
 
+    # Optionally simplify a dense mesh to reduce its size.
+    $ colmap mesh_simplifier \
+        --input_path $DATASET_PATH/dense/meshed-poisson.ply \
+        --output_path $DATASET_PATH/dense/meshed-poisson-simplified.ply \
+        --MeshSimplification.target_face_ratio 0.25
+
+    # Optionally texture a mesh using the undistorted images.
+    $ colmap mesh_texturer \
+        --workspace_path $DATASET_PATH/dense \
+        --input_path $DATASET_PATH/dense/meshed-poisson.ply \
+        --output_path $DATASET_PATH/dense/textured
+
+To use the global SfM pipeline instead of the incremental mapper, replace the
+``mapper`` step with ``global_mapper``. The global mapper depends on good focal
+length priors, so if reliable intrinsics are not available (e.g., from EXIF or
+lab calibration), you should run ``view_graph_calibrator`` first. This step is
+optional but recommended to improve the quality of global SfM, as was always
+the default in `GLOMAP <https://github.com/colmap/glomap>`_. Note that
+``view_graph_calibrator`` modifies camera intrinsics and two-view geometries
+in the database in-place, so it is recommended to work on a copy of the
+database::
+
+    $ colmap feature_extractor \
+       --database_path $DATASET_PATH/database.db \
+       --image_path $DATASET_PATH/images
+
+    $ colmap exhaustive_matcher \
+       --database_path $DATASET_PATH/database.db
+
+    # Optional but often needed: calibrate intrinsics from the view graph.
+    # This modifies the database in-place, so work on a copy.
+    $ cp $DATASET_PATH/database.db $DATASET_PATH/database_global.db
+    $ colmap view_graph_calibrator \
+        --database_path $DATASET_PATH/database_global.db
+
+    $ mkdir -p $DATASET_PATH/sparse
+
+    $ colmap global_mapper \
+        --database_path $DATASET_PATH/database_global.db \
+        --image_path $DATASET_PATH/images \
+        --output_path $DATASET_PATH/sparse
+
 If you want to run COLMAP on a computer without an attached display (e.g.,
 cluster or cloud service), COLMAP automatically switches to use CUDA if
 supported by your system. If no CUDA enabled device is available, you can
@@ -124,6 +166,9 @@ The available commands can be listed using the command::
           exhaustive_matcher
           feature_extractor
           feature_importer
+          geometric_verifier
+          global_mapper
+          guided_geometric_verifier
           hierarchical_mapper
           image_deleter
           image_filterer
@@ -133,8 +178,11 @@ The available commands can be listed using the command::
           image_undistorter_standalone
           mapper
           matches_importer
+          mesh_simplifier
+          mesh_texturer
           model_aligner
           model_analyzer
+          model_clusterer
           model_comparer
           model_converter
           model_cropper
@@ -149,10 +197,12 @@ The available commands can be listed using the command::
           poisson_mesher
           project_generator
           rig_configurator
+          rotation_averager
           sequential_matcher
           spatial_matcher
           stereo_fusion
           transitive_matcher
+          view_graph_calibrator
           vocab_tree_builder
           vocab_tree_matcher
           vocab_tree_retriever
@@ -167,8 +217,12 @@ the available options, e.g.::
 
             -h [ --help ]
             --default_random_seed arg (=0)
-            --log_to_stderr arg (=1)
+            --log_target arg (=stderr_and_file)
+                                  {stderr, stdout, file, stderr_and_file}
+            --log_path arg
             --log_level arg (=0)
+            --log_severity arg (=0)    0:INFO, 1:WARNING, 2:ERROR, 3:FATAL
+            --log_color arg (=1)
             --project_path arg
             --database_path arg
             --image_path arg
@@ -219,7 +273,12 @@ available as ``colmap [command]``:
   :ref:`Graphical User Interface <gui>` for more information.
 
 - ``automatic_reconstructor``: Automatically reconstruct sparse and dense model
-  for a set of input images.
+  for a set of input images. Key options include ``--quality`` (LOW, MEDIUM,
+  HIGH, EXTREME), ``--data_type`` (INDIVIDUAL, VIDEO, INTERNET) to tune settings
+  for different capture scenarios, ``--feature`` (SIFT, ALIKED) to select the
+  feature extraction algorithm, ``--mapper`` (INCREMENTAL, HIERARCHICAL, GLOBAL)
+  to choose the SfM pipeline, and ``--mesher`` (POISSON, DELAUNAY) to select the
+  surface reconstruction method.
 
 - ``project_generator``: Generate project files at different quality settings.
 
@@ -230,10 +289,27 @@ available as ``colmap [command]``:
   ``spatial_matcher``, ``transitive_matcher``, ``matches_importer``:
   Perform feature matching after performing feature extraction.
 
+- ``geometric_verifier``: Run standalone geometric verification on existing
+  feature matches in the database. This estimates two-view geometries
+  (fundamental/essential matrices, homographies) for matched image pairs.
+
+- ``guided_geometric_verifier``: Run geometric verification guided by an
+  existing sparse reconstruction. Uses the known relative camera poses to
+  improve match verification results.
+
 - ``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.
+- ``global_mapper``: Sparse 3D reconstruction using the global SfM pipeline.
+  Unlike the incremental ``mapper``, the global approach solves for all camera
+  poses simultaneously using rotation averaging and global positioning. This
+  can be faster for large datasets but may be less robust to outliers.
+  The global mapper depends on reasonably good focal length priors to perform
+  well. Run ``view_graph_calibrator`` before ``global_mapper`` to calibrate
+  camera intrinsics and estimate relative poses from the view graph, or provide
+  camera calibrations manually.
+
+- ``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.
@@ -265,6 +341,19 @@ available as ``colmap [command]``:
 - ``delaunay_mesher``: Meshing of the reconstructed sparse or dense point cloud
   using a graph cut on the Delaunay triangulation and visibility voting.
 
+- ``mesh_simplifier``: Simplify a triangle mesh (PLY format) using Quadric Error
+  Metric (QEM) decimation. This reduces the number of faces in a mesh while
+  preserving its overall shape and appearance. Key options include
+  ``--MeshSimplification.target_face_ratio`` to control the fraction of faces
+  to retain (default 0.1), ``--MeshSimplification.max_error`` to set a maximum
+  quadric error threshold (0 = disabled), and
+  ``--MeshSimplification.boundary_weight`` to control boundary edge preservation
+  (default 1000). Supports multi-threaded initialization via
+  ``--MeshSimplification.num_threads``.
+
+- ``mesh_texturer``: Produce a texture atlas and UV coordinates for a triangle
+  mesh using calibrated multi-view images.
+
 - ``image_registrator``: Register new images in the database against an existing
   model, e.g., when extracting features and matching newly added images in a
   database after running ``mapper``. Note that no bundle adjustment or
@@ -291,6 +380,10 @@ available as ``colmap [command]``:
 
 - ``model_analyzer``: Print statistics about reconstructions.
 
+- ``model_clusterer``: Split a reconstruction into smaller
+  sub-model clusters. Useful for managing and processing large-scale
+  reconstructions.
+
 - ``model_aligner``: Align/geo-register model to coordinate system of given
   camera centers.
 
@@ -328,6 +421,15 @@ available as ``colmap [command]``:
 
 - ``vocab_tree_retriever``: Perform vocabulary tree based image retrieval.
 
+- ``rotation_averager``: Run standalone rotation averaging on the view graph.
+  Estimates global camera rotations from pairwise relative rotations.
+
+- ``view_graph_calibrator``: Calibrate camera intrinsics using the view graph.
+  Estimates focal lengths and other intrinsic parameters from pairwise
+  geometric relations. Should be run before ``global_mapper``, if no good
+  prior camera intrinsics are known, since the global mapper
+  depends on reasonably good focal length priors to perform well.
+
 
 Visualization
 -------------
@@ -336,14 +438,17 @@ If you want to quickly visualize the outputs of the sparse or dense
 reconstruction pipelines, COLMAP offers you the following possibilities:
 
 - The sparse point cloud obtained with the ``mapper`` can be visualized via the
-  COLMAP GUI by importing the following files: choose ``File > Import Model``
-  and select the folder where the three files, ``cameras.txt``, ``images.txt``,
-  and ``points3d.txt`` are located.
+  COLMAP GUI by importing the model files: choose ``File > Import Model``
+  and select the folder containing the sparse model files (``cameras.txt``,
+  ``images.txt``, ``points3D.txt``, etc.).
 
 - The dense point cloud obtained with the ``stereo_fusion`` can be visualized
   via the COLMAP GUI by importing ``fused.ply``: choose
   ``File > Import Model from...`` and then select the file ``fused.ply``.
 
 - The dense mesh model ``meshed-*.ply`` obtained with the ``poisson_mesher`` or
   the ``delaunay_mesher`` can currently not be visualized with COLMAP, instead
-  you can use an external viewer, such as Meshlab.
+  you can use an external viewer, such as Meshlab. Use the ``mesh_simplifier``
+  command to reduce the mesh size for faster visualization or downstream
+  processing. Use the ``mesh_texturer`` command to produce a textured mesh
+  with a texture atlas that can be visualized in Meshlab or other 3D viewers.

_sources/database.rst.txt

@@ -20,7 +20,7 @@ The database contains the following tables:
 - two_view_geometries
 
 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``.
+either create a new project in the GUI or run the ``colmap database_creator`` command.
 
 
 Rigs and Sensors
@@ -70,12 +70,18 @@ keypoints have 4 columns, then the feature geometry is a similarity and the
 third column is the scale and the fourth column the orientation of the feature
 (according to SIFT conventions). If the keypoints have 6 columns, then the
 feature geometry is an affinity and the last 4 columns encode its affine shape
-(see ``src/feature/types.h`` for details).
+(see ``src/colmap/feature/types.h`` for details).
 
-The extracted descriptors are stored as row-major ``uint8`` binary blobs, where
-each row describes the feature appearance of the corresponding entry in the
-keypoints table. Note that COLMAP only supports 128-D descriptors for now, i.e.
-the ``cols`` column must be 128.
+The extracted descriptors are stored as row-major binary blobs, where each row
+describes the feature appearance of the corresponding entry in the keypoints
+table. The data type and dimensionality depend on the feature extractor:
+
+- **SIFT**: ``uint8`` descriptors with 128 dimensions (128 bytes per feature).
+- **ALIKED**: ``float32`` descriptors with 128 dimensions (512 bytes per feature).
+
+The ``cols`` column in the descriptors table specifies the number of bytes per
+descriptor row. For ``uint8`` descriptors, this equals the descriptor dimension.
+For ``float32`` descriptors, this equals ``4 * dimension``.
 
 In both tables, the ``rows`` table specifies the number of detected features per
 image, while ``rows=0`` means that an image has no features. For feature matching
@@ -121,4 +127,4 @@ the ``rows`` column specifies the number of feature matches.
 
 The F, E, H blobs in the ``two_view_geometries`` table are stored as 3x3 matrices
 in row-major ``float64`` format. The meaning of the ``config`` values are documented
-in the ``src/estimators/two_view_geometry.h`` source file.
+in the ``src/colmap/estimators/two_view_geometry.h`` source file.