eye-cv 1.0.0__py3-none-any.whl

eye/utils/internal.py

@@ -0,0 +1,200 @@
+import functools
+import inspect
+import os
+import warnings
+from typing import Any, Callable, Generic, Optional, Set, TypeVar
+
+
+class EyeWarnings(Warning):
+    """Eye warning category.
+    Set the deprecation warnings visibility for eye library.
+    You can set the environment variable EYE_DEPRECATION_WARNING to '0' to
+    disable the deprecation warnings.
+    """
+
+    pass
+
+
+def format_warning(msg, category, filename, lineno, line=None):
+    """
+    Format a warning the same way as the default formatter, but also include the
+    category name in the output.
+    """
+    return f"{category.__name__}: {msg}\n"
+
+
+warnings.formatwarning = format_warning
+
+if os.getenv("EYE_DEPRECATION_WARNING") == "0":
+    warnings.simplefilter("ignore", EyeWarnings)
+else:
+    warnings.simplefilter("always", EyeWarnings)
+
+
+def warn_deprecated(message: str):
+    """
+    Issue a warning that a function is deprecated.
+
+    Args:
+        message (str): The message to display when the function is called.
+    """
+    warnings.warn(message, category=EyeWarnings, stacklevel=2)
+
+
+def deprecated_parameter(
+    old_parameter: str,
+    new_parameter: str,
+    map_function: Callable = lambda x: x,
+    warning_message: str = "Warning: '{old_parameter}' in '{function_name}' is "
+    "deprecated: use '{new_parameter}' instead.",
+    **message_kwargs,
+):
+    """
+    A decorator to mark a function's parameter as deprecated and issue a warning when
+    used.
+
+    Parameters:
+        old_parameter (str): The name of the deprecated parameter.
+        new_parameter (str): The name of the parameter that should be used instead.
+        map_function (Callable): A function used to map the value of the old
+            parameter to the new parameter. Defaults to the identity function.
+        warning_message (str): The warning message to be displayed when the
+            deprecated parameter is used. Defaults to a generic warning message with
+            placeholders for the old parameter, new parameter, and function name.
+        **message_kwargs: Additional keyword arguments that can be used to customize
+            the warning message.
+
+    Returns:
+        Callable: A decorator function that can be applied to mark a function's
+            parameter as deprecated.
+
+    Examples:
+        ```python
+        @deprecated_parameter(
+            old_parameter=<OLD_PARAMETER_NAME>,
+            new_parameter=<NEW_PARAMETER_NAME>
+        )
+        def example_function(<NEW_PARAMETER_NAME>):
+            pass
+
+        # call function using deprecated parameter
+        example_function(<OLD_PARAMETER_NAME>=<OLD_PARAMETER_VALUE>)
+        ```
+    """
+
+    def decorator(func):
+        @functools.wraps(func)
+        def wrapper(*args, **kwargs):
+            if old_parameter in kwargs:
+                if args and hasattr(args[0], "__class__"):
+                    class_name = args[0].__class__.__name__
+                    function_name = f"{class_name}.{func.__name__}"
+                else:
+                    function_name = func.__name__
+
+                warn_deprecated(
+                    message=warning_message.format(
+                        function_name=function_name,
+                        old_parameter=old_parameter,
+                        new_parameter=new_parameter,
+                        **message_kwargs,
+                    )
+                )
+
+                kwargs[new_parameter] = map_function(kwargs.pop(old_parameter))
+
+            return func(*args, **kwargs)
+
+        return wrapper
+
+    return decorator
+
+
+def deprecated(reason: str):
+    def decorator(func):
+        @functools.wraps(func)
+        def wrapper(*args, **kwargs):
+            warn_deprecated(f"{func.__name__} is deprecated: {reason}")
+            return func(*args, **kwargs)
+
+        return wrapper
+
+    return decorator
+
+
+T = TypeVar("T")
+
+
+class classproperty(Generic[T]):
+    """
+    A decorator that combines @classmethod and @property.
+    It allows a method to be accessed as a property of the class,
+    rather than an instance, similar to a classmethod.
+
+    Usage:
+        @classproperty
+        def my_method(cls):
+            ...
+    """
+
+    def __init__(self, fget: Callable[..., T]):
+        """
+        Args:
+            The function that is called when the property is accessed.
+        """
+        self.fget = fget
+
+    def __get__(self, owner_self: Any, owner_cls: Optional[type] = None) -> T:
+        """
+        Override the __get__ method to return the result of the function call.
+
+        Args:
+            owner_self: The instance through which the attribute was accessed, or None.
+                Irrelevant for class properties.
+            owner_cls: The class through which the attribute was accessed.
+
+        Returns:
+            The result of calling the function stored in 'fget' with 'owner_cls'.
+        """
+        if self.fget is None:
+            raise AttributeError("unreadable attribute")
+        return self.fget(owner_cls)
+
+
+def get_instance_variables(instance: Any, include_properties=False) -> Set[str]:
+    """
+    Get the public variables of a class instance.
+
+    Args:
+        instance (Any): The instance of a class
+        include_properties (bool): Whether to include properties in the result
+
+    Usage:
+        ```python
+        detections = Detections(xyxy=np.array([1,2,3,4]))
+        variables = get_class_variables(detections)
+        # ["xyxy", "mask", "confidence", ..., "data"]
+        ```
+    """
+    if isinstance(instance, type):
+        raise ValueError("Only class instances are supported, not classes.")
+
+    fields = set(
+        (
+            name
+            for name, val in inspect.getmembers(instance)
+            if not callable(val) and not name.startswith("_")
+        )
+    )
+
+    if not include_properties:
+        properties = set(
+            (
+                name
+                for name, val in inspect.getmembers(instance.__class__)
+                if isinstance(val, property)
+            )
+        )
+        fields -= properties
+
+    return fields

