Stabilo

Stabilo stabilizes video frames and tracked object trajectories against a chosen reference frame, using robust homography or affine registration with optional exclusion masks for dynamic regions. It is the registration engine behind Geo-trax 🚀 and is tuned with Stabilo-Optimize 🎯.

🎬 An accelerated preview of Stabilo's capabilities. Watch the full 14-second 4K demo on YouTube.

Why Stabilo

• 🎯 Anchored, not smoothed: every frame and every tracked box is aligned to one chosen reference frame, so coordinates stay comparable across the whole video, not just between neighbouring frames.
• 🎭 Masks that ignore moving objects: exclude vehicles, pedestrians, or any dynamic region from registration, using five mask geometries (boxes, oriented boxes, four-point boxes, polygons, circles).
• 🧠 Classical and learned features in one API: 6 classical detectors (ORB, SIFT, RootSIFT, BRISK, KAZE, AKAZE) and 5 learned ones (XFeat, DISK, DeDoDe, KeyNet, LoFTR), paired with classical (BF, FLANN) or learned (LightGlue) matchers, see Feature Detectors and Matchers, all swappable with a single flag.
• ⚡ Two acceleration paths: OpenCV CUDA for the classical pipeline (--gpu) and any PyTorch device for the learned models (--device cuda|mps); see Configuration.
• 📦 Library and CLI: stabilo video and stabilo tracks need no code; the Stabilizer class embeds into your own pipeline in a handful of lines.
• 🔬 Battle-tested: powers the georeferenced trajectory extraction in Geo-trax, benchmarked ground-truth-free by Stabilo-Optimize.

Installation

It is recommended to create and activate a Python virtual environment (Python >= 3.11 and <= 3.13) first:

python3.11 -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

conda create -n stabilo python=3.11 -y
conda activate stabilo

uv venv --python 3.11
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

Install from PyPI:

pip install stabilo

This installs everything, including the learning-based detectors and matchers (kornia + torch). The first time a learned detector or matcher (xfeat, disk, dedode, keynet, loftr, lightglue) is used, its pretrained weights are downloaded into torch's cache directory (~/.cache/torch/hub/checkpoints on Linux/macOS, %USERPROFILE%\.cache\torch\hub\checkpoints on Windows; override with the TORCH_HOME env var) and reused from there on every later run, offline.

git clone https://github.com/rfonod/stabilo.git
cd stabilo && pip install -e '.[dev]'

Quick Start

data/video.mp4 is a short drone clip bundled for immediate testing, along with per-frame vehicle boxes in data/video.txt. See data/README.md for the reference outputs.

# Stabilize the video against frame 0, saving the result and a side-by-side visualization
stabilo video data/video.mp4 --save --save-viz --output data/out/

# Stabilize the vehicle trajectories, using the same boxes as exclusion masks
stabilo tracks data/video.mp4 --save --save-viz --output data/out/

Both write into the git-ignored data/out/, so you can diff your results against the reference files committed in data/ without overwriting them. Run stabilo -h, stabilo video -h, or stabilo tracks -h for the full option list.

Feature Detectors and Matchers

Stabilo ships classical OpenCV detectors and learning-based detectors/matchers from kornia as core functionality. The learning-based options download pretrained weights on first use (see Installation) and benefit from a GPU (--device cuda or --device mps).

Three matchers are available: bf (brute force) and flann work with every detector, while the learned lightglue pairs with disk, dedode, and keynet. loftr is detector-free: it matches an image pair directly, so matcher_name and filter_type are ignored. Full details in docs/usage.md.

Configuration

Every tunable parameter lives in one self-contained YAML file, stabilo/cfg/default.yaml, grouped by stage: feature detection, matching and filtering, transformation estimation, exclusion masks, pre-processing, hardware acceleration, detector-specific settings, and diagnostics. The shipped defaults are tuned for high-altitude bird's-eye-view drone imagery.

The same keys are accepted as Stabilizer(**kwargs) arguments, as CLI flags, and as entries in a custom YAML file:

stabilo video data/video.mp4 --save -o data/out/ --detector-name disk --matcher-name lightglue
stabilo video data/video.mp4 --save -o data/out/ --custom-config custom.yaml

Precedence is explicit CLI flags > custom config file > built-in defaults: a value in --custom-config fills in anything you didn't pass on the command line, but an explicit CLI flag always wins.

