eye-cv 1.0.0__py3-none-any.whl

eye/detection/tools/inference_slicer.py

@@ -0,0 +1,288 @@
+import warnings
+from concurrent.futures import ThreadPoolExecutor, as_completed
+from typing import Callable, Optional, Tuple, Union
+
+import numpy as np
+
+from eye.config import ORIENTED_BOX_COORDINATES
+from eye.detection.core import Detections
+from eye.detection.overlap_filter import OverlapFilter
+from eye.detection.utils import move_boxes, move_masks, move_oriented_boxes
+from eye.utils.image import crop_image
+from eye.utils.internal import (
+    EyeWarnings,
+    warn_deprecated,
+)
+
+
+def move_detections(
+    detections: Detections,
+    offset: np.ndarray,
+    resolution_wh: Optional[Tuple[int, int]] = None,
+) -> Detections:
+    """
+    Args:
+        detections (sv.Detections): Detections object to be moved.
+        offset (np.ndarray): An array of shape `(2,)` containing offset values in format
+            is `[dx, dy]`.
+        resolution_wh (Tuple[int, int]): The width and height of the desired mask
+            resolution. Required for segmentation detections.
+
+    Returns:
+        (sv.Detections) repositioned Detections object.
+    """
+    detections.xyxy = move_boxes(xyxy=detections.xyxy, offset=offset)
+    if ORIENTED_BOX_COORDINATES in detections.data:
+        detections.data[ORIENTED_BOX_COORDINATES] = move_oriented_boxes(
+            xyxyxyxy=detections.data[ORIENTED_BOX_COORDINATES], offset=offset
+        )
+    if detections.mask is not None:
+        if resolution_wh is None:
+            raise ValueError(
+                "Resolution width and height are required for moving segmentation "
+                "detections. This should be the same as (width, height) of image shape."
+            )
+        detections.mask = move_masks(
+            masks=detections.mask, offset=offset, resolution_wh=resolution_wh
+        )
+    return detections
+
+
+class InferenceSlicer:
+    """
+    InferenceSlicer performs slicing-based inference for small target detection. This
+    method, often referred to as
+    [Slicing Adaptive Inference (SAHI)](https://ieeexplore.ieee.org/document/9897990),
+    involves dividing a larger image into smaller slices, performing inference on each
+    slice, and then merging the detections.
+
+    Args:
+        slice_wh (Tuple[int, int]): Dimensions of each slice measured in pixels. The
+            tuple should be in the format `(width, height)`.
+        overlap_ratio_wh (Optional[Tuple[float, float]]): [⚠️ Deprecated: please set
+                to `None` and use `overlap_wh`] A tuple representing the
+            desired overlap ratio for width and height between consecutive slices.
+            Each value should be in the range [0, 1), where 0 means no overlap and
+            a value close to 1 means high overlap.
+        overlap_wh (Optional[Tuple[int, int]]): A tuple representing the desired
+            overlap for width and height between consecutive slices measured in pixels.
+            Each value should be greater than or equal to 0. Takes precedence over
+            `overlap_ratio_wh`.
+        overlap_filter (Union[OverlapFilter, str]): Strategy for
+            filtering or merging overlapping detections in slices.
+        iou_threshold (float): Intersection over Union (IoU) threshold
+            used when filtering by overlap.
+        callback (Callable): A function that performs inference on a given image
+            slice and returns detections.
+        thread_workers (int): Number of threads for parallel execution.
+
+    Note:
+        The class ensures that slices do not exceed the boundaries of the original
+        image. As a result, the final slices in the row and column dimensions might be
+        smaller than the specified slice dimensions if the image's width or height is
+        not a multiple of the slice's width or height minus the overlap.
+    """
+
+    def __init__(
+        self,
+        callback: Callable[[np.ndarray], Detections],
+        slice_wh: Tuple[int, int] = (320, 320),
+        overlap_ratio_wh: Optional[Tuple[float, float]] = (0.2, 0.2),
+        overlap_wh: Optional[Tuple[int, int]] = None,
+        overlap_filter: Union[OverlapFilter, str] = OverlapFilter.NON_MAX_SUPPRESSION,
+        iou_threshold: float = 0.5,
+        thread_workers: int = 1,
+    ):
+        if overlap_ratio_wh is not None:
+            warn_deprecated(
+                "`overlap_ratio_wh` in `InferenceSlicer.__init__` is deprecated and "
+                "will be removed in `eye-0.27.0`. Please manually set it to "
+                "`None` and use `overlap_wh` instead."
+            )
+
+        self._validate_overlap(overlap_ratio_wh, overlap_wh)
+        self.overlap_ratio_wh = overlap_ratio_wh
+        self.overlap_wh = overlap_wh
+
+        self.slice_wh = slice_wh
+        self.iou_threshold = iou_threshold
+        self.overlap_filter = OverlapFilter.from_value(overlap_filter)
+        self.callback = callback
+        self.thread_workers = thread_workers
+
+    def __call__(self, image: np.ndarray) -> Detections:
+        """
+        Performs slicing-based inference on the provided image using the specified
+            callback.
+
+        Args:
+            image (np.ndarray): The input image on which inference needs to be
+                performed. The image should be in the format
+                `(height, width, channels)`.
+
+        Returns:
+            Detections: A collection of detections for the entire image after merging
+                results from all slices and applying NMS.
+
+        Example:
+            ```python
+            import cv2
+            import eye as sv
+            from ultralytics import YOLO
+
+            image = cv2.imread(SOURCE_IMAGE_PATH)
+            model = YOLO(...)
+
+            def callback(image_slice: np.ndarray) -> sv.Detections:
+                result = model(image_slice)[0]
+                return sv.Detections.from_ultralytics(result)
+
+            slicer = sv.InferenceSlicer(
+                callback=callback,
+                overlap_filter_strategy=sv.OverlapFilter.NON_MAX_SUPPRESSION,
+            )
+
+            detections = slicer(image)
+            ```
+        """
+        detections_list = []
+        resolution_wh = (image.shape[1], image.shape[0])
+        offsets = self._generate_offset(
+            resolution_wh=resolution_wh,
+            slice_wh=self.slice_wh,
+            overlap_ratio_wh=self.overlap_ratio_wh,
+            overlap_wh=self.overlap_wh,
+        )
+
+        with ThreadPoolExecutor(max_workers=self.thread_workers) as executor:
+            futures = [
+                executor.submit(self._run_callback, image, offset) for offset in offsets
+            ]
+            for future in as_completed(futures):
+                detections_list.append(future.result())
+
+        merged = Detections.merge(detections_list=detections_list)
+        if self.overlap_filter == OverlapFilter.NONE:
+            return merged
+        elif self.overlap_filter == OverlapFilter.NON_MAX_SUPPRESSION:
+            return merged.with_nms(threshold=self.iou_threshold)
+        elif self.overlap_filter == OverlapFilter.NON_MAX_MERGE:
+            return merged.with_nmm(threshold=self.iou_threshold)
+        else:
+            warnings.warn(
+                f"Invalid overlap filter strategy: {self.overlap_filter}",
+                category=EyeWarnings,
+            )
+            return merged
+
+    def _run_callback(self, image, offset) -> Detections:
+        """
+        Run the provided callback on a slice of an image.
+
+        Args:
+            image (np.ndarray): The input image on which inference needs to run
+            offset (np.ndarray): An array of shape `(4,)` containing coordinates
+                for the slice.
+
+        Returns:
+            Detections: A collection of detections for the slice.
+        """
+        image_slice = crop_image(image=image, xyxy=offset)
+        detections = self.callback(image_slice)
+        resolution_wh = (image.shape[1], image.shape[0])
+        detections = move_detections(
+            detections=detections, offset=offset[:2], resolution_wh=resolution_wh
+        )
+
+        return detections
+
+    @staticmethod
+    def _generate_offset(
+        resolution_wh: Tuple[int, int],
+        slice_wh: Tuple[int, int],
+        overlap_ratio_wh: Optional[Tuple[float, float]],
+        overlap_wh: Optional[Tuple[int, int]],
+    ) -> np.ndarray:
+        """
+        Generate offset coordinates for slicing an image based on the given resolution,
+        slice dimensions, and overlap ratios.
+
+        Args:
+            resolution_wh (Tuple[int, int]): A tuple representing the width and height
+                of the image to be sliced.
+            slice_wh (Tuple[int, int]): Dimensions of each slice measured in pixels. The
+            tuple should be in the format `(width, height)`.
+            overlap_ratio_wh (Optional[Tuple[float, float]]): A tuple representing the
+                desired overlap ratio for width and height between consecutive slices.
+                Each value should be in the range [0, 1), where 0 means no overlap and
+                a value close to 1 means high overlap.
+            overlap_wh (Optional[Tuple[int, int]]): A tuple representing the desired
+                overlap for width and height between consecutive slices measured in
+                pixels. Each value should be greater than or equal to 0.
+
+        Returns:
+            np.ndarray: An array of shape `(n, 4)` containing coordinates for each
+                slice in the format `[xmin, ymin, xmax, ymax]`.
+
+        Note:
+            The function ensures that slices do not exceed the boundaries of the
+                original image. As a result, the final slices in the row and column
+                dimensions might be smaller than the specified slice dimensions if the
+                image's width or height is not a multiple of the slice's width or
+                height minus the overlap.
+        """
+        slice_width, slice_height = slice_wh
+        image_width, image_height = resolution_wh
+        overlap_width = (
+            overlap_wh[0]
+            if overlap_wh is not None
+            else int(overlap_ratio_wh[0] * slice_width)
+        )
+        overlap_height = (
+            overlap_wh[1]
+            if overlap_wh is not None
+            else int(overlap_ratio_wh[1] * slice_height)
+        )
+
+        width_stride = slice_width - overlap_width
+        height_stride = slice_height - overlap_height
+
+        ws = np.arange(0, image_width, width_stride)
+        hs = np.arange(0, image_height, height_stride)
+
+        xmin, ymin = np.meshgrid(ws, hs)
+        xmax = np.clip(xmin + slice_width, 0, image_width)
+        ymax = np.clip(ymin + slice_height, 0, image_height)
+
+        offsets = np.stack([xmin, ymin, xmax, ymax], axis=-1).reshape(-1, 4)
+
+        return offsets
+
+    @staticmethod
+    def _validate_overlap(
+        overlap_ratio_wh: Optional[Tuple[float, float]],
+        overlap_wh: Optional[Tuple[int, int]],
+    ) -> None:
+        if overlap_ratio_wh is not None and overlap_wh is not None:
+            raise ValueError(
+                "Both `overlap_ratio_wh` and `overlap_wh` cannot be provided. "
+                "Please provide only one of them."
+            )
+        if overlap_ratio_wh is None and overlap_wh is None:
+            raise ValueError(
+                "Either `overlap_ratio_wh` or `overlap_wh` must be provided. "
+                "Please provide one of them."
+            )
+
+        if overlap_ratio_wh is not None:
+            if not (0 <= overlap_ratio_wh[0] < 1 and 0 <= overlap_ratio_wh[1] < 1):
+                raise ValueError(
+                    "Overlap ratios must be in the range [0, 1). "
+                    f"Received: {overlap_ratio_wh}"
+                )
+        if overlap_wh is not None:
+            if not (overlap_wh[0] >= 0 and overlap_wh[1] >= 0):
+                raise ValueError(
+                    "Overlap values must be greater than or equal to 0. "
+                    f"Received: {overlap_wh}"
+                )

