dgenerate-ultralytics-headless 8.3.137__py3-none-any.whl → 8.3.224__py3-none-any.whl

ultralytics/solutions/solutions.py

@@ -1,42 +1,67 @@
 # Ultralytics 🚀 AGPL-3.0 License - https://ultralytics.com/license
 
+from __future__ import annotations
+
 import math
-from collections import defaultdict
+from collections import Counter, defaultdict
+from functools import lru_cache
+from typing import Any
 
 import cv2
 import numpy as np
 
 from ultralytics import YOLO
 from ultralytics.solutions.config import SolutionConfig
-from ultralytics.utils import ASSETS_URL, LOGGER
+from ultralytics.utils import ASSETS_URL, LOGGER, ops
 from ultralytics.utils.checks import check_imshow, check_requirements
 from ultralytics.utils.plotting import Annotator
 
 
 class BaseSolution:
-    """
-    A base class for managing Ultralytics Solutions.
+    """A base class for managing Ultralytics Solutions.
 
     This class provides core functionality for various Ultralytics Solutions, including model loading, object tracking,
-    and region initialization.
+    and region initialization. It serves as the foundation for implementing specific computer vision solutions such as
+    object counting, pose estimation, and analytics.
 
     Attributes:
-        LineString (shapely.geometry.LineString): Class for creating line string geometries.
-        Polygon (shapely.geometry.Polygon): Class for creating polygon geometries.
-        Point (shapely.geometry.Point): Class for creating point geometries.
-        CFG (dict): Configuration dictionary loaded from a YAML file and updated with kwargs.
-        region (List[Tuple[int, int]]): List of coordinate tuples defining a region of interest.
+        LineString: Class for creating line string geometries from shapely.
+        Polygon: Class for creating polygon geometries from shapely.
+        Point: Class for creating point geometries from shapely.
+        prep: Prepared geometry function from shapely for optimized spatial operations.
+        CFG (dict[str, Any]): Configuration dictionary loaded from YAML file and updated with kwargs.
+        LOGGER: Logger instance for solution-specific logging.
+        annotator: Annotator instance for drawing on images.
+        tracks: YOLO tracking results from the latest inference.
+        track_data: Extracted tracking data (boxes or OBB) from tracks.
+        boxes (list): Bounding box coordinates from tracking results.
+        clss (list[int]): Class indices from tracking results.
+        track_ids (list[int]): Track IDs from tracking results.
+        confs (list[float]): Confidence scores from tracking results.
+        track_line: Current track line for storing tracking history.
+        masks: Segmentation masks from tracking results.
+        r_s: Region or line geometry object for spatial operations.
+        frame_no (int): Current frame number for logging purposes.
+        region (list[tuple[int, int]]): List of coordinate tuples defining region of interest.
         line_width (int): Width of lines used in visualizations.
-        model (ultralytics.YOLO): Loaded YOLO model instance.
-        names (Dict[int, str]): Dictionary mapping class indices to class names.
-        env_check (bool): Flag indicating whether the environment supports image display.
-        track_history (collections.defaultdict): Dictionary to store tracking history for each object.
+        model (YOLO): Loaded YOLO model instance.
+        names (dict[int, str]): Dictionary mapping class indices to class names.
+        classes (list[int]): List of class indices to track.
+        show_conf (bool): Flag to show confidence scores in annotations.
+        show_labels (bool): Flag to show class labels in annotations.
+        device (str): Device for model inference.
+        track_add_args (dict[str, Any]): Additional arguments for tracking configuration.
+        env_check (bool): Flag indicating whether environment supports image display.
+        track_history (defaultdict): Dictionary storing tracking history for each object.
+        profilers (tuple): Profiler instances for performance monitoring.
 
     Methods:
-        extract_tracks: Apply object tracking and extract tracks from an input image.
-        store_tracking_history: Store object tracking history for a given track ID and bounding box.
-        initialize_region: Initialize the counting region and line segment based on configuration.
-        display_output: Display the results of processing, including showing frames or saving results.
+        adjust_box_label: Generate formatted label for bounding box.
+        extract_tracks: Apply object tracking and extract tracks from input image.
+        store_tracking_history: Store object tracking history for given track ID and bounding box.
+        initialize_region: Initialize counting region and line segment based on configuration.
+        display_output: Display processing results including frames or saved results.
+        process: Process method to be implemented by each Solution subclass.
 
     Examples:
         >>> solution = BaseSolution(model="yolo11n.pt", region=[(0, 0), (100, 0), (100, 100), (0, 100)])
@@ -46,87 +71,90 @@ class BaseSolution:
         >>> solution.display_output(image)
     """
 
-    def __init__(self, is_cli=False, **kwargs):
-        """
-        Initializes the BaseSolution class with configuration settings and the YOLO model.
+    def __init__(self, is_cli: bool = False, **kwargs: Any) -> None:
+        """Initialize the BaseSolution class with configuration settings and YOLO model.
 
         Args:
-            is_cli (bool): Enables CLI mode if set to True.
+            is_cli (bool): Enable CLI mode if set to True.
             **kwargs (Any): Additional configuration parameters that override defaults.
         """
         self.CFG = vars(SolutionConfig().update(**kwargs))
         self.LOGGER = LOGGER  # Store logger object to be used in multiple solution classes
 
