stabilo 1.0.0__py3-none-any.whl

stabilo/__init__.py

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

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]

stabilo/stabilo.py

@@ -0,0 +1,595 @@
+# -*- coding: utf-8 -*-
+# Author: Robert Fonod (robert.fonod@ieee.org)
+
+"""
+stabilo.py - Reference frame video stabilization with optional user-provided exclusion masks
+
+This module provides the Stabilizer class for video or track stabilization using feature matching
+and transformation estimation. It leverages OpenCV for core functionalities.
+
+The class supports various feature detectors, matchers, filtering methods, and transformation types.
+Fine-tuning these parameters allows customization for specific video stabilization needs.
+
+The parameters for the feature detectors, matchers, filtering methods, and transformations can be
+fine-tuned to suit specific requirements, see https://github.com/rfonod/stabilo-optimize.
+
+Key Features:
+  - Video or bounding box (tracks) stabilization with respect to a reference frame.
+  - Fine-tunable parameters for feature detectors, matchers, filtering methods, and transformations.
+  - Support for various feature detectors (e.g., ORB, SIFT) and matchers (e.g., BF, FLANN).
+  - Projective or affine transformations for frame stabilization.
+  - RANSAC-based algorithms for robust transformation matrix estimation.
+  - CLAHE and pre-processing options for contrast enhancement.
+  - Visualization and debugging features for keypoints, descriptors, and masks.
+  - GPU acceleration for improved performance (not implemented yet).
+
+Usage:
+1. Create an instance of the 'Stabilizer' class with desired parameter configurations.
+2. Set a reference frame using the 'set_ref_frame' method.
+3. Stabilize any preceding or subsequent frames using the 'stabilize' method.
+4. Access stabilized frames, bounding boxes, and transformation matrices using specific methods.
+"""
+
+import sys
+from pathlib import Path
+from typing import Union
+
+import cv2
+import numpy as np
+
+from .utils import four2xywh, load_config, setup_logger, timer, xywh2four
+
+# Configure logging
+logger = setup_logger(__name__)
+
+# Define the root directory
+ROOT = Path(__file__).resolve().parents[0]
+
+# Read the default parameters from a configuration file
+cfg = load_config(ROOT / "cfg" / "default.yaml", logger)
+
+# Profiling flag
+PROFILING = False
+
+
+class Stabilizer:
+    """
+    This class implements a video stabilizer. It uses feature matching to find the transformation
+    between the reference frame and the current frame, allowing stabilization of subsequent frames.
+    The transformation matrix can be used to transform the current frame to the reference frame or
+    to transform points from the current frame to the reference frame.
+    """
+
+    VALID_DETECTORS = ['orb', 'sift', 'rsift', 'brisk', 'kaze', 'akaze']
+    VALID_MATCHERS = ['bf', 'flann']
+    VALID_FILTER_TYPES = ['none', 'ratio', 'distance']
+    VALID_TRANSFORMATION_TYPES = ['projective', 'affine']
+    VALID_RANSAC_METHODS_DICT = {
+        'cv2.LMEDS': cv2.LMEDS,                  # 4 - LMEDS
+        'cv2.RANSAC': cv2.RANSAC,                # 8 - RANSAC
+        'cv2.RHO': cv2.RHO,                      # 16 - RHO
+        'cv2.USAC_DEFAULT': cv2.USAC_DEFAULT,    # 32 - DEGENSAC
+        'cv2.USAC_PARALLEL': cv2.USAC_PARALLEL,  # 33 - DEGENSAC (with different parameters)
+        'cv2.USAC_FAST': cv2.USAC_FAST,          # 35 - LO-RANSAC
+        'cv2.USAC_ACCURATE': cv2.USAC_ACCURATE,  # 36 - GC-RANSAC
+        'cv2.USAC_PROSAC': cv2.USAC_PROSAC,      # 37 - PROSAC
+        'cv2.USAC_MAGSAC': cv2.USAC_MAGSAC       # 38 - MAGSAC++
+    }
+
+    def __init__(self, **kwargs):
+        """
+        Initialize the Stabilizer with user-provided or default configurations.
+
+        Arguments:
+        - detector_name: str - feature detector to use (orb, sift, rsift, brisk, kaze, akaze)
+        - matcher_name: str - feature matcher to use (bf, flann)
+        - filter_type: str - filter type for the feature matcher (none, ratio, distance)
+        - transformation_type: str - transformation for stabilization (projective, affine)
+        - clahe: bool - use CLAHE for contrast enhancement
+        - downsample_ratio: float - down-sampling ratio for the frames (e.g., 0.5 for half the size)
+        - max_features: int - max number of features to detect (for BRISK, KAZE, and AKAZE this is an approximation)
+        - ref_multiplier: float - multiplier for max features in reference frame (ref_multiplier x max_features)
+        - mask_use: bool - use mask for feature detection
+        - filter_ratio: float - filtering ratio; Lowe's ratio for 'ratio' filter, distance threshold ratio for 'distance' filter
+        - ransac_method: int - method for RANSAC algorithm (see above for options)
+        - ransac_epipolar_threshold: float - threshold for RANSAC (e.g., 1.0)
+        - ransac_max_iter: int - max iterations for RANSAC (e.g., 2000)
+        - ransac_confidence: float - confidence for RANSAC (e.g., 0.999)
+        - brisk_threshold: int - threshold for BRISK detector (used only if 'max_features -> threshold' model is unavailable)
+        - kaze_threshold: float - threshold for KAZE detector (used only if 'max_features -> threshold' model is unavailable)
+        - akaze_threshold: float - threshold for AKAZE detector (used only if 'max_features -> threshold' model is unavailable)
+        - gpu: bool - use GPU acceleration (not fully implemented/tested yet)
+        - viz: bool - save some features for visualization (e.g., keypoints, descriptors, masks)
+        - benchmark: bool - different behavior for benchmarking purposes (e.g., re-use the last transformation if the current is None)
+        - min_good_match_count_warning: int - min number of good matches to trigger a warning
+        - min_inliers_match_count_warning: int - min number of inliers to trigger a warning
+        """
+        self._load_configuration(kwargs)
+        self._validate_arguments()
+        self._initialize_variables()
+        self._create_feature_detectors()
+        self._create_matcher()
+        self._create_transformer()
+        self._create_helpers()
+
+    def _load_configuration(self, kwargs):
+        """
+        Load configuration parameters, using defaults if not provided.
+        """
+        for key, value in cfg.items():
+            setattr(self, key, kwargs.get(key, value))
+
+    def _initialize_variables(self):
+        """
+        Initialize internal variables for the Stabilizer.
+        """
+        self.ref_frame, self.cur_frame = None, None
+        self.ref_frame_gray, self.cur_frame_gray = None, None
+        self.ref_boxes, self.cur_boxes = None, None
+        self.ref_mask, self.cur_mask = None, None
+        self.ref_kpts, self.cur_kpts = None, None
+        self.ref_desc, self.cur_desc = None, None
+        self.ref_pts, self.cur_pts = None, None
+        self.cur_trans_matrix, self.trans_matrix_last_known = None, None
+        self.cur_inliers, self.cur_inliers_count = None, None
+        self.h, self.w = None, None
+
+    def _create_feature_detectors(self):
+        """
+        Create feature detectors and descriptor extractors based on the provided configurations.
+        """
+        self.detector_cur, self.detector_ref = self._create_detector(self.detector_name)
+        self.norm_type = self._get_norm_type()
+
+    def _create_detector(self, detector_name: str):
+        """
+        Create a feature detector based on the provided detector name.
+        """
+        if detector_name == "orb":
+            return self._create_orb_detectors()
+        elif detector_name in ["sift", "rsift"]:
+            return self._create_sift_detectors()
+        elif detector_name == "brisk":
+            return self._create_brisk_detectors()
+        elif detector_name == "kaze":
+            return self._create_kaze_detectors()
+        elif detector_name == "akaze":
+            return self._create_akaze_detectors()
+
+    def _create_orb_detectors(self):
+        """
+        Create ORB detectors and descriptor extractors.
+        """
+        return (
+            cv2.cuda.ORB_create(self.max_features) if self.gpu else cv2.ORB_create(self.max_features),
+            cv2.cuda.ORB_create(round(self.ref_multiplier * self.max_features)) if self.gpu else cv2.ORB_create(round(self.ref_multiplier * self.max_features))
+        )
+
+    def _create_sift_detectors(self):
+        """
+        Create SIFT detectors and descriptor extractors.
+        """
+        return (
+            cv2.cuda.SIFT_create(self.max_features) if self.gpu else cv2.SIFT_create(self.max_features), # (enable_precise_upscale=True)
+            cv2.cuda.SIFT_create(round(self.ref_multiplier * self.max_features)) if self.gpu else cv2.SIFT_create(round(self.ref_multiplier * self.max_features))
+        )
+
+    def _create_brisk_detectors(self):
+        """
+        Create BRISK detectors and descriptor extractors.
+        """
+        threshold_cur, threshold_ref = self._get_thresholds()
+        return (
+            cv2.cuda.BRISK.create(thresh=round(threshold_cur)) if self.gpu else cv2.BRISK_create(thresh=round(threshold_cur)),
+            cv2.cuda.BRISK.create(thresh=round(threshold_ref)) if self.gpu else cv2.BRISK_create(thresh=round(threshold_ref))
+        )
+
+    def _create_kaze_detectors(self):
+        """
+        Create KAZE detectors and descriptor extractors.
+        """
+        threshold_cur, threshold_ref = self._get_thresholds()
+        return (
+            cv2.cuda.KAZE_create(threshold=threshold_cur) if self.gpu else cv2.KAZE_create(threshold=threshold_cur),
+            cv2.cuda.KAZE_create(threshold=threshold_ref) if self.gpu else cv2.KAZE_create(threshold=threshold_ref)
+        )
+
+    def _create_akaze_detectors(self):
+        """
+        Create AKAZE detectors and descriptor extractors.
+        """
+        threshold_cur, threshold_ref = self._get_thresholds()
+        return (
+            cv2.cuda.AKAZE_create(threshold=threshold_cur) if self.gpu else cv2.AKAZE_create(threshold=threshold_cur),
+            cv2.cuda.AKAZE_create(threshold=threshold_ref) if self.gpu else cv2.AKAZE_create(threshold=threshold_ref)
+        )
+
+    def _get_thresholds(self):
+        """
+        Get thresholds for BRISK, KAZE, and AKAZE based on precomputed models.
+        """
+        detector_name = self.detector_name.upper()
+        threshold_model_filepath = ROOT / 'thresholds' / 'models' / f'{detector_name}' / f'model_mask_{self.mask_use}_clahe_{self.clahe}.txt'
+        if threshold_model_filepath.exists():
+            model = np.loadtxt(str(threshold_model_filepath))
+            threshold_cur = model[1] + model[0] * self.max_features
+            threshold_ref = model[1] + model[0] * self.max_features * self.ref_multiplier
+            if not self.benchmark:
+                logger.info(f"Using {detector_name} with threshold {threshold_ref} for the reference frame and {threshold_cur} for the current frame.")
+        else:
+            threshold_cur = self.brisk_threshold if detector_name == 'BRISK' else self.kaze_threshold if detector_name == 'KAZE' else self.akaze_threshold
+            threshold_ref = threshold_cur
+            if not self.benchmark:
+                logger.warning(f"No threshold analysis for {detector_name}. Using default threshold.")
+        return threshold_cur, threshold_ref
+
+    def _get_norm_type(self):
+        """
+        Get the norm type based on the detector name.
+        """
+        if self.detector_name in ["orb", "brisk", "akaze"]:
+            return cv2.NORM_HAMMING # N.B.: if ORB is using WTA_K == 3 or 4, cv.NORM_HAMMING2 should be used
+        elif self.detector_name in ["sift", "rsift", "kaze"]:
+            return cv2.NORM_L2
+
+    def _create_matcher(self):
+        """
+        Create the feature matcher based on the provided configurations.
+        """
+        if self.matcher_name == "bf":
+            self.matcher = self._create_brute_force_matcher()
+        elif self.matcher_name == "flann":
+            self.matcher = self._create_flann_matcher()
+
+    def _create_brute_force_matcher(self):
+        """
+        Create a brute-force matcher.
+        """
+        return cv2.cuda.DescriptorMatcher_createBFMatcher(self.norm_type, crossCheck=(True,False)[self.filter_type=='ratio']) if self.gpu else cv2.BFMatcher(self.norm_type, crossCheck=(True,False)[self.filter_type=='ratio'])
+
+    def _create_flann_matcher(self):
+        """
+        Create a FLANN-based matcher.
+        """
+        if self.norm_type in [cv2.NORM_HAMMING, cv2.NORM_HAMMING2]:
+            index_params = dict(algorithm=6, table_number=6, key_size=12, multi_probe_level=1)
+        elif self.norm_type == cv2.NORM_L2:
+            index_params = dict(algorithm=0, trees=5)
+        search_params = dict(checks=100)
+        return cv2.cuda.DescriptorMatcher_createFlannBasedMatcher(index_params, search_params) if self.gpu else cv2.FlannBasedMatcher(index_params, search_params)
+
+    def _create_transformer(self):
+        """
+        Create the transformation matrix estimator based on the provided configurations.
+        """
+        if self.transformation_type == 'projective':
+            self.transformer = cv2.findHomography
+        elif self.transformation_type == 'affine':
+            self.transformer = cv2.estimateAffinePartial2D
+
+    def _create_helpers(self):
+        """
+        Create helper objects for grayscale conversion, CLAHE, and resizing.
+        """
+        self.grayscale_converter = cv2.cuda.cvtColor if self.gpu else cv2.cvtColor
+        self.claher = cv2.cuda.createCLAHE(clipLimit=1.0, tileGridSize=(8, 8)) if self.gpu else cv2.createCLAHE(clipLimit=1.0, tileGridSize=(8, 8))
+        self.resizer = cv2.cuda.resize if self.gpu else cv2.resize
+
+    @timer(PROFILING)
+    def set_ref_frame(self, frame: np.ndarray, boxes: np.ndarray = None, box_format: str = 'xywh') -> None:
+        """
+        Set the reference frame and object bounding boxes.
+        Calculate keypoints and descriptors for the reference frame.
+        """
+        self.process_frame(frame, boxes, box_format, is_reference=True)
+
+    @timer(PROFILING)
+    def stabilize(self, frame: np.ndarray, boxes: np.ndarray = None, box_format: str = 'xywh') -> None:
+        """
+        This method takes an un-stabilized video frame and
+        calculates a transformation matrix that can transform
+        this frame or boxes to the reference frame coordinates.
+        """
+        success = self.process_frame(frame, boxes, box_format, is_reference=False)
+        if success:
+            matches = self.get_matches(self.ref_desc, self.cur_desc)
+            if matches and self.ref_kpts is not None and self.cur_kpts is not None:
+                self.ref_pts = np.float32([self.ref_kpts[m.queryIdx].pt for m in matches]).reshape(-1, 2)
+                self.cur_pts = np.float32([self.cur_kpts[m.trainIdx].pt for m in matches]).reshape(-1, 2)
+            else:
+                self.ref_pts = []
+                self.cur_pts = []
+            self.calculate_transformation_matrix()
+
+    def process_frame(self, frame: np.ndarray, boxes: np.ndarray = None, box_format: str = 'xywh', is_reference: bool = False) -> bool:
+        """
+        Process the given frame and bounding boxes.
+        """
+        if frame is None:
+            logger.error(f'{"Reference" if is_reference else "Current"} frame is invalid.')
+            sys.exit(1)
+
+        if self.mask_use:
+            if boxes is None:
+                logger.warning(f'Mask is set to be used, but no bounding boxes were provided for the {"reference" if is_reference else "current"} frame.')
+        else:
+            boxes = None # if mask is not to be used, ignore the bounding boxes even if provided
+
+        if is_reference:
+            self.h, self.w = frame.shape[:2]
+            self.ref_frame, self.ref_boxes, self.ref_box_format = frame, boxes, box_format
+        else:
+            self.cur_frame, self.cur_boxes, self.cur_box_format = frame, boxes, box_format
+
+        mask = None if boxes is None else self.create_binary_mask(boxes, box_format)
+        kpts, desc, frame_gray = self.get_features_and_descriptors(frame, mask, is_reference)
+
+        if is_reference:
+            self.ref_kpts, self.ref_desc, self.ref_frame_gray = kpts, desc, frame_gray
+        else:
+            self.cur_kpts, self.cur_desc, self.cur_frame_gray = kpts, desc, frame_gray
+
+        if self.viz:
+            if is_reference:
+                self.ref_mask = mask
+                self.ref_pts = np.array([ref_kpt.pt for ref_kpt in self.ref_kpts], dtype=np.float32).reshape(-1, 2) if self.ref_kpts is not None else []
+            else:
+                self.cur_mask = mask
+
+        return True
+
+    @timer(PROFILING)
+    def get_features_and_descriptors(self, frame: np.ndarray, mask: np.ndarray = None, ref_frame: bool = False) -> tuple:
+        """
+        Get the features and descriptors for the given frame.
+        """
+        if frame is None:
+            return None, None, None
+
+        if self.gpu:
+            frame = cv2.cuda_GpuMat(frame)
+            mask = cv2.cuda_GpuMat(mask) if mask is not None else None
+
+        frame = self.grayscale_converter(frame, cv2.COLOR_BGR2GRAY)
+        if self.clahe:
+            frame = self.claher.apply(frame)
+
+        frame_gray = frame if self.viz else None
+
+        if self.downsample_ratio != 1.0:
+            frame = self.resizer(frame, (0, 0), fx=self.downsample_ratio, fy=self.downsample_ratio)
+            mask = self.resizer(mask, (0, 0), fx=self.downsample_ratio, fy=self.downsample_ratio) if mask is not None else None
+
+        try:
+            kpts, desc = (self.detector_ref if ref_frame else self.detector_cur).detectAndCompute(frame, mask)
+        except cv2.error as e:
+            logger.warning(f"Features and descriptors couldn't be found. \n Error: {e}")
+            return None, None, None
+
+        if self.detector_name == 'rsift':
+            desc /= (desc.sum(axis=1, keepdims=True) + 1e-8)
+            desc = np.sqrt(desc)
+
+        if self.downsample_ratio != 1.0:
+            for kpt in kpts:
+                kpt.pt = (kpt.pt[0] / self.downsample_ratio, kpt.pt[1] / self.downsample_ratio)
+
+        if self.gpu:
+            kpts = self.detector_cur.convert(kpts)
+            desc = self.detector_cur.convert(desc)
+            frame_gray = frame.download(frame_gray)
+
+        return kpts, desc, frame_gray
+
+    @timer(PROFILING)
+    def get_matches(self, desc1: np.ndarray, desc2: np.ndarray) -> list:
+        """
+        Match the given descriptors.
+        """
+        if desc1 is None or desc2 is None:
+            logger.warning("One of the descriptors is invalid.")
+            return []
+
+        try:
+            if self.filter_type == 'none':
+                good_matches = self.matcher.match(desc1, desc2, None)
+            elif self.filter_type == 'distance':
+                matches = self.matcher.match(desc1, desc2, None)
+                matches = sorted(matches, key=lambda x: x.distance)
+                min_dist, max_dist = matches[0].distance, matches[-1].distance
+                good_thresh = min_dist + (max_dist - min_dist) * self.filter_ratio
+                good_matches = [m for m in matches if m.distance <= good_thresh]
+            elif self.filter_type == 'ratio':
+                matches = self.matcher.knnMatch(desc1, desc2, k=2)
+                good_matches = []
+                for pair in matches:
+                    if len(pair) == 2:
+                        m, n = pair
+                        if m.distance < self.filter_ratio*n.distance:
+                            good_matches.append(m)
+        except cv2.error as e:
+            logger.error(f"Matches couldn't be found. \n Error: {e}")
+            return []
+
+        if len(good_matches) <= self.min_good_match_count_warning:
+            logger.warning(f'Only {len(good_matches)} good matches were found.')
+
+        return list(good_matches)
+
+    @timer(PROFILING)
+    def calculate_transformation_matrix(self) -> None:
+        """
+        Estimate the transformation matrix using the current and reference points.
+        """
+        if self.ref_pts is not None and self.cur_pts is not None and len(self.ref_pts) >= 4 and len(self.cur_pts) >= 4:
+            try:
+                self.cur_trans_matrix, inliers = self.transformer(self.cur_pts, self.ref_pts, maxIters=self.ransac_max_iter,
+                method=self.ransac_method, confidence=self.ransac_confidence, ransacReprojThreshold=self.ransac_epipolar_threshold)
+            except cv2.error as e:
+                logger.exception(f"Transformation matrix couldn't be calculated.\n Error: {e}")
+                self.cur_trans_matrix = np.eye(3) if self.benchmark else self.trans_matrix_last_known
+                inliers = np.full((len(self.cur_pts), 1), False, dtype=bool)
+                inliers_count = 'N/A'
+                if not self.benchmark:
+                    logger.warning("Re-using the last known transformation matrix.")
+            else:
+                if self.cur_trans_matrix is not None:
+                    self.trans_matrix_last_known = self.cur_trans_matrix
+                    inliers_count = sum(inliers.ravel().tolist())
+                    if inliers_count <= self.min_inliers_match_count_warning:
+                        logger.warning(f'Only {inliers_count} inliers points were used to estimate the transformation matrix.')
+                else:
+                    logger.warning('Transformation matrix is None.')
+                    self.cur_trans_matrix = np.eye(3) if self.benchmark else self.trans_matrix_last_known
+                    inliers = np.full((len(self.cur_pts), 1), False, dtype=bool)
+                    inliers_count = 'N/A'
+                    if not self.benchmark:
+                        logger.warning("Re-using the last known transformation matrix.")
+        else:
+            logger.warning('Not enough points to estimate the transformation matrix.')
+            self.cur_trans_matrix = np.eye(3) if self.benchmark else self.trans_matrix_last_known
+            if not self.benchmark:
+                logger.warning("Re-using the last known transformation matrix.")
+            inliers = np.full((len(self.cur_pts), 1), False, dtype=bool)
+            inliers_count = 'N/A'
+
+        if self.viz:
+            self.cur_inliers = inliers
+            self.cur_inliers_count = inliers_count
+
+    @timer(PROFILING)
+    def create_binary_mask(self, boxes: np.ndarray, box_format: str) -> np.ndarray:
+        """
+        Create a mask from the given bounding boxes.
+        """
+        if self.h is None or self.w is None:
+            logger.error("Reference frame is not set.")
+            sys.exit(1)
+
+        if box_format == 'four':
+            boxes = four2xywh(boxes)
+
+        mask = np.full((self.h, self.w), 255, dtype=np.uint8)
+        for box in boxes:
+            xc, yc, wb, hb = box
+            wb += wb * self.mask_margin_ratio
+            hb += hb * self.mask_margin_ratio
+            x1, y1, x2, y2 = int(xc - wb / 2), int(yc - hb / 2), int(xc + wb / 2), int(yc + hb / 2)
+            mask[max(0, y1):min(self.h, y2), max(0, x1):min(self.w, x2)] = 0
+
+        return mask
+
+    @timer(PROFILING)
+    def warp_cur_frame(self) -> Union[np.ndarray, None]:
+        """
+        Warp the current frame to the reference frame using the current transformation matrix.
+        """
+        return self.warp_frame(self.cur_frame)
+
+    def warp_frame(self, frame: np.ndarray) -> Union[np.ndarray, None]:
+        """
+        Warp the given frame to the reference frame using the current transformation matrix.
+        """
+        if frame is None:
+            return None
+        if self.w is None or self.h is None:
+            logger.error("Reference frame is not set.")
+            sys.exit(1)
+        if self.cur_trans_matrix is None:
+            logger.warning("Transformation matrix is None.")
+            return frame
+        if self.transformation_type == 'projective':
+            return cv2.warpPerspective(frame, self.cur_trans_matrix, (self.w, self.h))
+        elif self.transformation_type == 'affine':
+            return cv2.warpAffine(frame, self.cur_trans_matrix, (self.w, self.h))
+
+    def transform_cur_boxes(self, out_box_format: str = 'xywh') -> Union[np.ndarray, None]:
+        """
+        Warp the current bounding boxes to the reference frame using the current transformation matrix.
+        """
+        return self.transform_boxes(self.cur_boxes, self.cur_trans_matrix, self.cur_box_format, out_box_format)
+
+    def transform_boxes(self, boxes: np.ndarray, trans_matrix: np.ndarray, in_box_format: str = 'xywh', out_box_format: str = 'xywh') -> Union[np.ndarray, None]:
+        """
+        Transform the provided bounding boxes using the provided transformation matrix.
+        """
+        if boxes is None:
+            return None
+        if trans_matrix is None:
+            return boxes
+
+        if in_box_format == 'xywh':
+            boxes = xywh2four(boxes)
+
+        boxes = np.array([boxes]).reshape(-1, 1, 2)
+        if self.transformation_type == 'projective':
+            boxes = cv2.perspectiveTransform(boxes, trans_matrix)
+        elif self.transformation_type == 'affine':
+            boxes = cv2.transform(boxes, trans_matrix)
+
+        if out_box_format == 'xywh':
+            return four2xywh(boxes.reshape(-1, 8))
+        elif out_box_format == 'four':
+            return boxes.reshape(-1, 8)
+
+    def get_cur_frame(self) -> Union[np.ndarray, None]:
+        """
+        Get the current frame.
+        """
+        return self.cur_frame
+
+    def get_cur_boxes(self) -> Union[np.ndarray, None]:
+        """
+        Get the current bounding boxes.
+        """
+        return self.cur_boxes
+
+    def get_cur_trans_matrix(self) -> Union[np.ndarray, None]:
+        """
+        Get the current transformation matrix.
+        """
+        return self.cur_trans_matrix
+
+    def get_basic_info(self) -> dict:
+        """
+        Get basic information about the Stabilizer.
+        """
+        return {
+            'detector_name': self.detector_name,
+            'matcher_name': self.matcher_name,
+            'filter_type': self.filter_type,
+            'transformation_type': self.transformation_type,
+            'clahe': self.clahe,
+            'mask_use': self.mask_use,
+        }
+
+    def _validate_arguments(self):
+        """
+        Validate the arguments provided during the initialization of the Stabilizer class.
+        """
+        if self.detector_name not in self.VALID_DETECTORS:
+            raise ValueError(f"Invalid detector: {self.detector_name}. Choose from {self.VALID_DETECTORS}")
+        if self.matcher_name not in self.VALID_MATCHERS:
+            raise ValueError(f"Invalid matcher: {self.matcher_name}. Choose from {self.VALID_MATCHERS}")
+        if self.filter_type not in self.VALID_FILTER_TYPES:
+            raise ValueError(f"Invalid filter type: {self.filter_type}. Choose from {self.VALID_FILTER_TYPES}")
+        if self.transformation_type not in self.VALID_TRANSFORMATION_TYPES:
+            raise ValueError(f"Invalid transformation type: {self.transformation_type}. Choose from {self.VALID_TRANSFORMATION_TYPES}")
+        if self.ransac_method not in self.VALID_RANSAC_METHODS_DICT.values():
+            raise ValueError(f"Invalid RANSAC method: {self.ransac_method}. Choose from {self.VALID_RANSAC_METHODS_DICT.keys()}")
+        if not (0.0 < self.downsample_ratio <= 1.0):
+            raise ValueError("Invalid downsample_ratio. It should be in the range (0.0, 1.0]")
+        if not (0 < self.max_features) and isinstance(self.max_features, int):
+            raise ValueError("Invalid max_features. It should be greater than 0 and an integer")
+        if not (1 <= self.ref_multiplier):
+            raise ValueError("Invalid ref_multiplier. It should be greater than or equal to 1")
+        if not (0.0 < self.filter_ratio <= 1.0):
+            raise ValueError("Invalid filter_ratio. It should be in the range (0.0, 1.0]")
+        if not (0 < self.ransac_max_iter) and isinstance(self.ransac_max_iter, int):
+            raise ValueError("Invalid ransac_max_iter. It should be greater than 0 and an integer")
+        if not (0.0 < self.ransac_epipolar_threshold):
+            raise ValueError("Invalid ransac_epipolar_threshold. It should be greater than 0")
+        if not (0.0 < self.ransac_confidence <= 1.0):
+            raise ValueError("Invalid ransac_confidence. It should be in the range (0.0, 1.0]")
+        if self.gpu and not cv2.cuda.getCudaEnabledDeviceCount():
+            raise ValueError("GPU is enabled but no CUDA-enabled device was found")

