dgenerate-ultralytics-headless 8.3.141__py3-none-any.whl → 8.3.144__py3-none-any.whl

ultralytics/trackers/byte_tracker.py

@@ -1,5 +1,7 @@
 # Ultralytics 🚀 AGPL-3.0 License - https://ultralytics.com/license
 
+from typing import Any, List, Optional, Tuple
+
 import numpy as np
 
 from ..utils import LOGGER
@@ -29,16 +31,17 @@ class STrack(BaseTrack):
         idx (int): Index or identifier for the object.
         frame_id (int): Current frame ID.
         start_frame (int): Frame where the object was first detected.
+        angle (float | None): Optional angle information for oriented bounding boxes.
 
     Methods:
-        predict(): Predict the next state of the object using Kalman filter.
-        multi_predict(stracks): Predict the next states for multiple tracks.
-        multi_gmc(stracks, H): Update multiple track states using a homography matrix.
-        activate(kalman_filter, frame_id): Activate a new tracklet.
-        re_activate(new_track, frame_id, new_id): Reactivate a previously lost tracklet.
-        update(new_track, frame_id): Update the state of a matched track.
-        convert_coords(tlwh): Convert bounding box to x-y-aspect-height format.
-        tlwh_to_xyah(tlwh): Convert tlwh bounding box to xyah format.
+        predict: Predict the next state of the object using Kalman filter.
+        multi_predict: Predict the next states for multiple tracks.
+        multi_gmc: Update multiple track states using a homography matrix.
+        activate: Activate a new tracklet.
+        re_activate: Reactivate a previously lost tracklet.
+        update: Update the state of a matched track.
+        convert_coords: Convert bounding box to x-y-aspect-height format.
+        tlwh_to_xyah: Convert tlwh bounding box to xyah format.
 
     Examples:
         Initialize and activate a new track
@@ -48,7 +51,7 @@ class STrack(BaseTrack):
 
     shared_kalman = KalmanFilterXYAH()
 
-    def __init__(self, xywh, score, cls):
+    def __init__(self, xywh: List[float], score: float, cls: Any):
         """
         Initialize a new STrack instance.
 
@@ -79,14 +82,14 @@ class STrack(BaseTrack):
         self.angle = xywh[4] if len(xywh) == 6 else None
 
     def predict(self):
-        """Predicts the next state (mean and covariance) of the object using the Kalman filter."""
+        """Predict the next state (mean and covariance) of the object using the Kalman filter."""
         mean_state = self.mean.copy()
         if self.state != TrackState.Tracked:
             mean_state[7] = 0
         self.mean, self.covariance = self.kalman_filter.predict(mean_state, self.covariance)
 
     @staticmethod
-    def multi_predict(stracks):
+    def multi_predict(stracks: List["STrack"]):
         """Perform multi-object predictive tracking using Kalman filter for the provided list of STrack instances."""
         if len(stracks) <= 0:
             return
@@ -101,7 +104,7 @@ class STrack(BaseTrack):
             stracks[i].covariance = cov
 
     @staticmethod
-    def multi_gmc(stracks, H=np.eye(2, 3)):
+    def multi_gmc(stracks: List["STrack"], H: np.ndarray = np.eye(2, 3)):
         """Update state tracks positions and covariances using a homography matrix for multiple tracks."""
         if len(stracks) > 0:
             multi_mean = np.asarray([st.mean.copy() for st in stracks])
@@ -119,7 +122,7 @@ class STrack(BaseTrack):
                 stracks[i].mean = mean
                 stracks[i].covariance = cov
 
-    def activate(self, kalman_filter, frame_id):
+    def activate(self, kalman_filter: KalmanFilterXYAH, frame_id: int):
         """Activate a new tracklet using the provided Kalman filter and initialize its state and covariance."""
         self.kalman_filter = kalman_filter
         self.track_id = self.next_id()
@@ -132,8 +135,8 @@ class STrack(BaseTrack):
         self.frame_id = frame_id
         self.start_frame = frame_id
 
-    def re_activate(self, new_track, frame_id, new_id=False):
-        """Reactivates a previously lost track using new detection data and updates its state and attributes."""
+    def re_activate(self, new_track: "STrack", frame_id: int, new_id: bool = False):
+        """Reactivate a previously lost track using new detection data and update its state and attributes."""
         self.mean, self.covariance = self.kalman_filter.update(
             self.mean, self.covariance, self.convert_coords(new_track.tlwh)
         )
@@ -148,7 +151,7 @@ class STrack(BaseTrack):
         self.angle = new_track.angle
         self.idx = new_track.idx
 
-    def update(self, new_track, frame_id):
+    def update(self, new_track: "STrack", frame_id: int):
         """
         Update the state of a matched track.
 