-        if self.__class__.__name__ != "VisualAISearch":
-            check_requirements("shapely>=2.0.0")
-            from shapely.geometry import LineString, Point, Polygon
-            from shapely.prepared import prep
-
-            self.LineString = LineString
-            self.Polygon = Polygon
-            self.Point = Point
-            self.prep = prep
-            self.annotator = None  # Initialize annotator
-            self.tracks = None
-            self.track_data = None
-            self.boxes = []
-            self.clss = []
-            self.track_ids = []
-            self.track_line = None
-            self.masks = None
-            self.r_s = None
-
-            self.LOGGER.info(f"Ultralytics Solutions: ✅ {self.CFG}")
-            self.region = self.CFG["region"]  # Store region data for other classes usage
-            self.line_width = self.CFG["line_width"]
-
-            # Load Model and store additional information (classes, show_conf, show_label)
-            if self.CFG["model"] is None:
-                self.CFG["model"] = "yolo11n.pt"
-            self.model = YOLO(self.CFG["model"])
-            self.names = self.model.names
-            self.classes = self.CFG["classes"]
-            self.show_conf = self.CFG["show_conf"]
-            self.show_labels = self.CFG["show_labels"]
-
-            self.track_add_args = {  # Tracker additional arguments for advance configuration
-                k: self.CFG[k] for k in ["iou", "conf", "device", "max_det", "half", "tracker", "device", "verbose"]
-            }  # verbose must be passed to track method; setting it False in YOLO still logs the track information.
-
-            if is_cli and self.CFG["source"] is None:
-                d_s = "solutions_ci_demo.mp4" if "-pose" not in self.CFG["model"] else "solution_ci_pose_demo.mp4"
-                self.LOGGER.warning(f"source not provided. using default source {ASSETS_URL}/{d_s}")
-                from ultralytics.utils.downloads import safe_download
-
-                safe_download(f"{ASSETS_URL}/{d_s}")  # download source from ultralytics assets
-                self.CFG["source"] = d_s  # set default source
-
-            # Initialize environment and region setup
-            self.env_check = check_imshow(warn=True)
-            self.track_history = defaultdict(list)
-
-    def adjust_box_label(self, cls, conf, track_id=None):
-        """
-        Generates a formatted label for a bounding box.
+        check_requirements("shapely>=2.0.0")
+        from shapely.geometry import LineString, Point, Polygon
+        from shapely.prepared import prep
+
+        self.LineString = LineString
+        self.Polygon = Polygon
+        self.Point = Point
+        self.prep = prep
+        self.annotator = None  # Initialize annotator
+        self.tracks = None
+        self.track_data = None
+        self.boxes = []
+        self.clss = []
+        self.track_ids = []
+        self.track_line = None
+        self.masks = None
+        self.r_s = None
+        self.frame_no = -1  # Only for logging
+
+        self.LOGGER.info(f"Ultralytics Solutions: ✅ {self.CFG}")
+        self.region = self.CFG["region"]  # Store region data for other classes usage
+        self.line_width = self.CFG["line_width"]
+
+        # Load Model and store additional information (classes, show_conf, show_label)
+        if self.CFG["model"] is None:
+            self.CFG["model"] = "yolo11n.pt"
+        self.model = YOLO(self.CFG["model"])
+        self.names = self.model.names
+        self.classes = self.CFG["classes"]
+        self.show_conf = self.CFG["show_conf"]
+        self.show_labels = self.CFG["show_labels"]
+        self.device = self.CFG["device"]
+
+        self.track_add_args = {  # Tracker additional arguments for advance configuration
+            k: self.CFG[k] for k in {"iou", "conf", "device", "max_det", "half", "tracker"}
+        }  # verbose must be passed to track method; setting it False in YOLO still logs the track information.
+
+        if is_cli and self.CFG["source"] is None:
+            d_s = "solutions_ci_demo.mp4" if "-pose" not in self.CFG["model"] else "solution_ci_pose_demo.mp4"
+            self.LOGGER.warning(f"source not provided. using default source {ASSETS_URL}/{d_s}")
+            from ultralytics.utils.downloads import safe_download
+
+            safe_download(f"{ASSETS_URL}/{d_s}")  # download source from ultralytics assets
+            self.CFG["source"] = d_s  # set default source
+
+        # Initialize environment and region setup
+        self.env_check = check_imshow(warn=True)
+        self.track_history = defaultdict(list)
+
+        self.profilers = (
+            ops.Profile(device=self.device),  # track
+            ops.Profile(device=self.device),  # solution
+        )
 
-        This method constructs a label string for a bounding box using the class index and confidence score.
-        Optionally includes the track ID if provided. The label format adapts based on the display settings
-        defined in `self.show_conf` and `self.show_labels`.
+    def adjust_box_label(self, cls: int, conf: float, track_id: int | None = None) -> str | None:
+        """Generate a formatted label for a bounding box.
+
+        This method constructs a label string for a bounding box using the class index and confidence score. Optionally
+        includes the track ID if provided. The label format adapts based on the display settings defined in
+        `self.show_conf` and `self.show_labels`.
 
         Args:
             cls (int): The class index of the detected object.
             conf (float): The confidence score of the detection.
-            track_id (int, optional): The unique identifier for the tracked object. Defaults to None.
+            track_id (int, optional): The unique identifier for the tracked object.
 
         Returns:
