ultralytics 8.2.76__py3-none-any.whl → 8.2.77__py3-none-any.whl

ultralytics/trackers/utils/kalman_filter.py

@@ -6,17 +6,49 @@ import scipy.linalg
 
 class KalmanFilterXYAH:
     """
-    For bytetrack. A simple Kalman filter for tracking bounding boxes in image space.
-
-    The 8-dimensional state space (x, y, a, h, vx, vy, va, vh) contains the bounding box center position (x, y), aspect
-    ratio a, height h, and their respective velocities.
-
-    Object motion follows a constant velocity model. The bounding box location (x, y, a, h) is taken as direct
-    observation of the state space (linear observation model).
+    A KalmanFilterXYAH class for tracking bounding boxes in image space using a Kalman filter.
+
+    Implements a simple Kalman filter for tracking bounding boxes in image space. The 8-dimensional state space
+    (x, y, a, h, vx, vy, va, vh) contains the bounding box center position (x, y), aspect ratio a, height h, and their
+    respective velocities. Object motion follows a constant velocity model, and bounding box location (x, y, a, h) is
+    taken as a direct observation of the state space (linear observation model).
+
+    Attributes:
+        _motion_mat (np.ndarray): The motion matrix for the Kalman filter.
+        _update_mat (np.ndarray): The update matrix for the Kalman filter.
+        _std_weight_position (float): Standard deviation weight for position.
+        _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.
+
+    Examples:
+        Initialize the Kalman filter and create a track from a measurement
+        >>> kf = KalmanFilterXYAH()
+        >>> measurement = np.array([100, 200, 1.5, 50])
+        >>> mean, covariance = kf.initiate(measurement)
+        >>> print(mean)
+        >>> print(covariance)
     """
 
     def __init__(self):
-        """Initialize Kalman filter model matrices with motion and observation uncertainty weights."""
+        """
+        Initialize Kalman filter model matrices with motion and observation uncertainty weights.
+
+        The Kalman filter is initialized with an 8-dimensional state space (x, y, a, h, vx, vy, va, vh), where (x, y)
+        represents the bounding box center position, 'a' is the aspect ratio, 'h' is the height, and their respective
+        velocities are (vx, vy, va, vh). The filter uses a constant velocity model for object motion and a linear
+        observation model for bounding box location.
+
+        Examples:
+            Initialize a Kalman filter for tracking:
+            >>> kf = KalmanFilterXYAH()
+        """
         ndim, dt = 4, 1.0
 
         # Create Kalman filter model matrices
@@ -32,15 +64,20 @@ class KalmanFilterXYAH:
 
     def initiate(self, measurement: np.ndarray) -> tuple:
         """
-        Create track from unassociated measurement.
+        Create a track from an unassociated measurement.
 
         Args:
             measurement (ndarray): Bounding box coordinates (x, y, a, h) with center position (x, y), aspect ratio a,
                 and height h.
 
         Returns:
-            (tuple[ndarray, ndarray]): Returns the mean vector (8 dimensional) and covariance matrix (8x8 dimensional)
+            (tuple[ndarray, ndarray]): Returns the mean vector (8-dimensional) and covariance matrix (8x8 dimensional)
                 of the new track. Unobserved velocities are initialized to 0 mean.
+
+        Examples:
+            >>> kf = KalmanFilterXYAH()
+            >>> measurement = np.array([100, 50, 1.5, 200])
+            >>> mean, covariance = kf.initiate(measurement)
         """
         mean_pos = measurement
         mean_vel = np.zeros_like(mean_pos)
@@ -64,12 +101,18 @@ class KalmanFilterXYAH:
         Run Kalman filter prediction step.
 
         Args:
-            mean (ndarray): The 8 dimensional mean vector of the object state at the previous time step.
-            covariance (ndarray): The 8x8 dimensional covariance matrix of the object state at the previous time step.
+            mean (ndarray): The 8-dimensional mean vector of the object state at the previous time step.
+            covariance (ndarray): The 8x8-dimensional covariance matrix of the object state at the previous time step.
 
         Returns:
             (tuple[ndarray, ndarray]): Returns the mean vector and covariance matrix of the predicted state. Unobserved
                 velocities are initialized to 0 mean.
