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

ultralytics/solutions/config.py

@@ -1,37 +1,38 @@
 # Ultralytics 🚀 AGPL-3.0 License - https://ultralytics.com/license
 
+from __future__ import annotations
+
 from dataclasses import dataclass, field
-from typing import List, Optional, Tuple
+from typing import Any
 
 import cv2
 
 
 @dataclass
 class SolutionConfig:
-    """
-    Manages configuration parameters for Ultralytics Vision AI solutions.
+    """Manages configuration parameters for Ultralytics Vision AI solutions.
 
-    The SolutionConfig class serves as a centralized configuration container for all the
-    Ultralytics solution modules: https://docs.ultralytics.com/solutions/#solutions.
-    It leverages Python `dataclass` for clear, type-safe, and maintainable parameter definitions.
+    The SolutionConfig class serves as a centralized configuration container for all the Ultralytics solution modules:
+    https://docs.ultralytics.com/solutions/#solutions. It leverages Python `dataclass` for clear, type-safe, and
+    maintainable parameter definitions.
 
     Attributes:
-        source (Optional[str]): Path to the input source (video, RTSP, etc.). Only usable with Solutions CLI.
-        model (Optional[str]): Path to the Ultralytics YOLO model to be used for inference.
-        classes (Optional[List[int]]): List of class indices to filter detections.
+        source (str, optional): Path to the input source (video, RTSP, etc.). Only usable with Solutions CLI.
+        model (str, optional): Path to the Ultralytics YOLO model to be used for inference.
+        classes (list[int], optional): List of class indices to filter detections.
         show_conf (bool): Whether to show confidence scores on the visual output.
         show_labels (bool): Whether to display class labels on visual output.
-        region (Optional[List[Tuple[int, int]]]): Polygonal region or line for object counting.
-        colormap (Optional[int]): OpenCV colormap constant for visual overlays (e.g., cv2.COLORMAP_JET).
+        region (list[tuple[int, int]], optional): Polygonal region or line for object counting.
+        colormap (int, optional): OpenCV colormap constant for visual overlays (e.g., cv2.COLORMAP_JET).
         show_in (bool): Whether to display count number for objects entering the region.
         show_out (bool): Whether to display count number for objects leaving the region.
         up_angle (float): Upper angle threshold used in pose-based workouts monitoring.
         down_angle (int): Lower angle threshold used in pose-based workouts monitoring.
-        kpts (List[int]): Keypoint indices to monitor, e.g., for pose analytics.
+        kpts (list[int]): Keypoint indices to monitor, e.g., for pose analytics.
         analytics_type (str): Type of analytics to perform ("line", "area", "bar", "pie", etc.).
-        figsize (Optional[Tuple[int, int]]): Size of the matplotlib figure used for analytical plots (width, height).
+        figsize (tuple[int, int], optional): Size of the matplotlib figure used for analytical plots (width, height).
         blur_ratio (float): Ratio used to blur objects in the video frames (0.0 to 1.0).
-        vision_point (Tuple[int, int]): Reference point for directional tracking or perspective drawing.
+        vision_point (tuple[int, int]): Reference point for directional tracking or perspective drawing.
         crop_dir (str): Directory path to save cropped detection images.
         json_file (str): Path to a JSON file containing data for parking areas.
         line_width (int): Width for visual display i.e. bounding boxes, keypoints, counts.
@@ -43,7 +44,7 @@ class SolutionConfig:
         show (bool): Whether to display the visual output on screen.
         iou (float): Intersection-over-Union threshold for detection filtering.
         conf (float): Confidence threshold for keeping predictions.
-        device (Optional[str]): Device to run inference on (e.g., 'cpu', '0' for CUDA GPU).
+        device (str, optional): Device to run inference on (e.g., 'cpu', '0' for CUDA GPU).
         max_det (int): Maximum number of detections allowed per video frame.
         half (bool): Whether to use FP16 precision (requires a supported CUDA device).
         tracker (str): Path to tracking configuration YAML file (e.g., 'botsort.yaml').