stabilo/thresholds/models/AKAZE/model_mask_False_clahe_False.txt

@@ -0,0 +1,2 @@
+-1.238671541205360271e-06
+1.399651010429193293e-02

stabilo/thresholds/models/AKAZE/model_mask_False_clahe_True.txt

@@ -0,0 +1,2 @@
+-1.433874243028384286e-06
+1.797921843899690300e-02

stabilo/thresholds/models/AKAZE/model_mask_True_clahe_False.txt

@@ -0,0 +1,2 @@
+-1.007223706389076417e-06
+1.163307906351335880e-02

stabilo/thresholds/models/AKAZE/model_mask_True_clahe_True.txt

@@ -0,0 +1,2 @@
+-1.420484216983836093e-06
+1.574875889009140148e-02

stabilo/thresholds/models/BRISK/model_mask_False_clahe_False.txt

@@ -0,0 +1,2 @@
+-5.697760528375401222e-03
+1.362927870041904157e+02

stabilo/thresholds/models/BRISK/model_mask_False_clahe_True.txt

@@ -0,0 +1,2 @@
+-6.082518482010841263e-03
+1.538229586731700920e+02

stabilo/thresholds/models/BRISK/model_mask_True_clahe_False.txt

@@ -0,0 +1,2 @@
+-5.026162052230478440e-03
+1.261693929838898498e+02