-            (str or None): The formatted label string if `self.show_labels` is True; otherwise, None.
+            (str | None): The formatted label string if `self.show_labels` is True; otherwise, None.
         """
         name = ("" if track_id is None else f"{track_id} ") + self.names[cls]
         return (f"{name} {conf:.2f}" if self.show_conf else name) if self.show_labels else None
 
-    def extract_tracks(self, im0):
-        """
-        Applies object tracking and extracts tracks from an input image or frame.
+    def extract_tracks(self, im0: np.ndarray) -> None:
+        """Apply object tracking and extract tracks from an input image or frame.
 
         Args:
             im0 (np.ndarray): The input image or frame.
@@ -136,11 +164,15 @@ class BaseSolution:
             >>> frame = cv2.imread("path/to/image.jpg")
             >>> solution.extract_tracks(frame)
         """
-        self.tracks = self.model.track(source=im0, persist=True, classes=self.classes, **self.track_add_args)
-        self.track_data = self.tracks[0].obb or self.tracks[0].boxes  # Extract tracks for OBB or object detection
+        with self.profilers[0]:
+            self.tracks = self.model.track(
+                source=im0, persist=True, classes=self.classes, verbose=False, **self.track_add_args
+            )[0]
+        is_obb = self.tracks.obb is not None
+        self.track_data = self.tracks.obb if is_obb else self.tracks.boxes  # Extract tracks for OBB or object detection
 
-        if self.track_data and self.track_data.id is not None:
-            self.boxes = self.track_data.xyxy.cpu()
+        if self.track_data and self.track_data.is_track:
+            self.boxes = (self.track_data.xyxyxyxy if is_obb else self.track_data.xyxy).cpu()
             self.clss = self.track_data.cls.cpu().tolist()
             self.track_ids = self.track_data.id.int().cpu().tolist()
             self.confs = self.track_data.conf.cpu().tolist()
@@ -148,17 +180,15 @@ class BaseSolution:
             self.LOGGER.warning("no tracks found!")
             self.boxes, self.clss, self.track_ids, self.confs = [], [], [], []
 
-    def store_tracking_history(self, track_id, box, is_obb=False):
-        """
-        Stores the tracking history of an object.
+    def store_tracking_history(self, track_id: int, box) -> None:
+        """Store the tracking history of an object.
 
-        This method updates the tracking history for a given object by appending the center point of its
-        bounding box to the track line. It maintains a maximum of 30 points in the tracking history.
+        This method updates the tracking history for a given object by appending the center point of its bounding box to
+        the track line. It maintains a maximum of 30 points in the tracking history.
 
         Args:
             track_id (int): The unique identifier for the tracked object.
-            box (List[float]): The bounding box coordinates of the object in the format [x1, y1, x2, y2].
-            is_obb (bool): True if OBB model is used (applies to object counting only).
+            box (list[float]): The bounding box coordinates of the object in the format [x1, y1, x2, y2].
 
         Examples:
             >>> solution = BaseSolution()
