Stabilo: A Comprehensive Python Library for Video and Trajectory Stabilization with User-Defined Masks

Stabilo is a specialized Python package for stabilizing video frames or tracked object trajectories in videos, using robust homography or affine transformations. Its core functionality focuses on aligning each frame or object track to a chosen reference frame, enabling precise stabilization that mitigates disturbances like camera movements. Key features include robust keypoint-based image registration and the option to integrate user-defined masks, which exclude dynamic regions (e.g., moving objects) to enhance stabilization accuracy. Integrating seamlessly with object detection and tracking algorithms, Stabilo is ideal for high-precision applications like urban traffic monitoring, as demonstrated in the Geo-trax 🚀 trajectory extraction framework. Extensive transformation and enhancement options, including multiple feature detectors and matchers, masking techniques, further expand its utility. For systematic evaluation and hyperparameter tuning, the companion tool Stabilo-Optimize 🎯 provides a dedicated benchmarking framework. The repository also includes valuable resources like utility scripts and example videos to demonstrate its capabilities.

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.
• Masks that ignore moving objects: exclude vehicles, pedestrians, or any dynamic region from registration, using five mask geometries.
• Classical and learned features in one API: 6 classical detectors and 5 learning-based ones, paired with classical or learned matchers, all swappable with a single flag.
• Two acceleration paths: OpenCV CUDA for the classical pipeline and any PyTorch device for the learned models.
• Library and CLI: no code required for the stabilo console command; the Stabilizer class embeds into your own pipeline in a handful of lines.

📌 Important: If you use this code in your work, kindly acknowledge it by citing the following article:

Robert Fonod, Haechan Cho, Hwasoo Yeo, Nikolas Geroliminis (2025). Advanced computer vision for extracting georeferenced vehicle trajectories from drone imagery, Transportation Research Part C: Emerging Technologies, vol. 178, 105205. DOI: 10.1016/j.trc.2025.105205

Features

• Video Stabilization: Align (warp) all video frames to a custom (anchor) reference frame using homography or affine transformations.
• Trajectory Stabilization: Transform object trajectories (e.g., bounding boxes) to a common fixed reference frame using homography or affine transformations.
• User-Defined Masks: Allow users to specify custom masks to exclude regions of interest during stabilization, supporting axis-aligned boxes, oriented bounding boxes (OBBs), four-point boxes, polygonal masks, and circular masks.
• Wide Range of Algorithms: 6 classical feature detectors (ORB, SIFT, RSIFT, BRISK, KAZE, AKAZE) and 5 learning-based ones via kornia (XFeat, DISK, DeDoDe, KeyNet, LoFTR), matched with classical (BF, FLANN) or learned (LightGlue) matchers, plus RANSAC algorithms (MAGSAC++, GC-RANSAC, LO-RANSAC, ...), transformation types, and pre-processing options. The learning-based detectors download pretrained weights on first use and, except for KeyNet, are upright models best paired with a reduced downsample ratio; the classical detectors and KeyNet remain rotation invariant.
• Optional CUDA GPU Acceleration: Feature detection, matching, and frame warping can run on an NVIDIA GPU (gpu=True) when built against a CUDA-enabled OpenCV; see docs/cuda.md for build instructions. RANSAC-based transformation estimation always runs on CPU (no OpenCV CUDA equivalent exists). Learning-based detectors run on CPU, CUDA, or Apple MPS via the device option.
• Command-Line Interface: A stabilo console command (stabilo video and stabilo tracks subcommands) for stabilizing videos and object trajectories without writing code.
• Customizable Parameters: Fine-tune the stabilization by adjusting parameters such as the number of keypoints, RANSAC parameters, matching thresholds, downsampling factors, etc..
• Visualization Tools: Generate visualizations of the stabilization process, with frame-by-frame comparisons and trajectory transformations (see the above animation).
• Threshold Analysis: Analyze the relationship between detection thresholds and keypoint counts for BRISK, KAZE, and AKAZE to choose a threshold that yields enough keypoints.
• Benchmarking and Optimization: Fine-tune stabilization parameters with Stabilo-Optimize 🎯, which provides ground truth-free evaluation using random perturbations.

• Bi-directional Matching: Implementing bi-directional matching to enhance the robustness of keypoint matching.
• Additional Feature Detectors: Adding support for more feature detectors and matchers to provide users with a wider range of options for stabilization.