stabilo/thresholds/models/BRISK/model_mask_True_clahe_True.txt

@@ -0,0 +1,2 @@
+-5.684927998372675539e-03
+1.451210374444453635e+02

stabilo/thresholds/models/KAZE/model_mask_False_clahe_False.txt

@@ -0,0 +1,2 @@
+-1.342082518515861633e-06
+1.445548677509021600e-02

stabilo/thresholds/models/KAZE/model_mask_False_clahe_True.txt

@@ -0,0 +1,2 @@
+-1.471458874258221078e-06
+1.783699945834927095e-02

stabilo/thresholds/models/KAZE/model_mask_True_clahe_False.txt

@@ -0,0 +1,2 @@
+-9.680610223378339583e-07
+1.147348454716152349e-02

stabilo/thresholds/models/KAZE/model_mask_True_clahe_True.txt

@@ -0,0 +1,2 @@
+-1.350186975845170620e-06
+1.509247010983386615e-02

stabilo/utils.py

@@ -0,0 +1,112 @@
+# -*- coding: utf-8 -*-
+# Author: Robert Fonod (robert.fonod@ieee.org)
+
+import logging
+import sys
+import time
+
+import cv2
+import numpy as np
+import yaml
+
+
+def setup_logger(name: str, log_file: str = None, level: int = logging.INFO) -> logging.Logger:
+    """
+    Setup the logger
+    """
+    formatter = logging.Formatter('%(asctime)s - %(name)s - %(levelname)s - %(message)s')
+    logger = logging.getLogger(name)
+    logger.setLevel(level)
+
+    if log_file:
+        file_handler = logging.FileHandler(log_file)
+        file_handler.setFormatter(formatter)
+        logger.addHandler(file_handler)
+
+    console_handler = logging.StreamHandler()
+    console_handler.setFormatter(formatter)
+    logger.addHandler(console_handler)
+
+    return logger
+
+def timer(profiling: bool = False):
+    """
+    Decorator function to measure the execution time of a function.
+    """
+    def decorator(func):
+        def wrapper(*args, **kwargs):
+            if not profiling:
+                return func(*args, **kwargs)
+            start_time = time.time()
+            result = func(*args, **kwargs)
+            print(f"{func.__name__:<35} execution time: {1000*(time.time() - start_time):>10.2f} ms")
+            return result
+        return wrapper
+    return decorator
+
+def load_config(cfg_filepath: str, logger: logging.Logger = None) -> dict:
+    """
+    Load the configuration file
+    """
+    try:
+        with open(cfg_filepath, 'r') as f:
+            config = yaml.safe_load(f)
+    except FileNotFoundError:
+        if logger is not None:
+            logger.error(f"Configuration file {cfg_filepath} not found.")
+        sys.exit(1)
+    return config
+
+def xywh2four(boxes: np.ndarray) -> np.ndarray:
+    """
+    Convert bounding boxes from [xc, yc, w, h] to four point format [x1, y1, x2, y2, x3, y3, x4, y4].
+    """
+    x_c, y_c, w, h = boxes.T
+
+    x1 = x_c - 0.5 * w
+    y1 = y_c - 0.5 * h
+    x2 = x_c + 0.5 * w
+    y2 = y_c - 0.5 * h
+    x3 = x_c + 0.5 * w
+    y3 = y_c + 0.5 * h
+    x4 = x_c - 0.5 * w
+    y4 = y_c + 0.5 * h
+
+    return np.column_stack((x1, y1, x2, y2, x3, y3, x4, y4))
+
+def four2xywh(boxes: np.ndarray) -> np.ndarray:
+    """
+    Convert bounding boxes from any four-point format [x1, y1, x2, y2, x3, y3, x4, y4]
+    to YOLO format [xc, yc, w, h], robust to any point order and rotation.
+    """
+    points = boxes.reshape(-1, 4, 2)
+
+    x_min = np.min(points[:, :, 0], axis=1)
+    x_max = np.max(points[:, :, 0], axis=1)
+    y_min = np.min(points[:, :, 1], axis=1)
+    y_max = np.max(points[:, :, 1], axis=1)
+
+    x_c = (x_min + x_max) / 2
+    y_c = (y_min + y_max) / 2
+
+    w = x_max - x_min
+    h = y_max - y_min
+
+    return np.column_stack((x_c, y_c, w, h))
+
+def detect_delimiter(filepath: str, lines_to_check: int = 5) -> str:
+    """
+    Detect the delimiter of a CSV file by reading a few lines
+    """
+    delimiters = {',': 0, ' ': 0, '\t': 0}
+    with open(filepath, 'r') as file:
+        for _ in range(lines_to_check):
+            line = file.readline()
+            if not line:
+                break
+            delimiters[','] += line.count(',')
+            delimiters[' '] += line.count(' ')
+            delimiters['\t'] += line.count('\t')
+
+    return max(delimiters, key=delimiters.get)
+