+
+        Examples:
+            >>> kf = KalmanFilterXYAH()
+            >>> mean = np.array([0, 0, 1, 1, 0, 0, 0, 0])
+            >>> covariance = np.eye(8)
+            >>> predicted_mean, predicted_covariance = kf.predict(mean, covariance)
         """
         std_pos = [
             self._std_weight_position * mean[3],
@@ -100,6 +143,12 @@ class KalmanFilterXYAH:
 
         Returns:
             (tuple[ndarray, ndarray]): Returns the projected mean and covariance matrix of the given state estimate.
+
+        Examples:
+            >>> kf = KalmanFilterXYAH()
+            >>> mean = np.array([0, 0, 1, 1, 0, 0, 0, 0])
+            >>> covariance = np.eye(8)
+            >>> projected_mean, projected_covariance = kf.project(mean, covariance)
         """
         std = [
             self._std_weight_position * mean[3],
@@ -115,15 +164,21 @@ class KalmanFilterXYAH:
 
     def multi_predict(self, mean: np.ndarray, covariance: np.ndarray) -> tuple:
         """
-        Run Kalman filter prediction step (Vectorized version).
+        Run Kalman filter prediction step for multiple object states (Vectorized version).
 
         Args:
             mean (ndarray): The Nx8 dimensional mean matrix of the object states at the previous time step.
             covariance (ndarray): The Nx8x8 covariance matrix of the object states at the previous time step.
 
         Returns:
-            (tuple[ndarray, ndarray]): Returns the mean vector and covariance matrix of the predicted state. Unobserved
-                velocities are initialized to 0 mean.
+            (tuple[ndarray, ndarray]): Returns the mean matrix and covariance matrix of the predicted states.
+                The mean matrix has shape (N, 8) and the covariance matrix has shape (N, 8, 8). Unobserved velocities
+                are initialized to 0 mean.
+
+        Examples:
+            >>> mean = np.random.rand(10, 8)  # 10 object states
+            >>> covariance = np.random.rand(10, 8, 8)  # Covariance matrices for 10 object states
+            >>> predicted_mean, predicted_covariance = kalman_filter.multi_predict(mean, covariance)
         """
         std_pos = [
             self._std_weight_position * mean[:, 3],
@@ -160,6 +215,13 @@ class KalmanFilterXYAH:
 
         Returns:
             (tuple[ndarray, ndarray]): Returns the measurement-corrected state distribution.
+
+        Examples:
+            >>> kf = KalmanFilterXYAH()
+            >>> mean = np.array([0, 0, 1, 1, 0, 0, 0, 0])
+            >>> covariance = np.eye(8)
+            >>> measurement = np.array([1, 1, 1, 1])
+            >>> new_mean, new_covariance = kf.update(mean, covariance, measurement)
         """
         projected_mean, projected_cov = self.project(mean, covariance)
 
@@ -182,23 +244,31 @@ class KalmanFilterXYAH:
         metric: str = "maha",
     ) -> np.ndarray:
         """
-        Compute gating distance between state distribution and measurements. A suitable distance threshold can be
-        obtained from `chi2inv95`. If `only_position` is False, the chi-square distribution has 4 degrees of freedom,
-        otherwise 2.
+        Compute gating distance between state distribution and measurements.
+
+        A suitable distance threshold can be obtained from `chi2inv95`. If `only_position` is False, the chi-square
+        distribution has 4 degrees of freedom, otherwise 2.
 
         Args:
             mean (ndarray): Mean vector over the state distribution (8 dimensional).
             covariance (ndarray): Covariance of the state distribution (8x8 dimensional).
-            measurements (ndarray): An Nx4 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, optional): If True, distance computation is done with respect to the bounding box
-                center position only. Defaults to False.
-            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. Defaults to 'maha'.
+            measurements (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
+                Euclidean distance and 'maha' for the squared Mahalanobis distance.
 
         Returns:
             (np.ndarray): Returns an array of length N, where the i-th element contains the squared distance between
                 (mean, covariance) and `measurements[i]`.
+
+        Examples:
+            Compute gating distance using Mahalanobis metric:
+            >>> kf = KalmanFilterXYAH()
+            >>> mean = np.array([0, 0, 1, 1, 0, 0, 0, 0])
+            >>> covariance = np.eye(8)
+            >>> measurements = np.array([[1, 1, 1, 1], [2, 2, 1, 1]])
+            >>> distances = kf.gating_distance(mean, covariance, measurements, only_position=False, metric='maha')
         """
         mean, covariance = self.project(mean, covariance)
         if only_position:
@@ -218,13 +288,33 @@ class KalmanFilterXYAH:
 
 class KalmanFilterXYWH(KalmanFilterXYAH):
     """
-    For BoT-SORT. A simple Kalman filter for tracking bounding boxes in image space.
-
-    The 8-dimensional state space (x, y, w, h, vx, vy, vw, vh) contains the bounding box center position (x, y), width
-    w, height h, and their respective velocities.
+    A KalmanFilterXYWH class for tracking bounding boxes in image space using a Kalman filter.
 
-    Object motion follows a constant velocity model. The bounding box location (x, y, w, h) is taken as direct
+    Implements a Kalman filter for tracking bounding boxes with state space (x, y, w, h, vx, vy, vw, vh), where
+    (x, y) is the center position, w is the width, h is the height, and vx, vy, vw, vh are their respective velocities.
+    The object motion follows a constant velocity model, and the bounding box location (x, y, w, h) is taken as a direct
     observation of the state space (linear observation model).
+
+    Attributes:
+        _motion_mat (np.ndarray): The motion matrix for the Kalman filter.
+        _update_mat (np.ndarray): The update matrix for the Kalman filter.
+        _std_weight_position (float): Standard deviation weight for position.
+        _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.
+
+    Examples:
+        Create a Kalman filter and initialize a track
+        >>> kf = KalmanFilterXYWH()
+        >>> measurement = np.array([100, 50, 20, 40])
+        >>> mean, covariance = kf.initiate(measurement)
+        >>> print(mean)
+        >>> print(covariance)
     """
 
     def initiate(self, measurement: np.ndarray) -> tuple:
@@ -237,6 +327,22 @@ class KalmanFilterXYWH(KalmanFilterXYAH):
         Returns:
             (tuple[ndarray, ndarray]): Returns the mean vector (8 dimensional) and covariance matrix (8x8 dimensional)
                 of the new track. Unobserved velocities are initialized to 0 mean.
+
+        Examples:
+            >>> kf = KalmanFilterXYWH()
+            >>> measurement = np.array([100, 50, 20, 40])
+            >>> mean, covariance = kf.initiate(measurement)
+            >>> print(mean)
+            [100.  50.  20.  40.   0.   0.   0.   0.]
+            >>> print(covariance)
+            [[ 4.  0.  0.  0.  0.  0.  0.  0.]
+             [ 0.  4.  0.  0.  0.  0.  0.  0.]
+             [ 0.  0.  4.  0.  0.  0.  0.  0.]
+             [ 0.  0.  0.  4.  0.  0.  0.  0.]
+             [ 0.  0.  0.  0.  0.25  0.  0.  0.]
+             [ 0.  0.  0.  0.  0.  0.25  0.  0.]
+             [ 0.  0.  0.  0.  0.  0.  0.25  0.]
+             [ 0.  0.  0.  0.  0.  0.  0.  0.25]]
         """
         mean_pos = measurement
         mean_vel = np.zeros_like(mean_pos)
@@ -260,12 +366,18 @@ class KalmanFilterXYWH(KalmanFilterXYAH):
         Run Kalman filter prediction step.
 
         Args:
-            mean (ndarray): The 8 dimensional mean vector of the object state at the previous time step.
-            covariance (ndarray): The 8x8 dimensional covariance matrix of the object state at the previous time step.
+            mean (ndarray): The 8-dimensional mean vector of the object state at the previous time step.
+            covariance (ndarray): The 8x8-dimensional covariance matrix of the object state at the previous time step.
 
         Returns:
             (tuple[ndarray, ndarray]): Returns the mean vector and covariance matrix of the predicted state. Unobserved
                 velocities are initialized to 0 mean.
+
+        Examples:
+            >>> kf = KalmanFilterXYWH()
+            >>> mean = np.array([0, 0, 1, 1, 0, 0, 0, 0])
+            >>> covariance = np.eye(8)
+            >>> predicted_mean, predicted_covariance = kf.predict(mean, covariance)
         """
         std_pos = [
             self._std_weight_position * mean[2],
@@ -296,6 +408,12 @@ class KalmanFilterXYWH(KalmanFilterXYAH):
 
         Returns:
             (tuple[ndarray, ndarray]): Returns the projected mean and covariance matrix of the given state estimate.
+
+        Examples:
+            >>> kf = KalmanFilterXYWH()
+            >>> mean = np.array([0, 0, 1, 1, 0, 0, 0, 0])
+            >>> covariance = np.eye(8)
+            >>> projected_mean, projected_cov = kf.project(mean, covariance)
         """
         std = [
             self._std_weight_position * mean[2],
@@ -320,6 +438,12 @@ class KalmanFilterXYWH(KalmanFilterXYAH):
         Returns:
             (tuple[ndarray, ndarray]): Returns the mean vector and covariance matrix of the predicted state. Unobserved
                 velocities are initialized to 0 mean.
+
+        Examples:
+            >>> mean = np.random.rand(5, 8)  # 5 objects with 8-dimensional state vectors
+            >>> covariance = np.random.rand(5, 8, 8)  # 5 objects with 8x8 covariance matrices
+            >>> kf = KalmanFilterXYWH()
+            >>> predicted_mean, predicted_covariance = kf.multi_predict(mean, covariance)
         """
         std_pos = [
             self._std_weight_position * mean[:, 2],
@@ -356,5 +480,12 @@ class KalmanFilterXYWH(KalmanFilterXYAH):
 
         Returns:
             (tuple[ndarray, ndarray]): Returns the measurement-corrected state distribution.
+
+        Examples:
+            >>> kf = KalmanFilterXYWH()
+            >>> mean = np.array([0, 0, 1, 1, 0, 0, 0, 0])
+            >>> covariance = np.eye(8)
+            >>> measurement = np.array([0.5, 0.5, 1.2, 1.2])
+            >>> new_mean, new_covariance = kf.update(mean, covariance, measurement)
         """
         return super().update(mean, covariance, measurement)

ultralytics/trackers/utils/matching.py

@@ -19,18 +19,23 @@ except (ImportError, AssertionError, AttributeError):
 
 def linear_assignment(cost_matrix: np.ndarray, thresh: float, use_lap: bool = True) -> tuple:
     """
-    Perform linear assignment using scipy or lap.lapjv.
+    Perform linear assignment using either the scipy or lap.lapjv method.
 
     Args:
-        cost_matrix (np.ndarray): The matrix containing cost values for assignments.
+        cost_matrix (np.ndarray): The matrix containing cost values for assignments, with shape (N, M).
         thresh (float): Threshold for considering an assignment valid.
-        use_lap (bool, optional): Whether to use lap.lapjv. Defaults to True.
+        use_lap (bool): Use lap.lapjv for the assignment. If False, scipy.optimize.linear_sum_assignment is used.
 
     Returns:
-        Tuple with:
-            - matched indices
-            - unmatched indices from 'a'
-            - unmatched indices from 'b'
+        (tuple): A tuple containing:
+            - matched_indices (np.ndarray): Array of matched indices of shape (K, 2), where K is the number of matches.
+            - unmatched_a (np.ndarray): Array of unmatched indices from the first set, with shape (L,).
+            - unmatched_b (np.ndarray): Array of unmatched indices from the second set, with shape (M,).
+
+    Examples:
+        >>> cost_matrix = np.array([[1, 2, 3], [4, 5, 6], [7, 8, 9]])
+        >>> thresh = 5.0
+        >>> matched_indices, unmatched_a, unmatched_b = linear_assignment(cost_matrix, thresh, use_lap=True)
     """
 
     if cost_matrix.size == 0:
@@ -68,6 +73,12 @@ def iou_distance(atracks: list, btracks: list) -> np.ndarray:
 
     Returns:
         (np.ndarray): Cost matrix computed based on IoU.
+
+    Examples:
+        Compute IoU distance between two sets of tracks
+        >>> atracks = [np.array([0, 0, 10, 10]), np.array([20, 20, 30, 30])]
+        >>> btracks = [np.array([5, 5, 15, 15]), np.array([25, 25, 35, 35])]
+        >>> cost_matrix = iou_distance(atracks, btracks)
     """
 
     if atracks and isinstance(atracks[0], np.ndarray) or btracks and isinstance(btracks[0], np.ndarray):
@@ -98,12 +109,19 @@ def embedding_distance(tracks: list, detections: list, metric: str = "cosine") -
     Compute distance between tracks and detections based on embeddings.
 
     Args:
-        tracks (list[STrack]): List of tracks.
-        detections (list[BaseTrack]): List of detections.
-        metric (str, optional): Metric for distance computation. Defaults to 'cosine'.
+        tracks (list[STrack]): List of tracks, where each track contains embedding features.
+        detections (list[BaseTrack]): List of detections, where each detection contains embedding features.
+        metric (str): Metric for distance computation. Supported metrics include 'cosine', 'euclidean', etc.
 
     Returns:
-        (np.ndarray): Cost matrix computed based on embeddings.
+        (np.ndarray): Cost matrix computed based on embeddings with shape (N, M), where N is the number of tracks
+            and M is the number of detections.
+
+    Examples:
+        Compute the embedding distance between tracks and detections using cosine metric
+        >>> tracks = [STrack(...), STrack(...)]  # List of track objects with embedding features
+        >>> detections = [BaseTrack(...), BaseTrack(...)]  # List of detection objects with embedding features
+        >>> cost_matrix = embedding_distance(tracks, detections, metric='cosine')
     """
 
     cost_matrix = np.zeros((len(tracks), len(detections)), dtype=np.float32)
@@ -122,11 +140,17 @@ def fuse_score(cost_matrix: np.ndarray, detections: list) -> np.ndarray:
     Fuses cost matrix with detection scores to produce a single similarity matrix.
 
     Args:
-        cost_matrix (np.ndarray): The matrix containing cost values for assignments.
-        detections (list[BaseTrack]): List of detections with scores.
+        cost_matrix (np.ndarray): The matrix containing cost values for assignments, with shape (N, M).
+        detections (list[BaseTrack]): List of detections, each containing a score attribute.
 
     Returns:
-        (np.ndarray): Fused similarity matrix.
+        (np.ndarray): Fused similarity matrix with shape (N, M).
+
+    Examples:
+        Fuse a cost matrix with detection scores
+        >>> cost_matrix = np.random.rand(5, 10)  # 5 tracks and 10 detections
+        >>> detections = [BaseTrack(score=np.random.rand()) for _ in range(10)]
+        >>> fused_matrix = fuse_score(cost_matrix, detections)
     """
 
     if cost_matrix.size == 0:

ultralytics/utils/__init__.py

@@ -47,7 +47,7 @@ PYTHON_VERSION = platform.python_version()
 TORCH_VERSION = torch.__version__
 TORCHVISION_VERSION = importlib.metadata.version("torchvision")  # faster than importing torchvision
 HELP_MSG = """
-    Usage examples for running Ultralytics YOLO:
+    Examples for running Ultralytics:
 
     1. Install the ultralytics package:
 

ultralytics/utils/files.py

@@ -11,19 +11,44 @@ from pathlib import Path
 
 
 class WorkingDirectory(contextlib.ContextDecorator):
-    """Usage: @WorkingDirectory(dir) decorator or 'with WorkingDirectory(dir):' context manager."""
+    """
+    A context manager and decorator for temporarily changing the working directory.
+
+    This class allows for the temporary change of the working directory using a context manager or decorator.
+    It ensures that the original working directory is restored after the context or decorated function completes.
+
+    Attributes:
+        dir (Path): The new directory to switch to.
+        cwd (Path): The original current working directory before the switch.
+
+    Methods:
+        __enter__: Changes the current directory to the specified directory.
+        __exit__: Restores the original working directory on context exit.
+
+    Examples:
+        Using as a context manager:
+        >>> with WorkingDirectory('/path/to/new/dir'):
+        >>>     # Perform operations in the new directory
+        >>>     pass
+
+        Using as a decorator:
+        >>> @WorkingDirectory('/path/to/new/dir')
+        >>> def some_function():
+        >>>     # Perform operations in the new directory
+        >>>     pass
+    """
 
     def __init__(self, new_dir):
-        """Sets the working directory to 'new_dir' upon instantiation."""
+        """Sets the working directory to 'new_dir' upon instantiation for use with context managers or decorators."""
         self.dir = new_dir  # new dir
         self.cwd = Path.cwd().resolve()  # current dir
 
     def __enter__(self):
-        """Changes the current directory to the specified directory."""
+        """Changes the current working directory to the specified directory upon entering the context."""
         os.chdir(self.dir)
 
     def __exit__(self, exc_type, exc_val, exc_tb):  # noqa
-        """Restore the current working directory on context exit."""
+        """Restores the original working directory when exiting the context."""
         os.chdir(self.cwd)
 
 
@@ -35,18 +60,16 @@ def spaces_in_path(path):
     file/directory back to its original location.
 
     Args:
-        path (str | Path): The original path.
+        path (str | Path): The original path that may contain spaces.
 
     Yields:
         (Path): Temporary path with spaces replaced by underscores if spaces were present, otherwise the original path.
 
-    Example:
-        ```python
-        with ultralytics.utils.files import spaces_in_path
-
-        with spaces_in_path('/path/with spaces') as new_path:
-            # Your code here
-        ```
+    Examples:
+        Use the context manager to handle paths with spaces:
+        >>> from ultralytics.utils.files import spaces_in_path
+        >>> with spaces_in_path('/path/with spaces') as new_path:
+        >>>     # Your code here
     """
 
     # If path has spaces, replace them with underscores
@@ -84,21 +107,35 @@ def spaces_in_path(path):
 
 def increment_path(path, exist_ok=False, sep="", mkdir=False):
     """
-    Increments a file or directory path, i.e. runs/exp --> runs/exp{sep}2, runs/exp{sep}3, ... etc.
+    Increments a file or directory path, i.e., runs/exp --> runs/exp{sep}2, runs/exp{sep}3, ... etc.
 
-    If the path exists and exist_ok is not set to True, the path will be incremented by appending a number and sep to
+    If the path exists and `exist_ok` is not True, the path will be incremented by appending a number and `sep` to
     the end of the path. If the path is a file, the file extension will be preserved. If the path is a directory, the
-    number will be appended directly to the end of the path. If mkdir is set to True, the path will be created as a
+    number will be appended directly to the end of the path. If `mkdir` is set to True, the path will be created as a
     directory if it does not already exist.
 
     Args:
-        path (str, pathlib.Path): Path to increment.
-        exist_ok (bool, optional): If True, the path will not be incremented and returned as-is. Defaults to False.
-        sep (str, optional): Separator to use between the path and the incrementation number. Defaults to ''.
-        mkdir (bool, optional): Create a directory if it does not exist. Defaults to False.
+        path (str | pathlib.Path): Path to increment.
+        exist_ok (bool): If True, the path will not be incremented and returned as-is.
+        sep (str): Separator to use between the path and the incrementation number.
+        mkdir (bool): Create a directory if it does not exist.
 
     Returns:
         (pathlib.Path): Incremented path.
+
+    Examples:
+        Increment a directory path:
+        >>> from pathlib import Path
+        >>> path = Path("runs/exp")
+        >>> new_path = increment_path(path)
+        >>> print(new_path)
+        runs/exp2
+
+        Increment a file path:
+        >>> path = Path("runs/exp/results.txt")
+        >>> new_path = increment_path(path)
+        >>> print(new_path)
+        runs/exp/results2.txt
     """
     path = Path(path)  # os-agnostic
     if path.exists() and not exist_ok:
@@ -118,19 +155,19 @@ def increment_path(path, exist_ok=False, sep="", mkdir=False):
 
 
 def file_age(path=__file__):
-    """Return days since last file update."""
+    """Return days since the last modification of the specified file."""
     dt = datetime.now() - datetime.fromtimestamp(Path(path).stat().st_mtime)  # delta
     return dt.days  # + dt.seconds / 86400  # fractional days
 
 
 def file_date(path=__file__):
-    """Return human-readable file modification date, i.e. '2021-3-26'."""
+    """Returns the file modification date in 'YYYY-M-D' format."""
     t = datetime.fromtimestamp(Path(path).stat().st_mtime)
     return f"{t.year}-{t.month}-{t.day}"
 
 
 def file_size(path):
-    """Return file/dir size (MB)."""
+    """Returns the size of a file or directory in megabytes (MB)."""
     if isinstance(path, (str, Path)):
         mb = 1 << 20  # bytes to MiB (1024 ** 2)
         path = Path(path)
@@ -142,7 +179,7 @@ def file_size(path):
 
 
 def get_latest_run(search_dir="."):
-    """Return path to most recent 'last.pt' in /runs (i.e. to --resume from)."""
+    """Returns the path to the most recent 'last.pt' file in the specified directory for resuming training."""
     last_list = glob.glob(f"{search_dir}/**/last*.pt", recursive=True)
     return max(last_list, key=os.path.getctime) if last_list else ""
 
@@ -152,17 +189,15 @@ def update_models(model_names=("yolov8n.pt",), source_dir=Path("."), update_name
     Updates and re-saves specified YOLO models in an 'updated_models' subdirectory.
 
     Args:
-        model_names (tuple, optional): Model filenames to update, defaults to ("yolov8n.pt").
-        source_dir (Path, optional): Directory containing models and target subdirectory, defaults to current directory.
-        update_names (bool, optional): Update model names from a data YAML.
-
-    Example:
-        ```python
-        from ultralytics.utils.files import update_models
-
-        model_names = (f"rtdetr-{size}.pt" for size in "lx")
-        update_models(model_names)
-        ```
+        model_names (Tuple[str, ...]): Model filenames to update.
+        source_dir (Path): Directory containing models and target subdirectory.
+        update_names (bool): Update model names from a data YAML.
+
+    Examples:
+        Update specified YOLO models and save them in 'updated_models' subdirectory:
+        >>> from ultralytics.utils.files import update_models
+        >>> model_names = ("yolov8n.pt", "yolov8s.pt")
+        >>> update_models(model_names, source_dir=Path("/models"), update_names=True)
     """
     from ultralytics import YOLO
     from ultralytics.nn.autobackend import default_class_names

ultralytics/utils/plotting.py

@@ -369,7 +369,7 @@ class Annotator:
             # Convert im back to PIL and update draw
             self.fromarray(self.im)
 
-    def kpts(self, kpts, shape=(640, 640), radius=5, kpt_line=True, conf_thres=0.25):
+    def kpts(self, kpts, shape=(640, 640), radius=5, kpt_line=True, conf_thres=0.25, kpt_color=None):
         """
         Plot keypoints on the image.
 
@@ -379,6 +379,7 @@ class Annotator:
             radius (int, optional): Radius of the drawn keypoints. Default is 5.
             kpt_line (bool, optional): If True, the function will draw lines connecting keypoints
                                        for human pose. Default is True.
+            kpt_color (tuple, optional): The color of the keypoints (B, G, R).
 
         Note:
             `kpt_line=True` currently only supports human pose plotting.
@@ -391,7 +392,7 @@ class Annotator:
         is_pose = nkpt == 17 and ndim in {2, 3}
         kpt_line &= is_pose  # `kpt_line=True` for now only supports human pose plotting
         for i, k in enumerate(kpts):
-            color_k = [int(x) for x in self.kpt_color[i]] if is_pose else colors(i)
+            color_k = kpt_color or (self.kpt_color[i].tolist() if is_pose else colors(i))
             x_coord, y_coord = k[0], k[1]
             if x_coord % shape[1] != 0 and y_coord % shape[0] != 0:
                 if len(k) == 3:
@@ -414,7 +415,14 @@ class Annotator:
                     continue
                 if pos2[0] % shape[1] == 0 or pos2[1] % shape[0] == 0 or pos2[0] < 0 or pos2[1] < 0:
                     continue
-                cv2.line(self.im, pos1, pos2, [int(x) for x in self.limb_color[i]], thickness=2, lineType=cv2.LINE_AA)
+                cv2.line(
+                    self.im,
+                    pos1,
+                    pos2,
+                    kpt_color or self.limb_color[i].tolist(),
+                    thickness=2,
+                    lineType=cv2.LINE_AA,
+                )
         if self.pil:
             # Convert im back to PIL and update draw
             self.fromarray(self.im)

{ultralytics-8.2.76.dist-info → ultralytics-8.2.77.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: ultralytics
-Version: 8.2.76
+Version: 8.2.77
 Summary: Ultralytics YOLOv8 for SOTA object detection, multi-object tracking, instance segmentation, pose estimation and image classification.
 Author: Glenn Jocher, Ayush Chaurasia, Jing Qiu
 Maintainer: Glenn Jocher, Ayush Chaurasia, Jing Qiu
@@ -349,7 +349,7 @@ We love your input! YOLOv5 and YOLOv8 would not be possible without help from ou
 
 <!-- SVG image from https://opencollective.com/ultralytics/contributors.svg?width=990 -->
 
-<a href="https://github.com/ultralytics/yolov5/graphs/contributors">
+<a href="https://github.com/ultralytics/ultralytics/graphs/contributors">
 <img width="100%" src="https://github.com/ultralytics/assets/raw/main/im/image-contributors.png" alt="Ultralytics open-source contributors"></a>
 
 ## <div align="center">License</div>