@@ -177,13 +180,13 @@ class STrack(BaseTrack):
         self.angle = new_track.angle
         self.idx = new_track.idx
 
-    def convert_coords(self, tlwh):
+    def convert_coords(self, tlwh: np.ndarray) -> np.ndarray:
         """Convert a bounding box's top-left-width-height format to its x-y-aspect-height equivalent."""
         return self.tlwh_to_xyah(tlwh)
 
     @property
-    def tlwh(self):
-        """Returns the bounding box in top-left-width-height format from the current state estimate."""
+    def tlwh(self) -> np.ndarray:
+        """Get the bounding box in top-left-width-height format from the current state estimate."""
         if self.mean is None:
             return self._tlwh.copy()
         ret = self.mean[:4].copy()
@@ -192,14 +195,14 @@ class STrack(BaseTrack):
         return ret
 
     @property
-    def xyxy(self):
-        """Converts bounding box from (top left x, top left y, width, height) to (min x, min y, max x, max y) format."""
+    def xyxy(self) -> np.ndarray:
+        """Convert bounding box from (top left x, top left y, width, height) to (min x, min y, max x, max y) format."""
         ret = self.tlwh.copy()
         ret[2:] += ret[:2]
         return ret
 
     @staticmethod
-    def tlwh_to_xyah(tlwh):
+    def tlwh_to_xyah(tlwh: np.ndarray) -> np.ndarray:
         """Convert bounding box from tlwh format to center-x-center-y-aspect-height (xyah) format."""
         ret = np.asarray(tlwh).copy()
         ret[:2] += ret[2:] / 2
@@ -207,28 +210,28 @@ class STrack(BaseTrack):
         return ret
 
     @property
-    def xywh(self):
-        """Returns the current position of the bounding box in (center x, center y, width, height) format."""
+    def xywh(self) -> np.ndarray:
+        """Get the current position of the bounding box in (center x, center y, width, height) format."""
         ret = np.asarray(self.tlwh).copy()
         ret[:2] += ret[2:] / 2
         return ret
 
     @property
-    def xywha(self):
-        """Returns position in (center x, center y, width, height, angle) format, warning if angle is missing."""
+    def xywha(self) -> np.ndarray:
+        """Get position in (center x, center y, width, height, angle) format, warning if angle is missing."""
         if self.angle is None:
             LOGGER.warning("`angle` attr not found, returning `xywh` instead.")
             return self.xywh
         return np.concatenate([self.xywh, self.angle[None]])
 
     @property
-    def result(self):
-        """Returns the current tracking results in the appropriate bounding box format."""
+    def result(self) -> List[float]:
+        """Get the current tracking results in the appropriate bounding box format."""
         coords = self.xyxy if self.angle is None else self.xywha
         return coords.tolist() + [self.track_id, self.score, self.cls, self.idx]
 
-    def __repr__(self):
-        """Returns a string representation of the STrack object including start frame, end frame, and track ID."""
+    def __repr__(self) -> str:
+        """Return a string representation of the STrack object including start frame, end frame, and track ID."""
         return f"OT_{self.track_id}_({self.start_frame}-{self.end_frame})"
 
 
