stabilo-benchmark 1.0.0__py3-none-any.whl

stabilo_benchmark/__init__.py

@@ -0,0 +1,8 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+# Author: Robert Fonod (robert.fonod@ieee.org)
+
+"""Stabilo Benchmark - reproducible benchmarks for reference-based UAV video stabilization."""
+
+__version__ = '1.0.0'
+__all__ = ['__version__']

stabilo_benchmark/__main__.py

@@ -0,0 +1,15 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+# Author: Robert Fonod (robert.fonod@ieee.org)
+
+"""Allow `python -m stabilo_benchmark <command>` to behave like the console script."""
+
+import sys
+
+from stabilo_benchmark.cli import main
+
+if __name__ == '__main__':
+    # sys.exit, not a bare call: the console-script wrapper setuptools generates exits with
+    # main()'s return value, and `python -m` must agree with it. Discarding it made every
+    # invocation succeed, so a scripted campaign would run on past a failed stage.
+    sys.exit(main())

stabilo_benchmark/annotation.py

@@ -0,0 +1,72 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+# Author: Robert Fonod (robert.fonod@ieee.org)
+
+"""
+annotation.py - The two hbb2obb commands that annotate an image directory.
+
+    <root>/
+      images/              the frames
+      labels_hbb/          hbb2obb-detect: horizontal boxes, absolute pixels
+      labels_obb/          hbb2obb: oriented boxes, one per horizontal box, same order
+      labels_confidence/   hbb2obb: per-box conversion score (0.0 marks an HBB fallback)
+      PROVENANCE_hbb.txt   hbb2obb-detect: command, settings, checkpoint SHA-256
+      PROVENANCE_obb.txt   hbb2obb: the same for the conversion
+
+The detector is hbb2obb's registered `geotrax` model; the conversion settings are those selected
+for Songdo Vision OBB. The README prints the same two commands, and `tests/test_samples.py`
+checks that they match.
+"""
+
+from __future__ import annotations
+
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+from typing import List, Optional
+
+DETECT_ARGS = ['--model', 'geotrax', '--no_confidence', '--save_provenance']
+# fmt: off
+CONVERT_ARGS = [
+    '--sam_models', 'sam_l',
+    '--imgsz', '1024',
+    '--scale_factors', '0.02',
+    '--opening_kernel_percentage', '-0.1',
+    '--fragment_ratio', '0.1',
+    '--confidence_dir',
+    '--save_provenance',
+]
+# fmt: on
+
+
+class AnnotationError(RuntimeError):
+    """Raised when an hbb2obb command is missing or fails."""
+
+
+def commands(images_dir: Path, device: Optional[str] = None, overwrite: bool = False) -> List[List[str]]:
+    """The hbb2obb-detect and hbb2obb command lines for an image directory."""
+    device_args = ['--device', str(device)] if device else []
+    detect = ['hbb2obb-detect', str(images_dir), *DETECT_ARGS, *device_args, *(['--overwrite'] if overwrite else [])]
+    convert = ['hbb2obb', str(images_dir), *CONVERT_ARGS, *device_args]
+    return [detect, convert]
+
+
+def annotate(images_dir: Path, device: Optional[str] = None, overwrite: bool = False) -> None:
+    """Run both commands; labels land beside `images_dir`."""
+    for command in commands(Path(images_dir), device=device, overwrite=overwrite):
+        executable = _executable(command[0])
+        result = subprocess.run([executable, *command[1:]], check=False)
+        if result.returncode != 0:
+            raise AnnotationError(f"{' '.join(command)} exited with status {result.returncode}")
+
+
+def _executable(name: str) -> str:
+    """The console script beside this interpreter first, so an unactivated venv still finds it."""
+    beside = Path(sys.executable).parent / name
+    if beside.is_file():
+        return str(beside)
+    found = shutil.which(name)
+    if found is None:
+        raise AnnotationError(f"'{name}' was not found. It is installed with hbb2obb: pip install hbb2obb")
+    return found

stabilo_benchmark/cfg/pipelines.yaml

