stabilo 1.0.0__tar.gz

stabilo-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Robert Fonod
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

stabilo-1.0.0/PKG-INFO

@@ -0,0 +1,209 @@
+Metadata-Version: 2.1
+Name: stabilo
+Version: 1.0.0
+Summary: Stabilizes video or extracted trajectories with respect to a selected reference frame in the video, with optional user-provided masks.
+Author-email: Robert Fonod <robert.fonod@ieee.org>
+License: MIT License
+        
+        Copyright (c) 2024 Robert Fonod
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+Project-URL: Homepage, https://github.com/rfonod/stabilo/
+Project-URL: Repository, https://github.com/rfonod/stabilo/
+Project-URL: Changelog, https://github.com/rfonod/stabilo/releases
+Project-URL: Issues, https://github.com/rfonod/stabilo/issues/
+Keywords: stabilo,video-stabilization,object-stabilization,mask,reference-frame,computer-vision
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Software Development
+Classifier: Topic :: Multimedia :: Video
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy<2.0,>=1.26.4
+Requires-Dist: opencv-python>=4.6.0
+Requires-Dist: pyyaml>=5.3.1
+Requires-Dist: tqdm>=4.64.0
+Provides-Extra: extras
+Requires-Dist: matplotlib>=3.5.0; extra == "extras"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: matplotlib>=3.5.0; extra == "dev"
+
+# Stabilo
+
+[![PyPI Version](https://img.shields.io/pypi/v/stabilo)](https://pypi.org/project/stabilo/) [![GitHub Release](https://img.shields.io/github/v/release/rfonod/stabilo?include_prereleases)](https://github.com/rfonod/stabilo/releases) [![License](https://img.shields.io/github/license/rfonod/stabilo)](https://github.com/rfonod/stabilo/blob/main/LICENSE) [![DOI](https://zenodo.org/badge/816993640.svg)](https://zenodo.org/doi/10.5281/zenodo.12117092) [![Downloads](https://img.shields.io/pypi/dm/stabilo)](https://pypistats.org/packages/stabilo) [![Development Status](https://img.shields.io/badge/development-active-brightgreen)](https://github.com/rfonod/stabilo)
+
+**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](https://github.com/rfonod/geo-trax) 🚀 trajectory extraction framework. Extensive transformation and enhancement options, including multiple feature detectors and matchers, masking techniques, further expand its utility. The repository also includes valuable resources like utility scripts and example videos to demonstrate its capabilities.
+
+![Stabilization Visualization GIF](https://raw.githubusercontent.com/rfonod/stabilo/main/assets/stabilization_visualization.gif?raw=True)
+
+## 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.
+- **Wide Range of Algorithms**: Includes support for various feature detectors (ORB, (R)SIFT, BRISK, (A)KAZE), matchers (BF, FLANN), RANSAC algorithms (MAGSAC++, DEGENSAC, ...), transformation types, and pre-processing options.
+- **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 fairly benchmark with different detectors.
+- **Benchmarking Campaigns**: Use [stabilo-optimize](https://github.com/rfonod/stabilo-optimize) 🎯 to establish benchmarking campaigns to optimize algorithm and hyperparameter selection for specific applications.
+
+<details>
+<summary><b>🚀 Planned Enhancements</b></summary>
+
+- **Unit Tests**: Comprehensive unit test suite to ensure package stability and reliability.
+- **Different Mask Types**: Inclusion of additional mask types (e.g., polygonal, circular) for enhanced precision in stabilization.
+- **GPU Acceleration**: Integration of GPU acceleration to improve processing speed.
+- **Documentation**: Detailed documentation covering the package’s functionality and usage.
+
+</details>
+
+
+## Installation
+
+First, create a **Python Virtual Environment** (Python >= 3.9) using e.g., [Miniconda3](https://docs.anaconda.com/free/miniconda/):
+```bash
+conda create -n stabilo python=3.9 -y
+conda activate stabilo
+```
+    
+Then, install the stabilo library using one of the following options:
+
+### Option 1: Install from PyPI
+You can install the package from PyPI using pip:
+```sh
+pip install stabilo
+```
+
+### Option 2: Install from Source
+You can install the package directly from the repository:
+```sh
+pip install git+https://github.com/rfonod/stabilo.git
+```
+
+### Option 3: Install from Local Source
+
+You can also clone the repository and install the package from the local source:
+
+```sh
+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 .`.
+
+## Example Usage
+
+```python
+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
+``` 
+
+## Utility Scripts
+
+Utility scripts are provided to demonstrate the functionality of the Stabilo package. These scripts can be found in the `scripts` directory.
+
+#### Stabilization Examples
+
+- `stabilize_video.py`: Implements video stabilization relative to a reference frame.
+- `stabilize_boxes.py`: Implements object trajectory stabilization relative to a reference frame.
+
+#### Threshold Analysis
+
+- `find_threshold_models.py`: Computes regression models between detection thresholds and average keypoint counts for BRISK, KAZE, and AKAZE feature detectors.
+
+## Citing This Work
+
+If you use this project in your academic research, commercial products, or any published material, please acknowledge its use by citing it.
+
+1.	**Preferred Citation:** For research-related references, please cite the related paper once it is formally published. A preprint is currently available on [arXiv](https://arxiv.org/abs/2411.02136):
+
+```bibtex
+@misc{fonod2024advanced,
+  title={Advanced computer vision for extracting georeferenced vehicle trajectories from drone imagery}, 
+  author={Robert Fonod and Haechan Cho and Hwasoo Yeo and Nikolas Geroliminis},
+  year={2024},
+  eprint={2411.02136},
+  archivePrefix={arXiv},
+  primaryClass={cs.CV},
+  url={https://arxiv.org/abs/2411.02136},
+  doi={https://doi.org/10.48550/arXiv.2411.02136}
+}
+```
+
+2.	**Repository Citation:** For direct use of the stabilo repository, please cite the software release version on Zenodo. You may refer to the DOI badge above for the correct version or use the BibTeX below:
+
+```bibtex
+@software{fonod2024stabilo,
+author = {Fonod, Robert},
+license = {MIT},
+month = nov,
+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.0.0},
+year = {2024}
+}
+```
+
+To ensure accurate and consistent citations, a CITATION.cff file is included in this repository. GitHub automatically generates a formatted citation from this file, accessible in the "Cite this repository" option at the top right of this page.
+
+Please select the correct citation based on your use:
+- **Methodology:** For referencing the research framework and methodology, cite the journal paper (or preprint if unpublished).
+- **Repository:** For direct use of the code, cite the Zenodo release of this GitHub repository.
+
+
+## Contributing
+
+Contributions are welcome! If you encounter any issues or have suggestions for improvements, please open a [GitHub Issue](https://github.com/rfonod/stabilo/issues) or submit a pull request. Your contributions are greatly appreciated!
+
+
+## License
+
+This project is licensed under the MIT License, an [OSI-approved](https://opensource.org/licenses/MIT) open-source license, which allows for both academic and commercial use. By citing this project, you help support its development and acknowledge the effort that went into creating it. For more details, see the [LICENSE](LICENSE) file. Thank you!

stabilo-1.0.0/README.md

@@ -0,0 +1,151 @@
+# Stabilo
+
+[![PyPI Version](https://img.shields.io/pypi/v/stabilo)](https://pypi.org/project/stabilo/) [![GitHub Release](https://img.shields.io/github/v/release/rfonod/stabilo?include_prereleases)](https://github.com/rfonod/stabilo/releases) [![License](https://img.shields.io/github/license/rfonod/stabilo)](https://github.com/rfonod/stabilo/blob/main/LICENSE) [![DOI](https://zenodo.org/badge/816993640.svg)](https://zenodo.org/doi/10.5281/zenodo.12117092) [![Downloads](https://img.shields.io/pypi/dm/stabilo)](https://pypistats.org/packages/stabilo) [![Development Status](https://img.shields.io/badge/development-active-brightgreen)](https://github.com/rfonod/stabilo)
+
+**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](https://github.com/rfonod/geo-trax) 🚀 trajectory extraction framework. Extensive transformation and enhancement options, including multiple feature detectors and matchers, masking techniques, further expand its utility. The repository also includes valuable resources like utility scripts and example videos to demonstrate its capabilities.
+
+![Stabilization Visualization GIF](https://raw.githubusercontent.com/rfonod/stabilo/main/assets/stabilization_visualization.gif?raw=True)
+
+## 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.
+- **Wide Range of Algorithms**: Includes support for various feature detectors (ORB, (R)SIFT, BRISK, (A)KAZE), matchers (BF, FLANN), RANSAC algorithms (MAGSAC++, DEGENSAC, ...), transformation types, and pre-processing options.
+- **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 fairly benchmark with different detectors.
+- **Benchmarking Campaigns**: Use [stabilo-optimize](https://github.com/rfonod/stabilo-optimize) 🎯 to establish benchmarking campaigns to optimize algorithm and hyperparameter selection for specific applications.
+
+<details>
+<summary><b>🚀 Planned Enhancements</b></summary>
+
+- **Unit Tests**: Comprehensive unit test suite to ensure package stability and reliability.
+- **Different Mask Types**: Inclusion of additional mask types (e.g., polygonal, circular) for enhanced precision in stabilization.
+- **GPU Acceleration**: Integration of GPU acceleration to improve processing speed.
+- **Documentation**: Detailed documentation covering the package’s functionality and usage.
+
+</details>
+
+
+## Installation
+
+First, create a **Python Virtual Environment** (Python >= 3.9) using e.g., [Miniconda3](https://docs.anaconda.com/free/miniconda/):
+```bash
+conda create -n stabilo python=3.9 -y
+conda activate stabilo
+```
+    
+Then, install the stabilo library using one of the following options:
+
+### Option 1: Install from PyPI
+You can install the package from PyPI using pip:
+```sh
+pip install stabilo
+```
+
+### Option 2: Install from Source
+You can install the package directly from the repository:
+```sh
+pip install git+https://github.com/rfonod/stabilo.git
+```
+
+### Option 3: Install from Local Source
+
+You can also clone the repository and install the package from the local source:
+
+```sh
+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 .`.
+
+## Example Usage
+
+```python
+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
+``` 
+
+## Utility Scripts
+
+Utility scripts are provided to demonstrate the functionality of the Stabilo package. These scripts can be found in the `scripts` directory.
+
+#### Stabilization Examples
+
+- `stabilize_video.py`: Implements video stabilization relative to a reference frame.
+- `stabilize_boxes.py`: Implements object trajectory stabilization relative to a reference frame.
+
+#### Threshold Analysis
+
+- `find_threshold_models.py`: Computes regression models between detection thresholds and average keypoint counts for BRISK, KAZE, and AKAZE feature detectors.
+
+## Citing This Work
+
+If you use this project in your academic research, commercial products, or any published material, please acknowledge its use by citing it.
+
+1.	**Preferred Citation:** For research-related references, please cite the related paper once it is formally published. A preprint is currently available on [arXiv](https://arxiv.org/abs/2411.02136):
+
+```bibtex
+@misc{fonod2024advanced,
+  title={Advanced computer vision for extracting georeferenced vehicle trajectories from drone imagery}, 
+  author={Robert Fonod and Haechan Cho and Hwasoo Yeo and Nikolas Geroliminis},
+  year={2024},
+  eprint={2411.02136},
+  archivePrefix={arXiv},
+  primaryClass={cs.CV},
+  url={https://arxiv.org/abs/2411.02136},
+  doi={https://doi.org/10.48550/arXiv.2411.02136}
+}
+```
+
+2.	**Repository Citation:** For direct use of the stabilo repository, please cite the software release version on Zenodo. You may refer to the DOI badge above for the correct version or use the BibTeX below:
+
+```bibtex
+@software{fonod2024stabilo,
+author = {Fonod, Robert},
+license = {MIT},
+month = nov,
+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.0.0},
+year = {2024}
+}
+```
+
+To ensure accurate and consistent citations, a CITATION.cff file is included in this repository. GitHub automatically generates a formatted citation from this file, accessible in the "Cite this repository" option at the top right of this page.
+
+Please select the correct citation based on your use:
+- **Methodology:** For referencing the research framework and methodology, cite the journal paper (or preprint if unpublished).
+- **Repository:** For direct use of the code, cite the Zenodo release of this GitHub repository.
+
+
+## Contributing
+
+Contributions are welcome! If you encounter any issues or have suggestions for improvements, please open a [GitHub Issue](https://github.com/rfonod/stabilo/issues) or submit a pull request. Your contributions are greatly appreciated!
+
+
+## License
+
+This project is licensed under the MIT License, an [OSI-approved](https://opensource.org/licenses/MIT) open-source license, which allows for both academic and commercial use. By citing this project, you help support its development and acknowledge the effort that went into creating it. For more details, see the [LICENSE](LICENSE) file. Thank you!

stabilo-1.0.0/pyproject.toml

@@ -0,0 +1,88 @@
+# ==============================================================
+# Stabilo - MIT License
+# ==============================================================
+# Overview:
+# This pyproject.toml file configures the build system and 
+# project metadata for the Stabilo package. 
+#
+# Installation:
+# To install the Stabilo package, use the following command:
+#   pip install stabilo
+#
+# For development purposes, enabling real-time updates without 
+# reinstallation, use one of the following commands:
+#   pip install -e .[dev]
+#   pip install -e '.[dev]'  (for zsh shells)
+#
+# ==============================================================
+
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "stabilo"
+dynamic = ["version"]
+description = "Stabilizes video or extracted trajectories with respect to a selected reference frame in the video, with optional user-provided masks."
+authors = [
+    { name = "Robert Fonod", email = "robert.fonod@ieee.org" },
+]
+readme = "README.md"
+license = { file = "LICENSE" }
+requires-python = ">=3.9"
+keywords = ["stabilo", "video-stabilization", "object-stabilization", "mask", "reference-frame", "computer-vision"]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Science/Research",
+    "Topic :: Scientific/Engineering",
+    "Topic :: Software Development",
+    "Topic :: Multimedia :: Video",
+]
+
+dependencies = [
+    "numpy>=1.26.4,<2.0",
+    "opencv-python>=4.6.0",
+    "pyyaml>=5.3.1",
+    "tqdm>=4.64.0",
+]
+
+[project.optional-dependencies]
+extras = [
+    "matplotlib>=3.5.0"
+]
+dev = [
+    "pytest>=7.0.0",
+    "matplotlib>=3.5.0"
+]
+
+[tool.setuptools] 
+packages = { find = { where = ["."], include = ["stabilo", "stabilo.*"] } }
+package-data = { "stabilo" = ["**/*.yaml", "**/*.txt"] }
+
+[tool.setuptools.dynamic]
+version = { attr = "stabilo.__version__" }
+
+[project.urls]
+Homepage = "https://github.com/rfonod/stabilo/"
+Repository = "https://github.com/rfonod/stabilo/"
+Changelog = "https://github.com/rfonod/stabilo/releases"
+Issues = "https://github.com/rfonod/stabilo/issues/"
+
+[tool.ruff]
+line-length = 120
+
+[tool.ruff.lint]
+select = ['E', 'F', 'W', 'A', "B", 'PLC', 'PLE', 'PLW', 'I']
+
+[tool.ruff.format]
+docstring-code-format = true
+quote-style = "preserve"

stabilo-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

stabilo-1.0.0/stabilo/__init__.py

@@ -0,0 +1,4 @@
+from .stabilo import Stabilizer
+
+__version__ = '1.0.0'
+__all__ = ['Stabilizer', '__version__']

stabilo-1.0.0/stabilo/cfg/default.yaml

@@ -0,0 +1,57 @@
+# This is the default configuration file (default.yaml) containing optimized parameters 
+# for the ORB detector, brute force (BF) matcher, ratio test, and projective transformation. 
+# This template serves as a starting point for users to customize according to their specific needs.
+#
+# The goal of this optimization was to balance high accuracy without compromising on speed,
+# specifically tailored for high-altitude bird's-eye view (BeV) drone imagery analysis.
+#
+# The optimization involved a set of BeV drone scenes with associated vehicle masks captured 
+# from an altitude of approximately 150 meters. With the projective transformation fixed, 
+# we then optimized all the remaining parameters in a hierarchical manner.
+#
+# Details of the optimization process will be available soon at: 
+# https://github.com/rfonod/stabilo-optimize
+#
+# The detailed description of each parameter is explained in the stabilo.py module.
+
+
+# Image pre-processing related
+clahe: false  # Contrast Limited Adaptive Histogram Equalization (CLAHE); [true, false]
+downsample_ratio: 0.5  # Downsample ratio for image resizing; (0.0, 1.0]
+
+# Feature detectors and descriptors related
+detector_name: 'orb'  # Feature detector name; ['orb', 'sift', 'rsift', 'brisk', 'kaze', 'akaze']
+max_features: 2000  # Maximum number of features to detect; [0, inf)
+ref_multiplier: 2.0  # Reference multiplier for the number of features; (0.0, inf)
+
+# Feature matching and filtering related
+matcher_name: 'bf'  # Feature matcher name; ['bf', 'flann']
+filter_type: 'ratio'  # Filter type; ['none', 'ratio', 'distance']
+filter_ratio: 0.9  # Ratio test threshold; (0.0, 1.0]
+
+# Transformation matrix calculation related
+transformation_type: 'projective'  # Transformation type; ['projective', 'affine']
+ransac_method: 38  # RANSAC method; [4: LMEDS, 8: RANSAC, 16: RHO, 32: DEGENSAC, 33: DEGENSAC (with different parameters), 35: LO-RANSAC, 36: GC-RANSAC, 37: PROSAC, 38: MAGSAC++]
+ransac_epipolar_threshold: 2.0  # Epipolar threshold for RANSAC; (0.0, inf)
+ransac_max_iter: 5000  # Maximum number of iterations for RANSAC; (0, inf]
+ransac_confidence: 0.999999  # Confidence level for RANSAC; (0.0, 1.0]
+
+# Mask related
+mask_use: true  # Use mask for feature matching; [true, false]
+mask_margin_ratio: 0.15  # Margin ratio for mask generation; [0.0, 1.0]
+
+# Default thresholds for BRISK, KAZE, and AKAZE (if threshold analysis not performed)
+brisk_threshold: 130  # BRISK threshold; (0, 255]
+kaze_threshold: 0.01  # KAZE threshold; (0.0, inf]
+akaze_threshold: 0.01  # AKAZE threshold; (0.0, inf]
+
+# Computation related
+gpu: false  # Use GPU for computation; [true, false]
+
+# Miscellaneous
+viz: false  # Store features and matches for visualization; [true, false]
+benchmark: false  # Benchmark mode; [true, false]
+
+# Debug related
+min_good_match_count_warning: 20  # Minimum good match count warning; [0, inf]
+min_inliers_match_count_warning: 10  # Minimum inliers match count warning; [0, inf]