ultralytics 8.3.143__py3-none-any.whl → 8.3.144__py3-none-any.whl

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)
 

ultralytics/trackers/utils/kalman_filter.py

@@ -20,12 +20,12 @@ class KalmanFilterXYAH:
         _std_weight_velocity (float): Standard deviation weight for velocity.
 
     Methods:
-        initiate: Creates a track from an unassociated measurement.
-        predict: Runs the Kalman filter prediction step.
-        project: Projects the state distribution to measurement space.
-        multi_predict: Runs the Kalman filter prediction step (vectorized version).
-        update: Runs the Kalman filter correction step.
-        gating_distance: Computes the gating distance between state distribution and measurements.
+        initiate: Create a track from an unassociated measurement.
+        predict: Run the Kalman filter prediction step.
+        project: Project the state distribution to measurement space.
+        multi_predict: Run the Kalman filter prediction step (vectorized version).
+        update: Run the Kalman filter correction step.
+        gating_distance: Compute the gating distance between state distribution and measurements.
 
     Examples:
         Initialize the Kalman filter and create a track from a measurement
@@ -70,8 +70,8 @@ class KalmanFilterXYAH:
                 and height h.
 
         Returns:
-            (np.ndarray): Mean vector (8-dimensional) of the new track. Unobserved velocities are initialized to 0 mean.
-            (np.ndarray): Covariance matrix (8x8 dimensional) of the new track.
+            mean (np.ndarray): Mean vector (8-dimensional) of the new track. Unobserved velocities are initialized to 0 mean.
+            covariance (np.ndarray): Covariance matrix (8x8 dimensional) of the new track.
 
         Examples:
             >>> kf = KalmanFilterXYAH()
@@ -104,8 +104,8 @@ class KalmanFilterXYAH:
             covariance (np.ndarray): The 8x8-dimensional covariance matrix of the object state at the previous time step.
 
         Returns:
-            (np.ndarray): Mean vector of the predicted state. Unobserved velocities are initialized to 0 mean.
-            (np.ndarray): Covariance matrix of the predicted state.
+            mean (np.ndarray): Mean vector of the predicted state. Unobserved velocities are initialized to 0 mean.
+            covariance (np.ndarray): Covariance matrix of the predicted state.
 
         Examples:
             >>> kf = KalmanFilterXYAH()
@@ -141,8 +141,8 @@ class KalmanFilterXYAH:
             covariance (np.ndarray): The state's covariance matrix (8x8 dimensional).
 
         Returns:
-            (np.ndarray): Projected mean of the given state estimate.
-            (np.ndarray): Projected covariance matrix of the given state estimate.
+            mean (np.ndarray): Projected mean of the given state estimate.
+            covariance (np.ndarray): Projected covariance matrix of the given state estimate.
 
         Examples:
             >>> kf = KalmanFilterXYAH()
@@ -171,8 +171,8 @@ class KalmanFilterXYAH:
             covariance (np.ndarray): The Nx8x8 covariance matrix of the object states at the previous time step.
 
         Returns:
-            (np.ndarray): Mean matrix of the predicted states with shape (N, 8).
-            (np.ndarray): Covariance matrix of the predicted states with shape (N, 8, 8).
+            mean (np.ndarray): Mean matrix of the predicted states with shape (N, 8).
+            covariance (np.ndarray): Covariance matrix of the predicted states with shape (N, 8, 8).
 
         Examples:
             >>> mean = np.random.rand(10, 8)  # 10 object states
@@ -213,8 +213,8 @@ class KalmanFilterXYAH:
                 position, a the aspect ratio, and h the height of the bounding box.
 
         Returns:
-            (np.ndarray): Measurement-corrected state mean.
-            (np.ndarray): Measurement-corrected state covariance.
+            new_mean (np.ndarray): Measurement-corrected state mean.
+            new_covariance (np.ndarray): Measurement-corrected state covariance.
 
         Examples:
             >>> kf = KalmanFilterXYAH()
@@ -254,8 +254,8 @@ class KalmanFilterXYAH:
             covariance (np.ndarray): Covariance of the state distribution (8x8 dimensional).
             measurements (np.ndarray): An (N, 4) matrix of N measurements, each in format (x, y, a, h) where (x, y) is the
                 bounding box center position, a the aspect ratio, and h the height.
-            only_position (bool): If True, distance computation is done with respect to box center position only.
-            metric (str): The metric to use for calculating the distance. Options are 'gaussian' for the squared
+            only_position (bool, optional): If True, distance computation is done with respect to box center position only.
+            metric (str, optional): The metric to use for calculating the distance. Options are 'gaussian' for the squared
                 Euclidean distance and 'maha' for the squared Mahalanobis distance.
 
         Returns:
@@ -302,11 +302,11 @@ class KalmanFilterXYWH(KalmanFilterXYAH):
         _std_weight_velocity (float): Standard deviation weight for velocity.
 
     Methods:
-        initiate: Creates a track from an unassociated measurement.
-        predict: Runs the Kalman filter prediction step.
-        project: Projects the state distribution to measurement space.
-        multi_predict: Runs the Kalman filter prediction step in a vectorized manner.
-        update: Runs the Kalman filter correction step.
+        initiate: Create a track from an unassociated measurement.
+        predict: Run the Kalman filter prediction step.
+        project: Project the state distribution to measurement space.
+        multi_predict: Run the Kalman filter prediction step in a vectorized manner.
+        update: Run the Kalman filter correction step.
 
     Examples:
         Create a Kalman filter and initialize a track
