|
| 1 | +# Stabilo |
| 2 | + |
| 3 | + [](https://opensource.org/licenses/MIT)  |
| 4 | + |
| 5 | +🚧 **Development Notice** 🚧 |
| 6 | + |
| 7 | +> ⚠️ **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. |
| 8 | +
|
| 9 | +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. |
| 10 | + |
| 11 | +## Features |
| 12 | + |
| 13 | +- **Video Stabilization**: Align video frames to a selected reference using homography or affine transformations. |
| 14 | +- **Trajectory Stabilization**: Apply stabilization to object trajectories using homography or affine transformations. |
| 15 | +- **User-Defined Masks**: Allow users to specify areas to ignore during stabilization, such as bounding boxes of moving objects or regions of no interest. |
| 16 | +- **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. |
| 17 | +- **Customizable Parameters**: Fine-tune the stabilization process by adjusting parameters such as the number of keypoints, RANSAC and matching thresholds, and downsampling factors. |
| 18 | +- **Visualization Tools**: Generate visualizations of the stabilization process, including frame-by-frame comparisons. |
| 19 | +- **Threshold Analysis**: Analyze the relationship between detection thresholds and keypoint counts for BRISK, KAZE, and AKAZE feature detectors. |
| 20 | + |
| 21 | +<details> |
| 22 | +<summary><b>🚀 Planned Enhancements</b></summary> |
| 23 | + |
| 24 | +- **Benchmarking and Tuning Tools**: Develop tools to benchmark and tune the performance of the stabilization algorithms. |
| 25 | +- **Trajectory Stabilization Script**: Create a script to stabilize object trajectories in videos. |
| 26 | +- **Custom Mask Encoding**: Support for more generic types of custom mask encodings. |
| 27 | +- **Custom Reference Frame Selection**: Allow users to select a custom reference frame for stabilization. |
| 28 | +- **GPU Acceleration**: Utilize GPU acceleration for faster processing. |
| 29 | +- **Documentation**: Provide detailed documentation and examples for ease of use. |
| 30 | +- **Unit Tests**: Implement comprehensive unit tests to ensure the stability and reliability of the package. |
| 31 | +- **Deployment to PyPI**: Publish the package on PyPI for easy installation and distribution. |
| 32 | + |
| 33 | +</details> |
| 34 | + |
| 35 | +## Installation |
| 36 | + |
| 37 | +First, create a **Python Virtual Environment** (Python >= 3.9) using e.g., [Miniconda3](https://docs.anaconda.com/free/miniconda/): |
| 38 | +```bash |
| 39 | +conda create -n stabilo python=3.9 -y |
| 40 | +conda activate stabilo |
| 41 | +``` |
| 42 | + |
| 43 | +Then, install the package using one of the following methods: |
| 44 | + |
| 45 | +### Option 1: Install from PyPI |
| 46 | +You can install the package from PyPI (not available yet): |
| 47 | + |
| 48 | +<strike> |
| 49 | + |
| 50 | +```sh |
| 51 | +pip install stabilo |
| 52 | +``` |
| 53 | + |
| 54 | +</strike> |
| 55 | + |
| 56 | + |
| 57 | +### Option 2: Install from Source (recommended) |
| 58 | +You can install the package directly from the repository: |
| 59 | +```sh |
| 60 | +pip install git+https://github.com/rfonod/stabilo.git |
| 61 | +``` |
| 62 | + |
| 63 | +### Option 3: Install from Local Source |
| 64 | + |
| 65 | +Clone the repository and install the package: |
| 66 | + |
| 67 | +```sh |
| 68 | +git clone https://github.com/rfonod/stabilo.git |
| 69 | +cd stabilo |
| 70 | +pip install . |
| 71 | +``` |
| 72 | + |
| 73 | +If you want the changes you make in the repo to be reflected in your install, use `pip install -e .` instead of `pip install .`. |
| 74 | + |
| 75 | +## Example Usage |
| 76 | + |
| 77 | +```python |
| 78 | +from stabilo import Stabilizer |
| 79 | + |
| 80 | +# Create an instance of the Stabilizer class with default parameters |
| 81 | +stabilizer = Stabilizer() |
| 82 | + |
| 83 | +# Set a reference frame with optional mask (e.g., bounding boxes) |
| 84 | +stabilizer.set_ref_frame(ref_frame, ref_mask) |
| 85 | + |
| 86 | +# Stabilize any consecutive frame with optional mask |
| 87 | +stabilizer.stabilize(frame, mask) |
| 88 | + |
| 89 | +# Get the stabilized (warped to the reference frame) frame |
| 90 | +stabilized_frame = stabilizer.warp_cur_frame() |
| 91 | + |
| 92 | +# Get the transformed bounding boxes (if mask was provided) |
| 93 | +stabilized_boxes = stabilizer.transform_cur_boxes() |
| 94 | +``` |
| 95 | + |
| 96 | +## Additional Scripts |
| 97 | + |
| 98 | +Utility scripts are provided to demonstrate the functionality of the Stabilo package. These scripts can be found in the `scripts` directory. |
| 99 | + |
| 100 | +#### Stabilization Examples |
| 101 | + |
| 102 | +- `stabilize_video.py`: Demonstrates video stabilization relative to a reference frame. |
| 103 | +- `stabilize_boxes.py`: Shows how to stabilize bounding boxes relative to a reference frame. |
| 104 | + |
| 105 | +#### Threshold Analysis |
| 106 | + |
| 107 | +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. |
| 108 | + |
| 109 | +To run this script, install the optional dependencies `pip install .[extras]` (or `pip install '.[extras]'` if you use zsh). |
| 110 | + |
| 111 | +## Citing This Work |
| 112 | + |
| 113 | +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). |
| 114 | + |
| 115 | +```bibtex |
| 116 | +@software{Fonod_Stabilo_2024, |
| 117 | +author = {Fonod, Robert}, |
| 118 | +license = {MIT}, |
| 119 | +month = jun, |
| 120 | +title = {{Stabilo}}, |
| 121 | +url = {https://github.com/rfonod/stabilo}, |
| 122 | +version = {0.1.0}, |
| 123 | +year = {2024} |
| 124 | +} |
| 125 | +``` |
| 126 | + |
| 127 | +## Contributing |
| 128 | + |
| 129 | +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! |
| 130 | + |
| 131 | + |
| 132 | +## License |
| 133 | + |
| 134 | +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! |
0 commit comments