Two independent, mutually exclusive acceleration knobs are worth calling out:

stabilo config show                 # print the default configuration
stabilo config copy                 # write an editable copy to ./custom.yaml
stabilo config copy -o ~/myproject  # write it somewhere else

stabilo config copy
# edit custom.yaml ...
stabilo video data/video.mp4 --save -o data/out/ --custom-config custom.yaml

Library Usage

from stabilo import Stabilizer

stabilizer = Stabilizer()                            # see Configuration for kwargs

stabilizer.set_ref_frame(ref_frame, ref_mask)        # anchor frame (+ optional exclusion mask)
stabilizer.stabilize(cur_frame, cur_mask)            # register any other frame against it

stabilized_frame = stabilizer.warp_cur_frame()       # the warped frame
stabilized_boxes = stabilizer.transform_cur_boxes()  # the transformed boxes
matrix = stabilizer.get_cur_trans_matrix()           # current -> reference transform

Masks and boxes accept five formats: xywh (axis-aligned), xywha (oriented), four (four corner points), polygon, and circle.

import numpy as np

# Oriented bounding boxes (OBBs): [x_center, y_center, width, height, angle_degrees]
obb_boxes = np.array([
    [100, 150, 50, 30, 45],
    [200, 200, 60, 40, 90],
])
stabilizer.set_ref_frame(ref_frame, obb_boxes, box_format='xywha')
stabilizer.stabilize(cur_frame, cur_boxes, box_format='xywha')

# Convert the result to another format on the way out
transformed = stabilizer.transform_cur_boxes(out_box_format='four')

# Polygon masks: flattened [x1, y1, ..., xN, yN] rows, or (N, 2) point arrays
polygon_masks = np.array([
    [60, 60, 120, 60, 120, 120, 60, 120],
    [200, 200, 260, 210, 240, 270, 190, 260],
])
stabilizer.set_ref_frame(ref_frame, polygon_masks, box_format='polygon')

# Circular masks: [x_center, y_center, radius]
circle_masks = np.array([
    [120, 120, 25],
    [360, 240, 40],
])
stabilizer.stabilize(cur_frame, circle_masks, box_format='circle')

# Transform an arbitrary pixel coordinate into reference-frame coordinates
ref_point = stabilizer.get_cur_trans_matrix() @ np.array([x, y, 1])

When a CLI command runs, stabilo performs a best-effort check for a newer release on PyPI and prints a one-line notice if one is available. Set STABILO_DISABLE_UPDATE_CHECK=1 to disable it.

Documentation

• docs/usage.md: detailed usage guide covering the workflow, mask formats, every configuration key, the detector and matcher reference, RANSAC methods, visualization, benchmarking, and the CLI.
• docs/cuda.md: building OpenCV with CUDA and enabling --gpu.
• scripts/README.md: the threshold-analysis research tool.

Citing This Work

If you use Stabilo in your research, software, or product, please cite the following resources appropriately:

1. Preferred Citation: Please cite the associated article for any use of the Stabilo package, including research, applications, and derivative work:

   @article{fonod2025advanced,
     title = {Advanced computer vision for extracting georeferenced vehicle trajectories from drone imagery},
     author = {Fonod, Robert and Cho, Haechan and Yeo, Hwasoo and Geroliminis, Nikolas},
     journal = {Transportation Research Part C: Emerging Technologies},
     volume = {178},
     pages = {105205},
     year = {2025},
     publisher = {Elsevier},
     doi = {10.1016/j.trc.2025.105205},
     url = {https://doi.org/10.1016/j.trc.2025.105205}
   }
   

2. Repository Citation: If you reference, modify, or build upon the Stabilo software itself, please also cite the corresponding Zenodo release:

   @software{fonod2026stabilo,
     author = {Fonod, Robert},
     license = {MIT},
     month = sep,
     title = {Stabilo: A Comprehensive Python Library for Video and Trajectory Stabilization with User-Defined Masks},
     url = {https://github.com/rfonod/stabilo},
     doi = {10.5281/zenodo.12117092},
     version = {1.4.3},
     year = {2026}
   }
   

Contributing

Contributions from the community are welcome! If you encounter any issues or have suggestions for improvements, please open a GitHub Issue or submit a pull request.

License

This project is distributed under the MIT License. See the LICENSE file for more details.