@@ -325,8 +325,8 @@ class KalmanFilterXYWH(KalmanFilterXYAH):
             measurement (np.ndarray): Bounding box coordinates (x, y, w, h) with center position (x, y), width, and height.
 
         Returns:
-            (np.ndarray): Mean vector (8 dimensional) of the new track. Unobserved velocities are initialized to 0 mean.
-            (np.ndarray): Covariance matrix (8x8 dimensional) of the new track.
+            mean (np.ndarray): Mean vector (8 dimensional) of the new track. Unobserved velocities are initialized to 0 mean.
+            covariance (np.ndarray): Covariance matrix (8x8 dimensional) of the new track.
 
         Examples:
             >>> kf = KalmanFilterXYWH()
@@ -361,7 +361,7 @@ class KalmanFilterXYWH(KalmanFilterXYAH):
         covariance = np.diag(np.square(std))
         return mean, covariance
 
-    def predict(self, mean, covariance):
+    def predict(self, mean: np.ndarray, covariance: np.ndarray):
         """
         Run Kalman filter prediction step.
 
@@ -370,8 +370,8 @@ class KalmanFilterXYWH(KalmanFilterXYAH):
             covariance (np.ndarray): The 8x8-dimensional covariance matrix of the object state at the previous time step.
 
         Returns:
-            (np.ndarray): Mean vector of the predicted state. Unobserved velocities are initialized to 0 mean.
-            (np.ndarray): Covariance matrix of the predicted state.
+            mean (np.ndarray): Mean vector of the predicted state. Unobserved velocities are initialized to 0 mean.
+            covariance (np.ndarray): Covariance matrix of the predicted state.
 
         Examples:
             >>> kf = KalmanFilterXYWH()
@@ -398,7 +398,7 @@ class KalmanFilterXYWH(KalmanFilterXYAH):
 
         return mean, covariance
 
-    def project(self, mean, covariance):
+    def project(self, mean: np.ndarray, covariance: np.ndarray):
         """
         Project state distribution to measurement space.
 
@@ -407,8 +407,8 @@ class KalmanFilterXYWH(KalmanFilterXYAH):
             covariance (np.ndarray): The state's covariance matrix (8x8 dimensional).
 
         Returns:
-            (np.ndarray): Projected mean of the given state estimate.
-            (np.ndarray): Projected covariance matrix of the given state estimate.
+            mean (np.ndarray): Projected mean of the given state estimate.
+            covariance (np.ndarray): Projected covariance matrix of the given state estimate.
 
         Examples:
             >>> kf = KalmanFilterXYWH()
@@ -428,7 +428,7 @@ class KalmanFilterXYWH(KalmanFilterXYAH):
         covariance = np.linalg.multi_dot((self._update_mat, covariance, self._update_mat.T))
         return mean, covariance + innovation_cov
 
-    def multi_predict(self, mean, covariance):
+    def multi_predict(self, mean: np.ndarray, covariance: np.ndarray):
         """
         Run Kalman filter prediction step (Vectorized version).
 
@@ -437,8 +437,8 @@ class KalmanFilterXYWH(KalmanFilterXYAH):
             covariance (np.ndarray): The Nx8x8 covariance matrix of the object states at the previous time step.
 
         Returns:
-            (np.ndarray): Mean matrix of the predicted states with shape (N, 8).
-            (np.ndarray): Covariance matrix of the predicted states with shape (N, 8, 8).
+            mean (np.ndarray): Mean matrix of the predicted states with shape (N, 8).
+            covariance (np.ndarray): Covariance matrix of the predicted states with shape (N, 8, 8).
 
         Examples:
             >>> mean = np.random.rand(5, 8)  # 5 objects with 8-dimensional state vectors
@@ -469,7 +469,7 @@ class KalmanFilterXYWH(KalmanFilterXYAH):
 
         return mean, covariance
 
-    def update(self, mean, covariance, measurement):
+    def update(self, mean: np.ndarray, covariance: np.ndarray, measurement: np.ndarray):
         """
         Run Kalman filter correction step.
 
@@ -480,8 +480,8 @@ class KalmanFilterXYWH(KalmanFilterXYAH):
                 position, w the width, and h the height of the bounding box.
 
         Returns:
-            (np.ndarray): Measurement-corrected state mean.
-            (np.ndarray): Measurement-corrected state covariance.
+            new_mean (np.ndarray): Measurement-corrected state mean.
+            new_covariance (np.ndarray): Measurement-corrected state covariance.
 
         Examples:
             >>> kf = KalmanFilterXYWH()

ultralytics/trackers/utils/matching.py

@@ -17,7 +17,7 @@ except (ImportError, AssertionError, AttributeError):
     import lap
 
 
-def linear_assignment(cost_matrix: np.ndarray, thresh: float, use_lap: bool = True) -> tuple:
+def linear_assignment(cost_matrix: np.ndarray, thresh: float, use_lap: bool = True):
     """
     Perform linear assignment using either the scipy or lap.lapjv method.