stabilo-1.0.0.dist-info/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.dist-info/METADATA

@@ -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: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: matplotlib>=3.5.0; extra == "dev"
+Provides-Extra: extras
+Requires-Dist: matplotlib>=3.5.0; extra == "extras"
+
+# 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.dist-info/RECORD

@@ -0,0 +1,21 @@
+stabilo/__init__.py,sha256=QwOwL8BYKjKTEPpYw0V2qed_tl-zrk6_5QjZScLVJaU,95
+stabilo/stabilo.py,sha256=1GDR0f4Eg1V5r52pnnkX6VBgHBB7zZDscqL65Egs70s,28322
+stabilo/utils.py,sha256=D2QAQJXAMsYUhPhJW_6FLQKlMIh7I_2WRsripkPmR1I,3225
+stabilo/cfg/default.yaml,sha256=kwMfJlbG7NOa8VzLVnqDI7I-_ARpI8-urjrSoWCANtY,2957
+stabilo/thresholds/models/AKAZE/model_mask_False_clahe_False.txt,sha256=iE4OMFGbQYtwh8I26gfg5WaH_7MovCoFMXJ9Jdlz21o,51
+stabilo/thresholds/models/AKAZE/model_mask_False_clahe_True.txt,sha256=nrfKupwWyJZ9kd9A9qBXYBT6zCTSuCdxubypnn4YJuY,51
+stabilo/thresholds/models/AKAZE/model_mask_True_clahe_False.txt,sha256=UBHbWksqT0eiU8DBueBzC2-SPXIA6LFK3m2ZVo1KgJk,51
+stabilo/thresholds/models/AKAZE/model_mask_True_clahe_True.txt,sha256=gfHWItznmy-BeW2Sq4_NwdVSeKX2DOipv9jnacHLoUQ,51
+stabilo/thresholds/models/BRISK/model_mask_False_clahe_False.txt,sha256=eVkEknyAsg5rl1ixjc8Rldy-iypwGrOfG-Uz_jtFqNQ,51
+stabilo/thresholds/models/BRISK/model_mask_False_clahe_True.txt,sha256=Ng3wCMuu8dqkWSsdJoxXUxYREB61_AqSMwmUu_BN1n0,51
+stabilo/thresholds/models/BRISK/model_mask_True_clahe_False.txt,sha256=FxlSc9bS-uxs-Yccek7oV12xBD8Aj7D4Ua7UhDxARBo,51
+stabilo/thresholds/models/BRISK/model_mask_True_clahe_True.txt,sha256=tgT9tTPquwxNU4FPHYT33J8cELwvKjRHAw5-g3RJJ7c,51
+stabilo/thresholds/models/KAZE/model_mask_False_clahe_False.txt,sha256=ZgYIqNvci0jQyp_nW_BAhmDyfmc9v9hlyCOMiKu0pX8,51
+stabilo/thresholds/models/KAZE/model_mask_False_clahe_True.txt,sha256=BKIT1m2Vh9tXEIYi0e1tULqWKxgO9q0iRAnFmfZ5ufw,51
+stabilo/thresholds/models/KAZE/model_mask_True_clahe_False.txt,sha256=2lxN-bDBMbPl7u-IifBp7KU0tzi_DldagVxk9cdG4AI,51
+stabilo/thresholds/models/KAZE/model_mask_True_clahe_True.txt,sha256=-XZnLgHImN70jNCYAVE-ZrSrw6UJhFP9IwaNxBy31gA,51
+stabilo-1.0.0.dist-info/LICENSE,sha256=3dtRxi571l0chCMw2dqHmD2y1teMiqT1wkqs74lotFA,1068
+stabilo-1.0.0.dist-info/METADATA,sha256=bZ5Wh_JCoXgJpiriOvw2pgZhBmaZTJ0CTLRINg07HAI,11306
+stabilo-1.0.0.dist-info/WHEEL,sha256=R06PA3UVYHThwHvxuRWMqaGcr-PuniXahwjmQRFMEkY,91
+stabilo-1.0.0.dist-info/top_level.txt,sha256=86H6WrIsGB1DZALM4Ih3wlx3yTw1w19ZOmrlSxe1dEU,8
+stabilo-1.0.0.dist-info/RECORD,,

stabilo-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (75.5.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

stabilo-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+stabilo