Stabilo integrates with and complements several specialized tools:

• Geo-trax 🚀 — End-to-end framework for extracting georeferenced vehicle trajectories from drone imagery. Uses Stabilo as its core stabilization engine to align video frames and vehicle tracks to a common reference frame.

• Stabilo-Optimize 🎯 — Benchmarking and hyperparameter optimization framework for Stabilo. Evaluates stabilization performance through ground truth-free assessment using random perturbations. Used to fine-tune Stabilo parameters.

• HBB2OBB 📦 — Converts horizontal bounding boxes to oriented bounding boxes using SAM segmentation models. Can be used alongside Stabilo when object orientation is needed for downstream analysis.

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

Miniconda:

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

uv (fastest; use uv pip install in step 3):

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

Then, install the stabilo library using one of the following options:

Option 1: Install from PyPI

pip install stabilo

Option 2: Install from Local Source

You can also clone the repository and install the package from the local source:

git clone https://github.com/rfonod/stabilo.git
cd stabilo && pip install .

If you want the changes you make in the repo to be reflected in your install, use pip install -e . instead of pip install ..

Configuration

Every tunable parameter lives in one self-contained YAML file, stabilo/cfg/default.yaml. The same keys are accepted as Stabilizer(**kwargs) arguments, as CLI flags, and as entries in a custom YAML file passed via --custom-config; precedence is explicit CLI flags > custom config file > built-in defaults. Manage the bundled configuration with stabilo config show and stabilo config copy. Two independent acceleration knobs are available: gpu (OpenCV CUDA, classical detectors only) and device (PyTorch device, learning-based detectors/matchers only).

Library Usage

from stabilo import Stabilizer 

# Create an instance of the Stabilizer class with default parameters
stabilizer = Stabilizer() 

# Set a reference frame with (optional) mask
stabilizer.set_ref_frame(ref_frame, ref_mask)

# Stabilize any frame with (optional) mask
stabilizer.stabilize(cur_frame, cur_mask)

# Get the stabilized (warped) frame 
stabilized_frame = stabilizer.warp_cur_frame()

# Transform current masks (bounding boxes) if it was provided
stabilized_boxes = stabilizer.transform_cur_boxes()

# Transform any point (pixel coordinates) from the current frame to reference frame
cur_point = np.array([x, y, 1])
ref_point = stabilizer.get_cur_trans_matrix() @ cur_point

Bounding Box Formats

Stabilo supports multiple mask and bounding-box formats:

• xywh: Axis-aligned boxes [x_center, y_center, width, height]
• xywha: Oriented bounding boxes [x_center, y_center, width, height, angle_degrees]
• four: Four corner points [x1, y1, x2, y2, x3, y3, x4, y4] (auto-detects if rotated)
• polygon: Polygon points as flattened rows [x1, y1, ..., xN, yN] or (N, 2) point arrays
• circle: Circular masks [x_center, y_center, radius]

import numpy as np

# Example with oriented bounding boxes (OBBs)
obb_boxes = np.array([
    [100, 150, 50, 30, 45],  # Rotated 45 degrees
    [200, 200, 60, 40, 90],  # Rotated 90 degrees
])

stabilizer.set_ref_frame(ref_frame, obb_boxes, box_format='xywha')
stabilizer.stabilize(cur_frame, cur_boxes, box_format='xywha')

# Transform boxes and get result in different format
transformed = stabilizer.transform_cur_boxes(out_box_format='four')

Polygon and Circular Mask Examples

# Polygon mask(s)
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 mask(s)
circle_masks = np.array([
    [120, 120, 25],
    [360, 240, 40],
])
stabilizer.stabilize(cur_frame, circle_masks, box_format='circle')

Documentation

For detailed package documentation, including architecture, end-to-end workflows, mask format specifications, and API behavior notes, see:

• docs/usage.md

Command-Line Interface

Installing stabilo provides a stabilo console command with three subcommands: stabilo video (stabilize a video), stabilo tracks (stabilize object trajectories), and stabilo config (inspect or copy the default configuration). Run stabilo video --help or stabilo tracks --help for the full option reference. Each CLI invocation performs a best-effort check for a newer stabilo release on PyPI.

Threshold Analysis

• find_threshold_models.py: Fits how the average keypoint count of BRISK, KAZE, and AKAZE varies with their detection threshold.

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.4},
     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.