@@ -60,22 +61,22 @@ class SolutionConfig:
         >>> print(cfg.model)
     """
 
-    source: Optional[str] = None
-    model: Optional[str] = None
-    classes: Optional[List[int]] = None
+    source: str | None = None
+    model: str | None = None
+    classes: list[int] | None = None
     show_conf: bool = True
     show_labels: bool = True
-    region: Optional[List[Tuple[int, int]]] = None
-    colormap: Optional[int] = cv2.COLORMAP_DEEPGREEN
+    region: list[tuple[int, int]] | None = None
+    colormap: int | None = cv2.COLORMAP_DEEPGREEN
     show_in: bool = True
     show_out: bool = True
     up_angle: float = 145.0
     down_angle: int = 90
-    kpts: List[int] = field(default_factory=lambda: [6, 8, 10])
+    kpts: list[int] = field(default_factory=lambda: [6, 8, 10])
     analytics_type: str = "line"
-    figsize: Optional[Tuple[int, int]] = (12.8, 7.2)
+    figsize: tuple[int, int] | None = (12.8, 7.2)
     blur_ratio: float = 0.5
-    vision_point: Tuple[int, int] = (20, 20)
+    vision_point: tuple[int, int] = (20, 20)
     crop_dir: str = "cropped-detections"
     json_file: str = None
     line_width: int = 2
@@ -87,20 +88,20 @@ class SolutionConfig:
     show: bool = False
     iou: float = 0.7
     conf: float = 0.25
-    device: Optional[str] = None
+    device: str | None = None
     max_det: int = 300
     half: bool = False
     tracker: str = "botsort.yaml"
     verbose: bool = True
     data: str = "images"
 
-    def update(self, **kwargs):
+    def update(self, **kwargs: Any):
         """Update configuration parameters with new values provided as keyword arguments."""
         for key, value in kwargs.items():
             if hasattr(self, key):
                 setattr(self, key, value)
             else:
-                raise ValueError(
-                    f"❌ {key} is not a valid solution argument, available arguments here: https://docs.ultralytics.com/solutions/#solutions-arguments"
-                )
+                url = "https://docs.ultralytics.com/solutions/#solutions-arguments"
+                raise ValueError(f"{key} is not a valid solution argument, see {url}")
+
         return self

ultralytics/solutions/distance_calculation.py

@@ -1,6 +1,7 @@
 # Ultralytics 🚀 AGPL-3.0 License - https://ultralytics.com/license
 
 import math
+from typing import Any
 
 import cv2
 
@@ -9,20 +10,19 @@ from ultralytics.utils.plotting import colors
 
 
 class DistanceCalculation(BaseSolution):
-    """
-    A class to calculate distance between two objects in a real-time video stream based on their tracks.
+    """A class to calculate distance between two objects in a real-time video stream based on their tracks.
 
-    This class extends BaseSolution to provide functionality for selecting objects and calculating the distance
-    between them in a video stream using YOLO object detection and tracking.
+    This class extends BaseSolution to provide functionality for selecting objects and calculating the distance between
+    them in a video stream using YOLO object detection and tracking.
 
     Attributes:
         left_mouse_count (int): Counter for left mouse button clicks.
-        selected_boxes (Dict[int, List[float]]): Dictionary to store selected bounding boxes and their track IDs.
-        centroids (List[List[int]]): List to store centroids of selected bounding boxes.
+        selected_boxes (dict[int, list[float]]): Dictionary to store selected bounding boxes and their track IDs.
+        centroids (list[list[int]]): List to store centroids of selected bounding boxes.
 
     Methods:
-        mouse_event_for_distance: Handles mouse events for selecting objects in the video stream.
-        process: Processes video frames and calculates the distance between selected objects.
+        mouse_event_for_distance: Handle mouse events for selecting objects in the video stream.
+        process: Process video frames and calculate the distance between selected objects.
 
     Examples:
         >>> distance_calc = DistanceCalculation()
@@ -32,18 +32,17 @@ class DistanceCalculation(BaseSolution):
         >>> cv2.waitKey(0)
     """
 
-    def __init__(self, **kwargs):
-        """Initializes the DistanceCalculation class for measuring object distances in video streams."""
+    def __init__(self, **kwargs: Any) -> None:
+        """Initialize the DistanceCalculation class for measuring object distances in video streams."""
         super().__init__(**kwargs)
 
         # Mouse event information
         self.left_mouse_count = 0
-        self.selected_boxes = {}
-        self.centroids = []  # Store centroids of selected objects
+        self.selected_boxes: dict[int, list[float]] = {}
+        self.centroids: list[list[int]] = []  # Store centroids of selected objects
 
-    def mouse_event_for_distance(self, event, x, y, flags, param):
-        """
-        Handles mouse events to select regions in a real-time video stream for distance calculation.
+    def mouse_event_for_distance(self, event: int, x: int, y: int, flags: int, param: Any) -> None:
+        """Handle mouse events to select regions in a real-time video stream for distance calculation.
 
         Args:
             event (int): Type of mouse event (e.g., cv2.EVENT_MOUSEMOVE, cv2.EVENT_LBUTTONDOWN).