@@ -250,15 +253,16 @@ class BYTETracker:
         kalman_filter (KalmanFilterXYAH): Kalman Filter object.
 
     Methods:
-        update(results, img=None): Updates object tracker with new detections.
-        get_kalmanfilter(): Returns a Kalman filter object for tracking bounding boxes.
-        init_track(dets, scores, cls, img=None): Initialize object tracking with detections.
-        get_dists(tracks, detections): Calculates the distance between tracks and detections.
-        multi_predict(tracks): Predicts the location of tracks.
-        reset_id(): Resets the ID counter of STrack.
-        joint_stracks(tlista, tlistb): Combines two lists of stracks.
-        sub_stracks(tlista, tlistb): Filters out the stracks present in the second list from the first list.
-        remove_duplicate_stracks(stracksa, stracksb): Removes duplicate stracks based on IoU.
+        update: Update object tracker with new detections.
+        get_kalmanfilter: Return a Kalman filter object for tracking bounding boxes.
+        init_track: Initialize object tracking with detections.
+        get_dists: Calculate the distance between tracks and detections.
+        multi_predict: Predict the location of tracks.
+        reset_id: Reset the ID counter of STrack.
+        reset: Reset the tracker by clearing all tracks.
+        joint_stracks: Combine two lists of stracks.
+        sub_stracks: Filter out the stracks present in the second list from the first list.
+        remove_duplicate_stracks: Remove duplicate stracks based on IoU.
 
     Examples:
         Initialize BYTETracker and update with detection results
@@ -267,7 +271,7 @@ class BYTETracker:
         >>> tracked_objects = tracker.update(results)
     """
 
-    def __init__(self, args, frame_rate=30):
+    def __init__(self, args, frame_rate: int = 30):
         """
         Initialize a BYTETracker instance for object tracking.
 
