Merge pull request #1655 from roboflow/develop

`supervision-0.25.0` release

.github/workflows/poetry-test.yml

@@ -0,0 +1,37 @@
+name: 🔧 Poetry Check and Installation Test Workflow
+on:
+  push:
+    paths:
+      - 'poetry.lock'
+      - 'pyproject.toml'
+  pull_request:
+    paths:
+      - 'poetry.lock'
+      - 'pyproject.toml'
+  workflow_dispatch:
+
+jobs:
+  poetry-tests:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+        python-version: ["3.8", "3.9", "3.10", "3.11", "3.12", "3.13"]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - name: 📥 Checkout the repository
+        uses: actions/checkout@v4
+
+      - name: 🐍 Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: 📦 Install the base dependencies
+        run: python -m pip install --upgrade poetry
+
+      - name: 🔍 Check the correctness of the project config
+        run: poetry check
+
+      - name: 🚀 Do Install the package Test
+        run: poetry install

.github/workflows/publish-test.yml

@@ -1,17 +1,20 @@
-name: Supervision Test Releases to PyPi
+name: Publish Supervision Pre-Releases to PyPI and TestPyPI
 on:
   push:
     tags:
-      - '[0-9]+.[0-9]+[0-9]+.[0-9]+a[0-9]'
-      - '[0-9]+.[0-9]+[0-9]+.[0-9]+b[0-9]'
-      - '[0-9]+.[0-9]+[0-9]+.[0-9]+rc[0-9]'
+      - "[0-9]+.[0-9]+[0-9]+.[0-9]+a[0-9]"
+      - "[0-9]+.[0-9]+[0-9]+.[0-9]+b[0-9]"
+      - "[0-9]+.[0-9]+[0-9]+.[0-9]+rc[0-9]"
 
   workflow_dispatch:
 
 jobs:
-  build-n-publish:
+  build-and-publish-pre-release-pypi:
     name: Build and publish to PyPI
     runs-on: ubuntu-latest
+    environment: test
+    permissions:
+      id-token: write
     strategy:
       matrix:
         python-version: ["3.10"]
@@ -30,14 +33,11 @@ jobs:
           python -m pip install --upgrade build twine
           python -m build
           twine check --strict dist/*
-      - name: 🚀 Publish distribution to PyPI
-        uses: pypa/gh-action-pypi-publish@release/v1
-        with:
-          user: ${{ secrets.PYPI_USERNAME }}
-          password: ${{ secrets.PYPI_PASSWORD }}
+
+      - name: 🚀 Publish to PyPi
+        uses: pypa/gh-action-pypi-publish@release/v1.10
+
       - name: 🚀 Publish to Test-PyPi
-        uses: pypa/gh-action-pypi-publish@release/v1
+        uses: pypa/gh-action-pypi-publish@release/v1.10
         with:
           repository-url: https://test.pypi.org/legacy/
-          user: ${{ secrets.PYPI_TEST_USERNAME }}
-          password: ${{ secrets.PYPI_TEST_PASSWORD }}

.github/workflows/publish.yml

@@ -1,14 +1,17 @@
-name: Supervision Releases to PyPi
+name: Publish Supervision Releases to PyPI and TestPyPI
 on:
   push:
     tags:
-      - '[0-9]+.[0-9]+[0-9]+.[0-9]'
+      - "[0-9]+.[0-9]+[0-9]+.[0-9]"
 
   workflow_dispatch:
 
 jobs:
-  build:
+  build-and-publish-pre-release:
     runs-on: ubuntu-latest
+    environment: release
+    permissions:
+      id-token: write
     strategy:
       matrix:
         python-version: ["3.10"]
@@ -22,19 +25,16 @@ jobs:
         with:
           python-version: ${{ matrix.python-version }}
 
-      - name:  🏗️ Build source and wheel distributions
+      - name: 🏗️ Build source and wheel distributions
         run: |
           python -m pip install --upgrade build twine
           python -m build
           twine check --strict dist/*
+
       - name: 🚀 Publish to PyPi
-        uses: pypa/gh-action-pypi-publish@release/v1
-        with:
-          user: ${{ secrets.PYPI_USERNAME }}
-          password: ${{ secrets.PYPI_PASSWORD }}
+        uses: pypa/gh-action-pypi-publish@release/v1.10
+
       - name: 🚀 Publish to Test-PyPi
-        uses: pypa/gh-action-pypi-publish@release/v1
+        uses: pypa/gh-action-pypi-publish@release/v1.10
         with:
           repository-url: https://test.pypi.org/legacy/
-          user: ${{ secrets.PYPI_TEST_USERNAME }}
-          password: ${{ secrets.PYPI_TEST_PASSWORD }}

.github/workflows/test.yml

@@ -9,7 +9,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: ["3.8", "3.9", "3.10", "3.11", "3.12"]
+        python-version: ["3.8", "3.9", "3.10", "3.11", "3.12", "3.13"]
     steps:
       - name: 🛎️ Checkout
         uses: actions/checkout@v4

.github/workflows/welcome.yml

@@ -1,18 +0,0 @@
-name: Welcome WorkFlow
-
-on:
-  issues:
-    types: [opened]
-  pull_request_target:
-    types: [opened]
-
-jobs:
-  build:
-    name: 👋 Welcome
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/first-interaction@v1.3.0
-        with:
-          repo-token: ${{ secrets.GITHUB_TOKEN }}
-          issue-message: "Hello there, thank you for opening an Issue ! 🙏🏻 The team was notified and they will get back to you asap."
-          pr-message:  "Hello there, thank you for opening an PR ! 🙏🏻 The team was notified and they will get back to you asap."

.pre-commit-config.yaml

@@ -7,7 +7,7 @@ ci:
 
 repos:
   - repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v4.6.0
+    rev: v5.0.0
     hooks:
       - id: trailing-whitespace
         exclude: test/.*\.py
@@ -25,16 +25,31 @@ repos:
       - id: mixed-line-ending
 
   -   repo: https://github.com/PyCQA/bandit
-      rev: '1.7.9'
+      rev: '1.7.10'
       hooks:
       -   id: bandit
           args: ["-c", "pyproject.toml"]
           additional_dependencies: ["bandit[toml]"]
 
   -   repo: https://github.com/astral-sh/ruff-pre-commit
-      rev: v0.6.2
+      rev: v0.7.3
       hooks:
       -   id: ruff
           args: [--fix, --exit-non-zero-on-fix]
       -   id: ruff-format
           types_or: [ python, pyi, jupyter ]
+
+  # - repo: https://github.com/executablebooks/mdformat
+  #   rev: 0.7.17
+  #   hooks:
+  #     - id: mdformat
+  #       additional_dependencies:
+  #         - "mdformat-mkdocs[recommended]>=2.1.0"
+  #       args: ["--number"]
+
+  - repo: https://github.com/codespell-project/codespell
+    rev: v2.3.0
+    hooks:
+      - id: codespell
+        additional_dependencies:
+          - tomli

CODE_OF_CONDUCT.md

@@ -1,4 +1,3 @@
-
 # Contributor Covenant Code of Conduct
 
 ## Our Pledge
@@ -6,7 +5,7 @@
 We as members, contributors, and leaders pledge to make participation in our
 community a harassment-free experience for everyone, regardless of age, body
 size, visible or invisible disability, ethnicity, sex characteristics, gender
-identity and expression, level of experience, education, socio-economic status,
+identity and expression, level of experience, education, socioeconomic status,
 nationality, personal appearance, race, caste, color, religion, or sexual
 identity and orientation.
 
@@ -18,23 +17,23 @@ diverse, inclusive, and healthy community.
 Examples of behavior that contributes to a positive environment for our
 community include:
 
-* Demonstrating empathy and kindness toward other people
-* Being respectful of differing opinions, viewpoints, and experiences
-* Giving and gracefully accepting constructive feedback
-* Accepting responsibility and apologizing to those affected by our mistakes,
+- Demonstrating empathy and kindness toward other people
+- Being respectful of differing opinions, viewpoints, and experiences
+- Giving and gracefully accepting constructive feedback
+- Accepting responsibility and apologizing to those affected by our mistakes,
   and learning from the experience
-* Focusing on what is best not just for us as individuals, but for the overall
+- Focusing on what is best not just for us as individuals, but for the overall
   community
 
 Examples of unacceptable behavior include:
 
-* The use of sexualized language or imagery, and sexual attention or advances of
+- The use of sexualized language or imagery, and sexual attention or advances of
   any kind
-* Trolling, insulting or derogatory comments, and personal or political attacks
-* Public or private harassment
-* Publishing others' private information, such as a physical or email address,
+- Trolling, insulting or derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information, such as a physical or email address,
   without their explicit permission
-* Other conduct which could reasonably be considered inappropriate in a
+- Other conduct which could reasonably be considered inappropriate in a
   professional setting
 
 ## Enforcement Responsibilities
@@ -121,14 +120,14 @@ version 2.1, available at
 [https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
 
 Community Impact Guidelines were inspired by
-[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+[Mozilla's code of conduct enforcement ladder][mozilla coc].
 
 For answers to common questions about this code of conduct, see the FAQ at
-[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
+[https://www.contributor-covenant.org/faq][faq]. Translations are available at
 [https://www.contributor-covenant.org/translations][translations].
 
+[faq]: https://www.contributor-covenant.org/faq
 [homepage]: https://www.contributor-covenant.org
-[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
-[Mozilla CoC]: https://github.com/mozilla/diversity
-[FAQ]: https://www.contributor-covenant.org/faq
+[mozilla coc]: https://github.com/mozilla/diversity
 [translations]: https://www.contributor-covenant.org/translations
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html

CONTRIBUTING.md

@@ -6,22 +6,22 @@ We are actively improving this library to reduce the amount of work you need to
 
 ## Code of Conduct
 
-Please read and adhere to our [Code of Conduct](CODE_OF_CONDUCT.md). This document outlines the expected behavior for all participants in our project.
+Please read and adhere to our [Code of Conduct](https://supervision.roboflow.com/latest/code_of_conduct/). This document outlines the expected behavior for all participants in our project.
 
 ## Table of Contents
 
 - [Contribution Guidelines](#contribution-guidelines)
-  - [Contributing Features](#contributing-features-)
+    - [Contributing Features](#contributing-features)
 - [How to Contribute Changes](#how-to-contribute-changes)
 - [Installation for Contributors](#installation-for-contributors)
-- [Code Style and Quality](#-code-style-and-quality)
-  - [Pre-commit tool](#pre-commit-tool)
-  - [Docstrings](#docstrings)
-  - [Type checking](#type-checking)
-- [Documentation](#-documentation)
-- [Cookbooks](#-cookbooks)
-- [Tests](#-tests)
-- [License](#-license)
+- [Code Style and Quality](#code-style-and-quality)
+    - [Pre-commit tool](#pre-commit-tool)
+    - [Docstrings](#docstrings)
+    - [Type checking](#type-checking)
+- [Documentation](#documentation)
+- [Cookbooks](#cookbooks)
+- [Tests](#tests)
+- [License](#license)
 
 ## Contribution Guidelines
 
@@ -83,9 +83,10 @@ git push -u origin <your_branch_name>
 
 Use conventional commit messages to clearly describe your changes. The format is:
 
-<type>[optional scope]: <description>
+<type>\[optional scope\]: <description>
 
 Common types include:
+
 - feat: A new feature
 - fix: A bug fix
 - docs: Documentation only changes
@@ -128,40 +129,47 @@ PRs must pass all tests and linting requirements before they can be merged.
 Before starting your work on the project, set up your development environment:
 
 1. Clone your fork of the project:
-   ```bash
-   git clone https://github.com/YOUR_USERNAME/supervision.git
-   cd supervision
-   ```
-   Replace `YOUR_USERNAME` with your GitHub username.
+
+    ```bash
+    git clone https://github.com/YOUR_USERNAME/supervision.git
+    cd supervision
+    ```
+
+    Replace `YOUR_USERNAME` with your GitHub username.
 
 2. Create and activate a virtual environment:
-   ```bash
-   python3 -m venv .venv
-   source .venv/bin/activate
-   ```
+
+    ```bash
+    python3 -m venv .venv
+    source .venv/bin/activate
+    ```
 
 3. Install Poetry:
 
-   Using pip:
-   ```bash
-   pip install -U pip setuptools
-   pip install poetry
-   ```
+    Using pip:
 
-   Or using pipx (recommended for global installation):
-   ```bash
-   pipx install poetry
-   ```
+    ```bash
+    pip install -U pip setuptools
+    pip install poetry
+    ```
+
+    Or using pipx (recommended for global installation):
+
+    ```bash
+    pipx install poetry
+    ```
 
 4. Install project dependencies:
-   ```bash
-   poetry install
-   ```
+
+    ```bash
+    poetry install
+    ```
 
 5. Run pytest to verify the setup:
-   ```bash
-   poetry run pytest
-   ```
+
+    ```bash
+    poetry run pytest
+    ```
 
 ## 🎨 Code Style and Quality
 

README.md

@@ -8,11 +8,11 @@
     </a>
   </p>
 
-  <br>
+<br>
 
 [notebooks](https://github.com/roboflow/notebooks) | [inference](https://github.com/roboflow/inference) | [autodistill](https://github.com/autodistill/autodistill) | [maestro](https://github.com/roboflow/multimodal-maestro)
 
-  <br>
+<br>
 
 [![version](https://badge.fury.io/py/supervision.svg)](https://badge.fury.io/py/supervision)
 [![downloads](https://img.shields.io/pypi/dm/supervision)](https://pypistats.org/packages/supervision)
@@ -21,16 +21,19 @@
 [![python-version](https://img.shields.io/pypi/pyversions/supervision)](https://badge.fury.io/py/supervision)
 [![colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/roboflow/supervision/blob/main/demo.ipynb)
 [![gradio](https://img.shields.io/badge/%F0%9F%A4%97%20Hugging%20Face-Spaces-blue)](https://huggingface.co/spaces/Roboflow/Annotators)
-[![discord](https://img.shields.io/discord/1159501506232451173)](https://discord.gg/GbfgXGJ8Bk)
+[![discord](https://img.shields.io/discord/1159501506232451173?logo=discord&label=discord&labelColor=fff&color=5865f2&link=https%3A%2F%2Fdiscord.gg%2FGbfgXGJ8Bk)](https://discord.gg/GbfgXGJ8Bk)
 [![built-with-material-for-mkdocs](https://img.shields.io/badge/Material_for_MkDocs-526CFE?logo=MaterialForMkDocs&logoColor=white)](https://squidfunk.github.io/mkdocs-material/)
+
+  <div align="center">
+    <a href="https://trendshift.io/repositories/124"  target="_blank"><img src="https://trendshift.io/api/badge/repositories/124" alt="roboflow%2Fsupervision | Trendshift" style="width: 250px; height: 55px;" width="250" height="55"/></a>
+  </div>
+
 </div>
 
 ## 👋 hello
 
 **We write your reusable computer vision tools.** Whether you need to load your dataset from your hard drive, draw detections on an image or video, or count how many detections are in a zone. You can count on us! 🤝
 
-[![supervision-hackfest](https://github.com/roboflow/supervision/assets/26109316/c05cc954-b9a6-4ed5-9a52-d0b4b619ff65)](https://github.com/orgs/roboflow/projects)
-
 ## 💻 install
 
 Pip install the supervision package in a
@@ -54,7 +57,7 @@ import supervision as sv
 from ultralytics import YOLO
 
 image = cv2.imread(...)
-model = YOLO('yolov8s.pt')
+model = YOLO("yolov8s.pt")
 result = model(image)[0]
 detections = sv.Detections.from_ultralytics(result)
 
@@ -67,21 +70,21 @@ len(detections)
 
 - inference
 
-    Running with [Inference](https://github.com/roboflow/inference) requires a [Roboflow API KEY](https://docs.roboflow.com/api-reference/authentication#retrieve-an-api-key).
+  Running with [Inference](https://github.com/roboflow/inference) requires a [Roboflow API KEY](https://docs.roboflow.com/api-reference/authentication#retrieve-an-api-key).
 
-    ```python
-    import cv2
-    import supervision as sv
-    from inference import get_model
+  ```python
+  import cv2
+  import supervision as sv
+  from inference import get_model
 
-    image = cv2.imread(...)
-    model = get_model(model_id="yolov8s-640", api_key=<ROBOFLOW API KEY>)
-    result = model.infer(image)[0]
-    detections = sv.Detections.from_inference(result)
+  image = cv2.imread(...)
+  model = get_model(model_id="yolov8s-640", api_key=<ROBOFLOW API KEY>)
+  result = model.infer(image)[0]
+  detections = sv.Detections.from_inference(result)
 
-    len(detections)
-    # 5
-    ```
+  len(detections)
+  # 5
+  ```
 
 </details>
 
@@ -98,9 +101,8 @@ detections = sv.Detections(...)
 
 box_annotator = sv.BoxAnnotator()
 annotated_frame = box_annotator.annotate(
-    scene=image.copy(),
-    detections=detections
-)
+  scene=image.copy(),
+  detections=detections)
 ```
 
 https://github.com/roboflow/supervision/assets/26109316/691e219c-0565-4403-9218-ab5644f39bce
@@ -158,7 +160,7 @@ for path, image, annotation in ds:
   test_dataset, valid_dataset = test_dataset.split(split_ratio=0.5)
 
   len(train_dataset), len(test_dataset), len(valid_dataset)
-  # (700, 150, 150)
+  # (700, 150, 150)
   ```
 
 - merge
@@ -166,21 +168,21 @@ for path, image, annotation in ds:
   ```python
   ds_1 = sv.DetectionDataset(...)
   len(ds_1)
-  # 100
+  # 100
   ds_1.classes
-  # ['dog', 'person']
+  # ['dog', 'person']
 
   ds_2 = sv.DetectionDataset(...)
   len(ds_2)
   # 200
   ds_2.classes
-  # ['cat']
+  # ['cat']
 
   ds_merged = sv.DetectionDataset.merge([ds_1, ds_2])
   len(ds_merged)
-  # 300
+  # 300
   ds_merged.classes
-  # ['cat', 'dog', 'person']
+  # ['cat', 'dog', 'person']
   ```
 
 - save
@@ -266,7 +268,7 @@ We love your input! Please see our [contributing guide](https://github.com/robof
 
 <div align="center">
 
-  <div align="center">
+<div align="center">
       <a href="https://youtube.com/roboflow">
           <img
             src="https://media.roboflow.com/notebooks/template/icons/purple/youtube.png?ik-sdk-version=javascript-1.4.3&updatedAt=1672949634652"
@@ -295,7 +297,7 @@ We love your input! Please see our [contributing guide](https://github.com/robof
           />
       </a>
       <img src="https://raw.githubusercontent.com/ultralytics/assets/main/social/logo-transparent.png" width="3%"/>
-      <a href="https://disuss.roboflow.com">
+      <a href="https://discuss.roboflow.com">
           <img
             src="https://media.roboflow.com/notebooks/template/icons/purple/forum.png?ik-sdk-version=javascript-1.4.3&updatedAt=1672949633584"
             width="3%"

demo.ipynb

@@ -1357,7 +1357,7 @@
     }
    ],
    "source": [
-    "IMAGE_NAME = list(ds.images.keys())[0]\n",
+    "IMAGE_NAME = next(iter(ds.images.keys()))\n",
     "\n",
     "image = ds.images[IMAGE_NAME]\n",
     "annotations = ds.annotations[IMAGE_NAME]\n",

docs/assets.md

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

docs/changelog.md

@@ -1,6 +1,291 @@
+# CHANGELOG
+
+### 0.25.0 <small>Nov 12, 2024</small>
+
+- No removals or deprecations in this release!
+
+- Essential update to the [`LineZone`](https://supervision.roboflow.com/0.25.0/detection/tools/line_zone/): when computing line crossings, detections that jitter might be counted twice (or more). This can now be solved with the `minimum_crossing_threshold` argument. If you set it to `2` or more, extra frames will be used to confirm the crossing, improving the accuracy significantly. ([#1540](https://github.com/roboflow/supervision/pull/1540))
+
+- It is now possible to track objects detected as [`KeyPoints`](https://supervision.roboflow.com/0.25.0/keypoint/core/#supervision.keypoint.core.KeyPoints). See the complete step-by-step guide in the [Object Tracking Guide](https://supervision.roboflow.com/latest/how_to/track_objects/#keypoints). ([#1658](https://github.com/roboflow/supervision/pull/1658))
+
+```python
+import numpy as np
+import supervision as sv
+from ultralytics import YOLO
+
+model = YOLO("yolov8m-pose.pt")
+tracker = sv.ByteTrack()
+trace_annotator = sv.TraceAnnotator()
+
+def callback(frame: np.ndarray, _: int) -> np.ndarray:
+    results = model(frame)[0]
+    key_points = sv.KeyPoints.from_ultralytics(results)
+
+    detections = key_points.as_detections()
+    detections = tracker.update_with_detections(detections)
+
+    annotated_image = trace_annotator.annotate(frame.copy(), detections)
+    return annotated_image
+
+sv.process_video(
+    source_path="input_video.mp4",
+    target_path="output_video.mp4",
+    callback=callback
+)
+```
+
+- Added `is_empty` method to [`KeyPoints`](https://supervision.roboflow.com/0.25.0/keypoint/core/#supervision.keypoint.core.KeyPoints) to check if there are any keypoints in the object. ([#1658](https://github.com/roboflow/supervision/pull/1658))
+
+- Added `as_detections` method to [`KeyPoints`](https://supervision.roboflow.com/0.25.0/keypoint/core/#supervision.keypoint.core.KeyPoints) that converts `KeyPoints` to `Detections`. ([#1658](https://github.com/roboflow/supervision/pull/1658))
+
+- Added a new video to `supervision[assets]`. ([#1657](https://github.com/roboflow/supervision/pull/1657))
+
+```python
+from supervision.assets import download_assets, VideoAssets
+
+path_to_video = download_assets(VideoAssets.SKIING)
+```
+
+- Supervision can now be used with [`Python 3.13`](https://docs.python.org/3/whatsnew/3.13.html). The most renowned update is the ability to run Python [without Global Interpreter Lock (GIL)](https://docs.python.org/3/whatsnew/3.13.html#whatsnew313-free-threaded-cpython). We expect support for this among our dependencies to be inconsistent, but if you do attempt it - let us know the results! ([#1595](https://github.com/roboflow/supervision/pull/1595))
+
+- Added [`Mean Average Recall`](https://supervision.roboflow.com/latest/metrics/mean_average_recall/) mAR metric, which returns a recall score, averaged over IoU thresholds, detected object classes, and limits imposed on maximum considered detections. ([#1661](https://github.com/roboflow/supervision/pull/1661))
+
+```python
+import supervision as sv
+from supervision.metrics import MeanAverageRecall
+
+predictions = sv.Detections(...)
+targets = sv.Detections(...)
+
+map_metric = MeanAverageRecall()
+map_result = map_metric.update(predictions, targets).compute()
+
+map_result.plot()
+```
+
+- Added [`Precision`](https://supervision.roboflow.com/latest/metrics/precision/) and [`Recall`](https://supervision.roboflow.com/latest/metrics/recall/) metrics, providing a baseline for comparing model outputs to ground truth or another model ([#1609](https://github.com/roboflow/supervision/pull/1609))
+
+```python
+import supervision as sv
+from supervision.metrics import Recall
+
+predictions = sv.Detections(...)
+targets = sv.Detections(...)
+
+recall_metric = Recall()
+recall_result = recall_metric.update(predictions, targets).compute()
+
+recall_result.plot()
+```
+
+- All Metrics now support Oriented Bounding Boxes (OBB) ([#1593](https://github.com/roboflow/supervision/pull/1593))
+
+```python
+import supervision as sv
+from supervision.metrics import F1_Score
+
+predictions = sv.Detections(...)
+targets = sv.Detections(...)
+
+f1_metric = MeanAverageRecall(metric_target=sv.MetricTarget.ORIENTED_BOUNDING_BOXES)
+f1_result = f1_metric.update(predictions, targets).compute()
+```
+
+- Introducing Smart Labels! When `smart_position` is set for [`LabelAnnotator`](https://supervision.roboflow.com/0.25.0/detection/annotators/#supervision.annotators.core.LabelAnnotator), [`RichLabelAnnotator`](https://supervision.roboflow.com/0.25.0/detection/annotators/#supervision.annotators.core.RichLabelAnnotator) or [`VertexLabelAnnotator`](https://supervision.roboflow.com/0.25.0/detection/annotators/#supervision.annotators.core.RichLabelAnnotator), the labels will move around to avoid overlapping others. ([#1625](https://github.com/roboflow/supervision/pull/1625))
+
+```python
+import supervision as sv
+from ultralytics import YOLO
+
+image = cv2.imread("image.jpg")
+
+label_annotator = sv.LabelAnnotator(smart_position=True)
+
+model = YOLO("yolo11m.pt")
+results = model(image)[0]
+detections = sv.Detections.from_ultralytics(results)
+
+annotated_frame = label_annotator.annotate(first_frame.copy(), detections)
+sv.plot_image(annotated_frame)
+```
+
+- Added the `metadata` variable to [`Detections`](https://supervision.roboflow.com/0.25.0/detection/core/#supervision.detection.core.Detections). It allows you to store custom data per-image, rather than per-detected-object as was possible with `data` variable. For example, `metadata` could be used to store the source video path, camera model or camera parameters. ([#1589](https://github.com/roboflow/supervision/pull/1589))
+
+```python
+import supervision as sv
+from ultralytics import YOLO
+
+model = YOLO("yolov8m")
+
+result = model("image.png")[0]
+detections = sv.Detections.from_ultralytics(result)
+
+# Items in `data` must match length of detections
+object_ids = [num for num in range(len(detections))]
+detections.data["object_number"] = object_ids
+
+# Items in `metadata` can be of any length.
+detections.metadata["camera_model"] = "Luxonis OAK-D"
+```
+
+- Added a `py.typed` type hints metafile. It should provide a stronger signal to type annotators and IDEs that type support is available. ([#1586](https://github.com/roboflow/supervision/pull/1586))
+
+- `ByteTrack` no longer requires `detections` to have a `class_id` ([#1637](https://github.com/roboflow/supervision/pull/1637))
+- `draw_line`, `draw_rectangle`, `draw_filled_rectangle`, `draw_polygon`, `draw_filled_polygon` and `PolygonZoneAnnotator` now comes with a default color ([#1591](https://github.com/roboflow/supervision/pull/1591))
+- Dataset classes are treated as case-sensitive when merging multiple datasets. ([#1643](https://github.com/roboflow/supervision/pull/1643))
+- Expanded [metrics documentation](https://supervision.roboflow.com/0.25.0/metrics/f1_score/) with example plots and printed results ([#1660](https://github.com/roboflow/supervision/pull/1660))
+- Added usage example for polygon zone ([#1608](https://github.com/roboflow/supervision/pull/1608))
+- Small improvements to error handling in polygons: ([#1602](https://github.com/roboflow/supervision/pull/1602))
+
+- Updated [`ByteTrack`](https://supervision.roboflow.com/0.25.0/trackers/#supervision.tracker.byte_tracker.core.ByteTrack), removing shared variables. Previously, multiple instances of `ByteTrack` would share some date, requiring liberal use of `tracker.reset()`. ([#1603](https://github.com/roboflow/supervision/pull/1603)), ([#1528](https://github.com/roboflow/supervision/pull/1528))
+- Fixed a bug where `class_agnostic` setting in `MeanAveragePrecision` would not work. ([#1577](https://github.com/roboflow/supervision/pull/1577)) hacktoberfest
+- Removed welcome workflow from our CI system. ([#1596](https://github.com/roboflow/supervision/pull/1596))
+
+- Large refactor of `ByteTrack`: STrack moved to separate class, removed superfluous `BaseTrack` class, removed unused variables ([#1603](https://github.com/roboflow/supervision/pull/1603))
+- Large refactor of `RichLabelAnnotator`, matching its contents with `LabelAnnotator`. ([#1625](https://github.com/roboflow/supervision/pull/1625))
+
+### 0.24.0 <small>Oct 4, 2024</small>
+
+- Added [F1 score](https://supervision.roboflow.com/0.24.0/metrics/f1_score/#supervision.metrics.f1_score.F1Score) as a new metric for detection and segmentation. [#1521](https://github.com/roboflow/supervision/pull/1521)
+
+```python
+import supervision as sv
+from supervision.metrics import F1Score
+
+predictions = sv.Detections(...)
+targets = sv.Detections(...)
+
+f1_metric = F1Score()
+f1_result = f1_metric.update(predictions, targets).compute()
+
+print(f1_result)
+print(f1_result.f1_50)
+print(f1_result.small_objects.f1_50)
+```
+
+- Added new cookbook: [Small Object Detection with SAHI](https://supervision.roboflow.com/0.24.0/notebooks/small-object-detection-with-sahi/). This cookbook provides a detailed guide on using [`InferenceSlicer`](https://supervision.roboflow.com/0.24.0/detection/tools/inference_slicer/) for small object detection. [#1483](https://github.com/roboflow/supervision/pull/1483)
+
+- Added an [Embedded Workflow](https://roboflow.com/workflows), which allows you to [preview annotators](https://supervision.roboflow.com/0.24.0/detection/annotators/). [#1533](https://github.com/roboflow/supervision/pull/1533)
+
+- Enhanced [`LineZoneAnnotator`](https://supervision.roboflow.com/0.24.0/detection/tools/line_zone/#supervision.detection.line_zone.LineZoneAnnotator), allowing the labels to align with the line, even when it's not horizontal. Also, you can now disable text background, and choose to draw labels off-center which minimizes overlaps for multiple [`LineZone`](https://supervision.roboflow.com/0.24.0/detection/tools/line_zone/#supervision.detection.line_zone.LineZone) labels. [#854](https://github.com/roboflow/supervision/pull/854)
+
+```python
+import supervision as sv
+import cv2
+
+image = cv2.imread("<SOURCE_IMAGE_PATH>")
+
+line_zone = sv.LineZone(
+    start=sv.Point(0, 100),
+    end=sv.Point(50, 200)
+)
+line_zone_annotator = sv.LineZoneAnnotator(
+    text_orient_to_line=True,
+    display_text_box=False,
+    text_centered=False
+)
+
+annotated_frame = line_zone_annotator.annotate(
+    frame=image.copy(), line_counter=line_zone
+)
+
+sv.plot_image(frame)
+```
+
+- Added per-class counting capabilities to [`LineZone`](https://supervision.roboflow.com/0.24.0/detection/tools/line_zone/#supervision.detection.line_zone.LineZone) and introduced [`LineZoneAnnotatorMulticlass`](https://supervision.roboflow.com/0.24.0/detection/tools/line_zone/#supervision.detection.line_zone.LineZoneAnnotatorMulticlass) for visualizing the counts per class. This feature allows tracking of individual classes crossing a line, enhancing the flexibility of use cases like traffic monitoring or crowd analysis. [#1555](https://github.com/roboflow/supervision/pull/1555)
+
+```python
+import supervision as sv
+import cv2
+
+image = cv2.imread("<SOURCE_IMAGE_PATH>")
+
+line_zone = sv.LineZone(
+    start=sv.Point(0, 100),
+    end=sv.Point(50, 200)
+)
+line_zone_annotator = sv.LineZoneAnnotatorMulticlass()
+
+frame = line_zone_annotator.annotate(
+    frame=frame, line_zones=[line_zone]
+)
+
+sv.plot_image(frame)
+```
+
+- Added [`from_easyocr`](https://supervision.roboflow.com/0.24.0/detection/core/#supervision.detection.core.Detections.from_easyocr), allowing integration of OCR results into the supervision framework. [EasyOCR](https://github.com/JaidedAI/EasyOCR) is an open-source optical character recognition (OCR) library that can read text from images. [#1515](https://github.com/roboflow/supervision/pull/1515)
+
+```python
+import supervision as sv
+import easyocr
+import cv2
+
+image = cv2.imread("<SOURCE_IMAGE_PATH>")
+
+reader = easyocr.Reader(["en"])
+result = reader.readtext("<SOURCE_IMAGE_PATH>", paragraph=True)
+detections = sv.Detections.from_easyocr(result)
+
+box_annotator = sv.BoxAnnotator(color_lookup=sv.ColorLookup.INDEX)
+label_annotator = sv.LabelAnnotator(color_lookup=sv.ColorLookup.INDEX)
+
+annotated_image = image.copy()
+annotated_image = box_annotator.annotate(scene=annotated_image, detections=detections)
+annotated_image = label_annotator.annotate(scene=annotated_image, detections=detections)
+
+sv.plot_image(annotated_image)
+```
+
+- Added [`oriented_box_iou_batch`](https://supervision.roboflow.com/0.24.0/detection/utils/#supervision.detection.utils.oriented_box_iou_batch) function to `detection.utils`. This function computes Intersection over Union (IoU) for oriented or rotated bounding boxes (OBB). [#1502](https://github.com/roboflow/supervision/pull/1502)
+
+```python
+import numpy as np
+
+boxes_true = np.array([[[1, 0], [0, 1], [3, 4], [4, 3]]])
+boxes_detection = np.array([[[1, 1], [2, 0], [4, 2], [3, 3]]])
+ious = sv.oriented_box_iou_batch(boxes_true, boxes_detection)
+print("IoU between true and detected boxes:", ious)
+```
+
+- Extended [`PolygonZoneAnnotator`](https://supervision.roboflow.com/0.24.0/detection/tools/polygon_zone/#supervision.detection.tools.polygon_zone.PolygonZoneAnnotator) to allow setting opacity when drawing zones, providing enhanced visualization by filling the zone with adjustable transparency. [#1527](https://github.com/roboflow/supervision/pull/1527)
+
+```python
+import cv2
+from ncnn.model_zoo import get_model
+import supervision as sv
+
+image = cv2.imread("<SOURCE_IMAGE_PATH>")
+model = get_model(
+    "yolov8s",
+    target_size=640,
+    prob_threshold=0.5,
+    nms_threshold=0.45,
+    num_threads=4,
+    use_gpu=True,
+)
+result = model(image)
+detections = sv.Detections.from_ncnn(result)
+```
+
+!!! failure "Removed"
+
+    The `frame_resolution_wh` parameter in [`PolygonZone`](https://supervision.roboflow.com/0.24.0/detection/tools/polygon_zone/#supervision.detection.tools.polygon_zone.PolygonZone) has been removed.
+
+!!! failure "Removed"
+
+    Supervision installation methods `"headless"` and `"desktop"` were removed, as they are no longer needed. `pip install supervision[headless]` will install the base library and harmlessly warn of non-existent extras.
+
+- Supervision now depends on `opencv-python` rather than `opencv-python-headless`. [#1530](https://github.com/roboflow/supervision/pull/1530)
+
+- Fixed the COCO 101 point Average Precision algorithm to correctly interpolate precision, providing a more precise calculation of average precision without averaging out intermediate values. [#1500](https://github.com/roboflow/supervision/pull/1500)
+
+- Resolved miscellaneous issues highlighted when building documentation. This mostly includes whitespace adjustments and type inconsistencies. Updated documentation for clarity and fixed formatting issues. Added explicit version for `mkdocstrings-python`. [#1549](https://github.com/roboflow/supervision/pull/1549)
+
+- Enabled and fixed Ruff rules for code formatting, including changes like avoiding unnecessary iterable allocations and using Optional for default mutable arguments. [#1526](https://github.com/roboflow/supervision/pull/1526)
+
 ### 0.23.0 <small>Aug 28, 2024</small>
 
-- Added [#930](https://github.com/roboflow/supervision/pull/930): `IconAnnotator`, a [new annotator](https://supervision.roboflow.com/latest/detection/annotators/#supervision.annotators.core.IconAnnotator) that allows drawing icons on each detection. Useful if you want to draw a specific icon for each class.
+- Added [#930](https://github.com/roboflow/supervision/pull/930): `IconAnnotator`, a [new annotator](https://supervision.roboflow.com/0.23.0/detection/annotators/#supervision.annotators.core.IconAnnotator) that allows drawing icons on each detection. Useful if you want to draw a specific icon for each class.
 
 ```python
 import supervision as sv
@@ -31,7 +316,7 @@ annotated_frame = icon_annotator.annotate(
 )
 ```
 
-- Added [#1385](https://github.com/roboflow/supervision/pull/1385): [`BackgroundColorAnnotator`](https://supervision.roboflow.com/latest/detection/annotators/#supervision.annotators.core.BackgroundColorAnnotator), that draws an overlay on the background images of the detections.
+- Added [#1385](https://github.com/roboflow/supervision/pull/1385): [`BackgroundColorAnnotator`](https://supervision.roboflow.com/0.23.0/detection/annotators/#supervision.annotators.core.BackgroundColorAnnotator), that draws an overlay on the background images of the detections.
 
 ```python
 import supervision as sv
@@ -50,7 +335,7 @@ annotated_frame = background_overlay_annotator.annotate(
 )
 ```
 
-- Added [#1386](https://github.com/roboflow/supervision/pull/1386): Support for Transformers v5 functions in [`sv.Detections.from_transformers`](https://supervision.roboflow.com/latest/detection/core/#supervision.detection.core.Detections.from_transformers). This includes the `DetrImageProcessor` methods `post_process_object_detection`, `post_process_panoptic_segmentation`, `post_process_semantic_segmentation`, and `post_process_instance_segmentation`.
+- Added [#1386](https://github.com/roboflow/supervision/pull/1386): Support for Transformers v5 functions in [`sv.Detections.from_transformers`](https://supervision.roboflow.com/0.23.0/detection/core/#supervision.detection.core.Detections.from_transformers). This includes the `DetrImageProcessor` methods `post_process_object_detection`, `post_process_panoptic_segmentation`, `post_process_semantic_segmentation`, and `post_process_instance_segmentation`.
 
 ```python
 import torch
@@ -76,7 +361,7 @@ detections = sv.Detections.from_transformers(
     id2label=model.config.id2label)
 ```
 
-- Added [#1354](https://github.com/roboflow/supervision/pull/1354): Ultralytics SAM (Segment Anything Model) support in [`sv.Detections.from_ultralytics`](https://supervision.roboflow.com/latest/detection/core/#supervision.detection.core.Detections.from_ultralytics). [SAM2](https://sam2.metademolab.com/) was released during this update, and is already supported via [`sv.Detections.from_sam`](https://supervision.roboflow.com/latest/detection/core/#supervision.detection.core.Detections.from_sam).
+- Added [#1354](https://github.com/roboflow/supervision/pull/1354): Ultralytics SAM (Segment Anything Model) support in [`sv.Detections.from_ultralytics`](https://supervision.roboflow.com/0.23.0/detection/core/#supervision.detection.core.Detections.from_ultralytics). [SAM2](https://sam2.metademolab.com/) was released during this update, and is already supported via [`sv.Detections.from_sam`](https://supervision.roboflow.com/0.23.0/detection/core/#supervision.detection.core.Detections.from_sam).
 
 ```python
 import supervision as sv
@@ -84,7 +369,6 @@ from segment_anything import (
     sam_model_registry,
     SamAutomaticMaskGenerator
 )
-
 sam_model_reg = sam_model_registry[MODEL_TYPE]
 sam = sam_model_reg(checkpoint=CHECKPOINT_PATH).to(device=DEVICE)
 mask_generator = SamAutomaticMaskGenerator(sam)
@@ -92,15 +376,15 @@ sam_result = mask_generator.generate(IMAGE)
 detections = sv.Detections.from_sam(sam_result=sam_result)
 ```
 
-- Added [#1458](https://github.com/roboflow/supervision/pull/1458): `outline_color` options for [`TriangleAnnotator`](https://supervision.roboflow.com/latest/detection/annotators/#supervision.annotators.core.TriangleAnnotator) and [`DotAnnotator`](https://supervision.roboflow.com/latest/detection/annotators/#supervision.annotators.core.DotAnnotator).
+- Added [#1458](https://github.com/roboflow/supervision/pull/1458): `outline_color` options for [`TriangleAnnotator`](https://supervision.roboflow.com/0.23.0/detection/annotators/#supervision.annotators.core.TriangleAnnotator) and [`DotAnnotator`](https://supervision.roboflow.com/0.23.0/detection/annotators/#supervision.annotators.core.DotAnnotator).
 
-- Added [#1409](https://github.com/roboflow/supervision/pull/1409): `text_color` option for [`VertexLabelAnnotator`](https://supervision.roboflow.com/latest/keypoint/annotators/#supervision.keypoint.annotators.VertexLabelAnnotator) keypoint annotator.
+- Added [#1409](https://github.com/roboflow/supervision/pull/1409): `text_color` option for [`VertexLabelAnnotator`](https://supervision.roboflow.com/0.23.0/keypoint/annotators/#supervision.keypoint.annotators.VertexLabelAnnotator) keypoint annotator.
 
-- Changed [#1434](https://github.com/roboflow/supervision/pull/1434): [`InferenceSlicer`](https://supervision.roboflow.com/latest/detection/tools/inference_slicer/) now features an `overlap_ratio_wh` parameter, making it easier to compute slice sizes when handling overlapping slices.
+- Changed [#1434](https://github.com/roboflow/supervision/pull/1434): [`InferenceSlicer`](https://supervision.roboflow.com/0.23.0/detection/tools/inference_slicer/) now features an `overlap_wh` parameter, making it easier to compute slice sizes when handling overlapping slices.
 
 - Fix [#1448](https://github.com/roboflow/supervision/pull/1448): Various annotator type issues have been resolved, supporting expanded error handling.
 
-- Fix [#1348](https://github.com/roboflow/supervision/pull/1348): Introduced a new method for [seeking to a specific video frame](https://supervision.roboflow.com/latest/utils/video/#supervision.utils.video.get_video_frames_generator), addressing cases where traditional seek methods were failing. It can be enabled with `iterative_seek=True`.
+- Fix [#1348](https://github.com/roboflow/supervision/pull/1348): Introduced a new method for [seeking to a specific video frame](https://supervision.roboflow.com/0.23.0/utils/video/#supervision.utils.video.get_video_frames_generator), addressing cases where traditional seek methods were failing. It can be enabled with `iterative_seek=True`.
 
 ```python
 import supervision as sv
@@ -121,7 +405,7 @@ for frame in sv.get_video_frames_generator(
 
 !!! failure "Removed"
 
-    The `triggering_position ` parameter in [`sv.PolygonZone`](detection/tools/polygon_zone.md/#supervision.detection.tools.polygon_zone.PolygonZone) was removed as of `supervision-0.23.0`. Use `triggering_anchors ` instead.
+    The `triggering_position` parameter in [`sv.PolygonZone`](detection/tools/polygon_zone.md/#supervision.detection.tools.polygon_zone.PolygonZone) was removed as of `supervision-0.23.0`. Use `triggering_anchors` instead.
 
 !!! failure "Deprecated"
 
@@ -133,7 +417,7 @@ for frame in sv.get_video_frames_generator(
 
 ### 0.22.0 <small>Jul 12, 2024</small>
 
-- Added [#1326](https://github.com/roboflow/supervision/pull/1326): [`sv.DetectionsDataset`](https://supervision.roboflow.com/latest/datasets/core/#supervision.dataset.core.DetectionDataset) and [`sv.ClassificationDataset`](https://supervision.roboflow.com/latest/datasets/core/#supervision.dataset.core.ClassificationDataset) allowing to load the images into memory only when necessary (lazy loading).
+- Added [#1326](https://github.com/roboflow/supervision/pull/1326): [`sv.DetectionsDataset`](https://supervision.roboflow.com/0.22.0/datasets/core/#supervision.dataset.core.DetectionDataset) and [`sv.ClassificationDataset`](https://supervision.roboflow.com/0.22.0/datasets/core/#supervision.dataset.core.ClassificationDataset) allowing to load the images into memory only when necessary (lazy loading).
 
 !!! failure "Deprecated"
 
@@ -166,15 +450,15 @@ for path, image, annotation in ds_train:
     # loads image on demand
 ```
 
-- Added [#1296](https://github.com/roboflow/supervision/pull/1296): [`sv.Detections.from_lmm`](https://supervision.roboflow.com/latest/detection/core/#supervision.detection.core.Detections.from_lmm) now supports parsing results from the [Florence 2](https://huggingface.co/microsoft/Florence-2-large) model, extending the capability to handle outputs from this Large Multimodal Model (LMM). This includes detailed object detection, OCR with region proposals, segmentation, and more. Find out more in our [Colab notebook](https://colab.research.google.com/github/roboflow-ai/notebooks/blob/main/notebooks/how-to-finetune-florence-2-on-detection-dataset.ipynb).
+- Added [#1296](https://github.com/roboflow/supervision/pull/1296): [`sv.Detections.from_lmm`](https://supervision.roboflow.com/0.22.0/detection/core/#supervision.detection.core.Detections.from_lmm) now supports parsing results from the [Florence 2](https://huggingface.co/microsoft/Florence-2-large) model, extending the capability to handle outputs from this Large Multimodal Model (LMM). This includes detailed object detection, OCR with region proposals, segmentation, and more. Find out more in our [Colab notebook](https://colab.research.google.com/github/roboflow-ai/notebooks/blob/main/notebooks/how-to-finetune-florence-2-on-detection-dataset.ipynb).
 
-- Added [#1232](https://github.com/roboflow/supervision/pull/1232) to support keypoint detection with Mediapipe. Both [legacy](https://colab.research.google.com/github/googlesamples/mediapipe/blob/main/examples/pose_landmarker/python/%5BMediaPipe_Python_Tasks%5D_Pose_Landmarker.ipynb) and [modern](https://ai.google.dev/edge/mediapipe/solutions/vision/pose_landmarker/python) pipelines are supported. See [`sv.KeyPoints.from_mediapipe`](https://supervision.roboflow.com/latest/keypoint/core/#supervision.keypoint.core.KeyPoints.from_mediapipe) for more.
+- Added [#1232](https://github.com/roboflow/supervision/pull/1232) to support keypoint detection with Mediapipe. Both [legacy](https://colab.research.google.com/github/googlesamples/mediapipe/blob/main/examples/pose_landmarker/python/%5BMediaPipe_Python_Tasks%5D_Pose_Landmarker.ipynb) and [modern](https://ai.google.dev/edge/mediapipe/solutions/vision/pose_landmarker/python) pipelines are supported. See [`sv.KeyPoints.from_mediapipe`](https://supervision.roboflow.com/0.22.0/keypoint/core/#supervision.keypoint.core.KeyPoints.from_mediapipe) for more.
 
-- Added [#1316](https://github.com/roboflow/supervision/pull/1316): [`sv.KeyPoints.from_mediapipe`](https://supervision.roboflow.com/latest/keypoint/core/#supervision.keypoint.core.KeyPoints.from_mediapipe) extended to support FaceMesh from Mediapipe. This enhancement allows for processing both face landmarks from `FaceLandmarker`, and legacy results from `FaceMesh`.
+- Added [#1316](https://github.com/roboflow/supervision/pull/1316): [`sv.KeyPoints.from_mediapipe`](https://supervision.roboflow.com/0.22.0/keypoint/core/#supervision.keypoint.core.KeyPoints.from_mediapipe) extended to support FaceMesh from Mediapipe. This enhancement allows for processing both face landmarks from `FaceLandmarker`, and legacy results from `FaceMesh`.
 
-- Added [#1310](https://github.com/roboflow/supervision/pull/1310): [`sv.KeyPoints.from_detectron2`](https://supervision.roboflow.com/latest/keypoint/core/#supervision.keypoint.core.KeyPoints.from_detectron2) is a new `KeyPoints` method, adding support for extracting keypoints from the popular [Detectron 2](https://github.com/facebookresearch/detectron2) platform.
+- Added [#1310](https://github.com/roboflow/supervision/pull/1310): [`sv.KeyPoints.from_detectron2`](https://supervision.roboflow.com/0.22.0/keypoint/core/#supervision.keypoint.core.KeyPoints.from_detectron2) is a new `KeyPoints` method, adding support for extracting keypoints from the popular [Detectron 2](https://github.com/facebookresearch/detectron2) platform.
 
-- Added [#1300](https://github.com/roboflow/supervision/pull/1300): [`sv.Detections.from_detectron2`](https://supervision.roboflow.com/latest/detection/core/#supervision.detection.core.Detections.from_detectron2) now supports segmentation models detectron2. The resulting masks can be used with [`sv.MaskAnnotator`](https://supervision.roboflow.com/latest/annotators/#supervision.annotators.core.MaskAnnotator) for displaying annotations.
+- Added [#1300](https://github.com/roboflow/supervision/pull/1300): [`sv.Detections.from_detectron2`](https://supervision.roboflow.com/0.22.0/detection/core/#supervision.detection.core.Detections.from_detectron2) now supports segmentation models detectron2. The resulting masks can be used with [`sv.MaskAnnotator`](https://supervision.roboflow.com/0.22.0/detection/annotators/#supervision.annotators.core.MaskAnnotator) for displaying annotations.
 
 ```python
 import supervision as sv
@@ -196,7 +480,7 @@ mask_annotator = sv.MaskAnnotator()
 annotated_frame = mask_annotator.annotate(scene=image.copy(), detections=detections)
 ```
 
-- Added [#1277](https://github.com/roboflow/supervision/pull/1277): if you provide a font that supports symbols of a language, [`sv.RichLabelAnnotator`](https://supervision.roboflow.com/latest/detection/annotators/#supervision.annotators.core.LabelAnnotator.annotate) will draw them on your images.
+- Added [#1277](https://github.com/roboflow/supervision/pull/1277): if you provide a font that supports symbols of a language, [`sv.RichLabelAnnotator`](https://supervision.roboflow.com/0.22.0/detection/annotators/#supervision.annotators.core.LabelAnnotator.annotate) will draw them on your images.
   - Various other annotators have been revised to ensure proper in-place functionality when used with `numpy` arrays. Additionally, we fixed a bug where `sv.ColorAnnotator` was filling boxes with solid color when used in-place.
 
 ```python
@@ -223,7 +507,7 @@ train_ds = sv.DetectionDataset.from_yolo(
     images_directory_path="/content/dataset/train/images",
     annotations_directory_path="/content/dataset/train/labels",
     data_yaml_path="/content/dataset/data.yaml",
-    is_obb=True
+    is_obb=True,
 )
 
 _, image, detections in train_ds[0]
@@ -232,25 +516,25 @@ obb_annotator = OrientedBoxAnnotator()
 annotated_image = obb_annotator.annotate(scene=image.copy(), detections=detections)
 ```
 
-- Fixed [#1312](https://github.com/roboflow/supervision/pull/1312): Fixed [`CropAnnotator`](https://supervision.roboflow.com/latest/detection/annotators/#supervision.annotators.core.TraceAnnotator.annotate).
+- Fixed [#1312](https://github.com/roboflow/supervision/pull/1312): Fixed [`CropAnnotator`](https://supervision.roboflow.com/0.22.0/detection/annotators/#supervision.annotators.core.TraceAnnotator.annotate).
 
 !!! failure "Removed"
 
-    `BoxAnnotator` was removed, however `BoundingBoxAnnotator` has been renamed to `BoxAnnotator`. Use a combination of [`BoxAnnotator`](https://supervision.roboflow.com/latest/detection/annotators/#supervision.annotators.core.BoxAnnotator) and [`LabelAnnotator`](https://supervision.roboflow.com/latest/detection/annotators/#supervision.annotators.core.LabelAnnotator) to simulate old `BoundingBox` behavior.
+    `BoxAnnotator` was removed, however `BoundingBoxAnnotator` has been renamed to `BoxAnnotator`. Use a combination of [`BoxAnnotator`](https://supervision.roboflow.com/0.22.0/detection/annotators/#supervision.annotators.core.BoxAnnotator) and [`LabelAnnotator`](https://supervision.roboflow.com/0.22.0/detection/annotators/#supervision.annotators.core.LabelAnnotator) to simulate old `BoundingBox` behavior.
 
 !!! failure "Deprecated"
 
-    The name `BoundingBoxAnnotator` has been deprecated and will be removed in `supervision-0.26.0`. It has been renamed to [`BoxAnnotator`](https://supervision.roboflow.com/latest/detection/annotators/#supervision.annotators.core.BoxAnnotator).
+    The name `BoundingBoxAnnotator` has been deprecated and will be removed in `supervision-0.26.0`. It has been renamed to [`BoxAnnotator`](https://supervision.roboflow.com/0.22.0/detection/annotators/#supervision.annotators.core.BoxAnnotator).
 
 - Added [#975](https://github.com/roboflow/supervision/pull/975) 📝 New Cookbooks: serialize detections into [json](https://github.com/roboflow/supervision/blob/de896189b83a1f9434c0a37dd9192ee00d2a1283/docs/notebooks/serialise-detections-to-json.ipynb) and [csv](https://github.com/roboflow/supervision/blob/de896189b83a1f9434c0a37dd9192ee00d2a1283/docs/notebooks/serialise-detections-to-csv.ipynb).
 
 - Added [#1290](https://github.com/roboflow/supervision/pull/1290): Mostly an internal change, our file utility function now support both `str` and `pathlib` paths.
 
-- Added [#1340](https://github.com/roboflow/supervision/pull/1340): Two new methods for converting between bounding box formats - [`xywh_to_xyxy`](https://supervision.roboflow.com/latest/detection/utils/#supervision.detection.utils.xywh_to_xyxy) and [`xcycwh_to_xyxy`](https://supervision.roboflow.com/latest/detection/utils/#supervision.detection.utils.xcycwh_to_xyxy)
+- Added [#1340](https://github.com/roboflow/supervision/pull/1340): Two new methods for converting between bounding box formats - [`xywh_to_xyxy`](https://supervision.roboflow.com/0.22.0/detection/utils/#supervision.detection.utils.xywh_to_xyxy) and [`xcycwh_to_xyxy`](https://supervision.roboflow.com/0.22.0/detection/utils/#supervision.detection.utils.xcycwh_to_xyxy)
 
 !!! failure "Removed"
 
-    `from_roboflow` method has been removed due to deprecation. Use [from_inference](https://supervision.roboflow.com/latest/detection/core/#supervision.detection.core.Detections.from_inference) instead.
+    `from_roboflow` method has been removed due to deprecation. Use [from_inference](https://supervision.roboflow.com/0.22.0/detection/core/#supervision.detection.core.Detections.from_inference) instead.
 
 !!! failure "Removed"
 
@@ -274,17 +558,17 @@ annotated_image = obb_annotator.annotate(scene=image.copy(), detections=detectio
 
 !!! failure "Removed"
 
-    `ColorPalette.default()` has been removed due to deprecation. Use [ColorPalette.DEFAULT](https://supervision.roboflow.com/latest/utils/draw/#supervision.draw.color.ColorPalette.DEFAULT) instead.
+    `ColorPalette.default()` has been removed due to deprecation. Use [ColorPalette.DEFAULT](https://supervision.roboflow.com/0.22.0/utils/draw/#supervision.draw.color.ColorPalette.DEFAULT) instead.
 
 !!! failure "Removed"
 
-    `FPSMonitor.__call__` has been removed due to deprecation. Use the attribute [FPSMonitor.fps](https://supervision.roboflow.com/latest/utils/video/#supervision.utils.video.FPSMonitor.fps) instead.
+    `FPSMonitor.__call__` has been removed due to deprecation. Use the attribute [FPSMonitor.fps](https://supervision.roboflow.com/0.22.0/utils/video/#supervision.utils.video.FPSMonitor.fps) instead.
 
 ### 0.21.0 <small>Jun 5, 2024</small>
 
-- Added [#500](https://github.com/roboflow/supervision/pull/500): [`sv.Detections.with_nmm`](https://supervision.roboflow.com/latest/detection/core/#supervision.detection.core.Detections.with_nmm) to perform non-maximum merging on the current set of object detections.
+- Added [#500](https://github.com/roboflow/supervision/pull/500): [`sv.Detections.with_nmm`](https://supervision.roboflow.com/0.21.0/detection/core/#supervision.detection.core.Detections.with_nmm) to perform non-maximum merging on the current set of object detections.
 
-- Added [#1221](https://github.com/roboflow/supervision/pull/1221): [`sv.Detections.from_lmm`](https://supervision.roboflow.com/latest/detection/core/#supervision.detection.core.Detections.from_lmm) allowing to parse Large Multimodal Model (LMM) text result into [`sv.Detections`](https://supervision.roboflow.com/latest/detection/core/) object. For now `from_lmm` supports only [PaliGemma](https://colab.research.google.com/github/roboflow-ai/notebooks/blob/main/notebooks/how-to-finetune-paligemma-on-detection-dataset.ipynb) result parsing.
+- Added [#1221](https://github.com/roboflow/supervision/pull/1221): [`sv.Detections.from_lmm`](https://supervision.roboflow.com/0.21.0/detection/core/#supervision.detection.core.Detections.from_lmm) allowing to parse Large Multimodal Model (LMM) text result into [`sv.Detections`](https://supervision.roboflow.com/0.21.0/detection/core/) object. For now `from_lmm` supports only [PaliGemma](https://colab.research.google.com/github/roboflow-ai/notebooks/blob/main/notebooks/how-to-finetune-paligemma-on-detection-dataset.ipynb) result parsing.
 
 ```python
 import supervision as sv
@@ -294,7 +578,7 @@ detections = sv.Detections.from_lmm(
     sv.LMM.PALIGEMMA,
     paligemma_result,
     resolution_wh=(1000, 1000),
-    classes=['cat', 'dog']
+    classes=["cat", "dog"],
 )
 detections.xyxy
 # array([[250., 250., 750., 750.]])
@@ -303,7 +587,7 @@ detections.class_id
 # array([0])
 ```
 
-- Added [#1236](https://github.com/roboflow/supervision/pull/1236): [`sv.VertexLabelAnnotator`](https://supervision.roboflow.com/latest/keypoint/annotators/#supervision.keypoint.annotators.EdgeAnnotator.annotate) allowing to annotate every vertex of a keypoint skeleton with custom text and color.
+- Added [#1236](https://github.com/roboflow/supervision/pull/1236): [`sv.VertexLabelAnnotator`](https://supervision.roboflow.com/0.21.0/keypoint/annotators/#supervision.keypoint.annotators.EdgeAnnotator.annotate) allowing to annotate every vertex of a keypoint skeleton with custom text and color.
 
 ```python
 import supervision as sv
@@ -321,15 +605,15 @@ annotated_frame = edge_annotator.annotate(
 )
 ```
 
-- Added [#1147](https://github.com/roboflow/supervision/pull/1147): [`sv.KeyPoints.from_inference`](https://supervision.roboflow.com/develop/keypoint/core/#supervision.keypoint.core.KeyPoints.from_inference) allowing to create [`sv.KeyPoints`](https://supervision.roboflow.com/develop/keypoint/core/#supervision.keypoint.core.KeyPoints) from [Inference](https://github.com/roboflow/inference) result.
+- Added [#1147](https://github.com/roboflow/supervision/pull/1147): [`sv.KeyPoints.from_inference`](https://supervision.roboflow.com/0.21.0/keypoint/core/#supervision.keypoint.core.KeyPoints.from_inference) allowing to create [`sv.KeyPoints`](https://supervision.roboflow.com/0.21.0/keypoint/core/#supervision.keypoint.core.KeyPoints) from [Inference](https://github.com/roboflow/inference) result.
 
-- Added [#1138](https://github.com/roboflow/supervision/pull/1138): [`sv.KeyPoints.from_yolo_nas`](https://supervision.roboflow.com/develop/keypoint/core/#supervision.keypoint.core.KeyPoints.from_yolo_nas) allowing to create [`sv.KeyPoints`](https://supervision.roboflow.com/develop/keypoint/core/#supervision.keypoint.core.KeyPoints) from [YOLO-NAS](https://github.com/Deci-AI/super-gradients/blob/master/YOLONAS.md) result.
+- Added [#1138](https://github.com/roboflow/supervision/pull/1138): [`sv.KeyPoints.from_yolo_nas`](https://supervision.roboflow.com/0.21.0/keypoint/core/#supervision.keypoint.core.KeyPoints.from_yolo_nas) allowing to create [`sv.KeyPoints`](https://supervision.roboflow.com/0.21.0/keypoint/core/#supervision.keypoint.core.KeyPoints) from [YOLO-NAS](https://github.com/Deci-AI/super-gradients/blob/master/YOLONAS.md) result.
 
-- Added [#1163](https://github.com/roboflow/supervision/pull/1163): [`sv.mask_to_rle`](https://supervision.roboflow.com/develop/datasets/utils/#supervision.dataset.utils.rle_to_mask) and [`sv.rle_to_mask`](https://supervision.roboflow.com/develop/datasets/utils/#supervision.dataset.utils.rle_to_mask) allowing for easy conversion between mask and rle formats.
+- Added [#1163](https://github.com/roboflow/supervision/pull/1163): [`sv.mask_to_rle`](https://supervision.roboflow.com/0.21.0/datasets/utils/#supervision.dataset.utils.rle_to_mask) and [`sv.rle_to_mask`](https://supervision.roboflow.com/0.21.0/datasets/utils/#supervision.dataset.utils.rle_to_mask) allowing for easy conversion between mask and rle formats.
 
-- Changed [#1236](https://github.com/roboflow/supervision/pull/1236): [`sv.InferenceSlicer`](https://supervision.roboflow.com/develop/detection/tools/inference_slicer/) allowing to select overlap filtering strategy (`NONE`, `NON_MAX_SUPPRESSION` and `NON_MAX_MERGE`).
+- Changed [#1236](https://github.com/roboflow/supervision/pull/1236): [`sv.InferenceSlicer`](https://supervision.roboflow.com/0.21.0/detection/tools/inference_slicer/) allowing to select overlap filtering strategy (`NONE`, `NON_MAX_SUPPRESSION` and `NON_MAX_MERGE`).
 
-- Changed [#1178](https://github.com/roboflow/supervision/pull/1178): [`sv.InferenceSlicer`](https://supervision.roboflow.com/develop/detection/tools/inference_slicer/) adding instance segmentation model support.
+- Changed [#1178](https://github.com/roboflow/supervision/pull/1178): [`sv.InferenceSlicer`](https://supervision.roboflow.com/0.21.0/detection/tools/inference_slicer/) adding instance segmentation model support.
 
 ```python
 import cv2
@@ -356,9 +640,9 @@ annotated_image = label_annotator.annotate(
     scene=annotated_image, detections=detections)
 ```
 
-- Changed [#1228](https://github.com/roboflow/supervision/pull/1228): [`sv.LineZone`](https://supervision.roboflow.com/develop/detection/tools/line_zone/) making it 10-20 times faster, depending on the use case.
+- Changed [#1228](https://github.com/roboflow/supervision/pull/1228): [`sv.LineZone`](https://supervision.roboflow.com/0.21.0/detection/tools/line_zone/) making it 10-20 times faster, depending on the use case.
 
-- Changed [#1163](https://github.com/roboflow/supervision/pull/1163): [`sv.DetectionDataset.from_coco`](https://supervision.roboflow.com/develop/datasets/core/#supervision.dataset.core.DetectionDataset.from_coco) and [`sv.DetectionDataset.as_coco`](https://supervision.roboflow.com/develop/datasets/core/#supervision.dataset.core.DetectionDataset.as_coco) adding support for run-length encoding (RLE) mask format.
+- Changed [#1163](https://github.com/roboflow/supervision/pull/1163): [`sv.DetectionDataset.from_coco`](https://supervision.roboflow.com/0.21.0/datasets/core/#supervision.dataset.core.DetectionDataset.from_coco) and [`sv.DetectionDataset.as_coco`](https://supervision.roboflow.com/0.21.0/datasets/core/#supervision.dataset.core.DetectionDataset.as_coco) adding support for run-length encoding (RLE) mask format.
 
 ### 0.20.0 <small>April 24, 2024</small>
 
@@ -485,11 +769,11 @@ annotated_frame = crop_annotator.annotate(
 )
 ```
 
-- Changed [#827](https://github.com/roboflow/supervision/pull/827): [`sv.ByteTrack.reset`](/0.19.0/tracking/#supervision.tracking.ByteTrack.reset) allowing users to clear trackers state, enabling the processing of multiple video files in sequence.
+- Changed [#827](https://github.com/roboflow/supervision/pull/827): [`sv.ByteTrack.reset`](/0.19.0/trackers/#supervision.tracker.ByteTrack.reset) allowing users to clear trackers state, enabling the processing of multiple video files in sequence.
 
 - Changed [#802](https://github.com/roboflow/supervision/pull/802): [`sv.LineZoneAnnotator`](/0.19.0/detection/tools/line_zone/#supervision.detection.line_zone.LineZone) allowing to hide in/out count using `display_in_count` and `display_out_count` properties.
 
-- Changed [#787](https://github.com/roboflow/supervision/pull/787): [`sv.ByteTrack`](/0.19.0/tracking/#supervision.tracking.ByteTrack) input arguments and docstrings updated to improve readability and ease of use.
+- Changed [#787](https://github.com/roboflow/supervision/pull/787): [`sv.ByteTrack`](/0.19.0/trackers/#supervision.tracker.ByteTrack) input arguments and docstrings updated to improve readability and ease of use.
 
 !!! failure "Deprecated"
 
@@ -916,7 +1200,7 @@ array([
 
 - Added [#101](https://github.com/roboflow/supervision/pull/101): ability to extract masks from YOLOv8 result using [`sv.Detections.from_yolov8`](/0.8.0/detection/core/#supervision.detection.core.Detections.from_yolov8). Here is an example illustrating how to extract boolean masks from the result of the YOLOv8 model inference.
 
-- Added [#122](https://github.com/roboflow/supervision/pull/122): ability to crop image using [`sv.crop`](/latest/utils/image/#crop). Here is an example showing how to get a separate crop for each detection in `sv.Detections`.
+- Added [#122](https://github.com/roboflow/supervision/pull/122): ability to crop image using [`sv.crop`](/0.9.0/utils/image/#crop). Here is an example showing how to get a separate crop for each detection in `sv.Detections`.
 
 - Added [#120](https://github.com/roboflow/supervision/pull/120): ability to conveniently save multiple images into directory using [`sv.ImageSink`](/0.9.0/utils/image/#imagesink). Here is an example showing how to save every tenth video frame as a separate image.
 
@@ -928,11 +1212,11 @@ array([
 ...         sink.save_image(image=image)
 ```
 
-- Fixed [#106](https://github.com/roboflow/supervision/issues/106): inconvenient handling of [`sv.PolygonZone`](/0.8.0/supervision/detection/tools/polygon_zone/#polygonzone) coordinates. Now `sv.PolygonZone` accepts coordinates in the form of `[[x1, y1], [x2, y2], ...]` that can be both integers and floats.
+- Fixed [#106](https://github.com/roboflow/supervision/issues/106): inconvenient handling of [`sv.PolygonZone`](/0.8.0/detection/tools/polygon_zone/#polygonzone) coordinates. Now `sv.PolygonZone` accepts coordinates in the form of `[[x1, y1], [x2, y2], ...]` that can be both integers and floats.
 
 ### 0.8.0 <small>May 17, 2023</small>
 
-- Added [#100](https://github.com/roboflow/supervision/pull/100): support for dataset inheritance. The current `Dataset` got renamed to `DetectionDataset`. Now [`DetectionDataset`](/0.8.0/supervision/dataset/core/#detectiondataset) inherits from `BaseDataset`. This change was made to enforce the future consistency of APIs of different types of computer vision datasets.
+- Added [#100](https://github.com/roboflow/supervision/pull/100): support for dataset inheritance. The current `Dataset` got renamed to `DetectionDataset`. Now [`DetectionDataset`](/0.8.0/dataset/core/#detectiondataset) inherits from `BaseDataset`. This change was made to enforce the future consistency of APIs of different types of computer vision datasets.
 - Added [#100](https://github.com/roboflow/supervision/pull/100): ability to save datasets in YOLO format using [`DetectionDataset.as_yolo`](/0.8.0/dataset/core/#supervision.dataset.core.DetectionDataset.as_yolo).
 
 ```python

docs/datasets/core.md

@@ -5,7 +5,6 @@ comments: true
 # Datasets
 
 !!! warning
-
     Dataset API is still fluid and may change. If you use Dataset API in your project until further notice, freeze the
     `supervision` version in your `requirements.txt` or `setup.py`.
 

docs/deprecated.md

@@ -7,30 +7,40 @@ status: deprecated
 
 These features are phased out due to better alternatives or potential issues in future versions. Deprecated functionalities are supported for **five subsequent releases**, providing time for users to transition to updated methods.
 
-- The `frame_resolution_wh ` parameter in [`sv.PolygonZone`](detection/tools/polygon_zone.md/#supervision.detection.tools.polygon_zone.PolygonZone) will be removed in `supervision-0.24.0`.
-
 - Constructing [`DetectionDataset`](https://supervision.roboflow.com/latest/datasets/core/#supervision.dataset.core.DetectionDataset) and [`ClassificationDataset`](https://supervision.roboflow.com/latest/datasets/core/#supervision.dataset.core.ClassificationDataset) with parameter `images` as `Dict[str, np.ndarray]` will be removed in `supervision-0.26.0`. Please pass a list of paths `List[str]` instead.
+
 - The `DetectionDataset.images` property will be removed in `supervision-0.26.0`. Please loop over images with `for path, image, annotation in dataset:`, as that does not require loading all images into memory.
+
 - `BoundingBoxAnnotator` has been renamed to `BoxAnnotator` after the old implementation of [`BoxAnnotator`](https://supervision.roboflow.com/latest/detection/annotators/#supervision.annotators.core.BoxAnnotator) has been removed. `BoundingBoxAnnotator` will be removed in `supervision-0.26.0`.
 
 - `overlap_filter_strategy` in [`InferenceSlicer.__init__`](https://supervision.roboflow.com/latest/detection/tools/inference_slicer/) is deprecated and will be removed in `supervision-0.27.0`. Use `overlap_strategy` instead.
+
 - `overlap_ratio_wh` in [`InferenceSlicer.__init__`](https://supervision.roboflow.com/latest/detection/tools/inference_slicer/) is deprecated and will be removed in `supervision-0.27.0`. Use `overlap_wh` instead.
 
 # Removed
 
+### 0.25.0
+
+No removals in this version!
+
+### 0.24.0
+
+- The `frame_resolution_wh ` parameter in [`sv.PolygonZone`](detection/tools/polygon_zone.md/#supervision.detection.tools.polygon_zone.PolygonZone) has been removed.
+- Supervision installation methods `"headless"` and `"desktop"` were removed, as they are no longer needed. `pip install supervision[headless]` will install the base library and harmlessly warn of non-existent extras.
+
 ### 0.23.0
 
 - The `track_buffer`, `track_thresh`, and `match_thresh` parameters in [`ByteTrack`](trackers.md/#supervision.tracker.byte_tracker.core.ByteTrack) are deprecated and were removed as of `supervision-0.23.0`. Use `lost_track_buffer,` `track_activation_threshold`, and `minimum_matching_threshold` instead.
-- The `triggering_position ` parameter in [`sv.PolygonZone`](detection/tools/polygon_zone.md/#supervision.detection.tools.polygon_zone.PolygonZone) was removed as of `supervision-0.23.0`. Use `triggering_anchors ` instead.
+- The `triggering_position ` parameter in [`sv.PolygonZone`](detection/tools/polygon_zone.md/#supervision.detection.tools.polygon_zone.PolygonZone) was removed as of `supervision-0.23.0`. Use `triggering_anchors` instead.
 
 ### 0.22.0
 
-- [`Detections.from_froboflow`](detection/core.md/#supervision.detection.core.Detections.from_roboflow) is removed as of `supervision-0.22.0`. Use [`Detections.from_inference`](detection/core.md/#supervision.detection.core.Detections.from_inference) instead.
+- `Detections.from_roboflow` is removed as of `supervision-0.22.0`. Use [`Detections.from_inference`](detection/core.md/#supervision.detection.core.Detections.from_inference) instead.
 - The method `Color.white()` was removed as of `supervision-0.22.0`. Use the constant `Color.WHITE` instead.
 - The method `Color.black()` was removed as of `supervision-0.22.0`. Use the constant `Color.BLACK` instead.
 - The method `Color.red()` was removed as of `supervision-0.22.0`. Use the constant `Color.RED` instead.
 - The method `Color.green()` was removed as of `supervision-0.22.0`. Use the constant `Color.GREEN` instead.
 - The method `Color.blue()` was removed as of `supervision-0.22.0`. Use the constant `Color.BLUE` instead.
-- The method [`ColorPalette.default()`](draw/color.md/#supervision.draw.color.ColorPalette.default) was removed as of `supervision-0.22.0`. Use the constant [`ColorPalette.DEFAULT`](draw/color.md/#supervision.draw.color.ColorPalette.DEFAULT) instead.
+- The method `ColorPalette.default()` was removed as of `supervision-0.22.0`. Use the constant [`ColorPalette.DEFAULT`](/utils/draw/#supervision.draw.color.ColorPalette.DEFAULT) instead.
 - `BoxAnnotator` was removed as of `supervision-0.22.0`, however `BoundingBoxAnnotator` was immediately renamed to `BoxAnnotator`. Use [`BoxAnnotator`](detection/annotators.md/#supervision.annotators.core.BoxAnnotator) and [`LabelAnnotator`](detection/annotators.md/#supervision.annotators.core.LabelAnnotator) instead of the old `BoxAnnotator`.
-- The method [`FPSMonitor.__call__`](utils/video.md/#supervision.utils.video.FPSMonitor.__call__) was removed as of `supervision-0.22.0`. Use the attribute [`FPSMonitor.fps`](utils/video.md/#supervision.utils.video.FPSMonitor.fps) instead.
+- The method `FPSMonitor.__call__` was removed as of `supervision-0.22.0`. Use the attribute [`FPSMonitor.fps`](utils/video.md/#supervision.utils.video.FPSMonitor.fps) instead.

docs/detection/annotators.md

@@ -5,6 +5,8 @@ status: new
 
 # Annotators
 
+Annotators accept detections and apply box or mask visualizations to the detections. Annotators have many available styles.
+
 === "Box"
 
     ```python
@@ -481,6 +483,13 @@ status: new
 
     </div>
 
+<div class="md-typeset">
+    <h2>Try Supervision Annotators on your own image</h2>
+    Visualize annotators on images with COCO classes such as people, vehicles, animals, household items.
+</div>
+
+<div style="height: 400px; width: 100%; border-radius: 8px; overflow: hidden;"><iframe src="https://app.roboflow.com/workflows/embed/eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ3b3JrZmxvd0lkIjoiNDdtd2xuWW16S25VNWtOYUZjMG8iLCJ3b3Jrc3BhY2VJZCI6ImtyT1RBYm5jRmhvUU1DZExPbGU0IiwidXNlcklkIjoiRVJNUFBZY3FQMmZWWjB1NkRpNXZaYXJDdlZPMiIsImlhdCI6MTcyNjgzOTM2N30.gj2F6SnmmURAScJe4PTC1raUXsAK5mZyrUIGIJ44NhM?hideToolbar=true&hideHeader=true&defaultVisual=true" loading="lazy" title="Roboflow Workflow for Supervision Annotators" style="width: 100%; height: 100%; min-height: 400px; border: none;"></iframe></div>
+
 <div class="md-typeset">
     <h2><a href="#supervision.annotators.core.BoxAnnotator">BoxAnnotator</a></h2>
 </div>

docs/detection/tools/inference_slicer.md

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

docs/detection/tools/line_zone.md

@@ -1,5 +1,6 @@
 ---
 comments: true
+status: new
 ---
 
 <div class="md-typeset">
@@ -13,3 +14,9 @@ comments: true
 </div>
 
 :::supervision.detection.line_zone.LineZoneAnnotator
+
+<div class="md-typeset">
+  <h2>LineZoneAnnotatorMulticlass</h2>
+</div>
+
+:::supervision.detection.line_zone.LineZoneAnnotatorMulticlass

docs/detection/utils.md

@@ -1,5 +1,6 @@
 ---
 comments: true
+status: new
 ---
 
 # Detection Utils
@@ -16,6 +17,12 @@ comments: true
 
 :::supervision.detection.utils.mask_iou_batch
 
+<div class="md-typeset">
+  <h2><a href="#supervision.detection.utils.oriented_box_iou_batch">oriented_box_iou_batch</a></h2>
+</div>
+
+:::supervision.detection.utils.oriented_box_iou_batch
+
 <div class="md-typeset">
   <h2><a href="#supervision.detection.utils.polygon_to_mask">polygon_to_mask</a></h2>
 </div>

docs/how_to/detect_and_annotate.md

@@ -6,7 +6,7 @@ comments: true
 
 Supervision provides a seamless process for annotating predictions generated by various
 object detection and segmentation models. This guide shows how to perform inference
-with the  [Inference](https://github.com/roboflow/inference),
+with the [Inference](https://github.com/roboflow/inference),
 [Ultralytics](https://github.com/ultralytics/ultralytics) or
 [Transformers](https://github.com/huggingface/transformers) packages. Following this,
 you'll learn how to import these predictions into Supervision and use them to annotate
@@ -20,7 +20,6 @@ First, you'll need to obtain predictions from your object detection or segmentat
 model.
 
 === "Inference"
-
     ```python
     import cv2
     from inference import get_model
@@ -31,7 +30,6 @@ model.
     ```
 
 === "Ultralytics"
-
     ```python
     import cv2
     from ultralytics import YOLO
@@ -42,7 +40,6 @@ model.
     ```
 
 === "Transformers"
-
     ```python
     import torch
     from PIL import Image
@@ -68,8 +65,7 @@ model.
 Now that we have predictions from a model, we can load them into Supervision.
 
 === "Inference"
-
-    We can do so using the [`sv.Detections.from_inference`](detection/core/#supervision.detection.core.Detections.from_inference) method, which accepts model results from both detection and segmentation models.
+    We can do so using the [`sv.Detections.from_inference`](/latest/detection/core/#supervision.detection.core.Detections.from_inference) method, which accepts model results from both detection and segmentation models.
 
     ```{ .py hl_lines="2 8" }
     import cv2
@@ -83,8 +79,7 @@ Now that we have predictions from a model, we can load them into Supervision.
     ```
 
 === "Ultralytics"
-
-    We can do so using the [`sv.Detections.from_ultralytics`](detection/core/#supervision.detection.core.Detections.from_ultralytics) method, which accepts model results from both detection and segmentation models.
+    We can do so using the [`sv.Detections.from_ultralytics`](/latest/detection/core/#supervision.detection.core.Detections.from_ultralytics) method, which accepts model results from both detection and segmentation models.
 
     ```{ .py hl_lines="2 8" }
     import cv2
@@ -98,8 +93,7 @@ Now that we have predictions from a model, we can load them into Supervision.
     ```
 
 === "Transformers"
-
-    We can do so using the [`sv.Detections.from_transformers`](detection/core/#supervision.detection.core.Detections.from_transformers) method, which accepts model results from both detection and segmentation models.
+    We can do so using the [`sv.Detections.from_transformers`](/latest/detection/core/#supervision.detection.core.Detections.from_transformers) method, which accepts model results from both detection and segmentation models.
 
     ```{ .py hl_lines="2 19-21" }
     import torch
@@ -135,10 +129,9 @@ You can load predictions from other computer vision frameworks and libraries usi
 
 ## Annotate Image with Detections
 
-Finally, we can annotate the image with the predictions. Since we are working with an object detection model, we will use the [`sv.BoxAnnotator`](/latest/annotators/#supervision.annotators.core.BoxAnnotator) and [`sv.LabelAnnotator`](/latest/annotators/#supervision.annotators.core.LabelAnnotator) classes.
+Finally, we can annotate the image with the predictions. Since we are working with an object detection model, we will use the [`sv.BoxAnnotator`](/latest/detection/annotators/#supervision.annotators.core.BoxAnnotator) and [`sv.LabelAnnotator`](/latest/detection/annotators/#supervision.annotators.core.LabelAnnotator) classes.
 
 === "Inference"
-
     ```{ .py hl_lines="10-16" }
     import cv2
     import supervision as sv
@@ -159,7 +152,6 @@ Finally, we can annotate the image with the predictions. Since we are working wi
     ```
 
 === "Ultralytics"
-
     ```{ .py hl_lines="10-16" }
     import cv2
     import supervision as sv
@@ -180,7 +172,6 @@ Finally, we can annotate the image with the predictions. Since we are working wi
     ```
 
 === "Transformers"
-
     ```{ .py hl_lines="23-30" }
     import torch
     import supervision as sv
@@ -217,12 +208,11 @@ Finally, we can annotate the image with the predictions. Since we are working wi
 
 ## Display Custom Labels
 
-By default, [`sv.LabelAnnotator`](/latest/annotators/#supervision.annotators.core.LabelAnnotator)
+By default, [`sv.LabelAnnotator`](/latest/detection/annotators/#supervision.annotators.core.LabelAnnotator)
 will label each detection with its `class_name` (if possible) or `class_id`. You can
 override this behavior by passing a list of custom `labels` to the `annotate` method.
 
 === "Inference"
-
     ```{ .py hl_lines="13-17 22" }
     import cv2
     import supervision as sv
@@ -249,7 +239,6 @@ override this behavior by passing a list of custom `labels` to the `annotate` me
     ```
 
 === "Ultralytics"
-
     ```{ .py hl_lines="13-17 22" }
     import cv2
     import supervision as sv
@@ -276,7 +265,6 @@ override this behavior by passing a list of custom `labels` to the `annotate` me
     ```
 
 === "Transformers"
-
     ```{ .py hl_lines="26-30 35" }
     import torch
     import supervision as sv
@@ -320,13 +308,12 @@ override this behavior by passing a list of custom `labels` to the `annotate` me
 ## Annotate Image with Segmentations
 
 If you are running the segmentation model
-[`sv.MaskAnnotator`](/latest/annotators/#supervision.annotators.core.MaskAnnotator)
+[`sv.MaskAnnotator`](/latest/detection/annotators/#supervision.annotators.core.MaskAnnotator)
 is a drop-in replacement for
-[`sv.BoxAnnotator`](/latest/annotators/#supervision.annotators.core.BoxAnnotator)
+[`sv.BoxAnnotator`](/latest/detection/annotators/#supervision.annotators.core.BoxAnnotator)
 that will allow you to draw masks instead of boxes.
 
 === "Inference"
-
     ```python
     import cv2
     import supervision as sv
@@ -347,7 +334,6 @@ that will allow you to draw masks instead of boxes.
     ```
 
 === "Ultralytics"
-
     ```python
     import cv2
     import supervision as sv
@@ -368,7 +354,6 @@ that will allow you to draw masks instead of boxes.
     ```
 
 === "Transformers"
-
     ```python
     import torch
     import supervision as sv

docs/how_to/detect_small_objects.md

@@ -20,7 +20,6 @@ Small object detection in high-resolution images presents challenges due to the
 size relative to the image resolution.
 
 === "Inference"
-
     ```python
     import cv2
     import supervision as sv
@@ -41,7 +40,6 @@ size relative to the image resolution.
     ```
 
 === "Ultralytics"
-
     ```python
     import cv2
     import supervision as sv
@@ -62,7 +60,6 @@ size relative to the image resolution.
     ```
 
 === "Transformers"
-
     ```python
     import torch
     import supervision as sv
@@ -108,7 +105,6 @@ identification at the cost of processing speed and increased memory usage. This
 is less effective for ultra-high-resolution images (4K and above).
 
 === "Inference"
-
     ```{ .py hl_lines="5" }
     import cv2
     import supervision as sv
@@ -129,7 +125,6 @@ is less effective for ultra-high-resolution images (4K and above).
     ```
 
 === "Ultralytics"
-
     ```{ .py hl_lines="7" }
     import cv2
     import supervision as sv
@@ -162,7 +157,6 @@ objects within each, and aggregating the results.
 </video>
 
 === "Inference"
-
     ```{ .py hl_lines="9-14" }
     import cv2
     import numpy as np
@@ -189,7 +183,6 @@ objects within each, and aggregating the results.
     ```
 
 === "Ultralytics"
-
     ```{ .py hl_lines="9-14" }
     import cv2
     import numpy as np
@@ -216,7 +209,6 @@ objects within each, and aggregating the results.
     ```
 
 === "Transformers"
-
     ```{ .py hl_lines="13-28" }
     import cv2
     import torch
@@ -269,7 +261,6 @@ objects within each, and aggregating the results.
 [`InferenceSlicer`](/latest/detection/tools/inference_slicer/#supervision.detection.tools.inference_slicer.InferenceSlicer) can perform segmentation tasks too.
 
 === "Inference"
-
     ```{ .py hl_lines="6 16 19-20" }
     import cv2
     import numpy as np
@@ -296,7 +287,6 @@ objects within each, and aggregating the results.
     ```
 
 === "Ultralytics"
-
     ```{ .py hl_lines="6 16 19-20" }
     import cv2
     import numpy as np

docs/how_to/filter_detections.md

@@ -15,7 +15,6 @@ the filters in their applications.
 Allows you to select detections that belong only to one selected class.
 
 === "After"
-
     ```python
     import supervision as sv
 
@@ -30,7 +29,6 @@ Allows you to select detections that belong only to one selected class.
     </div>
 
 === "Before"
-
     ```python
     import supervision as sv
 
@@ -49,7 +47,6 @@ Allows you to select detections that belong only to one selected class.
 Allows you to select detections that belong only to selected set of classes.
 
 === "After"
-
     ```python
     import numpy as np
     import supervision as sv
@@ -66,7 +63,6 @@ Allows you to select detections that belong only to selected set of classes.
     </div>
 
 === "Before"
-
     ```python
     import numpy as np
     import supervision as sv
@@ -87,7 +83,6 @@ Allows you to select detections that belong only to selected set of classes.
 Allows you to select detections with specific confidence value, for example higher than selected threshold.
 
 === "After"
-
     ```python
     import supervision as sv
 
@@ -102,7 +97,6 @@ Allows you to select detections with specific confidence value, for example high
     </div>
 
 === "Before"
-
     ```python
     import supervision as sv
 
@@ -122,7 +116,6 @@ Allows you to select detections based on their size. We define the area as the n
 detection in the image. In the example below, we have sifted out the detections that are too small.
 
 === "After"
-
     ```python
     import supervision as sv
 
@@ -137,7 +130,6 @@ detection in the image. In the example below, we have sifted out the detections
     </div>
 
 === "Before"
-
     ```python
     import supervision as sv
 
@@ -159,7 +151,6 @@ but small on a 3840x2160 image. In such cases, we can filter out detections base
 occupied by them. In the example below, we remove too large detections.
 
 === "After"
-
     ```python
     import supervision as sv
 
@@ -178,7 +169,6 @@ occupied by them. In the example below, we remove too large detections.
     </div>
 
 === "Before"
-
     ```python
     import supervision as sv
 
@@ -203,7 +193,6 @@ can be criteria for rejecting detection. Implementing such filtering requires a
 simple and fast.
 
 === "After"
-
     ```python
     import supervision as sv
 
@@ -220,7 +209,6 @@ simple and fast.
     </div>
 
 === "Before"
-
     ```python
     import supervision as sv
 
@@ -242,7 +230,6 @@ Allows you to use `Detections` in combination with `PolygonZone` to weed out bou
 zone. In the example below you can see how to filter out all detections located in the lower part of the image.
 
 === "After"
-
     ```python
     import supervision as sv
 
@@ -259,7 +246,6 @@ zone. In the example below you can see how to filter out all detections located
     </div>
 
 === "Before"
-
     ```python
     import supervision as sv
 
@@ -280,7 +266,6 @@ zone. In the example below you can see how to filter out all detections located
 `Detections`' greatest strength, however, is that you can build arbitrarily complex logical conditions by simply combining separate conditions using `&` or `|`.
 
 === "After"
-
     ```python
     import supervision as sv
 
@@ -297,7 +282,6 @@ zone. In the example below you can see how to filter out all detections located
     </div>
 
 === "Before"
-
     ```python
     import supervision as sv
 

docs/how_to/save_detections.md

@@ -19,7 +19,6 @@ model. You can learn more on this topic in our
 [How to Detect and Annotate](/latest/how_to/detect_and_annotate.md) guide.
 
 === "Inference"
-
     ```python
     import supervision as sv
     from inference import get_model
@@ -34,7 +33,6 @@ model. You can learn more on this topic in our
     ```
 
 === "Ultralytics"
-
     ```python
     import supervision as sv
     from ultralytics import YOLO
@@ -49,7 +47,6 @@ model. You can learn more on this topic in our
     ```
 
 === "Transformers"
-
     ```python
     import torch
     import supervision as sv
@@ -83,7 +80,6 @@ and then pass the
 object resulting from the inference to it. Its fields are parsed and saved on disk.
 
 === "Inference"
-
     ```{ .py hl_lines="7 12" }
     import supervision as sv
     from inference import get_model
@@ -100,7 +96,6 @@ object resulting from the inference to it. Its fields are parsed and saved on di
     ```
 
 === "Ultralytics"
-
     ```{ .py hl_lines="7 12" }
     import supervision as sv
     from ultralytics import YOLO
@@ -117,7 +112,6 @@ object resulting from the inference to it. Its fields are parsed and saved on di
     ```
 
 === "Transformers"
-
     ```{ .py hl_lines="9 23" }
     import torch
     import supervision as sv
@@ -144,11 +138,11 @@ object resulting from the inference to it. Its fields are parsed and saved on di
             sink.append(detections, {})
     ```
 
-| x_min   | y_min    | x_max   | y_max    | class_id | confidence | tracker_id | class_name |
-|---------|----------|---------|----------|----------|------------|------------|------------|
-| 2941.14 | 1269.31  | 3220.77 | 1500.67  | 2        | 0.8517     |            | car        |
-| 944.889 | 899.641  | 1235.42 | 1308.80  | 7        | 0.6752     |            | truck      |
-| 1439.78 | 1077.79  | 1621.27 | 1231.40  | 2        | 0.6450     |            | car        |
+| x_min   | y_min   | x_max   | y_max   | class_id | confidence | tracker_id | class_name |
+| ------- | ------- | ------- | ------- | -------- | ---------- | ---------- | ---------- |
+| 2941.14 | 1269.31 | 3220.77 | 1500.67 | 2        | 0.8517     |            | car        |
+| 944.889 | 899.641 | 1235.42 | 1308.80 | 7        | 0.6752     |            | truck      |
+| 1439.78 | 1077.79 | 1621.27 | 1231.40 | 2        | 0.6450     |            | car        |
 
 ## Custom Fields
 
@@ -160,7 +154,6 @@ also allows you to add custom information to each row, which can be passed via t
 frame index from which the detections originate.
 
 === "Inference"
-
     ```{ .py hl_lines="8 12" }
     import supervision as sv
     from inference import get_model
@@ -177,7 +170,6 @@ frame index from which the detections originate.
     ```
 
 === "Ultralytics"
-
     ```{ .py hl_lines="8 12" }
     import supervision as sv
     from ultralytics import YOLO
@@ -194,7 +186,6 @@ frame index from which the detections originate.
     ```
 
 === "Transformers"
-
     ```{ .py hl_lines="10 23" }
     import torch
     import supervision as sv
@@ -221,11 +212,11 @@ frame index from which the detections originate.
             sink.append(detections, {"frame_index": frame_index})
     ```
 
-| x_min   | y_min    | x_max   | y_max    | class_id | confidence | tracker_id | class_name | frame_index |
-|---------|----------|---------|----------|----------|------------|------------|------------|-------------|
-| 2941.14 | 1269.31  | 3220.77 | 1500.67  | 2        | 0.8517     |            | car        | 0           |
-| 944.889 | 899.641  | 1235.42 | 1308.80  | 7        | 0.6752     |            | truck      | 0           |
-| 1439.78 | 1077.79  | 1621.27 | 1231.40  | 2        | 0.6450     |            | car        | 0           |
+| x_min   | y_min   | x_max   | y_max   | class_id | confidence | tracker_id | class_name | frame_index |
+| ------- | ------- | ------- | ------- | -------- | ---------- | ---------- | ---------- | ----------- |
+| 2941.14 | 1269.31 | 3220.77 | 1500.67 | 2        | 0.8517     |            | car        | 0           |
+| 944.889 | 899.641 | 1235.42 | 1308.80 | 7        | 0.6752     |            | truck      | 0           |
+| 1439.78 | 1077.79 | 1621.27 | 1231.40 | 2        | 0.6450     |            | car        | 0           |
 
 ## Save Detections as JSON
 
@@ -236,7 +227,6 @@ with
 [`sv.JSONSink`](/latest/detection/tools/save_detections/#supervision.detection.tools.csv_sink.JSONSink).
 
 === "Inference"
-
     ```{ .py hl_lines="7" }
     import supervision as sv
     from inference import get_model
@@ -253,7 +243,6 @@ with
     ```
 
 === "Ultralytics"
-
     ```{ .py hl_lines="7" }
     import supervision as sv
     from ultralytics import YOLO
@@ -270,7 +259,6 @@ with
     ```
 
 === "Transformers"
-
     ```{ .py hl_lines="9" }
     import torch
     import supervision as sv

docs/how_to/track_objects.md

@@ -1,18 +1,21 @@
 ---
 comments: true
+status: new
 ---
 
 # Track Objects
 
 Leverage Supervision's advanced capabilities for enhancing your video analysis by
 seamlessly [tracking](/latest/trackers/) objects recognized by
-a multitude of object detection and segmentation models. This comprehensive guide will
+a multitude of object detection, segmentation and keypoint models. This comprehensive guide will
 take you through the steps to perform inference using the YOLOv8 model via either the
 [Inference](https://github.com/roboflow/inference) or
 [Ultralytics](https://github.com/ultralytics/ultralytics) packages. Following this,
 you'll discover how to track these objects efficiently and annotate your video content
 for a deeper analysis.
 
+## Object Detection & Segmentation
+
 To make it easier for you to follow our tutorial download the video we will use as an
 example. You can do this using
 [`supervision[assets]`](/latest/assets/) extension.
@@ -27,7 +30,7 @@ download_assets(VideoAssets.PEOPLE_WALKING)
     <source src="https://media.roboflow.com/supervision/video-examples/people-walking.mp4" type="video/mp4">
 </video>
 
-## Run Inference
+### Run Inference
 
 First, you'll need to obtain predictions from your object detection or segmentation
 model. In this tutorial, we are using the YOLOv8 model as an example. However,
@@ -40,6 +43,10 @@ by obtaining model predictions and then annotating the frame based on these pred
 This `callback` function will be essential in the subsequent steps of the tutorial, as
 it will be modified to include tracking, labeling, and trace annotations.
 
+!!! tip
+
+    Both object detection and segmentation models are supported. Try it with `yolov8n.pt` or `yolov8n-640-seg`!
+
 === "Ultralytics"
 
     ```{ .py }
@@ -88,7 +95,7 @@ it will be modified to include tracking, labeling, and trace annotations.
     <source src="https://media.roboflow.com/supervision/video-examples/how-to/track-objects/run-inference.mp4" type="video/mp4">
 </video>
 
-## Tracking
+### Tracking
 
 After running inference and obtaining predictions, the next step is to track the
 detected objects throughout the video. Utilizing Supervision’s
@@ -144,11 +151,11 @@ enabling the continuous following of the object's motion path across different f
     )
     ```
 
-## Annotate Video with Tracking IDs
+### Annotate Video with Tracking IDs
 
 Annotating the video with tracking IDs helps in distinguishing and following each object
 distinctly. With the
-[`sv.LabelAnnotator`](/latest/annotators.md/#supervision.annotators.core.LabelAnnotator)
+[`sv.LabelAnnotator`](/latest/detection/annotators/#supervision.annotators.core.LabelAnnotator)
 in Supervision, we can overlay the tracker IDs and class labels on the detected objects,
 offering a clear visual representation of each object's class and unique identifier.
 
@@ -226,11 +233,11 @@ offering a clear visual representation of each object's class and unique identif
     <source src="https://media.roboflow.com/supervision/video-examples/how-to/track-objects/annotate-video-with-tracking-ids.mp4" type="video/mp4">
 </video>
 
-## Annotate Video with Traces
+### Annotate Video with Traces
 
 Adding traces to the video involves overlaying the historical paths of the detected
 objects. This feature, powered by the
-[`sv.TraceAnnotator`](/latest/annotators/#supervision.annotators.core.TraceAnnotator),
+[`sv.TraceAnnotator`](/latest/detection/annotators/#supervision.annotators.core.TraceAnnotator),
 allows for visualizing the trajectories of objects, helping in understanding the
 movement patterns and interactions between objects in the video.
 
@@ -314,6 +321,336 @@ movement patterns and interactions between objects in the video.
     <source src="https://media.roboflow.com/supervision/video-examples/how-to/track-objects/annotate-video-with-traces.mp4" type="video/mp4">
 </video>
 
-This structured walkthrough should give a detailed pathway to annotate videos
-effectively using Supervision’s various functionalities, including object tracking and
-trace annotations.
+## Keypoints
+
+Models aren't limited to object detection and segmentation. Keypoint detection allows for detailed analysis of body joints and connections, especially valuable for applications like human pose estimation. This section introduces keypoint tracking. We'll walk through the steps of annotating keypoints, converting them into bounding box detections compatible with `ByteTrack`, and applying detection smoothing for enhanced stability.
+
+To make it easier for you to follow our tutorial, let's download the video we will use as an
+example. You can do this using [`supervision[assets]`](/latest/assets/) extension.
+
+```python
+from supervision.assets import download_assets, VideoAssets
+
+download_assets(VideoAssets.SKIING)
+```
+
+<video controls muted>
+    <source src="https://media.roboflow.com/supervision/video-examples/how-to/track-objects/skiing-hd.mp4" type="video/mp4">
+</video>
+
+### Keypoint Detection
+
+First, you'll need to obtain predictions from your keypoint detection model. In this tutorial, we are using the YOLOv8 model as an example. However,
+Supervision is versatile and compatible with various models. Check this [link](/latest/keypoint/core/) for guidance on how to plug in other models.
+
+We will define a `callback` function, which will process each frame of the video by obtaining model predictions and then annotating the frame based on these predictions.
+
+Let's immediately visualize the results with our [`EdgeAnnotator`](/latest/keypoint/annotators/#supervision.keypoint.annotators.EdgeAnnotator) and [`VertexAnnotator`](https://supervision.roboflow.com/latest/keypoint/annotators/#supervision.keypoint.annotators.VertexAnnotator).
+
+=== "Ultralytics"
+
+    ```{ .py hl_lines="5 10-11" }
+    import numpy as np
+    import supervision as sv
+    from ultralytics import YOLO
+
+    model = YOLO("yolov8m-pose.pt")
+    edge_annotator = sv.EdgeAnnotator()
+    vertex_annotator = sv.VertexAnnotator()
+
+    def callback(frame: np.ndarray, _: int) -> np.ndarray:
+        results = model(frame)[0]
+        key_points = sv.KeyPoints.from_ultralytics(results)
+
+        annotated_frame = edge_annotator.annotate(
+            frame.copy(), key_points=key_points)
+        return vertex_annotator.annotate(
+            annotated_frame, key_points=key_points)
+
+    sv.process_video(
+        source_path="skiing.mp4",
+        target_path="result.mp4",
+        callback=callback
+    )
+    ```
+
+=== "Inference"
+
+    ```{ .py hl_lines="5-6 11-12" }
+    import numpy as np
+    import supervision as sv
+    from inference.models.utils import get_roboflow_model
+
+    model = get_roboflow_model(
+        model_id="yolov8m-pose-640", api_key=<ROBOFLOW API KEY>)
+    edge_annotator = sv.EdgeAnnotator()
+    vertex_annotator = sv.VertexAnnotator()
+
+    def callback(frame: np.ndarray, _: int) -> np.ndarray:
+        results = model.infer(frame)[0]
+        key_points = sv.KeyPoints.from_inference(results)
+
+        annotated_frame = edge_annotator.annotate(
+            frame.copy(), key_points=key_points)
+        return vertex_annotator.annotate(
+            annotated_frame, key_points=key_points)
+
+    sv.process_video(
+        source_path="skiing.mp4",
+        target_path="result.mp4",
+        callback=callback
+    )
+    ```
+
+<video controls>
+    <source src="https://media.roboflow.com/supervision/video-examples/how-to/track-objects/track-keypoints-only-keypoints.mp4" type="video/mp4">
+</video>
+
+### Convert to Detections
+
+Keypoint tracking is currently supported via the conversion of `KeyPoints` to `Detections`. This is achieved with the [`KeyPoints.as_detections()`](/latest/keypoint/core/#supervision.keypoint.core.KeyPoints.as_detections) function.
+
+Let's convert to detections and visualize the results with our [`BoxAnnotator`](/latest/detection/annotators/#supervision.annotators.core.BoxAnnotator).
+
+!!! tip
+
+    You may use the `selected_keypoint_indices` argument to specify a subset of keypoints to convert. This is useful when some keypoints could be occluded. For example: a person might swing their arm, causing the elbow to be occluded by the torso sometimes.
+
+=== "Ultralytics"
+
+    ```{ .py hl_lines="8 13 19-20" }
+    import numpy as np
+    import supervision as sv
+    from ultralytics import YOLO
+
+    model = YOLO("yolov8m-pose.pt")
+    edge_annotator = sv.EdgeAnnotator()
+    vertex_annotator = sv.VertexAnnotator()
+    box_annotator = sv.BoxAnnotator()
+
+    def callback(frame: np.ndarray, _: int) -> np.ndarray:
+        results = model(frame)[0]
+        key_points = sv.KeyPoints.from_ultralytics(results)
+        detections = key_points.as_detections()
+
+        annotated_frame = edge_annotator.annotate(
+            frame.copy(), key_points=key_points)
+        annotated_frame = vertex_annotator.annotate(
+            annotated_frame, key_points=key_points)
+        return box_annotator.annotate(
+            annotated_frame, detections=detections)
+
+    sv.process_video(
+        source_path="skiing.mp4",
+        target_path="result.mp4",
+        callback=callback
+    )
+    ```
+
+=== "Inference"
+
+    ```{ .py hl_lines="9 14 20-21" }
+    import numpy as np
+    import supervision as sv
+    from inference.models.utils import get_roboflow_model
+
+    model = get_roboflow_model(
+        model_id="yolov8m-pose-640", api_key=<ROBOFLOW API KEY>)
+    edge_annotator = sv.EdgeAnnotator()
+    vertex_annotator = sv.VertexAnnotator()
+    box_annotator = sv.BoxAnnotator()
+
+    def callback(frame: np.ndarray, _: int) -> np.ndarray:
+        results = model.infer(frame)[0]
+        key_points = sv.KeyPoints.from_inference(results)
+        detections = key_points.as_detections()
+
+        annotated_frame = edge_annotator.annotate(
+            frame.copy(), key_points=key_points)
+        annotated_frame = vertex_annotator.annotate(
+            annotated_frame, key_points=key_points)
+        return box_annotator.annotate(
+            annotated_frame, detections=detections)
+
+    sv.process_video(
+        source_path="skiing.mp4",
+        target_path="result.mp4",
+        callback=callback
+    )
+    ```
+
+<video controls>
+    <source src="https://media.roboflow.com/supervision/video-examples/how-to/track-objects/track-keypoints-converted-to-detections.mp4" type="video/mp4">
+</video>
+
+### Keypoint Tracking
+
+Now that we have a `Detections` object, we can track it throughout the video. Utilizing Supervision’s [`sv.ByteTrack`](/latest/trackers/#supervision.tracker.byte_tracker.core.ByteTrack) functionality, each detected object is assigned a unique tracker ID, enabling the continuous following of the object's motion path across different frames. We shall visualize the result with `TraceAnnotator`.
+
+=== "Ultralytics"
+
+    ```{ .py hl_lines="10-11 17 25-26" }
+    import numpy as np
+    import supervision as sv
+    from ultralytics import YOLO
+
+    model = YOLO("yolov8m-pose.pt")
+    edge_annotator = sv.EdgeAnnotator()
+    vertex_annotator = sv.VertexAnnotator()
+    box_annotator = sv.BoxAnnotator()
+
+    tracker = sv.ByteTrack()
+    trace_annotator = sv.TraceAnnotator()
+
+    def callback(frame: np.ndarray, _: int) -> np.ndarray:
+        results = model(frame)[0]
+        key_points = sv.KeyPoints.from_ultralytics(results)
+        detections = key_points.as_detections()
+        detections = tracker.update_with_detections(detections)
+
+        annotated_frame = edge_annotator.annotate(
+            frame.copy(), key_points=key_points)
+        annotated_frame = vertex_annotator.annotate(
+            annotated_frame, key_points=key_points)
+        annotated_frame = box_annotator.annotate(
+            annotated_frame, detections=detections)
+        return trace_annotator.annotate(
+            annotated_frame, detections=detections)
+
+    sv.process_video(
+        source_path="skiing.mp4",
+        target_path="result.mp4",
+        callback=callback
+    )
+    ```
+
+=== "Inference"
+
+    ```{ .py hl_lines="11-12 18 26-27" }
+    import numpy as np
+    import supervision as sv
+    from inference.models.utils import get_roboflow_model
+
+    model = get_roboflow_model(
+        model_id="yolov8m-pose-640", api_key=<ROBOFLOW API KEY>)
+    edge_annotator = sv.EdgeAnnotator()
+    vertex_annotator = sv.VertexAnnotator()
+    box_annotator = sv.BoxAnnotator()
+
+    tracker = sv.ByteTrack()
+    trace_annotator = sv.TraceAnnotator()
+
+    def callback(frame: np.ndarray, _: int) -> np.ndarray:
+        results = model.infer(frame)[0]
+        key_points = sv.KeyPoints.from_inference(results)
+        detections = key_points.as_detections()
+        detections = tracker.update_with_detections(detections)
+
+        annotated_frame = edge_annotator.annotate(
+            frame.copy(), key_points=key_points)
+        annotated_frame = vertex_annotator.annotate(
+            annotated_frame, key_points=key_points)
+        annotated_frame = box_annotator.annotate(
+            annotated_frame, detections=detections)
+        return trace_annotator.annotate(
+            annotated_frame, detections=detections)
+
+    sv.process_video(
+        source_path="skiing.mp4",
+        target_path="result.mp4",
+        callback=callback
+    )
+    ```
+
+<video controls>
+    <source src="https://media.roboflow.com/supervision/video-examples/how-to/track-objects/track-keypoints-with-tracking.mp4" type="video/mp4">
+</video>
+
+### Bonus: Smoothing
+
+We could stop here as we have successfully tracked the object detected by the keypoint model. However, we can further enhance the stability of the boxes by applying [`DetectionsSmoother`](/latest/detection/tools/smoother/). This tool helps in stabilizing the boxes by smoothing the bounding box coordinates across frames. It is very simple to use:
+
+=== "Ultralytics"
+
+    ```{ .py hl_lines="11 19" }
+    import numpy as np
+    import supervision as sv
+    from ultralytics import YOLO
+
+    model = YOLO("yolov8m-pose.pt")
+    edge_annotator = sv.EdgeAnnotator()
+    vertex_annotator = sv.VertexAnnotator()
+    box_annotator = sv.BoxAnnotator()
+
+    tracker = sv.ByteTrack()
+    smoother = sv.DetectionsSmoother()
+    trace_annotator = sv.TraceAnnotator()
+
+    def callback(frame: np.ndarray, _: int) -> np.ndarray:
+        results = model(frame)[0]
+        key_points = sv.KeyPoints.from_ultralytics(results)
+        detections = key_points.as_detections()
+        detections = tracker.update_with_detections(detections)
+        detections = smoother.update_with_detections(detections)
+
+        annotated_frame = edge_annotator.annotate(
+            frame.copy(), key_points=key_points)
+        annotated_frame = vertex_annotator.annotate(
+            annotated_frame, key_points=key_points)
+        annotated_frame = box_annotator.annotate(
+            annotated_frame, detections=detections)
+        return trace_annotator.annotate(
+            annotated_frame, detections=detections)
+
+    sv.process_video(
+        source_path="skiing.mp4",
+        target_path="result.mp4",
+        callback=callback
+    )
+    ```
+
+=== "Inference"
+
+    ```{ .py hl_lines="12 20" }
+    import numpy as np
+    import supervision as sv
+    from inference.models.utils import get_roboflow_model
+
+    model = get_roboflow_model(
+        model_id="yolov8m-pose-640", api_key=<ROBOFLOW API KEY>)
+    edge_annotator = sv.EdgeAnnotator()
+    vertex_annotator = sv.VertexAnnotator()
+    box_annotator = sv.BoxAnnotator()
+
+    tracker = sv.ByteTrack()
+    smoother = sv.DetectionsSmoother()
+    trace_annotator = sv.TraceAnnotator()
+
+    def callback(frame: np.ndarray, _: int) -> np.ndarray:
+        results = model.infer(frame)[0]
+        key_points = sv.KeyPoints.from_inference(results)
+        detections = key_points.as_detections()
+        detections = tracker.update_with_detections(detections)
+        detections = smoother.update_with_detections(detections)
+
+        annotated_frame = edge_annotator.annotate(
+            frame.copy(), key_points=key_points)
+        annotated_frame = vertex_annotator.annotate(
+            annotated_frame, key_points=key_points)
+        annotated_frame = box_annotator.annotate(
+            annotated_frame, detections=detections)
+        return trace_annotator.annotate(
+            annotated_frame, detections=detections)
+
+    sv.process_video(
+        source_path="skiing.mp4",
+        target_path="result.mp4",
+        callback=callback
+    )
+    ```
+
+<video controls>
+    <source src="https://media.roboflow.com/supervision/video-examples/how-to/track-objects/track-keypoints-with-smoothing.mp4" type="video/mp4">
+</video>
+
+This structured walkthrough should give a detailed pathway to annotate videos effectively using Supervision’s various functionalities, including object tracking and trace annotations.

docs/index.md

@@ -34,25 +34,18 @@ You can install `supervision` in a
 [**Python>=3.8**](https://www.python.org/) environment.
 
 !!! example "pip install (recommended)"
-
-    === "headless"
-        The headless installation of `supervision` is designed for environments where graphical user interfaces (GUI) are not needed, making it more lightweight and suitable for server-side applications.
+    === "pip"
+        [![version](https://badge.fury.io/py/supervision.svg)](https://badge.fury.io/py/supervision)
+        [![downloads](https://img.shields.io/pypi/dm/supervision)](https://pypistats.org/packages/supervision)
+        [![license](https://img.shields.io/pypi/l/supervision)](https://github.com/roboflow/supervision/blob/main/LICENSE.md)
+        [![python-version](https://img.shields.io/pypi/pyversions/supervision)](https://badge.fury.io/py/supervision)
 
         ```bash
         pip install supervision
         ```
 
-    === "desktop"
-        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]"
-        ```
-
 !!! example "conda/mamba install"
-
     === "conda"
-
         [![conda-recipe](https://img.shields.io/badge/recipe-supervision-green.svg)](https://anaconda.org/conda-forge/supervision) [![conda-downloads](https://img.shields.io/conda/dn/conda-forge/supervision.svg)](https://anaconda.org/conda-forge/supervision) [![conda-version](https://img.shields.io/conda/vn/conda-forge/supervision.svg)](https://anaconda.org/conda-forge/supervision) [![conda-platforms](https://img.shields.io/conda/pn/conda-forge/supervision.svg)](https://anaconda.org/conda-forge/supervision)
 
         ```bash
@@ -60,7 +53,6 @@ You can install `supervision` in a
         ```
 
     === "mamba"
-
         [![mamba-recipe](https://img.shields.io/badge/recipe-supervision-green.svg)](https://anaconda.org/conda-forge/supervision) [![mamba-downloads](https://img.shields.io/conda/dn/conda-forge/supervision.svg)](https://anaconda.org/conda-forge/supervision) [![mamba-version](https://img.shields.io/conda/vn/conda-forge/supervision.svg)](https://anaconda.org/conda-forge/supervision) [![mamba-platforms](https://img.shields.io/conda/pn/conda-forge/supervision.svg)](https://anaconda.org/conda-forge/supervision)
 
         ```bash
@@ -68,9 +60,7 @@ You can install `supervision` in a
         ```
 
 !!! example "git clone (for development)"
-
     === "virtualenv"
-
         ```bash
         # clone repository and navigate to root directory
         git clone https://github.com/roboflow/supervision.git
@@ -81,15 +71,11 @@ You can install `supervision` in a
         source venv/bin/activate
         pip install --upgrade pip
 
-        # headless install
+        # installation
         pip install -e "."
-
-        # desktop install
-        pip install -e ".[desktop]"
         ```
 
     === "poetry"
-
         ```bash
         # clone repository and navigate to root directory
         git clone https://github.com/roboflow/supervision.git
@@ -99,18 +85,15 @@ You can install `supervision` in a
         poetry env use python3.10
         poetry shell
 
-        # headless install
+        # installation
         poetry install
-
-        # desktop install
-        poetry install --extras "desktop"
         ```
 
 ## 🚀 Quickstart
 
 <div class="grid cards" markdown>
 
--   __Detect and Annotate__
+- **Detect and Annotate**
 
     ---
 
@@ -118,7 +101,7 @@ You can install `supervision` in a
 
     [:octicons-arrow-right-24: Tutorial](how_to/detect_and_annotate.md)
 
--   __Track Objects__
+- **Track Objects**
 
     ---
 
@@ -126,7 +109,7 @@ You can install `supervision` in a
 
     [:octicons-arrow-right-24: Tutorial](how_to/track_objects.md)
 
--   __Detect Small Objects__
+- **Detect Small Objects**
 
     ---
 
@@ -134,25 +117,26 @@ You can install `supervision` in a
 
     [:octicons-arrow-right-24: Tutorial](how_to/detect_small_objects.md)
 
--   > __Count Objects Crossing Line__
+- **Count Objects Crossing Line**
 
     ---
 
     Explore methods to accurately count and analyze objects crossing a predefined line
 
--   > __Filter Objects in Zone__
+    [:octicons-arrow-right-24: Notebook](https://supervision.roboflow.com/latest/notebooks/count-objects-crossing-the-line/)
+
+- > **Filter Objects in Zone**
 
     ---
 
     Master the techniques to selectively filter and focus on objects within a specific zone
 
--   **Cheatsheet**
+- **Cheatsheet**
 
-    ***
+    ---
 
     Access a quick reference guide to the most common `supervision` functions
 
     [:octicons-arrow-right-24: Cheatsheet](https://roboflow.github.io/cheatsheet-supervision/)
 
-
 </div>

docs/keypoint/core.md

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

docs/metrics/common_values.md

@@ -0,0 +1,20 @@
+---
+comments: true
+status: new
+---
+
+# Common Values
+
+This page contains supplementary values, types and enums that metrics use.
+
+<div class="md-typeset">
+    <h2><a href="#supervision.metrics.core.MetricTarget">MetricTarget</a></h2>
+</div>
+
+:::supervision.metrics.core.MetricTarget
+
+<div class="md-typeset">
+    <h2><a href="#supervision.metrics.core.AveragingMethod">AveragingMethod</a></h2>
+</div>
+
+:::supervision.metrics.core.AveragingMethod

docs/metrics/f1_score.md

@@ -0,0 +1,18 @@
+---
+comments: true
+status: new
+---
+
+# F1 Score
+
+<div class="md-typeset">
+    <h2><a href="#supervision.metrics.f1_score.F1Score">F1Score</a></h2>
+</div>
+
+:::supervision.metrics.f1_score.F1Score
+
+<div class="md-typeset">
+    <h2><a href="#supervision.metrics.f1_score.F1ScoreResult">F1ScoreResult</a></h2>
+</div>
+
+:::supervision.metrics.f1_score.F1ScoreResult

docs/metrics/mean_average_recall.md

@@ -0,0 +1,18 @@
+---
+comments: true
+status: new
+---
+
+# Mean Average Recall
+
+<div class="md-typeset">
+    <h2><a href="#supervision.metrics.mean_average_recall.MeanAverageRecall">MeanAverageRecall</a></h2>
+</div>
+
+:::supervision.metrics.mean_average_recall.MeanAverageRecall
+
+<div class="md-typeset">
+    <h2><a href="#supervision.metrics.mean_average_recall.MeanAverageRecallResult">MeanAverageRecallResult</a></h2>
+</div>
+
+:::supervision.metrics.mean_average_recall.MeanAverageRecallResult

docs/metrics/precision.md

@@ -0,0 +1,18 @@
+---
+comments: true
+status: new
+---
+
+# Precision
+
+<div class="md-typeset">
+    <h2><a href="#supervision.metrics.precision.Precision">Precision</a></h2>
+</div>
+
+:::supervision.metrics.precision.Precision
+
+<div class="md-typeset">
+    <h2><a href="#supervision.metrics.precision.PrecisionResult">PrecisionResult</a></h2>
+</div>
+
+:::supervision.metrics.precision.PrecisionResult

docs/metrics/recall.md

@@ -0,0 +1,18 @@
+---
+comments: true
+status: new
+---
+
+# Recall
+
+<div class="md-typeset">
+    <h2><a href="#supervision.metrics.recall.Recall">Recall</a></h2>
+</div>
+
+:::supervision.metrics.recall.Recall
+
+<div class="md-typeset">
+    <h2><a href="#supervision.metrics.recall.RecallResult">RecallResult</a></h2>
+</div>
+
+:::supervision.metrics.recall.RecallResult

docs/notebooks/annotate-video-with-detections.ipynb

@@ -287,10 +287,10 @@
             ],
             "source": [
                 "# Create a bounding box annotator object.\n",
-                "bounding_box = sv.BoundingBoxAnnotator()\n",
+                "box_annotator = sv.BoxAnnotator()\n",
                 "\n",
                 "# Annotate our frame with detections.\n",
-                "annotated_frame = bounding_box.annotate(scene=frame.copy(), detections=detections)\n",
+                "annotated_frame = box_annotator.annotate(scene=frame.copy(), detections=detections)\n",
                 "\n",
                 "# Display the frame.\n",
                 "sv.plot_image(annotated_frame)"
@@ -302,7 +302,7 @@
                 "id": "o8SsyCid6YV3"
             },
             "source": [
-                "Notice that we create a `box_annoator` variable by initalizing a [BoundingBoxAnnotator](https://supervision.roboflow.com/latest/annotators/#boundingboxannotator). We can change the color and thickness, but for simplicity we keep the defaults. There are a ton of easy to use [annotators](https://supervision.roboflow.com/latest/annotators/) available in the Supervision package other than a bounding box that are fun to play with."
+                "Notice that we create a `box_annotator` variable by initalizing a [BoxAnnotator](https://supervision.roboflow.com/latest/detection/annotators/#boxannotator). We can change the color and thickness, but for simplicity we keep the defaults. There are a ton of easy to use [annotators](https://supervision.roboflow.com/latest/detection/annotators/) available in the Supervision package other than a bounding box that are fun to play with."
             ]
         },
         {
@@ -342,7 +342,7 @@
                 "        detections = sv.Detections.from_inference(result)\n",
                 "\n",
                 "        # Apply bounding box to detections on a copy of the frame.\n",
-                "        annotated_frame = bounding_box.annotate(\n",
+                "        annotated_frame = box_annotator.annotate(\n",
                 "            scene=frame.copy(),\n",
                 "            detections=detections\n",
                 "        )\n",
@@ -368,7 +368,7 @@
                 "<br>\n",
                 "\n",
                 "\n",
-                "In the code above we've created a`video_info` variable to pass information about the video to our `VideoSink`. The `VideoSink` is a cool little context manager that allows us to `write_frames()` to a video ouput file. We're also optionally using `tqdm` to display a progress bar with a % complete. We only scratched the surface of all of the customizable Annotators and additional features that Supervision and Inference have to offer. Stay tuned for more cookbooks on how to take advantge of them in your computer vision applications. Happy building! \ud83d\ude80"
+                "In the code above we've created a`video_info` variable to pass information about the video to our `VideoSink`. The `VideoSink` is a cool little context manager that allows us to `write_frames()` to a video output file. We're also optionally using `tqdm` to display a progress bar with a % complete. We only scratched the surface of all of the customizable Annotators and additional features that Supervision and Inference have to offer. Stay tuned for more cookbooks on how to take advantage of them in your computer vision applications. Happy building! \ud83d\ude80"
             ]
         }
     ],

docs/notebooks/occupancy_analytics.ipynb

@@ -951,7 +951,7 @@
             },
             "source": [
                 "#### Import your data\n",
-                "To load your data back in, upload the saved file to the Colab enviorment and run the code cell."
+                "To load your data back in, upload the saved file to the Colab environment and run the code cell."
             ]
         },
         {

docs/theme/cookbooks.html

@@ -50,6 +50,10 @@
         <p class="card repo-card" data-name="Serialise Detections to a JSON File"
           data-labels="DETECTIONS,JSON SINK,INFERENCE" data-version="v0.21.0" data-author="onuralpszr"></p>
       </a>
+      <a href="/develop/notebooks/small-object-detection-with-sahi">
+        <p class="card repo-card" data-name="Small Object Detection with SAHI"
+          data-labels="DETECTIONS,SAHI,SMALL,OBJECT,INFERENCE" data-version="v0.23.0" data-author="ediardo"></p>
+      </a>
     </div>
   </div>
 </section>

docs/trackers.md

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

docs/utils/draw.md

@@ -28,6 +28,12 @@ comments: true
 
 :::supervision.draw.utils.draw_polygon
 
+<div class="md-typeset">
+    <h2><a href="#supervision.draw.utils.draw_filled_polygon">draw_filled_polygon</a></h2>
+</div>
+
+:::supervision.draw.utils.draw_filled_polygon
+
 <div class="md-typeset">
     <h2><a href="#supervision.draw.utils.draw_text">draw_text</a></h2>
 </div>

docs/utils/image.md

@@ -1,6 +1,5 @@
 ---
 comments: true
-status: new
 ---
 
 # Image Utils

docs/utils/video.md

@@ -1,6 +1,5 @@
 ---
 comments: true
-status: new
 ---
 
 # Video Utils

examples/count_people_in_zone/README.md

@@ -16,67 +16,76 @@ https://github.com/roboflow/supervision/assets/26109316/f84db7b5-79e2-4142-a1da-
 
 - clone repository and navigate to example directory
 
-  ```bash
-  git clone https://github.com/roboflow/supervision.git
-  cd supervision/examples/count_people_in_zone
-  ```
+    ```bash
+    git clone https://github.com/roboflow/supervision.git
+    cd supervision/examples/count_people_in_zone
+    ```
 
-- setup python environment and activate it [optional]
+- setup python environment and activate it \[optional\]
 
-  ```bash
-  python3 -m venv venv
-  source venv/bin/activate
-  ```
+    ```bash
+    python3 -m venv venv
+    source venv/bin/activate
+    ```
 
 - install required dependencies
 
-  ```bash
-  pip install -r requirements.txt
-  ```
+    ```bash
+    pip install -r requirements.txt
+    ```
 
 - download `traffic_analysis.pt` and `traffic_analysis.mov` files
 
-  ```bash
-  ./setup.sh
-  ```
+    ```bash
+    ./setup.sh
+    ```
 
 ## 🛠️ script arguments
 
 - ultralytics
 
-  - `--source_weights_path` (optional): The path to the YOLO model's weights file.
-    Defaults to `"yolov8x.pt"` if not specified.
+    - `--source_weights_path` (optional): The path to the YOLO model's weights file.
+        Defaults to `"yolov8x.pt"` if not specified.
 
-  - `--zone_configuration_path`: Specifies the path to the JSON file containing zone
-    configurations. This file defines the polygonal areas in the video where objects will
-    be counted.
-  - `--source_video_path`: The path to the source video file that will be analyzed.
-  - `--target_video_path` (optional): The path to save the output video with annotations.
-    If not provided, the processed video will be displayed in real-time.
-  - `--confidence_threshold` (optional): Sets the confidence threshold for the YOLO model
-    to filter detections. Default is `0.3`.
-  - `--iou_threshold` (optional): Specifies the IOU (Intersection Over Union) threshold
-    for the model. Default is `0.7`.
+    - `--zone_configuration_path`: Specifies the path to the JSON file containing zone
+        configurations. This file defines the polygonal areas in the video where objects will
+        be counted.
+
+    - `--source_video_path`: The path to the source video file that will be analyzed.
+
+    - `--target_video_path` (optional): The path to save the output video with annotations.
+        If not provided, the processed video will be displayed in real-time.
+
+    - `--confidence_threshold` (optional): Sets the confidence threshold for the YOLO model
+        to filter detections. Default is `0.3`.
+
+    - `--iou_threshold` (optional): Specifies the IOU (Intersection Over Union) threshold
+        for the model. Default is `0.7`.
 
 - inference
 
-  - `--roboflow_api_key` (optional): The API key for Roboflow services. If not provided
-    directly, the script tries to fetch it from the `ROBOFLOW_API_KEY` environment
-    variable. Follow [this guide](https://docs.roboflow.com/api-reference/authentication#retrieve-an-api-key)
-    to acquire your `API KEY`.
-  - `--model_id` (optional): Designates the Roboflow model ID to be used. The default
-    value is `"yolov8x-1280"`.
+    - `--roboflow_api_key` (optional): The API key for Roboflow services. If not provided
+        directly, the script tries to fetch it from the `ROBOFLOW_API_KEY` environment
+        variable. Follow [this guide](https://docs.roboflow.com/api-reference/authentication#retrieve-an-api-key)
+        to acquire your `API KEY`.
 
-  - `--zone_configuration_path`: Specifies the path to the JSON file containing zone
-    configurations. This file defines the polygonal areas in the video where objects will
-    be counted.
-  - `--source_video_path`: The path to the source video file that will be analyzed.
-  - `--target_video_path` (optional): The path to save the output video with annotations.
-    If not provided, the processed video will be displayed in real-time.
-  - `--confidence_threshold` (optional): Sets the confidence threshold for the YOLO model
-    to filter detections. Default is `0.3`.
-  - `--iou_threshold` (optional): Specifies the IOU (Intersection Over Union) threshold
-    for the model. Default is `0.7`.
+    - `--model_id` (optional): Designates the Roboflow model ID to be used. The default
+        value is `"yolov8x-1280"`.
+
+    - `--zone_configuration_path`: Specifies the path to the JSON file containing zone
+        configurations. This file defines the polygonal areas in the video where objects will
+        be counted.
+
+    - `--source_video_path`: The path to the source video file that will be analyzed.
+
+    - `--target_video_path` (optional): The path to save the output video with annotations.
+        If not provided, the processed video will be displayed in real-time.
+
+    - `--confidence_threshold` (optional): Sets the confidence threshold for the YOLO model
+        to filter detections. Default is `0.3`.
+
+    - `--iou_threshold` (optional): Specifies the IOU (Intersection Over Union) threshold
+        for the model. Default is `0.7`.
 
 ## 📌 zone configuration
 
@@ -89,35 +98,35 @@ https://github.com/roboflow/supervision/assets/26109316/f84db7b5-79e2-4142-a1da-
 
 - ultralytics
 
-  ```bash
-  python ultralytics_example.py \
-  --zone_configuration_path data/multi-zone-config.json \
-  --source_video_path data/market-square.mp4 \
-  --confidence_threshold 0.3 \
-  --iou_threshold 0.5
-  ```
+    ```bash
+    python ultralytics_example.py \
+        --zone_configuration_path data/multi-zone-config.json \
+        --source_video_path data/market-square.mp4 \
+        --confidence_threshold 0.3 \
+        --iou_threshold 0.5
+    ```
 
 - inference
 
-  ```bash
-  python inference_example.py \
-  --roboflow_api_key <ROBOFLOW API KEY> \
-  --zone_configuration_path data/multi-zone-config.json \
-  --source_video_path data/market-square.mp4 \
-  --confidence_threshold 0.3 \
-  --iou_threshold 0.5
-  ```
+    ```bash
+    python inference_example.py \
+        --roboflow_api_key <ROBOFLOW API KEY> \
+        --zone_configuration_path data/multi-zone-config.json \
+        --source_video_path data/market-square.mp4 \
+        --confidence_threshold 0.3 \
+        --iou_threshold 0.5
+    ```
 
 ## © license
 
 This demo integrates two main components, each with its own licensing:
 
 - ultralytics: The object detection model used in this demo, YOLOv8, is distributed
-  under the [AGPL-3.0 license](https://github.com/ultralytics/ultralytics/blob/main/LICENSE).
-  You can find more details about this license here.
+    under the [AGPL-3.0 license](https://github.com/ultralytics/ultralytics/blob/main/LICENSE).
+    You can find more details about this license here.
 
 - supervision: The analytics code that powers the zone-based analysis in this demo is
-  based on the Supervision library, which is licensed under the
-  [MIT license](https://github.com/roboflow/supervision/blob/develop/LICENSE.md). This
-  makes the Supervision part of the code fully open source and freely usable in your
-  projects.
+    based on the Supervision library, which is licensed under the
+    [MIT license](https://github.com/roboflow/supervision/blob/develop/LICENSE.md). This
+    makes the Supervision part of the code fully open source and freely usable in your
+    projects.

examples/heatmap_and_track/README.md

@@ -6,7 +6,6 @@ This script performs heatmap and tracking analysis using YOLOv8, an object-detec
 ByteTrack, a simple yet effective online multi-object tracking method. It uses the
 supervision package for multiple tasks such as drawing heatmap annotations, tracking objects, etc.
 
-
 ## 💻 install
 
 - clone repository and navigate to example directory
@@ -16,7 +15,7 @@ supervision package for multiple tasks such as drawing heatmap annotations, trac
     cd supervision/examples/heatmap_and_track
     ```
 
-- setup python environment and activate it [optional]
+- setup python environment and activate it \[optional\]
 
     ```bash
     python3 -m venv venv
@@ -32,17 +31,17 @@ supervision package for multiple tasks such as drawing heatmap annotations, trac
 ## 🛠️ script arguments
 
 - `--source_weights_path`: Required. Specifies the path to the weights file for the
-YOLO model. This file contains the trained model data necessary for object detection.
+    YOLO model. This file contains the trained model data necessary for object detection.
 - `--source_video_path` (optional): The path to the source video file that will be
-analyzed. This is the input video on which crowd analysis will be performed.
-If not specified default is `people-walking.mp4` from supervision assets
+    analyzed. This is the input video on which crowd analysis will be performed.
+    If not specified default is `people-walking.mp4` from supervision assets
 - `--target_video_path` (optional): The path to save the output.mp4 video with annotations.
 - `--confidence_threshold` (optional): Sets the confidence threshold for the YOLO model
-to filter detections. Default is `0.3`. This determines how confident the model should
-be to recognize an object in the video.
+    to filter detections. Default is `0.3`. This determines how confident the model should
+    be to recognize an object in the video.
 - `--iou_threshold` (optional): Specifies the IOU (Intersection Over Union) threshold
-for the model. Default is 0.7. This value is used to manage object detection accuracy,
-particularly in distinguishing between different objects.
+    for the model. Default is 0.7. This value is used to manage object detection accuracy,
+    particularly in distinguishing between different objects.
 - `--heatmap_alpha` (optional): Opacity of the overlay mask, between 0 and 1.
 - `--radius` (optional): Radius of the heat circle.
 - `--track_threshold` (optional): Detection confidence threshold for track activation.
@@ -53,11 +52,11 @@ particularly in distinguishing between different objects.
 
 ```bash
 python script.py \
---source_weights_path weight.pt \
---source_video_path  input_video.mp4 \
---confidence_threshold 0.3 \
---iou_threshold 0.5 \
---target_video_path  output_video.mp4
+    --source_weights_path weight.pt \
+    --source_video_path  input_video.mp4 \
+    --confidence_threshold 0.3 \
+    --iou_threshold 0.5 \
+    --target_video_path  output_video.mp4
 ```
 
 ## © license
@@ -65,11 +64,11 @@ python script.py \
 This demo integrates two main components, each with its own licensing:
 
 - ultralytics: The object detection model used in this demo, YOLOv8, is distributed
-  under the [AGPL-3.0 license](https://github.com/ultralytics/ultralytics/blob/main/LICENSE).
-  You can find more details about this license here.
+    under the [AGPL-3.0 license](https://github.com/ultralytics/ultralytics/blob/main/LICENSE).
+    You can find more details about this license here.
 
 - supervision: The analytics code that powers the zone-based analysis in this demo is
-  based on the Supervision library, which is licensed under the
-  [MIT license](https://github.com/roboflow/supervision/blob/develop/LICENSE.md). This
-  makes the Supervision part of the code fully open source and freely usable in your
-  projects.
+    based on the Supervision library, which is licensed under the
+    [MIT license](https://github.com/roboflow/supervision/blob/develop/LICENSE.md). This
+    makes the Supervision part of the code fully open source and freely usable in your
+    projects.

examples/speed_estimation/README.md

@@ -11,7 +11,7 @@ supervision package for multiple tasks such as tracking, annotations, etc.
 
 https://github.com/roboflow/supervision/assets/26109316/d50118c1-2ae4-458d-915a-5d860fd36f71
 
-> [!IMPORTANT]
+> \[!IMPORTANT\]
 > Adjust the [`SOURCE`](https://github.com/roboflow/supervision/blob/e32b05a636dab2ea1f39299e529c4b22b8baa8da/examples/speed_estimation/ultralytics_example.py#L10)
 > and [`TARGET`](https://github.com/roboflow/supervision/blob/e32b05a636dab2ea1f39299e529c4b22b8baa8da/examples/speed_estimation/ultralytics_example.py#L15)
 > configuration if you plan to run a speed estimation script on your video file. Those must be adjusted separately for each camera view. You can learn more
@@ -21,97 +21,102 @@ https://github.com/roboflow/supervision/assets/26109316/d50118c1-2ae4-458d-915a-
 
 - clone repository and navigate to example directory
 
-  ```bash
-  git clone https://github.com/roboflow/supervision.git
-  cd supervision/examples/speed_estimation
-  ```
+    ```bash
+    git clone https://github.com/roboflow/supervision.git
+    cd supervision/examples/speed_estimation
+    ```
 
-- setup python environment and activate it [optional]
+- setup python environment and activate it \[optional\]
 
-  ```bash
-  python3.10 -m venv venv
-  source venv/bin/activate
-  ```
+    ```bash
+    python3.10 -m venv venv
+    source venv/bin/activate
+    ```
 
 - install required dependencies
 
-  ```bash
-  pip install -r requirements.txt
-  ```
+    ```bash
+    pip install -r requirements.txt
+    ```
 
 - download `vehicles.mp4` file
 
-  ```bash
-  python3.10 video_downloader.py
-  ```
+    ```bash
+    python3.10 video_downloader.py
+    ```
 
 ## 🛠️ script arguments
 
 - `--roboflow_api_key` (optional): The API key for Roboflow services. If not provided
-  directly, the script tries to fetch it from the `ROBOFLOW_API_KEY` environment
-  variable. Follow [this guide](https://docs.roboflow.com/api-reference/authentication#retrieve-an-api-key)
-  to acquire your `API KEY`.
+    directly, the script tries to fetch it from the `ROBOFLOW_API_KEY` environment
+    variable. Follow [this guide](https://docs.roboflow.com/api-reference/authentication#retrieve-an-api-key)
+    to acquire your `API KEY`.
+
 - `--model_id` (optional): Designates the Roboflow model ID to be used. The default
-  value is `"yolov8x-1280"`.
+    value is `"yolov8x-1280"`.
 
 - `--source_weights_path`: Required. Specifies the path to the YOLO model's weights
-  file, which is essential for the object detection process. This file contains the
-  data that the model uses to identify objects in the video.
+    file, which is essential for the object detection process. This file contains the
+    data that the model uses to identify objects in the video.
+
 - `--source_video_path`: Required. The path to the source video file that will be
-  analyzed. This is the input video on which traffic flow analysis will be performed.
+    analyzed. This is the input video on which traffic flow analysis will be performed.
+
 - `--target_video_path`: The path to save the output video with
-  annotations. If not specified, the processed video will be displayed in real-time
-  without being saved.
+    annotations. If not specified, the processed video will be displayed in real-time
+    without being saved.
+
 - `--confidence_threshold` (optional): Sets the confidence threshold for the YOLO
-  model to filter detections. Default is `0.3`. This determines how confident the
-  model should be to recognize an object in the video.
+    model to filter detections. Default is `0.3`. This determines how confident the
+    model should be to recognize an object in the video.
+
 - `--iou_threshold` (optional): Specifies the IOU (Intersection Over Union) threshold
-  for the model. Default is 0.7. This value is used to manage object detection
-  accuracy, particularly in distinguishing between different objects.
+    for the model. Default is 0.7. This value is used to manage object detection
+    accuracy, particularly in distinguishing between different objects.
 
 ## ⚙️ run
 
 - yolo-nas
 
-  ```bash
+    ```bash
     python yolo_nas_example.py \
-    --source_video_path data/vehicles.mp4 \
-    --target_video_path data/vehicles-result.mp4 \
-    --confidence_threshold 0.3 \
-    --iou_threshold 0.5
-  ```
+        --source_video_path data/vehicles.mp4 \
+        --target_video_path data/vehicles-result.mp4 \
+        --confidence_threshold 0.3 \
+        --iou_threshold 0.5
+    ```
 
 - inference
 
-  ```bash
+    ```bash
     python inference_example.py \
-    --roboflow_api_key <ROBOFLOW API KEY> \
-    --source_video_path data/vehicles.mp4 \
-    --target_video_path data/vehicles-result.mp4 \
-    --confidence_threshold 0.3 \
-    --iou_threshold 0.5
-  ```
+        --roboflow_api_key <ROBOFLOW API KEY> \
+        --source_video_path data/vehicles.mp4 \
+        --target_video_path data/vehicles-result.mp4 \
+        --confidence_threshold 0.3 \
+        --iou_threshold 0.5
+    ```
 
 - ultralytics
 
-  ```bash
+    ```bash
     python ultralytics_example.py \
-    --source_video_path data/vehicles.mp4 \
-    --target_video_path data/vehicles-result.mp4 \
-    --confidence_threshold 0.3 \
-    --iou_threshold 0.5
-  ```
+        --source_video_path data/vehicles.mp4 \
+        --target_video_path data/vehicles-result.mp4 \
+        --confidence_threshold 0.3 \
+        --iou_threshold 0.5
+    ```
 
 ## © license
 
 This demo integrates two main components, each with its own licensing:
 
 - ultralytics: The object detection model used in this demo, YOLOv8, is distributed
-  under the [AGPL-3.0 license](https://github.com/ultralytics/ultralytics/blob/main/LICENSE).
-  You can find more details about this license here.
+    under the [AGPL-3.0 license](https://github.com/ultralytics/ultralytics/blob/main/LICENSE).
+    You can find more details about this license here.
 
 - supervision: The analytics code that powers the zone-based analysis in this demo is
-  based on the Supervision library, which is licensed under the
-  [MIT license](https://github.com/roboflow/supervision/blob/develop/LICENSE.md). This
-  makes the Supervision part of the code fully open source and freely usable in your
-  projects.
+    based on the Supervision library, which is licensed under the
+    [MIT license](https://github.com/roboflow/supervision/blob/develop/LICENSE.md). This
+    makes the Supervision part of the code fully open source and freely usable in your
+    projects.

examples/time_in_zone/README.md

@@ -15,23 +15,23 @@ https://github.com/roboflow/supervision/assets/26109316/d051cc8a-dd15-41d4-aa36-
 
 - clone repository and navigate to example directory
 
-  ```bash
-  git clone https://github.com/roboflow/supervision.git
-  cd supervision/examples/time_in_zone
-  ```
+    ```bash
+    git clone https://github.com/roboflow/supervision.git
+    cd supervision/examples/time_in_zone
+    ```
 
-- setup python environment and activate it [optional]
+- setup python environment and activate it \[optional\]
 
-  ```bash
-  python3 -m venv venv
-  source venv/bin/activate
-  ```
+    ```bash
+    python3 -m venv venv
+    source venv/bin/activate
+    ```
 
 - install required dependencies
 
-  ```bash
-  pip install -r requirements.txt
-  ```
+    ```bash
+    pip install -r requirements.txt
+    ```
 
 ## 🛠 scripts
 
@@ -45,16 +45,16 @@ This script allows you to download a video from YouTube.
 
 ```bash
 python scripts/download_from_youtube.py \
---url "https://www.youtube.com/watch?v=-8zyEwAa50Q" \
---output_path "data/checkout" \
---file_name "video.mp4"
+    --url "https://www.youtube.com/watch?v=-8zyEwAa50Q" \
+    --output_path "data/checkout" \
+    --file_name "video.mp4"
 ```
 
 ```bash
 python scripts/download_from_youtube.py \
---url "https://www.youtube.com/watch?v=MNn9qKG2UFI" \
---output_path "data/traffic" \
---file_name "video.mp4"
+    --url "https://www.youtube.com/watch?v=MNn9qKG2UFI" \
+    --output_path "data/traffic" \
+    --file_name "video.mp4"
 ```
 
 ### `stream_from_file`
@@ -68,14 +68,14 @@ mock a live video stream for local testing. Video will be streamed in a loop und
 
 ```bash
 python scripts/stream_from_file.py \
---video_directory "data/checkout" \
---number_of_streams 1
+    --video_directory "data/checkout" \
+    --number_of_streams 1
 ```
 
 ```bash
 python scripts/stream_from_file.py \
---video_directory "data/traffic" \
---number_of_streams 1
+    --video_directory "data/traffic" \
+    --number_of_streams 1
 ```
 
 ### `draw_zones`
@@ -86,24 +86,27 @@ window where you can draw polygons on the source image or video file. The polygo
 be saved as a JSON file.
 
 - `--source_path`: Path to the source image or video file for drawing polygons.
+
 - `--zone_configuration_path`: Path where the polygon annotations will be saved as a JSON file.
 
-
 - `enter` - finish drawing the current polygon.
+
 - `escape` - cancel drawing the current polygon.
+
 - `q` - quit the drawing window.
+
 - `s` - save zone configuration to a JSON file.
 
 ```bash
 python scripts/draw_zones.py \
---source_path "data/checkout/video.mp4" \
---zone_configuration_path "data/checkout/config.json"
+    --source_path "data/checkout/video.mp4" \
+    --zone_configuration_path "data/checkout/config.json"
 ```
 
 ```bash
 python scripts/draw_zones.py \
---source_path "data/traffic/video.mp4" \
---zone_configuration_path "data/traffic/config.json"
+    --source_path "data/traffic/video.mp4" \
+    --zone_configuration_path "data/traffic/config.json"
 ```
 
 https://github.com/roboflow/supervision/assets/26109316/9d514c9e-2a61-418b-ae49-6ac1ad6ae5ac
@@ -114,33 +117,33 @@ https://github.com/roboflow/supervision/assets/26109316/9d514c9e-2a61-418b-ae49-
 
 Script to run object detection on a video file using the Roboflow Inference model.
 
-  - `--zone_configuration_path`: Path to the zone configuration JSON file.
-  - `--source_video_path`: Path to the source video file.
-  - `--model_id`: Roboflow model ID.
-  - `--classes`: List of class IDs to track. If empty, all classes are tracked.
-  - `--confidence_threshold`: Confidence level for detections (`0` to `1`). Default is `0.3`.
-  - `--iou_threshold`: IOU threshold for non-max suppression. Default is `0.7`.
+- `--zone_configuration_path`: Path to the zone configuration JSON file.
+- `--source_video_path`: Path to the source video file.
+- `--model_id`: Roboflow model ID.
+- `--classes`: List of class IDs to track. If empty, all classes are tracked.
+- `--confidence_threshold`: Confidence level for detections (`0` to `1`). Default is `0.3`.
+- `--iou_threshold`: IOU threshold for non-max suppression. Default is `0.7`.
 
 ```bash
 python inference_file_example.py \
---zone_configuration_path "data/checkout/config.json" \
---source_video_path "data/checkout/video.mp4" \
---model_id "yolov8x-640" \
---classes 0 \
---confidence_threshold 0.3 \
---iou_threshold 0.7
+    --zone_configuration_path "data/checkout/config.json" \
+    --source_video_path "data/checkout/video.mp4" \
+    --model_id "yolov8x-640" \
+    --classes 0 \
+    --confidence_threshold 0.3 \
+    --iou_threshold 0.7
 ```
 
 https://github.com/roboflow/supervision/assets/26109316/d051cc8a-dd15-41d4-aa36-d38b86334c39
 
 ```bash
 python inference_file_example.py \
---zone_configuration_path "data/traffic/config.json" \
---source_video_path "data/traffic/video.mp4" \
---model_id "yolov8x-640" \
---classes 2 5 6 7 \
---confidence_threshold 0.3 \
---iou_threshold 0.7
+    --zone_configuration_path "data/traffic/config.json" \
+    --source_video_path "data/traffic/video.mp4" \
+    --model_id "yolov8x-640" \
+    --classes 2 5 6 7 \
+    --confidence_threshold 0.3 \
+    --iou_threshold 0.7
 ```
 
 https://github.com/roboflow/supervision/assets/26109316/5ec896d7-4b39-4426-8979-11e71666878b
@@ -149,31 +152,31 @@ https://github.com/roboflow/supervision/assets/26109316/5ec896d7-4b39-4426-8979-
 
 Script to run object detection on a video stream using the Roboflow Inference model.
 
-  - `--zone_configuration_path`: Path to the zone configuration JSON file.
-  - `--rtsp_url`: Complete RTSP URL for the video stream.
-  - `--model_id`: Roboflow model ID.
-  - `--classes`: List of class IDs to track. If empty, all classes are tracked.
-  - `--confidence_threshold`: Confidence level for detections (`0` to `1`). Default is `0.3`.
-  - `--iou_threshold`: IOU threshold for non-max suppression. Default is `0.7`.
+- `--zone_configuration_path`: Path to the zone configuration JSON file.
+- `--rtsp_url`: Complete RTSP URL for the video stream.
+- `--model_id`: Roboflow model ID.
+- `--classes`: List of class IDs to track. If empty, all classes are tracked.
+- `--confidence_threshold`: Confidence level for detections (`0` to `1`). Default is `0.3`.
+- `--iou_threshold`: IOU threshold for non-max suppression. Default is `0.7`.
 
 ```bash
 python inference_stream_example.py \
---zone_configuration_path "data/checkout/config.json" \
---rtsp_url "rtsp://localhost:8554/live0.stream" \
---model_id "yolov8x-640" \
---classes 0 \
---confidence_threshold 0.3 \
---iou_threshold 0.7
+    --zone_configuration_path "data/checkout/config.json" \
+    --rtsp_url "rtsp://localhost:8554/live0.stream" \
+    --model_id "yolov8x-640" \
+    --classes 0 \
+    --confidence_threshold 0.3 \
+    --iou_threshold 0.7
 ```
 
 ```bash
 python inference_stream_example.py \
---zone_configuration_path "data/traffic/config.json" \
---rtsp_url "rtsp://localhost:8554/live0.stream" \
---model_id "yolov8x-640" \
---classes 2 5 6 7 \
---confidence_threshold 0.3 \
---iou_threshold 0.7
+    --zone_configuration_path "data/traffic/config.json" \
+    --rtsp_url "rtsp://localhost:8554/live0.stream" \
+    --model_id "yolov8x-640" \
+    --classes 2 5 6 7 \
+    --confidence_threshold 0.3 \
+    --iou_threshold 0.7
 ```
 
 <details>
@@ -183,68 +186,68 @@ python inference_stream_example.py \
 
 Script to run object detection on a video file using the Ultralytics YOLOv8 model.
 
-  - `--zone_configuration_path`: Path to the zone configuration JSON file.
-  - `--source_video_path`: Path to the source video file.
-  - `--weights`: Path to the model weights file. Default is `'yolov8s.pt'`.
-  - `--device`: Computation device (`'cpu'`, `'mps'` or `'cuda'`). Default is `'cpu'`.
-  - `--classes`: List of class IDs to track. If empty, all classes are tracked.
-  - `--confidence_threshold`: Confidence level for detections (`0` to `1`). Default is `0.3`.
-  - `--iou_threshold`: IOU threshold for non-max suppression. Default is `0.7`.
+- `--zone_configuration_path`: Path to the zone configuration JSON file.
+- `--source_video_path`: Path to the source video file.
+- `--weights`: Path to the model weights file. Default is `'yolov8s.pt'`.
+- `--device`: Computation device (`'cpu'`, `'mps'` or `'cuda'`). Default is `'cpu'`.
+- `--classes`: List of class IDs to track. If empty, all classes are tracked.
+- `--confidence_threshold`: Confidence level for detections (`0` to `1`). Default is `0.3`.
+- `--iou_threshold`: IOU threshold for non-max suppression. Default is `0.7`.
 
 ```bash
 python ultralytics_file_example.py \
---zone_configuration_path "data/checkout/config.json" \
---source_video_path "data/checkout/video.mp4" \
---weights "yolov8x.pt" \
---device "cpu" \
---classes 0 \
---confidence_threshold 0.3 \
---iou_threshold 0.7
+    --zone_configuration_path "data/checkout/config.json" \
+    --source_video_path "data/checkout/video.mp4" \
+    --weights "yolov8x.pt" \
+    --device "cpu" \
+    --classes 0 \
+    --confidence_threshold 0.3 \
+    --iou_threshold 0.7
 ```
 
 ```bash
 python ultralytics_file_example.py \
---zone_configuration_path "data/traffic/config.json" \
---source_video_path "data/traffic/video.mp4" \
---weights "yolov8x.pt" \
---device "cpu" \
---classes 2 5 6 7 \
---confidence_threshold 0.3 \
---iou_threshold 0.7
+    --zone_configuration_path "data/traffic/config.json" \
+    --source_video_path "data/traffic/video.mp4" \
+    --weights "yolov8x.pt" \
+    --device "cpu" \
+    --classes 2 5 6 7 \
+    --confidence_threshold 0.3 \
+    --iou_threshold 0.7
 ```
 
 ### `ultralytics_stream_example`
 
 Script to run object detection on a video stream using the Ultralytics YOLOv8 model.
 
-  - `--zone_configuration_path`: Path to the zone configuration JSON file.
-  - `--rtsp_url`: Complete RTSP URL for the video stream.
-  - `--weights`: Path to the model weights file. Default is `'yolov8s.pt'`.
-  - `--device`: Computation device (`'cpu'`, `'mps'` or `'cuda'`). Default is `'cpu'`.
-  - `--classes`: List of class IDs to track. If empty, all classes are tracked.
-  - `--confidence_threshold`: Confidence level for detections (`0` to `1`). Default is `0.3`.
-  - `--iou_threshold`: IOU threshold for non-max suppression. Default is `0.7`.
+- `--zone_configuration_path`: Path to the zone configuration JSON file.
+- `--rtsp_url`: Complete RTSP URL for the video stream.
+- `--weights`: Path to the model weights file. Default is `'yolov8s.pt'`.
+- `--device`: Computation device (`'cpu'`, `'mps'` or `'cuda'`). Default is `'cpu'`.
+- `--classes`: List of class IDs to track. If empty, all classes are tracked.
+- `--confidence_threshold`: Confidence level for detections (`0` to `1`). Default is `0.3`.
+- `--iou_threshold`: IOU threshold for non-max suppression. Default is `0.7`.
 
 ```bash
 python ultralytics_stream_example.py \
---zone_configuration_path "data/checkout/config.json" \
---rtsp_url "rtsp://localhost:8554/live0.stream" \
---weights "yolov8x.pt" \
---device "cpu" \
---classes 0 \
---confidence_threshold 0.3 \
---iou_threshold 0.7
+    --zone_configuration_path "data/checkout/config.json" \
+    --rtsp_url "rtsp://localhost:8554/live0.stream" \
+    --weights "yolov8x.pt" \
+    --device "cpu" \
+    --classes 0 \
+    --confidence_threshold 0.3 \
+    --iou_threshold 0.7
 ```
 
 ```bash
 python ultralytics_stream_example.py \
---zone_configuration_path "data/traffic/config.json" \
---rtsp_url "rtsp://localhost:8554/live0.stream" \
---weights "yolov8x.pt" \
---device "cpu" \
---classes 2 5 6 7 \
---confidence_threshold 0.3 \
---iou_threshold 0.7
+    --zone_configuration_path "data/traffic/config.json" \
+    --rtsp_url "rtsp://localhost:8554/live0.stream" \
+    --weights "yolov8x.pt" \
+    --device "cpu" \
+    --classes 2 5 6 7 \
+    --confidence_threshold 0.3 \
+    --iou_threshold 0.7
 ```
 
 </details>
@@ -254,11 +257,11 @@ python ultralytics_stream_example.py \
 This demo integrates two main components, each with its own licensing:
 
 - ultralytics: The object detection model used in this demo, YOLOv8, is distributed
-  under the [AGPL-3.0 license](https://github.com/ultralytics/ultralytics/blob/main/LICENSE).
-  You can find more details about this license here.
+    under the [AGPL-3.0 license](https://github.com/ultralytics/ultralytics/blob/main/LICENSE).
+    You can find more details about this license here.
 
 - supervision: The analytics code that powers the zone-based analysis in this demo is
-  based on the Supervision library, which is licensed under the
-  [MIT license](https://github.com/roboflow/supervision/blob/develop/LICENSE.md). This
-  makes the Supervision part of the code fully open source and freely usable in your
-  projects.
+    based on the Supervision library, which is licensed under the
+    [MIT license](https://github.com/roboflow/supervision/blob/develop/LICENSE.md). This
+    makes the Supervision part of the code fully open source and freely usable in your
+    projects.

examples/tracking/README.md

@@ -9,93 +9,100 @@ detection and Supervision for tracking and annotation.
 
 - clone repository and navigate to example directory
 
-  ```bash
-  git clone https://github.com/roboflow/supervision.git
-  cd supervision/examples/tracking
-  ```
+    ```bash
+    git clone https://github.com/roboflow/supervision.git
+    cd supervision/examples/tracking
+    ```
 
-- setup python environment and activate it [optional]
+- setup python environment and activate it \[optional\]
 
-  ```bash
-  python3 -m venv venv
-  source venv/bin/activate
-  ```
+    ```bash
+    python3 -m venv venv
+    source venv/bin/activate
+    ```
 
 - install required dependencies
 
-  ```bash
-  pip install -r requirements.txt
-  ```
+    ```bash
+    pip install -r requirements.txt
+    ```
 
 ## 🛠️ script arguments
 
 - ultralytics
 
-  - `--source_weights_path`: Required. Specifies the path to the YOLO model's weights
-    file, which is essential for the object detection process. This file contains the data
-    that the model uses to identify objects in the video.
+    - `--source_weights_path`: Required. Specifies the path to the YOLO model's weights
+        file, which is essential for the object detection process. This file contains the data
+        that the model uses to identify objects in the video.
 
-  - `--source_video_path`: Required. The path to the source video file to be processed.
-    This is the video on which object detection and annotation will be performed.
-  - `--target_video_path`: Required. The path where the processed video, with annotations
-    added, will be saved. This is your output video file.
-  - `--confidence_threshold` (optional): Sets the confidence level at which the model
-    identifies objects in the video. Default is `0.3`. A higher threshold makes the model
-    more selective, while a lower threshold makes it more inclusive in identifying objects.
-  - `--iou_threshold` (optional): Specifies the IOU (Intersection Over Union) threshold
-    for the model, defaulting to `0.7`. This parameter helps in differentiating between
-    distinct objects, especially in crowded scenes.
+    - `--source_video_path`: Required. The path to the source video file to be processed.
+        This is the video on which object detection and annotation will be performed.
+
+    - `--target_video_path`: Required. The path where the processed video, with annotations
+        added, will be saved. This is your output video file.
+
+    - `--confidence_threshold` (optional): Sets the confidence level at which the model
+        identifies objects in the video. Default is `0.3`. A higher threshold makes the model
+        more selective, while a lower threshold makes it more inclusive in identifying objects.
+
+    - `--iou_threshold` (optional): Specifies the IOU (Intersection Over Union) threshold
+        for the model, defaulting to `0.7`. This parameter helps in differentiating between
+        distinct objects, especially in crowded scenes.
 
 - inference
 
-  - `--roboflow_api_key` (optional): The API key for Roboflow services. If not provided
-    directly, the script tries to fetch it from the `ROBOFLOW_API_KEY` environment
-    variable. Follow [this guide](https://docs.roboflow.com/api-reference/authentication#retrieve-an-api-key)
-    to acquire your `API KEY`.
-  - `--model_id` (optional): Designates the Roboflow model ID to be used. The default
-    value is `"yolov8x-1280"`.
+    - `--roboflow_api_key` (optional): The API key for Roboflow services. If not provided
+        directly, the script tries to fetch it from the `ROBOFLOW_API_KEY` environment
+        variable. Follow [this guide](https://docs.roboflow.com/api-reference/authentication#retrieve-an-api-key)
+        to acquire your `API KEY`.
 
-  - `--source_video_path`: Required. The path to the source video file to be processed.
-    This is the video on which object detection and annotation will be performed.
-  - `--target_video_path`: Required. The path where the processed video, with annotations
-    added, will be saved. This is your output video file.
-  - `--confidence_threshold` (optional): Sets the confidence level at which the model
-    identifies objects in the video. Default is `0.3`. A higher threshold makes the model
-    more selective, while a lower threshold makes it more inclusive in identifying objects.
-  - `--iou_threshold` (optional): Specifies the IOU (Intersection Over Union) threshold
-    for the model, defaulting to `0.7`. This parameter helps in differentiating between
-    distinct objects, especially in crowded scenes.
+    - `--model_id` (optional): Designates the Roboflow model ID to be used. The default
+        value is `"yolov8x-1280"`.
+
+    - `--source_video_path`: Required. The path to the source video file to be processed.
+        This is the video on which object detection and annotation will be performed.
+
+    - `--target_video_path`: Required. The path where the processed video, with annotations
+        added, will be saved. This is your output video file.
+
+    - `--confidence_threshold` (optional): Sets the confidence level at which the model
+        identifies objects in the video. Default is `0.3`. A higher threshold makes the model
+        more selective, while a lower threshold makes it more inclusive in identifying objects.
+
+    - `--iou_threshold` (optional): Specifies the IOU (Intersection Over Union) threshold
+        for the model, defaulting to `0.7`. This parameter helps in differentiating between
+        distinct objects, especially in crowded scenes.
 
 ## ⚙️ run
 
 - inference
 
-  ```bash
-  python inference_example.py \
-  --roboflow_api_key <ROBOFLOW API KEY> \
-  --source_video_path input.mp4 \
-  --target_video_path tracking_result.mp4
-  ```
+    ```bash
+    python inference_example.py \
+        --roboflow_api_key <ROBOFLOW API KEY> \
+        --source_video_path input.mp4 \
+        --target_video_path tracking_result.mp4
+    ```
 
 - ultralytics
 
-  ```bash
-  python ultralytics_example.py \
-  --source_weights_path yolov8s.pt \
-  --source_video_path input.mp4 \
-  --target_video_path tracking_result.mp4
-  ```
+    ```bash
+    python ultralytics_example.py \
+        --source_weights_path yolov8s.pt \
+        --source_video_path input.mp4 \
+        --target_video_path tracking_result.mp4
+    ```
 
 ## © license
 
 This demo integrates two main components, each with its own licensing:
 
 - ultralytics: The object detection model used in this demo, YOLOv8, is distributed
-  under the [AGPL-3.0 license](https://github.com/ultralytics/ultralytics/blob/main/LICENSE).
-  You can find more details about this license here.
+    under the [AGPL-3.0 license](https://github.com/ultralytics/ultralytics/blob/main/LICENSE).
+    You can find more details about this license here.
 
 - supervision: The analytics code that powers the zone-based analysis in this demo is
-  based on the Supervision library, which is licensed under the
-  [MIT license](https://github.com/roboflow/supervision/blob/develop/LICENSE.md). This
-  makes the Supervision part of the code fully open source and freely usable in your
-  projects.
+    based on the Supervision library, which is licensed under the
+    [MIT license](https://github.com/roboflow/supervision/blob/develop/LICENSE.md). This
+    makes the Supervision part of the code fully open source and freely usable in your
+    projects.

examples/traffic_analysis/README.md

@@ -12,105 +12,112 @@ https://github.com/roboflow/supervision/assets/26109316/c9436828-9fbf-4c25-ae8c-
 
 - clone repository and navigate to example directory
 
-  ```bash
-  git clone https://github.com/roboflow/supervision.git
-  cd supervision/examples/traffic_analysis
-  ```
+    ```bash
+    git clone https://github.com/roboflow/supervision.git
+    cd supervision/examples/traffic_analysis
+    ```
 
-- setup python environment and activate it [optional]
+- setup python environment and activate it \[optional\]
 
-  ```bash
-  python3 -m venv venv
-  source venv/bin/activate
-  ```
+    ```bash
+    python3 -m venv venv
+    source venv/bin/activate
+    ```
 
 - install required dependencies
 
-  ```bash
-  pip install -r requirements.txt
-  ```
+    ```bash
+    pip install -r requirements.txt
+    ```
 
 - download `traffic_analysis.pt` and `traffic_analysis.mov` files
 
-  ```bash
-  ./setup.sh
-  ```
+    ```bash
+    ./setup.sh
+    ```
 
 ## 🛠️ script arguments
 
 - ultralytics
 
-  - `--source_weights_path`: Required. Specifies the path to the YOLO model's weights
-    file, which is essential for the object detection process. This file contains the
-    data that the model uses to identify objects in the video.
+    - `--source_weights_path`: Required. Specifies the path to the YOLO model's weights
+        file, which is essential for the object detection process. This file contains the
+        data that the model uses to identify objects in the video.
 
-  - `--source_video_path`: Required. The path to the source video file that will be
-    analyzed. This is the input video on which traffic flow analysis will be performed.
-  - `--target_video_path` (optional): The path to save the output video with
-    annotations. If not specified, the processed video will be displayed in real-time
-    without being saved.
-  - `--confidence_threshold` (optional): Sets the confidence threshold for the YOLO
-    model to filter detections. Default is `0.3`. This determines how confident the
-    model should be to recognize an object in the video.
-  - `--iou_threshold` (optional): Specifies the IOU (Intersection Over Union) threshold
-    for the model. Default is 0.7. This value is used to manage object detection
-    accuracy, particularly in distinguishing between different objects.
+    - `--source_video_path`: Required. The path to the source video file that will be
+        analyzed. This is the input video on which traffic flow analysis will be performed.
+
+    - `--target_video_path` (optional): The path to save the output video with
+        annotations. If not specified, the processed video will be displayed in real-time
+        without being saved.
+
+    - `--confidence_threshold` (optional): Sets the confidence threshold for the YOLO
+        model to filter detections. Default is `0.3`. This determines how confident the
+        model should be to recognize an object in the video.
+
+    - `--iou_threshold` (optional): Specifies the IOU (Intersection Over Union) threshold
+        for the model. Default is 0.7. This value is used to manage object detection
+        accuracy, particularly in distinguishing between different objects.
 
 - inference
 
-  - `--roboflow_api_key` (optional): The API key for Roboflow services. If not provided
-    directly, the script tries to fetch it from the `ROBOFLOW_API_KEY` environment
-    variable. Follow [this guide](https://docs.roboflow.com/api-reference/authentication#retrieve-an-api-key)
-    to acquire your `API KEY`.
-  - `--model_id` (optional): Designates the Roboflow model ID to be used. The default
-    value is `"vehicle-count-in-drone-video/6"`.
+    - `--roboflow_api_key` (optional): The API key for Roboflow services. If not provided
+        directly, the script tries to fetch it from the `ROBOFLOW_API_KEY` environment
+        variable. Follow [this guide](https://docs.roboflow.com/api-reference/authentication#retrieve-an-api-key)
+        to acquire your `API KEY`.
 
-  - `--source_video_path`: Required. The path to the source video file that will be
-    analyzed. This is the input video on which traffic flow analysis will be performed.
-  - `--target_video_path` (optional): The path to save the output video with
-    annotations. If not specified, the processed video will be displayed in real-time
-    without being saved.
-  - `--confidence_threshold` (optional): Sets the confidence threshold for the YOLO
-    model to filter detections. Default is `0.3`. This determines how confident the
-    model should be to recognize an object in the video.
-  - `--iou_threshold` (optional): Specifies the IOU (Intersection Over Union) threshold
-    for the model. Default is 0.7. This value is used to manage object detection
-    accuracy, particularly in distinguishing between different objects.
+    - `--model_id` (optional): Designates the Roboflow model ID to be used. The default
+        value is `"vehicle-count-in-drone-video/6"`.
+
+    - `--source_video_path`: Required. The path to the source video file that will be
+        analyzed. This is the input video on which traffic flow analysis will be performed.
+
+    - `--target_video_path` (optional): The path to save the output video with
+        annotations. If not specified, the processed video will be displayed in real-time
+        without being saved.
+
+    - `--confidence_threshold` (optional): Sets the confidence threshold for the YOLO
+        model to filter detections. Default is `0.3`. This determines how confident the
+        model should be to recognize an object in the video.
+
+    - `--iou_threshold` (optional): Specifies the IOU (Intersection Over Union) threshold
+        for the model. Default is 0.7. This value is used to manage object detection
+        accuracy, particularly in distinguishing between different objects.
 
 ## ⚙️ run
 
 - ultralytics
 
-  ```bash
-  python ultralytics_example.py \
-  --source_weights_path data/traffic_analysis.pt \
-  --source_video_path data/traffic_analysis.mov \
-  --confidence_threshold 0.3 \
-  --iou_threshold 0.5 \
-  --target_video_path data/traffic_analysis_result.mov
-  ```
+    ```bash
+    python ultralytics_example.py \
+        --source_weights_path data/traffic_analysis.pt \
+        --source_video_path data/traffic_analysis.mov \
+        --confidence_threshold 0.3 \
+        --iou_threshold 0.5 \
+        --target_video_path data/traffic_analysis_result.mov
+    ```
 
 - inference
 
-  ```bash
-  python inference_example.py \
-  --roboflow_api_key <ROBOFLOW API KEY> \
-  --source_video_path data/traffic_analysis.mov \
-  --confidence_threshold 0.3 \
-  --iou_threshold 0.5 \
-  --target_video_path data/traffic_analysis_result.mov
-  ```
+    ```bash
+    python inference_example.py \
+        --roboflow_api_key <ROBOFLOW API KEY> \
+        --source_video_path data/traffic_analysis.mov \
+        --confidence_threshold 0.3 \
+        --iou_threshold 0.5 \
+        --target_video_path data/traffic_analysis_result.mov
+    ```
 
 ## © license
 
 This demo integrates two main components, each with its own licensing:
 
 - ultralytics: The object detection model used in this demo, YOLOv8, is distributed
-  under the [AGPL-3.0 license](https://github.com/ultralytics/ultralytics/blob/main/LICENSE).
-  You can find more details about this license here.
+    under the [AGPL-3.0 license](https://github.com/ultralytics/ultralytics/blob/main/LICENSE).
+    You can find more details about this license here.
 
 - supervision: The analytics code that powers the zone-based analysis in this demo is
-  based on the Supervision library, which is licensed under the
-  [MIT license](https://github.com/roboflow/supervision/blob/develop/LICENSE.md). This
-  makes the Supervision part of the code fully open source and freely usable in your
-  projects.
+    based on the Supervision library, which is licensed under the
+    [MIT license](https://github.com/roboflow/supervision/blob/develop/LICENSE.md). This
+    makes the Supervision part of the code fully open source and freely usable in your
+    projects.

examples/traffic_analysis/inference_example.py

@@ -1,6 +1,6 @@
 import argparse
 import os
-from typing import Dict, Iterable, List, Set
+from typing import Dict, Iterable, List, Optional, Set
 
 import cv2
 import numpy as np
@@ -77,7 +77,7 @@ class VideoProcessor:
         roboflow_api_key: str,
         model_id: str,
         source_video_path: str,
-        target_video_path: str = None,
+        target_video_path: Optional[str] = None,
         confidence_threshold: float = 0.3,
         iou_threshold: float = 0.7,
     ) -> None:

examples/traffic_analysis/ultralytics_example.py

@@ -1,5 +1,5 @@
 import argparse
-from typing import Dict, Iterable, List, Set
+from typing import Dict, Iterable, List, Optional, Set
 
 import cv2
 import numpy as np
@@ -74,7 +74,7 @@ class VideoProcessor:
         self,
         source_weights_path: str,
         source_video_path: str,
-        target_video_path: str = None,
+        target_video_path: Optional[str] = None,
         confidence_threshold: float = 0.3,
         iou_threshold: float = 0.7,
     ) -> None:

mkdocs.yml

@@ -66,6 +66,11 @@ nav:
           - Utils: datasets/utils.md
       - Metrics:
           - mAP: metrics/mean_average_precision.md
+          - mAR: metrics/mean_average_recall.md
+          - Precision: metrics/precision.md
+          - Recall: metrics/recall.md
+          - F1 Score: metrics/f1_score.md
+          - Common Values: metrics/common_values.md
           - Legacy Metrics: detection/metrics.md
       - Utils:
           - Video: utils/video.md

pyproject.toml

@@ -1,15 +1,18 @@
 [tool.poetry]
 name = "supervision"
-version = "0.23.0"
+version = "0.25.0"
 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>"]
+maintainers = [
+    "Piotr Skalski <piotr.skalski92@gmail.com>",
+    "Linas Kondrackis <linas@roboflow.com>",
+]
 readme = "README.md"
 license = "MIT"
-packages = [{ include = "supervision" }]
+packages = [{ include = "supervision" }, { include = "supervision/py.typed" }]
 homepage = "https://github.com/roboflow/supervision"
 repository = "https://github.com/roboflow/supervision"
-documentation = "https://github.com/roboflow/supervision/blob/main/README.md"
+documentation = "https://supervision.roboflow.com/latest/"
 keywords = [
     "machine-learning",
     "deep-learning",
@@ -43,32 +46,45 @@ python = "^3.8"
 numpy = [
     { version = ">=1.21.2,<1.23.3", python = "<=3.10" },
     { version = ">=1.23.3", python = ">3.10" },
+    { version = ">=2.1.0", python = ">=3.13" },
 ]
 scipy = [
     { version = "1.10.0", python = "<3.9" },
     { version = "^1.10.0", python = ">=3.9" },
+    { version = ">=1.14.1", python = ">=3.13" },
+
 ]
+
+# Matplotlib sub-dependency
+# The 'contourpy' package is required by Matplotlib for contour plotting.
+# We need to ensure compatibility with both Python 3.8 and Python 3.13.
+#
+# For Python 3.8 and above, we use version 1.0.7 or higher, as it is the lowest major version that supports Python 3.8.
+# For Python 3.13 and above, we use version 1.3.0 or higher, as it is the first version that explicitly supports Python 3.13.
+contourpy = [
+    { version = ">=1.0.7", python = ">=3.8" },
+    { version = ">=1.3.0", python = ">=3.13" },
+]
+
 matplotlib = ">=3.6.0"
 pyyaml = ">=5.3"
 defusedxml = "^0.7.1"
 pillow = ">=9.4"
-opencv-python = { version = ">=4.5.5.64", optional = true }
-opencv-python-headless = ">=4.5.5.64"
 requests = { version = ">=2.26.0,<=2.32.3", optional = true }
-tqdm = { version = ">=4.62.3,<=4.66.5", optional = true }
+tqdm = { version = ">=4.62.3,<=4.67.0", optional = true }
 # pandas: picked lowest major version that supports Python 3.8
 pandas = { version = ">=2.0.0", optional = true }
 pandas-stubs = { version = ">=2.0.0.230412", optional = true }
+opencv-python = ">=4.5.5.64"
 
 [tool.poetry.extras]
-desktop = ["opencv-python"]
 assets = ["requests", "tqdm"]
 metrics = ["pandas", "pandas-stubs"]
 
 [tool.poetry.group.dev.dependencies]
 twine = "^5.1.1"
 pytest = ">=7.2.2,<9.0.0"
-wheel = ">=0.40,<0.45"
+wheel = ">=0.40,<0.46"
 build = ">=0.10,<1.3"
 ruff = ">=0.1.0"
 mypy = "^1.4.1"
@@ -85,12 +101,13 @@ docutils = [
 
 [tool.poetry.group.docs.dependencies]
 mkdocs-material = { extras = ["imaging"], version = "^9.5.5" }
-mkdocstrings = { extras = ["python"], version = "^0.25.2" }
+mkdocstrings = ">=0.25.2,<0.27.0"
+mkdocstrings-python = "^1.10.9"
 mike = "^2.0.0"
 # For Documentation Development use Python 3.10 or above
 # Use Latest mkdocs-jupyter min 0.24.6 for Jupyter Notebook Theme support
 mkdocs-jupyter = "^0.24.3"
-mkdocs-git-committers-plugin-2 = "^2.2.3"
+mkdocs-git-committers-plugin-2 = "^2.4.1"
 mkdocs-git-revision-date-localized-plugin = "^1.2.4"
 
 [tool.poetry.group.typecheck]
@@ -111,24 +128,6 @@ tests = ["B201", "B301", "B318", "B314", "B303", "B413", "B412", "B410"]
 check = true
 imports = ["cv2", "supervision"]
 
-[tool.black]
-target-version = ["py38"]
-line-length = 88
-include = '\.pyi?$'
-exclude = '''
-/(
-    \.git
-  | \.hg
-  | \.mypy_cache
-  | \.tox
-  | \.venv
-  | _build
-  | buck-out
-  | build
-  | dist
-  | docs
-)/
-'''
 
 [tool.ruff]
 target-version = "py38"
@@ -166,7 +165,7 @@ indent-width = 4
 
 [tool.ruff.lint]
 # Enable pycodestyle (`E`) and Pyflakes (`F`) codes by default.
-select = ["E", "F", "I", "A", "Q", "W"]
+select = ["E", "F", "I", "A", "Q", "W", "RUF"]
 ignore = []
 # Allow autofix for all enabled rules (when `--fix`) is provided.
 fixable = [
@@ -252,6 +251,12 @@ skip-magic-trailing-comma = false
 # Like Black, automatically detect the appropriate line ending.
 line-ending = "auto"
 
+[tool.codespell]
+skip = "*.ipynb,poetry.lock"
+count = true
+quiet-level = 3
+ignore-words-list = "STrack,sTrack,strack"
+
 [tool.setuptools]
 include-package-data = false
 

release_process.md

@@ -6,19 +6,19 @@ It assumes you already have the code changes, as well as a draft of the release
 
 1. Make sure you have all required changes were merged into `develop`.
 2. Create and merge a PR, merging `develop` into `main`, containing:
-   - A commit that updates the project version in `pyproject.toml`.
-   - All changes made during the release.
+    - A commit that updates the project version in `pyproject.toml`.
+    - All changes made during the release.
 3. Tag the commit with the new supervision version.
-   - make sure to pull from `main` !
-   - Verify that the latest merge commits exists. `git log`.
-   - Run `git tag x.y.z`, with your version
-   - Check with `git log`.
-   - Run `git push origin --tags`
-   - Upon pushing the tag, the [PyPi](https://pypi.org/project/supervision/) should update to the new version. Check this!
+    - make sure to pull from `main` !
+    - Verify that the latest merge commits exists. `git log`.
+    - Run `git tag x.y.z`, with your version
+    - Check with `git log`.
+    - Run `git push origin --tags`
+    - Upon pushing the tag, the [PyPi](https://pypi.org/project/supervision/) should update to the new version. Check this!
 4. Open and merge a PR, merging `main` into `develop`.
 5. Update the docs by running the [Supervision Release Documentation Workflow 📚](https://github.com/roboflow/supervision/actions/workflows/publish-release-docs.yml) workflow from GitHub.
-   - Select the `main` branch from the dropdown.
+    - Select the `main` branch from the dropdown.
 6. Create a release on GitHub.
-   - Go to releases
-   - Assign the release notes to the tag created in step 3.
-   - Publish the release.
+    - Go to releases
+    - Assign the release notes to the tag created in step 3.
+    - Publish the release.

supervision/__init__.py

@@ -40,7 +40,11 @@ from supervision.dataset.core import (
 )
 from supervision.dataset.utils import mask_to_rle, rle_to_mask
 from supervision.detection.core import Detections
-from supervision.detection.line_zone import LineZone, LineZoneAnnotator
+from supervision.detection.line_zone import (
+    LineZone,
+    LineZoneAnnotator,
+    LineZoneAnnotatorMulticlass,
+)
 from supervision.detection.lmm import LMM
 from supervision.detection.overlap_filter import (
     OverlapFilter,
@@ -65,6 +69,7 @@ from supervision.detection.utils import (
     mask_to_xyxy,
     move_boxes,
     move_masks,
+    oriented_box_iou_batch,
     pad_boxes,
     polygon_to_mask,
     polygon_to_xyxy,
@@ -76,6 +81,7 @@ from supervision.draw.color import Color, ColorPalette
 from supervision.draw.utils import (
     calculate_optimal_line_thickness,
     calculate_optimal_text_scale,
+    draw_filled_polygon,
     draw_filled_rectangle,
     draw_image,
     draw_line,

supervision/annotators/core.py

@@ -16,7 +16,7 @@ from supervision.annotators.utils import (
 )
 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
+from supervision.detection.utils import clip_boxes, mask_to_polygons, spread_out_boxes
 from supervision.draw.color import Color, ColorPalette
 from supervision.draw.utils import draw_polygon
 from supervision.geometry.core import Position
@@ -32,6 +32,8 @@ from supervision.utils.image import (
 )
 from supervision.utils.internal import deprecated
 
+CV2_FONT = cv2.FONT_HERSHEY_SIMPLEX
+
 
 class BoxAnnotator(BaseAnnotator):
     """
@@ -68,7 +70,8 @@ class BoxAnnotator(BaseAnnotator):
 
         Args:
             scene (ImageType): The image where bounding boxes will be drawn. `ImageType`
-            is a flexible type, accepting either `numpy.ndarray` or `PIL.Image.Image`.
+                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.
@@ -1053,6 +1056,7 @@ class LabelAnnotator(BaseAnnotator):
         text_position: Position = Position.TOP_LEFT,
         color_lookup: ColorLookup = ColorLookup.CLASS,
         border_radius: int = 0,
+        smart_position: bool = False,
     ):
         """
         Args:
@@ -1069,6 +1073,7 @@ class LabelAnnotator(BaseAnnotator):
                 Options are `INDEX`, `CLASS`, `TRACK`.
             border_radius (int): The radius to apply round edges. If the selected
                 value is higher than the lower dimension, width or height, is clipped.
+            smart_position (bool): Spread out the labels to avoid overlapping.
         """
         self.border_radius: int = border_radius
         self.color: Union[Color, ColorPalette] = color
@@ -1078,6 +1083,7 @@ class LabelAnnotator(BaseAnnotator):
         self.text_padding: int = text_padding
         self.text_anchor: Position = text_position
         self.color_lookup: ColorLookup = color_lookup
+        self.smart_position = smart_position
 
     @ensure_cv2_image_for_annotation
     def annotate(
@@ -1127,11 +1133,29 @@ class LabelAnnotator(BaseAnnotator):
         ![label-annotator-example](https://media.roboflow.com/
         supervision-annotator-examples/label-annotator-example-purple.png)
         """
+
         assert isinstance(scene, np.ndarray)
-        font = cv2.FONT_HERSHEY_SIMPLEX
-        anchors_coordinates = detections.get_anchors_coordinates(
-            anchor=self.text_anchor
-        ).astype(int)
+        self._validate_labels(labels, detections)
+
+        labels = self._get_labels_text(detections, labels)
+        label_properties = self._get_label_properties(detections, labels)
+
+        if self.smart_position:
+            xyxy = label_properties[:, :4]
+            xyxy = spread_out_boxes(xyxy)
+            label_properties[:, :4] = xyxy
+
+        self._draw_labels(
+            scene=scene,
+            labels=labels,
+            label_properties=label_properties,
+            detections=detections,
+            custom_color_lookup=custom_color_lookup,
+        )
+
+        return scene
+
+    def _validate_labels(self, labels: Optional[List[str]], detections: Detections):
         if labels is not None and len(labels) != len(detections):
             raise ValueError(
                 f"The number of labels ({len(labels)}) does not match the "
@@ -1139,72 +1163,121 @@ class LabelAnnotator(BaseAnnotator):
                 f"should have exactly 1 label."
             )
 
-        for detection_idx, center_coordinates in enumerate(anchors_coordinates):
-            color = resolve_color(
-                color=self.color,
-                detections=detections,
-                detection_idx=detection_idx,
-                color_lookup=(
-                    self.color_lookup
-                    if custom_color_lookup is None
-                    else custom_color_lookup
-                ),
-            )
+    def _get_label_properties(
+        self,
+        detections: Detections,
+        labels: List[str],
+    ) -> np.ndarray:
+        """
+        Calculate the numerical properties required to draw the labels on the image.
 
-            text_color = resolve_color(
-                color=self.text_color,
-                detections=detections,
-                detection_idx=detection_idx,
-                color_lookup=(
-                    self.color_lookup
-                    if custom_color_lookup is None
-                    else custom_color_lookup
-                ),
-            )
+        Returns:
+            (np.ndarray): An array of label properties, containing columns:
+                `min_x`, `min_y`, `max_x`, `max_y`, `padded_text_height`.
+        """
+        label_properties = []
+        anchors_coordinates = detections.get_anchors_coordinates(
+            anchor=self.text_anchor
+        ).astype(int)
 
-            if labels is not None:
-                text = labels[detection_idx]
-            elif CLASS_NAME_DATA_FIELD in detections.data:
-                text = detections.data[CLASS_NAME_DATA_FIELD][detection_idx]
-            elif detections.class_id is not None:
-                text = str(detections.class_id[detection_idx])
-            else:
-                text = str(detection_idx)
-
-            text_w, text_h = cv2.getTextSize(
-                text=text,
-                fontFace=font,
+        for label, center_coords in zip(labels, anchors_coordinates):
+            (text_w, text_h) = cv2.getTextSize(
+                text=label,
+                fontFace=CV2_FONT,
                 fontScale=self.text_scale,
                 thickness=self.text_thickness,
             )[0]
-            text_w_padded = text_w + 2 * self.text_padding
-            text_h_padded = text_h + 2 * self.text_padding
+
+            width_padded = text_w + 2 * self.text_padding
+            height_padded = text_h + 2 * self.text_padding
+
             text_background_xyxy = resolve_text_background_xyxy(
-                center_coordinates=tuple(center_coordinates),
-                text_wh=(text_w_padded, text_h_padded),
+                center_coordinates=tuple(center_coords),
+                text_wh=(width_padded, height_padded),
                 position=self.text_anchor,
             )
 
-            text_x = text_background_xyxy[0] + self.text_padding
-            text_y = text_background_xyxy[1] + self.text_padding + text_h
+            label_properties.append(
+                [
+                    *text_background_xyxy,
+                    text_h,
+                ]
+            )
 
+        return np.array(label_properties).reshape(-1, 5)
+
+    @staticmethod
+    def _get_labels_text(
+        detections: Detections, custom_labels: Optional[List[str]]
+    ) -> List[str]:
+        if custom_labels is not None:
+            return custom_labels
+
+        labels = []
+        for idx in range(len(detections)):
+            if CLASS_NAME_DATA_FIELD in detections.data:
+                labels.append(detections.data[CLASS_NAME_DATA_FIELD][idx])
+            elif detections.class_id is not None:
+                labels.append(str(detections.class_id[idx]))
+            else:
+                labels.append(str(idx))
+        return labels
+
+    def _draw_labels(
+        self,
+        scene: np.ndarray,
+        labels: List[str],
+        label_properties: np.ndarray,
+        detections: Detections,
+        custom_color_lookup: Optional[np.ndarray],
+    ) -> None:
+        assert len(labels) == len(label_properties) == len(detections), (
+            f"Number of label properties ({len(label_properties)}), "
+            f"labels ({len(labels)}) and detections ({len(detections)}) "
+            "do not match."
+        )
+
+        color_lookup = (
+            custom_color_lookup
+            if custom_color_lookup is not None
+            else self.color_lookup
+        )
+
+        for idx, label_property in enumerate(label_properties):
+            background_color = resolve_color(
+                color=self.color,
+                detections=detections,
+                detection_idx=idx,
+                color_lookup=color_lookup,
+            )
+            text_color = resolve_color(
+                color=self.text_color,
+                detections=detections,
+                detection_idx=idx,
+                color_lookup=color_lookup,
+            )
+
+            box_xyxy = label_property[:4]
+            text_height_padded = label_property[4]
             self.draw_rounded_rectangle(
                 scene=scene,
-                xyxy=text_background_xyxy,
-                color=color.as_bgr(),
+                xyxy=box_xyxy,
+                color=background_color.as_bgr(),
                 border_radius=self.border_radius,
             )
+
+            text_x = box_xyxy[0] + self.text_padding
+            text_y = box_xyxy[1] + self.text_padding + text_height_padded
             cv2.putText(
                 img=scene,
-                text=text,
+                text=labels[idx],
                 org=(text_x, text_y),
-                fontFace=font,
+                fontFace=CV2_FONT,
                 fontScale=self.text_scale,
                 color=text_color.as_bgr(),
                 thickness=self.text_thickness,
                 lineType=cv2.LINE_AA,
             )
-        return scene
 
     @staticmethod
     def draw_rounded_rectangle(
@@ -1265,6 +1338,7 @@ class RichLabelAnnotator(BaseAnnotator):
         text_position: Position = Position.TOP_LEFT,
         color_lookup: ColorLookup = ColorLookup.CLASS,
         border_radius: int = 0,
+        smart_position: bool = False,
     ):
         """
         Args:
@@ -1281,6 +1355,7 @@ class RichLabelAnnotator(BaseAnnotator):
                 Options are `INDEX`, `CLASS`, `TRACK`.
             border_radius (int): The radius to apply round edges. If the selected
                 value is higher than the lower dimension, width or height, is clipped.
+            smart_position (bool): Spread out the labels to avoid overlapping.
         """
         self.color = color
         self.text_color = text_color
@@ -1288,14 +1363,8 @@ class RichLabelAnnotator(BaseAnnotator):
         self.text_anchor = text_position
         self.color_lookup = color_lookup
         self.border_radius = border_radius
-        if font_path is not None:
-            try:
-                self.font = ImageFont.truetype(font_path, font_size)
-            except OSError:
-                print(f"Font path '{font_path}' not found. Using PIL's default font.")
-                self.font = self._load_default_font(font_size)
-        else:
-            self.font = self._load_default_font(font_size)
+        self.smart_position = smart_position
+        self.font = self._load_font(font_size, font_path)
 
     @ensure_pil_image_for_annotation
     def annotate(
@@ -1345,88 +1414,157 @@ class RichLabelAnnotator(BaseAnnotator):
 
         """
         assert isinstance(scene, Image.Image)
+        self._validate_labels(labels, detections)
+
         draw = ImageDraw.Draw(scene)
-        anchors_coordinates = detections.get_anchors_coordinates(
-            anchor=self.text_anchor
-        ).astype(int)
+        labels = self._get_labels_text(detections, labels)
+        label_properties = self._get_label_properties(draw, detections, labels)
+
+        if self.smart_position:
+            xyxy = label_properties[:, :4]
+            xyxy = spread_out_boxes(xyxy)
+            label_properties[:, :4] = xyxy
+
+        self._draw_labels(
+            draw=draw,
+            labels=labels,
+            label_properties=label_properties,
+            detections=detections,
+            custom_color_lookup=custom_color_lookup,
+        )
+
+        return scene
+
+    def _validate_labels(self, labels: Optional[List[str]], detections: Detections):
         if labels is not None and len(labels) != len(detections):
             raise ValueError(
-                f"The number of labels provided ({len(labels)}) does not match the "
-                f"number of detections ({len(detections)}). Each detection should have "
-                f"a corresponding label."
-            )
-        for detection_idx, center_coordinates in enumerate(anchors_coordinates):
-            color = resolve_color(
-                color=self.color,
-                detections=detections,
-                detection_idx=detection_idx,
-                color_lookup=(
-                    self.color_lookup
-                    if custom_color_lookup is None
-                    else custom_color_lookup
-                ),
+                f"The number of labels ({len(labels)}) does not match the "
+                f"number of detections ({len(detections)}). Each detection "
+                f"should have exactly 1 label."
             )
 
-            text_color = resolve_color(
-                color=self.text_color,
-                detections=detections,
-                detection_idx=detection_idx,
-                color_lookup=(
-                    self.color_lookup
-                    if custom_color_lookup is None
-                    else custom_color_lookup
-                ),
+    def _get_label_properties(
+        self, draw, detections: Detections, labels: List[str]
+    ) -> np.ndarray:
+        """
+        Calculate the numerical properties required to draw the labels on the image.
+
+        Returns:
+            (np.ndarray): An array of label properties, containing columns:
+                `min_x`, `min_y`, `max_x`, `max_y`, `text_left_coordinate`,
+                `text_top_coordinate`. The first 4 values are already padded
+                with `text_padding`.
+        """
+        label_properties = []
+
+        anchor_coordinates = detections.get_anchors_coordinates(
+            anchor=self.text_anchor
+        ).astype(int)
+
+        for label, center_coords in zip(labels, anchor_coordinates):
+            text_left, text_top, text_right, text_bottom = draw.textbbox(
+                (0, 0), label, font=self.font
             )
+            text_width = text_right - text_left
+            text_height = text_bottom - text_top
+            width_padded = text_width + 2 * self.text_padding
+            height_padded = text_height + 2 * self.text_padding
 
-            if labels is not None:
-                text = labels[detection_idx]
-            elif CLASS_NAME_DATA_FIELD in detections.data:
-                text = detections.data[CLASS_NAME_DATA_FIELD][detection_idx]
-            elif detections.class_id is not None:
-                text = str(detections.class_id[detection_idx])
-            else:
-                text = str(detection_idx)
-
-            left, top, right, bottom = draw.textbbox((0, 0), text, font=self.font)
-            text_width = right - left
-            text_height = bottom - top
-            text_w_padded = text_width + 2 * self.text_padding
-            text_h_padded = text_height + 2 * self.text_padding
             text_background_xyxy = resolve_text_background_xyxy(
-                center_coordinates=tuple(center_coordinates),
-                text_wh=(text_w_padded, text_h_padded),
+                center_coordinates=tuple(center_coords),
+                text_wh=(width_padded, height_padded),
                 position=self.text_anchor,
             )
 
-            text_x = text_background_xyxy[0] + self.text_padding - left
-            text_y = text_background_xyxy[1] + self.text_padding - top
+            label_properties.append([*text_background_xyxy, text_left, text_top])
+
+        return np.array(label_properties).reshape(-1, 6)
+
+    @staticmethod
+    def _get_labels_text(
+        detections: Detections, custom_labels: Optional[List[str]]
+    ) -> List[str]:
+        if custom_labels is not None:
+            return custom_labels
+
+        labels = []
+        for idx in range(len(detections)):
+            if CLASS_NAME_DATA_FIELD in detections.data:
+                labels.append(detections.data[CLASS_NAME_DATA_FIELD][idx])
+            elif detections.class_id is not None:
+                labels.append(str(detections.class_id[idx]))
+            else:
+                labels.append(str(idx))
+        return labels
+
+    def _draw_labels(
+        self,
+        draw,
+        labels: List[str],
+        label_properties: np.ndarray,
+        detections: Detections,
+        custom_color_lookup: Optional[np.ndarray],
+    ) -> None:
+        assert len(labels) == len(label_properties) == len(detections), (
+            f"Number of label properties ({len(label_properties)}), "
+            f"labels ({len(labels)}) and detections ({len(detections)}) "
+            "do not match."
+        )
+        color_lookup = (
+            custom_color_lookup
+            if custom_color_lookup is not None
+            else self.color_lookup
+        )
+
+        for idx, label_property in enumerate(label_properties):
+            background_color = resolve_color(
+                color=self.color,
+                detections=detections,
+                detection_idx=idx,
+                color_lookup=color_lookup,
+            )
+            text_color = resolve_color(
+                color=self.text_color,
+                detections=detections,
+                detection_idx=idx,
+                color_lookup=color_lookup,
+            )
+
+            box_xyxy = label_property[:4]
+            text_left = label_property[4]
+            text_top = label_property[5]
+            label_x_position = box_xyxy[0] + self.text_padding - text_left
+            label_y_position = box_xyxy[1] + self.text_padding - text_top
 
             draw.rounded_rectangle(
-                text_background_xyxy,
+                tuple(box_xyxy),
                 radius=self.border_radius,
-                fill=color.as_rgb(),
+                fill=background_color.as_rgb(),
                 outline=None,
             )
             draw.text(
-                xy=(text_x, text_y),
-                text=text,
+                xy=(label_x_position, label_y_position),
+                text=labels[idx],
                 font=self.font,
                 fill=text_color.as_rgb(),
             )
-        return scene
 
     @staticmethod
-    def _load_default_font(size):
-        """
-        PIL either loads a font that accepts a size (e.g. on my machine)
-        or raises an error saying `load_default` does not accept arguments
-        (e.g. in Colab).
-        """
+    def _load_font(font_size: int, font_path: Optional[str]):
+        def load_default_font(size):
+            try:
+                return ImageFont.load_default(size)
+            except TypeError:
+                return ImageFont.load_default()
+
+        if font_path is None:
+            return load_default_font(font_size)
+
         try:
-            font = ImageFont.load_default(size)
-        except TypeError:
-            font = ImageFont.load_default()
-        return font
+            return ImageFont.truetype(font_path, font_size)
+        except OSError:
+            print(f"Font path '{font_path}' not found. Using PIL's default font.")
+            return load_default_font(font_size)
 
 
 class IconAnnotator(BaseAnnotator):

supervision/annotators/utils.py

@@ -51,14 +51,17 @@ def resolve_color_idx(
         if detections.class_id is None:
             raise ValueError(
                 "Could not resolve color by class because "
-                "Detections do not have class_id"
+                "Detections do not have class_id. If using an annotator, "
+                "try setting color_lookup to sv.ColorLookup.INDEX or "
+                "sv.ColorLookup.TRACK."
             )
         return detections.class_id[detection_idx]
     elif color_lookup == ColorLookup.TRACK:
         if detections.tracker_id is None:
             raise ValueError(
                 "Could not resolve color by track because "
-                "Detections do not have tracker_id"
+                "Detections do not have tracker_id. Did you call "
+                "tracker.update_with_detections(...) before annotating?"
             )
         return detections.tracker_id[detection_idx]
 

supervision/assets/list.py

@@ -20,6 +20,7 @@ class VideoAssets(Enum):
     | `PEOPLE_WALKING`       | `people-walking.mp4`       | [Link](https://media.roboflow.com/supervision/video-examples/people-walking.mp4)      |
     | `BEACH`                | `beach-1.mp4`              | [Link](https://media.roboflow.com/supervision/video-examples/beach-1.mp4)             |
     | `BASKETBALL`           | `basketball-1.mp4`         | [Link](https://media.roboflow.com/supervision/video-examples/basketball-1.mp4)        |
+    | `SKIING`               | `skiing.mp4`               | [Link](https://media.roboflow.com/supervision/video-examples/skiing.mp4)              |
     """  # noqa: E501 // docs
 
     VEHICLES = "vehicles.mp4"
@@ -31,6 +32,7 @@ class VideoAssets(Enum):
     PEOPLE_WALKING = "people-walking.mp4"
     BEACH = "beach-1.mp4"
     BASKETBALL = "basketball-1.mp4"
+    SKIING = "skiing.mp4"
 
     @classmethod
     def list(cls):
@@ -74,4 +76,8 @@ VIDEO_ASSETS: Dict[str, Tuple[str, str]] = {
         f"{BASE_VIDEO_URL}{VideoAssets.BASKETBALL.value}",
         "60d94a3c7c47d16f09d342b088012ecc",
     ),
+    VideoAssets.SKIING.value: (
+        f"{BASE_VIDEO_URL}{VideoAssets.SKIING.value}",
+        "d30987cbab1bbc5934199cdd1b293119",
+    ),
 }

supervision/dataset/utils.py

@@ -55,7 +55,7 @@ def merge_class_lists(class_lists: List[List[str]]) -> List[str]:
 
     for class_list in class_lists:
         for class_name in class_list:
-            unique_classes.add(class_name.lower())
+            unique_classes.add(class_name)
 
     return sorted(list(unique_classes))
 

supervision/detection/core.py

@@ -6,7 +6,10 @@ from typing import Any, Dict, Iterator, List, Optional, Tuple, Union
 
 import numpy as np
 
-from supervision.config import CLASS_NAME_DATA_FIELD, ORIENTED_BOX_COORDINATES
+from supervision.config import (
+    CLASS_NAME_DATA_FIELD,
+    ORIENTED_BOX_COORDINATES,
+)
 from supervision.detection.lmm import (
     LMM,
     from_florence_2,
@@ -29,8 +32,10 @@ from supervision.detection.utils import (
     extract_ultralytics_masks,
     get_data_item,
     is_data_equal,
+    is_metadata_equal,
     mask_to_xyxy,
     merge_data,
+    merge_metadata,
     process_roboflow_result,
     xywh_to_xyxy,
 )
@@ -45,7 +50,7 @@ class Detections:
     The `sv.Detections` class in the Supervision library standardizes results from
     various object detection and segmentation models into a consistent format. This
     class simplifies data manipulation and filtering, providing a uniform API for
-    integration with Supervision [trackers](/trackers/), [annotators](/detection/annotators/), and [tools](/detection/tools/line_zone/).
+    integration with Supervision [trackers](/trackers/), [annotators](/latest/detection/annotators/), and [tools](/detection/tools/line_zone/).
 
     === "Inference"
 
@@ -122,6 +127,9 @@ class Detections:
         data (Dict[str, Union[np.ndarray, List]]): A dictionary containing additional
             data where each key is a string representing the data type, and the value
             is either a NumPy array or a list of corresponding data.
+        metadata (Dict[str, Any]): A dictionary containing collection-level metadata
+            that applies to the entire set of detections. This may include information such
+            as the video name, camera parameters, timestamp, or other global metadata.
     """  # noqa: E501 // docs
 
     xyxy: np.ndarray
@@ -130,6 +138,7 @@ class Detections:
     class_id: Optional[np.ndarray] = None
     tracker_id: Optional[np.ndarray] = None
     data: Dict[str, Union[np.ndarray, List]] = field(default_factory=dict)
+    metadata: Dict[str, Any] = field(default_factory=dict)
 
     def __post_init__(self):
         validate_detections_fields(
@@ -182,6 +191,7 @@ class Detections:
                 np.array_equal(self.confidence, other.confidence),
                 np.array_equal(self.tracker_id, other.tracker_id),
                 is_data_equal(self.data, other.data),
+                is_metadata_equal(self.metadata, other.metadata),
             ]
         )
 
@@ -249,7 +259,7 @@ class Detections:
             results = model(image)[0]
             detections = sv.Detections.from_ultralytics(results)
             ```
-        """  # noqa: E501 // docs
+        """
 
         if hasattr(ultralytics_results, "obb") and ultralytics_results.obb is not None:
             class_id = ultralytics_results.obb.cls.cpu().numpy().astype(int)
@@ -356,7 +366,7 @@ class Detections:
             result = model(img)
             detections = sv.Detections.from_tensorflow(result)
             ```
-        """  # noqa: E501 // docs
+        """
 
         boxes = tensorflow_results["detection_boxes"][0].numpy()
         boxes[:, [0, 2]] *= resolution_wh[0]
@@ -431,7 +441,7 @@ class Detections:
             result = inference_detector(model, image)
             detections = sv.Detections.from_mmdetection(result)
             ```
-        """  # noqa: E501 // docs
+        """
 
         return cls(
             xyxy=mmdet_results.pred_instances.bboxes.cpu().numpy(),
@@ -490,7 +500,7 @@ class Detections:
                 id2label=model.config.id2label
             )
             ```
-        """  # noqa: E501 // docs
+        """
 
         if (
             transformers_results.__class__.__name__ == "Tensor"
@@ -514,14 +524,21 @@ class Detections:
                 **process_transformers_detection_result(transformers_results, id2label)
             )
 
+        else:
+            raise ValueError(
+                "The provided Transformers results do not contain any valid fields."
+                " Expected fields are 'boxes', 'masks', 'segments_info' or"
+                " 'segmentation'."
+            )
+
     @classmethod
-    def from_detectron2(cls, detectron2_results) -> Detections:
+    def from_detectron2(cls, detectron2_results: Any) -> Detections:
         """
         Create a Detections object from the
         [Detectron2](https://github.com/facebookresearch/detectron2) inference result.
 
         Args:
-            detectron2_results: The output of a
+            detectron2_results (Any): The output of a
                 Detectron2 model containing instances with prediction data.
 
         Returns:
@@ -782,7 +799,7 @@ class Detections:
 
     @classmethod
     def from_lmm(
-        cls, lmm: Union[LMM, str], result: Union[str, dict], **kwargs
+        cls, lmm: Union[LMM, str], result: Union[str, dict], **kwargs: Any
     ) -> Detections:
         """
         Creates a Detections object from the given result string based on the specified
@@ -791,7 +808,7 @@ class Detections:
         Args:
             lmm (Union[LMM, str]): The type of LMM (Large Multimodal Model) to use.
             result (str): The result string containing the detection data.
-            **kwargs: Additional keyword arguments required by the specified LMM.
+            **kwargs (Any): Additional keyword arguments required by the specified LMM.
 
         Returns:
             Detections: A new Detections object.
@@ -843,6 +860,110 @@ class Detections:
 
         raise ValueError(f"Unsupported LMM: {lmm}")
 
+    @classmethod
+    def from_easyocr(cls, easyocr_results: list) -> Detections:
+        """
+        Create a Detections object from the
+        [EasyOCR](https://github.com/JaidedAI/EasyOCR) result.
+
+        Results are placed in the `data` field with the key `"class_name"`.
+
+        Args:
+            easyocr_results (List): The output Results instance from EasyOCR
+
+        Returns:
+            Detections: A new Detections object.
+
+        Example:
+            ```python
+            import supervision as sv
+            import easyocr
+
+            reader = easyocr.Reader(['en'])
+            results = reader.readtext(<SOURCE_IMAGE_PATH>)
+            detections = sv.Detections.from_easyocr(results)
+            detected_text = detections["class_name"]
+            ```
+        """
+        if len(easyocr_results) == 0:
+            return cls.empty()
+
+        bbox = np.array([result[0] for result in easyocr_results])
+        xyxy = np.hstack((np.min(bbox, axis=1), np.max(bbox, axis=1)))
+        confidence = np.array(
+            [
+                result[2] if len(result) > 2 and result[2] else 0
+                for result in easyocr_results
+            ]
+        )
+        ocr_text = np.array([result[1] for result in easyocr_results])
+
+        return cls(
+            xyxy=xyxy.astype(np.float32),
+            confidence=confidence.astype(np.float32),
+            data={
+                CLASS_NAME_DATA_FIELD: ocr_text,
+            },
+        )
+
+    @classmethod
+    def from_ncnn(cls, ncnn_results) -> Detections:
+        """
+        Creates a Detections instance from the
+        [ncnn](https://github.com/Tencent/ncnn) inference result.
+        Supports object detection models.
+
+        Arguments:
+            ncnn_results (dict): The output Results instance from ncnn.
+
+        Returns:
+            Detections: A new Detections object.
+
+        Example:
+            ```python
+            import cv2
+            from ncnn.model_zoo import get_model
+            import supervision as sv
+
+            image = cv2.imread(<SOURCE_IMAGE_PATH>)
+            model = get_model(
+                "yolov8s",
+                target_size=640
+                prob_threshold=0.5,
+                nms_threshold=0.45,
+                num_threads=4,
+                use_gpu=True,
+                )
+            result = model(image)
+            detections = sv.Detections.from_ncnn(result)
+            ```
+        """
+
+        xywh, confidences, class_ids = [], [], []
+
+        if len(ncnn_results) == 0:
+            return cls.empty()
+
+        for ncnn_result in ncnn_results:
+            rect = ncnn_result.rect
+            xywh.append(
+                [
+                    rect.x.astype(np.float32),
+                    rect.y.astype(np.float32),
+                    rect.w.astype(np.float32),
+                    rect.h.astype(np.float32),
+                ]
+            )
+
+            confidences.append(ncnn_result.prob)
+            class_ids.append(ncnn_result.label)
+
+        return cls(
+            xyxy=xywh_to_xyxy(np.array(xywh, dtype=np.float32)),
+            confidence=np.array(confidences, dtype=np.float32),
+            class_id=np.array(class_ids, dtype=int),
+        )
+
     @classmethod
     def empty(cls) -> Detections:
         """
@@ -871,6 +992,7 @@ class Detections:
         """
         empty_detections = Detections.empty()
         empty_detections.data = self.data
+        empty_detections.metadata = self.metadata
         return self == empty_detections
 
     @classmethod
@@ -964,6 +1086,9 @@ class Detections:
 
         data = merge_data([d.data for d in detections_list])
 
+        metadata_list = [detections.metadata for detections in detections_list]
+        metadata = merge_metadata(metadata_list)
+
         return cls(
             xyxy=xyxy,
             mask=mask,
@@ -971,6 +1096,7 @@ class Detections:
             class_id=class_id,
             tracker_id=tracker_id,
             data=data,
+            metadata=metadata,
         )
 
     def get_anchors_coordinates(self, anchor: Position) -> np.ndarray:
@@ -1084,6 +1210,7 @@ class Detections:
             class_id=self.class_id[index] if self.class_id is not None else None,
             tracker_id=self.tracker_id[index] if self.tracker_id is not None else None,
             data=get_data_item(self.data, index),
+            metadata=self.metadata,
         )
 
     def __setitem__(self, key: str, value: Union[np.ndarray, List]):
@@ -1345,6 +1472,8 @@ def merge_inner_detection_object_pair(
     else:
         winning_detection = detections_2
 
+    metadata = merge_metadata([detections_1.metadata, detections_2.metadata])
+
     return Detections(
         xyxy=merged_xyxy,
         mask=merged_mask,
@@ -1352,6 +1481,7 @@ def merge_inner_detection_object_pair(
         class_id=winning_detection.class_id,
         tracker_id=winning_detection.tracker_id,
         data=winning_detection.data,
+        metadata=metadata,
     )
 
 

supervision/detection/line_zone.py

@@ -1,16 +1,24 @@
+import math
 import warnings
-from typing import Dict, Iterable, Optional, Tuple
+from collections import Counter, defaultdict, deque
+from functools import lru_cache
+from typing import Any, Deque, Dict, Iterable, List, Literal, Optional, Tuple
 
 import cv2
 import numpy as np
+import numpy.typing as npt
 
+from supervision.config import CLASS_NAME_DATA_FIELD
 from supervision.detection.core import Detections
 from supervision.detection.utils import cross_product
 from supervision.draw.color import Color
-from supervision.draw.utils import draw_text
-from supervision.geometry.core import Point, Position, Vector
+from supervision.draw.utils import draw_rectangle, draw_text
+from supervision.geometry.core import Point, Position, Rect, Vector
+from supervision.utils.image import overlay_image
 from supervision.utils.internal import SupervisionWarnings
 
+TEXT_MARGIN = 10
+
 
 class LineZone:
     """
@@ -34,6 +42,10 @@ class LineZone:
             to inside.
         out_count (int): The number of objects that have crossed the line from inside
             to outside.
+        in_count_per_class (Dict[int, int]): Number of objects of each class that have
+            crossed the line from outside to inside.
+        out_count_per_class (Dict[int, int]): Number of objects of each class that have
+            crossed the line from inside to outside.
 
     Example:
         ```python
@@ -55,7 +67,7 @@ class LineZone:
         line_zone.in_count, line_zone.out_count
         # 7, 2
         ```
-    """  # noqa: E501 // docs
+    """
 
     def __init__(
         self,
@@ -67,6 +79,7 @@ class LineZone:
             Position.BOTTOM_LEFT,
             Position.BOTTOM_RIGHT,
         ),
+        minimum_crossing_threshold: int = 1,
     ):
         """
         Args:
@@ -77,53 +90,40 @@ class LineZone:
                 to consider when deciding on whether the detection
                 has passed the line counter or not. By default, this
                 contains the four corners of the detection's bounding box
+            minimum_crossing_threshold (int): Detection needs to be seen
+                on the other side of the line for this many frames to be
+                considered as having crossed the line. This is useful when
+                dealing with unstable bounding boxes or when detections
+                may linger on the line.
         """
         self.vector = Vector(start=start, end=end)
-        self.limits = self.calculate_region_of_interest_limits(vector=self.vector)
-        self.tracker_state: Dict[str, bool] = {}
-        self.in_count: int = 0
-        self.out_count: int = 0
+        self.limits = self._calculate_region_of_interest_limits(vector=self.vector)
+        self.crossing_history_length = max(2, minimum_crossing_threshold + 1)
+        self.crossing_state_history: Dict[int, Deque[bool]] = defaultdict(
+            lambda: deque(maxlen=self.crossing_history_length)
+        )
+        self._in_count_per_class: Counter = Counter()
+        self._out_count_per_class: Counter = Counter()
         self.triggering_anchors = triggering_anchors
         if not list(self.triggering_anchors):
             raise ValueError("Triggering anchors cannot be empty.")
+        self.class_id_to_name: Dict[int, str] = {}
 
-    @staticmethod
-    def calculate_region_of_interest_limits(vector: Vector) -> Tuple[Vector, Vector]:
-        magnitude = vector.magnitude
+    @property
+    def in_count(self) -> int:
+        return sum(self._in_count_per_class.values())
 
-        if magnitude == 0:
-            raise ValueError("The magnitude of the vector cannot be zero.")
+    @property
+    def out_count(self) -> int:
+        return sum(self._out_count_per_class.values())
 
-        delta_x = vector.end.x - vector.start.x
-        delta_y = vector.end.y - vector.start.y
+    @property
+    def in_count_per_class(self) -> Dict[int, int]:
+        return dict(self._in_count_per_class)
 
-        unit_vector_x = delta_x / magnitude
-        unit_vector_y = delta_y / magnitude
-
-        perpendicular_vector_x = -unit_vector_y
-        perpendicular_vector_y = unit_vector_x
-
-        start_region_limit = Vector(
-            start=vector.start,
-            end=Point(
-                x=vector.start.x + perpendicular_vector_x,
-                y=vector.start.y + perpendicular_vector_y,
-            ),
-        )
-        end_region_limit = Vector(
-            start=vector.end,
-            end=Point(
-                x=vector.end.x - perpendicular_vector_x,
-                y=vector.end.y - perpendicular_vector_y,
-            ),
-        )
-        return start_region_limit, end_region_limit
-
-    @staticmethod
-    def is_point_in_limits(point: Point, limits: Tuple[Vector, Vector]) -> bool:
-        cross_product_1 = limits[0].cross_product(point)
-        cross_product_2 = limits[1].cross_product(point)
-        return (cross_product_1 > 0) == (cross_product_2 > 0)
+    @property
+    def out_count_per_class(self) -> Dict[int, int]:
+        return dict(self._out_count_per_class)
 
     def trigger(self, detections: Detections) -> Tuple[np.ndarray, np.ndarray]:
         """
@@ -154,6 +154,123 @@ class LineZone:
             )
             return crossed_in, crossed_out
 
+        self._update_class_id_to_name(detections)
+
+        in_limits, has_any_left_trigger, has_any_right_trigger = (
+            self._compute_anchor_sides(detections)
+        )
+
+        class_ids: List[Optional[int]] = (
+            list(detections.class_id)
+            if detections.class_id is not None
+            else [None] * len(detections)
+        )
+
+        for i, (class_id, tracker_id) in enumerate(
+            zip(class_ids, detections.tracker_id)
+        ):
+            if not in_limits[i]:
+                continue
+
+            if has_any_left_trigger[i] and has_any_right_trigger[i]:
+                continue
+
+            tracker_state: bool = has_any_left_trigger[i]
+            crossing_history = self.crossing_state_history[tracker_id]
+            crossing_history.append(tracker_state)
+
+            if len(crossing_history) < self.crossing_history_length:
+                continue
+
+            # TODO: Account for incorrect class_id.
+            #   Most likely this would involve indexing self.crossing_state_history
+            #   with (tracker_id, class_id).
+
+            oldest_state = crossing_history[0]
+            if crossing_history.count(oldest_state) > 1:
+                continue
+
+            if tracker_state:
+                self._in_count_per_class[class_id] += 1
+                crossed_in[i] = True
+            else:
+                self._out_count_per_class[class_id] += 1
+                crossed_out[i] = True
+
+        return crossed_in, crossed_out
+
+    @staticmethod
+    def _calculate_region_of_interest_limits(vector: Vector) -> Tuple[Vector, Vector]:
+        magnitude = vector.magnitude
+
+        if magnitude == 0:
+            raise ValueError("The magnitude of the vector cannot be zero.")
+
+        delta_x = vector.end.x - vector.start.x
+        delta_y = vector.end.y - vector.start.y
+
+        unit_vector_x = delta_x / magnitude
+        unit_vector_y = delta_y / magnitude
+
+        perpendicular_vector_x = -unit_vector_y
+        perpendicular_vector_y = unit_vector_x
+
+        start_region_limit = Vector(
+            start=vector.start,
+            end=Point(
+                x=vector.start.x + perpendicular_vector_x,
+                y=vector.start.y + perpendicular_vector_y,
+            ),
+        )
+        end_region_limit = Vector(
+            start=vector.end,
+            end=Point(
+                x=vector.end.x - perpendicular_vector_x,
+                y=vector.end.y - perpendicular_vector_y,
+            ),
+        )
+        return start_region_limit, end_region_limit
+
+    def _compute_anchor_sides(
+        self, detections: Detections
+    ) -> Tuple[npt.NDArray[np.bool_], npt.NDArray[np.bool_], npt.NDArray[np.bool_]]:
+        """
+        Find if detections' anchors are within the limit of the line
+        zone and which anchors are on its left and right side.
+
+        Assumes:
+            * At least 1 detection is provided
+            * Detections have `tracker_id`
+
+        The limit is defined as the region between the two lines,
+        perpendicular to the line zone, and passing through its start
+        and end points, as shown below:
+
+        Limits:
+        ```
+                |    IN    ↑
+                |          |
+          OUT   o---LINE---o   OUT
+                |          |
+                ↓    IN    |
+        ```
+
+        Args:
+            detections (Detections): The detections to check.
+
+        Returns:
+            result (Tuple[np.ndarray, np.ndarray, np.ndarray]):
+                All 3 arrays are boolean arrays of shape (N, ) where N is the
+                number of detections. The first array, `in_limits`, indicates
+                if the detection's anchor is within the line zone limits.
+                The second array, `has_any_left_trigger`, indicates if the
+                detection's anchor is on the left side of the line zone.
+                The third array, `has_any_right_trigger`, indicates if the
+                detection's anchor is on the right side of the line zone.
+        """
+        assert len(detections) > 0
+        assert detections.tracker_id is not None
+
         all_anchors = np.array(
             [
                 detections.get_anchors_coordinates(anchor)
@@ -163,45 +280,46 @@ class LineZone:
 
         cross_products_1 = cross_product(all_anchors, self.limits[0])
         cross_products_2 = cross_product(all_anchors, self.limits[1])
+
+        # Works because limit vectors are pointing in opposite directions
         in_limits = (cross_products_1 > 0) == (cross_products_2 > 0)
         in_limits = np.all(in_limits, axis=0)
 
         triggers = cross_product(all_anchors, self.vector) < 0
         has_any_left_trigger = np.any(triggers, axis=0)
         has_any_right_trigger = np.any(~triggers, axis=0)
-        is_uniformly_triggered = ~(has_any_left_trigger & has_any_right_trigger)
-        for i, tracker_id in enumerate(detections.tracker_id):
-            if not in_limits[i]:
-                continue
 
-            if not is_uniformly_triggered[i]:
-                continue
+        return in_limits, has_any_left_trigger, has_any_right_trigger
 
-            tracker_state = has_any_left_trigger[i]
-            if tracker_id not in self.tracker_state:
-                self.tracker_state[tracker_id] = tracker_state
-                continue
+    def _update_class_id_to_name(self, detections: Detections) -> None:
+        """
+        Update the attribute keeping track of which class
+        IDs correspond to which class names.
 
-            if self.tracker_state.get(tracker_id) == tracker_state:
-                continue
+        Assumes that class_names are only provided when class_ids are.
+        """
+        class_names = detections.data.get(CLASS_NAME_DATA_FIELD)
+        assert class_names is None or detections.class_id is not None
 
-            self.tracker_state[tracker_id] = tracker_state
-            if tracker_state:
-                self.in_count += 1
-                crossed_in[i] = True
-            else:
-                self.out_count += 1
-                crossed_out[i] = True
+        if detections.class_id is None:
+            return
 
-        return crossed_in, crossed_out
+        if class_names is None:
+            new_names = {class_id: str(class_id) for class_id in detections.class_id}
+        else:
+            new_names = {
+                class_id: class_name
+                for class_id, class_name in zip(detections.class_id, class_names)
+            }
+        self.class_id_to_name.update(new_names)
 
 
 class LineZoneAnnotator:
     def __init__(
         self,
-        thickness: float = 2,
+        thickness: int = 2,
         color: Color = Color.WHITE,
-        text_thickness: float = 2,
+        text_thickness: int = 2,
         text_color: Color = Color.BLACK,
         text_scale: float = 0.5,
         text_offset: float = 1.5,
@@ -210,86 +328,67 @@ class LineZoneAnnotator:
         custom_out_text: Optional[str] = None,
         display_in_count: bool = True,
         display_out_count: bool = True,
+        display_text_box: bool = True,
+        text_orient_to_line: bool = False,
+        text_centered: bool = True,
     ):
         """
-        Initialize the LineCounterAnnotator object with default values.
+        A class for drawing the `LineZone` and its detected object count
+        on an image.
 
         Attributes:
-            thickness (float): The thickness of the line that will be drawn.
-            color (Color): The color of the line that will be drawn.
-            text_thickness (float): The thickness of the text that will be drawn.
-            text_color (Color): The color of the text that will be drawn.
-            text_scale (float): The scale of the text that will be drawn.
-            text_offset (float): The offset of the text that will be drawn.
-            text_padding (int): The padding of the text that will be drawn.
-            display_in_count (bool): Whether to display the in count or not.
-            display_out_count (bool): Whether to display the out count or not.
+            thickness (int): Line thickness.
+            color (Color): Line color.
+            text_thickness (int): Text thickness.
+            text_color (Color): Text color.
+            text_scale (float): Text scale.
+            text_offset (float): How far the text will be from the line.
+            text_padding (int): The empty space in the text box, surrounding the text.
+            custom_in_text (Optional[str]): Write something else instead of "in".
+            custom_out_text (Optional[str]): Write something else instead of "out".
+            display_in_count (bool): Pass `False` to hide the "in" count.
+            display_out_count (bool): Pass `False` to hide the "out" count.
+            display_text_box (bool): Pass `False` to hide the text background box.
+            text_orient_to_line (bool): ⭐ Match text orientation to the line.
+                Recommended to set to `True`.
+            text_centered (bool): Pass `False` to disable text centering. Useful
+                when the label overlaps something important.
 
         """
-        self.thickness: float = thickness
+        self.thickness: int = thickness
         self.color: Color = color
-        self.text_thickness: float = text_thickness
+        self.text_thickness: int = text_thickness
         self.text_color: Color = text_color
         self.text_scale: float = text_scale
         self.text_offset: float = text_offset
         self.text_padding: int = text_padding
-        self.custom_in_text: str = custom_in_text
-        self.custom_out_text: str = custom_out_text
+        self.in_text: str = custom_in_text if custom_in_text else "in"
+        self.out_text: str = custom_out_text if custom_out_text else "out"
         self.display_in_count: bool = display_in_count
         self.display_out_count: bool = display_out_count
-
-    def _annotate_count(
-        self,
-        frame: np.ndarray,
-        center_text_anchor: Point,
-        text: str,
-        is_in_count: bool,
-    ) -> None:
-        """This method is drawing the text on the frame.
-
-        Args:
-            frame (np.ndarray): The image on which the text will be drawn.
-            center_text_anchor: The center point that the text will be drawn.
-            text (str): The text that will be drawn.
-            is_in_count (bool): Whether to display the in count or out count.
-        """
-        _, text_height = cv2.getTextSize(
-            text, cv2.FONT_HERSHEY_SIMPLEX, self.text_scale, self.text_thickness
-        )[0]
-
-        if is_in_count:
-            center_text_anchor.y -= int(self.text_offset * text_height)
-        else:
-            center_text_anchor.y += int(self.text_offset * text_height)
-
-        draw_text(
-            scene=frame,
-            text=text,
-            text_anchor=center_text_anchor,
-            text_color=self.text_color,
-            text_scale=self.text_scale,
-            text_thickness=self.text_thickness,
-            text_padding=self.text_padding,
-            background_color=self.color,
-        )
+        self.display_text_box: bool = display_text_box
+        self.text_orient_to_line: bool = text_orient_to_line
+        self.text_centered: bool = text_centered
 
     def annotate(self, frame: np.ndarray, line_counter: LineZone) -> np.ndarray:
         """
-        Draws the line on the frame using the line_counter provided.
+        Draws the line on the frame using the line zone provided.
 
         Attributes:
             frame (np.ndarray): The image on which the line will be drawn.
-            line_counter (LineCounter): The line counter
+            line_counter (LineZone): The line zone
                 that will be used to draw the line.
 
         Returns:
-            np.ndarray: The image with the line drawn on it.
+            (np.ndarray): The image with the line drawn on it.
 
         """
+        line_start = line_counter.vector.start.as_xy_int_tuple()
+        line_end = line_counter.vector.end.as_xy_int_tuple()
         cv2.line(
             frame,
-            line_counter.vector.start.as_xy_int_tuple(),
-            line_counter.vector.end.as_xy_int_tuple(),
+            line_start,
+            line_end,
             self.color.as_bgr(),
             self.thickness,
             lineType=cv2.LINE_AA,
@@ -297,7 +396,7 @@ class LineZoneAnnotator:
         )
         cv2.circle(
             frame,
-            line_counter.vector.start.as_xy_int_tuple(),
+            line_start,
             radius=5,
             color=self.text_color.as_bgr(),
             thickness=-1,
@@ -305,40 +404,456 @@ class LineZoneAnnotator:
         )
         cv2.circle(
             frame,
-            line_counter.vector.end.as_xy_int_tuple(),
+            line_end,
             radius=5,
             color=self.text_color.as_bgr(),
             thickness=-1,
             lineType=cv2.LINE_AA,
         )
 
-        text_anchor = Vector(
-            start=line_counter.vector.start, end=line_counter.vector.end
+        in_text = f"{self.in_text}: {line_counter.in_count}"
+        out_text = f"{self.out_text}: {line_counter.out_count}"
+        line_angle_degrees = self._get_line_angle(line_counter)
+
+        for text, is_shown, is_in_count in [
+            (in_text, self.display_in_count, True),
+            (out_text, self.display_out_count, False),
+        ]:
+            if not is_shown:
+                continue
+
+            if line_angle_degrees == 0 or not self.text_orient_to_line:
+                self._draw_basic_label(
+                    frame=frame,
+                    line_center=line_counter.vector.center,
+                    text=text,
+                    is_in_count=is_in_count,
+                )
+            else:
+                self._draw_oriented_label(
+                    frame=frame,
+                    line_zone=line_counter,
+                    text=text,
+                    is_in_count=is_in_count,
+                )
+
+        return frame
+
+    def _get_line_angle(self, line_zone: LineZone) -> float:
+        """
+        Calculate the line counter angle (in degrees).
+
+        Args:
+            line_zone (LineZone): The line zone object.
+
+        Returns:
+            (float): Line counter angle, in degrees.
+        """
+        start_point = line_zone.vector.start.as_xy_int_tuple()
+        end_point = line_zone.vector.end.as_xy_int_tuple()
+
+        delta_x = end_point[0] - start_point[0]
+        delta_y = end_point[1] - start_point[1]
+
+        if delta_x == 0:
+            line_angle = 90.0
+            line_angle += 180 if delta_y < 0 else 0
+        else:
+            line_angle = math.degrees(math.atan(delta_y / delta_x))
+            line_angle += 180 if delta_x < 0 else 0
+
+        return line_angle
+
+    def _calculate_anchor_in_frame(
+        self,
+        line_zone: LineZone,
+        text_width: int,
+        text_height: int,
+        is_in_count: bool,
+        label_dimension: int,
+    ) -> Tuple[int, int]:
+        """
+        Calculate insertion anchor in frame to position the center of the count image.
+
+        Args:
+            line_zone (LineZone): The line counter object used for counting.
+            text_width (int): Text width.
+            text_height (int): Text height.
+            is_in_count (bool): Whether the count should be placed over or below line.
+            label_dimension (int): Size of the label image. Assumes the
+                label is rectangular.
+
+        Returns:
+            (Tuple[int, int]): xy, point in an image where the label will be placed.
+        """
+        line_angle = self._get_line_angle(line_zone)
+
+        if self.text_centered:
+            mid_point = Vector(
+                start=line_zone.vector.start, end=line_zone.vector.end
+            ).center.as_xy_int_tuple()
+            anchor = list(mid_point)
+        else:
+            end_point = line_zone.vector.end.as_xy_int_tuple()
+            anchor = list(end_point)
+
+            move_along_x = int(
+                math.cos(math.radians(line_angle))
+                * (text_width / 2 + self.text_padding)
+            )
+            move_along_y = int(
+                math.sin(math.radians(line_angle))
+                * (text_width / 2 + self.text_padding)
+            )
+
+            anchor[0] -= move_along_x
+            anchor[1] -= move_along_y
+
+        move_perpendicular_x = int(
+            math.sin(math.radians(line_angle)) * (self.text_offset * text_height)
+        )
+        move_perpendicular_y = int(
+            math.cos(math.radians(line_angle)) * (self.text_offset * text_height)
         )
 
-        if self.display_in_count:
-            in_text = (
-                f"{self.custom_in_text}: {line_counter.in_count}"
-                if self.custom_in_text is not None
-                else f"in: {line_counter.in_count}"
-            )
-            self._annotate_count(
-                frame=frame,
-                center_text_anchor=text_anchor.center,
-                text=in_text,
-                is_in_count=True,
+        if is_in_count:
+            anchor[0] += move_perpendicular_x
+            anchor[1] -= move_perpendicular_y
+        else:
+            anchor[0] -= move_perpendicular_x
+            anchor[1] += move_perpendicular_y
+
+        x1 = max(anchor[0] - label_dimension // 2, 0)
+        y1 = max(anchor[1] - label_dimension // 2, 0)
+
+        return x1, y1
+
+    def _draw_basic_label(
+        self,
+        frame: np.ndarray,
+        line_center: Point,
+        text: str,
+        is_in_count: bool,
+    ) -> np.ndarray:
+        """
+        Draw the count label on the frame. For example: "out: 7".
+        The label contains horizontal text and is not rotated.
+
+        Args:
+            frame (np.ndarray): The entire scene, on which the label will be placed.
+            line_center (Point): The center of the line zone.
+            text (str): The text that will be drawn.
+            is_in_count (bool): Whether to display the in count (above line)
+                or out count (below line).
+
+        Returns:
+            (np.ndarray): The scene with the label drawn on it.
+        """
+        _, text_height = cv2.getTextSize(
+            text, cv2.FONT_HERSHEY_SIMPLEX, self.text_scale, self.text_thickness
+        )[0]
+
+        if is_in_count:
+            line_center.y -= int(self.text_offset * text_height)
+        else:
+            line_center.y += int(self.text_offset * text_height)
+
+        draw_text(
+            scene=frame,
+            text=text,
+            text_anchor=line_center,
+            text_color=self.text_color,
+            text_scale=self.text_scale,
+            text_thickness=self.text_thickness,
+            text_padding=self.text_padding,
+            background_color=self.color if self.display_text_box else None,
+        )
+
+        return frame
+
+    def _draw_oriented_label(
+        self,
+        frame: np.ndarray,
+        line_zone: LineZone,
+        text: str,
+        is_in_count: bool,
+    ) -> np.ndarray:
+        """
+        Draw the count label on the frame. For example: "out: 7".
+        The label is oriented to match the line angle.
+
+        Args:
+            frame (np.ndarray): The entire scene, on which the label will be placed.
+            line_zone (LineZone): The line zone responsible for counting
+                objects crossing it.
+            text (str): The text that will be drawn.
+            is_in_count (bool): Whether to display the in count (above line)
+                or out count (below line).
+
+        Returns:
+            (np.ndarray): The scene with the label drawn on it.
+        """
+
+        line_angle_degrees = self._get_line_angle(line_zone)
+        label_image = self._make_label_image(
+            text,
+            text_scale=self.text_scale,
+            text_thickness=self.text_thickness,
+            text_padding=self.text_padding,
+            text_color=self.text_color,
+            text_box_show=self.display_text_box,
+            text_box_color=self.color,
+            line_angle_degrees=line_angle_degrees,
+        )
+        assert label_image.shape[0] == label_image.shape[1]
+
+        text_width, text_height = cv2.getTextSize(
+            text, cv2.FONT_HERSHEY_SIMPLEX, self.text_scale, self.text_thickness
+        )[0]
+
+        label_anchor = self._calculate_anchor_in_frame(
+            line_zone=line_zone,
+            text_width=text_width,
+            text_height=text_height,
+            is_in_count=is_in_count,
+            label_dimension=label_image.shape[0],
+        )
+
+        frame = overlay_image(frame, label_image, label_anchor)
+
+        return frame
+
+    @staticmethod
+    @lru_cache(maxsize=32)
+    def _make_label_image(
+        text: str,
+        *,
+        text_scale: float,
+        text_thickness: int,
+        text_padding: int,
+        text_color: Color,
+        text_box_show: bool,
+        text_box_color: Color,
+        line_angle_degrees: float,
+    ) -> np.ndarray:
+        """
+        Create the small text box displaying line zone count. E.g. "out: 7".
+
+        Args:
+            text (str): The text to display.
+            text_scale (float): The scale of the text.
+            text_thickness (int): The thickness of the text.
+            text_padding (int): The padding around the text.
+            text_color (Color): The color of the text.
+            text_box_show (bool): Whether to display the text box.
+            text_box_color (Color): The color of the text box.
+            line_angle_degrees (float): The angle of the line in degrees.
+
+        Returns:
+            (np.ndarray): The label of shape (H, W, 4), in BGRA format.
+        """
+        text_width, text_height = cv2.getTextSize(
+            text, cv2.FONT_HERSHEY_SIMPLEX, text_scale, text_thickness
+        )[0]
+
+        annotation_dim = int((max(text_width, text_height) + text_padding * 2) * 1.5)
+        annotation_shape = (annotation_dim, annotation_dim)
+        annotation_center = Point(annotation_dim // 2, annotation_dim // 2)
+
+        annotation = np.zeros((*annotation_shape, 3), dtype=np.uint8)
+        annotation_alpha = np.zeros((*annotation_shape, 1), dtype=np.uint8)
+
+        text_args: Dict[str, Any] = dict(
+            text=text,
+            text_anchor=annotation_center,
+            text_scale=text_scale,
+            text_thickness=text_thickness,
+            text_padding=text_padding,
+        )
+        draw_text(
+            scene=annotation,
+            text_color=text_color,
+            background_color=text_box_color if text_box_show else None,
+            **text_args,
+        )
+        draw_text(
+            scene=annotation_alpha,
+            text_color=Color.WHITE,
+            background_color=Color.WHITE if text_box_show else None,
+            **text_args,
+        )
+        annotation = np.dstack((annotation, annotation_alpha))
+
+        # Make sure text is displayed upright
+        if 90 < line_angle_degrees % 360 < 270:
+            annotation = cv2.flip(annotation, flipCode=-1).astype(np.uint8)
+
+        rotation_angle = -line_angle_degrees
+        rotation_matrix = cv2.getRotationMatrix2D(
+            annotation_center.as_xy_float_tuple(), rotation_angle, scale=1
+        )
+        annotation = cv2.warpAffine(annotation, rotation_matrix, annotation_shape)
+
+        return annotation
+
+
+class LineZoneAnnotatorMulticlass:
+    def __init__(
+        self,
+        *,
+        table_position: Literal[
+            Position.TOP_LEFT,
+            Position.TOP_RIGHT,
+            Position.BOTTOM_LEFT,
+            Position.BOTTOM_RIGHT,
+        ] = Position.TOP_RIGHT,
+        table_color: Color = Color.WHITE,
+        table_margin: int = 10,
+        table_padding: int = 10,
+        table_max_width: int = 400,
+        text_color: Color = Color.BLACK,
+        text_scale: float = 0.75,
+        text_thickness: int = 1,
+        force_draw_class_ids: bool = False,
+    ):
+        """
+        Draw a table showing how many items of each class crossed each line.
+
+        Args:
+            table_position (Position): The position of the table.
+            table_color (Color): The color of the table.
+            table_margin (int): The margin of the table from the image border.
+            table_padding (int): The padding of the table.
+            table_max_width (int): The maximum width of the table.
+            text_color (Color): The color of the text.
+            text_scale (float): The scale of the text.
+            text_thickness (int): The thickness of the text.
+            force_draw_class_ids (bool): Instead of writing the class names,
+                on the table, write the class IDs. E.g. instead of `person: 6`,
+                write `0: 6`.
+        """
+        if table_position not in {
+            Position.TOP_LEFT,
+            Position.TOP_RIGHT,
+            Position.BOTTOM_LEFT,
+            Position.BOTTOM_RIGHT,
+        }:
+            raise ValueError(
+                "Invalid table position. Supported values are:"
+                " TOP_LEFT, TOP_RIGHT, BOTTOM_LEFT, BOTTOM_RIGHT."
             )
 
-        if self.display_out_count:
-            out_text = (
-                f"{self.custom_out_text}: {line_counter.out_count}"
-                if self.custom_out_text is not None
-                else f"out: {line_counter.out_count}"
-            )
-            self._annotate_count(
-                frame=frame,
-                center_text_anchor=text_anchor.center,
-                text=out_text,
-                is_in_count=False,
+        self.table_position = table_position
+        self.table_color = table_color
+        self.table_margin = table_margin
+        self.table_padding = table_padding
+        self.table_max_width = table_max_width
+        self.text_color = text_color
+        self.text_scale = text_scale
+        self.text_thickness = text_thickness
+        self.force_draw_class_ids = force_draw_class_ids
+
+    def annotate(
+        self,
+        frame: np.ndarray,
+        line_zones: List[LineZone],
+        line_zone_labels: Optional[List[str]] = None,
+    ) -> np.ndarray:
+        """
+        Draws a table with the number of objects of each class that crossed each line.
+
+        Attributes:
+            frame (np.ndarray): The image on which the table will be drawn.
+            line_zones (List[LineZone]): The line zones to be annotated.
+            line_zone_labels (Optional[List[str]]): The labels, one for each
+                line zone. If not provided, the default labels will be used.
+
+        Returns:
+            (np.ndarray): The image with the table drawn on it.
+
+        """
+        if line_zone_labels is None:
+            line_zone_labels = [f"Line {i + 1}:" for i in range(len(line_zones))]
+        if len(line_zones) != len(line_zone_labels):
+            raise ValueError("The number of line zones and their labels must match.")
+
+        text_lines = ["Line Crossings:"]
+        for line_zone, line_zone_label in zip(line_zones, line_zone_labels):
+            text_lines.append(line_zone_label)
+            class_id_to_name = line_zone.class_id_to_name
+
+            for direction, count_per_class in [
+                ("In", line_zone.in_count_per_class),
+                ("Out", line_zone.out_count_per_class),
+            ]:
+                if not count_per_class:
+                    continue
+
+                text_lines.append(f" {direction}:")
+                for class_id, count in count_per_class.items():
+                    class_name = (
+                        class_id_to_name.get(class_id, str(class_id))
+                        if not self.force_draw_class_ids
+                        else str(class_id)
+                    )
+                    text_lines.append(f"  {class_name}: {count}")
+
+        table_width, table_height = 0, 0
+        for line in text_lines:
+            text_width, text_height = cv2.getTextSize(
+                line, cv2.FONT_HERSHEY_SIMPLEX, self.text_scale, self.text_thickness
+            )[0]
+            text_height += TEXT_MARGIN
+            table_width = max(table_width, text_width)
+            table_height += text_height
+
+        table_width += 2 * self.table_padding
+        table_height += 2 * self.table_padding
+        table_max_height = frame.shape[0] - 2 * self.table_margin
+        table_height = min(table_height, table_max_height)
+        table_width = min(table_width, self.table_max_width)
+
+        position_map = {
+            Position.TOP_LEFT: (self.table_margin, self.table_margin),
+            Position.TOP_RIGHT: (
+                frame.shape[1] - table_width - self.table_margin,
+                self.table_margin,
+            ),
+            Position.BOTTOM_LEFT: (
+                self.table_margin,
+                frame.shape[0] - table_height - self.table_margin,
+            ),
+            Position.BOTTOM_RIGHT: (
+                frame.shape[1] - table_width - self.table_margin,
+                frame.shape[0] - table_height - self.table_margin,
+            ),
+        }
+        table_x1, table_y1 = position_map[self.table_position]
+
+        table_rect = Rect(
+            x=table_x1, y=table_y1, width=table_width, height=table_height
+        )
+        frame = draw_rectangle(
+            scene=frame, rect=table_rect, color=self.table_color, thickness=-1
+        )
+
+        for i, line in enumerate(text_lines):
+            _, text_height = cv2.getTextSize(
+                line, cv2.FONT_HERSHEY_SIMPLEX, self.text_scale, self.text_thickness
+            )[0]
+            text_height += TEXT_MARGIN
+            anchor_x = table_x1 + self.table_padding
+            anchor_y = table_y1 + self.table_padding + (i + 1) * text_height
+
+            cv2.putText(
+                img=frame,
+                text=line,
+                org=(anchor_x, anchor_y),
+                fontFace=cv2.FONT_HERSHEY_SIMPLEX,
+                fontScale=self.text_scale,
+                color=self.text_color.as_bgr(),
+                thickness=self.text_thickness,
+                lineType=cv2.LINE_AA,
             )
+
         return frame

supervision/detection/lmm.py

@@ -113,7 +113,7 @@ def from_florence_2(
             oriented bounding boxes.
     """
     assert len(result) == 1, f"Expected result with a single element. Got: {result}"
-    task = list(result.keys())[0]
+    task = next(iter(result.keys()))
     if task not in SUPPORTED_TASKS_FLORENCE_2:
         raise ValueError(
             f"{task} not supported. Supported tasks are: {SUPPORTED_TASKS_FLORENCE_2}"

supervision/detection/overlap_filter.py

@@ -66,7 +66,7 @@ def mask_non_max_suppression(
 
     Raises:
         AssertionError: If `iou_threshold` is not within the closed
-        range from `0` to `1`.
+            range from `0` to `1`.
     """
     assert 0 <= iou_threshold <= 1, (
         "Value of `iou_threshold` must be in the closed range from 0 to 1, "
@@ -183,7 +183,7 @@ def group_overlapping_boxes(
         ious = ious.flatten()
 
         above_threshold = ious >= iou_threshold
-        merge_group = [idx] + np.flip(order[above_threshold]).tolist()
+        merge_group = [idx, *np.flip(order[above_threshold]).tolist()]
         merge_groups.append(merge_group)
         order = order[~above_threshold]
     return merge_groups

supervision/detection/tools/csv_sink.py

@@ -48,7 +48,7 @@ class CSVSink:
                 detections = sv.Detections.from_ultralytics(result)
                 sink.append(detections, custom_data={'<CUSTOM_LABEL>':'<CUSTOM_DATA>'})
         ```
-    """  # noqa: E501 // docs
+    """
 
     def __init__(self, file_name: str = "output.csv") -> None:
         """
@@ -104,7 +104,7 @@ class CSVSink:
 
     @staticmethod
     def parse_detection_data(
-        detections: Detections, custom_data: Dict[str, Any] = None
+        detections: Detections, custom_data: Optional[Dict[str, Any]] = None
     ) -> List[Dict[str, Any]]:
         parsed_rows = []
         for i in range(len(detections.xyxy)):
@@ -137,7 +137,7 @@ class CSVSink:
         return parsed_rows
 
     def append(
-        self, detections: Detections, custom_data: Dict[str, Any] = None
+        self, detections: Detections, custom_data: Optional[Dict[str, Any]] = None
     ) -> None:
         """
         Append detection data to the CSV file.

supervision/detection/tools/inference_slicer.py

@@ -11,7 +11,6 @@ from supervision.detection.utils import move_boxes, move_masks, move_oriented_bo
 from supervision.utils.image import crop_image
 from supervision.utils.internal import (
     SupervisionWarnings,
-    deprecated_parameter,
     warn_deprecated,
 )
 
@@ -60,13 +59,15 @@ class InferenceSlicer:
     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]]): A tuple representing the
+        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.
+            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
@@ -82,14 +83,6 @@ class InferenceSlicer:
         not a multiple of the slice's width or height minus the overlap.
     """
 
-    @deprecated_parameter(
-        old_parameter="overlap_filter_strategy",
-        new_parameter="overlap_filter",
-        map_function=lambda x: x,
-        warning_message="`{old_parameter}` in `{function_name}` is deprecated and will "
-        "be removed in `supervision-0.27.0`. Use '{new_parameter}' "
-        "instead.",
-    )
     def __init__(
         self,
         callback: Callable[[np.ndarray], Detections],
@@ -103,7 +96,8 @@ class InferenceSlicer:
         if overlap_ratio_wh is not None:
             warn_deprecated(
                 "`overlap_ratio_wh` in `InferenceSlicer.__init__` is deprecated and "
-                "will be removed in `supervision-0.27.0`. Use `overlap_wh` instead."
+                "will be removed in `supervision-0.27.0`. Please manually set it to "
+                "`None` and use `overlap_wh` instead."
             )
 
         self._validate_overlap(overlap_ratio_wh, overlap_wh)

supervision/detection/tools/json_sink.py

@@ -38,7 +38,7 @@ class JSONSink:
                 detections = sv.Detections.from_ultralytics(result)
                 sink.append(detections, custom_data={'<CUSTOM_LABEL>':'<CUSTOM_DATA>'})
         ```
-    """  # noqa: E501 // docs
+    """
 
     def __init__(self, file_name: str = "output.json") -> None:
         """
@@ -92,7 +92,7 @@ class JSONSink:
 
     @staticmethod
     def parse_detection_data(
-        detections: Detections, custom_data: Dict[str, Any] = None
+        detections: Detections, custom_data: Optional[Dict[str, Any]] = None
     ) -> List[Dict[str, Any]]:
         parsed_rows = []
         for i in range(len(detections.xyxy)):
@@ -126,7 +126,7 @@ class JSONSink:
         return parsed_rows
 
     def append(
-        self, detections: Detections, custom_data: Dict[str, Any] = None
+        self, detections: Detections, custom_data: Optional[Dict[str, Any]] = None
     ) -> None:
         """
         Append detection data to the JSON file.

supervision/detection/tools/polygon_zone.py

@@ -1,6 +1,5 @@
-import warnings
 from dataclasses import replace
-from typing import Iterable, Optional, Tuple
+from typing import Iterable, Optional
 
 import cv2
 import numpy as np
@@ -9,16 +8,21 @@ import numpy.typing as npt
 from supervision import Detections
 from supervision.detection.utils import clip_boxes, polygon_to_mask
 from supervision.draw.color import Color
-from supervision.draw.utils import draw_polygon, draw_text
+from supervision.draw.utils import draw_filled_polygon, draw_polygon, draw_text
 from supervision.geometry.core import Position
 from supervision.geometry.utils import get_polygon_center
-from supervision.utils.internal import SupervisionWarnings
 
 
 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.
@@ -28,22 +32,35 @@ class 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 supervision 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],
-        frame_resolution_wh: Optional[Tuple[int, int]] = None,
         triggering_anchors: Iterable[Position] = (Position.BOTTOM_CENTER,),
     ):
-        if frame_resolution_wh is not None:
-            warnings.warn(
-                "The `frame_resolution_wh` parameter is no longer required and will be "
-                "dropped in version supervision-0.24.0. The mask resolution is now "
-                "calculated automatically based on the polygon coordinates.",
-                category=SupervisionWarnings,
-            )
-
         self.polygon = polygon.astype(int)
         self.triggering_anchors = triggering_anchors
         if not list(self.triggering_anchors):
@@ -99,7 +116,7 @@ class PolygonZoneAnnotator:
 
     Attributes:
         zone (PolygonZone): The polygon zone to be annotated
-        color (Color): The color to draw the polygon lines
+        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
@@ -109,18 +126,20 @@ class PolygonZoneAnnotator:
             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: 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
@@ -132,6 +151,7 @@ class PolygonZoneAnnotator:
         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:
         """
@@ -145,12 +165,26 @@ class PolygonZoneAnnotator:
         Returns:
             np.ndarray: The image with the polygon zone and count of detected objects
         """
-        annotated_frame = draw_polygon(
-            scene=scene,
-            polygon=self.zone.polygon,
-            color=self.color,
-            thickness=self.thickness,
-        )
+        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(

supervision/detection/tools/smoother.py

@@ -53,7 +53,7 @@ class DetectionsSmoother:
                 annotated_frame = box_annotator.annotate(frame.copy(), detections)
                 sink.write_frame(annotated_frame)
         ```
-    """  # noqa: E501 // docs
+    """
 
     def __init__(self, length: int = 5) -> None:
         """

supervision/detection/utils.py

@@ -1,5 +1,5 @@
 from itertools import chain
-from typing import Dict, List, Optional, Tuple, Union
+from typing import Any, Dict, List, Optional, Tuple, Union
 
 import cv2
 import numpy as np
@@ -23,10 +23,9 @@ def polygon_to_mask(polygon: np.ndarray, resolution_wh: Tuple[int, int]) -> np.n
         np.ndarray: The generated 2D mask, where the polygon is marked with
             `1`'s and the rest is filled with `0`'s.
     """
-    width, height = resolution_wh
-    mask = np.zeros((height, width))
-
-    cv2.fillPoly(mask, [polygon], color=1)
+    width, height = map(int, resolution_wh)
+    mask = np.zeros((height, width), dtype=np.uint8)
+    cv2.fillPoly(mask, [polygon.astype(np.int32)], color=1)
     return mask
 
 
@@ -140,6 +139,45 @@ def mask_iou_batch(
     return np.vstack(ious)
 
 
+def oriented_box_iou_batch(
+    boxes_true: np.ndarray, boxes_detection: np.ndarray
+) -> np.ndarray:
+    """
+    Compute Intersection over Union (IoU) of two sets of oriented bounding boxes -
+    `boxes_true` and `boxes_detection`. Both sets of boxes are expected to be in
+    `((x1, y1), (x2, y2), (x3, y3), (x4, y4))` format.
+
+    Args:
+        boxes_true (np.ndarray): a `np.ndarray` representing ground-truth boxes.
+            `shape = (N, 4, 2)` where `N` is number of true objects.
+        boxes_detection (np.ndarray): a `np.ndarray` representing detection boxes.
+            `shape = (M, 4, 2)` where `M` is number of detected objects.
+
+    Returns:
+        np.ndarray: Pairwise IoU of boxes from `boxes_true` and `boxes_detection`.
+            `shape = (N, M)` where `N` is number of true objects and
+            `M` is number of detected objects.
+    """
+
+    boxes_true = boxes_true.reshape(-1, 4, 2)
+    boxes_detection = boxes_detection.reshape(-1, 4, 2)
+
+    max_height = int(max(boxes_true[:, :, 0].max(), boxes_detection[:, :, 0].max()) + 1)
+    # adding 1 because we are 0-indexed
+    max_width = int(max(boxes_true[:, :, 1].max(), boxes_detection[:, :, 1].max()) + 1)
+
+    mask_true = np.zeros((boxes_true.shape[0], max_height, max_width))
+    for i, box_true in enumerate(boxes_true):
+        mask_true[i] = polygon_to_mask(box_true, (max_width, max_height))
+
+    mask_detection = np.zeros((boxes_detection.shape[0], max_height, max_width))
+    for i, box_detection in enumerate(boxes_detection):
+        mask_detection[i] = polygon_to_mask(box_detection, (max_width, max_height))
+
+    ious = mask_iou_batch(mask_true, mask_detection)
+    return ious
+
+
 def clip_boxes(xyxy: np.ndarray, resolution_wh: Tuple[int, int]) -> np.ndarray:
     """
     Clips bounding boxes coordinates to fit within the frame resolution.
@@ -147,7 +185,7 @@ def clip_boxes(xyxy: np.ndarray, resolution_wh: Tuple[int, int]) -> np.ndarray:
     Args:
         xyxy (np.ndarray): A numpy array of shape `(N, 4)` where each
             row corresponds to a bounding box in
-        the format `(x_min, y_min, x_max, y_max)`.
+            the format `(x_min, y_min, x_max, y_max)`.
         resolution_wh (Tuple[int, int]): A tuple of the form `(width, height)`
             representing the resolution of the frame.
 
@@ -769,12 +807,36 @@ def is_data_equal(data_a: Dict[str, np.ndarray], data_b: Dict[str, np.ndarray])
     )
 
 
+def is_metadata_equal(metadata_a: Dict[str, Any], metadata_b: Dict[str, Any]) -> bool:
+    """
+    Compares the metadata payloads of two Detections instances.
+
+    Args:
+        metadata_a, metadata_b: The metadata payloads of the instances.
+
+    Returns:
+        True if the metadata payloads are equal, False otherwise.
+    """
+    return set(metadata_a.keys()) == set(metadata_b.keys()) and all(
+        np.array_equal(metadata_a[key], metadata_b[key])
+        if (
+            isinstance(metadata_a[key], np.ndarray)
+            and isinstance(metadata_b[key], np.ndarray)
+        )
+        else metadata_a[key] == metadata_b[key]
+        for key in metadata_a
+    )
+
+
 def merge_data(
     data_list: List[Dict[str, Union[npt.NDArray[np.generic], List]]],
 ) -> Dict[str, Union[npt.NDArray[np.generic], List]]:
     """
     Merges the data payloads of a list of Detections instances.
 
+    Warning: Assumes that empty detections were filtered-out before passing data to
+    this function.
+
     Args:
         data_list: The data payloads of the Detections instances. Each data payload
             is a dictionary with the same keys, and the values are either lists or
@@ -827,6 +889,61 @@ def merge_data(
     return merged_data
 
 
+def merge_metadata(metadata_list: List[Dict[str, Any]]) -> Dict[str, Any]:
+    """
+    Merge metadata from a list of metadata dictionaries.
+
+    This function combines the metadata dictionaries. If a key appears in more than one
+    dictionary, the values must be identical for the merge to succeed.
+
+    Warning: Assumes that empty detections were filtered-out before passing metadata to
+    this function.
+
+    Args:
+        metadata_list (List[Dict[str, Any]]): A list of metadata dictionaries to merge.
+
+    Returns:
+        Dict[str, Any]: A single merged metadata dictionary.
+
+    Raises:
+        ValueError: If there are conflicting values for the same key or if
+        dictionaries have different keys.
+    """
+    if not metadata_list:
+        return {}
+
+    all_keys_sets = [set(metadata.keys()) for metadata in metadata_list]
+    if not all(keys_set == all_keys_sets[0] for keys_set in all_keys_sets):
+        raise ValueError("All metadata dictionaries must have the same keys to merge.")
+
+    merged_metadata: Dict[str, Any] = {}
+    for metadata in metadata_list:
+        for key, value in metadata.items():
+            if key not in merged_metadata:
+                merged_metadata[key] = value
+                continue
+
+            other_value = merged_metadata[key]
+            if isinstance(value, np.ndarray) and isinstance(other_value, np.ndarray):
+                if not np.array_equal(merged_metadata[key], value):
+                    raise ValueError(
+                        f"Conflicting metadata for key: '{key}': "
+                        "{type(value)}, {type(other_value)}."
+                    )
+            elif isinstance(value, np.ndarray) or isinstance(other_value, np.ndarray):
+                # Since [] == np.array([]).
+                raise ValueError(
+                    f"Conflicting metadata for key: '{key}': "
+                    "{type(value)}, {type(other_value)}."
+                )
+            else:
+                print("hm")
+                if merged_metadata[key] != value:
+                    raise ValueError(f"Conflicting metadata for key: '{key}'.")
+
+    return merged_metadata
+
+
 def get_data_item(
     data: Dict[str, Union[np.ndarray, List]],
     index: Union[int, slice, List[int], np.ndarray],
@@ -1000,3 +1117,59 @@ def cross_product(anchors: np.ndarray, vector: Vector) -> np.ndarray:
     )
     vector_start = np.array([vector.start.x, vector.start.y])
     return np.cross(vector_at_zero, anchors - vector_start)
+
+
+def spread_out_boxes(
+    xyxy: np.ndarray,
+    max_iterations: int = 100,
+) -> np.ndarray:
+    """
+    Spread out boxes that overlap with each other.
+
+    Args:
+        xyxy: Numpy array of shape (N, 4) where N is the number of boxes.
+        max_iterations: Maximum number of iterations to run the algorithm for.
+    """
+    if len(xyxy) == 0:
+        return xyxy
+
+    xyxy_padded = pad_boxes(xyxy, px=1)
+    for _ in range(max_iterations):
+        # NxN
+        iou = box_iou_batch(xyxy_padded, xyxy_padded)
+        np.fill_diagonal(iou, 0)
+        if np.all(iou == 0):
+            break
+
+        overlap_mask = iou > 0
+
+        # Nx2
+        centers = (xyxy_padded[:, :2] + xyxy_padded[:, 2:]) / 2
+
+        # NxNx2
+        delta_centers = centers[:, np.newaxis, :] - centers[np.newaxis, :, :]
+        delta_centers *= overlap_mask[:, :, np.newaxis]
+
+        # Nx2
+        delta_sum = np.sum(delta_centers, axis=1)
+        delta_magnitude = np.linalg.norm(delta_sum, axis=1, keepdims=True)
+        direction_vectors = np.divide(
+            delta_sum,
+            delta_magnitude,
+            out=np.zeros_like(delta_sum),
+            where=delta_magnitude != 0,
+        )
+
+        force_vectors = np.sum(iou, axis=1)
+        force_vectors = force_vectors[:, np.newaxis] * direction_vectors
+
+        force_vectors *= 10
+        force_vectors[(force_vectors > 0) & (force_vectors < 2)] = 2
+        force_vectors[(force_vectors < 0) & (force_vectors > -2)] = -2
+
+        force_vectors = force_vectors.astype(int)
+
+        xyxy_padded[:, [0, 1]] += force_vectors
+        xyxy_padded[:, [2, 3]] += force_vectors
+
+    return pad_boxes(xyxy_padded, px=-1)

supervision/draw/color.py

@@ -255,6 +255,17 @@ class Color:
     def ROBOFLOW(cls) -> Color:
         return Color.from_hex("#A351FB")
 
+    def __hash__(self):
+        return hash((self.r, self.g, self.b))
+
+    def __eq__(self, other):
+        return (
+            isinstance(other, Color)
+            and self.r == other.r
+            and self.g == other.g
+            and self.b == other.b
+        )
+
 
 @dataclass
 class ColorPalette:
@@ -386,6 +397,15 @@ class ColorPalette:
         idx = idx % len(self.colors)
         return self.colors[idx]
 
+    def __len__(self) -> int:
+        """
+        Returns the number of colors in the palette.
+
+        Returns:
+            int: The number of colors.
+        """
+        return len(self.colors)
+
 
 def unify_to_bgr(color: Union[Tuple[int, int, int], Color]) -> Tuple[int, int, int]:
     """

supervision/draw/utils.py

@@ -9,7 +9,11 @@ from supervision.geometry.core import Point, Rect
 
 
 def draw_line(
-    scene: np.ndarray, start: Point, end: Point, color: Color, thickness: int = 2
+    scene: np.ndarray,
+    start: Point,
+    end: Point,
+    color: Color = Color.ROBOFLOW,
+    thickness: int = 2,
 ) -> np.ndarray:
     """
     Draws a line on a given scene.
@@ -18,7 +22,7 @@ def draw_line(
         scene (np.ndarray): The scene on which the line will be drawn
         start (Point): The starting point of the line
         end (Point): The end point of the line
-        color (Color): The color of the line
+        color (Color): The color of the line, defaults to Color.ROBOFLOW
         thickness (int): The thickness of the line
 
     Returns:
@@ -35,7 +39,7 @@ def draw_line(
 
 
 def draw_rectangle(
-    scene: np.ndarray, rect: Rect, color: Color, thickness: int = 2
+    scene: np.ndarray, rect: Rect, color: Color = Color.ROBOFLOW, thickness: int = 2
 ) -> np.ndarray:
     """
     Draws a rectangle on an image.
@@ -59,7 +63,9 @@ def draw_rectangle(
     return scene
 
 
-def draw_filled_rectangle(scene: np.ndarray, rect: Rect, color: Color) -> np.ndarray:
+def draw_filled_rectangle(
+    scene: np.ndarray, rect: Rect, color: Color = Color.ROBOFLOW, opacity: float = 1
+) -> np.ndarray:
     """
     Draws a filled rectangle on an image.
 
@@ -67,17 +73,32 @@ def draw_filled_rectangle(scene: np.ndarray, rect: Rect, color: Color) -> np.nda
         scene (np.ndarray): The scene on which the rectangle will be drawn
         rect (Rect): The rectangle to be drawn
         color (Color): The color of the rectangle
+        opacity (float): The opacity of rectangle when drawn on the scene.
 
     Returns:
         np.ndarray: The scene with the rectangle drawn on it
     """
-    cv2.rectangle(
-        scene,
-        rect.top_left.as_xy_int_tuple(),
-        rect.bottom_right.as_xy_int_tuple(),
-        color.as_bgr(),
-        -1,
-    )
+    if opacity == 1:
+        cv2.rectangle(
+            scene,
+            rect.top_left.as_xy_int_tuple(),
+            rect.bottom_right.as_xy_int_tuple(),
+            color.as_bgr(),
+            -1,
+        )
+    else:
+        scene_with_annotations = scene.copy()
+        cv2.rectangle(
+            scene_with_annotations,
+            rect.top_left.as_xy_int_tuple(),
+            rect.bottom_right.as_xy_int_tuple(),
+            color.as_bgr(),
+            -1,
+        )
+        cv2.addWeighted(
+            scene_with_annotations, opacity, scene, 1 - opacity, gamma=0, dst=scene
+        )
+
     return scene
 
 
@@ -134,14 +155,17 @@ def draw_rounded_rectangle(
 
 
 def draw_polygon(
-    scene: np.ndarray, polygon: np.ndarray, color: Color, thickness: int = 2
+    scene: np.ndarray,
+    polygon: np.ndarray,
+    color: Color = Color.ROBOFLOW,
+    thickness: int = 2,
 ) -> np.ndarray:
     """Draw a polygon on a scene.
 
     Parameters:
         scene (np.ndarray): The scene to draw the polygon on.
         polygon (np.ndarray): The polygon to be drawn, given as a list of vertices.
-        color (Color): The color of the polygon.
+        color (Color): The color of the polygon. Defaults to Color.ROBOFLOW.
         thickness (int): The thickness of the polygon lines, by default 2.
 
     Returns:
@@ -153,6 +177,35 @@ def draw_polygon(
     return scene
 
 
+def draw_filled_polygon(
+    scene: np.ndarray,
+    polygon: np.ndarray,
+    color: Color = Color.ROBOFLOW,
+    opacity: float = 1,
+) -> np.ndarray:
+    """Draw a filled polygon on a scene.
+
+    Parameters:
+        scene (np.ndarray): The scene to draw the polygon on.
+        polygon (np.ndarray): The polygon to be drawn, given as a list of vertices.
+        color (Color): The color of the polygon. Defaults to Color.ROBOFLOW.
+        opacity (float): The opacity of polygon when drawn on the scene.
+
+    Returns:
+        np.ndarray: The scene with the polygon drawn on it.
+    """
+    if opacity == 1:
+        cv2.fillPoly(scene, [polygon], color=color.as_bgr())
+    else:
+        scene_with_annotations = scene.copy()
+        cv2.fillPoly(scene_with_annotations, [polygon], color=color.as_bgr())
+        cv2.addWeighted(
+            scene_with_annotations, opacity, scene, 1 - opacity, gamma=0, dst=scene
+        )
+
+    return scene
+
+
 def draw_text(
     scene: np.ndarray,
     text: str,

supervision/geometry/utils.py

@@ -16,6 +16,9 @@ def get_polygon_center(polygon: np.ndarray) -> Point:
         Point: The center of the polygon, represented as a
             Point object with x and y attributes.
 
+    Raises:
+        ValueError: If the polygon has no vertices.
+
     Examples:
         ```python
         import numpy as np
@@ -30,6 +33,9 @@ def get_polygon_center(polygon: np.ndarray) -> Point:
     # This is one of the 3 candidate algorithms considered for centroid calculation.
     # For a more detailed discussion, see PR #1084 and commit eb33176
 
+    if len(polygon) == 0:
+        raise ValueError("Polygon must have at least one vertex.")
+
     shift_polygon = np.roll(polygon, -1, axis=0)
     signed_areas = np.cross(polygon, shift_polygon) / 2
     if signed_areas.sum() == 0:

supervision/keypoint/annotators.py

@@ -5,10 +5,11 @@ from typing import List, Optional, Tuple, Union
 import cv2
 import numpy as np
 
-from supervision import Rect, pad_boxes
 from supervision.annotators.base import ImageType
+from supervision.detection.utils import pad_boxes, spread_out_boxes
 from supervision.draw.color import Color
 from supervision.draw.utils import draw_rounded_rectangle
+from supervision.geometry.core import Rect
 from supervision.keypoint.core import KeyPoints
 from supervision.keypoint.skeletons import SKELETONS_BY_VERTEX_COUNT
 from supervision.utils.conversion import ensure_cv2_image_for_annotation
@@ -201,6 +202,7 @@ class VertexLabelAnnotator:
         text_thickness: int = 1,
         text_padding: int = 10,
         border_radius: int = 0,
+        smart_position: bool = False,
     ):
         """
         Args:
@@ -215,6 +217,7 @@ class VertexLabelAnnotator:
             text_padding (int): The padding around the text.
             border_radius (int): The radius of the rounded corners of the
                 boxes. Set to a high value to produce circles.
+            smart_position (bool): Spread out the labels to avoid overlap.
         """
         self.border_radius: int = border_radius
         self.color: Union[Color, List[Color]] = color
@@ -222,6 +225,7 @@ class VertexLabelAnnotator:
         self.text_scale: float = text_scale
         self.text_thickness: int = text_thickness
         self.text_padding: int = text_padding
+        self.smart_position = smart_position
 
     def annotate(
         self,
@@ -356,9 +360,12 @@ class VertexLabelAnnotator:
                 for anchor, label in zip(anchors, labels)
             ]
         )
-
         xyxy_padded = pad_boxes(xyxy=xyxy, px=self.text_padding)
 
+        if self.smart_position:
+            xyxy_padded = spread_out_boxes(xyxy_padded)
+            xyxy = pad_boxes(xyxy=xyxy_padded, px=-self.text_padding)
+
         for text, color, text_color, box, box_padded in zip(
             labels, colors, text_colors, xyxy, xyxy_padded
         ):

supervision/keypoint/core.py

@@ -2,12 +2,13 @@ from __future__ import annotations
 
 from contextlib import suppress
 from dataclasses import dataclass, field
-from typing import Any, Dict, Iterator, List, Optional, Tuple, Union
+from typing import Any, Dict, Iterable, Iterator, List, Optional, Tuple, Union
 
 import numpy as np
 import numpy.typing as npt
 
 from supervision.config import CLASS_NAME_DATA_FIELD
+from supervision.detection.core import Detections
 from supervision.detection.utils import get_data_item, is_data_equal
 from supervision.validators import validate_keypoints_fields
 
@@ -18,11 +19,11 @@ class KeyPoints:
     The `sv.KeyPoints` class in the Supervision library standardizes results from
     various keypoint detection and pose estimation models into a consistent format. This
     class simplifies data manipulation and filtering, providing a uniform API for
-    integration with Supervision [keypoints annotators](/keypoint/annotators).
+    integration with Supervision [keypoints annotators](/latest/keypoint/annotators).
 
     === "Ultralytics"
 
-        Use [`sv.KeyPoints.from_ultralytics`](/keypoint/core/#supervision.keypoint.core.KeyPoints.from_ultralytics)
+        Use [`sv.KeyPoints.from_ultralytics`](/latest/keypoint/core/#supervision.keypoint.core.KeyPoints.from_ultralytics)
         method, which accepts [YOLOv8](https://github.com/ultralytics/ultralytics)
         pose result.
 
@@ -40,7 +41,7 @@ class KeyPoints:
 
     === "Inference"
 
-        Use [`sv.KeyPoints.from_inference`](/keypoint/core/#supervision.keypoint.core.KeyPoints.from_inference)
+        Use [`sv.KeyPoints.from_inference`](/latest/keypoint/core/#supervision.keypoint.core.KeyPoints.from_inference)
         method, which accepts [Inference](https://inference.roboflow.com/) pose result.
 
         ```python
@@ -57,7 +58,7 @@ class KeyPoints:
 
     === "MediaPipe"
 
-        Use [`sv.KeyPoints.from_mediapipe`](/keypoint/core/#supervision.keypoint.core.KeyPoints.from_mediapipe)
+        Use [`sv.KeyPoints.from_mediapipe`](/latest/keypoint/core/#supervision.keypoint.core.KeyPoints.from_mediapipe)
         method, which accepts [MediaPipe](https://github.com/google-ai-edge/mediapipe)
         pose result.
 
@@ -429,7 +430,7 @@ class KeyPoints:
             results = model.predict(image, conf=0.1)
             key_points = sv.KeyPoints.from_yolo_nas(results)
             ```
-        """  # noqa: E501 // docs
+        """
         if len(yolo_nas_results.prediction.poses) == 0:
             return cls.empty()
 
@@ -459,13 +460,13 @@ class KeyPoints:
         )
 
     @classmethod
-    def from_detectron2(cls, detectron2_results) -> KeyPoints:
+    def from_detectron2(cls, detectron2_results: Any) -> KeyPoints:
         """
         Create a `sv.KeyPoints` object from the
         [Detectron2](https://github.com/facebookresearch/detectron2) inference result.
 
         Args:
-            detectron2_results: The output of a
+            detectron2_results (Any): The output of a
                 Detectron2 model containing instances with prediction data.
 
         Returns:
@@ -612,3 +613,75 @@ class KeyPoints:
             ```
         """
         return cls(xy=np.empty((0, 0, 2), dtype=np.float32))
+
+    def is_empty(self) -> bool:
+        """
+        Returns `True` if the `KeyPoints` object is considered empty.
+        """
+        empty_keypoints = KeyPoints.empty()
+        empty_keypoints.data = self.data
+        return self == empty_keypoints
+
+    def as_detections(
+        self, selected_keypoint_indices: Optional[Iterable[int]] = None
+    ) -> Detections:
+        """
+        Convert a KeyPoints object to a Detections object. This
+        approximates the bounding box of the detected object by
+        taking the bounding box that fits all keypoints.
+
+        Arguments:
+            selected_keypoint_indices (Optional[Iterable[int]]): The
+                indices of the keypoints to include in the bounding box
+                calculation. This helps focus on a subset of keypoints,
+                e.g. when some are occluded. Captures all keypoints by default.
+
+        Returns:
+            detections (Detections): The converted detections object.
+
+        Example:
+            ```python
+            keypoints = sv.KeyPoints.from_inference(...)
+            detections = keypoints.as_detections()
+            ```
+        """
+        if self.is_empty():
+            return Detections.empty()
+
+        detections_list = []
+        for i, xy in enumerate(self.xy):
+            if selected_keypoint_indices:
+                xy = xy[selected_keypoint_indices]
+
+            # [0, 0] used by some frameworks to indicate missing keypoints
+            xy = xy[~np.all(xy == 0, axis=1)]
+            if len(xy) == 0:
+                xyxy = np.array([[0, 0, 0, 0]], dtype=np.float32)
+            else:
+                x_min = xy[:, 0].min()
+                x_max = xy[:, 0].max()
+                y_min = xy[:, 1].min()
+                y_max = xy[:, 1].max()
+                xyxy = np.array([[x_min, y_min, x_max, y_max]], dtype=np.float32)
+
+            if self.confidence is None:
+                confidence = None
+            else:
+                confidence = self.confidence[i]
+                if selected_keypoint_indices:
+                    confidence = confidence[selected_keypoint_indices]
+                confidence = np.array([confidence.mean()], dtype=np.float32)
+
+            detections_list.append(
+                Detections(
+                    xyxy=xyxy,
+                    confidence=confidence,
+                )
+            )
+
+        detections = Detections.merge(detections_list)
+        detections.class_id = self.class_id
+        detections.data = self.data
+        detections = detections[detections.area > 0]
+
+        return detections

supervision/keypoint/skeletons.py

@@ -1,11 +1,11 @@
 from enum import Enum
-from typing import Dict, List, Tuple
+from typing import Dict, Tuple
 
-Edges = List[Tuple[int, int]]
+Edges = Tuple[Tuple[int, int], ...]
 
 
 class Skeleton(Enum):
-    COCO = [
+    COCO: Edges = (
         (1, 2),
         (1, 3),
         (2, 3),
@@ -23,9 +23,9 @@ class Skeleton(Enum):
         (15, 13),
         (16, 14),
         (17, 15),
-    ]
+    )
 
-    GHUM = [
+    GHUM: Edges = (
         (1, 2),
         (1, 5),
         (2, 3),
@@ -61,9 +61,9 @@ class Skeleton(Enum):
         (29, 33),
         (30, 32),
         (31, 33),
-    ]
+    )
 
-    FACEMESH_TESSELATION_NO_IRIS = [
+    FACEMESH_TESSELATION_NO_IRIS: Edges = (
         (128, 35),
         (35, 140),
         (140, 128),
@@ -2620,9 +2620,9 @@ class Skeleton(Enum):
         (340, 449),
         (449, 256),
         (256, 340),
-    ]
+    )
 
-    FACEMESH_TESSELATION = [
+    FACEMESH_TESSELATION: Edges = (
         (474, 474),
         (475, 476),
         (476, 477),
@@ -2633,7 +2633,8 @@ class Skeleton(Enum):
         (471, 472),
         (472, 473),
         (473, 470),
-    ] + FACEMESH_TESSELATION_NO_IRIS
+        *FACEMESH_TESSELATION_NO_IRIS,
+    )
 
 
 SKELETONS_BY_EDGE_COUNT: Dict[int, Edges] = {}

supervision/metrics/__init__.py

@@ -1,8 +1,19 @@
-from supervision.metrics.core import CLASS_ID_NONE, Metric, MetricTarget
+from supervision.metrics.core import (
+    AveragingMethod,
+    Metric,
+    MetricTarget,
+)
+from supervision.metrics.f1_score import F1Score, F1ScoreResult
 from supervision.metrics.mean_average_precision import (
     MeanAveragePrecision,
     MeanAveragePrecisionResult,
 )
+from supervision.metrics.mean_average_recall import (
+    MeanAverageRecall,
+    MeanAverageRecallResult,
+)
+from supervision.metrics.precision import Precision, PrecisionResult
+from supervision.metrics.recall import Recall, RecallResult
 from supervision.metrics.utils.object_size import (
     ObjectSizeCategory,
     get_detection_size_category,

supervision/metrics/core.py

@@ -4,9 +4,6 @@ from abc import ABC, abstractmethod
 from enum import Enum
 from typing import Any
 
-CLASS_ID_NONE = -1
-"""Used by metrics module as class ID, when none is present"""
-
 
 class Metric(ABC):
     """
@@ -40,11 +37,36 @@ class MetricTarget(Enum):
     """
     Specifies what type of detection is used to compute the metric.
 
-    * BOXES: xyxy bounding boxes
-    * MASKS: Binary masks
-    * ORIENTED_BOUNDING_BOXES: Oriented bounding boxes (OBB)
+    Attributes:
+        BOXES: xyxy bounding boxes
+        MASKS: Binary masks
+        ORIENTED_BOUNDING_BOXES: Oriented bounding boxes (OBB)
     """
 
     BOXES = "boxes"
     MASKS = "masks"
     ORIENTED_BOUNDING_BOXES = "obb"
+
+
+class AveragingMethod(Enum):
+    """
+    Defines different ways of averaging the metric results.
+
+    Suppose, before returning the final result, a metric is computed for each class.
+    How do you combine those to get the final number?
+
+    Attributes:
+        MACRO: Calculate the metric for each class and average the results. The simplest
+            averaging method, but it does not take class imbalance into account.
+        MICRO: Calculate the metric globally by counting the total true positives, false
+            positives, and false negatives. Micro averaging is useful when you want to
+            give more importance to classes with more samples. It's also more
+            appropriate if you have an imbalance in the number of instances per class.
+        WEIGHTED: Calculate the metric for each class and average the results, weighted
+            by the number of true instances of each class. Use weighted averaging if
+            you want to take class imbalance into account.
+    """
+
+    MACRO = "macro"
+    MICRO = "micro"
+    WEIGHTED = "weighted"

supervision/metrics/detection.py

@@ -440,8 +440,8 @@ class ConfusionMatrix:
         class_names = classes if classes is not None else self.classes
         use_labels_for_ticks = class_names is not None and (0 < len(class_names) < 99)
         if use_labels_for_ticks:
-            x_tick_labels = class_names + ["FN"]
-            y_tick_labels = class_names + ["FP"]
+            x_tick_labels = [*class_names, "FN"]
+            y_tick_labels = [*class_names, "FP"]
             num_ticks = len(x_tick_labels)
         else:
             x_tick_labels = None

supervision/metrics/f1_score.py

@@ -0,0 +1,648 @@
+from __future__ import annotations
+
+from copy import deepcopy
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, List, Optional, Tuple, Union
+
+import numpy as np
+from matplotlib import pyplot as plt
+
+from supervision.config import ORIENTED_BOX_COORDINATES
+from supervision.detection.core import Detections
+from supervision.detection.utils import (
+    box_iou_batch,
+    mask_iou_batch,
+    oriented_box_iou_batch,
+)
+from supervision.draw.color import LEGACY_COLOR_PALETTE
+from supervision.metrics.core import AveragingMethod, Metric, MetricTarget
+from supervision.metrics.utils.object_size import (
+    ObjectSizeCategory,
+    get_detection_size_category,
+)
+from supervision.metrics.utils.utils import ensure_pandas_installed
+
+if TYPE_CHECKING:
+    import pandas as pd
+
+
+class F1Score(Metric):
+    """
+    F1 Score is a metric used to evaluate object detection models. It is the harmonic
+    mean of precision and recall, calculated at different IoU thresholds.
+
+    In simple terms, F1 Score is a measure of a model's balance between precision and
+    recall (accuracy and completeness), calculated as:
+
+    `F1 = 2 * (precision * recall) / (precision + recall)`
+
+    Example:
+        ```python
+        import supervision as sv
+        from supervision.metrics import F1Score
+
+        predictions = sv.Detections(...)
+        targets = sv.Detections(...)
+
+        f1_metric = F1Score()
+        f1_result = f1_metric.update(predictions, targets).compute()
+
+        print(f1_result.f1_50)
+        # 0.7618
+
+        print(f1_result)
+        # F1ScoreResult:
+        # Metric target: MetricTarget.BOXES
+        # Averaging method: AveragingMethod.WEIGHTED
+        # F1 @ 50:     0.7618
+        # F1 @ 75:     0.7487
+        # F1 @ thresh: [0.76175  0.76068  0.76068]
+        # IoU thresh:  [0.5  0.55  0.6  ...]
+        # F1 per class:
+        # 0: [0.70968  0.70968  0.70968  ...]
+        # ...
+        # Small objects: ...
+        # Medium objects: ...
+        # Large objects: ...
+
+        f1_result.plot()
+        ```
+
+    ![example_plot](\
+        https://media.roboflow.com/supervision-docs/metrics/f1_plot_example.png\
+        ){ align=center width="800" }
+    """
+
+    def __init__(
+        self,
+        metric_target: MetricTarget = MetricTarget.BOXES,
+        averaging_method: AveragingMethod = AveragingMethod.WEIGHTED,
+    ):
+        """
+        Initialize the F1Score metric.
+
+        Args:
+            metric_target (MetricTarget): The type of detection data to use.
+            averaging_method (AveragingMethod): The averaging method used to compute the
+                F1 scores. Determines how the F1 scores are aggregated across classes.
+        """
+        self._metric_target = metric_target
+        self.averaging_method = averaging_method
+
+        self._predictions_list: List[Detections] = []
+        self._targets_list: List[Detections] = []
+
+    def reset(self) -> None:
+        """
+        Reset the metric to its initial state, clearing all stored data.
+        """
+        self._predictions_list = []
+        self._targets_list = []
+
+    def update(
+        self,
+        predictions: Union[Detections, List[Detections]],
+        targets: Union[Detections, List[Detections]],
+    ) -> F1Score:
+        """
+        Add new predictions and targets to the metric, but do not compute the result.
+
+        Args:
+            predictions (Union[Detections, List[Detections]]): The predicted detections.
+            targets (Union[Detections, List[Detections]]): The target detections.
+
+        Returns:
+            (F1Score): The updated metric instance.
+        """
+        if not isinstance(predictions, list):
+            predictions = [predictions]
+        if not isinstance(targets, list):
+            targets = [targets]
+
+        if len(predictions) != len(targets):
+            raise ValueError(
+                f"The number of predictions ({len(predictions)}) and"
+                f" targets ({len(targets)}) during the update must be the same."
+            )
+
+        self._predictions_list.extend(predictions)
+        self._targets_list.extend(targets)
+
+        return self
+
+    def compute(self) -> F1ScoreResult:
+        """
+        Calculate the F1 score metric based on the stored predictions and ground-truth
+        data, at different IoU thresholds.
+
+        Returns:
+            (F1ScoreResult): The F1 score metric result.
+        """
+        result = self._compute(self._predictions_list, self._targets_list)
+
+        small_predictions, small_targets = self._filter_predictions_and_targets_by_size(
+            self._predictions_list, self._targets_list, ObjectSizeCategory.SMALL
+        )
+        result.small_objects = self._compute(small_predictions, small_targets)
+
+        medium_predictions, medium_targets = (
+            self._filter_predictions_and_targets_by_size(
+                self._predictions_list, self._targets_list, ObjectSizeCategory.MEDIUM
+            )
+        )
+        result.medium_objects = self._compute(medium_predictions, medium_targets)
+
+        large_predictions, large_targets = self._filter_predictions_and_targets_by_size(
+            self._predictions_list, self._targets_list, ObjectSizeCategory.LARGE
+        )
+        result.large_objects = self._compute(large_predictions, large_targets)
+
+        return result
+
+    def _compute(
+        self, predictions_list: List[Detections], targets_list: List[Detections]
+    ) -> F1ScoreResult:
+        iou_thresholds = np.linspace(0.5, 0.95, 10)
+        stats = []
+
+        for predictions, targets in zip(predictions_list, targets_list):
+            prediction_contents = self._detections_content(predictions)
+            target_contents = self._detections_content(targets)
+
+            if len(targets) > 0:
+                if len(predictions) == 0:
+                    stats.append(
+                        (
+                            np.zeros((0, iou_thresholds.size), dtype=bool),
+                            np.zeros((0,), dtype=np.float32),
+                            np.zeros((0,), dtype=int),
+                            targets.class_id,
+                        )
+                    )
+
+                else:
+                    if self._metric_target == MetricTarget.BOXES:
+                        iou = box_iou_batch(target_contents, prediction_contents)
+                    elif self._metric_target == MetricTarget.MASKS:
+                        iou = mask_iou_batch(target_contents, prediction_contents)
+                    elif self._metric_target == MetricTarget.ORIENTED_BOUNDING_BOXES:
+                        iou = oriented_box_iou_batch(
+                            target_contents, prediction_contents
+                        )
+                    else:
+                        raise ValueError(
+                            "Unsupported metric target for IoU calculation"
+                        )
+
+                    matches = self._match_detection_batch(
+                        predictions.class_id, targets.class_id, iou, iou_thresholds
+                    )
+                    stats.append(
+                        (
+                            matches,
+                            predictions.confidence,
+                            predictions.class_id,
+                            targets.class_id,
+                        )
+                    )
+
+        if not stats:
+            return F1ScoreResult(
+                metric_target=self._metric_target,
+                averaging_method=self.averaging_method,
+                f1_scores=np.zeros(iou_thresholds.shape[0]),
+                f1_per_class=np.zeros((0, iou_thresholds.shape[0])),
+                iou_thresholds=iou_thresholds,
+                matched_classes=np.array([], dtype=int),
+                small_objects=None,
+                medium_objects=None,
+                large_objects=None,
+            )
+
+        concatenated_stats = [np.concatenate(items, 0) for items in zip(*stats)]
+        f1_scores, f1_per_class, unique_classes = self._compute_f1_for_classes(
+            *concatenated_stats
+        )
+
+        return F1ScoreResult(
+            metric_target=self._metric_target,
+            averaging_method=self.averaging_method,
+            f1_scores=f1_scores,
+            f1_per_class=f1_per_class,
+            iou_thresholds=iou_thresholds,
+            matched_classes=unique_classes,
+            small_objects=None,
+            medium_objects=None,
+            large_objects=None,
+        )
+
+    def _compute_f1_for_classes(
+        self,
+        matches: np.ndarray,
+        prediction_confidence: np.ndarray,
+        prediction_class_ids: np.ndarray,
+        true_class_ids: np.ndarray,
+    ) -> Tuple[np.ndarray, np.ndarray, np.ndarray]:
+        sorted_indices = np.argsort(-prediction_confidence)
+        matches = matches[sorted_indices]
+        prediction_class_ids = prediction_class_ids[sorted_indices]
+        unique_classes, class_counts = np.unique(true_class_ids, return_counts=True)
+
+        # Shape: PxTh,P,C,C -> CxThx3
+        confusion_matrix = self._compute_confusion_matrix(
+            matches, prediction_class_ids, unique_classes, class_counts
+        )
+
+        # Shape: CxThx3 -> CxTh
+        f1_per_class = self._compute_f1(confusion_matrix)
+
+        # Shape: CxTh -> Th
+        if self.averaging_method == AveragingMethod.MACRO:
+            f1_scores = np.mean(f1_per_class, axis=0)
+        elif self.averaging_method == AveragingMethod.MICRO:
+            confusion_matrix_merged = confusion_matrix.sum(0)
+            f1_scores = self._compute_f1(confusion_matrix_merged)
+        elif self.averaging_method == AveragingMethod.WEIGHTED:
+            class_counts = class_counts.astype(np.float32)
+            f1_scores = np.average(f1_per_class, axis=0, weights=class_counts)
+
+        return f1_scores, f1_per_class, unique_classes
+
+    @staticmethod
+    def _match_detection_batch(
+        predictions_classes: np.ndarray,
+        target_classes: np.ndarray,
+        iou: np.ndarray,
+        iou_thresholds: np.ndarray,
+    ) -> np.ndarray:
+        num_predictions, num_iou_levels = (
+            predictions_classes.shape[0],
+            iou_thresholds.shape[0],
+        )
+        correct = np.zeros((num_predictions, num_iou_levels), dtype=bool)
+        correct_class = target_classes[:, None] == predictions_classes
+
+        for i, iou_level in enumerate(iou_thresholds):
+            matched_indices = np.where((iou >= iou_level) & correct_class)
+
+            if matched_indices[0].shape[0]:
+                combined_indices = np.stack(matched_indices, axis=1)
+                iou_values = iou[matched_indices][:, None]
+                matches = np.hstack([combined_indices, iou_values])
+
+                if matched_indices[0].shape[0] > 1:
+                    matches = matches[matches[:, 2].argsort()[::-1]]
+                    matches = matches[np.unique(matches[:, 1], return_index=True)[1]]
+                    matches = matches[np.unique(matches[:, 0], return_index=True)[1]]
+
+                correct[matches[:, 1].astype(int), i] = True
+
+        return correct
+
+    @staticmethod
+    def _compute_confusion_matrix(
+        sorted_matches: np.ndarray,
+        sorted_prediction_class_ids: np.ndarray,
+        unique_classes: np.ndarray,
+        class_counts: np.ndarray,
+    ) -> np.ndarray:
+        """
+        Compute the confusion matrix for each class and IoU threshold.
+
+        Assumes the matches and prediction_class_ids are sorted by confidence
+        in descending order.
+
+        Arguments:
+            sorted_matches: np.ndarray, bool, shape (P, Th), that is True
+                if the prediction is a true positive at the given IoU threshold.
+            sorted_prediction_class_ids: np.ndarray, int, shape (P,), containing
+                the class id for each prediction.
+            unique_classes: np.ndarray, int, shape (C,), containing the unique
+                class ids.
+            class_counts: np.ndarray, int, shape (C,), containing the number
+                of true instances for each class.
+
+        Returns:
+            np.ndarray, shape (C, Th, 3), containing the true positives, false
+                positives, and false negatives for each class and IoU threshold.
+        """
+
+        num_thresholds = sorted_matches.shape[1]
+        num_classes = unique_classes.shape[0]
+
+        confusion_matrix = np.zeros((num_classes, num_thresholds, 3))
+        for class_idx, class_id in enumerate(unique_classes):
+            is_class = sorted_prediction_class_ids == class_id
+            num_true = class_counts[class_idx]
+            num_predictions = is_class.sum()
+
+            if num_predictions == 0:
+                true_positives = np.zeros(num_thresholds)
+                false_positives = np.zeros(num_thresholds)
+                false_negatives = np.full(num_thresholds, num_true)
+            elif num_true == 0:
+                true_positives = np.zeros(num_thresholds)
+                false_positives = np.full(num_thresholds, num_predictions)
+                false_negatives = np.zeros(num_thresholds)
+            else:
+                true_positives = sorted_matches[is_class].sum(0)
+                false_positives = (1 - sorted_matches[is_class]).sum(0)
+                false_negatives = num_true - true_positives
+            confusion_matrix[class_idx] = np.stack(
+                [true_positives, false_positives, false_negatives], axis=1
+            )
+
+        return confusion_matrix
+
+    @staticmethod
+    def _compute_f1(confusion_matrix: np.ndarray) -> np.ndarray:
+        """
+        Broadcastable function, computing the F1 score from the confusion matrix.
+
+        Arguments:
+            confusion_matrix: np.ndarray, shape (N, ..., 3), where the last dimension
+                contains the true positives, false positives, and false negatives.
+
+        Returns:
+            np.ndarray, shape (N, ...), containing the F1 score for each element.
+        """
+        if not confusion_matrix.shape[-1] == 3:
+            raise ValueError(
+                f"Confusion matrix must have shape (..., 3), got "
+                f"{confusion_matrix.shape}"
+            )
+        true_positives = confusion_matrix[..., 0]
+        false_positives = confusion_matrix[..., 1]
+        false_negatives = confusion_matrix[..., 2]
+
+        # Alternate formula, avoids multiple zero division checks
+        denominator = 2 * true_positives + false_positives + false_negatives
+        f1_score = np.where(denominator == 0, 0, 2 * true_positives / denominator)
+
+        return f1_score
+
+    def _detections_content(self, detections: Detections) -> np.ndarray:
+        """Return boxes, masks or oriented bounding boxes from detections."""
+        if self._metric_target == MetricTarget.BOXES:
+            return detections.xyxy
+        if self._metric_target == MetricTarget.MASKS:
+            return (
+                detections.mask
+                if detections.mask is not None
+                else self._make_empty_content()
+            )
+        if self._metric_target == MetricTarget.ORIENTED_BOUNDING_BOXES:
+            obb = detections.data.get(ORIENTED_BOX_COORDINATES)
+            if obb is not None and len(obb) > 0:
+                return np.array(obb, dtype=np.float32)
+            return self._make_empty_content()
+        raise ValueError(f"Invalid metric target: {self._metric_target}")
+
+    def _make_empty_content(self) -> np.ndarray:
+        if self._metric_target == MetricTarget.BOXES:
+            return np.empty((0, 4), dtype=np.float32)
+        if self._metric_target == MetricTarget.MASKS:
+            return np.empty((0, 0, 0), dtype=bool)
+        if self._metric_target == MetricTarget.ORIENTED_BOUNDING_BOXES:
+            return np.empty((0, 4, 2), dtype=np.float32)
+        raise ValueError(f"Invalid metric target: {self._metric_target}")
+
+    def _filter_detections_by_size(
+        self, detections: Detections, size_category: ObjectSizeCategory
+    ) -> Detections:
+        """Return a copy of detections with contents filtered by object size."""
+        new_detections = deepcopy(detections)
+        if detections.is_empty() or size_category == ObjectSizeCategory.ANY:
+            return new_detections
+
+        sizes = get_detection_size_category(new_detections, self._metric_target)
+        size_mask = sizes == size_category.value
+
+        new_detections.xyxy = new_detections.xyxy[size_mask]
+        if new_detections.mask is not None:
+            new_detections.mask = new_detections.mask[size_mask]
+        if new_detections.class_id is not None:
+            new_detections.class_id = new_detections.class_id[size_mask]
+        if new_detections.confidence is not None:
+            new_detections.confidence = new_detections.confidence[size_mask]
+        if new_detections.tracker_id is not None:
+            new_detections.tracker_id = new_detections.tracker_id[size_mask]
+        if new_detections.data is not None:
+            for key, value in new_detections.data.items():
+                new_detections.data[key] = np.array(value)[size_mask]
+
+        return new_detections
+
+    def _filter_predictions_and_targets_by_size(
+        self,
+        predictions_list: List[Detections],
+        targets_list: List[Detections],
+        size_category: ObjectSizeCategory,
+    ) -> Tuple[List[Detections], List[Detections]]:
+        """
+        Filter predictions and targets by object size category.
+        """
+        new_predictions_list = []
+        new_targets_list = []
+        for predictions, targets in zip(predictions_list, targets_list):
+            new_predictions_list.append(
+                self._filter_detections_by_size(predictions, size_category)
+            )
+            new_targets_list.append(
+                self._filter_detections_by_size(targets, size_category)
+            )
+        return new_predictions_list, new_targets_list
+
+
+@dataclass
+class F1ScoreResult:
+    """
+    The results of the F1 score metric calculation.
+
+    Defaults to `0` if no detections or targets were provided.
+
+    Attributes:
+        metric_target (MetricTarget): the type of data used for the metric -
+            boxes, masks or oriented bounding boxes.
+        averaging_method (AveragingMethod): the averaging method used to compute the
+            F1 scores. Determines how the F1 scores are aggregated across classes.
+        f1_50 (float): the F1 score at IoU threshold of `0.5`.
+        f1_75 (float): the F1 score at IoU threshold of `0.75`.
+        f1_scores (np.ndarray): the F1 scores at each IoU threshold.
+            Shape: `(num_iou_thresholds,)`
+        f1_per_class (np.ndarray): the F1 scores per class and IoU threshold.
+            Shape: `(num_target_classes, num_iou_thresholds)`
+        iou_thresholds (np.ndarray): the IoU thresholds used in the calculations.
+        matched_classes (np.ndarray): the class IDs of all matched classes.
+            Corresponds to the rows of `f1_per_class`.
+        small_objects (Optional[F1ScoreResult]): the F1 metric results
+            for small objects (area < 32²).
+        medium_objects (Optional[F1ScoreResult]): the F1 metric results
+            for medium objects (32² ≤ area < 96²).
+        large_objects (Optional[F1ScoreResult]): the F1 metric results
+            for large objects (area ≥ 96²).
+    """
+
+    metric_target: MetricTarget
+    averaging_method: AveragingMethod
+
+    @property
+    def f1_50(self) -> float:
+        return self.f1_scores[0]
+
+    @property
+    def f1_75(self) -> float:
+        return self.f1_scores[5]
+
+    f1_scores: np.ndarray
+    f1_per_class: np.ndarray
+    iou_thresholds: np.ndarray
+    matched_classes: np.ndarray
+
+    small_objects: Optional[F1ScoreResult]
+    medium_objects: Optional[F1ScoreResult]
+    large_objects: Optional[F1ScoreResult]
+
+    def __str__(self) -> str:
+        """
+        Format as a pretty string.
+
+        Example:
+            ```python
+            print(f1_result)
+            # F1ScoreResult:
+            # Metric target: MetricTarget.BOXES
+            # Averaging method: AveragingMethod.WEIGHTED
+            # F1 @ 50:     0.7618
+            # F1 @ 75:     0.7487
+            # F1 @ thresh: [0.76175  0.76068  0.76068]
+            # IoU thresh:  [0.5  0.55  0.6  ...]
+            # F1 per class:
+            # 0: [0.70968  0.70968  0.70968  ...]
+            # ...
+            # Small objects: ...
+            # Medium objects: ...
+            # Large objects: ...
+            ```
+        """
+        out_str = (
+            f"{self.__class__.__name__}:\n"
+            f"Metric target: {self.metric_target}\n"
+            f"Averaging method: {self.averaging_method}\n"
+            f"F1 @ 50:     {self.f1_50:.4f}\n"
+            f"F1 @ 75:     {self.f1_75:.4f}\n"
+            f"F1 @ thresh: {self.f1_scores}\n"
+            f"IoU thresh:  {self.iou_thresholds}\n"
+            f"F1 per class:\n"
+        )
+        if self.f1_per_class.size == 0:
+            out_str += "  No results\n"
+        for class_id, f1_of_class in zip(self.matched_classes, self.f1_per_class):
+            out_str += f"  {class_id}: {f1_of_class}\n"
+
+        indent = "  "
+        if self.small_objects is not None:
+            indented = indent + str(self.small_objects).replace("\n", f"\n{indent}")
+            out_str += f"\nSmall objects:\n{indented}"
+        if self.medium_objects is not None:
+            indented = indent + str(self.medium_objects).replace("\n", f"\n{indent}")
+            out_str += f"\nMedium objects:\n{indented}"
+        if self.large_objects is not None:
+            indented = indent + str(self.large_objects).replace("\n", f"\n{indent}")
+            out_str += f"\nLarge objects:\n{indented}"
+
+        return out_str
+
+    def to_pandas(self) -> "pd.DataFrame":
+        """
+        Convert the result to a pandas DataFrame.
+
+        Returns:
+            (pd.DataFrame): The result as a DataFrame.
+        """
+        ensure_pandas_installed()
+        import pandas as pd
+
+        pandas_data = {
+            "F1@50": self.f1_50,
+            "F1@75": self.f1_75,
+        }
+
+        if self.small_objects is not None:
+            small_objects_df = self.small_objects.to_pandas()
+            for key, value in small_objects_df.items():
+                pandas_data[f"small_objects_{key}"] = value
+        if self.medium_objects is not None:
+            medium_objects_df = self.medium_objects.to_pandas()
+            for key, value in medium_objects_df.items():
+                pandas_data[f"medium_objects_{key}"] = value
+        if self.large_objects is not None:
+            large_objects_df = self.large_objects.to_pandas()
+            for key, value in large_objects_df.items():
+                pandas_data[f"large_objects_{key}"] = value
+
+        return pd.DataFrame(pandas_data, index=[0])
+
+    def plot(self):
+        """
+        Plot the F1 results.
+
+        ![example_plot](\
+            https://media.roboflow.com/supervision-docs/metrics/f1_plot_example.png\
+            ){ align=center width="800" }
+        """
+
+        labels = ["F1@50", "F1@75"]
+        values = [self.f1_50, self.f1_75]
+        colors = [LEGACY_COLOR_PALETTE[0]] * 2
+
+        if self.small_objects is not None:
+            small_objects = self.small_objects
+            labels += ["Small: F1@50", "Small: F1@75"]
+            values += [small_objects.f1_50, small_objects.f1_75]
+            colors += [LEGACY_COLOR_PALETTE[3]] * 2
+
+        if self.medium_objects is not None:
+            medium_objects = self.medium_objects
+            labels += ["Medium: F1@50", "Medium: F1@75"]
+            values += [medium_objects.f1_50, medium_objects.f1_75]
+            colors += [LEGACY_COLOR_PALETTE[2]] * 2
+
+        if self.large_objects is not None:
+            large_objects = self.large_objects
+            labels += ["Large: F1@50", "Large: F1@75"]
+            values += [large_objects.f1_50, large_objects.f1_75]
+            colors += [LEGACY_COLOR_PALETTE[4]] * 2
+
+        plt.rcParams["font.family"] = "monospace"
+
+        _, ax = plt.subplots(figsize=(10, 6))
+        ax.set_ylim(0, 1)
+        ax.set_ylabel("Value", fontweight="bold")
+        title = (
+            f"F1 Score, by Object Size"
+            f"\n(target: {self.metric_target.value},"
+            f" averaging: {self.averaging_method.value})"
+        )
+        ax.set_title(title, fontweight="bold")
+
+        x_positions = range(len(labels))
+        bars = ax.bar(x_positions, values, color=colors, align="center")
+
+        ax.set_xticks(x_positions)
+        ax.set_xticklabels(labels, rotation=45, ha="right")
+
+        for bar in bars:
+            y_value = bar.get_height()
+            ax.text(
+                bar.get_x() + bar.get_width() / 2,
+                y_value + 0.02,
+                f"{y_value:.2f}",
+                ha="center",
+                va="bottom",
+            )
+
+        plt.rcParams["font.family"] = "sans-serif"
+
+        plt.tight_layout()
+        plt.show()

supervision/metrics/mean_average_precision.py

@@ -2,14 +2,18 @@ from __future__ import annotations
 
 from copy import deepcopy
 from dataclasses import dataclass
-from typing import TYPE_CHECKING, List, Optional, Union
+from typing import TYPE_CHECKING, List, Optional, Tuple, Union
 
 import numpy as np
 from matplotlib import pyplot as plt
 
 from supervision.config import ORIENTED_BOX_COORDINATES
 from supervision.detection.core import Detections
-from supervision.detection.utils import box_iou_batch, mask_iou_batch
+from supervision.detection.utils import (
+    box_iou_batch,
+    mask_iou_batch,
+    oriented_box_iou_batch,
+)
 from supervision.draw.color import LEGACY_COLOR_PALETTE
 from supervision.metrics.core import Metric, MetricTarget
 from supervision.metrics.utils.object_size import (
@@ -23,6 +27,48 @@ if TYPE_CHECKING:
 
 
 class MeanAveragePrecision(Metric):
+    """
+    Mean Average Precision (mAP) is a metric used to evaluate object detection models.
+    It is the average of the precision-recall curves at different IoU thresholds.
+
+    Example:
+        ```python
+        import supervision as sv
+        from supervision.metrics import MeanAveragePrecision
+
+        predictions = sv.Detections(...)
+        targets = sv.Detections(...)
+
+        map_metric = MeanAveragePrecision()
+        map_result = map_metric.update(predictions, targets).compute()
+
+        print(map_result.map50_95)
+        # 0.4674
+
+        print(map_result)
+        # MeanAveragePrecisionResult:
+        # Metric target: MetricTarget.BOXES
+        # Class agnostic: False
+        # mAP @ 50:95: 0.4674
+        # mAP @ 50:    0.5048
+        # mAP @ 75:    0.4796
+        # mAP scores: [0.50485  0.50377  0.50377  ...]
+        # IoU thresh: [0.5  0.55  0.6  ...]
+        # AP per class:
+        # 0: [0.67699  0.67699  0.67699  ...]
+        # ...
+        # Small objects: ...
+        # Medium objects: ...
+        # Large objects: ...
+
+        map_result.plot()
+        ```
+
+    ![example_plot](\
+        https://media.roboflow.com/supervision-docs/metrics/mAP_plot_example.png\
+        ){ align=center width="800" }
+    """
+
     def __init__(
         self,
         metric_target: MetricTarget = MetricTarget.BOXES,
@@ -36,17 +82,15 @@ class MeanAveragePrecision(Metric):
             class_agnostic (bool): Whether to treat all data as a single class.
         """
         self._metric_target = metric_target
-        if self._metric_target == MetricTarget.ORIENTED_BOUNDING_BOXES:
-            raise NotImplementedError(
-                "Mean Average Precision is not implemented for oriented bounding boxes."
-            )
-
         self._class_agnostic = class_agnostic
 
         self._predictions_list: List[Detections] = []
         self._targets_list: List[Detections] = []
 
     def reset(self) -> None:
+        """
+        Reset the metric to its initial state, clearing all stored data.
+        """
         self._predictions_list = []
         self._targets_list = []
 
@@ -76,6 +120,15 @@ class MeanAveragePrecision(Metric):
                 f" targets ({len(targets)}) during the update must be the same."
             )
 
+        if self._class_agnostic:
+            predictions = deepcopy(predictions)
+            targets = deepcopy(targets)
+
+            for prediction in predictions:
+                prediction.class_id[:] = -1
+            for target in targets:
+                target.class_id[:] = -1
+
         self._predictions_list.extend(predictions)
         self._targets_list.extend(targets)
 
@@ -86,35 +139,10 @@ class MeanAveragePrecision(Metric):
     ) -> MeanAveragePrecisionResult:
         """
         Calculate Mean Average Precision based on predicted and ground-truth
-            detections at different threshold.
+        detections at different thresholds.
 
-        Args:
-            predictions (List[np.ndarray]): Each element of the list describes
-                a single image and has `shape = (M, 6)` where `M` is
-                the number of detected objects. Each row is expected to be
-                in `(x_min, y_min, x_max, y_max, class, conf)` format.
-            targets (List[np.ndarray]): Each element of the list describes a single
-                image and has `shape = (N, 5)` where `N` is the
-                number of ground-truth objects. Each row is expected to be in
-                `(x_min, y_min, x_max, y_max, class)` format.
         Returns:
-            (MeanAveragePrecision): New instance of MeanAveragePrecision.
-
-        Example:
-            ```python
-            import supervision as sv
-            from supervision.metrics import MeanAveragePrecision
-
-            predictions = sv.Detections(...)
-            targets = sv.Detections(...)
-
-            map_metric = MeanAveragePrecision()
-            map_result = map_metric.update(predictions, targets).compute()
-
-            print(map_result)
-            print(map_result.map50_95)
-            map_result.plot()
-            ```
+            (MeanAveragePrecisionResult): The Mean Average Precision result.
         """
         result = self._compute(self._predictions_list, self._targets_list)
 
@@ -181,14 +209,19 @@ class MeanAveragePrecision(Metric):
                         iou = box_iou_batch(target_contents, prediction_contents)
                     elif self._metric_target == MetricTarget.MASKS:
                         iou = mask_iou_batch(target_contents, prediction_contents)
+                    elif self._metric_target == MetricTarget.ORIENTED_BOUNDING_BOXES:
+                        iou = oriented_box_iou_batch(
+                            target_contents, prediction_contents
+                        )
                     else:
-                        raise NotImplementedError(
+                        raise ValueError(
                             "Unsupported metric target for IoU calculation"
                         )
 
                     matches = self._match_detection_batch(
                         predictions.class_id, targets.class_id, iou, iou_thresholds
                     )
+
                     stats.append(
                         (
                             matches,
@@ -201,25 +234,26 @@ class MeanAveragePrecision(Metric):
         # Compute average precisions if any matches exist
         if stats:
             concatenated_stats = [np.concatenate(items, 0) for items in zip(*stats)]
-            average_precisions = self._average_precisions_per_class(*concatenated_stats)
-            map50 = average_precisions[:, 0].mean()
-            map75 = average_precisions[:, 5].mean()
-            map50_95 = average_precisions.mean()
+            average_precisions, unique_classes = self._average_precisions_per_class(
+                *concatenated_stats
+            )
+            mAP_scores = np.mean(average_precisions, axis=0)
         else:
-            map50, map75, map50_95 = 0, 0, 0
+            mAP_scores = np.zeros((10,), dtype=np.float32)
+            unique_classes = np.empty((0,), dtype=int)
             average_precisions = np.empty((0, len(iou_thresholds)), dtype=np.float32)
 
         return MeanAveragePrecisionResult(
-            iou_thresholds=iou_thresholds,
-            map50_95=map50_95,
-            map50=map50,
-            map75=map75,
-            per_class_ap50_95=average_precisions,
             metric_target=self._metric_target,
+            is_class_agnostic=self._class_agnostic,
+            mAP_scores=mAP_scores,
+            iou_thresholds=iou_thresholds,
+            matched_classes=unique_classes,
+            ap_per_class=average_precisions,
         )
 
     @staticmethod
-    def compute_average_precision(recall: np.ndarray, precision: np.ndarray) -> float:
+    def _compute_average_precision(recall: np.ndarray, precision: np.ndarray) -> float:
         """
         Compute the average precision using 101-point interpolation (COCO), given
             the recall and precision curves.
@@ -231,16 +265,15 @@ class MeanAveragePrecision(Metric):
         Returns:
             (float): Average precision.
         """
-        extended_recall = np.concatenate(([0.0], recall, [1.0]))
-        extended_precision = np.concatenate(([1.0], precision, [0.0]))
-        max_accumulated_precision = np.flip(
-            np.maximum.accumulate(np.flip(extended_precision))
-        )
-        interpolated_recall_levels = np.linspace(0, 1, 101)
-        interpolated_precision = np.interp(
-            interpolated_recall_levels, extended_recall, max_accumulated_precision
-        )
-        average_precision = np.trapz(interpolated_precision, interpolated_recall_levels)
+        if len(recall) == 0 and len(precision) == 0:
+            return 0.0
+
+        recall_levels = np.linspace(0, 1, 101)
+        precision_levels = np.zeros_like(recall_levels)
+        for r, p in zip(recall[::-1], precision[::-1]):
+            precision_levels[recall_levels <= r] = p
+
+        average_precision = (1 / 101 * precision_levels).sum()
         return average_precision
 
     @staticmethod
@@ -280,7 +313,7 @@ class MeanAveragePrecision(Metric):
         prediction_confidence: np.ndarray,
         prediction_class_ids: np.ndarray,
         true_class_ids: np.ndarray,
-    ) -> np.ndarray:
+    ) -> Tuple[np.ndarray, np.ndarray]:
         """
         Compute the average precision, given the recall and precision curves.
         Source: https://github.com/rafaelpadilla/Object-Detection-Metrics.
@@ -293,7 +326,8 @@ class MeanAveragePrecision(Metric):
             eps (float, optional): Small value to prevent division by zero.
 
         Returns:
-            (np.ndarray): Average precision for different IoU levels.
+            (Tuple[np.ndarray, np.ndarray]): Average precision for different
+                IoU levels, and an array of class IDs that were matched.
         """
         eps = 1e-16
 
@@ -316,19 +350,19 @@ class MeanAveragePrecision(Metric):
 
             false_positives = (1 - matches[is_class]).cumsum(0)
             true_positives = matches[is_class].cumsum(0)
-            true_negatives = total_true - true_positives
+            false_negatives = total_true - true_positives
 
-            recall = true_positives / (true_positives + true_negatives + eps)
+            recall = true_positives / (true_positives + false_negatives + eps)
             precision = true_positives / (true_positives + false_positives)
 
             for iou_level_idx in range(matches.shape[1]):
                 average_precisions[class_idx, iou_level_idx] = (
-                    MeanAveragePrecision.compute_average_precision(
+                    MeanAveragePrecision._compute_average_precision(
                         recall[:, iou_level_idx], precision[:, iou_level_idx]
                     )
                 )
 
-        return average_precisions
+        return average_precisions, unique_classes
 
     def _detections_content(self, detections: Detections) -> np.ndarray:
         """Return boxes, masks or oriented bounding boxes from detections."""
@@ -341,8 +375,9 @@ class MeanAveragePrecision(Metric):
                 else self._make_empty_content()
             )
         if self._metric_target == MetricTarget.ORIENTED_BOUNDING_BOXES:
-            if obb := detections.data.get(ORIENTED_BOX_COORDINATES):
-                return np.ndarray(obb, dtype=np.float32)
+            obb = detections.data.get(ORIENTED_BOX_COORDINATES)
+            if obb is not None and len(obb) > 0:
+                return np.array(obb, dtype=np.float32)
             return self._make_empty_content()
         raise ValueError(f"Invalid metric target: {self._metric_target}")
 
@@ -352,7 +387,7 @@ class MeanAveragePrecision(Metric):
         if self._metric_target == MetricTarget.MASKS:
             return np.empty((0, 0, 0), dtype=bool)
         if self._metric_target == MetricTarget.ORIENTED_BOUNDING_BOXES:
-            return np.empty((0, 8), dtype=np.float32)
+            return np.empty((0, 4, 2), dtype=np.float32)
         raise ValueError(f"Invalid metric target: {self._metric_target}")
 
     def _filter_detections_by_size(
@@ -384,69 +419,107 @@ class MeanAveragePrecision(Metric):
 
 @dataclass
 class MeanAveragePrecisionResult:
-    iou_thresholds: np.ndarray
-    """Array of IoU thresholds used in the calculations"""
-    map50_95: float
-    """Mean Average Precision over IoU thresholds from 0.5 to 0.95"""
+    """
+    The result of the Mean Average Precision calculation.
 
-    map50: float
-    """Mean Average Precision at IoU threshold of 0.5"""
+    Defaults to `0` when no detections or targets are present.
 
-    map75: float
-    """Mean Average Precision at IoU threshold of 0.75"""
-
-    per_class_ap50_95: np.ndarray
-    """Average precision for each class at different IoU thresholds"""
+    Attributes:
+        metric_target (MetricTarget): the type of data used for the metric -
+            boxes, masks or oriented bounding boxes.
+        class_agnostic (bool): When computing class-agnostic results, class ID
+            is set to `-1`.
+        mAP_map50_95 (float): the mAP score at IoU thresholds from `0.5` to `0.95`.
+        mAP_map50 (float): the mAP score at IoU threshold of `0.5`.
+        mAP_map75 (float): the mAP score at IoU threshold of `0.75`.
+        mAP_scores (np.ndarray): the mAP scores at each IoU threshold.
+            Shape: `(num_iou_thresholds,)`
+        ap_per_class (np.ndarray): the average precision scores per
+            class and IoU threshold. Shape: `(num_target_classes, num_iou_thresholds)`
+        iou_thresholds (np.ndarray): the IoU thresholds used in the calculations.
+        matched_classes (np.ndarray): the class IDs of all matched classes.
+            Corresponds to the rows of `ap_per_class`.
+        small_objects (Optional[MeanAveragePrecisionResult]): the mAP results
+            for small objects (area < 32²).
+        medium_objects (Optional[MeanAveragePrecisionResult]): the mAP results
+            for medium objects (32² ≤ area < 96²).
+        large_objects (Optional[MeanAveragePrecisionResult]): the mAP results
+            for large objects (area ≥ 96²).
+    """
 
     metric_target: MetricTarget
-    """
-    Defines the type of data used for the metric - boxes, masks or
-    oriented bounding boxes.
-    """
+    is_class_agnostic: bool
 
+    @property
+    def map50_95(self) -> float:
+        return self.mAP_scores.mean()
+
+    @property
+    def map50(self) -> float:
+        return self.mAP_scores[0]
+
+    @property
+    def map75(self) -> float:
+        return self.mAP_scores[5]
+
+    mAP_scores: np.ndarray
+    ap_per_class: np.ndarray
+    iou_thresholds: np.ndarray
+    matched_classes: np.ndarray
     small_objects: Optional[MeanAveragePrecisionResult] = None
-    """Mean Average Precision results for small objects"""
-
     medium_objects: Optional[MeanAveragePrecisionResult] = None
-    """Mean Average Precision results for medium objects"""
-
     large_objects: Optional[MeanAveragePrecisionResult] = None
-    """Mean Average Precision results for large objects"""
 
     def __str__(self) -> str:
         """
-        Format the mAP results as a pretty string.
+        Format as a pretty string.
 
         Example:
             ```python
             print(map_result)
+            # MeanAveragePrecisionResult:
+            # Metric target: MetricTarget.BOXES
+            # Class agnostic: False
+            # mAP @ 50:95: 0.4674
+            # mAP @ 50:    0.5048
+            # mAP @ 75:    0.4796
+            # mAP scores: [0.50485  0.50377  0.50377  ...]
+            # IoU thresh: [0.5  0.55  0.6  ...]
+            # AP per class:
+            # 0: [0.67699  0.67699  0.67699  ...]
+            # ...
+            # Small objects: ...
+            # Medium objects: ...
+            # Large objects: ...
             ```
         """
 
         out_str = (
             f"{self.__class__.__name__}:\n"
-            f"iou_thresholds: {self.iou_thresholds}\n"
-            f"map50_95:  {self.map50_95:.4f}\n"
-            f"map50:     {self.map50:.4f}\n"
-            f"map75:     {self.map75:.4f}\n"
-            f"per_class_ap50_95:"
+            f"Metric target: {self.metric_target}\n"
+            f"Class agnostic: {self.is_class_agnostic}\n"
+            f"mAP @ 50:95: {self.map50_95:.4f}\n"
+            f"mAP @ 50:    {self.map50:.4f}\n"
+            f"mAP @ 75:    {self.map75:.4f}\n"
+            f"mAP scores: {self.mAP_scores}\n"
+            f"IoU thresh: {self.iou_thresholds}\n"
+            f"AP per class:\n"
         )
-
-        for class_id, ap in enumerate(self.per_class_ap50_95):
-            out_str += f"\n  {class_id}:  {ap}"
+        if self.ap_per_class.size == 0:
+            out_str += "  No results\n"
+        for class_id, ap_of_class in zip(self.matched_classes, self.ap_per_class):
+            out_str += f"  {class_id}: {ap_of_class}\n"
 
         indent = "  "
         if self.small_objects is not None:
-            indented_str = indent + str(self.small_objects).replace("\n", f"\n{indent}")
-            out_str += f"\nSmall objects:\n{indented_str}"
+            indented = indent + str(self.small_objects).replace("\n", f"\n{indent}")
+            out_str += f"\nSmall objects:\n{indented}"
         if self.medium_objects is not None:
-            indented_str = indent + str(self.medium_objects).replace(
-                "\n", f"\n{indent}"
-            )
-            out_str += f"\nMedium objects:\n{indented_str}"
+            indented = indent + str(self.medium_objects).replace("\n", f"\n{indent}")
+            out_str += f"\nMedium objects:\n{indented}"
         if self.large_objects is not None:
-            indented_str = indent + str(self.large_objects).replace("\n", f"\n{indent}")
-            out_str += f"\nLarge objects:\n{indented_str}"
+            indented = indent + str(self.large_objects).replace("\n", f"\n{indent}")
+            out_str += f"\nLarge objects:\n{indented}"
 
         return out_str
 
@@ -461,10 +534,11 @@ class MeanAveragePrecisionResult:
         import pandas as pd
 
         pandas_data = {
-            "mAP_50_95": self.map50_95,
-            "mAP_50": self.map50,
-            "mAP_75": self.map75,
+            "mAP@50:95": self.map50_95,
+            "mAP@50": self.map50,
+            "mAP@75": self.map75,
         }
+
         if self.small_objects is not None:
             small_objects_df = self.small_objects.to_pandas()
             for key, value in small_objects_df.items():
@@ -488,18 +562,18 @@ class MeanAveragePrecisionResult:
     def plot(self):
         """
         Plot the mAP results.
+
+        ![example_plot](\
+            https://media.roboflow.com/supervision-docs/metrics/mAP_plot_example.png\
+            ){ align=center width="800" }
         """
 
-        labels = ["mAP_50_95", "mAP_50", "mAP_75"]
+        labels = ["mAP@50:95", "mAP@50", "mAP@75"]
         values = [self.map50_95, self.map50, self.map75]
         colors = [LEGACY_COLOR_PALETTE[0]] * 3
 
         if self.small_objects is not None:
-            labels += [
-                "small_objects_mAP_50_95",
-                "small_objects_mAP_50",
-                "small_objects_mAP_75",
-            ]
+            labels += ["Small: mAP@50:95", "Small: mAP@50", "Small: mAP@75"]
             values += [
                 self.small_objects.map50_95,
                 self.small_objects.map50,
@@ -508,11 +582,7 @@ class MeanAveragePrecisionResult:
             colors += [LEGACY_COLOR_PALETTE[3]] * 3
 
         if self.medium_objects is not None:
-            labels += [
-                "medium_objects_mAP_50_95",
-                "medium_objects_mAP_50",
-                "medium_objects_mAP_75",
-            ]
+            labels += ["Medium: mAP@50:95", "Medium: mAP@50", "Medium: mAP@75"]
             values += [
                 self.medium_objects.map50_95,
                 self.medium_objects.map50,
@@ -521,11 +591,7 @@ class MeanAveragePrecisionResult:
             colors += [LEGACY_COLOR_PALETTE[2]] * 3
 
         if self.large_objects is not None:
-            labels += [
-                "large_objects_mAP_50_95",
-                "large_objects_mAP_50",
-                "large_objects_mAP_75",
-            ]
+            labels += ["Large: mAP@50:95", "Large: mAP@50", "Large: mAP@75"]
             values += [
                 self.large_objects.map50_95,
                 self.large_objects.map50,

supervision/metrics/mean_average_recall.py

@@ -0,0 +1,697 @@
+from __future__ import annotations
+
+from copy import deepcopy
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, List, Optional, Tuple, Union
+
+import numpy as np
+from matplotlib import pyplot as plt
+
+from supervision.config import ORIENTED_BOX_COORDINATES
+from supervision.detection.core import Detections
+from supervision.detection.utils import (
+    box_iou_batch,
+    mask_iou_batch,
+    oriented_box_iou_batch,
+)
+from supervision.draw.color import LEGACY_COLOR_PALETTE
+from supervision.metrics.core import Metric, MetricTarget
+from supervision.metrics.utils.object_size import (
+    ObjectSizeCategory,
+    get_detection_size_category,
+)
+from supervision.metrics.utils.utils import ensure_pandas_installed
+
+if TYPE_CHECKING:
+    import pandas as pd
+
+
+class MeanAverageRecall(Metric):
+    """
+    Mean Average Recall (mAR) measures how well the model detects
+    and retrieves relevant objects by averaging recall over multiple
+    IoU thresholds, classes and detection limits.
+
+    Intuitively, while Recall measures the ability to find all relevant
+    objects, mAR narrows down how many detections are considered for each
+    class. For example, mAR @ 100 considers the top 100 highest confidence
+    detections for each class. mAR @ 1 considers only the highest
+    confidence detection for each class.
+
+    Example:
+        ```python
+        import supervision as sv
+        from supervision.metrics import MeanAverageRecall
+
+        predictions = sv.Detections(...)
+        targets = sv.Detections(...)
+
+        map_metric = MeanAverageRecall()
+        map_result = map_metric.update(predictions, targets).compute()
+
+        print(mar_results.mar_at_100)
+        # 0.5241
+
+        print(mar_results)
+        # MeanAverageRecallResult:
+        # Metric target:    MetricTarget.BOXES
+        # mAR @ 1:    0.1362
+        # mAR @ 10:   0.4239
+        # mAR @ 100:  0.5241
+        # max detections: [1  10 100]
+        # IoU thresh:     [0.5  0.55  0.6  ...]
+        # mAR per class:
+        # 0: [0.78571  0.78571  0.78571  ...]
+        # ...
+        # Small objects: ...
+        # Medium objects: ...
+        # Large objects: ...
+
+        mar_results.plot()
+        ```
+
+    ![example_plot](\
+        https://media.roboflow.com/supervision-docs/metrics/mAR_plot_example.png\
+        ){ align=center width="800" }
+    """
+
+    def __init__(
+        self,
+        metric_target: MetricTarget = MetricTarget.BOXES,
+    ):
+        """
+        Initialize the Mean Average Recall metric.
+
+        Args:
+            metric_target (MetricTarget): The type of detection data to use.
+        """
+        self._metric_target = metric_target
+
+        self._predictions_list: List[Detections] = []
+        self._targets_list: List[Detections] = []
+
+        self.max_detections = np.array([1, 10, 100])
+
+    def reset(self) -> None:
+        """
+        Reset the metric to its initial state, clearing all stored data.
+        """
+        self._predictions_list = []
+        self._targets_list = []
+
+    def update(
+        self,
+        predictions: Union[Detections, List[Detections]],
+        targets: Union[Detections, List[Detections]],
+    ) -> MeanAverageRecall:
+        """
+        Add new predictions and targets to the metric, but do not compute the result.
+
+        Args:
+            predictions (Union[Detections, List[Detections]]): The predicted detections.
+            targets (Union[Detections, List[Detections]]): The target detections.
+
+        Returns:
+            (Recall): The updated metric instance.
+        """
+        if not isinstance(predictions, list):
+            predictions = [predictions]
+        if not isinstance(targets, list):
+            targets = [targets]
+
+        if len(predictions) != len(targets):
+            raise ValueError(
+                f"The number of predictions ({len(predictions)}) and"
+                f" targets ({len(targets)}) during the update must be the same."
+            )
+
+        self._predictions_list.extend(predictions)
+        self._targets_list.extend(targets)
+
+        return self
+
+    def compute(self) -> MeanAverageRecallResult:
+        """
+        Calculate the Mean Average Recall metric based on the stored predictions
+        and ground-truth, at different IoU thresholds and maximum detection counts.
+
+        Returns:
+            (MeanAverageRecallResult): The Mean Average Recall metric result.
+        """
+        result = self._compute(self._predictions_list, self._targets_list)
+
+        small_predictions, small_targets = self._filter_predictions_and_targets_by_size(
+            self._predictions_list, self._targets_list, ObjectSizeCategory.SMALL
+        )
+        result.small_objects = self._compute(small_predictions, small_targets)
+
+        medium_predictions, medium_targets = (
+            self._filter_predictions_and_targets_by_size(
+                self._predictions_list, self._targets_list, ObjectSizeCategory.MEDIUM
+            )
+        )
+        result.medium_objects = self._compute(medium_predictions, medium_targets)
+
+        large_predictions, large_targets = self._filter_predictions_and_targets_by_size(
+            self._predictions_list, self._targets_list, ObjectSizeCategory.LARGE
+        )
+        result.large_objects = self._compute(large_predictions, large_targets)
+
+        return result
+
+    def _compute(
+        self, predictions_list: List[Detections], targets_list: List[Detections]
+    ) -> MeanAverageRecallResult:
+        iou_thresholds = np.linspace(0.5, 0.95, 10)
+        stats = []
+
+        for predictions, targets in zip(predictions_list, targets_list):
+            prediction_contents = self._detections_content(predictions)
+            target_contents = self._detections_content(targets)
+
+            if len(targets) > 0:
+                if len(predictions) == 0:
+                    stats.append(
+                        (
+                            np.zeros((0, iou_thresholds.size), dtype=bool),
+                            np.zeros((0,), dtype=np.float32),
+                            np.zeros((0,), dtype=int),
+                            targets.class_id,
+                        )
+                    )
+
+                else:
+                    if self._metric_target == MetricTarget.BOXES:
+                        iou = box_iou_batch(target_contents, prediction_contents)
+                    elif self._metric_target == MetricTarget.MASKS:
+                        iou = mask_iou_batch(target_contents, prediction_contents)
+                    elif self._metric_target == MetricTarget.ORIENTED_BOUNDING_BOXES:
+                        iou = oriented_box_iou_batch(
+                            target_contents, prediction_contents
+                        )
+                    else:
+                        raise ValueError(
+                            "Unsupported metric target for IoU calculation"
+                        )
+
+                    matches = self._match_detection_batch(
+                        predictions.class_id, targets.class_id, iou, iou_thresholds
+                    )
+                    stats.append(
+                        (
+                            matches,
+                            predictions.confidence,
+                            predictions.class_id,
+                            targets.class_id,
+                        )
+                    )
+
+        if not stats:
+            return MeanAverageRecallResult(
+                metric_target=self._metric_target,
+                recall_scores=np.zeros(iou_thresholds.shape[0]),
+                recall_per_class=np.zeros((0, iou_thresholds.shape[0])),
+                max_detections=self.max_detections,
+                iou_thresholds=iou_thresholds,
+                matched_classes=np.array([], dtype=int),
+                small_objects=None,
+                medium_objects=None,
+                large_objects=None,
+            )
+
+        concatenated_stats = [np.concatenate(items, 0) for items in zip(*stats)]
+        recall_scores_per_k, recall_per_class, unique_classes = (
+            self._compute_average_recall_for_classes(*concatenated_stats)
+        )
+
+        return MeanAverageRecallResult(
+            metric_target=self._metric_target,
+            recall_scores=recall_scores_per_k,
+            recall_per_class=recall_per_class,
+            max_detections=self.max_detections,
+            iou_thresholds=iou_thresholds,
+            matched_classes=unique_classes,
+            small_objects=None,
+            medium_objects=None,
+            large_objects=None,
+        )
+
+    def _compute_average_recall_for_classes(
+        self,
+        matches: np.ndarray,
+        prediction_confidence: np.ndarray,
+        prediction_class_ids: np.ndarray,
+        true_class_ids: np.ndarray,
+    ) -> Tuple[np.ndarray, np.ndarray, np.ndarray]:
+        sorted_indices = np.argsort(-prediction_confidence)
+        matches = matches[sorted_indices]
+        prediction_class_ids = prediction_class_ids[sorted_indices]
+        unique_classes, class_counts = np.unique(true_class_ids, return_counts=True)
+
+        recalls_at_k = []
+        for max_detections in self.max_detections:
+            # Shape: PxTh,P,C,C -> CxThx3
+            confusion_matrix = self._compute_confusion_matrix(
+                matches,
+                prediction_class_ids,
+                unique_classes,
+                class_counts,
+                max_detections=max_detections,
+            )
+
+            # Shape: CxThx3 -> CxTh
+            recall_per_class = self._compute_recall(confusion_matrix)
+            recalls_at_k.append(recall_per_class)
+
+        # Shape: KxCxTh -> KxC
+        recalls_at_k = np.array(recalls_at_k)
+        average_recall_per_class = np.mean(recalls_at_k, axis=2)
+
+        # Shape: KxC -> K
+        recall_scores = np.mean(average_recall_per_class, axis=1)
+
+        return recall_scores, recall_per_class, unique_classes
+
+    @staticmethod
+    def _match_detection_batch(
+        predictions_classes: np.ndarray,
+        target_classes: np.ndarray,
+        iou: np.ndarray,
+        iou_thresholds: np.ndarray,
+    ) -> np.ndarray:
+        num_predictions, num_iou_levels = (
+            predictions_classes.shape[0],
+            iou_thresholds.shape[0],
+        )
+        correct = np.zeros((num_predictions, num_iou_levels), dtype=bool)
+        correct_class = target_classes[:, None] == predictions_classes
+
+        for i, iou_level in enumerate(iou_thresholds):
+            matched_indices = np.where((iou >= iou_level) & correct_class)
+
+            if matched_indices[0].shape[0]:
+                combined_indices = np.stack(matched_indices, axis=1)
+                iou_values = iou[matched_indices][:, None]
+                matches = np.hstack([combined_indices, iou_values])
+
+                if matched_indices[0].shape[0] > 1:
+                    matches = matches[matches[:, 2].argsort()[::-1]]
+                    matches = matches[np.unique(matches[:, 1], return_index=True)[1]]
+                    matches = matches[np.unique(matches[:, 0], return_index=True)[1]]
+
+                correct[matches[:, 1].astype(int), i] = True
+
+        return correct
+
+    @staticmethod
+    def _compute_confusion_matrix(
+        sorted_matches: np.ndarray,
+        sorted_prediction_class_ids: np.ndarray,
+        unique_classes: np.ndarray,
+        class_counts: np.ndarray,
+        max_detections: Optional[int] = None,
+    ) -> np.ndarray:
+        """
+        Compute the confusion matrix for each class and IoU threshold.
+
+        Assumes the matches and prediction_class_ids are sorted by confidence
+        in descending order.
+
+        Args:
+            sorted_matches: np.ndarray, bool, shape (P, Th), that is True
+                if the prediction is a true positive at the given IoU threshold.
+            sorted_prediction_class_ids: np.ndarray, int, shape (P,), containing
+                the class id for each prediction.
+            unique_classes: np.ndarray, int, shape (C,), containing the unique
+                class ids.
+            class_counts: np.ndarray, int, shape (C,), containing the number
+                of true instances for each class.
+            max_detections: Optional[int], the maximum number of detections to
+                consider for each class. Extra detections are considered false
+                positives. By default, all detections are considered.
+
+        Returns:
+            np.ndarray, shape (C, Th, 3), containing the true positives, false
+                positives, and false negatives for each class and IoU threshold.
+        """
+        num_thresholds = sorted_matches.shape[1]
+        num_classes = unique_classes.shape[0]
+
+        confusion_matrix = np.zeros((num_classes, num_thresholds, 3))
+        for class_idx, class_id in enumerate(unique_classes):
+            is_class = sorted_prediction_class_ids == class_id
+            num_true = class_counts[class_idx]
+            num_predictions = is_class.sum()
+
+            if num_predictions == 0:
+                true_positives = np.zeros(num_thresholds)
+                false_positives = np.zeros(num_thresholds)
+                false_negatives = np.full(num_thresholds, num_true)
+            elif num_true == 0:
+                true_positives = np.zeros(num_thresholds)
+                false_positives = np.full(num_thresholds, num_predictions)
+                false_negatives = np.zeros(num_thresholds)
+            else:
+                limited_matches = sorted_matches[is_class][slice(max_detections)]
+                true_positives = limited_matches.sum(0)
+
+                false_positives = (1 - limited_matches).sum(0)
+                false_negatives = num_true - true_positives
+                false_negatives = num_true - true_positives
+            confusion_matrix[class_idx] = np.stack(
+                [true_positives, false_positives, false_negatives], axis=1
+            )
+
+        return confusion_matrix
+
+    @staticmethod
+    def _compute_recall(confusion_matrix: np.ndarray) -> np.ndarray:
+        """
+        Broadcastable function, computing the recall from the confusion matrix.
+
+        Arguments:
+            confusion_matrix: np.ndarray, shape (N, ..., 3), where the last dimension
+                contains the true positives, false positives, and false negatives.
+
+        Returns:
+            np.ndarray, shape (N, ...), containing the recall for each element.
+        """
+        if not confusion_matrix.shape[-1] == 3:
+            raise ValueError(
+                f"Confusion matrix must have shape (..., 3), got "
+                f"{confusion_matrix.shape}"
+            )
+        true_positives = confusion_matrix[..., 0]
+        false_negatives = confusion_matrix[..., 2]
+
+        denominator = true_positives + false_negatives
+        recall = np.where(denominator == 0, 0, true_positives / denominator)
+
+        return recall
+
+    def _detections_content(self, detections: Detections) -> np.ndarray:
+        """Return boxes, masks or oriented bounding boxes from detections."""
+        if self._metric_target == MetricTarget.BOXES:
+            return detections.xyxy
+        if self._metric_target == MetricTarget.MASKS:
+            return (
+                detections.mask
+                if detections.mask is not None
+                else self._make_empty_content()
+            )
+        if self._metric_target == MetricTarget.ORIENTED_BOUNDING_BOXES:
+            obb = detections.data.get(ORIENTED_BOX_COORDINATES)
+            if obb is not None and len(obb) > 0:
+                return np.array(obb, dtype=np.float32)
+            return self._make_empty_content()
+        raise ValueError(f"Invalid metric target: {self._metric_target}")
+
+    def _make_empty_content(self) -> np.ndarray:
+        if self._metric_target == MetricTarget.BOXES:
+            return np.empty((0, 4), dtype=np.float32)
+        if self._metric_target == MetricTarget.MASKS:
+            return np.empty((0, 0, 0), dtype=bool)
+        if self._metric_target == MetricTarget.ORIENTED_BOUNDING_BOXES:
+            return np.empty((0, 4, 2), dtype=np.float32)
+        raise ValueError(f"Invalid metric target: {self._metric_target}")
+
+    def _filter_detections_by_size(
+        self, detections: Detections, size_category: ObjectSizeCategory
+    ) -> Detections:
+        """Return a copy of detections with contents filtered by object size."""
+        new_detections = deepcopy(detections)
+        if detections.is_empty() or size_category == ObjectSizeCategory.ANY:
+            return new_detections
+
+        sizes = get_detection_size_category(new_detections, self._metric_target)
+        size_mask = sizes == size_category.value
+
+        new_detections.xyxy = new_detections.xyxy[size_mask]
+        if new_detections.mask is not None:
+            new_detections.mask = new_detections.mask[size_mask]
+        if new_detections.class_id is not None:
+            new_detections.class_id = new_detections.class_id[size_mask]
+        if new_detections.confidence is not None:
+            new_detections.confidence = new_detections.confidence[size_mask]
+        if new_detections.tracker_id is not None:
+            new_detections.tracker_id = new_detections.tracker_id[size_mask]
+        if new_detections.data is not None:
+            for key, value in new_detections.data.items():
+                new_detections.data[key] = np.array(value)[size_mask]
+
+        return new_detections
+
+    def _filter_predictions_and_targets_by_size(
+        self,
+        predictions_list: List[Detections],
+        targets_list: List[Detections],
+        size_category: ObjectSizeCategory,
+    ) -> Tuple[List[Detections], List[Detections]]:
+        new_predictions_list = []
+        new_targets_list = []
+        for predictions, targets in zip(predictions_list, targets_list):
+            new_predictions_list.append(
+                self._filter_detections_by_size(predictions, size_category)
+            )
+            new_targets_list.append(
+                self._filter_detections_by_size(targets, size_category)
+            )
+        return new_predictions_list, new_targets_list
+
+
+@dataclass
+class MeanAverageRecallResult:
+    # """
+    # The results of the recall metric calculation.
+
+    # Defaults to `0` if no detections or targets were provided.
+
+    # Attributes:
+    #     metric_target (MetricTarget): the type of data used for the metric -
+    #         boxes, masks or oriented bounding boxes.
+    #     averaging_method (AveragingMethod): the averaging method used to compute the
+    #         recall. Determines how the recall is aggregated across classes.
+    #     recall_at_50 (float): the recall at IoU threshold of `0.5`.
+    #     recall_at_75 (float): the recall at IoU threshold of `0.75`.
+    #     recall_scores (np.ndarray): the recall scores at each IoU threshold.
+    #         Shape: `(num_iou_thresholds,)`
+    #     recall_per_class (np.ndarray): the recall scores per class and IoU threshold.
+    #         Shape: `(num_target_classes, num_iou_thresholds)`
+    #     iou_thresholds (np.ndarray): the IoU thresholds used in the calculations.
+    #     matched_classes (np.ndarray): the class IDs of all matched classes.
+    #         Corresponds to the rows of `recall_per_class`.
+    #     small_objects (Optional[RecallResult]): the Recall metric results
+    #         for small objects.
+    #     medium_objects (Optional[RecallResult]): the Recall metric results
+    #         for medium objects.
+    #     large_objects (Optional[RecallResult]): the Recall metric results
+    #         for large objects.
+    # """
+    """
+    The results of the Mean Average Recall metric calculation.
+
+    Defaults to `0` if no detections or targets were provided.
+
+    Attributes:
+        metric_target (MetricTarget): the type of data used for the metric -
+            boxes, masks or oriented bounding boxes.
+        mAR_at_1 (float): the Mean Average Recall, when considering only the top
+            highest confidence detection for each class.
+        mAR_at_10 (float): the Mean Average Recall, when considering top 10
+            highest confidence detections for each class.
+        mAR_at_100 (float): the Mean Average Recall, when considering top 100
+            highest confidence detections for each class.
+        recall_per_class (np.ndarray): the recall scores per class and IoU threshold.
+            Shape: `(num_target_classes, num_iou_thresholds)`
+        max_detections (np.ndarray): the array with maximum number of detections
+            considered.
+        iou_thresholds (np.ndarray): the IoU thresholds used in the calculations.
+        matched_classes (np.ndarray): the class IDs of all matched classes.
+            Corresponds to the rows of `recall_per_class`.
+        small_objects (Optional[MeanAverageRecallResult]): the Mean Average Recall
+            metric results for small objects (area < 32²).
+        medium_objects (Optional[MeanAverageRecallResult]): the Mean Average Recall
+            metric results for medium objects (32² ≤ area < 96²).
+        large_objects (Optional[MeanAverageRecallResult]): the Mean Average Recall
+            metric results for large objects (area ≥ 96²).
+    """
+
+    metric_target: MetricTarget
+
+    @property
+    def mAR_at_1(self) -> float:
+        return self.recall_scores[0]
+
+    @property
+    def mAR_at_10(self) -> float:
+        return self.recall_scores[1]
+
+    @property
+    def mAR_at_100(self) -> float:
+        return self.recall_scores[2]
+
+    recall_scores: np.ndarray
+    recall_per_class: np.ndarray
+    max_detections: np.ndarray
+    iou_thresholds: np.ndarray
+    matched_classes: np.ndarray
+
+    small_objects: Optional[MeanAverageRecallResult]
+    medium_objects: Optional[MeanAverageRecallResult]
+    large_objects: Optional[MeanAverageRecallResult]
+
+    def __str__(self) -> str:
+        """
+        Format as a pretty string.
+
+        Example:
+            ```python
+            # MeanAverageRecallResult:
+            # Metric target:    MetricTarget.BOXES
+            # mAR @ 1:    0.1362
+            # mAR @ 10:   0.4239
+            # mAR @ 100:  0.5241
+            # max detections: [1  10 100]
+            # IoU thresh:     [0.5  0.55  0.6  ...]
+            # mAR per class:
+            # 0: [0.78571  0.78571  0.78571  ...]
+            # ...
+            # Small objects: ...
+            # Medium objects: ...
+            # Large objects: ...
+            ```
+        """
+        out_str = (
+            f"{self.__class__.__name__}:\n"
+            f"Metric target:  {self.metric_target}\n"
+            f"mAR @ 1:    {self.mAR_at_1:.4f}\n"
+            f"mAR @ 10:   {self.mAR_at_10:.4f}\n"
+            f"mAR @ 100:  {self.mAR_at_100:.4f}\n"
+            f"max detections: {self.max_detections}\n"
+            f"IoU thresh:     {self.iou_thresholds}\n"
+            f"mAR per class:\n"
+        )
+        if self.recall_per_class.size == 0:
+            out_str += "  No results\n"
+        for class_id, recall_of_class in zip(
+            self.matched_classes, self.recall_per_class
+        ):
+            out_str += f"  {class_id}: {recall_of_class}\n"
+
+        indent = "  "
+        if self.small_objects is not None:
+            indented = indent + str(self.small_objects).replace("\n", f"\n{indent}")
+            out_str += f"\nSmall objects:\n{indented}"
+        if self.medium_objects is not None:
+            indented = indent + str(self.medium_objects).replace("\n", f"\n{indent}")
+            out_str += f"\nMedium objects:\n{indented}"
+        if self.large_objects is not None:
+            indented = indent + str(self.large_objects).replace("\n", f"\n{indent}")
+            out_str += f"\nLarge objects:\n{indented}"
+
+        return out_str
+
+    def to_pandas(self) -> "pd.DataFrame":
+        """
+        Convert the result to a pandas DataFrame.
+
+        Returns:
+            (pd.DataFrame): The result as a DataFrame.
+        """
+        ensure_pandas_installed()
+        import pandas as pd
+
+        pandas_data = {
+            "mAR @ 1": self.mAR_at_1,
+            "mAR @ 10": self.mAR_at_10,
+            "mAR @ 100": self.mAR_at_100,
+        }
+
+        if self.small_objects is not None:
+            small_objects_df = self.small_objects.to_pandas()
+            for key, value in small_objects_df.items():
+                pandas_data[f"small_objects_{key}"] = value
+        if self.medium_objects is not None:
+            medium_objects_df = self.medium_objects.to_pandas()
+            for key, value in medium_objects_df.items():
+                pandas_data[f"medium_objects_{key}"] = value
+        if self.large_objects is not None:
+            large_objects_df = self.large_objects.to_pandas()
+            for key, value in large_objects_df.items():
+                pandas_data[f"large_objects_{key}"] = value
+
+        return pd.DataFrame(pandas_data, index=[0])
+
+    def plot(self):
+        """
+        Plot the Mean Average Recall results.
+
+        ![example_plot](\
+            https://media.roboflow.com/supervision-docs/metrics/mAR_plot_example.png\
+            ){ align=center width="800" }
+        """
+        labels = ["mAR @ 1", "mAR @ 10", "mAR @ 100"]
+        values = [self.mAR_at_1, self.mAR_at_10, self.mAR_at_100]
+        colors = [LEGACY_COLOR_PALETTE[0]] * 3
+
+        if self.small_objects is not None:
+            small_objects = self.small_objects
+            labels += ["Small: mAR @ 1", "Small: mAR @ 10", "Small: mAR @ 100"]
+            values += [
+                small_objects.mAR_at_1,
+                small_objects.mAR_at_10,
+                small_objects.mAR_at_100,
+            ]
+            colors += [LEGACY_COLOR_PALETTE[3]] * 3
+
+        if self.medium_objects is not None:
+            medium_objects = self.medium_objects
+            labels += ["Medium: mAR @ 1", "Medium: mAR @ 10", "Medium: mAR @ 100"]
+            values += [
+                medium_objects.mAR_at_1,
+                medium_objects.mAR_at_10,
+                medium_objects.mAR_at_100,
+            ]
+            colors += [LEGACY_COLOR_PALETTE[2]] * 3
+
+        if self.large_objects is not None:
+            large_objects = self.large_objects
+            labels += ["Large: mAR @ 1", "Large: mAR @ 10", "Large: mAR @ 100"]
+            values += [
+                large_objects.mAR_at_1,
+                large_objects.mAR_at_10,
+                large_objects.mAR_at_100,
+            ]
+            colors += [LEGACY_COLOR_PALETTE[4]] * 3
+
+        plt.rcParams["font.family"] = "monospace"
+
+        _, ax = plt.subplots(figsize=(10, 6))
+        ax.set_ylim(0, 1)
+        ax.set_ylabel("Value", fontweight="bold")
+        title = (
+            f"Mean Average Recall, by Object Size"
+            f"\n(target: {self.metric_target.value})"
+        )
+        ax.set_title(title, fontweight="bold")
+
+        x_positions = range(len(labels))
+        bars = ax.bar(x_positions, values, color=colors, align="center")
+
+        ax.set_xticks(x_positions)
+        ax.set_xticklabels(labels, rotation=45, ha="right")
+
+        for bar in bars:
+            y_value = bar.get_height()
+            ax.text(
+                bar.get_x() + bar.get_width() / 2,
+                y_value + 0.02,
+                f"{y_value:.2f}",
+                ha="center",
+                va="bottom",
+            )
+
+        plt.rcParams["font.family"] = "sans-serif"
+
+        plt.tight_layout()
+        plt.show()

supervision/metrics/precision.py

@@ -0,0 +1,653 @@
+from __future__ import annotations
+
+from copy import deepcopy
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, List, Optional, Tuple, Union
+
+import numpy as np
+from matplotlib import pyplot as plt
+
+from supervision.config import ORIENTED_BOX_COORDINATES
+from supervision.detection.core import Detections
+from supervision.detection.utils import (
+    box_iou_batch,
+    mask_iou_batch,
+    oriented_box_iou_batch,
+)
+from supervision.draw.color import LEGACY_COLOR_PALETTE
+from supervision.metrics.core import AveragingMethod, Metric, MetricTarget
+from supervision.metrics.utils.object_size import (
+    ObjectSizeCategory,
+    get_detection_size_category,
+)
+from supervision.metrics.utils.utils import ensure_pandas_installed
+
+if TYPE_CHECKING:
+    import pandas as pd
+
+
+class Precision(Metric):
+    """
+    Precision is a metric used to evaluate object detection models. It is the ratio of
+    true positive detections to the total number of predicted detections. We calculate
+    it at different IoU thresholds.
+
+    In simple terms, Precision is a measure of a model's accuracy, calculated as:
+
+    `Precision = TP / (TP + FP)`
+
+    Here, `TP` is the number of true positives (correct detections), and `FP` is the
+    number of false positive detections (detected, but incorrectly).
+
+    Example:
+        ```python
+        import supervision as sv
+        from supervision.metrics import Precision
+
+        predictions = sv.Detections(...)
+        targets = sv.Detections(...)
+
+        precision_metric = Precision()
+        precision_result = precision_metric.update(predictions, targets).compute()
+
+        print(precision_result.precision_at_50)
+        # 0.8099
+
+        print(precision_result)
+        # PrecisionResult:
+        # Metric target:  MetricTarget.BOXES
+        # Averaging method: AveragingMethod.WEIGHTED
+        # P @ 50:     0.8099
+        # P @ 75:     0.7969
+        # P @ thresh: [0.80992  0.80905  0.80905  ...]
+        # IoU thresh: [0.5  0.55  0.6  ...]
+        # Precision per class:
+        # 0: [0.64706  0.64706  0.64706   ...]
+        # ...
+        # Small objects: ...
+        # Medium objects: ...
+        # Large objects: ...
+
+        print(precision_result.small_objects.precision_at_50)
+        ```
+
+    ![example_plot](\
+        https://media.roboflow.com/supervision-docs/metrics/precision_plot_example.png\
+        ){ align=center width="800" }
+    """
+
+    def __init__(
+        self,
+        metric_target: MetricTarget = MetricTarget.BOXES,
+        averaging_method: AveragingMethod = AveragingMethod.WEIGHTED,
+    ):
+        """
+        Initialize the Precision metric.
+
+        Args:
+            metric_target (MetricTarget): The type of detection data to use.
+            averaging_method (AveragingMethod): The averaging method used to compute the
+                precision. Determines how the precision is aggregated across classes.
+        """
+        self._metric_target = metric_target
+        self.averaging_method = averaging_method
+
+        self._predictions_list: List[Detections] = []
+        self._targets_list: List[Detections] = []
+
+    def reset(self) -> None:
+        """
+        Reset the metric to its initial state, clearing all stored data.
+        """
+        self._predictions_list = []
+        self._targets_list = []
+
+    def update(
+        self,
+        predictions: Union[Detections, List[Detections]],
+        targets: Union[Detections, List[Detections]],
+    ) -> Precision:
+        """
+        Add new predictions and targets to the metric, but do not compute the result.
+
+        Args:
+            predictions (Union[Detections, List[Detections]]): The predicted detections.
+            targets (Union[Detections, List[Detections]]): The target detections.
+
+        Returns:
+            (Precision): The updated metric instance.
+        """
+        if not isinstance(predictions, list):
+            predictions = [predictions]
+        if not isinstance(targets, list):
+            targets = [targets]
+
+        if len(predictions) != len(targets):
+            raise ValueError(
+                f"The number of predictions ({len(predictions)}) and"
+                f" targets ({len(targets)}) during the update must be the same."
+            )
+
+        self._predictions_list.extend(predictions)
+        self._targets_list.extend(targets)
+
+        return self
+
+    def compute(self) -> PrecisionResult:
+        """
+        Calculate the precision metric based on the stored predictions and ground-truth
+        data, at different IoU thresholds.
+
+        Returns:
+            (PrecisionResult): The precision metric result.
+        """
+        result = self._compute(self._predictions_list, self._targets_list)
+
+        small_predictions, small_targets = self._filter_predictions_and_targets_by_size(
+            self._predictions_list, self._targets_list, ObjectSizeCategory.SMALL
+        )
+        result.small_objects = self._compute(small_predictions, small_targets)
+
+        medium_predictions, medium_targets = (
+            self._filter_predictions_and_targets_by_size(
+                self._predictions_list, self._targets_list, ObjectSizeCategory.MEDIUM
+            )
+        )
+        result.medium_objects = self._compute(medium_predictions, medium_targets)
+
+        large_predictions, large_targets = self._filter_predictions_and_targets_by_size(
+            self._predictions_list, self._targets_list, ObjectSizeCategory.LARGE
+        )
+        result.large_objects = self._compute(large_predictions, large_targets)
+
+        return result
+
+    def _compute(
+        self, predictions_list: List[Detections], targets_list: List[Detections]
+    ) -> PrecisionResult:
+        iou_thresholds = np.linspace(0.5, 0.95, 10)
+        stats = []
+
+        for predictions, targets in zip(predictions_list, targets_list):
+            prediction_contents = self._detections_content(predictions)
+            target_contents = self._detections_content(targets)
+
+            if len(targets) > 0:
+                if len(predictions) == 0:
+                    stats.append(
+                        (
+                            np.zeros((0, iou_thresholds.size), dtype=bool),
+                            np.zeros((0,), dtype=np.float32),
+                            np.zeros((0,), dtype=int),
+                            targets.class_id,
+                        )
+                    )
+
+                else:
+                    if self._metric_target == MetricTarget.BOXES:
+                        iou = box_iou_batch(target_contents, prediction_contents)
+                    elif self._metric_target == MetricTarget.MASKS:
+                        iou = mask_iou_batch(target_contents, prediction_contents)
+                    elif self._metric_target == MetricTarget.ORIENTED_BOUNDING_BOXES:
+                        iou = oriented_box_iou_batch(
+                            target_contents, prediction_contents
+                        )
+                    else:
+                        raise ValueError(
+                            "Unsupported metric target for IoU calculation"
+                        )
+
+                    matches = self._match_detection_batch(
+                        predictions.class_id, targets.class_id, iou, iou_thresholds
+                    )
+                    stats.append(
+                        (
+                            matches,
+                            predictions.confidence,
+                            predictions.class_id,
+                            targets.class_id,
+                        )
+                    )
+
+        if not stats:
+            return PrecisionResult(
+                metric_target=self._metric_target,
+                averaging_method=self.averaging_method,
+                precision_scores=np.zeros(iou_thresholds.shape[0]),
+                precision_per_class=np.zeros((0, iou_thresholds.shape[0])),
+                iou_thresholds=iou_thresholds,
+                matched_classes=np.array([], dtype=int),
+                small_objects=None,
+                medium_objects=None,
+                large_objects=None,
+            )
+
+        concatenated_stats = [np.concatenate(items, 0) for items in zip(*stats)]
+        precision_scores, precision_per_class, unique_classes = (
+            self._compute_precision_for_classes(*concatenated_stats)
+        )
+
+        return PrecisionResult(
+            metric_target=self._metric_target,
+            averaging_method=self.averaging_method,
+            precision_scores=precision_scores,
+            precision_per_class=precision_per_class,
+            iou_thresholds=iou_thresholds,
+            matched_classes=unique_classes,
+            small_objects=None,
+            medium_objects=None,
+            large_objects=None,
+        )
+
+    def _compute_precision_for_classes(
+        self,
+        matches: np.ndarray,
+        prediction_confidence: np.ndarray,
+        prediction_class_ids: np.ndarray,
+        true_class_ids: np.ndarray,
+    ) -> Tuple[np.ndarray, np.ndarray, np.ndarray]:
+        sorted_indices = np.argsort(-prediction_confidence)
+        matches = matches[sorted_indices]
+        prediction_class_ids = prediction_class_ids[sorted_indices]
+        unique_classes, class_counts = np.unique(true_class_ids, return_counts=True)
+
+        # Shape: PxTh,P,C,C -> CxThx3
+        confusion_matrix = self._compute_confusion_matrix(
+            matches, prediction_class_ids, unique_classes, class_counts
+        )
+
+        # Shape: CxThx3 -> CxTh
+        precision_per_class = self._compute_precision(confusion_matrix)
+
+        # Shape: CxTh -> Th
+        if self.averaging_method == AveragingMethod.MACRO:
+            precision_scores = np.mean(precision_per_class, axis=0)
+        elif self.averaging_method == AveragingMethod.MICRO:
+            confusion_matrix_merged = confusion_matrix.sum(0)
+            precision_scores = self._compute_precision(confusion_matrix_merged)
+        elif self.averaging_method == AveragingMethod.WEIGHTED:
+            class_counts = class_counts.astype(np.float32)
+            precision_scores = np.average(
+                precision_per_class, axis=0, weights=class_counts
+            )
+
+        return precision_scores, precision_per_class, unique_classes
+
+    @staticmethod
+    def _match_detection_batch(
+        predictions_classes: np.ndarray,
+        target_classes: np.ndarray,
+        iou: np.ndarray,
+        iou_thresholds: np.ndarray,
+    ) -> np.ndarray:
+        num_predictions, num_iou_levels = (
+            predictions_classes.shape[0],
+            iou_thresholds.shape[0],
+        )
+        correct = np.zeros((num_predictions, num_iou_levels), dtype=bool)
+        correct_class = target_classes[:, None] == predictions_classes
+
+        for i, iou_level in enumerate(iou_thresholds):
+            matched_indices = np.where((iou >= iou_level) & correct_class)
+
+            if matched_indices[0].shape[0]:
+                combined_indices = np.stack(matched_indices, axis=1)
+                iou_values = iou[matched_indices][:, None]
+                matches = np.hstack([combined_indices, iou_values])
+
+                if matched_indices[0].shape[0] > 1:
+                    matches = matches[matches[:, 2].argsort()[::-1]]
+                    matches = matches[np.unique(matches[:, 1], return_index=True)[1]]
+                    matches = matches[np.unique(matches[:, 0], return_index=True)[1]]
+
+                correct[matches[:, 1].astype(int), i] = True
+
+        return correct
+
+    @staticmethod
+    def _compute_confusion_matrix(
+        sorted_matches: np.ndarray,
+        sorted_prediction_class_ids: np.ndarray,
+        unique_classes: np.ndarray,
+        class_counts: np.ndarray,
+    ) -> np.ndarray:
+        """
+        Compute the confusion matrix for each class and IoU threshold.
+
+        Assumes the matches and prediction_class_ids are sorted by confidence
+        in descending order.
+
+        Arguments:
+            sorted_matches: np.ndarray, bool, shape (P, Th), that is True
+                if the prediction is a true positive at the given IoU threshold.
+            sorted_prediction_class_ids: np.ndarray, int, shape (P,), containing
+                the class id for each prediction.
+            unique_classes: np.ndarray, int, shape (C,), containing the unique
+                class ids.
+            class_counts: np.ndarray, int, shape (C,), containing the number
+                of true instances for each class.
+
+        Returns:
+            np.ndarray, shape (C, Th, 3), containing the true positives, false
+                positives, and false negatives for each class and IoU threshold.
+        """
+
+        num_thresholds = sorted_matches.shape[1]
+        num_classes = unique_classes.shape[0]
+
+        confusion_matrix = np.zeros((num_classes, num_thresholds, 3))
+        for class_idx, class_id in enumerate(unique_classes):
+            is_class = sorted_prediction_class_ids == class_id
+            num_true = class_counts[class_idx]
+            num_predictions = is_class.sum()
+
+            if num_predictions == 0:
+                true_positives = np.zeros(num_thresholds)
+                false_positives = np.zeros(num_thresholds)
+                false_negatives = np.full(num_thresholds, num_true)
+            elif num_true == 0:
+                true_positives = np.zeros(num_thresholds)
+                false_positives = np.full(num_thresholds, num_predictions)
+                false_negatives = np.zeros(num_thresholds)
+            else:
+                true_positives = sorted_matches[is_class].sum(0)
+                false_positives = (1 - sorted_matches[is_class]).sum(0)
+                false_negatives = num_true - true_positives
+            confusion_matrix[class_idx] = np.stack(
+                [true_positives, false_positives, false_negatives], axis=1
+            )
+
+        return confusion_matrix
+
+    @staticmethod
+    def _compute_precision(confusion_matrix: np.ndarray) -> np.ndarray:
+        """
+        Broadcastable function, computing the precision from the confusion matrix.
+
+        Arguments:
+            confusion_matrix: np.ndarray, shape (N, ..., 3), where the last dimension
+                contains the true positives, false positives, and false negatives.
+
+        Returns:
+            np.ndarray, shape (N, ...), containing the precision for each element.
+        """
+        if not confusion_matrix.shape[-1] == 3:
+            raise ValueError(
+                f"Confusion matrix must have shape (..., 3), got "
+                f"{confusion_matrix.shape}"
+            )
+        true_positives = confusion_matrix[..., 0]
+        false_positives = confusion_matrix[..., 1]
+
+        denominator = true_positives + false_positives
+        precision = np.where(denominator == 0, 0, true_positives / denominator)
+
+        return precision
+
+    def _detections_content(self, detections: Detections) -> np.ndarray:
+        """Return boxes, masks or oriented bounding boxes from detections."""
+        if self._metric_target == MetricTarget.BOXES:
+            return detections.xyxy
+        if self._metric_target == MetricTarget.MASKS:
+            return (
+                detections.mask
+                if detections.mask is not None
+                else self._make_empty_content()
+            )
+        if self._metric_target == MetricTarget.ORIENTED_BOUNDING_BOXES:
+            obb = detections.data.get(ORIENTED_BOX_COORDINATES)
+            if obb is not None and len(obb) > 0:
+                return np.array(obb, dtype=np.float32)
+            return self._make_empty_content()
+        raise ValueError(f"Invalid metric target: {self._metric_target}")
+
+    def _make_empty_content(self) -> np.ndarray:
+        if self._metric_target == MetricTarget.BOXES:
+            return np.empty((0, 4), dtype=np.float32)
+        if self._metric_target == MetricTarget.MASKS:
+            return np.empty((0, 0, 0), dtype=bool)
+        if self._metric_target == MetricTarget.ORIENTED_BOUNDING_BOXES:
+            return np.empty((0, 4, 2), dtype=np.float32)
+        raise ValueError(f"Invalid metric target: {self._metric_target}")
+
+    def _filter_detections_by_size(
+        self, detections: Detections, size_category: ObjectSizeCategory
+    ) -> Detections:
+        """Return a copy of detections with contents filtered by object size."""
+        new_detections = deepcopy(detections)
+        if detections.is_empty() or size_category == ObjectSizeCategory.ANY:
+            return new_detections
+
+        sizes = get_detection_size_category(new_detections, self._metric_target)
+        size_mask = sizes == size_category.value
+
+        new_detections.xyxy = new_detections.xyxy[size_mask]
+        if new_detections.mask is not None:
+            new_detections.mask = new_detections.mask[size_mask]
+        if new_detections.class_id is not None:
+            new_detections.class_id = new_detections.class_id[size_mask]
+        if new_detections.confidence is not None:
+            new_detections.confidence = new_detections.confidence[size_mask]
+        if new_detections.tracker_id is not None:
+            new_detections.tracker_id = new_detections.tracker_id[size_mask]
+        if new_detections.data is not None:
+            for key, value in new_detections.data.items():
+                new_detections.data[key] = np.array(value)[size_mask]
+
+        return new_detections
+
+    def _filter_predictions_and_targets_by_size(
+        self,
+        predictions_list: List[Detections],
+        targets_list: List[Detections],
+        size_category: ObjectSizeCategory,
+    ) -> Tuple[List[Detections], List[Detections]]:
+        """
+        Filter predictions and targets by object size category.
+        """
+        new_predictions_list = []
+        new_targets_list = []
+        for predictions, targets in zip(predictions_list, targets_list):
+            new_predictions_list.append(
+                self._filter_detections_by_size(predictions, size_category)
+            )
+            new_targets_list.append(
+                self._filter_detections_by_size(targets, size_category)
+            )
+        return new_predictions_list, new_targets_list
+
+
+@dataclass
+class PrecisionResult:
+    """
+    The results of the precision metric calculation.
+
+    Defaults to `0` if no detections or targets were provided.
+
+    Attributes:
+        metric_target (MetricTarget): the type of data used for the metric -
+            boxes, masks or oriented bounding boxes.
+        averaging_method (AveragingMethod): the averaging method used to compute the
+            precision. Determines how the precision is aggregated across classes.
+        precision_at_50 (float): the precision at IoU threshold of `0.5`.
+        precision_at_75 (float): the precision at IoU threshold of `0.75`.
+        precision_scores (np.ndarray): the precision scores at each IoU threshold.
+            Shape: `(num_iou_thresholds,)`
+        precision_per_class (np.ndarray): the precision scores per class and
+            IoU threshold. Shape: `(num_target_classes, num_iou_thresholds)`
+        iou_thresholds (np.ndarray): the IoU thresholds used in the calculations.
+        matched_classes (np.ndarray): the class IDs of all matched classes.
+            Corresponds to the rows of `precision_per_class`.
+        small_objects (Optional[PrecisionResult]): the Precision metric results
+            for small objects (area < 32²).
+        medium_objects (Optional[PrecisionResult]): the Precision metric results
+            for medium objects (32² ≤ area < 96²).
+        large_objects (Optional[PrecisionResult]): the Precision metric results
+            for large objects (area ≥ 96²).
+    """
+
+    metric_target: MetricTarget
+    averaging_method: AveragingMethod
+
+    @property
+    def precision_at_50(self) -> float:
+        return self.precision_scores[0]
+
+    @property
+    def precision_at_75(self) -> float:
+        return self.precision_scores[5]
+
+    precision_scores: np.ndarray
+    precision_per_class: np.ndarray
+    iou_thresholds: np.ndarray
+    matched_classes: np.ndarray
+
+    small_objects: Optional[PrecisionResult]
+    medium_objects: Optional[PrecisionResult]
+    large_objects: Optional[PrecisionResult]
+
+    def __str__(self) -> str:
+        """
+        Format as a pretty string.
+
+        Example:
+            ```python
+            print(precision_result)
+            # PrecisionResult:
+            # Metric target:  MetricTarget.BOXES
+            # Averaging method: AveragingMethod.WEIGHTED
+            # P @ 50:     0.8099
+            # P @ 75:     0.7969
+            # P @ thresh: [0.80992  0.80905  0.80905  ...]
+            # IoU thresh: [0.5  0.55  0.6  ...]
+            # Precision per class:
+            # 0: [0.64706  0.64706  0.64706   ...]
+            # ...
+            # Small objects: ...
+            # Medium objects: ...
+            # Large objects: ...
+            ```
+        """
+        out_str = (
+            f"{self.__class__.__name__}:\n"
+            f"Metric target:    {self.metric_target}\n"
+            f"Averaging method: {self.averaging_method}\n"
+            f"P @ 50:     {self.precision_at_50:.4f}\n"
+            f"P @ 75:     {self.precision_at_75:.4f}\n"
+            f"P @ thresh: {self.precision_scores}\n"
+            f"IoU thresh: {self.iou_thresholds}\n"
+            f"Precision per class:\n"
+        )
+        if self.precision_per_class.size == 0:
+            out_str += "  No results\n"
+        for class_id, precision_of_class in zip(
+            self.matched_classes, self.precision_per_class
+        ):
+            out_str += f"  {class_id}: {precision_of_class}\n"
+
+        indent = "  "
+        if self.small_objects is not None:
+            indented = indent + str(self.small_objects).replace("\n", f"\n{indent}")
+            out_str += f"\nSmall objects:\n{indented}"
+        if self.medium_objects is not None:
+            indented = indent + str(self.medium_objects).replace("\n", f"\n{indent}")
+            out_str += f"\nMedium objects:\n{indented}"
+        if self.large_objects is not None:
+            indented = indent + str(self.large_objects).replace("\n", f"\n{indent}")
+            out_str += f"\nLarge objects:\n{indented}"
+
+        return out_str
+
+    def to_pandas(self) -> "pd.DataFrame":
+        """
+        Convert the result to a pandas DataFrame.
+
+        Returns:
+            (pd.DataFrame): The result as a DataFrame.
+        """
+        ensure_pandas_installed()
+        import pandas as pd
+
+        pandas_data = {
+            "P@50": self.precision_at_50,
+            "P@75": self.precision_at_75,
+        }
+
+        if self.small_objects is not None:
+            small_objects_df = self.small_objects.to_pandas()
+            for key, value in small_objects_df.items():
+                pandas_data[f"small_objects_{key}"] = value
+        if self.medium_objects is not None:
+            medium_objects_df = self.medium_objects.to_pandas()
+            for key, value in medium_objects_df.items():
+                pandas_data[f"medium_objects_{key}"] = value
+        if self.large_objects is not None:
+            large_objects_df = self.large_objects.to_pandas()
+            for key, value in large_objects_df.items():
+                pandas_data[f"large_objects_{key}"] = value
+
+        return pd.DataFrame(pandas_data, index=[0])
+
+    def plot(self):
+        """
+        Plot the precision results.
+
+        ![example_plot](\
+            https://media.roboflow.com/supervision-docs/metrics/precision_plot_example.png\
+            ){ align=center width="800" }
+        """
+
+        labels = ["Precision@50", "Precision@75"]
+        values = [self.precision_at_50, self.precision_at_75]
+        colors = [LEGACY_COLOR_PALETTE[0]] * 2
+
+        if self.small_objects is not None:
+            small_objects = self.small_objects
+            labels += ["Small: P@50", "Small: P@75"]
+            values += [small_objects.precision_at_50, small_objects.precision_at_75]
+            colors += [LEGACY_COLOR_PALETTE[3]] * 2
+
+        if self.medium_objects is not None:
+            medium_objects = self.medium_objects
+            labels += ["Medium: P@50", "Medium: P@75"]
+            values += [medium_objects.precision_at_50, medium_objects.precision_at_75]
+            colors += [LEGACY_COLOR_PALETTE[2]] * 2
+
+        if self.large_objects is not None:
+            large_objects = self.large_objects
+            labels += ["Large: P@50", "Large: P@75"]
+            values += [large_objects.precision_at_50, large_objects.precision_at_75]
+            colors += [LEGACY_COLOR_PALETTE[4]] * 2
+
+        plt.rcParams["font.family"] = "monospace"
+
+        _, ax = plt.subplots(figsize=(10, 6))
+        ax.set_ylim(0, 1)
+        ax.set_ylabel("Value", fontweight="bold")
+        title = (
+            f"Precision, by Object Size"
+            f"\n(target: {self.metric_target.value},"
+            f" averaging: {self.averaging_method.value})"
+        )
+        ax.set_title(title, fontweight="bold")
+
+        x_positions = range(len(labels))
+        bars = ax.bar(x_positions, values, color=colors, align="center")
+
+        ax.set_xticks(x_positions)
+        ax.set_xticklabels(labels, rotation=45, ha="right")
+
+        for bar in bars:
+            y_value = bar.get_height()
+            ax.text(
+                bar.get_x() + bar.get_width() / 2,
+                y_value + 0.02,
+                f"{y_value:.2f}",
+                ha="center",
+                va="bottom",
+            )
+
+        plt.rcParams["font.family"] = "sans-serif"
+
+        plt.tight_layout()
+        plt.show()

supervision/metrics/recall.py

@@ -0,0 +1,652 @@
+from __future__ import annotations
+
+from copy import deepcopy
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, List, Optional, Tuple, Union
+
+import numpy as np
+from matplotlib import pyplot as plt
+
+from supervision.config import ORIENTED_BOX_COORDINATES
+from supervision.detection.core import Detections
+from supervision.detection.utils import (
+    box_iou_batch,
+    mask_iou_batch,
+    oriented_box_iou_batch,
+)
+from supervision.draw.color import LEGACY_COLOR_PALETTE
+from supervision.metrics.core import AveragingMethod, Metric, MetricTarget
+from supervision.metrics.utils.object_size import (
+    ObjectSizeCategory,
+    get_detection_size_category,
+)
+from supervision.metrics.utils.utils import ensure_pandas_installed
+
+if TYPE_CHECKING:
+    import pandas as pd
+
+
+class Recall(Metric):
+    """
+    Recall is a metric used to evaluate object detection models. It is the ratio of
+    true positive detections to the total number of ground truth instances. We calculate
+    it at different IoU thresholds.
+
+    In simple terms, Recall is a measure of a model's completeness, calculated as:
+
+    `Recall = TP / (TP + FN)`
+
+    Here, `TP` is the number of true positives (correct detections), and `FN` is the
+    number of false negatives (missed detections).
+
+    Example:
+        ```python
+        import supervision as sv
+        from supervision.metrics import Recall
+
+        predictions = sv.Detections(...)
+        targets = sv.Detections(...)
+
+        recall_metric = Recall()
+        recall_result = recall_metric.update(predictions, targets).compute()
+
+        print(recall_result.recall_at_50)
+        # 0.7615
+
+        print(recall_result)
+        # RecallResult:
+        # Metric target:    MetricTarget.BOXES
+        # Averaging method: AveragingMethod.WEIGHTED
+        # R @ 50:     0.7615
+        # R @ 75:     0.7462
+        # R @ thresh: [0.76151  0.76011  0.76011  0.75732  ...]
+        # IoU thresh: [0.5  0.55  0.6  ...]
+        # Recall per class:
+        # 0: [0.78571  0.78571  0.78571  ...]
+        # ...
+        # Small objects: ...
+        # Medium objects: ...
+        # Large objects: ...
+
+        recall_result.plot()
+
+        ```
+
+    ![example_plot](\
+        https://media.roboflow.com/supervision-docs/metrics/recall_plot_example.png\
+        ){ align=center width="800" }
+    """
+
+    def __init__(
+        self,
+        metric_target: MetricTarget = MetricTarget.BOXES,
+        averaging_method: AveragingMethod = AveragingMethod.WEIGHTED,
+    ):
+        """
+        Initialize the Recall metric.
+
+        Args:
+            metric_target (MetricTarget): The type of detection data to use.
+            averaging_method (AveragingMethod): The averaging method used to compute the
+                recall. Determines how the recall is aggregated across classes.
+        """
+        self._metric_target = metric_target
+        self.averaging_method = averaging_method
+
+        self._predictions_list: List[Detections] = []
+        self._targets_list: List[Detections] = []
+
+    def reset(self) -> None:
+        """
+        Reset the metric to its initial state, clearing all stored data.
+        """
+        self._predictions_list = []
+        self._targets_list = []
+
+    def update(
+        self,
+        predictions: Union[Detections, List[Detections]],
+        targets: Union[Detections, List[Detections]],
+    ) -> Recall:
+        """
+        Add new predictions and targets to the metric, but do not compute the result.
+
+        Args:
+            predictions (Union[Detections, List[Detections]]): The predicted detections.
+            targets (Union[Detections, List[Detections]]): The target detections.
+
+        Returns:
+            (Recall): The updated metric instance.
+        """
+        if not isinstance(predictions, list):
+            predictions = [predictions]
+        if not isinstance(targets, list):
+            targets = [targets]
+
+        if len(predictions) != len(targets):
+            raise ValueError(
+                f"The number of predictions ({len(predictions)}) and"
+                f" targets ({len(targets)}) during the update must be the same."
+            )
+
+        self._predictions_list.extend(predictions)
+        self._targets_list.extend(targets)
+
+        return self
+
+    def compute(self) -> RecallResult:
+        """
+        Calculate the recall metric based on the stored predictions and ground-truth
+        data, at different IoU thresholds.
+
+        Returns:
+            (RecallResult): The recall metric result.
+        """
+        result = self._compute(self._predictions_list, self._targets_list)
+
+        small_predictions, small_targets = self._filter_predictions_and_targets_by_size(
+            self._predictions_list, self._targets_list, ObjectSizeCategory.SMALL
+        )
+        result.small_objects = self._compute(small_predictions, small_targets)
+
+        medium_predictions, medium_targets = (
+            self._filter_predictions_and_targets_by_size(
+                self._predictions_list, self._targets_list, ObjectSizeCategory.MEDIUM
+            )
+        )
+        result.medium_objects = self._compute(medium_predictions, medium_targets)
+
+        large_predictions, large_targets = self._filter_predictions_and_targets_by_size(
+            self._predictions_list, self._targets_list, ObjectSizeCategory.LARGE
+        )
+        result.large_objects = self._compute(large_predictions, large_targets)
+
+        return result
+
+    def _compute(
+        self, predictions_list: List[Detections], targets_list: List[Detections]
+    ) -> RecallResult:
+        iou_thresholds = np.linspace(0.5, 0.95, 10)
+        stats = []
+
+        for predictions, targets in zip(predictions_list, targets_list):
+            prediction_contents = self._detections_content(predictions)
+            target_contents = self._detections_content(targets)
+
+            if len(targets) > 0:
+                if len(predictions) == 0:
+                    stats.append(
+                        (
+                            np.zeros((0, iou_thresholds.size), dtype=bool),
+                            np.zeros((0,), dtype=np.float32),
+                            np.zeros((0,), dtype=int),
+                            targets.class_id,
+                        )
+                    )
+
+                else:
+                    if self._metric_target == MetricTarget.BOXES:
+                        iou = box_iou_batch(target_contents, prediction_contents)
+                    elif self._metric_target == MetricTarget.MASKS:
+                        iou = mask_iou_batch(target_contents, prediction_contents)
+                    elif self._metric_target == MetricTarget.ORIENTED_BOUNDING_BOXES:
+                        iou = oriented_box_iou_batch(
+                            target_contents, prediction_contents
+                        )
+                    else:
+                        raise ValueError(
+                            "Unsupported metric target for IoU calculation"
+                        )
+
+                    matches = self._match_detection_batch(
+                        predictions.class_id, targets.class_id, iou, iou_thresholds
+                    )
+                    stats.append(
+                        (
+                            matches,
+                            predictions.confidence,
+                            predictions.class_id,
+                            targets.class_id,
+                        )
+                    )
+
+        if not stats:
+            return RecallResult(
+                metric_target=self._metric_target,
+                averaging_method=self.averaging_method,
+                recall_scores=np.zeros(iou_thresholds.shape[0]),
+                recall_per_class=np.zeros((0, iou_thresholds.shape[0])),
+                iou_thresholds=iou_thresholds,
+                matched_classes=np.array([], dtype=int),
+                small_objects=None,
+                medium_objects=None,
+                large_objects=None,
+            )
+
+        concatenated_stats = [np.concatenate(items, 0) for items in zip(*stats)]
+        recall_scores, recall_per_class, unique_classes = (
+            self._compute_recall_for_classes(*concatenated_stats)
+        )
+
+        return RecallResult(
+            metric_target=self._metric_target,
+            averaging_method=self.averaging_method,
+            recall_scores=recall_scores,
+            recall_per_class=recall_per_class,
+            iou_thresholds=iou_thresholds,
+            matched_classes=unique_classes,
+            small_objects=None,
+            medium_objects=None,
+            large_objects=None,
+        )
+
+    def _compute_recall_for_classes(
+        self,
+        matches: np.ndarray,
+        prediction_confidence: np.ndarray,
+        prediction_class_ids: np.ndarray,
+        true_class_ids: np.ndarray,
+    ) -> Tuple[np.ndarray, np.ndarray, np.ndarray]:
+        sorted_indices = np.argsort(-prediction_confidence)
+        matches = matches[sorted_indices]
+        prediction_class_ids = prediction_class_ids[sorted_indices]
+        unique_classes, class_counts = np.unique(true_class_ids, return_counts=True)
+
+        # Shape: PxTh,P,C,C -> CxThx3
+        confusion_matrix = self._compute_confusion_matrix(
+            matches, prediction_class_ids, unique_classes, class_counts
+        )
+
+        # Shape: CxThx3 -> CxTh
+        recall_per_class = self._compute_recall(confusion_matrix)
+
+        # Shape: CxTh -> Th
+        if self.averaging_method == AveragingMethod.MACRO:
+            recall_scores = np.mean(recall_per_class, axis=0)
+        elif self.averaging_method == AveragingMethod.MICRO:
+            confusion_matrix_merged = confusion_matrix.sum(0)
+            recall_scores = self._compute_recall(confusion_matrix_merged)
+        elif self.averaging_method == AveragingMethod.WEIGHTED:
+            class_counts = class_counts.astype(np.float32)
+            recall_scores = np.average(recall_per_class, axis=0, weights=class_counts)
+
+        return recall_scores, recall_per_class, unique_classes
+
+    @staticmethod
+    def _match_detection_batch(
+        predictions_classes: np.ndarray,
+        target_classes: np.ndarray,
+        iou: np.ndarray,
+        iou_thresholds: np.ndarray,
+    ) -> np.ndarray:
+        num_predictions, num_iou_levels = (
+            predictions_classes.shape[0],
+            iou_thresholds.shape[0],
+        )
+        correct = np.zeros((num_predictions, num_iou_levels), dtype=bool)
+        correct_class = target_classes[:, None] == predictions_classes
+
+        for i, iou_level in enumerate(iou_thresholds):
+            matched_indices = np.where((iou >= iou_level) & correct_class)
+
+            if matched_indices[0].shape[0]:
+                combined_indices = np.stack(matched_indices, axis=1)
+                iou_values = iou[matched_indices][:, None]
+                matches = np.hstack([combined_indices, iou_values])
+
+                if matched_indices[0].shape[0] > 1:
+                    matches = matches[matches[:, 2].argsort()[::-1]]
+                    matches = matches[np.unique(matches[:, 1], return_index=True)[1]]
+                    matches = matches[np.unique(matches[:, 0], return_index=True)[1]]
+
+                correct[matches[:, 1].astype(int), i] = True
+
+        return correct
+
+    @staticmethod
+    def _compute_confusion_matrix(
+        sorted_matches: np.ndarray,
+        sorted_prediction_class_ids: np.ndarray,
+        unique_classes: np.ndarray,
+        class_counts: np.ndarray,
+    ) -> np.ndarray:
+        """
+        Compute the confusion matrix for each class and IoU threshold.
+
+        Assumes the matches and prediction_class_ids are sorted by confidence
+        in descending order.
+
+        Arguments:
+            sorted_matches: np.ndarray, bool, shape (P, Th), that is True
+                if the prediction is a true positive at the given IoU threshold.
+            sorted_prediction_class_ids: np.ndarray, int, shape (P,), containing
+                the class id for each prediction.
+            unique_classes: np.ndarray, int, shape (C,), containing the unique
+                class ids.
+            class_counts: np.ndarray, int, shape (C,), containing the number
+                of true instances for each class.
+
+        Returns:
+            np.ndarray, shape (C, Th, 3), containing the true positives, false
+                positives, and false negatives for each class and IoU threshold.
+        """
+
+        num_thresholds = sorted_matches.shape[1]
+        num_classes = unique_classes.shape[0]
+
+        confusion_matrix = np.zeros((num_classes, num_thresholds, 3))
+        for class_idx, class_id in enumerate(unique_classes):
+            is_class = sorted_prediction_class_ids == class_id
+            num_true = class_counts[class_idx]
+            num_predictions = is_class.sum()
+
+            if num_predictions == 0:
+                true_positives = np.zeros(num_thresholds)
+                false_positives = np.zeros(num_thresholds)
+                false_negatives = np.full(num_thresholds, num_true)
+            elif num_true == 0:
+                true_positives = np.zeros(num_thresholds)
+                false_positives = np.full(num_thresholds, num_predictions)
+                false_negatives = np.zeros(num_thresholds)
+            else:
+                true_positives = sorted_matches[is_class].sum(0)
+                false_positives = (1 - sorted_matches[is_class]).sum(0)
+                false_negatives = num_true - true_positives
+            confusion_matrix[class_idx] = np.stack(
+                [true_positives, false_positives, false_negatives], axis=1
+            )
+
+        return confusion_matrix
+
+    @staticmethod
+    def _compute_recall(confusion_matrix: np.ndarray) -> np.ndarray:
+        """
+        Broadcastable function, computing the recall from the confusion matrix.
+
+        Arguments:
+            confusion_matrix: np.ndarray, shape (N, ..., 3), where the last dimension
+                contains the true positives, false positives, and false negatives.
+
+        Returns:
+            np.ndarray, shape (N, ...), containing the recall for each element.
+        """
+        if not confusion_matrix.shape[-1] == 3:
+            raise ValueError(
+                f"Confusion matrix must have shape (..., 3), got "
+                f"{confusion_matrix.shape}"
+            )
+        true_positives = confusion_matrix[..., 0]
+        false_negatives = confusion_matrix[..., 2]
+
+        denominator = true_positives + false_negatives
+        recall = np.where(denominator == 0, 0, true_positives / denominator)
+
+        return recall
+
+    def _detections_content(self, detections: Detections) -> np.ndarray:
+        """Return boxes, masks or oriented bounding boxes from detections."""
+        if self._metric_target == MetricTarget.BOXES:
+            return detections.xyxy
+        if self._metric_target == MetricTarget.MASKS:
+            return (
+                detections.mask
+                if detections.mask is not None
+                else self._make_empty_content()
+            )
+        if self._metric_target == MetricTarget.ORIENTED_BOUNDING_BOXES:
+            obb = detections.data.get(ORIENTED_BOX_COORDINATES)
+            if obb is not None and len(obb) > 0:
+                return np.array(obb, dtype=np.float32)
+            return self._make_empty_content()
+        raise ValueError(f"Invalid metric target: {self._metric_target}")
+
+    def _make_empty_content(self) -> np.ndarray:
+        if self._metric_target == MetricTarget.BOXES:
+            return np.empty((0, 4), dtype=np.float32)
+        if self._metric_target == MetricTarget.MASKS:
+            return np.empty((0, 0, 0), dtype=bool)
+        if self._metric_target == MetricTarget.ORIENTED_BOUNDING_BOXES:
+            return np.empty((0, 4, 2), dtype=np.float32)
+        raise ValueError(f"Invalid metric target: {self._metric_target}")
+
+    def _filter_detections_by_size(
+        self, detections: Detections, size_category: ObjectSizeCategory
+    ) -> Detections:
+        """Return a copy of detections with contents filtered by object size."""
+        new_detections = deepcopy(detections)
+        if detections.is_empty() or size_category == ObjectSizeCategory.ANY:
+            return new_detections
+
+        sizes = get_detection_size_category(new_detections, self._metric_target)
+        size_mask = sizes == size_category.value
+
+        new_detections.xyxy = new_detections.xyxy[size_mask]
+        if new_detections.mask is not None:
+            new_detections.mask = new_detections.mask[size_mask]
+        if new_detections.class_id is not None:
+            new_detections.class_id = new_detections.class_id[size_mask]
+        if new_detections.confidence is not None:
+            new_detections.confidence = new_detections.confidence[size_mask]
+        if new_detections.tracker_id is not None:
+            new_detections.tracker_id = new_detections.tracker_id[size_mask]
+        if new_detections.data is not None:
+            for key, value in new_detections.data.items():
+                new_detections.data[key] = np.array(value)[size_mask]
+
+        return new_detections
+
+    def _filter_predictions_and_targets_by_size(
+        self,
+        predictions_list: List[Detections],
+        targets_list: List[Detections],
+        size_category: ObjectSizeCategory,
+    ) -> Tuple[List[Detections], List[Detections]]:
+        """
+        Filter predictions and targets by object size category.
+        """
+        new_predictions_list = []
+        new_targets_list = []
+        for predictions, targets in zip(predictions_list, targets_list):
+            new_predictions_list.append(
+                self._filter_detections_by_size(predictions, size_category)
+            )
+            new_targets_list.append(
+                self._filter_detections_by_size(targets, size_category)
+            )
+        return new_predictions_list, new_targets_list
+
+
+@dataclass
+class RecallResult:
+    """
+    The results of the recall metric calculation.
+
+    Defaults to `0` if no detections or targets were provided.
+
+    Attributes:
+        metric_target (MetricTarget): the type of data used for the metric -
+            boxes, masks or oriented bounding boxes.
+        averaging_method (AveragingMethod): the averaging method used to compute the
+            recall. Determines how the recall is aggregated across classes.
+        recall_at_50 (float): the recall at IoU threshold of `0.5`.
+        recall_at_75 (float): the recall at IoU threshold of `0.75`.
+        recall_scores (np.ndarray): the recall scores at each IoU threshold.
+            Shape: `(num_iou_thresholds,)`
+        recall_per_class (np.ndarray): the recall scores per class and IoU threshold.
+            Shape: `(num_target_classes, num_iou_thresholds)`
+        iou_thresholds (np.ndarray): the IoU thresholds used in the calculations.
+        matched_classes (np.ndarray): the class IDs of all matched classes.
+            Corresponds to the rows of `recall_per_class`.
+        small_objects (Optional[RecallResult]): the Recall metric results
+            for small objects (area < 32²).
+        medium_objects (Optional[RecallResult]): the Recall metric results
+            for medium objects (32² ≤ area < 96²).
+        large_objects (Optional[RecallResult]): the Recall metric results
+            for large objects (area ≥ 96²).
+    """
+
+    metric_target: MetricTarget
+    averaging_method: AveragingMethod
+
+    @property
+    def recall_at_50(self) -> float:
+        return self.recall_scores[0]
+
+    @property
+    def recall_at_75(self) -> float:
+        return self.recall_scores[5]
+
+    recall_scores: np.ndarray
+    recall_per_class: np.ndarray
+    iou_thresholds: np.ndarray
+    matched_classes: np.ndarray
+
+    small_objects: Optional[RecallResult]
+    medium_objects: Optional[RecallResult]
+    large_objects: Optional[RecallResult]
+
+    def __str__(self) -> str:
+        """
+        Format as a pretty string.
+
+        Example:
+            ```python
+            print(recall_result)
+            # RecallResult:
+            # Metric target:    MetricTarget.BOXES
+            # Averaging method: AveragingMethod.WEIGHTED
+            # R @ 50:     0.7615
+            # R @ 75:     0.7462
+            # R @ thresh: [0.76151  0.76011  0.76011  0.75732  ...]
+            # IoU thresh: [0.5  0.55  0.6  ...]
+            # Recall per class:
+            # 0: [0.78571  0.78571  0.78571  ...]
+            # ...
+            # Small objects: ...
+            # Medium objects: ...
+            # Large objects: ...
+            ```
+        """
+        out_str = (
+            f"{self.__class__.__name__}:\n"
+            f"Metric target:    {self.metric_target}\n"
+            f"Averaging method: {self.averaging_method}\n"
+            f"R @ 50:     {self.recall_at_50:.4f}\n"
+            f"R @ 75:     {self.recall_at_75:.4f}\n"
+            f"R @ thresh: {self.recall_scores}\n"
+            f"IoU thresh: {self.iou_thresholds}\n"
+            f"Recall per class:\n"
+        )
+        if self.recall_per_class.size == 0:
+            out_str += "  No results\n"
+        for class_id, recall_of_class in zip(
+            self.matched_classes, self.recall_per_class
+        ):
+            out_str += f"  {class_id}: {recall_of_class}\n"
+
+        indent = "  "
+        if self.small_objects is not None:
+            indented = indent + str(self.small_objects).replace("\n", f"\n{indent}")
+            out_str += f"\nSmall objects:\n{indented}"
+        if self.medium_objects is not None:
+            indented = indent + str(self.medium_objects).replace("\n", f"\n{indent}")
+            out_str += f"\nMedium objects:\n{indented}"
+        if self.large_objects is not None:
+            indented = indent + str(self.large_objects).replace("\n", f"\n{indent}")
+            out_str += f"\nLarge objects:\n{indented}"
+
+        return out_str
+
+    def to_pandas(self) -> "pd.DataFrame":
+        """
+        Convert the result to a pandas DataFrame.
+
+        Returns:
+            (pd.DataFrame): The result as a DataFrame.
+        """
+        ensure_pandas_installed()
+        import pandas as pd
+
+        pandas_data = {
+            "R@50": self.recall_at_50,
+            "R@75": self.recall_at_75,
+        }
+
+        if self.small_objects is not None:
+            small_objects_df = self.small_objects.to_pandas()
+            for key, value in small_objects_df.items():
+                pandas_data[f"small_objects_{key}"] = value
+        if self.medium_objects is not None:
+            medium_objects_df = self.medium_objects.to_pandas()
+            for key, value in medium_objects_df.items():
+                pandas_data[f"medium_objects_{key}"] = value
+        if self.large_objects is not None:
+            large_objects_df = self.large_objects.to_pandas()
+            for key, value in large_objects_df.items():
+                pandas_data[f"large_objects_{key}"] = value
+
+        return pd.DataFrame(pandas_data, index=[0])
+
+    def plot(self):
+        """
+        Plot the recall results.
+
+        ![example_plot](\
+            https://media.roboflow.com/supervision-docs/metrics/recall_plot_example.png\
+            ){ align=center width="800" }
+        """
+
+        labels = ["Recall@50", "Recall@75"]
+        values = [self.recall_at_50, self.recall_at_75]
+        colors = [LEGACY_COLOR_PALETTE[0]] * 2
+
+        if self.small_objects is not None:
+            small_objects = self.small_objects
+            labels += ["Small: R@50", "Small: R@75"]
+            values += [small_objects.recall_at_50, small_objects.recall_at_75]
+            colors += [LEGACY_COLOR_PALETTE[3]] * 2
+
+        if self.medium_objects is not None:
+            medium_objects = self.medium_objects
+            labels += ["Medium: R@50", "Medium: R@75"]
+            values += [medium_objects.recall_at_50, medium_objects.recall_at_75]
+            colors += [LEGACY_COLOR_PALETTE[2]] * 2
+
+        if self.large_objects is not None:
+            large_objects = self.large_objects
+            labels += ["Large: R@50", "Large: R@75"]
+            values += [large_objects.recall_at_50, large_objects.recall_at_75]
+            colors += [LEGACY_COLOR_PALETTE[4]] * 2
+
+        plt.rcParams["font.family"] = "monospace"
+
+        _, ax = plt.subplots(figsize=(10, 6))
+        ax.set_ylim(0, 1)
+        ax.set_ylabel("Value", fontweight="bold")
+        title = (
+            f"Recall, by Object Size"
+            f"\n(target: {self.metric_target.value},"
+            f" averaging: {self.averaging_method.value})"
+        )
+        ax.set_title(title, fontweight="bold")
+
+        x_positions = range(len(labels))
+        bars = ax.bar(x_positions, values, color=colors, align="center")
+
+        ax.set_xticks(x_positions)
+        ax.set_xticklabels(labels, rotation=45, ha="right")
+
+        for bar in bars:
+            y_value = bar.get_height()
+            ax.text(
+                bar.get_x() + bar.get_width() / 2,
+                y_value + 0.02,
+                f"{y_value:.2f}",
+                ha="center",
+                va="bottom",
+            )
+
+        plt.rcParams["font.family"] = "sans-serif"
+
+        plt.tight_layout()
+        plt.show()

supervision/metrics/utils/internal_data_store.py

@@ -1,300 +0,0 @@
-from __future__ import annotations
-
-from typing import TYPE_CHECKING, List, Optional, Set, Tuple
-
-import numpy as np
-import numpy.typing as npt
-
-from supervision.config import ORIENTED_BOX_COORDINATES
-from supervision.metrics.core import CLASS_ID_NONE, MetricTarget
-from supervision.metrics.utils.object_size import (
-    ObjectSizeCategory,
-    get_object_size_category,
-)
-from supervision.metrics.utils.utils import unify_pad_masks_shape
-
-if TYPE_CHECKING:
-    from supervision.detection.core import Detections
-
-
-class MetricData:
-    """
-    A container for detection contents, decouple from `Detections`.
-    """
-
-    def __init__(self, metric_target: MetricTarget, class_agnostic: bool = False):
-        self._metric_target = metric_target
-        self._class_agnostic = class_agnostic
-        self._content_list: List[npt.NDArray] = []
-        self._confidence_list: List[npt.NDArray[np.float32]] = []
-        self._class_id_list: List[npt.NDArray[np.int_]] = []
-
-    def update(self, detections: Detections):
-        """Add new detections to the store."""
-        if detections.is_empty() or len(detections) == 0:
-            return
-
-        # Relies on Detections to ensure that member vars are equal in length
-        # or None/empty.
-        self._validate_new_entry(detections)
-
-        new_content = self._detections_content(detections)
-        self._validate_shape(new_content)
-        self._content_list.append(new_content)
-
-        if detections.confidence is not None:
-            self._confidence_list.append(detections.confidence)
-
-        if detections.class_id is not None:
-            if self._class_agnostic:
-                self._class_id_list.append(
-                    np.full(len(detections.class_id), CLASS_ID_NONE, dtype=int)
-                )
-            else:
-                self._class_id_list.append(detections.class_id)
-
-    def get_classes(self) -> Set[int]:
-        """Return all class IDs."""
-        if self._class_agnostic:
-            return {CLASS_ID_NONE}
-        return set.union(*[set(class_id) for class_id in self._class_id_list])
-
-    def get(
-        self, class_id: Optional[int] = None, size_category=ObjectSizeCategory.ANY
-    ) -> Tuple[npt.NDArray, npt.NDArray, npt.NDArray]:
-        """
-        Get the contents, class_ids and confidences, optionally filtered by
-        class_id and/or size.
-
-        Args:
-            class_id (Optional[int]): The class ID for the data to retrieve
-            size_category (ObjectSizeCategory): The size of the objects to retrieve.
-
-        Returns:
-            (np.ndarray): Boxes, masks or obb, all stacked in a single array.
-        """
-        if self._metric_target in [
-            MetricTarget.BOXES,
-            MetricTarget.ORIENTED_BOUNDING_BOXES,
-        ]:
-            self._merge_boxes()
-            if len(self._content_list) == 0:
-                content = self._make_empty_content()
-            else:
-                content = self._content_list[0]
-
-        elif self._metric_target == MetricTarget.MASKS:
-            self._merge_masks()
-            if len(self._content_list) == 0:
-                content = self._make_empty_content()
-            else:
-                content = self._content_list[0]
-
-        size_mask = np.full(len(content), True)
-        if size_category != ObjectSizeCategory.ANY:
-            sizes = get_object_size_category(content, self._metric_target)
-            size_mask = sizes == size_category.value
-
-        class_mask = np.full(len(content), True)
-        if class_id is not None:
-            self._merge_class_id()
-            class_ids = self._class_id_list[0]
-            class_mask = class_ids == class_id
-
-        content = content[(size_mask & class_mask)]
-
-        self._merge_class_id()
-        if len(self._class_id_list) == 0:
-            class_ids = np.array([], dtype=int)
-        else:
-            class_ids = self._class_id_list[0]
-        if len(class_ids) > 0:
-            class_ids = class_ids[(size_mask & class_mask)]
-
-        self._merge_confidence()
-        if len(self._confidence_list) == 0:
-            confidences = np.array([], dtype=float)
-        else:
-            confidences = self._confidence_list[0]
-        if len(confidences) > 0:
-            confidences = confidences[(size_mask & class_mask)]
-
-        return content, class_ids, confidences
-
-    def get_class_id(self) -> npt.NDArray[np.int_]:
-        self._merge_class_id()
-        if len(self._class_id_list) == 0:
-            return np.array([], dtype=int)
-        return self._class_id_list[0]
-
-    def get_confidence(self) -> npt.NDArray[np.float32]:
-        self._merge_confidence()
-        if len(self._confidence_list) == 0:
-            return np.array([], dtype=float)
-        return self._confidence_list[0]
-
-    def _detections_content(self, detections: Detections) -> npt.NDArray:
-        """Return boxes, masks or oriented bounding boxes from detections."""
-        if self._metric_target == MetricTarget.BOXES:
-            return detections.xyxy
-        if self._metric_target == MetricTarget.MASKS:
-            return (
-                detections.mask
-                if detections.mask is not None
-                else self._make_empty_content()
-            )
-        if self._metric_target == MetricTarget.ORIENTED_BOUNDING_BOXES:
-            if obb := detections.data.get(ORIENTED_BOX_COORDINATES):
-                return np.ndarray(obb, dtype=np.float32)
-            return self._make_empty_content()
-        raise ValueError(f"Invalid metric target: {self._metric_target}")
-
-    def _make_empty_content(self) -> npt.NDArray:
-        if self._metric_target == MetricTarget.BOXES:
-            return np.empty((0, 4), dtype=np.float32)
-        if self._metric_target == MetricTarget.MASKS:
-            return np.empty((0, 0, 0), dtype=bool)
-        if self._metric_target == MetricTarget.ORIENTED_BOUNDING_BOXES:
-            return np.empty((0, 8), dtype=np.float32)
-        raise ValueError(f"Invalid metric target: {self._metric_target}")
-
-    def _validate_new_entry(self, detections: Detections) -> None:
-        if (
-            len(self._content_list) == 0
-            or detections.is_empty()
-            or len(detections) == 0
-        ):
-            return
-
-        is_self_class_empty = len(self._class_id_list) == 0
-        is_self_confidence_empty = len(self._confidence_list) == 0
-        is_detection_class_empty = (
-            detections.class_id is None or len(detections.class_id) == 0
-        )
-        is_detection_confidence_empty = (
-            detections.confidence is None or len(detections.confidence) == 0
-        )
-
-        if is_self_confidence_empty and not is_detection_confidence_empty:
-            raise ValueError(
-                "Previously stored detections without confidence,"
-                " but new detections have it."
-            )
-        if is_self_class_empty and not is_detection_class_empty:
-            raise ValueError(
-                "Previously stored detections without class ID,"
-                " but new detections have it."
-            )
-        if not is_self_class_empty and is_detection_class_empty:
-            raise ValueError(
-                "Started storing detections with class ID, but"
-                " new detections do not have it."
-            )
-        if not is_self_confidence_empty and is_detection_confidence_empty:
-            raise ValueError(
-                "Started storing detections with confidence,"
-                " but new detections do not have it."
-            )
-
-    def _validate_shape(self, data: npt.NDArray) -> None:
-        if self._metric_target == MetricTarget.BOXES:
-            if len(data.shape) != 2 or data.shape[1] != 4:
-                raise ValueError(f"Invalid xyxy shape: {data.shape}. Expected: (N, 4)")
-        elif self._metric_target == MetricTarget.MASKS:
-            if len(data.shape) != 3:
-                raise ValueError(
-                    f"Invalid mask shape: {data.shape}. Expected: (N, H, W)"
-                )
-        elif self._metric_target == MetricTarget.ORIENTED_BOUNDING_BOXES:
-            if len(data.shape) != 2 or data.shape[1] != 8:
-                raise ValueError(f"Invalid obb shape: {data.shape}. Expected: (N, 8)")
-        else:
-            raise ValueError(f"Invalid metric target: {self._metric_target}")
-
-    def _merge_boxes(self):
-        """Merge all boxes into a single array."""
-        if self._metric_target not in (
-            MetricTarget.BOXES,
-            MetricTarget.ORIENTED_BOUNDING_BOXES,
-        ):
-            raise ValueError("Invalid metric target for merging boxes")
-        if len(self._content_list) < 2:
-            return
-        self._content_list = [np.vstack(self._content_list)]
-
-    def _merge_masks(self):
-        """Merge all masks into a single array."""
-        if self._metric_target != MetricTarget.MASKS:
-            raise ValueError("Invalid metric target for merging masks")
-        if len(self._content_list) < 2:
-            return
-
-        mew_mask_list = unify_pad_masks_shape(*self._content_list)
-        self._content_list = [np.vstack(mew_mask_list)]
-
-    def _merge_class_id(self):
-        """Merge all class IDs into a single array."""
-        if len(self._class_id_list) < 2:
-            return
-        self._class_id_list = [np.hstack(self._class_id_list)]
-
-    def _merge_confidence(self):
-        """Merge all confidences into a single array."""
-        if len(self._confidence_list) < 2:
-            return
-        self._confidence_list = [np.hstack(self._confidence_list)]
-
-
-class MetricDataStore:
-    """
-    Stores internal data for metrics.
-
-    Provides a class-agnostic way to access it.
-    """
-
-    def __init__(self, metric_target: MetricTarget, class_agnostic: bool = False):
-        self._metric_target = metric_target
-        self._class_agnostic = class_agnostic
-        self._data_1: MetricData
-        self._data_2: MetricData
-        self.reset()
-
-    def reset(self) -> None:
-        self._data_1 = MetricData(self._metric_target, self._class_agnostic)
-        self._data_2 = MetricData(self._metric_target, self._class_agnostic)
-
-    def update(self, data_1: Detections, data_2: Detections) -> None:
-        """
-        Add new data to the store.
-
-        Use sv.Detections.empty() if only one set of data is available.
-        """
-        self._data_1.update(data_1)
-        self._data_2.update(data_2)
-
-    def get(
-        self,
-        class_id: Optional[int] = None,
-        size_category: ObjectSizeCategory = ObjectSizeCategory.ANY,
-    ) -> Tuple[
-        Tuple[npt.NDArray, npt.NDArray, npt.NDArray],
-        Tuple[npt.NDArray, npt.NDArray, npt.NDArray],
-    ]:
-        """
-        Get the data for both sets, optionally filtered by class_id and/or size.
-        """
-
-        data_1, class_id_1, confidence_1 = self._data_1.get(class_id, size_category)
-        data_2, class_id_2, confidence_2 = self._data_2.get(class_id, size_category)
-
-        if self._metric_target == MetricTarget.MASKS:
-            data_1, data_2 = unify_pad_masks_shape(data_1, data_2)
-
-        return (
-            (data_1, class_id_1, confidence_1),
-            (data_2, class_id_2, confidence_2),
-        )
-
-    def get_classes(self) -> Set[int]:
-        """Return all class IDs."""
-        return self._data_1.get_classes() | self._data_2.get_classes()

supervision/metrics/utils/object_size.py

@@ -101,17 +101,20 @@ def get_obb_size_category(xyxyxyxy: npt.NDArray[np.float32]) -> npt.NDArray[np.i
     Get the size category of a oriented bounding boxes array.
 
     Args:
-        xyxyxyxy (np.ndarray): The bounding boxes array shaped (N, 8).
+        xyxyxyxy (np.ndarray): The bounding boxes array shaped (N, 4, 2).
 
     Returns:
         (np.ndarray) The size category of each bounding box, matching
         the enum values of ObjectSizeCategory. Shaped (N,).
     """
-    if len(xyxyxyxy.shape) != 2 or xyxyxyxy.shape[1] != 8:
-        raise ValueError("Oriented bounding boxes must be shaped (N, 8)")
+    if len(xyxyxyxy.shape) != 3 or xyxyxyxy.shape[1] != 4 or xyxyxyxy.shape[2] != 2:
+        raise ValueError("Oriented bounding boxes must be shaped (N, 4, 2)")
 
     # Shoelace formula
-    x1, y1, x2, y2, x3, y3, x4, y4 = xyxyxyxy.T
+    x = xyxyxyxy[:, :, 0]
+    y = xyxyxyxy[:, :, 1]
+    x1, x2, x3, x4 = x.T
+    y1, y2, y3, y4 = y.T
     areas = 0.5 * np.abs(
         (x1 * y2 + x2 * y3 + x3 * y4 + x4 * y1)
         - (x2 * y1 + x3 * y2 + x4 * y3 + x1 * y4)

supervision/metrics/utils/utils.py

@@ -1,9 +1,3 @@
-from typing import List, Tuple
-
-import numpy as np
-import numpy.typing as npt
-
-
 def ensure_pandas_installed():
     try:
         import pandas  # noqa
@@ -13,58 +7,3 @@ def ensure_pandas_installed():
             " Run `pip install 'supervision[metrics]'` or"
             " `poetry add supervision -E metrics`"
         )
-
-
-def pad_mask(mask: npt.NDArray, new_shape: Tuple[int, int]) -> npt.NDArray:
-    """Pad a mask to a new shape, inserting zeros on the right and bottom."""
-    if len(mask.shape) != 3:
-        raise ValueError(f"Invalid mask shape: {mask.shape}. Expected: (N, H, W)")
-
-    new_mask = np.pad(
-        mask,
-        (
-            (0, 0),
-            (0, new_shape[0] - mask.shape[1]),
-            (0, new_shape[1] - mask.shape[2]),
-        ),
-        mode="constant",
-        constant_values=0,
-    )
-
-    return new_mask
-
-
-def unify_pad_masks_shape(
-    *masks: npt.NDArray[np.bool_],
-) -> List[npt.NDArray[np.bool_]]:
-    """
-    Given any number of (N, H, W) mask objects, return copies of the
-    same (H, W), padded to the largest dimensions.
-
-    Args:
-        *masks (np.ndarray): The mask arrays to unify. Each shaped (_, H, W),
-
-    Returns:
-        List[np.ndarray]: The masks, padded to the largest dimensions.
-            Each list element shaped (_, H_max, W_max)
-    """
-    new_h = 0
-    new_w = 0
-    for mask in masks:
-        if len(mask.shape) != 3:
-            raise ValueError(f"Invalid mask shape: {mask.shape}. Expected: (N, H, W)")
-
-        _, h, w = mask.shape
-        new_h = max(new_h, h)
-        new_w = max(new_w, w)
-
-    results = []
-    for mask in masks:
-        results.append(pad_mask(mask, (new_h, new_w)))
-
-    return results
-
-
-def len0_like(data: npt.NDArray) -> npt.NDArray:
-    """Create an empty array with the same shape as input, but with 0 rows."""
-    return np.empty((0, *data.shape[1:]), dtype=data.dtype)

supervision/tracker/byte_tracker/basetrack.py

@@ -1,63 +0,0 @@
-from collections import OrderedDict
-from enum import Enum
-
-import numpy as np
-
-
-class TrackState(Enum):
-    New = 0
-    Tracked = 1
-    Lost = 2
-    Removed = 3
-
-
-class BaseTrack:
-    _count = 0
-
-    def __init__(self):
-        self.track_id = 0
-        self.is_activated = False
-        self.state = TrackState.New
-
-        self.history = OrderedDict()
-        self.features = []
-        self.curr_feature = None
-        self.score = 0
-        self.start_frame = 0
-        self.frame_id = 0
-        self.time_since_update = 0
-
-        # multi-camera
-        self.location = (np.inf, np.inf)
-
-    @property
-    def end_frame(self) -> int:
-        return self.frame_id
-
-    @staticmethod
-    def next_id() -> int:
-        BaseTrack._count += 1
-        return BaseTrack._count
-
-    @staticmethod
-    def reset_counter():
-        BaseTrack._count = 0
-        BaseTrack.track_id = 0
-        BaseTrack.start_frame = 0
-        BaseTrack.frame_id = 0
-        BaseTrack.time_since_update = 0
-
-    def activate(self, *args):
-        raise NotImplementedError
-
-    def predict(self):
-        raise NotImplementedError
-
-    def update(self, *args, **kwargs):
-        raise NotImplementedError
-
-    def mark_lost(self):
-        self.state = TrackState.Lost
-
-    def mark_removed(self):
-        self.state = TrackState.Removed

supervision/tracker/byte_tracker/core.py

@@ -5,186 +5,9 @@ import numpy as np
 from supervision.detection.core import Detections
 from supervision.detection.utils import box_iou_batch
 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
-
-
-class STrack(BaseTrack):
-    shared_kalman = KalmanFilter()
-    _external_count = 0
-
-    def __init__(self, tlwh, score, class_ids, minimum_consecutive_frames):
-        # wait activate
-        self._tlwh = np.asarray(tlwh, dtype=np.float32)
-        self.kalman_filter = None
-        self.mean, self.covariance = None, None
-        self.is_activated = False
-
-        self.score = score
-        self.class_ids = class_ids
-        self.tracklet_len = 0
-
-        self.external_track_id = -1
-
-        self.minimum_consecutive_frames = minimum_consecutive_frames
-
-    def predict(self):
-        mean_state = self.mean.copy()
-        if self.state != TrackState.Tracked:
-            mean_state[7] = 0
-        self.mean, self.covariance = self.kalman_filter.predict(
-            mean_state, self.covariance
-        )
-
-    @staticmethod
-    def multi_predict(stracks):
-        if len(stracks) > 0:
-            multi_mean = []
-            multi_covariance = []
-            for i, st in enumerate(stracks):
-                multi_mean.append(st.mean.copy())
-                multi_covariance.append(st.covariance)
-                if st.state != TrackState.Tracked:
-                    multi_mean[i][7] = 0
-
-            multi_mean, multi_covariance = STrack.shared_kalman.multi_predict(
-                np.asarray(multi_mean), np.asarray(multi_covariance)
-            )
-            for i, (mean, cov) in enumerate(zip(multi_mean, multi_covariance)):
-                stracks[i].mean = mean
-                stracks[i].covariance = cov
-
-    def activate(self, kalman_filter, frame_id):
-        """Start a new tracklet"""
-        self.kalman_filter = kalman_filter
-        self.internal_track_id = self.next_id()
-        self.mean, self.covariance = self.kalman_filter.initiate(
-            self.tlwh_to_xyah(self._tlwh)
-        )
-
-        self.tracklet_len = 0
-        self.state = TrackState.Tracked
-        if frame_id == 1:
-            self.is_activated = True
-
-        if self.minimum_consecutive_frames == 1:
-            self.external_track_id = self.next_external_id()
-
-        self.frame_id = frame_id
-        self.start_frame = frame_id
-
-    def re_activate(self, new_track, frame_id, new_id=False):
-        self.mean, self.covariance = self.kalman_filter.update(
-            self.mean, self.covariance, self.tlwh_to_xyah(new_track.tlwh)
-        )
-        self.tracklet_len = 0
-        self.state = TrackState.Tracked
-
-        self.frame_id = frame_id
-        if new_id:
-            self.internal_track_id = self.next_id()
-        self.score = new_track.score
-
-    def update(self, new_track, frame_id):
-        """
-        Update a matched track
-        :type new_track: STrack
-        :type frame_id: int
-        :type update_feature: bool
-        :return:
-        """
-        self.frame_id = frame_id
-        self.tracklet_len += 1
-
-        new_tlwh = new_track.tlwh
-        self.mean, self.covariance = self.kalman_filter.update(
-            self.mean, self.covariance, self.tlwh_to_xyah(new_tlwh)
-        )
-        self.state = TrackState.Tracked
-        if self.tracklet_len == self.minimum_consecutive_frames:
-            self.is_activated = True
-            if self.external_track_id == -1:
-                self.external_track_id = self.next_external_id()
-
-        self.score = new_track.score
-
-    @property
-    def tlwh(self):
-        """Get current position in bounding box format `(top left x, top left y,
-        width, height)`.
-        """
-        if self.mean is None:
-            return self._tlwh.copy()
-        ret = self.mean[:4].copy()
-        ret[2] *= ret[3]
-        ret[:2] -= ret[2:] / 2
-        return ret
-
-    @property
-    def tlbr(self):
-        """Convert bounding box to format `(min x, min y, max x, max y)`, i.e.,
-        `(top left, bottom right)`.
-        """
-        ret = self.tlwh.copy()
-        ret[2:] += ret[:2]
-        return ret
-
-    @staticmethod
-    def tlwh_to_xyah(tlwh):
-        """Convert bounding box to format `(center x, center y, aspect ratio,
-        height)`, where the aspect ratio is `width / height`.
-        """
-        ret = np.asarray(tlwh).copy()
-        ret[:2] += ret[2:] / 2
-        ret[2] /= ret[3]
-        return ret
-
-    def to_xyah(self):
-        return self.tlwh_to_xyah(self.tlwh)
-
-    @staticmethod
-    def next_external_id():
-        STrack._external_count += 1
-        return STrack._external_count
-
-    @staticmethod
-    def reset_external_counter():
-        STrack._external_count = 0
-
-    @staticmethod
-    def tlbr_to_tlwh(tlbr):
-        ret = np.asarray(tlbr).copy()
-        ret[2:] -= ret[:2]
-        return ret
-
-    @staticmethod
-    def tlwh_to_tlbr(tlwh):
-        ret = np.asarray(tlwh).copy()
-        ret[2:] += ret[:2]
-        return ret
-
-    def __repr__(self):
-        return "OT_{}_({}-{})".format(
-            self.internal_track_id, self.start_frame, self.end_frame
-        )
-
-
-def detections2boxes(detections: Detections) -> np.ndarray:
-    """
-    Convert Supervision Detections to numpy tensors for further computation.
-    Args:
-        detections (Detections): Detections/Targets in the format of sv.Detections.
-    Returns:
-        (np.ndarray): Detections as numpy tensors as in
-            `(x_min, y_min, x_max, y_max, confidence, class_id)` order.
-    """
-    return np.hstack(
-        (
-            detections.xyxy,
-            detections.confidence[:, np.newaxis],
-            detections.class_id[:, np.newaxis],
-        )
-    )
+from supervision.tracker.byte_tracker.single_object_track import STrack, TrackState
+from supervision.tracker.byte_tracker.utils import IdCounter
 
 
 class ByteTrack:
@@ -230,11 +53,17 @@ class ByteTrack:
         self.max_time_lost = int(frame_rate / 30.0 * lost_track_buffer)
         self.minimum_consecutive_frames = minimum_consecutive_frames
         self.kalman_filter = KalmanFilter()
+        self.shared_kalman = KalmanFilter()
 
         self.tracked_tracks: List[STrack] = []
         self.lost_tracks: List[STrack] = []
         self.removed_tracks: List[STrack] = []
 
+        # Warning, possible bug: If you also set internal_id to start at 1,
+        # all traces will be connected across objects.
+        self.internal_id_counter = IdCounter()
+        self.external_id_counter = IdCounter(start_id=1)
+
     def update_with_detections(self, detections: Detections) -> Detections:
         """
         Updates the tracker with the provided detections and returns the updated
@@ -274,8 +103,12 @@ class ByteTrack:
             )
             ```
         """
-
-        tensors = detections2boxes(detections=detections)
+        tensors = np.hstack(
+            (
+                detections.xyxy,
+                detections.confidence[:, np.newaxis],
+            )
+        )
         tracks = self.update_with_tensors(tensors=tensors)
 
         if len(tracks) > 0:
@@ -301,7 +134,7 @@ class ByteTrack:
 
             return detections
 
-    def reset(self):
+    def reset(self) -> None:
         """
         Resets the internal state of the ByteTrack tracker.
 
@@ -311,11 +144,11 @@ class ByteTrack:
         ensuring the tracker starts with a clean state for each new video.
         """
         self.frame_id = 0
-        self.tracked_tracks: List[STrack] = []
-        self.lost_tracks: List[STrack] = []
-        self.removed_tracks: List[STrack] = []
-        BaseTrack.reset_counter()
-        STrack.reset_external_counter()
+        self.internal_id_counter.reset()
+        self.external_id_counter.reset()
+        self.tracked_tracks = []
+        self.lost_tracks = []
+        self.removed_tracks = []
 
     def update_with_tensors(self, tensors: np.ndarray) -> List[STrack]:
         """
@@ -333,7 +166,6 @@ class ByteTrack:
         lost_stracks = []
         removed_stracks = []
 
-        class_ids = tensors[:, 5]
         scores = tensors[:, 4]
         bboxes = tensors[:, :4]
 
@@ -347,14 +179,18 @@ class ByteTrack:
         scores_keep = scores[remain_inds]
         scores_second = scores[inds_second]
 
-        class_ids_keep = class_ids[remain_inds]
-        class_ids_second = class_ids[inds_second]
-
         if len(dets) > 0:
             """Detections"""
             detections = [
-                STrack(STrack.tlbr_to_tlwh(tlbr), s, c, self.minimum_consecutive_frames)
-                for (tlbr, s, c) in zip(dets, scores_keep, class_ids_keep)
+                STrack(
+                    STrack.tlbr_to_tlwh(tlbr),
+                    score_keep,
+                    self.minimum_consecutive_frames,
+                    self.shared_kalman,
+                    self.internal_id_counter,
+                    self.external_id_counter,
+                )
+                for (tlbr, score_keep) in zip(dets, scores_keep)
             ]
         else:
             detections = []
@@ -372,7 +208,7 @@ class ByteTrack:
         """ Step 2: First association, with high score detection boxes"""
         strack_pool = joint_tracks(tracked_stracks, self.lost_tracks)
         # Predict the current location with KF
-        STrack.multi_predict(strack_pool)
+        STrack.multi_predict(strack_pool, self.shared_kalman)
         dists = matching.iou_distance(strack_pool, detections)
 
         dists = matching.fuse_score(dists, detections)
@@ -387,7 +223,7 @@ class ByteTrack:
                 track.update(detections[idet], self.frame_id)
                 activated_starcks.append(track)
             else:
-                track.re_activate(det, self.frame_id, new_id=False)
+                track.re_activate(det, self.frame_id)
                 refind_stracks.append(track)
 
         """ Step 3: Second association, with low score detection boxes"""
@@ -395,8 +231,15 @@ class ByteTrack:
         if len(dets_second) > 0:
             """Detections"""
             detections_second = [
-                STrack(STrack.tlbr_to_tlwh(tlbr), s, c, self.minimum_consecutive_frames)
-                for (tlbr, s, c) in zip(dets_second, scores_second, class_ids_second)
+                STrack(
+                    STrack.tlbr_to_tlwh(tlbr),
+                    score_second,
+                    self.minimum_consecutive_frames,
+                    self.shared_kalman,
+                    self.internal_id_counter,
+                    self.external_id_counter,
+                )
+                for (tlbr, score_second) in zip(dets_second, scores_second)
             ]
         else:
             detections_second = []
@@ -416,13 +259,13 @@ class ByteTrack:
                 track.update(det, self.frame_id)
                 activated_starcks.append(track)
             else:
-                track.re_activate(det, self.frame_id, new_id=False)
+                track.re_activate(det, self.frame_id)
                 refind_stracks.append(track)
 
         for it in u_track:
             track = r_tracked_stracks[it]
             if not track.state == TrackState.Lost:
-                track.mark_lost()
+                track.state = TrackState.Lost
                 lost_stracks.append(track)
 
         """Deal with unconfirmed tracks, usually tracks with only one beginning frame"""
@@ -438,7 +281,7 @@ class ByteTrack:
             activated_starcks.append(unconfirmed[itracked])
         for it in u_unconfirmed:
             track = unconfirmed[it]
-            track.mark_removed()
+            track.state = TrackState.Removed
             removed_stracks.append(track)
 
         """ Step 4: Init new stracks"""
@@ -450,8 +293,8 @@ class ByteTrack:
             activated_starcks.append(track)
         """ Step 5: Update state"""
         for track in self.lost_tracks:
-            if self.frame_id - track.end_frame > self.max_time_lost:
-                track.mark_removed()
+            if self.frame_id - track.frame_id > self.max_time_lost:
+                track.state = TrackState.Removed
                 removed_stracks.append(track)
 
         self.tracked_tracks = [
@@ -497,7 +340,7 @@ def joint_tracks(
     return result
 
 
-def sub_tracks(track_list_a: List, track_list_b: List) -> List[int]:
+def sub_tracks(track_list_a: List[STrack], track_list_b: List[STrack]) -> List[int]:
     """
     Returns a list of tracks from track_list_a after removing any tracks
     that share the same internal_track_id with tracks in track_list_b.
@@ -518,7 +361,9 @@ def sub_tracks(track_list_a: List, track_list_b: List) -> List[int]:
     return list(tracks.values())
 
 
-def remove_duplicate_tracks(tracks_a: List, tracks_b: List) -> Tuple[List, List]:
+def remove_duplicate_tracks(
+    tracks_a: List[STrack], tracks_b: List[STrack]
+) -> Tuple[List[STrack], List[STrack]]:
     pairwise_distance = matching.iou_distance(tracks_a, tracks_b)
     matching_pairs = np.where(pairwise_distance < 0.15)
 

supervision/tracker/byte_tracker/matching.py

@@ -1,10 +1,15 @@
-from typing import List, Tuple
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, List, Tuple
 
 import numpy as np
 from scipy.optimize import linear_sum_assignment
 
 from supervision.detection.utils import box_iou_batch
 
+if TYPE_CHECKING:
+    from supervision.tracker.byte_tracker.core import STrack
+
 
 def indices_to_matches(
     cost_matrix: np.ndarray, indices: np.ndarray, thresh: float
@@ -20,7 +25,7 @@ def indices_to_matches(
 
 def linear_assignment(
     cost_matrix: np.ndarray, thresh: float
-) -> [np.ndarray, Tuple[int], Tuple[int, int]]:
+) -> Tuple[np.ndarray, Tuple[int], Tuple[int, int]]:
     if cost_matrix.size == 0:
         return (
             np.empty((0, 2), dtype=int),
@@ -35,7 +40,7 @@ def linear_assignment(
     return indices_to_matches(cost_matrix, indices, thresh)
 
 
-def iou_distance(atracks: List, btracks: List) -> np.ndarray:
+def iou_distance(atracks: List[STrack], btracks: List[STrack]) -> np.ndarray:
     if (len(atracks) > 0 and isinstance(atracks[0], np.ndarray)) or (
         len(btracks) > 0 and isinstance(btracks[0], np.ndarray)
     ):
@@ -53,11 +58,11 @@ def iou_distance(atracks: List, btracks: List) -> np.ndarray:
     return cost_matrix
 
 
-def fuse_score(cost_matrix: np.ndarray, detections: List) -> np.ndarray:
+def fuse_score(cost_matrix: np.ndarray, stracks: List[STrack]) -> np.ndarray:
     if cost_matrix.size == 0:
         return cost_matrix
     iou_sim = 1 - cost_matrix
-    det_scores = np.array([det.score for det in detections])
+    det_scores = np.array([strack.score for strack in stracks])
     det_scores = np.expand_dims(det_scores, axis=0).repeat(cost_matrix.shape[0], axis=0)
     fuse_sim = iou_sim * det_scores
     fuse_cost = 1 - fuse_sim

supervision/tracker/byte_tracker/single_object_track.py

@@ -0,0 +1,178 @@
+from __future__ import annotations
+
+from enum import Enum
+from typing import List
+
+import numpy as np
+import numpy.typing as npt
+
+from supervision.tracker.byte_tracker.kalman_filter import KalmanFilter
+from supervision.tracker.byte_tracker.utils import IdCounter
+
+
+class TrackState(Enum):
+    New = 0
+    Tracked = 1
+    Lost = 2
+    Removed = 3
+
+
+class STrack:
+    def __init__(
+        self,
+        tlwh: npt.NDArray[np.float32],
+        score: npt.NDArray[np.float32],
+        minimum_consecutive_frames: int,
+        shared_kalman: KalmanFilter,
+        internal_id_counter: IdCounter,
+        external_id_counter: IdCounter,
+    ):
+        self.state = TrackState.New
+        self.is_activated = False
+        self.start_frame = 0
+        self.frame_id = 0
+
+        self._tlwh = np.asarray(tlwh, dtype=np.float32)
+        self.kalman_filter = None
+        self.shared_kalman = shared_kalman
+        self.mean, self.covariance = None, None
+        self.is_activated = False
+
+        self.score = score
+        self.tracklet_len = 0
+
+        self.minimum_consecutive_frames = minimum_consecutive_frames
+
+        self.internal_id_counter = internal_id_counter
+        self.external_id_counter = external_id_counter
+        self.internal_track_id = self.internal_id_counter.NO_ID
+        self.external_track_id = self.external_id_counter.NO_ID
+
+    def predict(self) -> None:
+        mean_state = self.mean.copy()
+        if self.state != TrackState.Tracked:
+            mean_state[7] = 0
+        self.mean, self.covariance = self.kalman_filter.predict(
+            mean_state, self.covariance
+        )
+
+    @staticmethod
+    def multi_predict(stracks: List[STrack], shared_kalman: KalmanFilter) -> None:
+        if len(stracks) > 0:
+            multi_mean = []
+            multi_covariance = []
+            for i, st in enumerate(stracks):
+                multi_mean.append(st.mean.copy())
+                multi_covariance.append(st.covariance)
+                if st.state != TrackState.Tracked:
+                    multi_mean[i][7] = 0
+
+            multi_mean, multi_covariance = shared_kalman.multi_predict(
+                np.asarray(multi_mean), np.asarray(multi_covariance)
+            )
+            for i, (mean, cov) in enumerate(zip(multi_mean, multi_covariance)):
+                stracks[i].mean = mean
+                stracks[i].covariance = cov
+
+    def activate(self, kalman_filter: KalmanFilter, frame_id: int) -> None:
+        """Start a new tracklet"""
+        self.kalman_filter = kalman_filter
+        self.internal_track_id = self.internal_id_counter.new_id()
+        self.mean, self.covariance = self.kalman_filter.initiate(
+            self.tlwh_to_xyah(self._tlwh)
+        )
+
+        self.tracklet_len = 0
+        self.state = TrackState.Tracked
+        if frame_id == 1:
+            self.is_activated = True
+
+        if self.minimum_consecutive_frames == 1:
+            self.external_track_id = self.external_id_counter.new_id()
+
+        self.frame_id = frame_id
+        self.start_frame = frame_id
+
+    def re_activate(self, new_track: STrack, frame_id: int) -> None:
+        self.mean, self.covariance = self.kalman_filter.update(
+            self.mean, self.covariance, self.tlwh_to_xyah(new_track.tlwh)
+        )
+        self.tracklet_len = 0
+        self.state = TrackState.Tracked
+
+        self.frame_id = frame_id
+        self.score = new_track.score
+
+    def update(self, new_track: STrack, frame_id: int) -> None:
+        """
+        Update a matched track
+        :type new_track: STrack
+        :type frame_id: int
+        :type update_feature: bool
+        :return:
+        """
+        self.frame_id = frame_id
+        self.tracklet_len += 1
+
+        new_tlwh = new_track.tlwh
+        self.mean, self.covariance = self.kalman_filter.update(
+            self.mean, self.covariance, self.tlwh_to_xyah(new_tlwh)
+        )
+        self.state = TrackState.Tracked
+        if self.tracklet_len == self.minimum_consecutive_frames:
+            self.is_activated = True
+            if self.external_track_id == self.external_id_counter.NO_ID:
+                self.external_track_id = self.external_id_counter.new_id()
+
+        self.score = new_track.score
+
+    @property
+    def tlwh(self) -> npt.NDArray[np.float32]:
+        """Get current position in bounding box format `(top left x, top left y,
+        width, height)`.
+        """
+        if self.mean is None:
+            return self._tlwh.copy()
+        ret = self.mean[:4].copy()
+        ret[2] *= ret[3]
+        ret[:2] -= ret[2:] / 2
+        return ret
+
+    @property
+    def tlbr(self) -> npt.NDArray[np.float32]:
+        """Convert bounding box to format `(min x, min y, max x, max y)`, i.e.,
+        `(top left, bottom right)`.
+        """
+        ret = self.tlwh.copy()
+        ret[2:] += ret[:2]
+        return ret
+
+    @staticmethod
+    def tlwh_to_xyah(tlwh) -> npt.NDArray[np.float32]:
+        """Convert bounding box to format `(center x, center y, aspect ratio,
+        height)`, where the aspect ratio is `width / height`.
+        """
+        ret = np.asarray(tlwh).copy()
+        ret[:2] += ret[2:] / 2
+        ret[2] /= ret[3]
+        return ret
+
+    def to_xyah(self) -> npt.NDArray[np.float32]:
+        return self.tlwh_to_xyah(self.tlwh)
+
+    @staticmethod
+    def tlbr_to_tlwh(tlbr) -> npt.NDArray[np.float32]:
+        ret = np.asarray(tlbr).copy()
+        ret[2:] -= ret[:2]
+        return ret
+
+    @staticmethod
+    def tlwh_to_tlbr(tlwh) -> npt.NDArray[np.float32]:
+        ret = np.asarray(tlwh).copy()
+        ret[2:] += ret[:2]
+        return ret
+
+    def __repr__(self) -> str:
+        return "OT_{}_({}-{})".format(
+            self.internal_track_id, self.start_frame, self.frame_id
+        )

supervision/tracker/byte_tracker/utils.py

@@ -0,0 +1,18 @@
+class IdCounter:
+    def __init__(self, start_id: int = 0):
+        self.start_id = start_id
+        if self.start_id <= self.NO_ID:
+            raise ValueError(f"start_id must be greater than {self.NO_ID}")
+        self.reset()
+
+    def reset(self) -> None:
+        self._id = self.start_id
+
+    def new_id(self) -> int:
+        returned_id = self._id
+        self._id += 1
+        return returned_id
+
+    @property
+    def NO_ID(self) -> int:
+        return -1

test/dataset/formats/test_coco.py

@@ -1,5 +1,5 @@
 from contextlib import ExitStack as DoesNotRaise
-from typing import Dict, List, Tuple, Union
+from typing import Dict, List, Optional, Tuple, Union
 
 import numpy as np
 import pytest
@@ -21,7 +21,7 @@ def mock_coco_annotation(
     category_id: int = 0,
     bbox: Tuple[float, float, float, float] = (0.0, 0.0, 0.0, 0.0),
     area: float = 0.0,
-    segmentation: Union[List[list], Dict] = None,
+    segmentation: Optional[Union[List[list], Dict]] = None,
     iscrowd: bool = False,
 ) -> dict:
     if not segmentation:
@@ -308,7 +308,7 @@ def test_group_coco_annotations_by_image_id(
                 ),
             ),
             DoesNotRaise(),
-        ),  # two image annotations with mask, one mask as polygon ans second as RLE
+        ),  # two image annotations with mask, one mask as polygon and second as RLE
         (
             [
                 mock_coco_annotation(

test/dataset/test_core.py

@@ -1,7 +1,6 @@
 from contextlib import ExitStack as DoesNotRaise
 from typing import List, Optional
 
-import numpy as np
 import pytest
 
 from supervision import DetectionDataset
@@ -13,29 +12,29 @@ from test.test_utils import mock_detections
     [
         (
             [],
-            DetectionDataset(classes=[], images={}, annotations={}),
+            DetectionDataset(classes=[], images=[], annotations={}),
             DoesNotRaise(),
         ),  # empty dataset list
         (
-            [DetectionDataset(classes=[], images={}, annotations={})],
-            DetectionDataset(classes=[], images={}, annotations={}),
+            [DetectionDataset(classes=[], images=[], annotations={})],
+            DetectionDataset(classes=[], images=[], annotations={}),
             DoesNotRaise(),
         ),  # single empty dataset
         (
             [
-                DetectionDataset(classes=["dog", "person"], images={}, annotations={}),
-                DetectionDataset(classes=["dog", "person"], images={}, annotations={}),
+                DetectionDataset(classes=["dog", "person"], images=[], annotations={}),
+                DetectionDataset(classes=["dog", "person"], images=[], annotations={}),
             ],
-            DetectionDataset(classes=["dog", "person"], images={}, annotations={}),
+            DetectionDataset(classes=["dog", "person"], images=[], annotations={}),
             DoesNotRaise(),
         ),  # two datasets; no images and annotations, the same classes
         (
             [
-                DetectionDataset(classes=["dog", "person"], images={}, annotations={}),
-                DetectionDataset(classes=["cat"], images={}, annotations={}),
+                DetectionDataset(classes=["dog", "person"], images=[], annotations={}),
+                DetectionDataset(classes=["cat"], images=[], annotations={}),
             ],
             DetectionDataset(
-                classes=["cat", "dog", "person"], images={}, annotations={}
+                classes=["cat", "dog", "person"], images=[], annotations={}
             ),
             DoesNotRaise(),
         ),  # two datasets; no images and annotations, different classes
@@ -43,10 +42,7 @@ from test.test_utils import mock_detections
             [
                 DetectionDataset(
                     classes=["dog", "person"],
-                    images={
-                        "image-1.png": np.zeros((100, 100, 3), dtype=np.uint8),
-                        "image-2.png": np.zeros((100, 100, 3), dtype=np.uint8),
-                    },
+                    images=["image-1.png", "image-2.png"],
                     annotations={
                         "image-1.png": mock_detections(
                             xyxy=[[0, 0, 10, 10]], class_id=[0]
@@ -56,14 +52,11 @@ from test.test_utils import mock_detections
                         ),
                     },
                 ),
-                DetectionDataset(classes=[], images={}, annotations={}),
+                DetectionDataset(classes=[], images=[], annotations={}),
             ],
             DetectionDataset(
                 classes=["dog", "person"],
-                images={
-                    "image-1.png": np.zeros((100, 100, 3), dtype=np.uint8),
-                    "image-2.png": np.zeros((100, 100, 3), dtype=np.uint8),
-                },
+                images=["image-1.png", "image-2.png"],
                 annotations={
                     "image-1.png": mock_detections(xyxy=[[0, 0, 10, 10]], class_id=[0]),
                     "image-2.png": mock_detections(xyxy=[[0, 0, 10, 10]], class_id=[1]),
@@ -75,10 +68,7 @@ from test.test_utils import mock_detections
             [
                 DetectionDataset(
                     classes=["dog", "person"],
-                    images={
-                        "image-1.png": np.zeros((100, 100, 3), dtype=np.uint8),
-                        "image-2.png": np.zeros((100, 100, 3), dtype=np.uint8),
-                    },
+                    images=["image-1.png", "image-2.png"],
                     annotations={
                         "image-1.png": mock_detections(
                             xyxy=[[0, 0, 10, 10]], class_id=[0]
@@ -88,14 +78,11 @@ from test.test_utils import mock_detections
                         ),
                     },
                 ),
-                DetectionDataset(classes=["cat"], images={}, annotations={}),
+                DetectionDataset(classes=["cat"], images=[], annotations={}),
             ],
             DetectionDataset(
                 classes=["cat", "dog", "person"],
-                images={
-                    "image-1.png": np.zeros((100, 100, 3), dtype=np.uint8),
-                    "image-2.png": np.zeros((100, 100, 3), dtype=np.uint8),
-                },
+                images=["image-1.png", "image-2.png"],
                 annotations={
                     "image-1.png": mock_detections(xyxy=[[0, 0, 10, 10]], class_id=[1]),
                     "image-2.png": mock_detections(xyxy=[[0, 0, 10, 10]], class_id=[2]),
@@ -107,10 +94,7 @@ from test.test_utils import mock_detections
             [
                 DetectionDataset(
                     classes=["dog", "person"],
-                    images={
-                        "image-1.png": np.zeros((100, 100, 3), dtype=np.uint8),
-                        "image-2.png": np.zeros((100, 100, 3), dtype=np.uint8),
-                    },
+                    images=["image-1.png", "image-2.png"],
                     annotations={
                         "image-1.png": mock_detections(
                             xyxy=[[0, 0, 10, 10]], class_id=[0]
@@ -122,9 +106,7 @@ from test.test_utils import mock_detections
                 ),
                 DetectionDataset(
                     classes=["cat"],
-                    images={
-                        "image-3.png": np.zeros((100, 100, 3), dtype=np.uint8),
-                    },
+                    images=["image-3.png"],
                     annotations={
                         "image-3.png": mock_detections(
                             xyxy=[[0, 0, 10, 10]], class_id=[0]
@@ -134,11 +116,7 @@ from test.test_utils import mock_detections
             ],
             DetectionDataset(
                 classes=["cat", "dog", "person"],
-                images={
-                    "image-1.png": np.zeros((100, 100, 3), dtype=np.uint8),
-                    "image-2.png": np.zeros((100, 100, 3), dtype=np.uint8),
-                    "image-3.png": np.zeros((100, 100, 3), dtype=np.uint8),
-                },
+                images=["image-1.png", "image-2.png", "image-3.png"],
                 annotations={
                     "image-1.png": mock_detections(xyxy=[[0, 0, 10, 10]], class_id=[1]),
                     "image-2.png": mock_detections(xyxy=[[0, 0, 10, 10]], class_id=[2]),
@@ -151,10 +129,7 @@ from test.test_utils import mock_detections
             [
                 DetectionDataset(
                     classes=["dog", "person"],
-                    images={
-                        "image-1.png": np.zeros((100, 100, 3), dtype=np.uint8),
-                        "image-2.png": np.zeros((100, 100, 3), dtype=np.uint8),
-                    },
+                    images=["image-1.png", "image-2.png"],
                     annotations={
                         "image-1.png": mock_detections(
                             xyxy=[[0, 0, 10, 10]], class_id=[0]
@@ -166,10 +141,7 @@ from test.test_utils import mock_detections
                 ),
                 DetectionDataset(
                     classes=["dog", "person"],
-                    images={
-                        "image-2.png": np.zeros((100, 100, 3), dtype=np.uint8),
-                        "image-3.png": np.zeros((100, 100, 3), dtype=np.uint8),
-                    },
+                    images=["image-2.png", "image-3.png"],
                     annotations={
                         "image-2.png": mock_detections(
                             xyxy=[[0, 0, 10, 10]], class_id=[0]

test/dataset/test_utils.py

@@ -278,7 +278,7 @@ def test_map_detections_class_id(
             np.array([[[]]]).astype(bool),
             None,
             pytest.raises(AssertionError),
-        ),  # raises AssertionError because mask dimentionality is not 2D
+        ),  # raises AssertionError because mask dimensionality is not 2D
         (
             np.array([[]]).astype(bool),
             None,

test/detection/test_core.py

@@ -106,6 +106,26 @@ TEST_DET_DIFFERENT_DATA = Detections(
         "never_seen_key": [9],
     },
 )
+TEST_DET_WITH_METADATA = Detections(
+    xyxy=np.array([[10, 10, 20, 20]]),
+    class_id=np.array([1]),
+    metadata={"source": "camera1"},
+)
+
+TEST_DET_WITH_METADATA_2 = Detections(
+    xyxy=np.array([[30, 30, 40, 40]]),
+    class_id=np.array([2]),
+    metadata={"source": "camera1"},
+)
+TEST_DET_NO_METADATA = Detections(
+    xyxy=np.array([[10, 10, 20, 20]]),
+    class_id=np.array([1]),
+)
+TEST_DET_DIFFERENT_METADATA = Detections(
+    xyxy=np.array([[50, 50, 60, 60]]),
+    class_id=np.array([3]),
+    metadata={"source": "camera2"},
+)
 
 
 @pytest.mark.parametrize(
@@ -258,6 +278,11 @@ def test_getitem(
             TEST_DET_1,
             DoesNotRaise(),
         ),  # Single detection and empty-array fields
+        (
+            [TEST_DET_ZERO_LENGTH, TEST_DET_ZERO_LENGTH],
+            TEST_DET_ZERO_LENGTH,
+            DoesNotRaise(),
+        ),  # Zero-length fields across all Detections
         (
             [
                 TEST_DET_1,
@@ -287,12 +312,190 @@ def test_getitem(
                 Detections.empty(),
             ],
             mock_detections(
-                xyxy=[[10, 10, 20, 20]],
+                xyxy=np.array([[10, 10, 20, 20]]),
                 class_id=[1],
                 mask=[np.zeros((4, 4), dtype=bool)],
             ),
             DoesNotRaise(),
         ),  # Segmentation + Empty
+        # Metadata
+        (
+            [
+                Detections(
+                    xyxy=np.array([[10, 10, 20, 20]]),
+                    class_id=np.array([1]),
+                    metadata={"source": "camera1"},
+                ),
+                Detections.empty(),
+            ],
+            Detections(
+                xyxy=np.array([[10, 10, 20, 20]]),
+                class_id=np.array([1]),
+                metadata={"source": "camera1"},
+            ),
+            DoesNotRaise(),
+        ),  # Metadata merge with empty detections
+        (
+            [
+                Detections(
+                    xyxy=np.array([[10, 10, 20, 20]]),
+                    class_id=np.array([1]),
+                    metadata={"source": "camera1"},
+                ),
+                Detections(xyxy=np.array([[30, 30, 40, 40]]), class_id=np.array([2])),
+            ],
+            None,
+            pytest.raises(ValueError),
+        ),  # Empty and non-empty metadata
+        (
+            [
+                Detections(
+                    xyxy=np.array([[10, 10, 20, 20]]),
+                    class_id=np.array([1]),
+                    metadata={"source": "camera1"},
+                )
+            ],
+            Detections(
+                xyxy=np.array([[10, 10, 20, 20]]),
+                class_id=np.array([1]),
+                metadata={"source": "camera1"},
+            ),
+            DoesNotRaise(),
+        ),  # Single detection with metadata
+        (
+            [
+                Detections(
+                    xyxy=np.array([[10, 10, 20, 20]]),
+                    class_id=np.array([1]),
+                    metadata={"source": "camera1"},
+                ),
+                Detections(
+                    xyxy=np.array([[30, 30, 40, 40]]),
+                    class_id=np.array([2]),
+                    metadata={"source": "camera1"},
+                ),
+            ],
+            Detections(
+                xyxy=np.array([[10, 10, 20, 20], [30, 30, 40, 40]]),
+                class_id=np.array([1, 2]),
+                metadata={"source": "camera1"},
+            ),
+            DoesNotRaise(),
+        ),  # Multiple metadata entries with identical values
+        (
+            [
+                Detections(
+                    xyxy=np.array([[10, 10, 20, 20]]),
+                    class_id=np.array([1]),
+                    metadata={"source": "camera1"},
+                ),
+                Detections(
+                    xyxy=np.array([[50, 50, 60, 60]]),
+                    class_id=np.array([3]),
+                    metadata={"source": "camera2"},
+                ),
+            ],
+            None,
+            pytest.raises(ValueError),
+        ),  # Different metadata values
+        (
+            [
+                Detections(
+                    xyxy=np.array([[10, 10, 20, 20]]),
+                    metadata={"source": "camera1", "resolution": "1080p"},
+                ),
+                Detections(
+                    xyxy=np.array([[30, 30, 40, 40]]),
+                    metadata={"source": "camera1", "resolution": "1080p"},
+                ),
+            ],
+            Detections(
+                xyxy=np.array([[10, 10, 20, 20], [30, 30, 40, 40]]),
+                metadata={"source": "camera1", "resolution": "1080p"},
+            ),
+            DoesNotRaise(),
+        ),  # Large metadata with multiple identical entries
+        (
+            [
+                Detections(
+                    xyxy=np.array([[10, 10, 20, 20]]), metadata={"source": "camera1"}
+                ),
+                Detections(
+                    xyxy=np.array([[30, 30, 40, 40]]), metadata={"source": ["camera1"]}
+                ),
+            ],
+            None,
+            pytest.raises(ValueError),
+        ),  # Inconsistent types in metadata values
+        (
+            [
+                Detections(
+                    xyxy=np.array([[10, 10, 20, 20]]), metadata={"source": "camera1"}
+                ),
+                Detections(
+                    xyxy=np.array([[30, 30, 40, 40]]), metadata={"location": "indoor"}
+                ),
+            ],
+            None,
+            pytest.raises(ValueError),
+        ),  # Metadata key mismatch
+        (
+            [
+                Detections(
+                    xyxy=np.array([[10, 10, 20, 20]]),
+                    metadata={
+                        "source": "camera1",
+                        "settings": {"resolution": "1080p", "fps": 30},
+                    },
+                ),
+                Detections(
+                    xyxy=np.array([[30, 30, 40, 40]]),
+                    metadata={
+                        "source": "camera1",
+                        "settings": {"resolution": "1080p", "fps": 30},
+                    },
+                ),
+            ],
+            Detections(
+                xyxy=np.array([[10, 10, 20, 20], [30, 30, 40, 40]]),
+                metadata={
+                    "source": "camera1",
+                    "settings": {"resolution": "1080p", "fps": 30},
+                },
+            ),
+            DoesNotRaise(),
+        ),  # multi-field metadata
+        (
+            [
+                Detections(
+                    xyxy=np.array([[10, 10, 20, 20]]),
+                    metadata={"calibration_matrix": np.array([[1, 0], [0, 1]])},
+                ),
+                Detections(
+                    xyxy=np.array([[30, 30, 40, 40]]),
+                    metadata={"calibration_matrix": np.array([[1, 0], [0, 1]])},
+                ),
+            ],
+            Detections(
+                xyxy=np.array([[10, 10, 20, 20], [30, 30, 40, 40]]),
+                metadata={"calibration_matrix": np.array([[1, 0], [0, 1]])},
+            ),
+            DoesNotRaise(),
+        ),  # Identical 2D numpy arrays in metadata
+        (
+            [
+                Detections(
+                    xyxy=np.array([[10, 10, 20, 20]]),
+                    metadata={"calibration_matrix": np.array([[1, 0], [0, 1]])},
+                ),
+                Detections(
+                    xyxy=np.array([[30, 30, 40, 40]]),
+                    metadata={"calibration_matrix": np.array([[2, 0], [0, 2]])},
+                ),
+            ],
+            None,
+            pytest.raises(ValueError),
+        ),  # Mismatching 2D numpy arrays in metadata
     ],
 )
 def test_merge(
@@ -302,7 +505,7 @@ def test_merge(
 ) -> None:
     with exception:
         result = Detections.merge(detections_list=detections_list)
-        assert result == expected_result
+        assert result == expected_result, f"Expected: {expected_result}, Got: {result}"
 
 
 @pytest.mark.parametrize(

test/detection/test_line_counter.py

@@ -69,7 +69,7 @@ def test_calculate_region_of_interest_limits(
     exception: Exception,
 ) -> None:
     with exception:
-        result = LineZone.calculate_region_of_interest_limits(vector=vector)
+        result = LineZone._calculate_region_of_interest_limits(vector=vector)
         assert result == expected_result
 
 
@@ -303,6 +303,19 @@ def test_line_zone_one_detection_default_anchors(
             [False, True, False, True],
             [False, False, True, False],
         ),
+        (  # Scrape line, left side, center anchor (along line point)
+            Vector(Point(0, 0), Point(10, 0)),
+            [
+                [-2, 4, 2, 6],
+                [-2, 4 - 10, 2, 6 - 10],
+                [-2, 4, 2, 6],
+                [-2, 4 - 10, 2, 6 - 10],
+                [-2, 4 - 10, 2, 6 - 10],
+            ],
+            [Position.CENTER],
+            [False, True, False, True, False],
+            [False, False, True, False, False],
+        ),
         (  # Scrape line, right side, corner anchors
             Vector(Point(0, 0), Point(10, 0)),
             [
@@ -477,3 +490,289 @@ def test_line_zone_multiple_detections(
 
         assert crossed_in_list == expected_crossed_in
         assert crossed_out_list == expected_crossed_out
+
+
+@pytest.mark.parametrize(
+    "vector, xyxy_sequence, triggering_anchors, minimum_crossing_threshold, "
+    "expected_crossed_in, expected_crossed_out",
+    [
+        (  # Detection lingers around line, all crosses counted
+            Vector(Point(0, 0), Point(10, 0)),
+            [
+                [2, 4, 3, 6],
+                [2, 4 - 10, 3, 6],
+                [2, 4, 3, 6],
+                [2, 4 - 10, 3, 6],
+                [2, 4 - 10, 3, 6],
+            ],
+            [
+                Position.TOP_LEFT,
+            ],
+            1,
+            [False, True, False, True, False],
+            [False, False, True, False, False],
+        ),
+        (  # Detection lingers around line, only final cross counted
+            Vector(Point(0, 0), Point(10, 0)),
+            [
+                [2, 4, 3, 6],
+                [2, 4 - 10, 3, 6],
+                [2, 4, 3, 6],
+                [2, 4 - 10, 3, 6],
+                [2, 4 - 10, 3, 6],
+            ],
+            [
+                Position.TOP_LEFT,
+            ],
+            2,
+            [False, False, False, False, True],
+            [False, False, False, False, False],
+        ),
+        (  # Detection lingers around line for a long time
+            Vector(Point(0, 0), Point(10, 0)),
+            [
+                [2, 4, 3, 6],
+                [2, 4 - 10, 3, 6],
+                [2, 4, 3, 6],
+                [2, 4 - 10, 3, 6],
+                [2, 4, 3, 6],
+                [2, 4 - 10, 3, 6],
+                [2, 4, 3, 6],
+                [2, 4 - 10, 3, 6],
+                [2, 4, 3, 6],
+                [2, 4 - 10, 3, 6],
+                [2, 4, 3, 6],
+                [2, 4 - 10, 3, 6],
+                [2, 4 - 10, 3, 6],
+            ],
+            [
+                Position.TOP_LEFT,
+            ],
+            2,
+            [False] * 12 + [True],
+            [False] * 13,
+        ),
+        (  # Detection lingers around line, longer cycle
+            Vector(Point(0, 0), Point(10, 0)),
+            [
+                [2, 4, 3, 6],
+                [2, 4 - 10, 3, 6],
+                [2, 4, 3, 6],
+                [2, 4, 3, 6],
+                [2, 4, 3, 6],
+                [2, 4 - 10, 3, 6],
+                [2, 4 - 10, 3, 6],
+                [2, 4 - 10, 3, 6],
+                [2, 4 - 10, 3, 6],
+            ],
+            [
+                Position.TOP_LEFT,
+            ],
+            4,
+            [False] * 8 + [True],
+            [False] * 9,
+        ),
+    ],
+)
+def test_line_zone_one_detection_long_horizon(
+    vector: Vector,
+    xyxy_sequence: List[List[float]],
+    triggering_anchors: List[Position],
+    minimum_crossing_threshold: int,
+    expected_crossed_in: List[bool],
+    expected_crossed_out: List[bool],
+) -> None:
+    line_zone = LineZone(
+        start=vector.start,
+        end=vector.end,
+        triggering_anchors=triggering_anchors,
+        minimum_crossing_threshold=minimum_crossing_threshold,
+    )
+
+    crossed_in_list = []
+    crossed_out_list = []
+    for i, bbox in enumerate(xyxy_sequence):
+        detections = mock_detections(
+            xyxy=[bbox],
+            tracker_id=[0],
+        )
+        crossed_in, crossed_out = line_zone.trigger(detections)
+        crossed_in_list.append(crossed_in[0])
+        crossed_out_list.append(crossed_out[0])
+
+    assert (
+        crossed_in_list == expected_crossed_in
+    ), f"expected {expected_crossed_in}, got {crossed_in_list}"
+    assert (
+        crossed_out_list == expected_crossed_out
+    ), f"expected {expected_crossed_out}, got {crossed_out_list}"
+
+
+@pytest.mark.parametrize(
+    "vector, xyxy_sequence, anchors, minimum_crossing_threshold, "
+    "expected_crossed_in, expected_crossed_out, expected_count_in, "
+    "expected_count_out, exception",
+    [
+        (  # One stays, one crosses, one disappears before crossing
+            Vector(Point(0, 0), Point(10, 0)),
+            [
+                [[4, 4, 6, 6], [4, 4, 6, 6], [4, 4, 6, 6]],
+                [[4, 4, 6, 6], [4, 4 - 10, 6, 6 - 10], [4, 4, 6, 6]],
+                [[4, 4, 6, 6], [4, 4, 6, 6]],
+                [[4, 4, 6, 6], [4, 4 - 10, 6, 6 - 10]],
+                [[4, 4, 6, 6], [4, 4 - 10, 6, 6 - 10]],
+            ],
+            [
+                Position.TOP_LEFT,
+            ],
+            1,
+            [
+                [False, False, False],
+                [False, True, False],
+                [False, False],
+                [False, True],
+                [False, False],
+            ],
+            [
+                [False, False, False],
+                [False, False, False],
+                [False, True],
+                [False, False],
+                [False, False],
+            ],
+            [0, 1, 1, 2, 2],
+            [0, 0, 1, 1, 1],
+            DoesNotRaise(),
+        ),
+        (  # One stays, one crosses, one disappears immediately after crossing
+            Vector(Point(0, 0), Point(10, 0)),
+            [
+                [[4, 4, 6, 6], [4, 4, 6, 6], [4, 4, 6, 6]],
+                [[4, 4, 6, 6], [4, 4 - 10, 6, 6 - 10], [4, 4, 6, 6]],
+                [[4, 4, 6, 6], [4, 4, 6, 6], [4, 4 - 10, 6, 6 - 10]],
+                [[4, 4, 6, 6], [4, 4 - 10, 6, 6 - 10]],
+                [[4, 4, 6, 6], [4, 4 - 10, 6, 6 - 10]],
+            ],
+            [
+                Position.TOP_LEFT,
+            ],
+            1,
+            [
+                [False, False, False],
+                [False, True, False],
+                [False, False, True],
+                [False, True],
+                [False, False],
+            ],
+            [
+                [False, False, False],
+                [False, False, False],
+                [False, True, False],
+                [False, False],
+                [False, False],
+            ],
+            [0, 1, 2, 3, 3],
+            [0, 0, 1, 1, 1],
+            DoesNotRaise(),
+        ),
+        (  # One stays, one crosses, one disappears before crossing
+            Vector(Point(0, 0), Point(10, 0)),
+            [
+                [[4, 4, 6, 6], [4, 4, 6, 6], [4, 4, 6, 6]],
+                [[4, 4, 6, 6], [4, 4 - 10, 6, 6 - 10], [4, 4, 6, 6]],
+                [[4, 4, 6, 6], [4, 4, 6, 6]],
+                [[4, 4, 6, 6], [4, 4 - 10, 6, 6 - 10]],
+                [[4, 4, 6, 6], [4, 4 - 10, 6, 6 - 10]],
+            ],
+            [
+                Position.TOP_LEFT,
+            ],
+            2,
+            [
+                [False, False, False],
+                [False, False, False],
+                [False, False],
+                [False, False],
+                [False, True],
+            ],
+            [
+                [False, False, False],
+                [False, False, False],
+                [False, False],
+                [False, False],
+                [False, False],
+            ],
+            [0, 0, 0, 0, 1],
+            [0, 0, 0, 0, 0],
+            DoesNotRaise(),
+        ),
+        (  # One stays, one crosses, one disappears immediately after crossing
+            Vector(Point(0, 0), Point(10, 0)),
+            [
+                [[4, 4, 6, 6], [4, 4, 6, 6], [4, 4, 6, 6]],
+                [[4, 4, 6, 6], [4, 4 - 10, 6, 6 - 10], [4, 4, 6, 6]],
+                [[4, 4, 6, 6], [4, 4, 6, 6], [4, 4 - 10, 6, 6 - 10]],
+                [[4, 4, 6, 6], [4, 4 - 10, 6, 6 - 10]],
+                [[4, 4, 6, 6], [4, 4 - 10, 6, 6 - 10]],
+            ],
+            [
+                Position.TOP_LEFT,
+            ],
+            2,
+            [
+                [False, False, False],
+                [False, False, False],
+                [False, False, False],
+                [False, False],
+                [False, True],
+            ],
+            [
+                [False, False, False],
+                [False, False, False],
+                [False, False, False],
+                [False, False],
+                [False, False],
+            ],
+            [0, 0, 0, 0, 1],
+            [0, 0, 0, 0, 0],
+            DoesNotRaise(),
+        ),
+    ],
+)
+def test_line_zone_long_horizon_disappearing_detections(
+    vector: Vector,
+    xyxy_sequence: List[List[Optional[List[float]]]],
+    anchors: List[Position],
+    minimum_crossing_threshold: int,
+    expected_crossed_in: List[List[bool]],
+    expected_crossed_out: List[List[bool]],
+    expected_count_in: List[int],
+    expected_count_out: List[int],
+    exception: Exception,
+) -> None:
+    with exception:
+        line_zone = LineZone(
+            start=vector.start,
+            end=vector.end,
+            triggering_anchors=anchors,
+            minimum_crossing_threshold=minimum_crossing_threshold,
+        )
+        crossed_in_list = []
+        crossed_out_list = []
+        count_in_list = []
+        count_out_list = []
+        for bboxes in xyxy_sequence:
+            detections = mock_detections(
+                xyxy=bboxes,
+                tracker_id=[i for i in range(0, len(bboxes))],
+            )
+            crossed_in, crossed_out = line_zone.trigger(detections)
+            crossed_in_list.append(list(crossed_in))
+            crossed_out_list.append(list(crossed_out))
+            count_in_list.append(line_zone.in_count)
+            count_out_list.append(line_zone.out_count)
+
+        assert crossed_in_list == expected_crossed_in
+        assert crossed_out_list == expected_crossed_out
+        assert count_in_list == expected_count_in
+        assert count_out_list == expected_count_out

test/detection/test_polygon_zone_annotator.py

@@ -0,0 +1,60 @@
+import numpy as np
+import pytest
+
+import supervision as sv
+
+COLOR = sv.Color(r=255, g=0, b=0)
+THICKNESS = 2
+POLYGON = np.array([[100, 100], [200, 100], [200, 200], [100, 200]])
+SCENE = np.random.randint(0, 255, (1000, 1000, 3), dtype=np.uint8)
+ANNOTATED_SCENE_NO_OPACITY = sv.draw_polygon(
+    scene=SCENE.copy(),
+    polygon=POLYGON,
+    color=COLOR,
+    thickness=THICKNESS,
+)
+ANNOTATED_SCENE_0_5_OPACITY = sv.draw_filled_polygon(
+    scene=ANNOTATED_SCENE_NO_OPACITY.copy(),
+    polygon=POLYGON,
+    color=COLOR,
+    opacity=0.5,
+)
+
+
+@pytest.mark.parametrize(
+    "scene, polygon_zone_annotator, expected_results",
+    [
+        (
+            SCENE,
+            sv.PolygonZoneAnnotator(
+                zone=sv.PolygonZone(
+                    POLYGON,
+                ),
+                color=COLOR,
+                thickness=THICKNESS,
+                display_in_zone_count=False,
+            ),
+            ANNOTATED_SCENE_NO_OPACITY,
+        ),  # Test no opacity (default)
+        (
+            SCENE,
+            sv.PolygonZoneAnnotator(
+                zone=sv.PolygonZone(
+                    POLYGON,
+                ),
+                color=COLOR,
+                thickness=THICKNESS,
+                display_in_zone_count=False,
+                opacity=0.5,
+            ),
+            ANNOTATED_SCENE_0_5_OPACITY,
+        ),  # Test 10% opacity
+    ],
+)
+def test_polygon_zone_annotator(
+    scene: np.ndarray,
+    polygon_zone_annotator: sv.PolygonZoneAnnotator,
+    expected_results: np.ndarray,
+) -> None:
+    annotated_scene = polygon_zone_annotator.annotate(scene=scene)
+    assert np.all(annotated_scene == expected_results)

test/detection/test_polygonzone.py

@@ -26,7 +26,6 @@ DETECTIONS = mock_detections(
 )
 
 POLYGON = np.array([[100, 100], [200, 100], [200, 200], [100, 200]])
-FRAME_RESOLUTION = (300, 300)
 
 
 @pytest.mark.parametrize(
@@ -36,7 +35,6 @@ FRAME_RESOLUTION = (300, 300)
             DETECTIONS,
             sv.PolygonZone(
                 POLYGON,
-                FRAME_RESOLUTION,
                 triggering_anchors=(
                     sv.Position.TOP_LEFT,
                     sv.Position.TOP_RIGHT,
@@ -53,7 +51,6 @@ FRAME_RESOLUTION = (300, 300)
             DETECTIONS,
             sv.PolygonZone(
                 POLYGON,
-                FRAME_RESOLUTION,
             ),
             np.array(
                 [False, False, True, True, True, True, False, False, False], dtype=bool
@@ -64,7 +61,6 @@ FRAME_RESOLUTION = (300, 300)
             DETECTIONS,
             sv.PolygonZone(
                 POLYGON,
-                FRAME_RESOLUTION,
                 triggering_anchors=[sv.Position.BOTTOM_CENTER],
             ),
             np.array(
@@ -76,7 +72,6 @@ FRAME_RESOLUTION = (300, 300)
             sv.Detections.empty(),
             sv.PolygonZone(
                 POLYGON,
-                FRAME_RESOLUTION,
             ),
             np.array([], dtype=bool),
             DoesNotRaise(),
@@ -107,4 +102,4 @@ def test_polygon_zone_trigger(
 )
 def test_polygon_zone_initialization(polygon, triggering_anchors, exception):
     with exception:
-        sv.PolygonZone(polygon, FRAME_RESOLUTION, triggering_anchors=triggering_anchors)
+        sv.PolygonZone(polygon, triggering_anchors=triggering_anchors)