eye/utils/iterables.py

@@ -0,0 +1,84 @@
+from typing import Generator, Iterable, List, TypeVar
+
+V = TypeVar("V")
+
+
+def create_batches(
+    sequence: Iterable[V], batch_size: int
+) -> Generator[List[V], None, None]:
+    """
+    Provides a generator that yields chunks of the input sequence
+    of the size specified by the `batch_size` parameter. The last
+    chunk may be a smaller batch.
+
+    Args:
+        sequence (Iterable[V]): The sequence to be split into batches.
+        batch_size (int): The expected size of a batch.
+
+    Returns:
+        (Generator[List[V], None, None]): A generator that yields chunks
+            of `sequence` of size `batch_size`, up to the length of
+            the input `sequence`.
+
+    Examples:
+        ```python
+        list(create_batches([1, 2, 3, 4, 5], 2))
+        # [[1, 2], [3, 4], [5]]
+
+        list(create_batches("abcde", 3))
+        # [['a', 'b', 'c'], ['d', 'e']]
+        ```
+    """
+    batch_size = max(batch_size, 1)
+    current_batch = []
+    for element in sequence:
+        if len(current_batch) == batch_size:
+            yield current_batch
+            current_batch = []
+        current_batch.append(element)
+    if current_batch:
+        yield current_batch
+
+
+def fill(sequence: List[V], desired_size: int, content: V) -> List[V]:
+    """
+    Fill the sequence with padding elements until the sequence reaches
+    the desired size.
+
+    Args:
+        sequence (List[V]): The input sequence.
+        desired_size (int): The expected size of the output list. The
+            difference between this value and the actual length of `sequence`
+            (if positive) dictates how many elements will be added as padding.
+        content (V): The element to be placed at the end of the input
+            `sequence` as padding.
+
+    Returns:
+        (List[V]): A padded version of the input `sequence` (if needed).
+
+    Examples:
+        ```python
+        fill([1, 2], 4, 0)
+        # [1, 2, 0, 0]
+
+        fill(['a', 'b'], 3, 'c')
+        # ['a', 'b', 'c']
+        ```
+    """
+    missing_size = max(0, desired_size - len(sequence))
+    sequence.extend([content] * missing_size)
+    return sequence
+
+
+def find_duplicates(sequence: List) -> List:
+    """
+    Find all duplicate elements in the input sequence.
+    """
+    seen = set()
+    duplicates = set()
+    for element in sequence:
+        if element in seen:
+            duplicates.add(element)
+        else:
+            seen.add(element)
+    return list(duplicates)

eye/utils/notebook.py