@@ -280,9 +284,9 @@ class BYTETracker:
             >>> args = Namespace(track_buffer=30)
             >>> tracker = BYTETracker(args, frame_rate=30)
         """
-        self.tracked_stracks = []  # type: list[STrack]
-        self.lost_stracks = []  # type: list[STrack]
-        self.removed_stracks = []  # type: list[STrack]
+        self.tracked_stracks = []  # type: List[STrack]
+        self.lost_stracks = []  # type: List[STrack]
+        self.removed_stracks = []  # type: List[STrack]
 
         self.frame_id = 0
         self.args = args
@@ -290,8 +294,8 @@ class BYTETracker:
         self.kalman_filter = self.get_kalmanfilter()
         self.reset_id()
 
-    def update(self, results, img=None, feats=None):
-        """Updates the tracker with new detections and returns the current list of tracked objects."""
+    def update(self, results, img: Optional[np.ndarray] = None, feats: Optional[np.ndarray] = None) -> np.ndarray:
+        """Update the tracker with new detections and return the current list of tracked objects."""
         self.frame_id += 1
         activated_stracks = []
         refind_stracks = []
@@ -319,7 +323,7 @@ class BYTETracker:
         detections = self.init_track(dets, scores_keep, cls_keep, img if feats is None else feats)
         # Add newly detected tracklets to tracked_stracks
         unconfirmed = []
-        tracked_stracks = []  # type: list[STrack]
+        tracked_stracks = []  # type: List[STrack]
         for track in self.tracked_stracks:
             if not track.is_activated:
                 unconfirmed.append(track)
@@ -408,42 +412,44 @@ class BYTETracker:
 
         return np.asarray([x.result for x in self.tracked_stracks if x.is_activated], dtype=np.float32)
 
-    def get_kalmanfilter(self):
-        """Returns a Kalman filter object for tracking bounding boxes using KalmanFilterXYAH."""
+    def get_kalmanfilter(self) -> KalmanFilterXYAH:
+        """Return a Kalman filter object for tracking bounding boxes using KalmanFilterXYAH."""
         return KalmanFilterXYAH()
 
-    def init_track(self, dets, scores, cls, img=None):
-        """Initializes object tracking with given detections, scores, and class labels using the STrack algorithm."""
+    def init_track(
+        self, dets: np.ndarray, scores: np.ndarray, cls: np.ndarray, img: Optional[np.ndarray] = None
+    ) -> List[STrack]:
+        """Initialize object tracking with given detections, scores, and class labels using the STrack algorithm."""
         return [STrack(xyxy, s, c) for (xyxy, s, c) in zip(dets, scores, cls)] if len(dets) else []  # detections
 
-    def get_dists(self, tracks, detections):
-        """Calculates the distance between tracks and detections using IoU and optionally fuses scores."""
+    def get_dists(self, tracks: List[STrack], detections: List[STrack]) -> np.ndarray:
+        """Calculate the distance between tracks and detections using IoU and optionally fuse scores."""
         dists = matching.iou_distance(tracks, detections)
         if self.args.fuse_score:
             dists = matching.fuse_score(dists, detections)
         return dists
 
-    def multi_predict(self, tracks):
+    def multi_predict(self, tracks: List[STrack]):
         """Predict the next states for multiple tracks using Kalman filter."""
         STrack.multi_predict(tracks)
 
     @staticmethod
     def reset_id():
-        """Resets the ID counter for STrack instances to ensure unique track IDs across tracking sessions."""
+        """Reset the ID counter for STrack instances to ensure unique track IDs across tracking sessions."""
         STrack.reset_id()
 
     def reset(self):
-        """Resets the tracker by clearing all tracked, lost, and removed tracks and reinitializing the Kalman filter."""
-        self.tracked_stracks = []  # type: list[STrack]
-        self.lost_stracks = []  # type: list[STrack]
-        self.removed_stracks = []  # type: list[STrack]
+        """Reset the tracker by clearing all tracked, lost, and removed tracks and reinitializing the Kalman filter."""
+        self.tracked_stracks = []  # type: List[STrack]
+        self.lost_stracks = []  # type: List[STrack]
+        self.removed_stracks = []  # type: List[STrack]
         self.frame_id = 0
         self.kalman_filter = self.get_kalmanfilter()
         self.reset_id()
 
     @staticmethod
-    def joint_stracks(tlista, tlistb):
-        """Combines two lists of STrack objects into a single list, ensuring no duplicates based on track IDs."""
+    def joint_stracks(tlista: List[STrack], tlistb: List[STrack]) -> List[STrack]:
+        """Combine two lists of STrack objects into a single list, ensuring no duplicates based on track IDs."""
         exists = {}
         res = []
         for t in tlista:
@@ -457,14 +463,14 @@ class BYTETracker:
         return res
 
     @staticmethod
-    def sub_stracks(tlista, tlistb):
-        """Filters out the stracks present in the second list from the first list."""
+    def sub_stracks(tlista: List[STrack], tlistb: List[STrack]) -> List[STrack]:
+        """Filter out the stracks present in the second list from the first list."""
         track_ids_b = {t.track_id for t in tlistb}
         return [t for t in tlista if t.track_id not in track_ids_b]
 
     @staticmethod
-    def remove_duplicate_stracks(stracksa, stracksb):
-        """Removes duplicate stracks from two lists based on Intersection over Union (IoU) distance."""
+    def remove_duplicate_stracks(stracksa: List[STrack], stracksb: List[STrack]) -> Tuple[List[STrack], List[STrack]]:
+        """Remove duplicate stracks from two lists based on Intersection over Union (IoU) distance."""
         pdist = matching.iou_distance(stracksa, stracksb)
         pairs = np.where(pdist < 0.15)
         dupa, dupb = [], []

ultralytics/trackers/track.py

@@ -20,15 +20,11 @@ def on_predict_start(predictor: object, persist: bool = False) -> None:
     Initialize trackers for object tracking during prediction.
 
     Args:
-        predictor (object): The predictor object to initialize trackers for.
-        persist (bool): Whether to persist the trackers if they already exist.
-
-    Raises:
-        AssertionError: If the tracker_type is not 'bytetrack' or 'botsort'.
-        ValueError: If the task is 'classify' as classification doesn't support tracking.
+        predictor (ultralytics.engine.predictor.BasePredictor): The predictor object to initialize trackers for.
+        persist (bool, optional): Whether to persist the trackers if they already exist.
 
     Examples:
-        Initialize trackers for a predictor object:
+        Initialize trackers for a predictor object
         >>> predictor = SomePredictorClass()
         >>> on_predict_start(predictor, persist=True)
     """
