bump version from 0.19.0rc3 to 0.19.0rc4

fix: 🐞 Custom warning type 'SupervisionWarning' added

.github/workflows/publish.yml

@@ -3,8 +3,6 @@ on:
   push:
     tags:
       - '[0-9]+.[0-9]+[0-9]+.[0-9]'
-      - '[0-9]+.[0-9]+[0-9]+.[0-9]'
-      - '[0-9]+.[0-9]+[0-9]+.[0-9]'
 
   # Allows you to run this workflow manually from the Actions tab
   workflow_dispatch:

.github/workflows/test-min.yml

@@ -37,6 +37,7 @@ jobs:
               matplotlib==3.5.0 \
               numpy==1.21.2 \
               opencv-python==4.5.5.64 \
+              Pillow==10.1.0 \
               packaging==23.2 \
               pluggy==1.3.0 \
               pyparsing==3.1.1 \

.pre-commit-config.yaml

@@ -14,7 +14,6 @@ repos:
         exclude: test/.*\.py
       - id: check-yaml
         exclude: mkdocs.yml
-      - id: check-docstring-first
       - id: check-executables-have-shebangs
       - id: check-toml
       - id: check-case-conflict
@@ -47,7 +46,7 @@ repos:
 
 
   -   repo: https://github.com/astral-sh/ruff-pre-commit
-      rev: v0.2.0
+      rev: v0.2.2
       hooks:
       -   id: ruff
           args: [--fix, --exit-non-zero-on-fix]

CONTRIBUTING.md

@@ -112,6 +112,20 @@ To run the documentation, install the project requirements with `poetry install
 
 You can learn more about mkdocs on the [mkdocs website](https://www.mkdocs.org/).
 
+## 🧑‍🍳 cookbooks
+
+We are always looking for new examples and cookbooks to add to the `supervision`
+documentation. If you have a use case that you think would be helpful to others, please
+submit a PR with your example. Here are some guidelines for submitting a new example:
+
+- Create a new notebook in the [`docs/nodebooks`](https://github.com/roboflow/supervision/tree/develop/docs/notebooks) folder.
+- Add a link to the new notebook in [`docs/theme/cookbooks.html`](https://github.com/roboflow/supervision/blob/develop/docs/theme/cookbooks.html). Make sure to add the path to the new notebook, as well as a title, labels, author and supervision version.
+- Use the [Count Objects Crossing the Line](https://supervision.roboflow.com/develop/notebooks/count-objects-crossing-the-line/) example as a template for your new example.
+- Freeze the version of `supervision` you are using.
+- Place an appropriate Open in Colab button at the top of the notebook. You can find an example of such a button in the aforementioned `Count Objects Crossing the Line` cookbook.
+- Notebook should be self-contained. If you rely on external data ( videos, images, etc.) or libraries, include download and installation commands in the notebook.
+- Annotate the code with appropriate comments, including links to the documentation describing each of the tools you have used.
+
 ## 🧪 tests
 
 [`pytests`](https://docs.pytest.org/en/7.1.x/) is used to run our tests.

docs/detection/tools/line_zone.md

@@ -2,6 +2,14 @@
 comments: true
 ---
 
-# LineZone
+<div class="md-typeset">
+  <h2>LineZone</h2>
+</div>
 
-:::supervision.detection.line_counter.LineZone
+:::supervision.detection.line_zone.LineZone
+
+<div class="md-typeset">
+  <h2>LineZoneAnnotator</h2>
+</div>
+
+:::supervision.detection.line_zone.LineZoneAnnotator

docs/detection/tools/polygon_zone.md

@@ -2,7 +2,9 @@
 comments: true
 ---
 
-# PolygonZone
+<div class="md-typeset">
+  <h2>PolygonZone</h2>
+</div>
 
 :::supervision.detection.tools.polygon_zone.PolygonZone
 

docs/detection/tools/smoother.md

@@ -1,6 +1,5 @@
 ---
 comments: true
-status: new
 ---
 
 # Detection Smoother

docs/index.md

@@ -1,19 +1,20 @@
 ---
+template: index.html
 comments: true
 hide:
   - navigation
   - toc
 ---
 
-<div align="center">
-  <p>
-    <a align="center" href="" target="_blank">
-      <img
-        width="850"
-        src="https://media.roboflow.com/open-source/supervision/rf-supervision-banner.png?updatedAt=1678995927529"
-      >
-    </a>
-  </p>
+<div class="md-typeset">
+  <h1></h1>
+</div>
+
+<div align="center" id="logo">
+  <a align="center" href="" target="_blank">
+      <img width="850"
+          src="https://media.roboflow.com/open-source/supervision/rf-supervision-banner.png?updatedAt=1678995927529">
+  </a>
 </div>
 
 ## 👋 Hello
@@ -45,7 +46,7 @@ You can install `supervision` with pip in a
         If you require the full version of `supervision` with GUI support you can install the desktop version. This version includes the GUI components of OpenCV, allowing you to display images and videos on the screen.
 
         ```bash
-        pip install supervision[desktop]
+        pip install "supervision[desktop]"
         ```
 
 !!! example "git clone (for development)"

docs/javascripts/cookbooks-card.js

@@ -55,7 +55,7 @@ document.addEventListener("DOMContentLoaded", function () {
 
     let authorAvatarsHTML = authorDataArray.map((authorData, index) => {
         const marginLeft = index === 0 ? '0' : '-10px';
-        const zIndex = 100 - index;
+        const zIndex = 4 - index;
         return `
             <div
                 class="author-container"

docs/notebooks/download-supervision-assets.ipynb

@@ -4,38 +4,20 @@
             "cell_type": "markdown",
             "metadata": {},
             "source": [
-                "# Experimenting with Supervision Assets\n",
+                "# Download Supervision Assets\n",
                 "\n",
                 "---\n",
                 "\n",
-                "<p align=\"center\">\n",
-                "  <a href=\"https://colab.research.google.com/github/roboflow/supervision/blob/develop/docs/notebooks/supervision-assets.ipynb\"><img src=\"https://colab.research.google.com/assets/colab-badge.svg\" alt=\"Colab\"></a>\n",
-                "</p>\n",
+                "[![Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/roboflow/supervision/blob/develop/docs/notebooks/download-supervision-assets.ipynb)\n",
                 "\n",
-                "When experimenting with interesting and useful features of the Supervision package, its important to have some sort of image or video data to experiment with. Luckily for us, Supervision ships with [Assets](https://supervision.roboflow.com/latest/assets/)! Assets is a collection of videos that you can utilize to start experimenting with the various features Supervision has to offer. Let's take a look at how to use this resource.\n",
+                "When experimenting with interesting and useful features of the Supervision package, it's important to have some sort of image or video data to experiment with. Luckily for us, Supervision ships with [Assets](https://supervision.roboflow.com/latest/assets/)! Assets is a collection of videos that you can utilize to start experimenting with the various features Supervision has to offer. Let's take a look at how to use this resource.\n",
                 "\n",
-                "## Install with Pip\n",
-                "\n",
-                "If you're running this code outside a Jupyter notebook, it's generally a best practice to create a virtual environment so that your projects deppendencies are isolated. Run the following ing your command line of choice to create and source one.\n",
-                "\n",
-                "```shell\n",
-                "\n",
-                "python -m venv venv\n",
-                "source venv/bin/activate\n",
-                "\n",
-                "``` "
-            ]
-        },
-        {
-            "cell_type": "markdown",
-            "metadata": {},
-            "source": [
-                "Now that we've got a virtual enviornment installed and sourced, let's install the pip package with the assets \"extra\" package. Make sure to remove the \"!\" if running this in your command line."
+                "## Install Dependencies"
             ]
         },
         {
             "cell_type": "code",
-            "execution_count": null,
+            "execution_count": 10,
             "metadata": {
                 "vscode": {
                     "languageId": "shellscript"
@@ -63,7 +45,7 @@
             "source": [
                 "from supervision.assets import download_assets, VideoAssets\n",
                 "\n",
-                "# Download a video asset from the supervision package.\n",
+                "# Download the a video of the subway.\n",
                 "path_to_video = download_assets(VideoAssets.SUBWAY)"
             ]
         },
@@ -71,7 +53,28 @@
             "cell_type": "markdown",
             "metadata": {},
             "source": [
-                "We're now equipt with a video asset from Supervision to run some experiements on! For more information on available video assets, visit the [Supervision API Reference](https://supervision.roboflow.com/latest/assets/#videoassets). Happy building!"
+                "With this, we now have a high quality video asset for use in demos. Let's take a look at what we downloaded. Keep in mind that the video preview below works only in the web version of the cookbooks and not in Google Colab.\n"
+            ]
+        },
+        {
+            "cell_type": "markdown",
+            "metadata": {},
+            "source": [
+                "<div style=\"display: flex; justify-content: center;\">\n",
+                "    <video controls width=\"320\" height=\"240\">\n",
+                "        <source\n",
+                "            src=\"https://media.roboflow.com/supervision/video-examples/subway.mp4\"\n",
+                "            type=\"video/mp4\"\n",
+                "        >\n",
+                "    </video>\n",
+                "</div>"
+            ]
+        },
+        {
+            "cell_type": "markdown",
+            "metadata": {},
+            "source": [
+                "We're now equipt with a video asset from Supervision to run some experiments on! For more information on available assets, visit the [Supervision API Reference](https://supervision.roboflow.com/latest/assets). Happy building!"
             ]
         }
     ],
