Skip to content

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.

What it does

  • Anchored, not smoothed. Every frame and every tracked box is aligned to one reference frame, so coordinates stay comparable across the whole video, not just between neighbouring frames.
  • Masks that ignore moving objects. Vehicles, pedestrians, or any other dynamic region can be excluded from registration, as axis-aligned boxes, oriented boxes, four-point boxes, polygons, or circles.
  • Classical and learned features in one API. Six classical OpenCV detectors and five learned kornia models, paired with brute-force, FLANN, or LightGlue matching; see Feature detectors and matchers.
  • Two acceleration paths. OpenCV CUDA for the classical pipeline (CUDA) and any PyTorch device for the learned models.
  • Library and CLI. The stabilo command needs no code; the Stabilizer class embeds into your own pipeline.

Installation

Stabilo needs Python 3.11 to 3.13:

pip install stabilo

This installs everything, including the learned detectors and matchers (kornia and torch). Their pretrained weights download into torch's cache the first time each model is used and are reused offline afterwards. See Usage: Installation for virtual-environment, conda, uv, and from-source instructions.

Minimal example

import cv2
from stabilo import Stabilizer

cap = cv2.VideoCapture("video.mp4")
stabilizer = Stabilizer(mask_use=False)  # no exclusion boxes in this example

ok, frame = cap.read()
stabilizer.set_ref_frame(frame)  # frame 0 is the reference

while True:
    ok, frame = cap.read()
    if not ok:
        break
    stabilizer.stabilize(frame)
    stabilized = stabilizer.warp_cur_frame()     # the frame warped onto the reference
    matrix = stabilizer.get_cur_trans_matrix()   # current -> reference transform

To exclude moving objects, keep the default mask_use=True and pass their boxes to set_ref_frame(frame, boxes) and stabilize(frame, boxes); transform_cur_boxes() then maps the boxes into the reference frame. See Usage: Main workflow and Masking behaviour.

The same pipeline from the command line:

stabilo video video.mp4 --save --save-viz
stabilo tracks video.mp4 --save

Demo

A 14-second 4K demo of stabilo on drone footage:

Where to go next