@@ -166,11 +196,11 @@ class BaseSolution:
         """
         # Store tracking history
         self.track_line = self.track_history[track_id]
-        self.track_line.append(tuple(box.mean(dim=0)) if is_obb else (box[:4:2].mean(), box[1:4:2].mean()))
+        self.track_line.append(tuple(box.mean(dim=0)) if box.numel() > 4 else (box[:4:2].mean(), box[1:4:2].mean()))
         if len(self.track_line) > 30:
             self.track_line.pop(0)
 
-    def initialize_region(self):
+    def initialize_region(self) -> None:
         """Initialize the counting region and line segment based on configuration settings."""
         if self.region is None:
             self.region = [(10, 200), (540, 200), (540, 180), (10, 180)]
@@ -178,15 +208,15 @@ class BaseSolution:
             self.Polygon(self.region) if len(self.region) >= 3 else self.LineString(self.region)
         )  # region or line
 
-    def display_output(self, plot_im):
-        """
-        Display the results of the processing, which could involve showing frames, printing counts, or saving results.
+    def display_output(self, plot_im: np.ndarray) -> None:
+        """Display the results of the processing, which could involve showing frames, printing counts, or saving
+        results.
 
         This method is responsible for visualizing the output of the object detection and tracking process. It displays
         the processed frame with annotations, and allows for user interaction to close the display.
 
         Args:
-            plot_im (numpy.ndarray): The image or frame that has been processed and annotated.
+            plot_im (np.ndarray): The image or frame that has been processed and annotated.
 
         Examples:
             >>> solution = BaseSolution()
@@ -204,24 +234,36 @@ class BaseSolution:
                 cv2.destroyAllWindows()  # Closes current frame window
                 return
 
-    def process(self, *args, **kwargs):
+    def process(self, *args: Any, **kwargs: Any):
         """Process method should be implemented by each Solution subclass."""
 
-    def __call__(self, *args, **kwargs):
+    def __call__(self, *args: Any, **kwargs: Any):
         """Allow instances to be called like a function with flexible arguments."""
-        result = self.process(*args, **kwargs)  # Call the subclass-specific process method
-        if self.CFG["verbose"]:  # extract verbose value to display the output logs if True
-            LOGGER.info(f"🚀 Results: {result}")
+        with self.profilers[1]:
+            result = self.process(*args, **kwargs)  # Call the subclass-specific process method
+        track_or_predict = "predict" if type(self).__name__ == "ObjectCropper" else "track"
+        track_or_predict_speed = self.profilers[0].dt * 1e3
+        solution_speed = (self.profilers[1].dt - self.profilers[0].dt) * 1e3  # solution time = process - track
+        result.speed = {track_or_predict: track_or_predict_speed, "solution": solution_speed}
+        if self.CFG["verbose"]:
+            self.frame_no += 1
+            counts = Counter(self.clss)  # Only for logging.
+            LOGGER.info(
+                f"{self.frame_no}: {result.plot_im.shape[0]}x{result.plot_im.shape[1]} {solution_speed:.1f}ms,"
+                f" {', '.join([f'{v} {self.names[k]}' for k, v in counts.items()])}\n"
+                f"Speed: {track_or_predict_speed:.1f}ms {track_or_predict}, "
+                f"{solution_speed:.1f}ms solution per image at shape "
+                f"(1, {getattr(self.model, 'ch', 3)}, {result.plot_im.shape[0]}, {result.plot_im.shape[1]})\n"
+            )
         return result
 
 
 class SolutionAnnotator(Annotator):
-    """
-    A specialized annotator class for visualizing and analyzing computer vision tasks.
+    """A specialized annotator class for visualizing and analyzing computer vision tasks.
 
     This class extends the base Annotator class, providing additional methods for drawing regions, centroids, tracking
-    trails, and visual annotations for Ultralytics Solutions: https://docs.ultralytics.com/solutions/.
-    and parking management.
+    trails, and visual annotations for Ultralytics Solutions. It offers comprehensive visualization capabilities for
+    various computer vision applications including object detection, tracking, pose estimation, and analytics.
 
     Attributes:
         im (np.ndarray): The image being annotated.
@@ -232,19 +274,18 @@ class SolutionAnnotator(Annotator):
         example (str): An example attribute for demonstration purposes.
 
     Methods:
-        draw_region: Draws a region using specified points, colors, and thickness.
-        queue_counts_display: Displays queue counts in the specified region.
-        display_analytics: Displays overall statistics for parking lot management.
-        estimate_pose_angle: Calculates the angle between three points in an object pose.
-        draw_specific_points: Draws specific keypoints on the image.
-        plot_workout_information: Draws a labeled text box on the image.
-        plot_angle_and_count_and_stage: Visualizes angle, step count, and stage for workout monitoring.
-        plot_distance_and_line: Displays the distance between centroids and connects them with a line.
-        display_objects_labels: Annotates bounding boxes with object class labels.
-        sweep_annotator: Visualizes a vertical sweep line and optional label.
-        visioneye: Maps and connects object centroids to a visual "eye" point.
-        circle_label: Draws a circular label within a bounding box.
-        text_label: Draws a rectangular label within a bounding box.
+        draw_region: Draw a region using specified points, colors, and thickness.
+        queue_counts_display: Display queue counts in the specified region.
+        display_analytics: Display overall statistics for parking lot management.
+        estimate_pose_angle: Calculate the angle between three points in an object pose.
+        draw_specific_kpts: Draw specific keypoints on the image.
+        plot_workout_information: Draw a labeled text box on the image.
+        plot_angle_and_count_and_stage: Visualize angle, step count, and stage for workout monitoring.
+        plot_distance_and_line: Display the distance between centroids and connect them with a line.
+        display_objects_labels: Annotate bounding boxes with object class labels.
+        sweep_annotator: Visualize a vertical sweep line and optional label.
+        visioneye: Map and connect object centroids to a visual "eye" point.
+        adaptive_label: Draw a circular or rectangle background shape label in center of a bounding box.
 
     Examples:
         >>> annotator = SolutionAnnotator(image)
@@ -254,27 +295,38 @@ class SolutionAnnotator(Annotator):
         ... )
     """
 
-    def __init__(self, im, line_width=None, font_size=None, font="Arial.ttf", pil=False, example="abc"):
-        """
-        Initializes the SolutionAnnotator class with an image for annotation.
+    def __init__(
+        self,
+        im: np.ndarray,
+        line_width: int | None = None,
+        font_size: int | None = None,
+        font: str = "Arial.ttf",
+        pil: bool = False,
+        example: str = "abc",
+    ):
+        """Initialize the SolutionAnnotator class with an image for annotation.
 
         Args:
             im (np.ndarray): The image to be annotated.
             line_width (int, optional): Line thickness for drawing on the image.
             font_size (int, optional): Font size for text annotations.
-            font (str, optional): Path to the font file.
-            pil (bool, optional): Indicates whether to use PIL for rendering text.
-            example (str, optional): An example parameter for demonstration purposes.
+            font (str): Path to the font file.
+            pil (bool): Indicates whether to use PIL for rendering text.
+            example (str): An example parameter for demonstration purposes.
         """
         super().__init__(im, line_width, font_size, font, pil, example)
 
-    def draw_region(self, reg_pts=None, color=(0, 255, 0), thickness=5):
-        """
-        Draw a region or line on the image.
+    def draw_region(
+        self,
+        reg_pts: list[tuple[int, int]] | None = None,
+        color: tuple[int, int, int] = (0, 255, 0),
+        thickness: int = 5,
+    ):
+        """Draw a region or line on the image.
 
         Args:
-            reg_pts (List[Tuple[int, int]]): Region points (for line 2 points, for region 4+ points).
-            color (Tuple[int, int, int]): RGB color value for the region.
+            reg_pts (list[tuple[int, int]], optional): Region points (for line 2 points, for region 4+ points).
+            color (tuple[int, int, int]): RGB color value for the region.
             thickness (int): Line thickness for drawing the region.
         """
         cv2.polylines(self.im, [np.array(reg_pts, dtype=np.int32)], isClosed=True, color=color, thickness=thickness)