@@ -0,0 +1,114 @@
+from typing import List, Optional, Tuple
+
+import cv2
+import matplotlib.pyplot as plt
+from PIL import Image
+
+from eye.annotators.base import ImageType
+from eye.utils.conversion import pillow_to_cv2
+
+
+def plot_image(
+    image: ImageType, size: Tuple[int, int] = (12, 12), cmap: Optional[str] = "gray"
+) -> None:
+    """
+    Plots image using matplotlib.
+
+    Args:
+        image (ImageType): The frame to be displayed ImageType
+             is a flexible type, accepting either `numpy.ndarray` or `PIL.Image.Image`.
+        size (Tuple[int, int]): The size of the plot in inches.
+        cmap (str): the colormap to use for single channel images.
+
+    Examples:
+        ```python
+        import cv2
+        import eye as sv
+
+        image = cv2.imread("path/to/image.jpg")
+
+        %matplotlib inline
+        sv.plot_image(image=image, size=(16, 16))
+        ```
+    """
+    if isinstance(image, Image.Image):
+        image = pillow_to_cv2(image)
+
+    plt.figure(figsize=size)
+
+    if image.ndim == 2:
+        plt.imshow(image, cmap=cmap)
+    else:
+        plt.imshow(cv2.cvtColor(image, cv2.COLOR_BGR2RGB))
+
+    plt.axis("off")
+    plt.show()
+
+
+def plot_images_grid(
+    images: List[ImageType],
+    grid_size: Tuple[int, int],
+    titles: Optional[List[str]] = None,
+    size: Tuple[int, int] = (12, 12),
+    cmap: Optional[str] = "gray",
+) -> None:
+    """
+    Plots images in a grid using matplotlib.
+
+    Args:
+       images (List[ImageType]): A list of images as ImageType
+             is a flexible type, accepting either `numpy.ndarray` or `PIL.Image.Image`.
+       grid_size (Tuple[int, int]): A tuple specifying the number
+            of rows and columns for the grid.
+       titles (Optional[List[str]]): A list of titles for each image.
+            Defaults to None.
+       size (Tuple[int, int]): A tuple specifying the width and
+            height of the entire plot in inches.
+       cmap (str): the colormap to use for single channel images.
+
+    Raises:
+       ValueError: If the number of images exceeds the grid size.
+
+    Examples:
+        ```python
+        import cv2
+        import eye as sv
+        from PIL import Image
+
+        image1 = cv2.imread("path/to/image1.jpg")
+        image2 = Image.open("path/to/image2.jpg")
+        image3 = cv2.imread("path/to/image3.jpg")
+
+        images = [image1, image2, image3]
+        titles = ["Image 1", "Image 2", "Image 3"]
+
+        %matplotlib inline
+        plot_images_grid(images, grid_size=(2, 2), titles=titles, size=(16, 16))
+        ```
+    """
+    nrows, ncols = grid_size
+
+    for idx, img in enumerate(images):
+        if isinstance(img, Image.Image):
+            images[idx] = pillow_to_cv2(img)
+
+    if len(images) > nrows * ncols:
+        raise ValueError(
+            "The number of images exceeds the grid size. Please increase the grid size"
+            " or reduce the number of images."
+        )
+
+    fig, axes = plt.subplots(nrows=nrows, ncols=ncols, figsize=size)
+
+    for idx, ax in enumerate(axes.flat):
+        if idx < len(images):
+            if images[idx].ndim == 2:
+                ax.imshow(images[idx], cmap=cmap)
+            else:
+                ax.imshow(cv2.cvtColor(images[idx], cv2.COLOR_BGR2RGB))
+
+            if titles is not None and idx < len(titles):
+                ax.set_title(titles[idx])
+
+        ax.axis("off")
+    plt.show()

eye/utils/video.py