@@ -79,7 +75,7 @@ def on_predict_postprocess_end(predictor: object, persist: bool = False) -> None
 
     Args:
         predictor (object): The predictor object containing the predictions.
-        persist (bool): Whether to persist the trackers if they already exist.
+        persist (bool, optional): Whether to persist the trackers if they already exist.
 
     Examples:
         Postprocess predictions and update with tracking

ultralytics/trackers/utils/gmc.py

@@ -1,6 +1,7 @@
 # Ultralytics 🚀 AGPL-3.0 License - https://ultralytics.com/license
 
 import copy
+from typing import List, Optional
 
 import cv2
 import numpy as np
@@ -19,7 +20,7 @@ class GMC:
         method (str): The tracking method to use. Options include 'orb', 'sift', 'ecc', 'sparseOptFlow', 'none'.
         downscale (int): Factor by which to downscale the frames for processing.
         prevFrame (np.ndarray): Previous frame for tracking.
-        prevKeyPoints (list): Keypoints from the previous frame.
+        prevKeyPoints (List): Keypoints from the previous frame.
         prevDescriptors (np.ndarray): Descriptors from the previous frame.
         initializedFirstFrame (bool): Flag indicating if the first frame has been processed.
 
@@ -88,13 +89,13 @@ class GMC:
         self.prevDescriptors = None
         self.initializedFirstFrame = False
 
-    def apply(self, raw_frame: np.ndarray, detections: list = None) -> np.ndarray:
+    def apply(self, raw_frame: np.ndarray, detections: Optional[List] = None) -> np.ndarray:
         """
         Apply object detection on a raw frame using the specified method.
 
         Args:
             raw_frame (np.ndarray): The raw frame to be processed, with shape (H, W, C).
-            detections (List | None): List of detections to be used in the processing.
+            detections (List, optional): List of detections to be used in the processing.
 
         Returns:
             (np.ndarray): Transformation matrix with shape (2, 3).
@@ -136,23 +137,18 @@ class GMC:
         frame = cv2.cvtColor(raw_frame, cv2.COLOR_BGR2GRAY) if c == 3 else raw_frame
         H = np.eye(2, 3, dtype=np.float32)
 
-        # Downscale image
+        # Downscale image for computational efficiency
         if self.downscale > 1.0:
             frame = cv2.GaussianBlur(frame, (3, 3), 1.5)
             frame = cv2.resize(frame, (width // self.downscale, height // self.downscale))
 
-        # Handle first frame
+        # Handle first frame initialization
         if not self.initializedFirstFrame:
-            # Initialize data
             self.prevFrame = frame.copy()
-
-            # Initialization done
             self.initializedFirstFrame = True
-
             return H
 
-        # Run the ECC algorithm. The results are stored in warp_matrix.
-        # (cc, H) = cv2.findTransformECC(self.prevFrame, frame, H, self.warp_mode, self.criteria)
+        # Run the ECC algorithm to find transformation matrix
         try:
             (_, H) = cv2.findTransformECC(self.prevFrame, frame, H, self.warp_mode, self.criteria, None, 1)
         except Exception as e:
@@ -160,13 +156,13 @@ class GMC:
 
         return H
 
-    def apply_features(self, raw_frame: np.ndarray, detections: list = None) -> np.ndarray:
+    def apply_features(self, raw_frame: np.ndarray, detections: Optional[List] = None) -> np.ndarray:
         """
         Apply feature-based methods like ORB or SIFT to a raw frame.
 
         Args:
             raw_frame (np.ndarray): The raw frame to be processed, with shape (H, W, C).