@@ -283,15 +335,20 @@ class SolutionAnnotator(Annotator):
         for point in reg_pts:
             cv2.circle(self.im, (point[0], point[1]), thickness * 2, color, -1)  # -1 fills the circle
 
-    def queue_counts_display(self, label, points=None, region_color=(255, 255, 255), txt_color=(0, 0, 0)):
-        """
-        Displays queue counts on an image centered at the points with customizable font size and colors.
+    def queue_counts_display(
+        self,
+        label: str,
+        points: list[tuple[int, int]] | None = None,
+        region_color: tuple[int, int, int] = (255, 255, 255),
+        txt_color: tuple[int, int, int] = (0, 0, 0),
+    ):
+        """Display queue counts on an image centered at the points with customizable font size and colors.
 
         Args:
             label (str): Queue counts label.
-            points (List[Tuple[int, int]]): Region points for center point calculation to display text.
-            region_color (Tuple[int, int, int]): RGB queue region color.
-            txt_color (Tuple[int, int, int]): RGB text display color.
+            points (list[tuple[int, int]], optional): Region points for center point calculation to display text.
+            region_color (tuple[int, int, int]): RGB queue region color.
+            txt_color (tuple[int, int, int]): RGB text display color.
         """
         x_values = [point[0] for point in points]
         y_values = [point[1] for point in points]
@@ -323,15 +380,21 @@ class SolutionAnnotator(Annotator):
             lineType=cv2.LINE_AA,
         )
 
-    def display_analytics(self, im0, text, txt_color, bg_color, margin):
-        """
-        Display the overall statistics for parking lots, object counter etc.
+    def display_analytics(
+        self,
+        im0: np.ndarray,
+        text: dict[str, Any],
+        txt_color: tuple[int, int, int],
+        bg_color: tuple[int, int, int],
+        margin: int,
+    ):
+        """Display the overall statistics for parking lots, object counter etc.
 
         Args:
             im0 (np.ndarray): Inference image.
-            text (Dict[str, Any]): Labels dictionary.
-            txt_color (Tuple[int, int, int]): Display color for text foreground.
-            bg_color (Tuple[int, int, int]): Display color for text background.
+            text (dict[str, Any]): Labels dictionary.
+            txt_color (tuple[int, int, int]): Display color for text foreground.
+            bg_color (tuple[int, int, int]): Display color for text background.
             margin (int): Gap between text and rectangle for better display.
         """
         horizontal_gap = int(im0.shape[1] * 0.02)
@@ -353,14 +416,14 @@ class SolutionAnnotator(Annotator):
             text_y_offset = rect_y2
 
     @staticmethod
-    def estimate_pose_angle(a, b, c):
-        """
-        Calculate the angle between three points for workout monitoring.
+    @lru_cache(maxsize=256)
+    def estimate_pose_angle(a: list[float], b: list[float], c: list[float]) -> float:
+        """Calculate the angle between three points for workout monitoring.
 
         Args:
-            a (List[float]): The coordinates of the first point.
-            b (List[float]): The coordinates of the second point (vertex).
-            c (List[float]): The coordinates of the third point.
+            a (list[float]): The coordinates of the first point.
+            b (list[float]): The coordinates of the second point (vertex).
+            c (list[float]): The coordinates of the third point.
 
         Returns:
             (float): The angle in degrees between the three points.
@@ -369,20 +432,25 @@ class SolutionAnnotator(Annotator):
         angle = abs(radians * 180.0 / math.pi)
         return angle if angle <= 180.0 else (360 - angle)
 
-    def draw_specific_kpts(self, keypoints, indices=None, radius=2, conf_thresh=0.25):
-        """
-        Draw specific keypoints for gym steps counting.
+    def draw_specific_kpts(
+        self,
+        keypoints: list[list[float]],
+        indices: list[int] | None = None,
+        radius: int = 2,
+        conf_thresh: float = 0.25,
+    ) -> np.ndarray:
+        """Draw specific keypoints for gym steps counting.
 
         Args:
-            keypoints (List[List[float]]): Keypoints data to be plotted, each in format [x, y, confidence].
-            indices (List[int], optional): Keypoint indices to be plotted.
-            radius (int, optional): Keypoint radius.
-            conf_thresh (float, optional): Confidence threshold for keypoints.
+            keypoints (list[list[float]]): Keypoints data to be plotted, each in format [x, y, confidence].
+            indices (list[int], optional): Keypoint indices to be plotted.
+            radius (int): Keypoint radius.
+            conf_thresh (float): Confidence threshold for keypoints.
 
         Returns:
             (np.ndarray): Image with drawn keypoints.
 