@@ -0,0 +1,307 @@
+from __future__ import annotations
+
+import time
+from collections import deque
+from dataclasses import dataclass
+from typing import Callable, Generator, Optional, Tuple
+
+import cv2
+import numpy as np
+
+
+@dataclass
+class VideoInfo:
+    """
+    A class to store video information, including width, height, fps and
+        total number of frames.
+
+    Attributes:
+        width (int): width of the video in pixels
+        height (int): height of the video in pixels
+        fps (int): frames per second of the video
+        total_frames (Optional[int]): total number of frames in the video,
+            default is None
+
+    Examples:
+        ```python
+        import eye as sv
+
+        video_info = sv.VideoInfo.from_video_path(video_path=<SOURCE_VIDEO_FILE>)
+
+        video_info
+        # VideoInfo(width=3840, height=2160, fps=25, total_frames=538)
+
+        video_info.resolution_wh
+        # (3840, 2160)
+        ```
+    """
+
+    width: int
+    height: int
+    fps: int
+    total_frames: Optional[int] = None
+
+    @classmethod
+    def from_video_path(cls, video_path: str) -> VideoInfo:
+        video = cv2.VideoCapture(video_path)
+        if not video.isOpened():
+            raise Exception(f"Could not open video at {video_path}")
+
+        width = int(video.get(cv2.CAP_PROP_FRAME_WIDTH))
+        height = int(video.get(cv2.CAP_PROP_FRAME_HEIGHT))
+        fps = int(video.get(cv2.CAP_PROP_FPS))
+        total_frames = int(video.get(cv2.CAP_PROP_FRAME_COUNT))
+        video.release()
+        return VideoInfo(width, height, fps, total_frames)
+
+    @property
+    def resolution_wh(self) -> Tuple[int, int]:
+        return self.width, self.height
+
+
+class VideoSink:
+    """
+    Context manager that saves video frames to a file using OpenCV.
+
+    Attributes:
+        target_path (str): The path to the output file where the video will be saved.
+        video_info (VideoInfo): Information about the video resolution, fps,
+            and total frame count.
+        codec (str): FOURCC code for video format
+
+    Example:
+        ```python
+        import eye as sv
+
+        video_info = sv.VideoInfo.from_video_path(<SOURCE_VIDEO_PATH>)
+        frames_generator = sv.get_video_frames_generator(<SOURCE_VIDEO_PATH>)
+
+        with sv.VideoSink(target_path=<TARGET_VIDEO_PATH>, video_info=video_info) as sink:
+            for frame in frames_generator:
+                sink.write_frame(frame=frame)
+        ```
+    """  # noqa: E501 // docs
+
+    def __init__(self, target_path: str, video_info: VideoInfo, codec: str = "mp4v"):
+        self.target_path = target_path
+        self.video_info = video_info
+        self.__codec = codec
+        self.__writer = None
+
+    def __enter__(self):
+        try:
+            self.__fourcc = cv2.VideoWriter_fourcc(*self.__codec)
+        except TypeError as e:
+            print(str(e) + ". Defaulting to mp4v...")
+            self.__fourcc = cv2.VideoWriter_fourcc(*"mp4v")
+        self.__writer = cv2.VideoWriter(
+            self.target_path,
+            self.__fourcc,
+            self.video_info.fps,
+            self.video_info.resolution_wh,
+        )
+        return self
+
+    def write_frame(self, frame: np.ndarray):
+        """
+        Writes a single video frame to the target video file.
+
+        Args:
+            frame (np.ndarray): The video frame to be written to the file. The frame
+                must be in BGR color format.
+        """
+        self.__writer.write(frame)
+
+    def __exit__(self, exc_type, exc_value, exc_traceback):
+        self.__writer.release()
+
+
+class VideoWriter:
+    """Compatibility wrapper for OpenCV VideoWriter.
+
+    Some scripts expect an object with `.write(frame)` and `.release()` methods.
+    This wrapper keeps that API while staying consistent with Eye's video utils.
+    """
+
+    def __init__(self, target_path: str, fps: int, resolution: Tuple[int, int], codec: str = "mp4v"):
+        self.target_path = target_path
+        self.fps = int(fps)
+        self.resolution = (int(resolution[0]), int(resolution[1]))
+        try:
+            fourcc = cv2.VideoWriter_fourcc(*codec)
+        except TypeError:
+            fourcc = cv2.VideoWriter_fourcc(*"mp4v")
+        self._writer = cv2.VideoWriter(self.target_path, fourcc, self.fps, self.resolution)
+
+    def write(self, frame: np.ndarray) -> None:
+        self._writer.write(frame)
+
+    def release(self) -> None:
+        self._writer.release()
+
+
+def _validate_and_setup_video(
+    source_path: str, start: int, end: Optional[int], iterative_seek: bool = False
+):
+    video = cv2.VideoCapture(source_path)
+    if not video.isOpened():
+        raise Exception(f"Could not open video at {source_path}")
+    total_frames = int(video.get(cv2.CAP_PROP_FRAME_COUNT))
+    if end is not None and end > total_frames:
+        raise Exception("Requested frames are outbound")
+    start = max(start, 0)
+    end = min(end, total_frames) if end is not None else total_frames
+
+    if iterative_seek:
+        while start > 0:
+            success = video.grab()
+            if not success:
+                break
+            start -= 1
+    elif start > 0:
+        video.set(cv2.CAP_PROP_POS_FRAMES, start)
+
+    return video, start, end
+
+
+def get_video_frames_generator(
+    source_path: str,
+    stride: int = 1,
+    start: int = 0,
+    end: Optional[int] = None,
+    iterative_seek: bool = False,
+) -> Generator[np.ndarray, None, None]:
+    """
+    Get a generator that yields the frames of the video.
+
+    Args:
+        source_path (str): The path of the video file.
+        stride (int): Indicates the interval at which frames are returned,
+            skipping stride - 1 frames between each.
+        start (int): Indicates the starting position from which
+            video should generate frames
+        end (Optional[int]): Indicates the ending position at which video
+            should stop generating frames. If None, video will be read to the end.
+        iterative_seek (bool): If True, the generator will seek to the
+            `start` frame by grabbing each frame, which is much slower. This is a
+            workaround for videos that don't open at all when you set the `start` value.
+
+    Returns:
+        (Generator[np.ndarray, None, None]): A generator that yields the
+            frames of the video.
+
+    Examples:
+        ```python
+        import eye as sv
+
+        for frame in sv.get_video_frames_generator(source_path=<SOURCE_VIDEO_PATH>):
+            ...
+        ```
+    """
+    video, start, end = _validate_and_setup_video(
+        source_path, start, end, iterative_seek
+    )
+    frame_position = start
+    while True:
+        success, frame = video.read()
+        if not success or frame_position >= end:
+            break
+        yield frame
+        for _ in range(stride - 1):
+            success = video.grab()
+            if not success:
+                break
+        frame_position += stride
+    video.release()
+
+
+def process_video(
+    source_path: str,
+    target_path: str,
+    callback: Callable[[np.ndarray, int], np.ndarray],
+) -> None:
+    """
+    Process a video file by applying a callback function on each frame
+        and saving the result to a target video file.
+
+    Args:
+        source_path (str): The path to the source video file.
+        target_path (str): The path to the target video file.
+        callback (Callable[[np.ndarray, int], np.ndarray]): A function that takes in
+            a numpy ndarray representation of a video frame and an
+            int index of the frame and returns a processed numpy ndarray
+            representation of the frame.
+
+    Examples:
+        ```python
+        import eye as sv
+
+        def callback(scene: np.ndarray, index: int) -> np.ndarray:
+            ...
+
+        process_video(
+            source_path=<SOURCE_VIDEO_PATH>,
+            target_path=<TARGET_VIDEO_PATH>,
+            callback=callback
+        )
+        ```
+    """
+    source_video_info = VideoInfo.from_video_path(video_path=source_path)
+    with VideoSink(target_path=target_path, video_info=source_video_info) as sink:
+        for index, frame in enumerate(
+            get_video_frames_generator(source_path=source_path)
+        ):
+            result_frame = callback(frame, index)
+            sink.write_frame(frame=result_frame)
+
+
+class FPSMonitor:
+    """
+    A class for monitoring frames per second (FPS) to benchmark latency.
+    """
+
+    def __init__(self, sample_size: int = 30):
+        """
+        Args:
+            sample_size (int): The maximum number of observations for latency
+                benchmarking.
+
+        Examples:
+            ```python
+            import eye as sv
+
+            frames_generator = sv.get_video_frames_generator(source_path=<SOURCE_FILE_PATH>)
+            fps_monitor = sv.FPSMonitor()
+
+            for frame in frames_generator:
+                # your processing code here
+                fps_monitor.tick()
+                fps = fps_monitor.fps
+            ```
+        """  # noqa: E501 // docs
+        self.all_timestamps = deque(maxlen=sample_size)
+
+    @property
+    def fps(self) -> float:
+        """
+        Computes and returns the average FPS based on the stored time stamps.
+
+        Returns:
+            float: The average FPS. Returns 0.0 if no time stamps are stored.
+        """
+        if not self.all_timestamps:
+            return 0.0
+        taken_time = self.all_timestamps[-1] - self.all_timestamps[0]
+        return (len(self.all_timestamps)) / taken_time if taken_time != 0 else 0.0
+
+    def tick(self) -> None:
+        """
+        Adds a new time stamp to the deque for FPS calculation.
+        """
+        self.all_timestamps.append(time.monotonic())
+
+    def reset(self) -> None:
+        """
+        Clears all the time stamps from the deque.
+        """
+        self.all_timestamps.clear()

eye/utils_eye/__init__.py

@@ -0,0 +1 @@
+"""Utils."""