@@ -91,7 +94,7 @@
             "name": "python",
             "nbconvert_exporter": "python",
             "pygments_lexer": "ipython3",
-            "version": "3.11.7"
+            "version": "3.11.8"
         }
     },
     "nbformat": 4,

docs/theme/cookbooks.html

@@ -12,6 +12,8 @@
     </div>
     <div class="custom-grid">
       <p class="card repo-card" data-url="/develop/notebooks/quickstart" data-name="Supervision Quickstart" data-labels="ANNOTATOR,DETECTION,SAM" data-version="v0.18.0" data-author="SkalskiP,onuralpszr"></p>
+      <p class="card repo-card" data-url="/develop/notebooks/count-objects-crossing-the-line" data-name="Count Objects Crossing the Line" data-labels="ANNOTATORS,LINE ZONE,TRACKING" data-version="v0.18.0" data-author="SkalskiP"></p>
+      <p class="card repo-card" data-url="/develop/notebooks/zero-shot-object-detection-with-yolo-world" data-name="Zero-Shot Object Detection with YOLO-World" data-labels="ANNOTATORS,DETECTION,INFERENCE" data-version="v0.19.0" data-author="SkalskiP"></p>
       <p class="card repo-card" data-url="/develop/notebooks/download-supervision-assets" data-name="Downloading Supervision Assets" data-labels="ASSETS" data-version="v0.18.0" data-author="nickherrig"></p>
       <p class="card repo-card" data-url="/develop/notebooks/annotate-video-with-detections" data-name="Annotate Video with Detections" data-labels="INFERENCE,YOLOV8" data-version="v0.18.0" data-author="nickherrig"></p>
       <p class="card repo-card" data-url="/develop/notebooks/object-tracking" data-name="Object Tracking"  data-labels="TRACKING, ANNOTATOR" data-version="v0.18.0" data-author="nickherrig"></p>

docs/theme/index.html

@@ -0,0 +1,15 @@
+{% extends "main.html" %}
+{% block content %}
+{{ super() }}
+<style>
+  .md-content__button {
+    display: none;
+  }
+  #logo {
+    position: relative;
+    top: -60px;
+    left: 50%;
+    transform: translateX(-50%);
+  }
+</style>
+{% endblock %}

pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "supervision"
-version = "0.19.0rc3"
+version = "0.19.0rc4"
 description = "A set of easy-to-use utils that will come in handy in any Computer Vision project"
 authors = ["Piotr Skalski <piotr.skalski92@gmail.com>"]
 maintainers = ["Piotr Skalski <piotr.skalski92@gmail.com>"]
@@ -43,14 +43,15 @@ defusedxml = "^0.7.1"
 opencv-python = { version = ">=4.5.5.64", optional = true }
 opencv-python-headless = ">=4.5.5.64"
 requests = { version = ">=2.26.0,<=2.31.0", optional = true }
-tqdm = { version = ">=4.62.3,<=4.66.1", optional = true }
+tqdm = { version = ">=4.62.3,<=4.66.2", optional = true }
+pillow = ">=9.4"
 
 [tool.poetry.extras]
 desktop = ["opencv-python"]
 assets = ["requests","tqdm"]
 
 [tool.poetry.group.dev.dependencies]
-twine = "^4.0.2"
+twine = ">=4.0.2,<6.0.0"
 pytest = ">=7.2.2,<9.0.0"
 wheel = ">=0.40,<0.43"
 build = ">=0.10,<1.1"