-        Note:
+        Notes:
             Keypoint format: [x, y] or [x, y, confidence].
             Modifies self.im in-place.
         """
@@ -399,20 +467,25 @@ class SolutionAnnotator(Annotator):
 
         return self.im
 
-    def plot_workout_information(self, display_text, position, color=(104, 31, 17), txt_color=(255, 255, 255)):
-        """
-        Draw workout text with a background on the image.
+    def plot_workout_information(
+        self,
+        display_text: str,
+        position: tuple[int, int],
+        color: tuple[int, int, int] = (104, 31, 17),
+        txt_color: tuple[int, int, int] = (255, 255, 255),
+    ) -> int:
+        """Draw workout text with a background on the image.
 
         Args:
             display_text (str): The text to be displayed.
-            position (Tuple[int, int]): Coordinates (x, y) on the image where the text will be placed.
-            color (Tuple[int, int, int], optional): Text background color.
-            txt_color (Tuple[int, int, int], optional): Text foreground color.
+            position (tuple[int, int]): Coordinates (x, y) on the image where the text will be placed.
+            color (tuple[int, int, int]): Text background color.
+            txt_color (tuple[int, int, int]): Text foreground color.
 
         Returns:
             (int): The height of the text.
         """
-        (text_width, text_height), _ = cv2.getTextSize(display_text, 0, self.sf, self.tf)
+        (text_width, text_height), _ = cv2.getTextSize(display_text, 0, fontScale=self.sf, thickness=self.tf)
 
         # Draw background rectangle
         cv2.rectangle(
@@ -428,18 +501,23 @@ class SolutionAnnotator(Annotator):
         return text_height
 
     def plot_angle_and_count_and_stage(
-        self, angle_text, count_text, stage_text, center_kpt, color=(104, 31, 17), txt_color=(255, 255, 255)
+        self,
+        angle_text: str,
+        count_text: str,
+        stage_text: str,
+        center_kpt: list[int],
+        color: tuple[int, int, int] = (104, 31, 17),
+        txt_color: tuple[int, int, int] = (255, 255, 255),
     ):
-        """
-        Plot the pose angle, count value, and step stage for workout monitoring.
+        """Plot the pose angle, count value, and step stage for workout monitoring.
 
         Args:
             angle_text (str): Angle value for workout monitoring.
             count_text (str): Counts value for workout monitoring.
             stage_text (str): Stage decision for workout monitoring.
-            center_kpt (List[int]): Centroid pose index for workout monitoring.
-            color (Tuple[int, int, int], optional): Text background color.
-            txt_color (Tuple[int, int, int], optional): Text foreground color.
+            center_kpt (list[int]): Centroid pose index for workout monitoring.
+            color (tuple[int, int, int]): Text background color.
+            txt_color (tuple[int, int, int]): Text foreground color.
         """
         # Format text
         angle_text, count_text, stage_text = f" {angle_text:.2f}", f"Steps : {count_text}", f" {stage_text}"
@@ -456,16 +534,19 @@ class SolutionAnnotator(Annotator):
         )
 
     def plot_distance_and_line(
-        self, pixels_distance, centroids, line_color=(104, 31, 17), centroid_color=(255, 0, 255)
+        self,
+        pixels_distance: float,
+        centroids: list[tuple[int, int]],
+        line_color: tuple[int, int, int] = (104, 31, 17),
+        centroid_color: tuple[int, int, int] = (255, 0, 255),
     ):
-        """
-        Plot the distance and line between two centroids on the frame.
+        """Plot the distance and line between two centroids on the frame.
 
         Args:
             pixels_distance (float): Pixels distance between two bbox centroids.
-            centroids (List[Tuple[int, int]]): Bounding box centroids data.
-            line_color (Tuple[int, int, int], optional): Distance line color.
-            centroid_color (Tuple[int, int, int], optional): Bounding box centroid color.
+            centroids (list[tuple[int, int]]): Bounding box centroids data.
+            line_color (tuple[int, int, int]): Distance line color.
+            centroid_color (tuple[int, int, int]): Bounding box centroid color.
         """
         # Get the text size
         text = f"Pixels Distance: {pixels_distance:.2f}"
@@ -491,15 +572,23 @@ class SolutionAnnotator(Annotator):
         cv2.circle(self.im, centroids[0], 6, centroid_color, -1)
         cv2.circle(self.im, centroids[1], 6, centroid_color, -1)
 
-    def display_objects_labels(self, im0, text, txt_color, bg_color, x_center, y_center, margin):
-        """
-        Display the bounding boxes labels in parking management app.
+    def display_objects_labels(
+        self,
+        im0: np.ndarray,
+        text: str,
+        txt_color: tuple[int, int, int],
+        bg_color: tuple[int, int, int],
+        x_center: float,
+        y_center: float,
+        margin: int,
+    ):
+        """Display the bounding boxes labels in parking management app.
 
         Args:
             im0 (np.ndarray): Inference image.
             text (str): Object/class name.
-            txt_color (Tuple[int, int, int]): Display color for text foreground.
-            bg_color (Tuple[int, int, int]): Display color for text background.
+            txt_color (tuple[int, int, int]): Display color for text foreground.
+            bg_color (tuple[int, int, int]): Display color for text background.
             x_center (float): The x position center point for bounding box.
             y_center (float): The y position center point for bounding box.
             margin (int): The gap between text and rectangle for better display.
@@ -531,16 +620,22 @@ class SolutionAnnotator(Annotator):
             lineType=cv2.LINE_AA,
         )
 
-    def sweep_annotator(self, line_x=0, line_y=0, label=None, color=(221, 0, 186), txt_color=(255, 255, 255)):
-        """
-        Draw a sweep annotation line and an optional label.
+    def sweep_annotator(
+        self,
+        line_x: int = 0,
+        line_y: int = 0,
+        label: str | None = None,
+        color: tuple[int, int, int] = (221, 0, 186),
+        txt_color: tuple[int, int, int] = (255, 255, 255),
+    ):
+        """Draw a sweep annotation line and an optional label.
 
         Args:
             line_x (int): The x-coordinate of the sweep line.
             line_y (int): The y-coordinate limit of the sweep line.
             label (str, optional): Text label to be drawn in center of sweep line. If None, no label is drawn.
-            color (Tuple[int, int, int]): RGB color for the line and label background.
-            txt_color (Tuple[int, int, int]): RGB color for the label text.
+            color (tuple[int, int, int]): RGB color for the line and label background.
+            txt_color (tuple[int, int, int]): RGB color for the label text.
         """
         # Draw the sweep line
         cv2.line(self.im, (line_x, 0), (line_x, line_y), color, self.tf * 2)
@@ -565,91 +660,77 @@ class SolutionAnnotator(Annotator):
                 self.tf,
             )
 
-    def visioneye(self, box, center_point, color=(235, 219, 11), pin_color=(255, 0, 255)):
-        """
-        Perform pinpoint human-vision eye mapping and plotting.
+    def visioneye(
+        self,
+        box: list[float],
+        center_point: tuple[int, int],
+        color: tuple[int, int, int] = (235, 219, 11),
+        pin_color: tuple[int, int, int] = (255, 0, 255),
+    ):
+        """Perform pinpoint human-vision eye mapping and plotting.
 
         Args:
-            box (List[float]): Bounding box coordinates in format [x1, y1, x2, y2].
-            center_point (Tuple[int, int]): Center point for vision eye view.
-            color (Tuple[int, int, int]): Object centroid and line color.
-            pin_color (Tuple[int, int, int]): Visioneye point color.
+            box (list[float]): Bounding box coordinates in format [x1, y1, x2, y2].
+            center_point (tuple[int, int]): Center point for vision eye view.
+            color (tuple[int, int, int]): Object centroid and line color.
+            pin_color (tuple[int, int, int]): Visioneye point color.
         """
         center_bbox = int((box[0] + box[2]) / 2), int((box[1] + box[3]) / 2)
         cv2.circle(self.im, center_point, self.tf * 2, pin_color, -1)
         cv2.circle(self.im, center_bbox, self.tf * 2, color, -1)
         cv2.line(self.im, center_point, center_bbox, color, self.tf)
 
-    def circle_label(self, box, label="", color=(128, 128, 128), txt_color=(255, 255, 255), margin=2):
-        """
-        Draw a label with a background circle centered within a given bounding box.
+    def adaptive_label(
+        self,
+        box: tuple[float, float, float, float],
+        label: str = "",
+        color: tuple[int, int, int] = (128, 128, 128),
+        txt_color: tuple[int, int, int] = (255, 255, 255),
+        shape: str = "rect",
+        margin: int = 5,
+    ):
+        """Draw a label with a background rectangle or circle centered within a given bounding box.
 
         Args:
-            box (Tuple[float, float, float, float]): The bounding box coordinates (x1, y1, x2, y2).
+            box (tuple[float, float, float, float]): The bounding box coordinates (x1, y1, x2, y2).
             label (str): The text label to be displayed.
-            color (Tuple[int, int, int]): The background color of the circle (B, G, R).
-            txt_color (Tuple[int, int, int]): The color of the text (R, G, B).
-            margin (int): The margin between the text and the circle border.
+            color (tuple[int, int, int]): The background color of the rectangle (B, G, R).
+            txt_color (tuple[int, int, int]): The color of the text (R, G, B).
+            shape (str): The shape of the label i.e "circle" or "rect"
+            margin (int): The margin between the text and the rectangle border.
         """
-        if len(label) > 3:
+        if shape == "circle" and len(label) > 3:
             LOGGER.warning(f"Length of label is {len(label)}, only first 3 letters will be used for circle annotation.")
             label = label[:3]
 
-        # Calculate the center of the box
-        x_center, y_center = int((box[0] + box[2]) / 2), int((box[1] + box[3]) / 2)
-        # Get the text size
-        text_size = cv2.getTextSize(str(label), cv2.FONT_HERSHEY_SIMPLEX, self.sf - 0.15, self.tf)[0]
-        # Calculate the required radius to fit the text with the margin
-        required_radius = int(((text_size[0] ** 2 + text_size[1] ** 2) ** 0.5) / 2) + margin
-        # Draw the circle with the required radius
-        cv2.circle(self.im, (x_center, y_center), required_radius, color, -1)
-        # Calculate the position for the text
-        text_x = x_center - text_size[0] // 2
-        text_y = y_center + text_size[1] // 2
-        # Draw the text
-        cv2.putText(
-            self.im,
-            str(label),
-            (text_x, text_y),
-            cv2.FONT_HERSHEY_SIMPLEX,
-            self.sf - 0.15,
-            self.get_txt_color(color, txt_color),
-            self.tf,
-            lineType=cv2.LINE_AA,
-        )
+        x_center, y_center = int((box[0] + box[2]) / 2), int((box[1] + box[3]) / 2)  # Calculate center of the bbox
+        text_size = cv2.getTextSize(label, cv2.FONT_HERSHEY_SIMPLEX, self.sf - 0.15, self.tf)[0]  # Get size of the text
+        text_x, text_y = x_center - text_size[0] // 2, y_center + text_size[1] // 2  # Calculate top-left corner of text
 
-    def text_label(self, box, label="", color=(128, 128, 128), txt_color=(255, 255, 255), margin=5):
-        """
-        Draw a label with a background rectangle centered within a given bounding box.
+        if shape == "circle":
+            cv2.circle(
+                self.im,
+                (x_center, y_center),
+                int(((text_size[0] ** 2 + text_size[1] ** 2) ** 0.5) / 2) + margin,  # Calculate the radius
+                color,
+                -1,
+            )
+        else:
+            cv2.rectangle(
+                self.im,
+                (text_x - margin, text_y - text_size[1] - margin),  # Calculate coordinates of the rectangle
+                (text_x + text_size[0] + margin, text_y + margin),  # Calculate coordinates of the rectangle
+                color,
+                -1,
+            )
 