eye/detection/tools/json_sink.py

@@ -0,0 +1,142 @@
+from __future__ import annotations
+
+import json
+import os
+from typing import Any, Dict, List, Optional
+
+from eye.detection.core import Detections
+
+
+class JSONSink:
+    """
+    A utility class for saving detection data to a JSON file. This class is designed to
+    efficiently serialize detection objects into a JSON format, allowing for the
+    inclusion of bounding box coordinates and additional attributes like `confidence`,
+    `class_id`, and `tracker_id`.
+
+    !!! tip
+
+        JSONsink allow to pass custom data alongside the detection fields, providing
+        flexibility for logging various types of information.
+
+    Args:
+        file_name (str): The name of the JSON file where the detections will be stored.
+            Defaults to 'output.json'.
+
+    Example:
+        ```python
+        import eye as sv
+        from ultralytics import YOLO
+
+        model = YOLO(<SOURCE_MODEL_PATH>)
+        json_sink = sv.JSONSink(<RESULT_JSON_FILE_PATH>)
+        frames_generator = sv.get_video_frames_generator(<SOURCE_VIDEO_PATH>)
+
+        with json_sink as sink:
+            for frame in frames_generator:
+                result = model(frame)[0]
+                detections = sv.Detections.from_ultralytics(result)
+                sink.append(detections, custom_data={'<CUSTOM_LABEL>':'<CUSTOM_DATA>'})
+        ```
+    """
+
+    def __init__(self, file_name: str = "output.json") -> None:
+        """
+        Initialize the JSONSink instance.
+
+        Args:
+            file_name (str): The name of the JSON file.
+
+        Returns:
+            None
+        """
+        self.file_name = file_name
+        self.file: Optional[open] = None
+        self.data: List[Dict[str, Any]] = []
+
+    def __enter__(self) -> JSONSink:
+        self.open()
+        return self
+
+    def __exit__(
+        self,
+        exc_type: Optional[type],
+        exc_val: Optional[Exception],
+        exc_tb: Optional[Any],
+    ) -> None:
+        self.write_and_close()
+
+    def open(self) -> None:
+        """
+        Open the JSON file for writing.
+
+        Returns:
+            None
+        """
+        parent_directory = os.path.dirname(self.file_name)
+        if parent_directory and not os.path.exists(parent_directory):
+            os.makedirs(parent_directory)
+
+        self.file = open(self.file_name, "w")
+
+    def write_and_close(self) -> None:
+        """
+        Write and close the JSON file.
+
+        Returns:
+            None
+        """
+        if self.file:
+            json.dump(self.data, self.file, indent=4)
+            self.file.close()
+
+    @staticmethod
+    def parse_detection_data(
+        detections: Detections, custom_data: Optional[Dict[str, Any]] = None
+    ) -> List[Dict[str, Any]]:
+        parsed_rows = []
+        for i in range(len(detections.xyxy)):
+            row = {
+                "x_min": float(detections.xyxy[i][0]),
+                "y_min": float(detections.xyxy[i][1]),
+                "x_max": float(detections.xyxy[i][2]),
+                "y_max": float(detections.xyxy[i][3]),
+                "class_id": ""
+                if detections.class_id is None
+                else int(detections.class_id[i]),
+                "confidence": ""
+                if detections.confidence is None
+                else float(detections.confidence[i]),
+                "tracker_id": ""
+                if detections.tracker_id is None
+                else int(detections.tracker_id[i]),
+            }
+
+            if hasattr(detections, "data"):
+                for key, value in detections.data.items():
+                    row[key] = (
+                        str(value[i])
+                        if hasattr(value, "__getitem__") and value.ndim != 0
+                        else str(value)
+                    )
+
+            if custom_data:
+                row.update(custom_data)
+            parsed_rows.append(row)
+        return parsed_rows
+
+    def append(
+        self, detections: Detections, custom_data: Optional[Dict[str, Any]] = None
+    ) -> None:
+        """
+        Append detection data to the JSON file.
+
+        Args:
+            detections (Detections): The detection data.
+            custom_data (Dict[str, Any]): Custom data to include.
+
+        Returns:
+            None
+        """
+        parsed_rows = JSONSink.parse_detection_data(detections, custom_data)
+        self.data.extend(parsed_rows)

