scar-calib 2.0.0__tar.gz

scar_calib-2.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Henry Hölzemann, Michael Schleiss
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

scar_calib-2.0.0/PKG-INFO

@@ -0,0 +1,176 @@
+Metadata-Version: 2.4
+Name: scar-calib
+Version: 2.0.0
+Summary: Satellite-based Calibration for Aerial Recordings
+Author-email: Henry Hölzemann <henry.hoelzemann@fkie.fraunhofer.de>
+License: MIT License
+        
+        Copyright (c) 2026 Henry Hölzemann, Michael Schleiss
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.24
+Requires-Dist: scipy>=1.10
+Requires-Dist: gtsam>=4.2
+Requires-Dist: pyproj>=3.6
+Requires-Dist: opencv-python>=4.8
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: legacy
+Requires-Dist: utm==0.8.1; extra == "legacy"
+Provides-Extra: references
+Requires-Dist: georay>=0.1; extra == "references"
+Requires-Dist: rasterio>=1.3; extra == "references"
+Provides-Extra: germany
+Requires-Dist: georay[germany]>=0.1; extra == "germany"
+Provides-Extra: matching
+Requires-Dist: torch; extra == "matching"
+Requires-Dist: vismatch>=1.3; extra == "matching"
+Provides-Extra: viewer
+Requires-Dist: rerun-sdk>=0.23; extra == "viewer"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: ruff>=0.6; extra == "dev"
+Dynamic: license-file
+
+<table align="center"><tr><td align="center" width="9999">
+<img src="assets/scar_icon.png" align="center" width="150" alt="SCAR icon">
+
+# SCAR
+
+**S**atellite-based **C**alibration for **A**erial **R**ecordings
+</td></tr></table>
+
+SCAR refines the intrinsics of an aerial camera and its extrinsics relative to a GNSS/INS from the
+recording itself: it matches the images against georeferenced orthophotos, lifts the matches to 3D
+anchors with a surface model and optimizes a factor graph (GTSAM) over cameras, anchors and the
+calibration. No calibration target or ground control points are needed.
+
+You provide images with timestamps, INS poses, an initial calibration and reference data:
+
+- **Germany:** official orthophotos and DSMs of the federal states supported by
+  [georaffer](https://github.com/michaelschleiss/georaffer) (NRW, RLP, BW, BY, BB, ...) are downloaded on
+  demand.
+- **Anywhere else:** your own orthophoto and surface model as GeoTIFF/COG/VRT in any CRS (e.g. NAIP +
+  3DEP in the US, national mapping data, your own survey), or your own reference provider.
+
+Frame cameras and event cameras (as reconstructed frames) are supported. The paper version is kept
+frozen as the preset `cvprw2026` and the tag `v1.0.0-cvprw2026`.
+
+## Installation
+
+SCAR needs Python 3.11+.
+
+```bash
+git clone https://github.com/hlzmnhnry/scar.git && cd scar
+pixi install            # environment with GTSAM, pyproj, rasterio, georay; CPU only
+pixi install -e gpu     # + PyTorch/CUDA, learned matchers (vismatch), georaffer, rerun viewer
+```
+
+With pip: `pip install -e ".[references,matching,viewer]"` (add `germany` for German state data).
+[georay](https://github.com/hlzmnhnry/georay) renders the reference views; the `germany` extra adds
+georaffer.
+
+## Quick start
+
+A complete run on a synthetic flight with local GeoTIFF reference data, CPU only and without downloads:
+
+```bash
+pixi run python examples/custom_region_geotiff/make_demo_data.py examples/custom_region_geotiff/demo
+pixi run scar run examples/custom_region_geotiff/config.yaml
+pixi run python examples/custom_region_geotiff/make_demo_data.py --compare examples/custom_region_geotiff/demo
+```
+
+For your own flight:
+
+```bash
+scar init my_flight.yaml --template csv     # or: ltc, event
+scar check my_flight.yaml --render          # time coverage, CRS, reference availability, footprint overlays
+scar run my_flight.yaml --viewer            # collect anchors and optimize; live view in rerun
+scar export runs/my_flight/calibration/calibration.yaml --format kalibr --output camchain.yaml
+```
+
+`scar collect` and `scar optimize` run the two steps separately; `scar evaluate` scores a calibration on
+anchors of an independent test sequence (reprojection error, optionally visual localization). See
+[`examples/`](examples) for an LTC campaign; `scar init --template event` starts an event camera setup.
+
+## Inputs
+
+All inputs are described in one YAML file; the templates in
+[`scar/config/templates`](scar/config/templates) document every option.
+
+| Input | Format |
+| --- | --- |
+| Images | CSV with timestamp and path, a directory of files named by timestamp, or LTC `camera.csv` |
+| Poses | CSV with geodetic (lat, lon, height) or projected positions in any CRS; quaternion or Euler orientation w.r.t. NED or ENU; optional per-sample accuracies |
+| Calibration | SCAR YAML, Kalibr camchain or LTC `camera.json`/`extrinsics.json`; pinhole with radial-tangential distortion |
+| Reference data | georaffer regions (Germany) or local orthophoto and DSM rasters |
+
+Poses are interpolated to the image timestamps (linear position, SLERP rotation), optionally with a
+time offset. The conventions for frames, heights, datums and the meridian convergence are described in
+[docs/coordinate_systems.md](docs/coordinate_systems.md); please read it before using your own data.
+
+## Outputs
+
+A run directory contains the anchors (`anchors.json`), the per-stage results (`calibration/stages.json`),
+the final calibration with the marginal covariance of the intrinsics (`calibration/calibration.yaml`)
+and, with `--viewer`, a rerun recording. `scar export` writes Kalibr, OpenCV and LTC formats.
+
+## Optimization presets
+
+| Preset | Description |
+| --- | --- |
+| `default` | Staged schedule of the paper (rotation, translation, landmarks, calibration, full) followed by a least-squares fit of the extrinsics; use with the corrected pose processing (default of all templates) |
+| `cvprw2026` | Frozen paper configuration; together with `paper/cvprw2026` it reproduces the published results |
+| `joint` | Experimental: extrinsics as a variable of the factor graph instead of the least-squares fit |
+
+## Reproducing the paper
+
+[`paper/cvprw2026`](paper/cvprw2026) contains the scripts, campaign definitions and initial calibrations
+of the CVPRW 2026 evaluation, the reproduction log and an ablation of geodetic corrections that were not
+part of the paper version (float32 coordinates, meridian convergence, heights, interpolation).
+The meridian convergence correction alone lowers the test reprojection error by 21 % on average over the
+six LTC campaigns.
+
+## Development
+
+```bash
+pixi run test           # unit, synthetic and system tests; regression tests need local LTC data
+pixi run -e repro test  # bit-exact paper regression with GTSAM 4.2.0
+```
+
+## Citation
+
+If you use SCAR in academic work, please cite:
+
+```bibtex
+@InProceedings{Holzemann_2026_CVPR,
+    author    = {H\"olzemann, Henry and Schleiss, Michael},
+    title     = {SCAR: Satellite Imagery-Based Calibration for Aerial Recordings},
+    booktitle = {Proceedings of the IEEE/CVF Conference on Computer Vision and Pattern Recognition (CVPR) Workshops},
+    month     = {June},
+    year      = {2026},
+    pages     = {987-996}
+}
+```
+
+Reference data obtained through georaffer are subject to the licenses of the respective providers
+(e.g. NRW: dl-de/zero-2.0, RLP: dl-de/by-2.0); SCAR does not redistribute them.

scar_calib-2.0.0/README.md

@@ -0,0 +1,123 @@
+<table align="center"><tr><td align="center" width="9999">
+<img src="assets/scar_icon.png" align="center" width="150" alt="SCAR icon">
+
+# SCAR
+
+**S**atellite-based **C**alibration for **A**erial **R**ecordings
+</td></tr></table>
+
+SCAR refines the intrinsics of an aerial camera and its extrinsics relative to a GNSS/INS from the
+recording itself: it matches the images against georeferenced orthophotos, lifts the matches to 3D
+anchors with a surface model and optimizes a factor graph (GTSAM) over cameras, anchors and the
+calibration. No calibration target or ground control points are needed.
+
+You provide images with timestamps, INS poses, an initial calibration and reference data:
+
+- **Germany:** official orthophotos and DSMs of the federal states supported by
+  [georaffer](https://github.com/michaelschleiss/georaffer) (NRW, RLP, BW, BY, BB, ...) are downloaded on
+  demand.
+- **Anywhere else:** your own orthophoto and surface model as GeoTIFF/COG/VRT in any CRS (e.g. NAIP +
+  3DEP in the US, national mapping data, your own survey), or your own reference provider.
+
+Frame cameras and event cameras (as reconstructed frames) are supported. The paper version is kept
+frozen as the preset `cvprw2026` and the tag `v1.0.0-cvprw2026`.
+
+## Installation
+
+SCAR needs Python 3.11+.
+
+```bash
+git clone https://github.com/hlzmnhnry/scar.git && cd scar
+pixi install            # environment with GTSAM, pyproj, rasterio, georay; CPU only
+pixi install -e gpu     # + PyTorch/CUDA, learned matchers (vismatch), georaffer, rerun viewer
+```
+
+With pip: `pip install -e ".[references,matching,viewer]"` (add `germany` for German state data).
+[georay](https://github.com/hlzmnhnry/georay) renders the reference views; the `germany` extra adds
+georaffer.
+
+## Quick start
+
+A complete run on a synthetic flight with local GeoTIFF reference data, CPU only and without downloads:
+
+```bash
+pixi run python examples/custom_region_geotiff/make_demo_data.py examples/custom_region_geotiff/demo
+pixi run scar run examples/custom_region_geotiff/config.yaml
+pixi run python examples/custom_region_geotiff/make_demo_data.py --compare examples/custom_region_geotiff/demo
+```
+
+For your own flight:
+
+```bash
+scar init my_flight.yaml --template csv     # or: ltc, event
+scar check my_flight.yaml --render          # time coverage, CRS, reference availability, footprint overlays
+scar run my_flight.yaml --viewer            # collect anchors and optimize; live view in rerun
+scar export runs/my_flight/calibration/calibration.yaml --format kalibr --output camchain.yaml
+```
+
+`scar collect` and `scar optimize` run the two steps separately; `scar evaluate` scores a calibration on
+anchors of an independent test sequence (reprojection error, optionally visual localization). See
+[`examples/`](examples) for an LTC campaign; `scar init --template event` starts an event camera setup.
+
+## Inputs
+
+All inputs are described in one YAML file; the templates in
+[`scar/config/templates`](scar/config/templates) document every option.
+
+| Input | Format |
+| --- | --- |
+| Images | CSV with timestamp and path, a directory of files named by timestamp, or LTC `camera.csv` |
+| Poses | CSV with geodetic (lat, lon, height) or projected positions in any CRS; quaternion or Euler orientation w.r.t. NED or ENU; optional per-sample accuracies |
+| Calibration | SCAR YAML, Kalibr camchain or LTC `camera.json`/`extrinsics.json`; pinhole with radial-tangential distortion |
+| Reference data | georaffer regions (Germany) or local orthophoto and DSM rasters |
+
+Poses are interpolated to the image timestamps (linear position, SLERP rotation), optionally with a
+time offset. The conventions for frames, heights, datums and the meridian convergence are described in
+[docs/coordinate_systems.md](docs/coordinate_systems.md); please read it before using your own data.
+
+## Outputs
+
+A run directory contains the anchors (`anchors.json`), the per-stage results (`calibration/stages.json`),
+the final calibration with the marginal covariance of the intrinsics (`calibration/calibration.yaml`)
+and, with `--viewer`, a rerun recording. `scar export` writes Kalibr, OpenCV and LTC formats.
+
+## Optimization presets
+
+| Preset | Description |
+| --- | --- |
+| `default` | Staged schedule of the paper (rotation, translation, landmarks, calibration, full) followed by a least-squares fit of the extrinsics; use with the corrected pose processing (default of all templates) |
+| `cvprw2026` | Frozen paper configuration; together with `paper/cvprw2026` it reproduces the published results |
+| `joint` | Experimental: extrinsics as a variable of the factor graph instead of the least-squares fit |
+
+## Reproducing the paper
+
+[`paper/cvprw2026`](paper/cvprw2026) contains the scripts, campaign definitions and initial calibrations
+of the CVPRW 2026 evaluation, the reproduction log and an ablation of geodetic corrections that were not
+part of the paper version (float32 coordinates, meridian convergence, heights, interpolation).
+The meridian convergence correction alone lowers the test reprojection error by 21 % on average over the
+six LTC campaigns.
+
+## Development
+
+```bash
+pixi run test           # unit, synthetic and system tests; regression tests need local LTC data
+pixi run -e repro test  # bit-exact paper regression with GTSAM 4.2.0
+```
+
+## Citation
+
+If you use SCAR in academic work, please cite:
+
+```bibtex
+@InProceedings{Holzemann_2026_CVPR,
+    author    = {H\"olzemann, Henry and Schleiss, Michael},
+    title     = {SCAR: Satellite Imagery-Based Calibration for Aerial Recordings},
+    booktitle = {Proceedings of the IEEE/CVF Conference on Computer Vision and Pattern Recognition (CVPR) Workshops},
+    month     = {June},
+    year      = {2026},
+    pages     = {987-996}
+}
+```
+
+Reference data obtained through georaffer are subject to the licenses of the respective providers
+(e.g. NRW: dl-de/zero-2.0, RLP: dl-de/by-2.0); SCAR does not redistribute them.

scar_calib-2.0.0/pyproject.toml

@@ -0,0 +1,104 @@
+[build-system]
+requires = ["setuptools>=64", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "scar-calib"
+version = "2.0.0"
+description = "Satellite-based Calibration for Aerial Recordings"
+authors = [{ name = "Henry Hölzemann", email = "henry.hoelzemann@fkie.fraunhofer.de" }]
+readme = "README.md"
+license = { file = "LICENSE" }
+requires-python = ">=3.11"
+dependencies = [
+    "numpy>=1.24",
+    "scipy>=1.10",
+    "gtsam>=4.2",
+    "pyproj>=3.6",
+    "opencv-python>=4.8",
+    "pyyaml>=6.0",
+]
+
+[project.optional-dependencies]
+legacy = ["utm==0.8.1"]
+references = ["georay>=0.1", "rasterio>=1.3"]
+germany = ["georay[germany]>=0.1"]
+matching = ["torch", "vismatch>=1.3"]
+viewer = ["rerun-sdk>=0.23"]
+dev = ["pytest>=7.0", "ruff>=0.6"]
+
+[project.scripts]
+scar = "scar.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["scar*"]
+
+[tool.setuptools.package-data]
+scar = ["config/presets/*.yaml", "config/templates/*.yaml"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+markers = [
+    "regression: needs local legacy anchors and INS data (set SCAR_TEST_DATA)",
+]
+
+[tool.pixi.workspace]
+channels = ["conda-forge"]
+platforms = ["linux-64"]
+
+[tool.pixi.dependencies]
+rasterio = ">=1.3"
+numpy = ">=1.24"
+scipy = ">=1.10"
+pyproj = ">=3.6"
+pyyaml = ">=6.0"
+
+[tool.pixi.feature.latest.dependencies]
+python = "3.12.*"
+gtsam = ">=4.3"
+
+# bit-exact reproduction of the CVPRW 2026 results (GTSAM version of the original environment)
+[tool.pixi.feature.repro.dependencies]
+python = "3.11.*"
+gtsam = { version = "==4.2.0", build = "py311hc9e34d7_12" }
+
+[tool.pixi.feature.dev.dependencies]
+pytest = ">=7.0"
+ruff = ">=0.6"
+
+[tool.pixi.pypi-dependencies]
+scar-calib = { path = ".", editable = true, extras = ["legacy"] }
+georay = ">=0.1"
+
+[tool.pixi.activation.env]
+# keep system-wide Python paths (e.g. ROS) out of the environment
+PYTHONPATH = ""
+
+# GPU matchers (torch + vismatch); several GB, install on demand: pixi install -e gpu
+[tool.pixi.feature.gpu.system-requirements]
+cuda = "12"
+
+[tool.pixi.feature.gpu.dependencies]
+pytorch-gpu = ">=2.4"
+torchvision = "*"
+setuptools = ">=83"
+rerun-sdk = ">=0.23"
+
+[tool.pixi.feature.gpu.pypi-dependencies]
+vismatch = ">=1.3"
+
+# German state tiles (NRW, RLP, ...) for the georay reference provider
+[tool.pixi.feature.germany.dependencies]
+libgdal-jp2openjpeg = "*"   # GDAL driver for the JP2 orthophotos of NRW and others
+
+[tool.pixi.feature.germany.pypi-dependencies]
+georaffer = ">=0.2"
+
+[tool.pixi.environments]
+default = ["latest", "dev"]
+repro = ["repro", "dev"]
+gpu = ["latest", "gpu", "germany", "dev"]
+
+[tool.pixi.tasks]
+test = "python -m pytest"

scar_calib-2.0.0/scar/__init__.py

@@ -0,0 +1,10 @@
+"""SCAR: satellite-based calibration for aerial recordings.
+
+Typical use goes through a run configuration (``scar init``/``scar run``); the library API:
+
+- :mod:`scar.core` data model (camera, poses, frames, anchors), :mod:`scar.geodesy` world frames,
+- :mod:`scar.datasets` / :mod:`scar.sources` inputs, :mod:`scar.references` reference data,
+- :mod:`scar.collect` anchor collection, :mod:`scar.optimize` calibration, :mod:`scar.evaluate` metrics.
+"""
+
+__version__ = "2.0.0"

scar_calib-2.0.0/scar/cli.py

@@ -0,0 +1,234 @@
+"""Command line interface: ``scar init | check | collect | optimize | run | export``."""
+
+from __future__ import annotations
+
+import argparse
+import logging
+import shutil
+import sys
+from pathlib import Path
+
+TEMPLATES = Path(__file__).resolve().parent / "config" / "templates"
+
+
+def _viewer(config, enabled: bool):
+    if not (enabled or config.viewer.enabled):
+        return None
+    from scar.viz.rerun_viewer import RerunViewer
+
+    save = str(config.path(config.viewer.save)) if config.viewer.save else None
+    return RerunViewer(application_id=config.name, spawn=config.viewer.spawn, save=save)
+
+
+def cmd_init(args) -> int:
+    source = TEMPLATES / f"{args.template}.yaml"
+    target = Path(args.path)
+    if target.exists() and not args.force:
+        print(f"{target} exists (use --force to overwrite)", file=sys.stderr)
+        return 1
+    target.parent.mkdir(parents=True, exist_ok=True)
+    shutil.copyfile(source, target)
+    print(f"wrote {target}; edit the paths and run 'scar check {target}'")
+    return 0
+
+
+def cmd_check(args) -> int:
+    import numpy as np
+
+    from scar.config.schema import load_run_config
+    from scar.pipeline import prepare_sequence
+
+    config = load_run_config(args.config)
+    prepared = prepare_sequence(config)
+    sequence = prepared.sequence
+    frames = sequence.frames
+    positions = np.asarray([f.pose_prior.T_world_body[:3, 3] for f in frames])
+    duration = (frames[-1].timestamp_ns - frames[0].timestamp_ns) * 1e-9
+    camera = sequence.camera
+
+    print(f"sequence   {len(frames)} frames over {duration:.1f} s, path {np.sum(np.linalg.norm(np.diff(positions, axis=0), axis=1)):.0f} m")
+    print(f"camera     {camera.width}x{camera.height}, f = ({camera.fx:.1f}, {camera.fy:.1f}), c = ({camera.cx:.1f}, {camera.cy:.1f}), "
+          f"distortion {[round(float(d), 5) for d in camera.distortion]}")
+    print(f"world      {sequence.world_frame.crs}, heights {sequence.world_frame.height.kind}"
+          f"{' (' + sequence.world_frame.height.name + ')' if sequence.world_frame.height.name else ''}, "
+          f"meridian convergence {'on' if sequence.world_frame.apply_meridian_convergence else 'off'}")
+    print(f"positions  x {positions[:, 0].min():.1f}..{positions[:, 0].max():.1f}, y {positions[:, 1].min():.1f}..{positions[:, 1].max():.1f}, "
+          f"height {positions[:, 2].min():.1f}..{positions[:, 2].max():.1f}")
+    missing = [f.image_path for f in frames[:: max(1, len(frames) // 20)] if not prepared.images.resolve(f.image_path).exists()]
+    if missing:
+        print(f"images     MISSING, e.g. {prepared.images.resolve(missing[0])}")
+        return 1
+    print("images     found")
+
+    if args.render:
+        import cv2
+
+        from scar.pipeline import reference_provider
+
+        references = reference_provider(config, sequence.world_frame)
+        output = config.path(config.output) / "check"
+        output.mkdir(parents=True, exist_ok=True)
+        for frame in (frames[0], frames[len(frames) // 2], frames[-1]):
+            view = references.render(frame.pose_prior.T_world_camera(sequence.extrinsics), camera)
+            image = cv2.cvtColor(prepared.read_image(frame), cv2.COLOR_GRAY2BGR)
+            reference = cv2.cvtColor(view.image, cv2.COLOR_RGB2BGR)
+            scale = image.shape[0] / reference.shape[0]
+            reference = cv2.resize(reference, (int(reference.shape[1] * scale), image.shape[0]))
+            path = output / f"frame_{frame.frame_id:05d}.png"
+            cv2.imwrite(str(path), np.hstack([image, reference]))
+            print(f"reference  frame {frame.frame_id}: {view.image.shape[1]}x{view.image.shape[0]} px at "
+                  f"{view.metadata['pixels_per_meter']} px/m -> {path}")
+    return 0
+
+
+def _collect(config, args):
+    from scar.pipeline import prepare_sequence, run_collect
+
+    prepared = prepare_sequence(config)
+    viewer = _viewer(config, args.viewer)
+    on_frame = None
+    if viewer is not None:
+        sequence = prepared.sequence
+
+        def on_frame(report):
+            viewer.on_frame(report, report.frame.pose_prior.T_world_camera(sequence.extrinsics), sequence.camera)
+    return run_collect(config, resume=args.resume, on_frame=on_frame, prepared=prepared), viewer
+
+
+def cmd_collect(args) -> int:
+    from scar.config.schema import load_run_config
+
+    config = load_run_config(args.config)
+    result, _ = _collect(config, args)
+    print(f"{len(result.landmarks)} anchors, {len(result.observations)} observations -> "
+          f"{config.path(config.output) / 'anchors.json'}")
+    return 0
+
+
+def _report_calibration(result, config) -> None:
+    from scar.core.se3 import rotation_angle
+
+    camera = result.camera
+    problem = result.problem
+    change = rotation_angle(result.T_body_camera[:3, :3], problem.extrinsics.T_body_camera[:3, :3])
+    print(f"optimized  {problem.num_frames} frames, {problem.num_landmarks} anchors, {problem.num_observations} observations")
+    print(f"intrinsics f = ({camera.fx:.2f}, {camera.fy:.2f}), c = ({camera.cx:.2f}, {camera.cy:.2f}), "
+          f"distortion {[round(float(d), 5) for d in camera.distortion]}")
+    print(f"extrinsics rotation changed by {change * 57.29577951308232:.3f} deg")
+    print(f"written    {config.path(config.output) / 'calibration' / 'calibration.yaml'}")
+
+
+def cmd_optimize(args) -> int:
+    from scar.config.schema import load_run_config
+    from scar.pipeline import run_optimize
+
+    config = load_run_config(args.config)
+    result = run_optimize(config)
+    viewer = _viewer(config, args.viewer)
+    if viewer is not None:
+        viewer.on_calibration(result)
+    _report_calibration(result, config)
+    return 0
+
+
+def cmd_run(args) -> int:
+    from scar.config.schema import load_run_config
+    from scar.pipeline import run_optimize
+
+    config = load_run_config(args.config)
+    anchors, viewer = _collect(config, args)
+    result = run_optimize(config, anchors)
+    if viewer is not None:
+        viewer.on_calibration(result)
+    _report_calibration(result, config)
+    return 0
+
+
+def cmd_evaluate(args) -> int:
+    import numpy as np
+
+    from scar.evaluate import (
+        ReprojectionStatistics,
+        estimate_pose_offset,
+        localize,
+        reprojection_errors,
+    )
+    from scar.io import load_camera, load_extrinsics, load_sequence
+
+    anchors = load_sequence(args.anchors)
+    camera, T = load_camera(args.calibration), load_extrinsics(args.calibration).T_body_camera
+    print(f"anchors    {len(anchors.frames)} frames, {len(anchors.landmarks)} anchors, {len(anchors.observations)} observations")
+    print(f"reprojection {ReprojectionStatistics.of(reprojection_errors(anchors, camera, T))}")
+    if args.offsets:
+        offset = estimate_pose_offset(anchors, camera, T, estimate_rotation=True)
+        print(f"offsets    translation {np.round(offset.delta, 3).tolist()} m, time {1000 * offset.dt:+.1f} ms, "
+              f"camera rotation {np.round(offset.omega_deg, 3).tolist()} deg (reprojection then {offset.after})")
+    if args.localize:
+        summary = localize(anchors, camera, T).summary()
+        accuracy = ", ".join(f"{key} {value:.3f}" for key, value in summary["accuracy"].items())
+        print(f"localization {summary['localized']}/{summary['frames']} frames, median rotation "
+              f"{summary['median_rotation_error_deg']:.3f} deg, translation {summary['median_translation_error_m']:.2f} m; {accuracy}")
+    return 0
+
+
+def cmd_export(args) -> int:
+    from scar.io import export_calibration, load_camera, load_extrinsics
+
+    files = export_calibration(args.output, load_camera(args.calibration), load_extrinsics(args.calibration), args.format)
+    for path in files:
+        print(f"wrote {path}")
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="scar", description="Satellite-based calibration for aerial recordings")
+    parser.add_argument("-v", "--verbose", action="store_true", help="log progress (INFO)")
+    commands = parser.add_subparsers(dest="command", required=True)
+
+    init = commands.add_parser("init", help="write a configuration template")
+    init.add_argument("path")
+    init.add_argument("--template", choices=sorted(p.stem for p in TEMPLATES.glob("*.yaml")), default="csv")
+    init.add_argument("--force", action="store_true")
+    init.set_defaults(func=cmd_init)
+
+    check = commands.add_parser("check", help="validate a configuration and its inputs")
+    check.add_argument("config")
+    check.add_argument("--render", action="store_true", help="render references for three frames (needs georay)")
+    check.set_defaults(func=cmd_check)
+
+    for name, func, help_text in (("collect", cmd_collect, "collect anchors"),
+            ("optimize", cmd_optimize, "optimize collected anchors"), ("run", cmd_run, "collect and optimize")):
+        command = commands.add_parser(name, help=help_text)
+        command.add_argument("config")
+        command.add_argument("--viewer", action="store_true", help="show progress in rerun")
+        if name != "optimize":
+            command.add_argument("--resume", action="store_true", help="continue from the last checkpoint")
+        command.set_defaults(func=func)
+
+    evaluate = commands.add_parser("evaluate", help="evaluate a calibration on independent anchors")
+    evaluate.add_argument("anchors", help="anchors.json of a test sequence (collected with the same pose processing)")
+    evaluate.add_argument("--calibration", required=True, help="calibration.yaml to evaluate")
+    evaluate.add_argument("--localize", action="store_true", help="visual localization (PnP) per frame; needs "
+        "per-frame anchors, e.g. collected with tracking disabled")
+    evaluate.add_argument("--offsets", action="store_true", help="estimate translation/time/rotation offsets")
+    evaluate.set_defaults(func=cmd_evaluate)
+
+    export = commands.add_parser("export", help="write a calibration for other tools")
+    export.add_argument("calibration", help="calibration.yaml of a run")
+    export.add_argument("--format", choices=["kalibr", "opencv", "ltc"], required=True)
+    export.add_argument("--output", required=True)
+    export.set_defaults(func=cmd_export)
+
+    args = parser.parse_args(argv)
+    logging.basicConfig(level=logging.INFO if args.verbose else logging.WARNING, format="%(asctime)s %(name)s: %(message)s")
+    try:
+        return args.func(args)
+    except Exception as error:
+        if args.verbose:
+            raise
+        print(f"error: {error}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())