initial commit

.gitignore

@@ -0,0 +1,98 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+pip-wheel-metadata/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+target/
+
+# pyenv
+.python-version
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# VS Code
+.vscode
+!.vscode/settings.json
+!.vscode/tasks.json
+!.vscode/launch.json
+!.vscode/extensions.json
+*.code-workspace
+
+# Local History for Visual Studio Code
+.history/
+
+# Mac OS-specific storage files
+.DS_Store
+**/.DS_Store
+
+# Google Drive related
+.tmp.driveupload
+.tmp.drivedownload
+
+# Data
+/data
+*.mp4
+
+# Misc
+TODOs.txt
+

CITATION.cff

@@ -0,0 +1,20 @@
+cff-version: 1.2.0
+title: Stabilo
+abstract: Reference frame video stabilization with or without user-provided masks.
+message: If you use this software, please cite it as below.
+type: software
+authors:
+  - given-names: Robert
+    family-names: Fonod
+    email: [email protected]
+    affiliation: EPFL
+    orcid: 'https://orcid.org/0000-0002-9434-3156'
+identifiers:
+  - type: doi
+    value: XXX
+    description: Zenodo archive
+repository-code: 'https://github.com/rfonod/stabilo'
+url: 'https://github.com/rfonod/stabilo'
+license: MIT
+version: 0.1.0
+date-released: '2024-06-18'

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.

README.md

@@ -0,0 +1,134 @@
+# Stabilo
+
+![GitHub Release](https://img.shields.io/github/v/release/rfonod/stabilo?include_prereleases) [![License](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT) ![GitHub](https://img.shields.io/badge/Development-Active-brightgreen)
+
+🚧 **Development Notice** 🚧
+
+> ⚠️ **IMPORTANT:** Stabilo is currently in its preliminary stages and under active development. Not all features are complete, and significant changes may occur. It is recommended for experimental use only. Please report any issues you encounter, and feel free to contribute to the project.
+
+Stabilo is a Python package for stabilizing video frames or tracked object trajectories in videos using homography or affine transformations, with optional user-provided masks that define areas to ignore during stabilization. It is optimized for use in environments where accurate, frame-by-frame alignment is crucial, such as video surveillance and research applications. For instance, Stabilo can be integrated with object detection and tracking algorithms to stabilize trajectories, enhancing the performance of such systems. See for example [this project](https://github.com/rfonod/geo-trax). The package offers flexibility through a variety of transformation and enhancement options, including the ability to handle different types of feature detection and masking techniques.
+
+## Features
+
+- **Video Stabilization**: Align video frames to a selected reference using homography or affine transformations.
+- **Trajectory Stabilization**: Apply stabilization to object trajectories using homography or affine transformations.
+- **User-Defined Masks**: Allow users to specify areas to ignore during stabilization, such as bounding boxes of moving objects or regions of no interest.
+- **Wide Range of Algorithms**: Support for various feature detectors (e.g., ORB, (R)SIFT, BRISK, (A)KAZE), matchers (e.g., BF, FLANN), RANSAC algorithms, transformation types, and pre-processing options.
+- **Customizable Parameters**: Fine-tune the stabilization process by adjusting parameters such as the number of keypoints, RANSAC and matching thresholds, and downsampling factors.
+- **Visualization Tools**: Generate visualizations of the stabilization process, including frame-by-frame comparisons.
+- **Threshold Analysis**: Analyze the relationship between detection thresholds and keypoint counts for BRISK, KAZE, and AKAZE feature detectors.
+
+<details>
+<summary><b>🚀 Planned Enhancements</b></summary>
+
+- **Benchmarking and Tuning Tools**: Develop tools to benchmark and tune the performance of the stabilization algorithms.
+- **Trajectory Stabilization Script**: Create a script to stabilize object trajectories in videos. 
+- **Custom Mask Encoding**: Support for more generic types of custom mask encodings.
+- **Custom Reference Frame Selection**: Allow users to select a custom reference frame for stabilization.
+- **GPU Acceleration**: Utilize GPU acceleration for faster processing.
+- **Documentation**: Provide detailed documentation and examples for ease of use.
+- **Unit Tests**: Implement comprehensive unit tests to ensure the stability and reliability of the package.
+- **Deployment to PyPI**: Publish the package on PyPI for easy installation and distribution.
+
+</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 package using one of the following methods:
+
+### Option 1: Install from PyPI
+You can install the package from PyPI (not available yet):
+
+<strike>
+
+```sh
+pip install stabilo
+```
+
+</strike>
+
+
+### Option 2: Install from Source (recommended)
+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
+
+Clone the repository and install the package:
+
+```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 (e.g., bounding boxes)
+stabilizer.set_ref_frame(ref_frame, ref_mask)
+
+# Stabilize any consecutive frame with optional mask
+stabilizer.stabilize(frame, mask)
+
+# Get the stabilized (warped to the reference frame) frame  
+stabilized_frame = stabilizer.warp_cur_frame()
+
+# Get the transformed bounding boxes (if mask was provided)
+stabilized_boxes = stabilizer.transform_cur_boxes()
+``` 
+
+## Additional 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`: Demonstrates video stabilization relative to a reference frame.
+- `stabilize_boxes.py`: Shows how to stabilize bounding boxes relative to a reference frame.
+
+#### Threshold Analysis
+
+The `find_threshold_models.py` script is designed to model the relationship between detection thresholds for BRISK, KAZE, and AKAZE feature detectors and their average keypoint counts. It outputs regression models, saves pertinent data, and generates plots for visual analysis.
+
+To run this script, install the optional dependencies `pip install .[extras]` (or `pip install '.[extras]'` if you use zsh).
+
+## 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. For the correct citation, refer to the DOI badge above, which links to the appropriate version of the release on Zenodo. Ensure you reference the version you actually used. A formatted citation can also be obtained from the top right of the [GitHub repository](https://github.com/stabilo).
+
+```bibtex
+@software{Fonod_Stabilo_2024,
+author = {Fonod, Robert},
+license = {MIT},
+month = jun,
+title = {{Stabilo}},
+url = {https://github.com/rfonod/stabilo},
+version = {0.1.0},
+year = {2024}
+}
+```
+
+## 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!

pyproject.toml

@@ -0,0 +1,49 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "stabilo"
+dynamic = ["version"]
+description = "Reference frame video stabilization with optional user-provided masks."
+authors = [
+    { name = "Robert Fonod", email = "[email protected]" },
+]
+readme = "README.md"
+license = { file = "LICENSE" }
+requires-python = ">=3.9"
+keywords = ["stabilo", "video-stabilization", "object-stabilization", "mask", "reference-frame", "computer-vision"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Topic :: Software Development",
+    "Topic :: Scientific/Engineering",
+]
+
+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"
+]
+
+[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/"
+issues = "https://github.com/rfonod/stabilo/issues/"
+releases = "https://github.com/rfonod/stabilo/releases"

scripts/find_thresholds/README.md

@@ -0,0 +1,32 @@
+# find_thresholds.py
+
+## Description
+The `find_thresholds.py` script is designed to derive linear regression models for the BRISK, KAZE, and AKAZE feature detectors. These models aim to establish the correspondence between the average number of detected keypoints in an image and the threshold value applied by the detectors. The script employs a diverse image dataset with optional axis-aligned bounding boxes representing regions where features should not be detected. Additionally, histogram normalization using CLAHE may influence the models, leading to the creation of separate models for all combinations of mask usage and CLAHE application. The resulting threshold models play a crucial role in configuring the Stabilo module, enabling a fair comparison with other detectors like ORB, SIFT, and RSIFT.
+
+## Usage
+```
+python find_thresholds.py --dataset-dir=<dir>
+
+Options
+--dataset-dir=<dir>: Directory containing the diverse image dataset (default: scenes/).
+```
+
+## Dataset Requirements
+
+1. **Diverse Set of Images**: The dataset should include a diverse set of images representing various scenarios.
+2. **Axis-Aligned Bounding Boxes (Optional)**: The images may come with axis-aligned bounding boxes representing regions where features should not be detected.
+
+## Script Functionality
+- **Threshold Models**: Finds linear models for BRISK, KAZE, and AKAZE detectors, considering various combinations of detectors, mask usage, and CLAHE.
+- **Data Generation**: Collects data by finding the average number of detected keypoints for different threshold values.
+- **Model Fitting**: Fits linear models to the collected data, considering a specified range of keypoints.
+- **Data Filtering**: Filters the collected data to fit the model only within a specified range of keypoints.
+- **Data and Model Storage**: Saves raw and filtered data, as well as the linear models for further analysis.
+- **Plotting**: Generates and saves plots illustrating the relationship between average keypoints and thresholds.
+
+## Important Notes
+- The dataset should be carefully crafted to ensure a representative set of images with diverse content and scenarios.
+- Axis-aligned bounding boxes can be provided to guide the feature detection process and create more meaningful threshold models.
+- The generated models will be stored in the `models` directory, while the data and plots will be saved in the `results` and `plots` directories, respectively.
+
+Feel free to adapt the script and instructions based on your specific dataset and requirements.