eye/detection/tools/polygon_zone.py

@@ -0,0 +1,202 @@
+from dataclasses import replace
+from typing import Iterable, Optional
+
+import cv2
+import numpy as np
+import numpy.typing as npt
+
+from eye import Detections
+from eye.detection.utils import clip_boxes, polygon_to_mask
+from eye.draw.color import Color
+from eye.draw.utils import draw_filled_polygon, draw_polygon, draw_text
+from eye.geometry.core import Position
+from eye.geometry.utils import get_polygon_center
+
+
+class PolygonZone:
+    """
+    A class for defining a polygon-shaped zone within a frame for detecting objects.
+
+    !!! warning
+
+        PolygonZone uses the `tracker_id`. Read
+        [here](/latest/trackers/) to learn how to plug
+        tracking into your inference pipeline.
+
+    Attributes:
+        polygon (np.ndarray): A polygon represented by a numpy array of shape
+            `(N, 2)`, containing the `x`, `y` coordinates of the points.
+        triggering_anchors (Iterable[sv.Position]): A list of positions specifying
+            which anchors of the detections bounding box to consider when deciding on
+            whether the detection fits within the PolygonZone
+            (default: (sv.Position.BOTTOM_CENTER,)).
+        current_count (int): The current count of detected objects within the zone
+        mask (np.ndarray): The 2D bool mask for the polygon zone
+
+    Example:
+        ```python
+        import eye as sv
+        from ultralytics import YOLO
+        import numpy as np
+        import cv2
+
+        image = cv2.imread(<SOURCE_IMAGE_PATH>)
+        model = YOLO("yolo11s")
+        tracker = sv.ByteTrack()
+
+        polygon = np.array([[100, 200], [200, 100], [300, 200], [200, 300]])
+        polygon_zone = sv.PolygonZone(polygon=polygon)
+
+        result = model.infer(image)[0]
+        detections = sv.Detections.from_ultralytics(result)
+        detections = tracker.update_with_detections(detections)
+
+        is_detections_in_zone = polygon_zone.trigger(detections)
+        print(polygon_zone.current_count)
+        ```
+    """
+
+    def __init__(
+        self,
+        polygon: npt.NDArray[np.int64],
+        triggering_anchors: Iterable[Position] = (Position.BOTTOM_CENTER,),
+    ):
+        self.polygon = polygon.astype(int)
+        self.triggering_anchors = triggering_anchors
+        if not list(self.triggering_anchors):
+            raise ValueError("Triggering anchors cannot be empty.")
+
+        self.current_count = 0
+
+        x_max, y_max = np.max(polygon, axis=0)
+        self.frame_resolution_wh = (x_max + 1, y_max + 1)
+        self.mask = polygon_to_mask(
+            polygon=polygon, resolution_wh=(x_max + 2, y_max + 2)
+        )
+
+    def trigger(self, detections: Detections) -> npt.NDArray[np.bool_]:
+        """
+        Determines if the detections are within the polygon zone.
+
+        Parameters:
+            detections (Detections): The detections
+                to be checked against the polygon zone
+
+        Returns:
+            np.ndarray: A boolean numpy array indicating
+                if each detection is within the polygon zone
+        """
+
+        clipped_xyxy = clip_boxes(
+            xyxy=detections.xyxy, resolution_wh=self.frame_resolution_wh
+        )
+        clipped_detections = replace(detections, xyxy=clipped_xyxy)
+        all_clipped_anchors = np.array(
+            [
+                np.ceil(clipped_detections.get_anchors_coordinates(anchor)).astype(int)
+                for anchor in self.triggering_anchors
+            ]
+        )
+
+        is_in_zone: npt.NDArray[np.bool_] = (
+            self.mask[all_clipped_anchors[:, :, 1], all_clipped_anchors[:, :, 0]]
+            .transpose()
+            .astype(bool)
+        )
+
+        is_in_zone: npt.NDArray[np.bool_] = np.all(is_in_zone, axis=1)
+        self.current_count = int(np.sum(is_in_zone))
+        return is_in_zone.astype(bool)
+
+
+class PolygonZoneAnnotator:
+    """
+    A class for annotating a polygon-shaped zone within a
+        frame with a count of detected objects.
+
+    Attributes:
+        zone (PolygonZone): The polygon zone to be annotated
+        color (Color): The color to draw the polygon lines, default is white
+        thickness (int): The thickness of the polygon lines, default is 2
+        text_color (Color): The color of the text on the polygon, default is black
+        text_scale (float): The scale of the text on the polygon, default is 0.5
+        text_thickness (int): The thickness of the text on the polygon, default is 1
+        text_padding (int): The padding around the text on the polygon, default is 10
+        font (int): The font type for the text on the polygon,
+            default is cv2.FONT_HERSHEY_SIMPLEX
+        center (Tuple[int, int]): The center of the polygon for text placement
+        display_in_zone_count (bool): Show the label of the zone or not. Default is True
+        opacity: The opacity of zone filling when drawn on the scene. Default is 0
+    """
+
+    def __init__(
+        self,
+        zone: PolygonZone,
+        color: Color = Color.WHITE,
+        thickness: int = 2,
+        text_color: Color = Color.BLACK,
+        text_scale: float = 0.5,
+        text_thickness: int = 1,
+        text_padding: int = 10,
+        display_in_zone_count: bool = True,
+        opacity: float = 0,
+    ):
+        self.zone = zone
+        self.color = color
+        self.thickness = thickness
+        self.text_color = text_color
+        self.text_scale = text_scale
+        self.text_thickness = text_thickness
+        self.text_padding = text_padding
+        self.font = cv2.FONT_HERSHEY_SIMPLEX
+        self.center = get_polygon_center(polygon=zone.polygon)
+        self.display_in_zone_count = display_in_zone_count
+        self.opacity = opacity
+
+    def annotate(self, scene: np.ndarray, label: Optional[str] = None) -> np.ndarray:
+        """
+        Annotates the polygon zone within a frame with a count of detected objects.
+
+        Parameters:
+            scene (np.ndarray): The image on which the polygon zone will be annotated
+            label (Optional[str]): A label for the count of detected objects
+                within the polygon zone (default: None)
+
+        Returns:
+            np.ndarray: The image with the polygon zone and count of detected objects
+        """
+        if self.opacity == 0:
+            annotated_frame = draw_polygon(
+                scene=scene,
+                polygon=self.zone.polygon,
+                color=self.color,
+                thickness=self.thickness,
+            )
+        else:
+            annotated_frame = draw_filled_polygon(
+                scene=scene.copy(),
+                polygon=self.zone.polygon,
+                color=self.color,
+                opacity=self.opacity,
+            )
+            annotated_frame = draw_polygon(
+                scene=annotated_frame,
+                polygon=self.zone.polygon,
+                color=self.color,
+                thickness=self.thickness,
+            )
+
+        if self.display_in_zone_count:
+            annotated_frame = draw_text(
+                scene=annotated_frame,
+                text=str(self.zone.current_count) if label is None else label,
+                text_anchor=self.center,
+                background_color=self.color,
+                text_color=self.text_color,
+                text_scale=self.text_scale,
+                text_thickness=self.text_thickness,
+                text_padding=self.text_padding,
+                text_font=self.font,
+            )
+
+        return annotated_frame