@@ -67,19 +66,18 @@ class DistanceCalculation(BaseSolution):
             self.selected_boxes = {}
             self.left_mouse_count = 0
 
-    def process(self, im0):
-        """
-        Processes a video frame and calculates the distance between two selected bounding boxes.
+    def process(self, im0) -> SolutionResults:
+        """Process a video frame and calculate the distance between two selected bounding boxes.
 
-        This method extracts tracks from the input frame, annotates bounding boxes, and calculates the distance
-        between two user-selected objects if they have been chosen.
+        This method extracts tracks from the input frame, annotates bounding boxes, and calculates the distance between
+        two user-selected objects if they have been chosen.
 
         Args:
-            im0 (numpy.ndarray): The input image frame to process.
+            im0 (np.ndarray): The input image frame to process.
 
         Returns:
-            (SolutionResults): Contains processed image `plot_im`, `total_tracks` (int) representing the total number
-                of tracked objects, and `pixels_distance` (float) representing the distance between selected objects
+            (SolutionResults): Contains processed image `plot_im`, `total_tracks` (int) representing the total number of
+                tracked objects, and `pixels_distance` (float) representing the distance between selected objects
                 in pixels.
 
         Examples:
@@ -118,7 +116,8 @@ class DistanceCalculation(BaseSolution):
         self.centroids = []  # Reset centroids for next frame
         plot_im = annotator.result()
         self.display_output(plot_im)  # Display output with base class function
-        cv2.setMouseCallback("Ultralytics Solutions", self.mouse_event_for_distance)
+        if self.CFG.get("show") and self.env_check:
+            cv2.setMouseCallback("Ultralytics Solutions", self.mouse_event_for_distance)
 
         # Return SolutionResults with processed image and calculated metrics
         return SolutionResults(plot_im=plot_im, pixels_distance=pixels_distance, total_tracks=len(self.track_ids))

ultralytics/solutions/heatmap.py

@@ -1,5 +1,9 @@
 # Ultralytics 🚀 AGPL-3.0 License - https://ultralytics.com/license
 
+from __future__ import annotations
+
+from typing import Any
+
 import cv2
 import numpy as np
 
@@ -8,8 +12,7 @@ from ultralytics.solutions.solutions import SolutionAnnotator, SolutionResults
 
 
 class Heatmap(ObjectCounter):
-    """
-    A class to draw heatmaps in real-time video streams based on object tracks.
+    """A class to draw heatmaps in real-time video streams based on object tracks.
 
     This class extends the ObjectCounter class to generate and visualize heatmaps of object movements in video
     streams. It uses tracked object positions to create a cumulative heatmap effect over time.