-        Args:
-            box (Tuple[float, float, float, float]): The bounding box coordinates (x1, y1, x2, y2).
-            label (str): The text label to be displayed.
-            color (Tuple[int, int, int]): The background color of the rectangle (B, G, R).
-            txt_color (Tuple[int, int, int]): The color of the text (R, G, B).
-            margin (int): The margin between the text and the rectangle border.
-        """
-        # Calculate the center of the bounding box
-        x_center, y_center = int((box[0] + box[2]) / 2), int((box[1] + box[3]) / 2)
-        # Get the size of the text
-        text_size = cv2.getTextSize(label, cv2.FONT_HERSHEY_SIMPLEX, self.sf - 0.1, self.tf)[0]
-        # Calculate the top-left corner of the text (to center it)
-        text_x = x_center - text_size[0] // 2
-        text_y = y_center + text_size[1] // 2
-        # Calculate the coordinates of the background rectangle
-        rect_x1 = text_x - margin
-        rect_y1 = text_y - text_size[1] - margin
-        rect_x2 = text_x + text_size[0] + margin
-        rect_y2 = text_y + margin
-        # Draw the background rectangle
-        cv2.rectangle(self.im, (rect_x1, rect_y1), (rect_x2, rect_y2), color, -1)
         # Draw the text on top of the rectangle
         cv2.putText(
             self.im,
             label,
-            (text_x, text_y),
+            (text_x, text_y),  # Calculate top-left corner of the text
             cv2.FONT_HERSHEY_SIMPLEX,
-            self.sf - 0.1,
+            self.sf - 0.15,
             self.get_txt_color(color, txt_color),
             self.tf,
             lineType=cv2.LINE_AA,
@@ -657,17 +738,17 @@ class SolutionAnnotator(Annotator):
 
 
 class SolutionResults:
-    """
-    A class to encapsulate the results of Ultralytics Solutions.
+    """A class to encapsulate the results of Ultralytics Solutions.
 
     This class is designed to store and manage various outputs generated by the solution pipeline, including counts,
-    angles, and workout stages.
+    angles, workout stages, and other analytics data. It provides a structured way to access and manipulate results from
+    different computer vision solutions such as object counting, pose estimation, and tracking analytics.
 
     Attributes:
         plot_im (np.ndarray): Processed image with counts, blurred, or other effects from solutions.
         in_count (int): The total number of "in" counts in a video stream.
         out_count (int): The total number of "out" counts in a video stream.
-        classwise_count (Dict[str, int]): A dictionary containing counts of objects categorized by class.
+        classwise_count (dict[str, int]): A dictionary containing counts of objects categorized by class.
         queue_count (int): The count of objects in a queue or waiting area.
         workout_count (int): The count of workout repetitions.
         workout_angle (float): The angle calculated during a workout exercise.
@@ -677,14 +758,14 @@ class SolutionResults:
         filled_slots (int): The number of filled slots in a monitored area.
         email_sent (bool): A flag indicating whether an email notification was sent.
         total_tracks (int): The total number of tracked objects.
-        region_counts (dict): The count of objects within a specific region.
-        speed_dict (Dict[str, float]): A dictionary containing speed information for tracked objects.
+        region_counts (dict[str, int]): The count of objects within a specific region.
+        speed_dict (dict[str, float]): A dictionary containing speed information for tracked objects.
         total_crop_objects (int): Total number of cropped objects using ObjectCropper class.
+        speed (dict[str, float]): Performance timing information for tracking and solution processing.
     """
 
     def __init__(self, **kwargs):
-        """
-        Initialize a SolutionResults object with default or user-specified values.
+        """Initialize a SolutionResults object with default or user-specified values.
 
         Args:
             **kwargs (Any): Optional arguments to override default attribute values.
@@ -703,15 +784,15 @@ class SolutionResults:
         self.email_sent = False
         self.total_tracks = 0
         self.region_counts = {}
-        self.speed_dict = {}
+        self.speed_dict = {}  # for speed estimation
         self.total_crop_objects = 0
+        self.speed = {}
 
         # Override with user-defined values
         self.__dict__.update(kwargs)
 
-    def __str__(self):
-        """
-        Return a formatted string representation of the SolutionResults object.
+    def __str__(self) -> str:
+        """Return a formatted string representation of the SolutionResults object.
 
         Returns:
             (str): A string representation listing non-null attributes.
@@ -721,4 +802,4 @@ class SolutionResults:
             for k, v in self.__dict__.items()
             if k != "plot_im" and v not in [None, {}, 0, 0.0, False]  # Exclude `plot_im` explicitly
         }
-        return f"SolutionResults({', '.join(f'{k}={v}' for k, v in attrs.items())})"
+        return ", ".join(f"{k}={v}" for k, v in attrs.items())