@@ -111,12 +112,12 @@ exclude = '''
 [tool.ruff]
 target-version = "py38"
 # Enable pycodestyle (`E`) and Pyflakes (`F`) codes by default.
-select = ["E", "F"]
-ignore = []
+lint.select = ["E", "F"]
+lint.ignore = []
 
 # Allow autofix for all enabled rules (when `--fix`) is provided.
-fixable = ["A", "B", "C", "D", "E", "F", "G", "I", "N", "Q", "S", "T", "W", "ANN", "ARG", "BLE", "COM", "DJ", "DTZ", "EM", "ERA", "EXE", "FBT", "ICN", "INP", "ISC", "NPY", "PD", "PGH", "PIE", "PL", "PT", "PTH", "PYI", "RET", "RSE", "RUF", "SIM", "SLF", "TCH", "TID", "TRY", "UP", "YTT"]
-unfixable = []
+lint.fixable = ["A", "B", "C", "D", "E", "F", "G", "I", "N", "Q", "S", "T", "W", "ANN", "ARG", "BLE", "COM", "DJ", "DTZ", "EM", "ERA", "EXE", "FBT", "ICN", "INP", "ISC", "NPY", "PD", "PGH", "PIE", "PL", "PT", "PTH", "PYI", "RET", "RSE", "RUF", "SIM", "SLF", "TCH", "TID", "TRY", "UP", "YTT"]
+lint.unfixable = []
 
 # Exclude a variety of commonly ignored directories.
 exclude = [
@@ -151,17 +152,17 @@ line-length = 88
 indent-width = 4
 
 # Allow unused variables when underscore-prefixed.
-dummy-variable-rgx = "^(_+|(_+[a-zA-Z0-9_]*[a-zA-Z0-9]+?))$"
+lint.dummy-variable-rgx = "^(_+|(_+[a-zA-Z0-9_]*[a-zA-Z0-9]+?))$"
 
-[tool.ruff.flake8-quotes]
+[tool.ruff.lint.flake8-quotes]
 inline-quotes = "double"
 multiline-quotes = "double"
 docstring-quotes = "double"
 
-[tool.ruff.pydocstyle]
+[tool.ruff.lint.pydocstyle]
 convention = "google"
 
-[tool.ruff.per-file-ignores]
+[tool.ruff.lint.per-file-ignores]
 "__init__.py" = ["E402","F401"]
 "supervision/assets/list.py" = ["E501"]
 

supervision/__init__.py

@@ -35,7 +35,7 @@ from supervision.dataset.core import (
 )
 from supervision.detection.annotate import BoxAnnotator
 from supervision.detection.core import Detections
-from supervision.detection.line_counter import LineZone, LineZoneAnnotator
+from supervision.detection.line_zone import LineZone, LineZoneAnnotator
 from supervision.detection.tools.csv_sink import CSVSink
 from supervision.detection.tools.inference_slicer import InferenceSlicer
 from supervision.detection.tools.polygon_zone import PolygonZone, PolygonZoneAnnotator

supervision/annotators/base.py

@@ -1,11 +1,22 @@
 from abc import ABC, abstractmethod
+from typing import TypeVar
 
 import numpy as np
+from PIL import Image
 
 from supervision.detection.core import Detections
 
+ImageType = TypeVar("ImageType", np.ndarray, Image.Image)
+"""
+An image of type `np.ndarray` or `PIL.Image.Image`.
+
+Unlike a `Union`, ensures the type remains consistent. If a function
+takes an `ImageType` argument and returns an `ImageType`, when you
+pass an `np.ndarray`, you will get an `np.ndarray` back.
+"""
+
 
 class BaseAnnotator(ABC):
     @abstractmethod
-    def annotate(self, scene: np.ndarray, detections: Detections) -> np.ndarray:
+    def annotate(self, scene: ImageType, detections: Detections) -> ImageType:
         pass

supervision/annotators/core.py

@@ -4,8 +4,13 @@ from typing import List, Optional, Tuple, Union
 import cv2
 import numpy as np
 
-from supervision.annotators.base import BaseAnnotator
-from supervision.annotators.utils import ColorLookup, Trace, resolve_color
+from supervision.annotators.base import BaseAnnotator, ImageType
+from supervision.annotators.utils import (
+    ColorLookup,
+    Trace,
+    resolve_color,
+    scene_to_annotator_img_type,
+)
 from supervision.config import CLASS_NAME_DATA_FIELD, ORIENTED_BOX_COORDINATES
 from supervision.detection.core import Detections
 from supervision.detection.utils import clip_boxes, mask_to_polygons
@@ -37,23 +42,26 @@ class BoundingBoxAnnotator(BaseAnnotator):
         self.thickness: int = thickness
         self.color_lookup: ColorLookup = color_lookup
 
+    @scene_to_annotator_img_type
     def annotate(
         self,
-        scene: np.ndarray,
+        scene: ImageType,
         detections: Detections,
         custom_color_lookup: Optional[np.ndarray] = None,
-    ) -> np.ndarray:
+    ) -> ImageType:
         """
         Annotates the given scene with bounding boxes based on the provided detections.
 
         Args:
-            scene (np.ndarray): The image where bounding boxes will be drawn.
+            scene (ImageType): The image where bounding boxes will be drawn. `ImageType`
+            is a flexible type, accepting either `numpy.ndarray` or `PIL.Image.Image`.
             detections (Detections): Object detections to annotate.
             custom_color_lookup (Optional[np.ndarray]): Custom color lookup array.
                 Allows to override the default color mapping strategy.
 
         Returns:
-            The annotated image.
+            The annotated image, matching the type of `scene` (`numpy.ndarray`
+                or `PIL.Image.Image`)
 
         Example:
             ```python
@@ -115,23 +123,27 @@ class OrientedBoxAnnotator(BaseAnnotator):
         self.thickness: int = thickness
         self.color_lookup: ColorLookup = color_lookup
 
+    @scene_to_annotator_img_type
     def annotate(
         self,
-        scene: np.ndarray,
+        scene: ImageType,
         detections: Detections,
         custom_color_lookup: Optional[np.ndarray] = None,
-    ) -> np.ndarray:
+    ) -> ImageType:
         """
         Annotates the given scene with oriented bounding boxes based on the provided detections.
 
         Args:
-            scene (np.ndarray): The image where bounding boxes will be drawn.
+            scene (ImageType): The image where bounding boxes will be drawn.
+                `ImageType` is a flexible type, accepting either `numpy.ndarray`
+                or `PIL.Image.Image`.
             detections (Detections): Object detections to annotate.
             custom_color_lookup (Optional[np.ndarray]): Custom color lookup array.
                 Allows to override the default color mapping strategy.
 
         Returns:
-            The annotated image.
+            The annotated image, matching the type of `scene` (`numpy.ndarray`
+                or `PIL.Image.Image`)
 
         Example:
             ```python
@@ -199,23 +211,27 @@ class MaskAnnotator(BaseAnnotator):
         self.opacity = opacity
         self.color_lookup: ColorLookup = color_lookup
 
+    @scene_to_annotator_img_type
     def annotate(
         self,
-        scene: np.ndarray,
+        scene: ImageType,
         detections: Detections,
         custom_color_lookup: Optional[np.ndarray] = None,
-    ) -> np.ndarray:
+    ) -> ImageType:
         """
         Annotates the given scene with masks based on the provided detections.
 
         Args:
-            scene (np.ndarray): The image where masks will be drawn.
+            scene (ImageType): The image where masks will be drawn.
+                `ImageType` is a flexible type, accepting either `numpy.ndarray`
+                or `PIL.Image.Image`.
             detections (Detections): Object detections to annotate.
             custom_color_lookup (Optional[np.ndarray]): Custom color lookup array.
                 Allows to override the default color mapping strategy.
 
         Returns:
-            The annotated image.
+            The annotated image, matching the type of `scene` (`numpy.ndarray`
+                or `PIL.Image.Image`)
 
         Example:
             ```python
@@ -282,23 +298,27 @@ class PolygonAnnotator(BaseAnnotator):
         self.thickness: int = thickness
         self.color_lookup: ColorLookup = color_lookup
 
+    @scene_to_annotator_img_type
     def annotate(
         self,
-        scene: np.ndarray,
+        scene: ImageType,
         detections: Detections,
         custom_color_lookup: Optional[np.ndarray] = None,
-    ) -> np.ndarray:
+    ) -> ImageType:
         """
         Annotates the given scene with polygons based on the provided detections.
 
         Args:
-            scene (np.ndarray): The image where polygons will be drawn.
+            scene (ImageType): The image where polygons will be drawn.
+                `ImageType` is a flexible type, accepting either `numpy.ndarray`
+                or `PIL.Image.Image`.
             detections (Detections): Object detections to annotate.
             custom_color_lookup (Optional[np.ndarray]): Custom color lookup array.
                 Allows to override the default color mapping strategy.
 
         Returns:
-            The annotated image.
+            The annotated image, matching the type of `scene` (`numpy.ndarray`
+                or `PIL.Image.Image`)
 
         Example:
             ```python
@@ -364,23 +384,27 @@ class ColorAnnotator(BaseAnnotator):
         self.color_lookup: ColorLookup = color_lookup
         self.opacity = opacity
 
+    @scene_to_annotator_img_type
     def annotate(
         self,
-        scene: np.ndarray,
+        scene: ImageType,
         detections: Detections,
         custom_color_lookup: Optional[np.ndarray] = None,
-    ) -> np.ndarray:
+    ) -> ImageType:
         """
         Annotates the given scene with box masks based on the provided detections.
 
         Args:
-            scene (np.ndarray): The image where bounding boxes will be drawn.
+            scene (ImageType): The image where bounding boxes will be drawn.
+                `ImageType` is a flexible type, accepting either `numpy.ndarray`
+                or `PIL.Image.Image`.
             detections (Detections): Object detections to annotate.
             custom_color_lookup (Optional[np.ndarray]): Custom color lookup array.
                 Allows to override the default color mapping strategy.
 
         Returns:
-            The annotated image.
+            The annotated image, matching the type of `scene` (`numpy.ndarray`
+                or `PIL.Image.Image`)
 
         Example:
             ```python
@@ -454,23 +478,27 @@ class HaloAnnotator(BaseAnnotator):
         self.color_lookup: ColorLookup = color_lookup
         self.kernel_size: int = kernel_size
 
+    @scene_to_annotator_img_type
     def annotate(
         self,
-        scene: np.ndarray,
+        scene: ImageType,
         detections: Detections,
         custom_color_lookup: Optional[np.ndarray] = None,
-    ) -> np.ndarray:
+    ) -> ImageType:
         """
         Annotates the given scene with halos based on the provided detections.
 
         Args:
-            scene (np.ndarray): The image where masks will be drawn.
+            scene (ImageType): The image where masks will be drawn.
+                `ImageType` is a flexible type, accepting either `numpy.ndarray`
+                or `PIL.Image.Image`.
             detections (Detections): Object detections to annotate.
             custom_color_lookup (Optional[np.ndarray]): Custom color lookup array.
                 Allows to override the default color mapping strategy.
 
         Returns:
-            The annotated image.
+            The annotated image, matching the type of `scene` (`numpy.ndarray`
+                or `PIL.Image.Image`)
 
         Example:
             ```python
@@ -548,23 +576,27 @@ class EllipseAnnotator(BaseAnnotator):
         self.end_angle: int = end_angle
         self.color_lookup: ColorLookup = color_lookup
 
+    @scene_to_annotator_img_type
     def annotate(
         self,
-        scene: np.ndarray,
+        scene: ImageType,
         detections: Detections,
         custom_color_lookup: Optional[np.ndarray] = None,
-    ) -> np.ndarray:
+    ) -> ImageType:
         """
         Annotates the given scene with ellipses based on the provided detections.
 
         Args:
-            scene (np.ndarray): The image where ellipses will be drawn.
+            scene (ImageType): The image where ellipses will be drawn.
+                `ImageType` is a flexible type, accepting either `numpy.ndarray`
+                or `PIL.Image.Image`.
             detections (Detections): Object detections to annotate.
             custom_color_lookup (Optional[np.ndarray]): Custom color lookup array.
                 Allows to override the default color mapping strategy.
 
         Returns:
-            The annotated image.
+            The annotated image, matching the type of `scene` (`numpy.ndarray`
+                or `PIL.Image.Image`)
 
         Example:
             ```python
@@ -635,23 +667,27 @@ class BoxCornerAnnotator(BaseAnnotator):
         self.corner_length: int = corner_length
         self.color_lookup: ColorLookup = color_lookup
 
+    @scene_to_annotator_img_type
     def annotate(
         self,
-        scene: np.ndarray,
+        scene: ImageType,
         detections: Detections,
         custom_color_lookup: Optional[np.ndarray] = None,
-    ) -> np.ndarray:
+    ) -> ImageType:
         """
         Annotates the given scene with box corners based on the provided detections.
 
         Args:
-            scene (np.ndarray): The image where box corners will be drawn.
+            scene (ImageType): The image where box corners will be drawn.
+                `ImageType` is a flexible type, accepting either `numpy.ndarray`
+                or `PIL.Image.Image`.
             detections (Detections): Object detections to annotate.
             custom_color_lookup (Optional[np.ndarray]): Custom color lookup array.
                 Allows to override the default color mapping strategy.
 
         Returns:
-            The annotated image.
+            The annotated image, matching the type of `scene` (`numpy.ndarray`
+                or `PIL.Image.Image`)
 
         Example:
             ```python
@@ -719,23 +755,27 @@ class CircleAnnotator(BaseAnnotator):
         self.thickness: int = thickness
         self.color_lookup: ColorLookup = color_lookup
 
+    @scene_to_annotator_img_type
     def annotate(
         self,
-        scene: np.ndarray,
+        scene: ImageType,
         detections: Detections,
         custom_color_lookup: Optional[np.ndarray] = None,
-    ) -> np.ndarray:
+    ) -> ImageType:
         """
         Annotates the given scene with circles based on the provided detections.
 
         Args:
-            scene (np.ndarray): The image where box corners will be drawn.
+            scene (ImageType): The image where box corners will be drawn.
+                `ImageType` is a flexible type, accepting either `numpy.ndarray`
+                or `PIL.Image.Image`.
             detections (Detections): Object detections to annotate.
             custom_color_lookup (Optional[np.ndarray]): Custom color lookup array.
                 Allows to override the default color mapping strategy.
 
         Returns:
-            The annotated image.
+            The annotated image, matching the type of `scene` (`numpy.ndarray`
+                or `PIL.Image.Image`)
 
         Example:
             ```python
@@ -805,23 +845,27 @@ class DotAnnotator(BaseAnnotator):
         self.position: Position = position
         self.color_lookup: ColorLookup = color_lookup
 
+    @scene_to_annotator_img_type
     def annotate(
         self,
-        scene: np.ndarray,
+        scene: ImageType,
         detections: Detections,
         custom_color_lookup: Optional[np.ndarray] = None,
-    ) -> np.ndarray:
+    ) -> ImageType:
         """
         Annotates the given scene with dots based on the provided detections.
 
         Args:
-            scene (np.ndarray): The image where dots will be drawn.
+            scene (ImageType): The image where dots will be drawn.
+                `ImageType` is a flexible type, accepting either `numpy.ndarray`
+                or `PIL.Image.Image`.
             detections (Detections): Object detections to annotate.
             custom_color_lookup (Optional[np.ndarray]): Custom color lookup array.
                 Allows to override the default color mapping strategy.
 
         Returns:
-            The annotated image.
+            The annotated image, matching the type of `scene` (`numpy.ndarray`
+                or `PIL.Image.Image`)
 
         Example:
             ```python
@@ -929,26 +973,44 @@ class LabelAnnotator:
                 center_x + text_w // 2,
                 center_y + text_h,
             )
+        elif position == Position.CENTER_LEFT:
+            return (
+                center_x - text_w,
+                center_y - text_h // 2,
+                center_x,
+                center_y + text_h // 2,
+            )
+        elif position == Position.CENTER_RIGHT:
+            return (
+                center_x,
+                center_y - text_h // 2,
+                center_x + text_w,
+                center_y + text_h // 2,
+            )
 
+    @scene_to_annotator_img_type
     def annotate(
         self,
-        scene: np.ndarray,
+        scene: ImageType,
         detections: Detections,
         labels: List[str] = None,
         custom_color_lookup: Optional[np.ndarray] = None,
-    ) -> np.ndarray:
+    ) -> ImageType:
         """
         Annotates the given scene with labels based on the provided detections.
 
         Args:
-            scene (np.ndarray): The image where labels will be drawn.
+            scene (ImageType): The image where labels will be drawn.
+                `ImageType` is a flexible type, accepting either `numpy.ndarray`
+                or `PIL.Image.Image`.
             detections (Detections): Object detections to annotate.
             labels (List[str]): Optional. Custom labels for each detection.
             custom_color_lookup (Optional[np.ndarray]): Custom color lookup array.
                 Allows to override the default color mapping strategy.
 
         Returns:
-            The annotated image.
+            The annotated image, matching the type of `scene` (`numpy.ndarray`
+                or `PIL.Image.Image`)
 
         Example:
             ```python
@@ -1049,20 +1111,24 @@ class BlurAnnotator(BaseAnnotator):
         """
         self.kernel_size: int = kernel_size
 
+    @scene_to_annotator_img_type
     def annotate(
         self,
-        scene: np.ndarray,
+        scene: ImageType,
         detections: Detections,
-    ) -> np.ndarray:
+    ) -> ImageType:
         """
         Annotates the given scene by blurring regions based on the provided detections.
 
         Args:
-            scene (np.ndarray): The image where blurring will be applied.
+            scene (ImageType): The image where blurring will be applied.
+                `ImageType` is a flexible type, accepting either `numpy.ndarray`
+                or `PIL.Image.Image`.
             detections (Detections): Object detections to annotate.
 
         Returns:
-            The annotated image.
+            The annotated image, matching the type of `scene` (`numpy.ndarray`
+                or `PIL.Image.Image`)
 
         Example:
             ```python
@@ -1130,24 +1196,28 @@ class TraceAnnotator:
         self.thickness = thickness
         self.color_lookup: ColorLookup = color_lookup
 
+    @scene_to_annotator_img_type
     def annotate(
         self,
-        scene: np.ndarray,
+        scene: ImageType,
         detections: Detections,
         custom_color_lookup: Optional[np.ndarray] = None,
-    ) -> np.ndarray:
+    ) -> ImageType:
         """
         Draws trace paths on the frame based on the detection coordinates provided.
 
         Args:
-            scene (np.ndarray): The image on which the traces will be drawn.
+            scene (ImageType): The image on which the traces will be drawn.
+                `ImageType` is a flexible type, accepting either `numpy.ndarray`
+                or `PIL.Image.Image`.
             detections (Detections): The detections which include coordinates for
                 which the traces will be drawn.
             custom_color_lookup (Optional[np.ndarray]): Custom color lookup array.
                 Allows to override the default color mapping strategy.
 
         Returns:
-            The annotated image.
+            The annotated image, matching the type of `scene` (`numpy.ndarray`
+                or `PIL.Image.Image`)
 
         Example:
             ```python
@@ -1233,16 +1303,20 @@ class HeatMapAnnotator:
         self.top_hue = top_hue
         self.low_hue = low_hue
 
-    def annotate(self, scene: np.ndarray, detections: Detections) -> np.ndarray:
+    @scene_to_annotator_img_type
+    def annotate(self, scene: ImageType, detections: Detections) -> ImageType:
         """
         Annotates the scene with a heatmap based on the provided detections.
 
         Args:
-            scene (np.ndarray): The image where the heatmap will be drawn.
+            scene (ImageType): The image where the heatmap will be drawn.
+                `ImageType` is a flexible type, accepting either `numpy.ndarray`
+                or `PIL.Image.Image`.
             detections (Detections): Object detections to annotate.
 
         Returns:
-            Annotated image.
+            The annotated image, matching the type of `scene` (`numpy.ndarray`
+                or `PIL.Image.Image`)
 
         Example:
             ```python
@@ -1305,21 +1379,25 @@ class PixelateAnnotator(BaseAnnotator):
         """
         self.pixel_size: int = pixel_size
 
+    @scene_to_annotator_img_type
     def annotate(
         self,
-        scene: np.ndarray,
+        scene: ImageType,
         detections: Detections,
-    ) -> np.ndarray:
+    ) -> ImageType:
         """
         Annotates the given scene by pixelating regions based on the provided
             detections.
 
         Args:
-            scene (np.ndarray): The image where pixelating will be applied.
+            scene (ImageType): The image where pixelating will be applied.
+                `ImageType` is a flexible type, accepting either `numpy.ndarray`
+                or `PIL.Image.Image`.
             detections (Detections): Object detections to annotate.
 
         Returns:
-            The annotated image.
+            The annotated image, matching the type of `scene` (`numpy.ndarray`
+                or `PIL.Image.Image`)
 
         Example:
             ```python
@@ -1389,23 +1467,27 @@ class TriangleAnnotator(BaseAnnotator):
         self.position: Position = position
         self.color_lookup: ColorLookup = color_lookup
 
+    @scene_to_annotator_img_type
     def annotate(
         self,
-        scene: np.ndarray,
+        scene: ImageType,
         detections: Detections,
         custom_color_lookup: Optional[np.ndarray] = None,
-    ) -> np.ndarray:
+    ) -> ImageType:
         """
         Annotates the given scene with triangles based on the provided detections.
 
         Args:
-            scene (np.ndarray): The image where triangles will be drawn.
+            scene (ImageType): The image where triangles will be drawn.
+                `ImageType` is a flexible type, accepting either `numpy.ndarray`
+                or `PIL.Image.Image`.
             detections (Detections): Object detections to annotate.
             custom_color_lookup (Optional[np.ndarray]): Custom color lookup array.
                 Allows to override the default color mapping strategy.
 
         Returns:
-            np.ndarray: The annotated image.
+            The annotated image, matching the type of `scene` (`numpy.ndarray`
+                or `PIL.Image.Image`)
 
         Example:
             ```python
@@ -1481,24 +1563,28 @@ class RoundBoxAnnotator(BaseAnnotator):
             raise ValueError("roundness attribute must be float between (0, 1.0]")
         self.roundness: float = roundness
 
+    @scene_to_annotator_img_type
     def annotate(
         self,
-        scene: np.ndarray,
+        scene: ImageType,
         detections: Detections,
         custom_color_lookup: Optional[np.ndarray] = None,
-    ) -> np.ndarray:
+    ) -> ImageType:
         """
         Annotates the given scene with bounding boxes with rounded edges
         based on the provided detections.
 
         Args:
-            scene (np.ndarray): The image where rounded bounding boxes will be drawn.
+            scene (ImageType): The image where rounded bounding boxes will be drawn.
+                `ImageType` is a flexible type, accepting either `numpy.ndarray`
+                or `PIL.Image.Image`.
             detections (Detections): Object detections to annotate.
             custom_color_lookup (Optional[np.ndarray]): Custom color lookup array.
                 Allows to override the default color mapping strategy.
 
         Returns:
-            The annotated image.
+            The annotated image, matching the type of `scene` (`numpy.ndarray`
+                or `PIL.Image.Image`)
 
         Example:
             ```python
@@ -1614,20 +1700,23 @@ class PercentageBarAnnotator(BaseAnnotator):
         if border_thickness is None:
             self.border_thickness = int(0.15 * self.height)
 
+    @scene_to_annotator_img_type
     def annotate(
         self,
-        scene: np.ndarray,
+        scene: ImageType,
         detections: Detections,
         custom_color_lookup: Optional[np.ndarray] = None,
         custom_values: Optional[np.ndarray] = None,
-    ) -> np.ndarray:
+    ) -> ImageType:
         """
         Annotates the given scene with percentage bars based on the provided
         detections. The percentage bars visually represent the confidence or custom
         values associated with each detection.
 
         Args:
-            scene (np.ndarray): The image where percentage bars will be drawn.
+            scene (ImageType): The image where percentage bars will be drawn.
+                `ImageType` is a flexible type, accepting either `numpy.ndarray`
+                or `PIL.Image.Image`.
             detections (Detections): Object detections to annotate.
             custom_color_lookup (Optional[np.ndarray]): Custom color lookup array.
                 Allows to override the default color mapping strategy.
@@ -1638,7 +1727,8 @@ class PercentageBarAnnotator(BaseAnnotator):
                 to be displayed.
 
         Returns:
-            The annotated image.
+            The annotated image, matching the type of `scene` (`numpy.ndarray`
+                or `PIL.Image.Image`)
 
         Example:
             ```python
@@ -1647,7 +1737,7 @@ class PercentageBarAnnotator(BaseAnnotator):
             image = ...
             detections = sv.Detections(...)
 
-            percentage_bar_annotator = sv.BoundingBoxAnnotator()
+            percentage_bar_annotator = sv.PercentageBarAnnotator()
             annotated_frame = percentage_bar_annotator.annotate(
                 scene=image.copy(),
                 detections=detections

supervision/annotators/utils.py

@@ -1,8 +1,12 @@
 from enum import Enum
+from functools import wraps
 from typing import Optional, Union
 
+import cv2
 import numpy as np
+from PIL import Image
 
+from supervision.annotators.base import ImageType
 from supervision.detection.core import Detections
 from supervision.draw.color import Color, ColorPalette
 from supervision.geometry.core import Position
@@ -119,3 +123,28 @@ class Trace:
 
     def get(self, tracker_id: int) -> np.ndarray:
         return self.xy[self.tracker_id == tracker_id]
+
+
+def scene_to_annotator_img_type(annotate_func):
+    """
+    Decorates `BaseAnnotator.annotate` implementations, converts scene to
+    an image type used internally by the annotators, converts back when annotation
+    is complete.
+    """
+
+    @wraps(annotate_func)
+    def wrapper(self, scene: ImageType, *args, **kwargs):
+        if isinstance(scene, np.ndarray):
+            return annotate_func(self, scene, *args, **kwargs)
+
+        if isinstance(scene, Image.Image):
+            scene = np.array(scene)
+            scene = cv2.cvtColor(scene, cv2.COLOR_RGB2BGR)
+            annotated = annotate_func(self, scene, *args, **kwargs)
+            annotated = cv2.cvtColor(annotated, cv2.COLOR_BGR2RGB)
+            annotated = Image.fromarray(annotated)
+            return annotated
+
+        raise ValueError(f"Unsupported image type: {type(scene)}")
+
+    return wrapper

supervision/detection/annotate.py

@@ -1,8 +1,9 @@
 from typing import List, Optional, Union
 
 import cv2
-import numpy as np
 
+from supervision.annotators.base import ImageType
+from supervision.annotators.utils import scene_to_annotator_img_type
 from supervision.detection.core import Detections
 from supervision.draw.color import Color, ColorPalette
 from supervision.utils.internal import deprecated
@@ -45,18 +46,21 @@ class BoxAnnotator:
         self.text_thickness: int = text_thickness
         self.text_padding: int = text_padding
 
+    @scene_to_annotator_img_type
     def annotate(
         self,
-        scene: np.ndarray,
+        scene: ImageType,
         detections: Detections,
         labels: Optional[List[str]] = None,
         skip_label: bool = False,
-    ) -> np.ndarray:
+    ) -> ImageType:
         """
         Draws bounding boxes on the frame using the detections provided.
 
         Args:
-            scene (np.ndarray): The image on which the bounding boxes will be drawn
+            scene (ImageType): The image on which the bounding boxes will be drawn.
+                `ImageType` is a flexible type, accepting either `numpy.ndarray`
+                or `PIL.Image.Image`.
             detections (Detections): The detections for which the
                 bounding boxes will be drawn
             labels (Optional[List[str]]): An optional list of labels
@@ -64,7 +68,8 @@ class BoxAnnotator:
                 corresponding `class_id` will be used as label.
             skip_label (bool): Is set to `True`, skips bounding box label annotation.
         Returns:
-            np.ndarray: The image with the bounding boxes drawn on it
+            ImageType: The image with the bounding boxes drawn on it, matching the
+                type of `scene` (`numpy.ndarray` or `PIL.Image.Image`)
 
         Example:
             ```python

supervision/detection/core.py

@@ -487,7 +487,9 @@ class Detections:
         )
 
         if np.asarray(xyxy).shape[0] == 0:
-            return cls.empty()
+            empty_detection = cls.empty()
+            empty_detection.data = {CLASS_NAME_DATA_FIELD: np.empty(0)}
+            return empty_detection
 
         return cls(
             xyxy=xyxy,

supervision/detection/line_zone.py

@@ -14,6 +14,12 @@ class LineZone:
     This class is responsible for counting the number of objects that cross a
     predefined line.
 
+    <video controls>
+        <source
+            src="https://media.roboflow.com/supervision/cookbooks/count-objects-crossing-the-line-result-1280x720.mp4"
+            type="video/mp4">
+    </video>
+
     !!! warning
 
         LineZone uses the `tracker_id`. Read
@@ -25,7 +31,28 @@ class LineZone:
             to inside.
         out_count (int): The number of objects that have crossed the line from inside
             to outside.
-    """
+
+    Example:
+        ```python
+        import supervision as sv
+        from ultralytics import YOLO
+
+        model = YOLO(<SOURCE_MODEL_PATH>)
+        tracker = sv.ByteTrack()
+        frames_generator = sv.get_video_frames_generator(<SOURCE_VIDEO_PATH>)
+        start, end = sv.Point(x=0, y=1080), sv.Point(x=3840, y=1080)
+        line_zone = sv.LineZone(start=start, end=end)
+
+        for frame in frames_generator:
+            result = model(frame)[0]
+            detections = sv.Detections.from_ultralytics(result)
+            detections = tracker.update_with_detections(detections)
+            crossed_in, crossed_out = line_zone.trigger(detections)
+
+        line_zone.in_count, line_zone.out_count
+        # 7, 2
+        ```
+    """  # noqa: E501 // docs
 
     def __init__(
         self,

supervision/detection/tools/polygon_zone.py

@@ -1,5 +1,5 @@
 from dataclasses import replace
-from typing import Optional, Tuple
+from typing import Iterable, Optional, Tuple
 
 import cv2
 import numpy as np
@@ -10,6 +10,7 @@ from supervision.draw.color import Color
 from supervision.draw.utils import draw_polygon, draw_text
 from supervision.geometry.core import Position
 from supervision.geometry.utils import get_polygon_center
+from supervision.utils.internal import deprecated_parameter
 
 
 class PolygonZone:
@@ -20,21 +21,32 @@ class PolygonZone:
         polygon (np.ndarray): A polygon represented by a numpy array of shape
             `(N, 2)`, containing the `x`, `y` coordinates of the points.
         frame_resolution_wh (Tuple[int, int]): The frame resolution (width, height)
-        triggering_position (Position): The position within the bounding
-            box that triggers the zone (default: Position.BOTTOM_CENTER)
+        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
     """
 
+    @deprecated_parameter(
+        old_parameter="triggering_position",
+        new_parameter="triggering_anchors",
+        map_function=lambda x: [x],
+        warning_message="`{old_parameter}` in `{function_name}` is deprecated and will "
+        "be remove in `supervision-0.23.0`. Use '{new_parameter}' "
+        "instead.",
+    )
     def __init__(
         self,
         polygon: np.ndarray,
         frame_resolution_wh: Tuple[int, int],
-        triggering_position: Position = Position.BOTTOM_CENTER,
+        triggering_anchors: Iterable[Position] = (Position.BOTTOM_CENTER,),
     ):
         self.polygon = polygon.astype(int)
         self.frame_resolution_wh = frame_resolution_wh
-        self.triggering_position = triggering_position
+        self.triggering_anchors = triggering_anchors
+
         self.current_count = 0
 
         width, height = frame_resolution_wh
@@ -59,10 +71,20 @@ class PolygonZone:
             xyxy=detections.xyxy, resolution_wh=self.frame_resolution_wh
         )
         clipped_detections = replace(detections, xyxy=clipped_xyxy)
-        clipped_anchors = np.ceil(
-            clipped_detections.get_anchors_coordinates(anchor=self.triggering_position)
-        ).astype(int)
-        is_in_zone = self.mask[clipped_anchors[:, 1], clipped_anchors[:, 0]]
+        all_clipped_anchors = np.array(
+            [
+                np.ceil(clipped_detections.get_anchors_coordinates(anchor)).astype(int)
+                for anchor in self.triggering_anchors
+            ]
+        )
+
+        is_in_zone = (
+            self.mask[all_clipped_anchors[:, :, 1], all_clipped_anchors[:, :, 0]]
+            .transpose()
+            .astype(bool)
+        )
+        is_in_zone = np.all(is_in_zone, axis=1)
+
         self.current_count = int(np.sum(is_in_zone))
         return is_in_zone.astype(bool)
 
@@ -83,6 +105,7 @@ class PolygonZoneAnnotator:
         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
     """
 
     def __init__(
@@ -94,6 +117,7 @@ class PolygonZoneAnnotator:
         text_scale: float = 0.5,
         text_thickness: int = 1,
         text_padding: int = 10,
+        display_in_zone_count: bool = True,
     ):
         self.zone = zone
         self.color = color
@@ -104,6 +128,7 @@ class PolygonZoneAnnotator:
         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
 
     def annotate(self, scene: np.ndarray, label: Optional[str] = None) -> np.ndarray:
         """
@@ -124,16 +149,17 @@ class PolygonZoneAnnotator:
             thickness=self.thickness,
         )
 
-        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,
-        )
+        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

supervision/detection/tools/smoother.py

@@ -115,4 +115,8 @@ class DetectionsSmoother:
             if track is not None:
                 tracked_detections.append(track)
 
-        return Detections.merge(tracked_detections)
+        detections = Detections.merge(tracked_detections)
+        if len(detections) == 0:
+            detections.tracker_id = np.array([], dtype=int)
+
+        return detections

supervision/detection/utils.py

@@ -59,8 +59,11 @@ def box_iou_batch(boxes_true: np.ndarray, boxes_detection: np.ndarray) -> np.nda
     return area_inter / (area_true[:, None] + area_detection - area_inter)
 
 
-def mask_iou_batch(masks_true: np.ndarray, masks_detection: np.ndarray) -> np.ndarray:
+def _mask_iou_batch_split(
+    masks_true: np.ndarray, masks_detection: np.ndarray
+) -> np.ndarray:
     """
+    Internal function.
     Compute Intersection over Union (IoU) of two sets of masks -
         `masks_true` and `masks_detection`.
 
@@ -74,9 +77,9 @@ def mask_iou_batch(masks_true: np.ndarray, masks_detection: np.ndarray) -> np.nd
     intersection_area = np.logical_and(masks_true[:, None], masks_detection).sum(
         axis=(2, 3)
     )
+
     masks_true_area = masks_true.sum(axis=(1, 2))
     masks_detection_area = masks_detection.sum(axis=(1, 2))
-
     union_area = masks_true_area[:, None] + masks_detection_area - intersection_area
 
     return np.divide(
@@ -87,6 +90,52 @@ def mask_iou_batch(masks_true: np.ndarray, masks_detection: np.ndarray) -> np.nd
     )
 
 
+def mask_iou_batch(
+    masks_true: np.ndarray,
+    masks_detection: np.ndarray,
+    memory_limit: int = 1024 * 5,
+) -> np.ndarray:
+    """
+    Compute Intersection over Union (IoU) of two sets of masks -
+        `masks_true` and `masks_detection`.
+
+    Args:
+        masks_true (np.ndarray): 3D `np.ndarray` representing ground-truth masks.
+        masks_detection (np.ndarray): 3D `np.ndarray` representing detection masks.
+        memory_limit (int, optional): memory limit in MB, default is 1024 * 5 MB (5GB).
+
+    Returns:
+        np.ndarray: Pairwise IoU of masks from `masks_true` and `masks_detection`.
+    """
+    memory = (
+        masks_true.shape[0]
+        * masks_true.shape[1]
+        * masks_true.shape[2]
+        * masks_detection.shape[0]
+        / 1024
+        / 1024
+    )
+    if memory <= memory_limit:
+        return _mask_iou_batch_split(masks_true, masks_detection)
+
+    ious = []
+    step = max(
+        memory_limit
+        * 1024
+        * 1024
+        // (
+            masks_detection.shape[0]
+            * masks_detection.shape[1]
+            * masks_detection.shape[2]
+        ),
+        1,
+    )
+    for i in range(0, masks_true.shape[0], step):
+        ious.append(_mask_iou_batch_split(masks_true[i : i + step], masks_detection))
+
+    return np.vstack(ious)
+
+
 def resize_masks(masks: np.ndarray, max_dimension: int = 640) -> np.ndarray:
     """
     Resize all masks in the array to have a maximum dimension of max_dimension,

supervision/tracker/byte_tracker/core.py

@@ -6,6 +6,7 @@ from supervision.detection.core import Detections
 from supervision.tracker.byte_tracker import matching
 from supervision.tracker.byte_tracker.basetrack import BaseTrack, TrackState
 from supervision.tracker.byte_tracker.kalman_filter import KalmanFilter
+from supervision.utils.internal import deprecated_parameter
 
 
 class STrack(BaseTrack):
@@ -172,26 +173,57 @@ class ByteTrack:
     </video>
 
     Parameters:
-        track_thresh (float, optional): Detection confidence threshold
-            for track activation.
-        track_buffer (int, optional): Number of frames to buffer when a track is lost.
-        match_thresh (float, optional): Threshold for matching tracks with detections.
+        track_activation_threshold (float, optional): Detection confidence threshold
+            for track activation. Increasing track_activation_threshold improves accuracy
+            and stability but might miss true detections. Decreasing it increases
+            completeness but risks introducing noise and instability.
+        lost_track_buffer (int, optional): Number of frames to buffer when a track is lost.
+            Increasing lost_track_buffer enhances occlusion handling, significantly
+            reducing the likelihood of track fragmentation or disappearance caused
+            by brief detection gaps.
+        minimum_matching_threshold (float, optional): Threshold for matching tracks with detections.
+            Increasing minimum_matching_threshold improves accuracy but risks fragmentation.
+            Decreasing it improves completeness but risks false positives and drift.
         frame_rate (int, optional): The frame rate of the video.
     """  # noqa: E501 // docs
 
+    @deprecated_parameter(
+        old_parameter="track_buffer",
+        new_parameter="lost_track_buffer",
+        map_function=lambda x: x,
+        warning_message="`{old_parameter}` in `{function_name}` is deprecated and will "
+        "be remove in `supervision-0.23.0`. Use '{new_parameter}' "
+        "instead.",
+    )
+    @deprecated_parameter(
+        old_parameter="track_thresh",
+        new_parameter="track_activation_threshold",
+        map_function=lambda x: x,
+        warning_message="`{old_parameter}` in `{function_name}` is deprecated and will "
+        "be remove in `supervision-0.23.0`. Use '{new_parameter}' "
+        "instead.",
+    )
+    @deprecated_parameter(
+        old_parameter="match_thresh",
+        new_parameter="minimum_matching_threshold",
+        map_function=lambda x: x,
+        warning_message="`{old_parameter}` in `{function_name}` is deprecated and will "
+        "be remove in `supervision-0.23.0`. Use '{new_parameter}' "
+        "instead.",
+    )
     def __init__(
         self,
-        track_thresh: float = 0.25,
-        track_buffer: int = 30,
-        match_thresh: float = 0.8,
+        track_activation_threshold: float = 0.25,
+        lost_track_buffer: int = 30,
+        minimum_matching_threshold: float = 0.8,
         frame_rate: int = 30,
     ):
-        self.track_thresh = track_thresh
-        self.match_thresh = match_thresh
+        self.track_activation_threshold = track_activation_threshold
+        self.minimum_matching_threshold = minimum_matching_threshold
 
         self.frame_id = 0
-        self.det_thresh = self.track_thresh + 0.1
-        self.max_time_lost = int(frame_rate / 30.0 * track_buffer)
+        self.det_thresh = self.track_activation_threshold + 0.1
+        self.max_time_lost = int(frame_rate / 30.0 * lost_track_buffer)
         self.kalman_filter = KalmanFilter()
 
         self.tracked_tracks: List[STrack] = []
@@ -295,9 +327,9 @@ class ByteTrack:
         scores = tensors[:, 4]
         bboxes = tensors[:, :4]
 
-        remain_inds = scores > self.track_thresh
+        remain_inds = scores > self.track_activation_threshold
         inds_low = scores > 0.1
-        inds_high = scores < self.track_thresh
+        inds_high = scores < self.track_activation_threshold
 
         inds_second = np.logical_and(inds_low, inds_high)
         dets_second = bboxes[inds_second]
@@ -335,7 +367,7 @@ class ByteTrack:
 
         dists = matching.fuse_score(dists, detections)
         matches, u_track, u_detection = matching.linear_assignment(
-            dists, thresh=self.match_thresh
+            dists, thresh=self.minimum_matching_threshold
         )
 
         for itracked, idet in matches:

supervision/utils/internal.py

@@ -1,5 +1,104 @@
 import functools
+import os
 import warnings
+from typing import Callable
+
+
+class SupervisionWarnings(Warning):
+    """Supervision warning category.
+    Set the deprecation warnings visibility for Supervision library.
+    You can set the environment variable SUPERVISON_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("SUPERVISON_DEPRECATION_WARNING") == "0":
+    warnings.simplefilter("ignore", SupervisionWarnings)
+else:
+    warnings.simplefilter("always", SupervisionWarnings)
+
+
+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, optional): A function used to map the value of the old
+            parameter to the new parameter. Defaults to the identity function.
+        warning_message (str, optional): 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__
+
+                warnings.warn(
+                    message=warning_message.format(
+                        function_name=function_name,
+                        old_parameter=old_parameter,
+                        new_parameter=new_parameter,
+                        **message_kwargs,
+                    ),
+                    category=SupervisionWarnings,
+                    stacklevel=2,
+                )
+
+                kwargs[new_parameter] = map_function(kwargs.pop(old_parameter))
+
+            return func(*args, **kwargs)
+
+        return wrapper
+
+    return decorator
 
 
 def deprecated(reason: str):
@@ -8,7 +107,7 @@ def deprecated(reason: str):
         def wrapper(*args, **kwargs):
             warnings.warn(
                 f"{func.__name__} is deprecated: {reason}",
-                category=DeprecationWarning,
+                category=SupervisionWarnings,
                 stacklevel=2,
             )
             return func(*args, **kwargs)

supervision/utils/video.py

@@ -28,7 +28,7 @@ class VideoInfo:
         ```python
         import supervision as sv
 
-        video_info = sv.VideoInfo.from_video_path(video_path='video.mp4')
+        video_info = sv.VideoInfo.from_video_path(video_path=<SOURCE_VIDEO_FILE>)
 
         video_info
         # VideoInfo(width=3840, height=2160, fps=25, total_frames=538)
@@ -75,14 +75,14 @@ class VideoSink:
         ```python
         import supervision as sv
 
-        video_info = sv.VideoInfo.from_video_path('source.mp4')
-        frames_generator = sv.get_video_frames_generator('source.mp4')
+        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.mp4', video_info=video_info) as sink:
+        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
@@ -147,7 +147,7 @@ def get_video_frames_generator(
         ```python
         import supervision as sv
 
-        for frame in sv.get_video_frames_generator(source_path='source_video.mp4'):
+        for frame in sv.get_video_frames_generator(source_path=<SOURCE_VIDEO_PATH>):
             ...
         ```
     """
@@ -191,8 +191,8 @@ def process_video(
             ...
 
         process_video(
-            source_path='...',
-            target_path='...',
+            source_path=<SOURCE_VIDEO_PATH>,
+            target_path=<TARGET_VIDEO_PATH>,
             callback=callback
         )
         ```

test/detection/test_polygonzone.py

@@ -0,0 +1,92 @@
+from contextlib import ExitStack as DoesNotRaise
+from test.test_utils import mock_detections
+
+import numpy as np
+import pytest
+
+import supervision as sv
+
+DETECTION_BOXES = np.array(
+    [
+        [35.0, 35.0, 65.0, 65.0],
+        [60.0, 60.0, 90.0, 90.0],
+        [85.0, 85.0, 115.0, 115.0],
+        [110.0, 110.0, 140.0, 140.0],
+        [135.0, 135.0, 165.0, 165.0],
+        [160.0, 160.0, 190.0, 190.0],
+        [185.0, 185.0, 215.0, 215.0],
+        [210.0, 210.0, 240.0, 240.0],
+        [235.0, 235.0, 265.0, 265.0],
+    ],
+    dtype=np.float32,
+)
+
+DETECTIONS = mock_detections(
+    xyxy=DETECTION_BOXES, class_id=np.array([0, 0, 0, 0, 0, 0, 0, 0, 0])
+)
+
+POLYGON = np.array([[100, 100], [200, 100], [200, 200], [100, 200]])
+FRAME_RESOLUTION = (300, 300)
+
+
+@pytest.mark.parametrize(
+    "detections, polygon_zone, expected_results, exception",
+    [
+        (
+            DETECTIONS,
+            sv.PolygonZone(
+                POLYGON,
+                FRAME_RESOLUTION,
+                triggering_anchors=(
+                    sv.Position.TOP_LEFT,
+                    sv.Position.TOP_RIGHT,
+                    sv.Position.BOTTOM_LEFT,
+                    sv.Position.BOTTOM_RIGHT,
+                ),
+            ),
+            np.array(
+                [False, False, False, True, True, True, False, False, False], dtype=bool
+            ),
+            DoesNotRaise(),
+        ),  # Test all four corners
+        (
+            DETECTIONS,
+            sv.PolygonZone(
+                POLYGON,
+                FRAME_RESOLUTION,
+            ),
+            np.array(
+                [False, False, True, True, True, True, False, False, False], dtype=bool
+            ),
+            DoesNotRaise(),
+        ),  # Test default behaviour when no anchors are provided
+        (
+            DETECTIONS,
+            sv.PolygonZone(
+                POLYGON, FRAME_RESOLUTION, triggering_position=sv.Position.BOTTOM_CENTER
+            ),
+            np.array(
+                [False, False, True, True, True, True, False, False, False], dtype=bool
+            ),
+            DoesNotRaise(),
+        ),  # Test default behaviour with deprecated api.
+        (
+            sv.Detections.empty(),
+            sv.PolygonZone(
+                POLYGON,
+                FRAME_RESOLUTION,
+            ),
+            np.array([], dtype=bool),
+            DoesNotRaise(),
+        ),  # Test empty detections
+    ],
+)
+def test_polygon_zone_trigger(
+    detections: sv.Detections,
+    polygon_zone: sv.PolygonZone,
+    expected_results: np.ndarray,
+    exception: Exception,
+) -> None:
+    with exception:
+        in_zone = polygon_zone.trigger(detections)
+        assert np.all(in_zone == expected_results)