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 \ud83d\ude80 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 \ud83c\udfaf provides a dedicated benchmarking framework. The repository also includes valuable resources like utility scripts and example videos to demonstrate its capabilities.
\n\ud83d\udccc Important: If you use this code in your work, kindly acknowledge it by citing the following article:
\n\n\n\nRobert 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
\n
\ud83d\ude80 Planned Enhancements
\n\ud83d\udd17 Related Projects
\nStabilo integrates with and complements several specialized tools:
\nGeo-trax \ud83d\ude80 — 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.
\nStabilo-Optimize \ud83c\udfaf — Benchmarking and hyperparameter optimization framework for Stabilo. Evaluates stabilization performance through ground truth-free assessment using random perturbations. Used to fine-tune Stabilo parameters.
\nHBB2OBB \ud83d\udce6 — 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.
\nIt is recommended to create and activate a Python Virtual Environment (Python >= 3.9) first. You can use Python's built-in venv module:
python -m venv .venv\nsource .venv/bin/activate # On Windows: .venv\\Scripts\\activateAlternatively, you can use Miniconda3:
\nconda create -n stabilo python=3.11 -y\nconda activate stabiloThen, install the stabilo library using one of the following options:
\n\npip install stabiloYou can also clone the repository and install the package from the local source:
\ngit clone https://github.com/rfonod/stabilo.git\ncd 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 ..
from stabilo import Stabilizer \n\n# Create an instance of the Stabilizer class with default parameters\nstabilizer = Stabilizer() \n\n# Set a reference frame with (optional) mask\nstabilizer.set_ref_frame(ref_frame, ref_mask)\n\n# Stabilize any frame with (optional) mask\nstabilizer.stabilize(cur_frame, cur_mask)\n\n# Get the stabilized (warped) frame \nstabilized_frame = stabilizer.warp_cur_frame()\n\n# Transform current masks (bounding boxes) if it was provided\nstabilized_boxes = stabilizer.transform_cur_boxes()\n\n# Transform any point (pixel coordinates) from the current frame to reference frame\ncur_point = np.array([x, y, 1])\nref_point = stabilizer.get_cur_trans_matrix() @ cur_pointStabilo supports multiple mask and bounding-box formats:
\nxywh: 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 arrayscircle: Circular masks [x_center, y_center, radius]import numpy as np\n\n# Example with oriented bounding boxes (OBBs)\nobb_boxes = np.array([\n [100, 150, 50, 30, 45], # Rotated 45 degrees\n [200, 200, 60, 40, 90], # Rotated 90 degrees\n])\n\nstabilizer.set_ref_frame(ref_frame, obb_boxes, box_format='xywha')\nstabilizer.stabilize(cur_frame, cur_boxes, box_format='xywha')\n\n# Transform boxes and get result in different format\ntransformed = stabilizer.transform_cur_boxes(out_box_format='four')# Polygon mask(s)\npolygon_masks = np.array([\n [60, 60, 120, 60, 120, 120, 60, 120],\n [200, 200, 260, 210, 240, 270, 190, 260],\n])\nstabilizer.set_ref_frame(ref_frame, polygon_masks, box_format='polygon')\n\n# Circular mask(s)\ncircle_masks = np.array([\n [120, 120, 25],\n [360, 240, 40],\n])\nstabilizer.stabilize(cur_frame, circle_masks, box_format='circle')For detailed package documentation, including architecture, end-to-end workflows, mask format specifications, and API behavior notes, see:
\ndocs/usage.mdUtility scripts are provided to demonstrate the functionality of the Stabilo package. These scripts can be found in the scripts directory and are briefly documented in the scripts README.
stabilize_video.py: Implements video stabilization relative to a reference frame.stabilize_boxes.py: Implements object trajectory stabilization relative to a reference frame.find_threshold_models.py: Computes regression models between detection thresholds and average keypoint counts for BRISK, KAZE, and AKAZE feature detectors.If you use Stabilo in your research, software, or product, please cite the following resources appropriately:
\nPreferred Citation: Please cite the associated article for any use of the Stabilo package, including research, applications, and derivative work:
\n@article{fonod2025advanced,\n title = {Advanced computer vision for extracting georeferenced vehicle trajectories from drone imagery},\n author = {Fonod, Robert and Cho, Haechan and Yeo, Hwasoo and Geroliminis, Nikolas},\n journal = {Transportation Research Part C: Emerging Technologies},\n volume = {178},\n pages = {105205},\n year = {2025},\n publisher = {Elsevier},\n doi = {10.1016/j.trc.2025.105205},\n url = {https://doi.org/10.1016/j.trc.2025.105205}\n}Repository Citation: If you reference, modify, or build upon the Stabilo software itself, please also cite the corresponding Zenodo release:
\n@software{fonod2026stabilo,\n author = {Fonod, Robert},\n license = {MIT},\n month = apr,\n title = {Stabilo: A Comprehensive Python Library for Video and Trajectory Stabilization with User-Defined Masks},\n url = {https://github.com/rfonod/stabilo},\n doi = {10.5281/zenodo.12117092},\n version = {1.2.0},\n year = {2026}\n}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.
\n\nThis project is distributed under the MIT License. See the LICENSE file for more details.
\nFull Changelog: https://github.com/rfonod/stabilo/compare/v1.1.0...v1.2.0
", "languages": [ { "id": "eng", "title": { "en": "English" } } ], "publication_date": "2026-05-13", "publisher": "Zenodo", "related_identifiers": [ { "identifier": "https://github.com/rfonod/stabilo/tree/v1.2.0", "relation_type": { "id": "issupplementto", "title": { "de": "Erg\u00e4nzt", "en": "Is supplement to" } }, "resource_type": { "id": "software", "title": { "de": "Software", "en": "Software" } }, "scheme": "url" }, { "identifier": "https://github.com/rfonod/geo-trax/", "relation_type": { "id": "isreviewedby", "title": { "de": "Wird begutachtet von", "en": "Is reviewed by" } }, "resource_type": { "id": "software", "title": { "de": "Software", "en": "Software" } }, "scheme": "url" }, { "identifier": "arXiv:2411.02136", "relation_type": { "id": "isdescribedby", "title": { "de": "Wird beschrieben von", "en": "Is described by" } }, "resource_type": { "id": "publication-preprint", "title": { "de": "Preprint", "en": "Preprint" } }, "scheme": "arxiv" }, { "identifier": "10.1016/j.trc.2025.105205", "relation_type": { "id": "isdescribedby", "title": { "de": "Wird beschrieben von", "en": "Is described by" } }, "resource_type": { "id": "publication-article", "title": { "de": "Zeitschriftenartikel", "en": "Journal article" } }, "scheme": "doi" }, { "identifier": "https://github.com/rfonod/stabilo-optimize/", "relation_type": { "id": "isrequiredby", "title": { "de": "Wird gefordert von", "en": "Is required by" } }, "resource_type": { "id": "software", "title": { "de": "Software", "en": "Software" } }, "scheme": "url" } ], "resource_type": { "id": "software", "title": { "de": "Software", "en": "Software" } }, "rights": [ { "description": { "en": "A short and simple permissive license with conditions only requiring preservation of copyright and license notices. Licensed works, modifications, and larger works may be distributed under different terms and without source code." }, "id": "mit", "props": { "scheme": "spdx", "url": "https://opensource.org/licenses/MIT" }, "title": { "en": "MIT License" } } ], "subjects": [ { "subject": "RANSAC" }, { "subject": "Homography Estimation" }, { "subject": "Feature Matching" }, { "subject": "Video Stabilization" }, { "subject": "Python" }, { "subject": "OpenCV" }, { "subject": "Image Registration" }, { "subject": "Feature Extraction" }, { "subject": "Video Processing" }, { "subject": "Image Processing" }, { "id": "euroscivoc:935", "identifiers": [ { "identifier": "http://data.europa.eu/8mn/euroscivoc/c3f7741c-652b-44cc-9062-491fc41aed2f", "scheme": "url" } ], "props": { "parents": "euroscivoc:23,euroscivoc:47,euroscivoc:297" }, "scheme": "EuroSciVoc", "subject": "Computer vision" }, { "subject": "Stabilization" }, { "subject": "Reference Frame" }, { "subject": "Frame Alignment" } ], "title": "Stabilo: A Comprehensive Python Library for Video and Trajectory Stabilization with User-Defined Masks", "version": "v1.2.0" }, "parent": { "access": { "owned_by": { "user": "305396" }, "settings": { "accept_conditions_text": null, "allow_guest_requests": false, "allow_user_requests": false, "secret_link_expiration": 0 } }, "communities": { "default": "3c1383da-d7ab-4167-8f12-4d8aa0cc637f", "entries": [ { "access": { "member_policy": "open", "members_visibility": "public", "record_submission_policy": "open", "review_policy": "closed", "visibility": "public" }, "children": { "allow": false }, "created": "2013-10-17T09:43:15+00:00", "custom_fields": {}, "deletion_status": { "is_deleted": false, "status": "P" }, "id": "3c1383da-d7ab-4167-8f12-4d8aa0cc637f", "links": {}, "metadata": { "curation_policy": "The MUST criteria are required in order to accept a work into the EPFL community.
\nReferences to works accepted in the EPFL Community will be imported on Infoscience for improved visibility. If allowed by the license, openly accessible works related to publications will be archived in the EPFL Academic Output Archive, ACOUA.
\nMUST
\nM1. At least one author is affiliated with EPFL at the time of the submission or creation of the submitted work.
\nM2. Contact information for at least one EPFL author is provided, preferably through an ORCID identifier.
\nM3. The content of the submitted work must be accessible for review, i.e. Open Access, or Restricted after an access request has been granted to the reviewers. Embargoed works will be reviewed after the embargo expires.
\nM4. The Description of the submitted work is sufficiently detailed. Mere references to external articles or to other external resources are not sufficient descriptions.
\nM5. The submitted work includes a clearly identifiable README file, typically in the root directory. This is not required for works consisting in one single document (ex. publication, poster, or presentation).
\nM6. The main DOI has been assigned by Zenodo. Entering an existing DOI as the main identifier is allowed only if the submitted work is an exact copy of a digital object that has already received its DOI on another platform. For example, supplementary data to a journal article should NOT re-use the journal article DOI.
\nRECOMMENDED
\nR1. All authors are identified by their ORCID.
\nR2. The main title is human-readable on the same level as conventional publications: filenames or coded expressions are deprecated.
\nR3. If existing, references to related publications (e.g., article, source code, other datasets, etc.) are specified in the \"Related works\" field. If available, references are designated by their respective DOIs.
\nR4. If related grants require an acknowledgement, they are listed using “Funding/Grants” fields.
\nR5. Any personal and sensitive data has been anonymized.
\nNICE TO HAVE
\nN1. The submitted work has been cleaned up (e.g., there are no temporary files, no unnecessary empty files or folders, no superfluous file versions, etc.).
\nN2. Permissive licenses are preferred. CC0, CC-BY-4.0, CC-BY-SA-4.0 for data and MIT, BSD, GPL for code are suggested.
\nN3. The README file contains detailed information about the work creation (authors, time, place, methodologies…), content (file organization and naming, formats, relevant standards…), sharing and access, etc.
\nN4. If the submission is related to a PhD thesis, the supervisor is specified.
\nN5. Files are available in open formats. If proprietary formats are present, the work also includes versions of the files converted to open formats, with the least possible loss of information.
\nN6. Where applicable, sources from which the work is derived are specified in the “References” field.
\nN7. Keywords are entered as separated fields in the “Keywords and subjects” field.
", "description": "Research data, code, other resources and academic output shared by EPFL members.", "organizations": [ { "id": "02s376052" } ], "page": "Research data, code, other resources and academic output shared by EPFL members.
\nThe aim of the EPFL Community on Zenodo is to strengthen the visibility and re-usability of the datasets produced by EPFL researchers, and to facilitate the dissemination of information (links between publications and data; potential re-use by other researchers; reporting for scientific grants; etc.). This community was created to showcase datasets and software, but any upload type can be submitted. However, we generally recommend EPFL’s institutional repository Infoscience instead of Zenodo for the following types: Publication, Poster, Presentation and Lesson.
\nFor support with your upload and curation, or for any questions about this community, please contact the RDM team of EPFL Library at researchdata@epfl.ch.
\nThe MUST criteria are required to accept a work into the EPFL community.
\nReferences to works accepted in the EPFL Community will be imported on Infoscience for improved visibility. If allowed by the license, openly accessible works related to publications will be archived in the EPFL Academic Output Archive, ACOUA.
\nMUST
\nM1. At least one author is affiliated with EPFL at the time of the submission or creation of the submitted work.
\nM2. Contact information for at least one EPFL author is provided, preferably through an ORCID identifier.
\nM3. The content of the submitted work must be accessible for review, i.e. Open Access, or Restricted after an access request has been granted to the reviewers. Embargoed works will be reviewed after the embargo expires.
\nM4. The Description of the submitted work is sufficiently detailed. Mere references to external articles or to other external resources are not sufficient descriptions.
\nM5. The submitted work includes a clearly identifiable README file, typically in the root directory. This is not required for works consisting in one single document (ex. publication, poster, or presentation).
\nM6. The main DOI has been assigned by Zenodo. Entering an existing DOI as the main identifier is allowed only if the submitted work is an exact copy of a digital object that has already received its DOI on another platform. For example, supplementary data to a journal article should NOT re-use the journal article DOI.
\nRECOMMENDED
\nR1. All authors are identified by their ORCID.
\nR2. The main title is human-readable on the same level as conventional publications: filenames or coded expressions are deprecated.
\nR3. If existing, references to related publications (e.g., article, source code, other datasets, etc.) are specified in the \"Related works\" field. If available, references are designated by their respective DOIs.
\nR4. If related grants require an acknowledgement, they are listed using “Funding/Grants” fields.
\nR5. Any personal and sensitive data has been anonymized.
\nNICE TO HAVE
\nN1. The submitted work has been cleaned up (e.g., there are no temporary files, no unnecessary empty files or folders, no superfluous file versions, etc.).
\nN2. Permissive licenses are preferred. CC0, CC-BY-4.0, CC-BY-SA-4.0 for data and MIT, BSD, GPL for code are suggested.
\nN3. The README file contains detailed information about the work creation (authors, time, place, methodologies…), content (file organization and naming, formats, relevant standards…), sharing and access, etc.
\nN4. If the submission is related to a PhD thesis, the supervisor is specified.
\nN5. Files are available in open formats. If proprietary formats are present, the work also includes versions of the files converted to open formats, with the least possible loss of information.
\nN6. Where applicable, sources from which the work is derived are specified in the “References” field.
\nN7. Keywords are entered as separated fields in the “Keywords and subjects” field.
\nOnce the curator receives a notification email of a submission, the submission is reviewed against the quality criteria listed in the Curation policy.
\nIf some criteria are not met, the Curator will contact the authors and suggest appropriate modifications. Depending on the importance of the missing criterion, the curator will proceed as follows:
\n