@@ -0,0 +1,131 @@
+# =============================================================================
+# stabilo-benchmark - named registration pipeline presets
+# =============================================================================
+# Each entry is a partial set of stabilo `Stabilizer` keyword arguments; keys absent from
+# stabilo's cfg/default.yaml are rejected by `pipelines.validate_spec`.
+#
+# `masking` (none | hbb | obb) is an experiment-config axis, and `mask_use` is derived from it;
+# neither is set here.
+#
+# `extends: <name>` inherits from another preset; keys given locally win.
+#
+# `filter_ratio` and `ransac_epipolar_threshold` of each benchmarked preset are its mAA-optimal point
+# in configs/songdo/static/tuning.yaml, on the tuning scenes. LightGlue and LoFTR do not apply the ratio
+# test, so only the threshold is set for them.
+# =============================================================================
+
+# -----------------------------------------------------------------------------
+# Shared baseline; every preset inherits from it.
+# -----------------------------------------------------------------------------
+base:
+  matcher_name: bf
+  filter_type: ratio
+  filter_ratio: 0.9
+  transformation_type: projective
+  ransac_method: 38          # MAGSAC++
+  ransac_epipolar_threshold: 2.0
+  ransac_max_iter: 5000
+  ransac_confidence: 0.999999
+  clahe: false
+  downsample_ratio: 1.0      # matched operating point, from configs/songdo/static/budget.yaml
+  max_features: 8000
+  ref_multiplier: 2.0
+  mask_margin_ratio: 0.15
+
+# -----------------------------------------------------------------------------
+# Classical detectors (OpenCV).
+# -----------------------------------------------------------------------------
+orb:
+  extends: base
+  detector_name: orb
+  filter_ratio: 0.85
+  ransac_epipolar_threshold: 4.0
+
+sift:
+  extends: base
+  detector_name: sift
+  filter_ratio: 0.7
+  ransac_epipolar_threshold: 0.5
+
+rsift:
+  extends: base
+  detector_name: rsift
+  filter_ratio: 0.7
+  ransac_epipolar_threshold: 0.5
+
+brisk:
+  extends: base
+  detector_name: brisk
+  filter_ratio: 0.7
+  ransac_epipolar_threshold: 1.5
+
+kaze:
+  extends: base
+  detector_name: kaze
+  filter_ratio: 0.7
+  ransac_epipolar_threshold: 0.5
+
+akaze:
+  extends: base
+  detector_name: akaze
+  filter_ratio: 0.7
+  ransac_epipolar_threshold: 4.0
+
+# -----------------------------------------------------------------------------
+# Learning-based detectors / matchers (kornia, via stabilo >= 1.4.0).
+#
+# `pipelines.check_resolution` warns when a preset exceeds Stabilizer.DL_PIXEL_BUDGETS; a
+# configuration the machine cannot hold is recorded as infeasible and reported as N/A.
+#
+# xfeat / disk / dedode / loftr are upright models: matching degrades past roughly 30 degrees of
+# in-plane rotation. keynet estimates keypoint orientation.
+#
+# lightglue accepts only the detectors in Stabilizer.LIGHTGLUE_FEATURE_NAMES (disk, dedode,
+# keynet), not xfeat.
+# -----------------------------------------------------------------------------
+xfeat:
+  extends: base
+  detector_name: xfeat
+  matcher_name: bf
+  filter_ratio: 0.7
+  ransac_epipolar_threshold: 2.0
+
+disk_lightglue:
+  extends: base
+  detector_name: disk
+  matcher_name: lightglue
+  ransac_epipolar_threshold: 2.0
+
+dedode_lightglue:
+  extends: base
+  detector_name: dedode
+  matcher_name: lightglue
+  ransac_epipolar_threshold: 1.0
+  dedode_detector_weights: L-C4-v2
+  dedode_descriptor_weights: B-upright
+
+keynet_lightglue:
+  extends: base
+  detector_name: keynet
+  matcher_name: lightglue
+  ransac_epipolar_threshold: 4.0
+
+loftr:
+  extends: base
+  detector_name: loftr       # detector-free: matcher_name / filter_type are ignored
+  loftr_weights: outdoor
+  loftr_confidence: 0.0
+
+# -----------------------------------------------------------------------------
+# Reference estimator (pseudo-ground truth) for the dynamic benchmark: the sift preset with its
+# tuned ratio test and inlier threshold, at full resolution with a larger feature budget and a
+# stricter estimator. Its error is bounded by `stabilo-benchmark audit`.
+# -----------------------------------------------------------------------------
+oracle:
+  extends: sift
+  downsample_ratio: 1.0
+  max_features: 20000
+  ref_multiplier: 2.0
+  ransac_max_iter: 20000
+  ransac_confidence: 0.9999999
+  mask_margin_ratio: 0.20