-            detections (List | None): List of detections to be used in the processing.
+            detections (List, optional): List of detections to be used in the processing.
 
         Returns:
             (np.ndarray): Transformation matrix with shape (2, 3).
@@ -182,55 +178,50 @@ class GMC:
         frame = cv2.cvtColor(raw_frame, cv2.COLOR_BGR2GRAY) if c == 3 else raw_frame
         H = np.eye(2, 3)
 
-        # Downscale image
+        # Downscale image for computational efficiency
         if self.downscale > 1.0:
             frame = cv2.resize(frame, (width // self.downscale, height // self.downscale))
             width = width // self.downscale
             height = height // self.downscale
 
-        # Find the keypoints
+        # Create mask for keypoint detection, excluding border regions
         mask = np.zeros_like(frame)
         mask[int(0.02 * height) : int(0.98 * height), int(0.02 * width) : int(0.98 * width)] = 255
+
+        # Exclude detection regions from mask to avoid tracking detected objects
         if detections is not None:
             for det in detections:
                 tlbr = (det[:4] / self.downscale).astype(np.int_)
                 mask[tlbr[1] : tlbr[3], tlbr[0] : tlbr[2]] = 0
 
+        # Find keypoints and compute descriptors
         keypoints = self.detector.detect(frame, mask)
-
-        # Compute the descriptors
         keypoints, descriptors = self.extractor.compute(frame, keypoints)
 
-        # Handle first frame
+        # Handle first frame initialization
         if not self.initializedFirstFrame:
-            # Initialize data
             self.prevFrame = frame.copy()
             self.prevKeyPoints = copy.copy(keypoints)
             self.prevDescriptors = copy.copy(descriptors)
-
-            # Initialization done
             self.initializedFirstFrame = True
-
             return H
 
-        # Match descriptors
+        # Match descriptors between previous and current frame
         knnMatches = self.matcher.knnMatch(self.prevDescriptors, descriptors, 2)
 
-        # Filter matches based on smallest spatial distance
+        # Filter matches based on spatial distance constraints
         matches = []
         spatialDistances = []
-
         maxSpatialDistance = 0.25 * np.array([width, height])
 
         # Handle empty matches case
         if len(knnMatches) == 0:
-            # Store to next iteration
             self.prevFrame = frame.copy()
             self.prevKeyPoints = copy.copy(keypoints)
             self.prevDescriptors = copy.copy(descriptors)
-
             return H
 
+        # Apply Lowe's ratio test and spatial distance filtering
         for m, n in knnMatches:
             if m.distance < 0.9 * n.distance:
                 prevKeyPointLocation = self.prevKeyPoints[m.queryIdx].pt
@@ -247,11 +238,12 @@ class GMC:
                     spatialDistances.append(spatialDistance)
                     matches.append(m)
 
+        # Filter outliers using statistical analysis
         meanSpatialDistances = np.mean(spatialDistances, 0)
         stdSpatialDistances = np.std(spatialDistances, 0)
-
         inliers = (spatialDistances - meanSpatialDistances) < 2.5 * stdSpatialDistances
 
+        # Extract good matches and corresponding points
         goodMatches = []
         prevPoints = []
         currPoints = []
@@ -264,39 +256,18 @@ class GMC:
         prevPoints = np.array(prevPoints)
         currPoints = np.array(currPoints)
 
-        # Draw the keypoint matches on the output image
-        # if False:
-        #     import matplotlib.pyplot as plt
-        #     matches_img = np.hstack((self.prevFrame, frame))
-        #     matches_img = cv2.cvtColor(matches_img, cv2.COLOR_GRAY2BGR)
-        #     W = self.prevFrame.shape[1]
-        #     for m in goodMatches:
-        #         prev_pt = np.array(self.prevKeyPoints[m.queryIdx].pt, dtype=np.int_)
-        #         curr_pt = np.array(keypoints[m.trainIdx].pt, dtype=np.int_)
-        #         curr_pt[0] += W
-        #         color = np.random.randint(0, 255, 3)
-        #         color = (int(color[0]), int(color[1]), int(color[2]))
-        #
-        #         matches_img = cv2.line(matches_img, prev_pt, curr_pt, tuple(color), 1, cv2.LINE_AA)
-        #         matches_img = cv2.circle(matches_img, prev_pt, 2, tuple(color), -1)
-        #         matches_img = cv2.circle(matches_img, curr_pt, 2, tuple(color), -1)
-        #
-        #     plt.figure()
-        #     plt.imshow(matches_img)
-        #     plt.show()
-
-        # Find rigid matrix
+        # Estimate transformation matrix using RANSAC
         if prevPoints.shape[0] > 4:
             H, inliers = cv2.estimateAffinePartial2D(prevPoints, currPoints, cv2.RANSAC)
 
-            # Handle downscale
+            # Scale translation components back to original resolution
             if self.downscale > 1.0:
                 H[0, 2] *= self.downscale
                 H[1, 2] *= self.downscale
         else:
             LOGGER.warning("not enough matching points")
 
-        # Store to next iteration
+        # Store current frame data for next iteration
         self.prevFrame = frame.copy()
         self.prevKeyPoints = copy.copy(keypoints)
         self.prevDescriptors = copy.copy(descriptors)
@@ -324,24 +295,24 @@ class GMC:
         frame = cv2.cvtColor(raw_frame, cv2.COLOR_BGR2GRAY) if c == 3 else raw_frame
         H = np.eye(2, 3)
 
-        # Downscale image
+        # Downscale image for computational efficiency
         if self.downscale > 1.0:
             frame = cv2.resize(frame, (width // self.downscale, height // self.downscale))
 
-        # Find the keypoints
+        # Find good features to track
         keypoints = cv2.goodFeaturesToTrack(frame, mask=None, **self.feature_params)
 
-        # Handle first frame
+        # Handle first frame initialization
         if not self.initializedFirstFrame or self.prevKeyPoints is None:
             self.prevFrame = frame.copy()
             self.prevKeyPoints = copy.copy(keypoints)
             self.initializedFirstFrame = True
             return H
 
-        # Find correspondences
+        # Calculate optical flow using Lucas-Kanade method
         matchedKeypoints, status, _ = cv2.calcOpticalFlowPyrLK(self.prevFrame, frame, self.prevKeyPoints, None)
 
-        # Leave good correspondences only
+        # Extract successfully tracked points
         prevPoints = []
         currPoints = []
 
@@ -353,16 +324,18 @@ class GMC:
         prevPoints = np.array(prevPoints)
         currPoints = np.array(currPoints)
 
-        # Find rigid matrix
+        # Estimate transformation matrix using RANSAC
         if (prevPoints.shape[0] > 4) and (prevPoints.shape[0] == currPoints.shape[0]):
             H, _ = cv2.estimateAffinePartial2D(prevPoints, currPoints, cv2.RANSAC)
 
+            # Scale translation components back to original resolution
             if self.downscale > 1.0:
                 H[0, 2] *= self.downscale
                 H[1, 2] *= self.downscale
         else:
             LOGGER.warning("not enough matching points")
 
+        # Store current frame data for next iteration
         self.prevFrame = frame.copy()
         self.prevKeyPoints = copy.copy(keypoints)