@@ -31,9 +34,8 @@ class Heatmap(ObjectCounter):
         >>> processed_frame = heatmap.process(frame)
     """
 
-    def __init__(self, **kwargs):
-        """
-        Initialize the Heatmap class for real-time video stream heatmap generation based on object tracks.
+    def __init__(self, **kwargs: Any) -> None:
+        """Initialize the Heatmap class for real-time video stream heatmap generation based on object tracks.
 
         Args:
             **kwargs (Any): Keyword arguments passed to the parent ObjectCounter class.
@@ -48,12 +50,11 @@ class Heatmap(ObjectCounter):
         self.colormap = self.CFG["colormap"]
         self.heatmap = None
 
-    def heatmap_effect(self, box):
-        """
-        Efficiently calculate heatmap area and effect location for applying colormap.
+    def heatmap_effect(self, box: list[float]) -> None:
+        """Efficiently calculate heatmap area and effect location for applying colormap.
 
         Args:
-            box (List[float]): Bounding box coordinates [x0, y0, x1, y1].
+            box (list[float]): Bounding box coordinates [x0, y0, x1, y1].
         """
         x0, y0, x1, y1 = map(int, box)
         radius_squared = (min(x1 - x0, y1 - y0) // 2) ** 2
@@ -70,19 +71,16 @@ class Heatmap(ObjectCounter):
         # Update only the values within the bounding box in a single vectorized operation
         self.heatmap[y0:y1, x0:x1][within_radius] += 2
 
-    def process(self, im0):
-        """
-        Generate heatmap for each frame using Ultralytics.
+    def process(self, im0: np.ndarray) -> SolutionResults:
+        """Generate heatmap for each frame using Ultralytics tracking.
 
         Args:
             im0 (np.ndarray): Input image array for processing.
 
         Returns:
-            (SolutionResults): Contains processed image `plot_im`,
-                'in_count' (int, count of objects entering the region),
-                'out_count' (int, count of objects exiting the region),
-                'classwise_count' (dict, per-class object count), and
-                'total_tracks' (int, total number of tracked objects).
+            (SolutionResults): Contains processed image `plot_im`, 'in_count' (int, count of objects entering the
+                region), 'out_count' (int, count of objects exiting the region), 'classwise_count' (dict, per-class
+                object count), and 'total_tracks' (int, total number of tracked objects).
         """
         if not self.initialized:
             self.heatmap = np.zeros_like(im0, dtype=np.float32) * 0.99
@@ -110,7 +108,7 @@ class Heatmap(ObjectCounter):
             self.display_counts(plot_im)  # Display the counts on the frame
 
         # Normalize, apply colormap to heatmap and combine with original image
-        if self.track_data.id is not None:
+        if self.track_data.is_track:
             normalized_heatmap = cv2.normalize(self.heatmap, None, 0, 255, cv2.NORM_MINMAX).astype(np.uint8)
             colored_heatmap = cv2.applyColorMap(normalized_heatmap, self.colormap)
             plot_im = cv2.addWeighted(plot_im, 0.5, colored_heatmap, 0.5, 0)
@@ -122,6 +120,6 @@ class Heatmap(ObjectCounter):
             plot_im=plot_im,
             in_count=self.in_count,
             out_count=self.out_count,
-            classwise_count=dict(self.classwise_counts),
+            classwise_count=dict(self.classwise_count),
             total_tracks=len(self.track_ids),
         )

ultralytics/solutions/instance_segmentation.py

@@ -1,12 +1,13 @@
 # Ultralytics 🚀 AGPL-3.0 License - https://ultralytics.com/license
 
+from typing import Any
+
 from ultralytics.engine.results import Results
 from ultralytics.solutions.solutions import BaseSolution, SolutionResults
 
 
 class InstanceSegmentation(BaseSolution):
-    """
-    A class to manage instance segmentation in images or video streams.
+    """A class to manage instance segmentation in images or video streams.
 
     This class extends the BaseSolution class and provides functionality for performing instance segmentation, including
     drawing segmented masks with bounding boxes and labels.
@@ -14,10 +15,13 @@ class InstanceSegmentation(BaseSolution):
     Attributes:
         model (str): The segmentation model to use for inference.
         line_width (int): Width of the bounding box and text lines.
-        names (Dict[int, str]): Dictionary mapping class indices to class names.
-        clss (List[int]): List of detected class indices.
-        track_ids (List[int]): List of track IDs for detected instances.
-        masks (List[numpy.ndarray]): List of segmentation masks for detected instances.
+        names (dict[int, str]): Dictionary mapping class indices to class names.
+        clss (list[int]): List of detected class indices.
+        track_ids (list[int]): List of track IDs for detected instances.
+        masks (list[np.ndarray]): List of segmentation masks for detected instances.
+        show_conf (bool): Whether to display confidence scores.
+        show_labels (bool): Whether to display class labels.
+        show_boxes (bool): Whether to display bounding boxes.
 
     Methods:
         process: Process the input image to perform instance segmentation and annotate results.
@@ -26,17 +30,16 @@ class InstanceSegmentation(BaseSolution):
     Examples:
         >>> segmenter = InstanceSegmentation()
         >>> frame = cv2.imread("frame.jpg")
-        >>> results = segmenter.segment(frame)
-        >>> print(f"Total segmented instances: {results['total_tracks']}")
+        >>> results = segmenter.process(frame)
+        >>> print(f"Total segmented instances: {results.total_tracks}")
     """
 
-    def __init__(self, **kwargs):
-        """
-        Initialize the InstanceSegmentation class for detecting and annotating segmented instances.
+    def __init__(self, **kwargs: Any) -> None:
+        """Initialize the InstanceSegmentation class for detecting and annotating segmented instances.
 
         Args:
-            **kwargs (Any): Keyword arguments passed to the BaseSolution parent class.
-                model (str): Model name or path, defaults to "yolo11n-seg.pt".
+            **kwargs (Any): Keyword arguments passed to the BaseSolution parent class including:
+                - model (str): Model name or path, defaults to "yolo11n-seg.pt".
         """
         kwargs["model"] = kwargs.get("model", "yolo11n-seg.pt")
         super().__init__(**kwargs)
@@ -45,12 +48,11 @@ class InstanceSegmentation(BaseSolution):
         self.show_labels = self.CFG.get("show_labels", True)
         self.show_boxes = self.CFG.get("show_boxes", True)
 
-    def process(self, im0):
-        """
-        Perform instance segmentation on the input image and annotate the results.
+    def process(self, im0) -> SolutionResults:
+        """Perform instance segmentation on the input image and annotate the results.
 
         Args:
-            im0 (numpy.ndarray): The input image for segmentation.
+            im0 (np.ndarray): The input image for segmentation.
 
         Returns:
             (SolutionResults): Object containing the annotated image and total number of tracked instances.
@@ -58,11 +60,11 @@ class InstanceSegmentation(BaseSolution):
         Examples:
             >>> segmenter = InstanceSegmentation()
             >>> frame = cv2.imread("image.jpg")
-            >>> summary = segmenter.segment(frame)
+            >>> summary = segmenter.process(frame)
             >>> print(summary)
         """
         self.extract_tracks(im0)  # Extract tracks (bounding boxes, classes, and masks)
-        self.masks = getattr(self.tracks[0], "masks", None)
+        self.masks = getattr(self.tracks, "masks", None)
 
         # Iterate over detected classes, track IDs, and segmentation masks
         if self.masks is None:

ultralytics/solutions/object_blurrer.py

@@ -1,5 +1,7 @@
 # Ultralytics 🚀 AGPL-3.0 License - https://ultralytics.com/license
 
+from typing import Any
+
 import cv2
 
 from ultralytics.solutions.solutions import BaseSolution, SolutionAnnotator, SolutionResults
@@ -8,8 +10,7 @@ from ultralytics.utils.plotting import colors
 
 
 class ObjectBlurrer(BaseSolution):
-    """
-    A class to manage the blurring of detected objects in a real-time video stream.
+    """A class to manage the blurring of detected objects in a real-time video stream.
 
     This class extends the BaseSolution class and provides functionality for blurring objects based on detected bounding
     boxes. The blurred areas are updated directly in the input image, allowing for privacy preservation or other effects.
@@ -20,9 +21,9 @@ class ObjectBlurrer(BaseSolution):
         conf (float): Confidence threshold for object detection.
 
     Methods:
-        process: Applies a blurring effect to detected objects in the input image.
-        extract_tracks: Extracts tracking information from detected objects.
-        display_output: Displays the processed output image.
+        process: Apply a blurring effect to detected objects in the input image.
+        extract_tracks: Extract tracking information from detected objects.
+        display_output: Display the processed output image.
 
     Examples:
         >>> blurrer = ObjectBlurrer()
@@ -31,13 +32,12 @@ class ObjectBlurrer(BaseSolution):
         >>> print(f"Total blurred objects: {processed_results.total_tracks}")
     """
 
-    def __init__(self, **kwargs):
-        """
-        Initialize the ObjectBlurrer class for applying a blur effect to objects detected in video streams or images.
+    def __init__(self, **kwargs: Any) -> None:
+        """Initialize the ObjectBlurrer class for applying a blur effect to objects detected in video streams or images.
 
         Args:
-            **kwargs (Any): Keyword arguments passed to the parent class and for configuration.
-                blur_ratio (float): Intensity of the blur effect (0.1-1.0, default=0.5).
+            **kwargs (Any): Keyword arguments passed to the parent class and for configuration including:
+                - blur_ratio (float): Intensity of the blur effect (0.1-1.0, default=0.5).
         """
         super().__init__(**kwargs)
         blur_ratio = self.CFG["blur_ratio"]
@@ -46,19 +46,18 @@ class ObjectBlurrer(BaseSolution):
             blur_ratio = 0.5
         self.blur_ratio = int(blur_ratio * 100)
 
-    def process(self, im0):
-        """
-        Apply a blurring effect to detected objects in the input image.
+    def process(self, im0) -> SolutionResults:
+        """Apply a blurring effect to detected objects in the input image.
 
-        This method extracts tracking information, applies blur to regions corresponding to detected objects,
-        and annotates the image with bounding boxes.
+        This method extracts tracking information, applies blur to regions corresponding to detected objects, and
+        annotates the image with bounding boxes.
 
         Args:
-            im0 (numpy.ndarray): The input image containing detected objects.
+            im0 (np.ndarray): The input image containing detected objects.
 
         Returns:
             (SolutionResults): Object containing the processed image and number of tracked objects.
-                - plot_im (numpy.ndarray): The annotated output image with blurred objects.
+                - plot_im (np.ndarray): The annotated output image with blurred objects.
                 - total_tracks (int): The total number of tracked objects in the frame.
 
         Examples: