Support calibrated camera rigs

README.md

@@ -30,6 +30,7 @@ estimate camera poses, camera intrinsics, and a sparse 3D map.
 
 - 🔧 [Setup](#setup) — Install dependencies and prepare the environment.
 - 🚀 [Run VidMap](#execution) — Reconstruct a video or image sequence.
+- 📷 [Camera rigs](#camera-rigs) — Configure your cameras.
 - 👀 [Visualization](#visualization) — Explore your reconstruction in the browser or Rerun.
 - 🛠️ [Pipeline Configurations](#configuration) — Customize the frontend and mapping settings.
 - ⚡ [Speed up VidMap](#speed-up-vidmap) — Find settings to make extraction and mapping faster.
@@ -46,7 +47,7 @@ git clone --recursive https://github.com/cvg/vidmap.git && cd vidmap
 
 Build and install [COLMAP](https://github.com/colmap/colmap) and its PyCOLMAP bindings
 [from source](https://colmap.github.io/install.html#build-from-source).
-Last tested with [9e653da](https://github.com/colmap/colmap/commit/9e653da3baaaada926bda6c5286568413fb3e675).
+Last tested with: [COLMAP `b1972bc2`](https://github.com/colmap/colmap/commit/b1972bc226f58e095c8b75bc214f4bb2d8ba57e4).
 For GPU mapper acceleration, build them against
 [Ceres 2.3 or newer](https://ceres-solver.readthedocs.io/latest/installation.html)
 with CUDA and cuDSS instead ([see how to enable](#gpu-acceleration)).
@@ -103,6 +104,23 @@ Both mapping commands write the final COLMAP model under `$OUTPUT_DIR/rec`.
 Resolved `frontend_config.yaml` and `mapping_config.yaml` are written directly
 under `$OUTPUT_DIR`.
 
+See [files and folders](docs/files.md) for image layouts, frame associations,
+configuration files and run artifacts.
+
+### Camera rigs
+
+| Input | Uncalibrated mono | Calibrated mono | Uncalibrated rig | Calibrated rig |
+|---|:---:|:---:|:---:|:---:|
+| Pinhole | [✓](docs/cameras.md#monocular) | [✓](docs/cameras.md#calibrated-monocular) | ✗ | [✓](docs/cameras.md#camera-rigs) |
+| Distorted perspective | ✗ | [✓](docs/cameras.md#calibrated-monocular)¹ | ✗ | [✓](docs/cameras.md#camera-rigs)¹ |
+| Fisheye | ✗ | [✓](docs/cameras.md#calibrated-monocular)¹ | ✗ | [✓](docs/cameras.md#camera-rigs)¹ |
+
+Distorted perspective models: `SIMPLE_RADIAL`, `RADIAL`, `OPENCV`, `FULL_OPENCV`,
+`SIMPLE_DIVISION`, `DIVISION`. See [COLMAP camera models](https://colmap.github.io/cameras.html)
+for model definitions and parameter order.
+
+1. Undistorted to pinhole before mapping. Calibrated rigs may mix camera models.
+
 ## Visualization
 
 ### Browser viewer

docs/cameras.md

@@ -0,0 +1,71 @@
+# Camera setup
+
+Set your input/output paths and choose the config names below (without `.yaml`):
+
+```bash
+python -m vidmap.run --input_data /data/images --output /results/run \
+  --frontend-conf FRONTEND_CONFIG --mapping-conf MAPPING_CONFIG
+```
+
+| Input | `FRONTEND_CONFIG` | `MAPPING_CONFIG` |
+|---|---|---|
+| Uncalibrated monocular | `uncalib/base` | `uncalib/base` |
+| Calibrated examples below | Saved config name | `calib/base` |
+
+## Monocular
+
+The default configuration uses uncalibrated monocular input.
+
+### Calibrated monocular
+
+Use a one-camera rig. Save `vidmap/configs/frontend/my_camera.yaml`:
+
+```yaml
+defaults: [calib/base]
+rig:
+  cameras:
+    - camera_model_name: PINHOLE
+      camera_params: [500, 500, 420, 420]
+```
+
+Replace the calibration with yours. Put timestamp-named images (e.g. `1.000.png`)
+in `/data/images/cam0/`.
+
+## Camera rigs
+
+Example four-camera rig: a stereo pair (0–1), an oblique camera (2), and a rear camera (3).
+
+![Four-camera rig viewing directions](assets/rig-example.svg)
+
+Use synchronized images in `cam0/` through `cam3/`;
+see [input folders and frame association](files.md#input-images). Save `vidmap/configs/frontend/my_rig.yaml`:
+
+```yaml
+defaults: [calib/rig]
+rig:
+  cameras:
+    - camera_model_name: PINHOLE
+      camera_params: [500, 500, 420, 420]  # fx, fy, cx, cy (pixels)
+    - camera_model_name: PINHOLE
+      camera_params: [500, 500, 420, 420]
+      cam_from_rig_rotation: [1, 0, 0, 0]
+      cam_from_rig_translation: [-0.1, 0, 0]
+    - camera_model_name: PINHOLE
+      camera_params: [500, 500, 420, 420]
+      cam_from_rig_rotation: [0.9238795325112867, 0, -0.3826834323650898, 0]
+      cam_from_rig_translation: [-0.1414214, 0, -0.1414214]
+    - camera_model_name: PINHOLE
+      camera_params: [500, 500, 420, 420]
+      cam_from_rig_rotation: [0, 0, 1, 0]
+      cam_from_rig_translation: [0.1, 0, -0.15]
+  match_same_timestamp: [[0, 1], [1, 2]]
+  flag_same_timestamp_as_sequential: [[0, 1]]
+```
+
+Camera 0 is the reference and the default keyframing camera.
+
+In this example:
+
+- **0–1:** Reliable stereo overlap: included in `match_same_timestamp` and `flag_same_timestamp_as_sequential` for sequential losses.
+- **1–2:** Overlap with a larger viewpoint change: included only in `match_same_timestamp`, using loop-closure losses.
+- **3:** No overlap: omitted from `match_same_timestamp`.