Merge pull request #2005 from roboflow/develop

supervision-0.27.0 release

.github/CODEOWNERS

@@ -1,4 +1,4 @@
 # These owners will be the default owners for everything in
 # the repo. They will be requested for review when someone
 # opens a pull request.
-*   @SkalskiP @onuralpszr
+*   @SkalskiP @soumik12345

.github/workflows/clear-cache.yml

@@ -16,7 +16,7 @@ jobs:
     timeout-minutes: 10
     steps:
       - name: Clear cache
-        uses: actions/github-script@60a0d83039c74a4aee543508d2ffcb1c3799cdea # v7.0.1
+        uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8.0.0
         with:
           script: |
             console.log("Starting cache cleanup...")

.github/workflows/publish-docs.yml

@@ -34,13 +34,15 @@ jobs:
           fetch-depth: 0
 
       - name: 🐍 Install uv and set Python ${{ matrix.python-version }}
-        uses: astral-sh/setup-uv@d4b2f3b6ecc6e67c4457f6d3e41ec42d3d0fcb86 # v5.4.2
+        uses: astral-sh/setup-uv@85856786d1ce8acfbcc2f13a5f3fbd6b938f9f41 # v7.1.2
         with:
           python-version: ${{ matrix.python-version }}
+          activate-environment: true
+
 
       - name: 🔑 Create GitHub App token (mkdocs)
         id: mkdocs_token
-        uses: actions/create-github-app-token@3ff1caaa28b64c9cc276ce0a02e2ff584f3900c5 # v2.0.2
+        uses: actions/create-github-app-token@df432ceedc7162793a195dd1713ff69aefc7379e # v2.0.6
         with:
           app-id: ${{ secrets.MKDOCS_APP_ID }}
           private-key: ${{ secrets.MKDOCS_PEM }}
@@ -49,7 +51,7 @@ jobs:
 
       - name: 🏗️ Install dependencies
         run: |
-          uv pip install -r pyproject.toml --extra docs
+          uv pip install -r pyproject.toml --group docs
           # Install mkdocs-material-insiders using the GitHub App token
           uv pip install "git+https://roboflow:${{ steps.mkdocs_token.outputs.token }}@github.com/roboflow/mkdocs-material-insiders.git@9.5.49-insiders-4.53.14#egg=mkdocs-material[imaging]"
 

.github/workflows/publish-pre-release.yml

@@ -29,17 +29,19 @@ jobs:
         uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
 
       - name: 🐍 Install uv and set Python version ${{ matrix.python-version }}
-        uses: astral-sh/setup-uv@d4b2f3b6ecc6e67c4457f6d3e41ec42d3d0fcb86 # v5.4.2
+        uses: astral-sh/setup-uv@85856786d1ce8acfbcc2f13a5f3fbd6b938f9f41 # v7.1.2
         with:
           python-version: ${{ matrix.python-version }}
+          activate-environment: true
+
 
       - name: 🏗️ Build source and wheel distributions
         run: |
-          uv pip install -r pyproject.toml --extra build
+          uv pip install -r pyproject.toml --group build
           uv build
           uv run twine check --strict dist/*
 
       - name: 🚀 Publish to PyPi
-        uses: pypa/gh-action-pypi-publish@76f52bc884231f62b9a034ebfe128415bbaabdfc # v1.12.4
+        uses: pypa/gh-action-pypi-publish@ed0c53931b1dc9bd32cbe73a98c7f6766f8a527e # v1.13.0
         with:
           attestations: true

.github/workflows/publish-release.yml

@@ -27,17 +27,19 @@ jobs:
         uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
 
       - name: 🐍 Install uv and set Python version ${{ matrix.python-version }}
-        uses: astral-sh/setup-uv@d4b2f3b6ecc6e67c4457f6d3e41ec42d3d0fcb86 # v5.4.2
+        uses: astral-sh/setup-uv@85856786d1ce8acfbcc2f13a5f3fbd6b938f9f41 # v7.1.2
         with:
           python-version: ${{ matrix.python-version }}
+          activate-environment: true
+
 
       - name: 🏗️ Build source and wheel distributions
         run: |
-          uv pip install -r pyproject.toml --extra build
+          uv pip install -r pyproject.toml --group build
           uv build
           uv run twine check --strict dist/*
 
       - name: 🚀 Publish to PyPi
-        uses: pypa/gh-action-pypi-publish@76f52bc884231f62b9a034ebfe128415bbaabdfc # v1.12.4
+        uses: pypa/gh-action-pypi-publish@ed0c53931b1dc9bd32cbe73a98c7f6766f8a527e # v1.13.0
         with:
           attestations: true

.github/workflows/publish-testpypi.yml

@@ -24,18 +24,20 @@ jobs:
         uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
 
       - name: 🐍 Install uv and set Python version ${{ matrix.python-version }}
-        uses: astral-sh/setup-uv@d4b2f3b6ecc6e67c4457f6d3e41ec42d3d0fcb86 # v5.4.2
+        uses: astral-sh/setup-uv@85856786d1ce8acfbcc2f13a5f3fbd6b938f9f41 # v7.1.2
         with:
           python-version: ${{ matrix.python-version }}
+          activate-environment: true
+
 
       - name: 🏗️ Build source and wheel distributions
         run: |
-          uv pip install -r pyproject.toml --extra build
+          uv pip install -r pyproject.toml --group build
           uv build
           uv run twine check --strict dist/*
 
       - name: 🚀 Publish to Test-PyPi
-        uses: pypa/gh-action-pypi-publish@76f52bc884231f62b9a034ebfe128415bbaabdfc # v1.12.4
+        uses: pypa/gh-action-pypi-publish@ed0c53931b1dc9bd32cbe73a98c7f6766f8a527e # v1.13.0
         with:
           repository-url: https://test.pypi.org/legacy/
           attestations: true

.github/workflows/test-doc.yml

@@ -24,14 +24,14 @@ jobs:
           fetch-depth: 0
 
       - name: 🐍 Install uv and set Python ${{ matrix.python-version }}
-        uses: astral-sh/setup-uv@d4b2f3b6ecc6e67c4457f6d3e41ec42d3d0fcb86 # v5.4.2
+        uses: astral-sh/setup-uv@85856786d1ce8acfbcc2f13a5f3fbd6b938f9f41 # v7.1.2
         with:
           python-version: ${{ matrix.python-version }}
+          activate-environment: true
 
       - name: 🏗️ Install dependencies
         run: |
-          uv pip install -r pyproject.toml --extra docs
-
+          uv pip install -r pyproject.toml --group docs
 
       - name: 🧪 Test Docs Build
         run: uv run mkdocs build --verbose

.github/workflows/uv-test.yml

@@ -12,19 +12,21 @@ jobs:
       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"]
+        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
     runs-on: ${{ matrix.os }}
     steps:
       - name: 📥 Checkout the repository
         uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
 
       - name: 🐍 Install uv and set Python version ${{ matrix.python-version }}
-        uses: astral-sh/setup-uv@d4b2f3b6ecc6e67c4457f6d3e41ec42d3d0fcb86 # v5.4.2
+        uses: astral-sh/setup-uv@85856786d1ce8acfbcc2f13a5f3fbd6b938f9f41 # v7.1.2
         with:
           python-version: ${{ matrix.python-version }}
+          activate-environment: true
+
 
       - name: 🚀 Install Packages
-        run: uv pip install -r pyproject.toml --extra dev --extra docs --extra metrics
+        run: uv pip install -r pyproject.toml --group dev --group docs --extra metrics
 
       - name: 🧪 Run the Import test
         run: uv run python -c "import supervision; from supervision import assets; from supervision import metrics; print(supervision.__version__)"

.pre-commit-config.yaml

@@ -25,14 +25,14 @@ repos:
       - id: mixed-line-ending
 
   -   repo: https://github.com/PyCQA/bandit
-      rev: '1.8.3'
+      rev: '1.8.6'
       hooks:
       -   id: bandit
           args: ["-c", "pyproject.toml"]
           additional_dependencies: ["bandit[toml]"]
 
   -   repo: https://github.com/astral-sh/ruff-pre-commit
-      rev: v0.11.6
+      rev: v0.12.5
       hooks:
       -   id: ruff
           args: [--fix, --exit-non-zero-on-fix]
@@ -53,3 +53,11 @@ repos:
       - id: codespell
         additional_dependencies:
           - tomli
+
+  - repo: https://github.com/asottile/pyupgrade
+    rev: v3.20.0
+    hooks:
+    -   id: pyupgrade
+        args: ["--py310-plus"]
+        additional_dependencies:
+          - tomli

README.md

@@ -37,7 +37,7 @@
 ## 💻 install
 
 Pip install the supervision package in a
-[**Python>=3.8**](https://www.python.org/) environment.
+[**Python>=3.9**](https://www.python.org/) environment.
 
 ```bash
 pip install supervision

docs/changelog.md

@@ -1,4 +1,259 @@
-# CHANGELOG
+# Changelog
+
+### 0.27.0 <small>Nov 16, 2025</small>
+
+- Added [#2008](https://github.com/roboflow/supervision/pull/2008): [`sv.filter_segments_by_distance`](https://supervision.roboflow.com/0.27.0/detection/utils/masks/#supervision.detection.utils.masks.filter_segments_by_distance) to keep the largest connected component and nearby components within an absolute or relative distance threshold. Useful for cleaning segmentation predictions from models such as SAM, SAM2, YOLO segmentation, and RF-DETR segmentation.
+
+- Added [#2006](https://github.com/roboflow/supervision/pull/2006): [`sv.xyxy_to_mask`](https://supervision.roboflow.com/0.27.0/detection/utils/converters/#supervision.detection.utils.converters.xyxy_to_mask) to convert bounding boxes into 2D boolean masks, where each mask corresponds to a single box.
+
+- Added [#1943](https://github.com/roboflow/supervision/pull/1943): [`sv.tint_image`](https://supervision.roboflow.com/0.27.0/utils/image/#supervision.utils.image.tint_image) to apply a solid color overlay to an image at a given opacity. Works with both NumPy and PIL inputs.
+
+- Added [#1943](https://github.com/roboflow/supervision/pull/1943): [`sv.grayscale_image`](https://supervision.roboflow.com/0.27.0/utils/image/#supervision.utils.image.tint_image) to convert an image to 3 channel grayscale for compatibility with color based drawing utilities.
+
+- Added [#2014](https://github.com/roboflow/supervision/pull/2014): [`sv.get_image_resolution_wh`](https://supervision.roboflow.com/0.27.0/utils/image/#supervision.utils.image.get_image_resolution_wh) as a unified way to read image width and height from NumPy and PIL inputs.
+
+- Added [#1912](https://github.com/roboflow/supervision/pull/1912): [`sv.edit_distance`](https://supervision.roboflow.com/0.27.0/detection/utils/vlms/#supervision.detection.utils.vlms.edit_distance) for Levenshtein distance between two strings. Supports insert, delete, and substitute operations.
+
+- Added [#1912](https://github.com/roboflow/supervision/pull/1912): [`sv.fuzzy_match_index`](https://supervision.roboflow.com/0.27.0/detection/utils/vlms/#supervision.detection.utils.vlms.fuzzy_match_index) to find the first close match in a list using edit distance.
+
+- Changed [#2015](https://github.com/roboflow/supervision/pull/2015): [`sv.Detections.from_vlm`](https://supervision.roboflow.com/0.27.0/detection/core/#supervision.detection.core.Detections.from_vlm) and legacy `from_lmm` now support Qwen3 VL via `vlm=sv.VLM.QWEN_3_VL`.
+
+- Changed [#1884](https://github.com/roboflow/supervision/pull/1884): [`sv.Detections.from_vlm`](https://supervision.roboflow.com/0.27.0/detection/core/#supervision.detection.core.Detections.from_vlm) and legacy `from_lmm` now support DeepSeek VL 2 via `vlm=sv.VLM.DEEPSEEK_VL_2`.
+
+- Changed [#2015](https://github.com/roboflow/supervision/pull/2015): [`sv.Detections.from_vlm`](https://supervision.roboflow.com/0.27.0/detection/core/#supervision.detection.core.Detections.from_vlm) now parses Qwen 2.5 VL outputs more robustly and handles incomplete or truncated JSON responses.
+
+- Changed [#2014](https://github.com/roboflow/supervision/pull/2014): [`sv.InferenceSlicer`](https://supervision.roboflow.com/0.27.0/detection/tools/inference_slicer/#supervision.detection.tools.inference_slicer.InferenceSlicer) now uses a new offset generation logic that removes redundant tiles and aligns borders cleanly. This reduces the number of processed tiles and shortens inference time without hurting detection quality.
+
+- Changed [#2016](https://github.com/roboflow/supervision/pull/2016): [`sv.Detections`](https://supervision.roboflow.com/0.27.0/detection/core/#supervision.detection.core.Detections) now includes a `box_aspect_ratio` property for vectorized aspect ratio computation, useful for filtering detections based on box shape.
+
+- Changed [#2001](https://github.com/roboflow/supervision/pull/2001): Significantly improved the performance of [`sv.box_iou_batch`](https://supervision.roboflow.com/0.27.0/detection/utils/iou_and_nms/#supervision.detection.utils.iou_and_nms.box_iou_batch). On internal benchmarks, processing runs approximately 2x to 5x faster.
+
+- Changed [#1997](https://github.com/roboflow/supervision/pull/1997): [`sv.process_video`](https://supervision.roboflow.com/0.27.0/utils/video/#supervision.utils.video.process_video) now uses a threaded reader, processor, and writer pipeline. This removes I/O stalls and improves throughput while keeping the callback single threaded and safe for stateful models.
+
+- Changed: [`sv.denormalize_boxes`](https://supervision.roboflow.com/0.27.0/detection/utils/boxes/#supervision.detection.utils.boxes.denormalize_boxes) now supports batch conversion of bounding boxes. The function accepts arrays of shape `(N, 4)` and returns a batch of absolute pixel coordinates.
+
+- Changed [#1917](https://github.com/roboflow/supervision/pull/1917): [`sv.LabelAnnotator`](https://supervision.roboflow.com/develop/0.27.0/annotators/#supervision.annotators.core.LabelAnnotator) and [`sv.RichLabelAnnotator`](https://supervision.roboflow.com/develop/0.27.0/annotators/#supervision.annotators.core.LabelAnnotator) now accept `text_offset=(x, y)` to shift the label relative to `text_position`. Works with smart label position and line wrapping.
+
+!!! failure "Removed"
+    Removed the deprecated `overlap_ratio_wh` argument from `sv.InferenceSlicer`. Use the pixel based `overlap_wh` argument to control slice overlap.
+
+!!! info "Tip"
+    Convert your old ratio based overlap to pixel based overlap by multiplying each ratio by the slice dimensions.
+
+    ```python
+    # before
+
+    slice_wh = (640, 640)
+    overlap_ratio_wh = (0.25, 0.25)
+
+    slicer = sv.InferenceSlicer(
+        callback=callback,
+        slice_wh=slice_wh,
+        overlap_ratio_wh=overlap_ratio_wh,
+        overlap_filter=sv.OverlapFilter.NON_MAX_SUPPRESSION,
+    )
+
+    # after
+
+    overlap_wh = (
+        int(overlap_ratio_wh[0] * slice_wh[0]),
+        int(overlap_ratio_wh[1] * slice_wh[1]),
+    )
+
+    slicer = sv.InferenceSlicer(
+        callback=callback,
+        slice_wh=slice_wh,
+        overlap_wh=overlap_wh,
+        overlap_filter=sv.OverlapFilter.NON_MAX_SUPPRESSION,
+    )
+    ```
+
+### 0.26.1 <small>Jul 22, 2025</small>
+
+- Fixed [1894](https://github.com/roboflow/supervision/pull/1894): Error in [`sv.MeanAveragePrecision`](https://supervision.roboflow.com/0.26.1/metrics/mean_average_precision/#supervision.metrics.mean_average_precision.MeanAveragePrecision) where the area used for size-specific evaluation (small / medium / large) was always zero unless explicitly provided in `sv.Detections.data`.
+
+- Fixed [1895](https://github.com/roboflow/supervision/pull/1895): `ID=0` bug in [`sv.MeanAveragePrecision`](https://supervision.roboflow.com/0.26.1/metrics/mean_average_precision/#supervision.metrics.mean_average_precision.MeanAveragePrecision) where objects were getting `0.0` mAP despite perfect IoU matches due to a bug in annotation ID assignment.
+
+- Fixed [1898](https://github.com/roboflow/supervision/pull/1898): Issue where [`sv.MeanAveragePrecision`](https://supervision.roboflow.com/0.26.1/metrics/mean_average_precision/#supervision.metrics.mean_average_precision.MeanAveragePrecision) could return negative values when certain object size categories have no data.
+
+- Fixed [1901](https://github.com/roboflow/supervision/pull/1901): `match_metric` support for [`sv.Detections.with_nms`](https://supervision.roboflow.com/0.26.1/metrics/mean_average_precision/#supervision.detection.core.Detections.with_nms).
+
+- Fixed [1906](https://github.com/roboflow/supervision/pull/1906): `border_thickness` parameter usage for [`sv.PercentageBarAnnotator`](https://supervision.roboflow.com/0.26.1/metrics/mean_average_precision/#supervision.annotators.core.PercentageBarAnnotator).
+
+### 0.26.0 <small>Jul 16, 2025</small>
+
+!!! failure "Removed"
+    `supervision-0.26.0` drops `python3.8` support and upgrade all codes to `python3.9` syntax style.
+
+!!! info "Tip"
+    Supervision’s documentation theme now has a fresh look that is consistent with the documentations of all Roboflow open-source projects. ([#1858](https://github.com/roboflow/supervision/pull/1858))
+
+- Added [#1774](https://github.com/roboflow/supervision/pull/1774): Support for the IOS (Intersection over Smallest) overlap metric that measures how much of the smaller object is covered by the larger one in [`sv.Detections.with_nms`](https://supervision.roboflow.com/0.26.0/detection/core/#supervision.detection.core.Detections.with_nms), [`sv.Detections.with_nmm`](https://supervision.roboflow.com/0.26.0/detection/core/#supervision.detection.core.Detections.with_nmm), [`sv.box_iou_batch`](https://supervision.roboflow.com/0.26.0/detection/utils/iou_and_nms/#supervision.detection.utils.iou_and_nms.box_iou_batch), and [`sv.mask_iou_batch`](https://supervision.roboflow.com/0.26.0/detection/utils/iou_and_nms/#supervision.detection.utils.iou_and_nms.mask_iou_batch).
+
+    ```python
+    import numpy as np
+    import supervision as sv
+
+    boxes_true = np.array([
+        [100, 100, 200, 200],
+        [300, 300, 400, 400]
+    ])
+    boxes_detection = np.array([
+        [150, 150, 250, 250],
+        [320, 320, 420, 420]
+    ])
+
+    sv.box_iou_batch(
+        boxes_true=boxes_true,
+        boxes_detection=boxes_detection,
+        overlap_metric=sv.OverlapMetric.IOU
+    )
+
+    # array([[0.14285714, 0.        ],
+    #        [0.        , 0.47058824]])
+
+    sv.box_iou_batch(
+        boxes_true=boxes_true,
+        boxes_detection=boxes_detection,
+        overlap_metric=sv.OverlapMetric.IOS
+    )
+
+    # array([[0.25, 0.  ],
+    #        [0.  , 0.64]])
+    ```
+
+- Added [#1874](https://github.com/roboflow/supervision/pull/1874): [`sv.box_iou`](https://supervision.roboflow.com/0.26.0/detection/utils/iou_and_nms/#supervision.detection.utils.iou_and_nms.box_iou) that efficiently computes the Intersection over Union (IoU) between two individual bounding boxes.
+
+- Added [#1816](https://github.com/roboflow/supervision/pull/1816): Support for frame limitations and progress bar in [`sv.process_video`](https://supervision.roboflow.com/0.26.0/utils/video/#supervision.utils.video.process_video).
+
+- Added [#1788](https://github.com/roboflow/supervision/pull/1788): Support for creating [`sv.KeyPoints`](https://supervision.roboflow.com/0.26.0/keypoint/core/#supervision.keypoint.core.KeyPoints) objects from [ViTPose](https://huggingface.co/docs/transformers/en/model_doc/vitpose) and [ViTPose++](https://huggingface.co/docs/transformers/en/model_doc/vitpose#vitpose-models) inference results via [`sv.KeyPoints.from_transformers`](https://supervision.roboflow.com/0.26.0/keypoint/core/#supervision.keypoint.core.KeyPoints.from_transformers).
+
+- Added [#1823](https://github.com/roboflow/supervision/pull/1823): [`sv.xyxy_to_xcycarh`](https://supervision.roboflow.com/0.26.0/detection/utils/converters/#supervision.detection.utils.converters.xyxy_to_xcycarh) function to convert bounding box coordinates from `(x_min, y_min, x_max, y_max)` into measurement space to format `(center x, center y, aspect ratio, height)`, where the aspect ratio is `width / height`.
+
+- Added [#1788](https://github.com/roboflow/supervision/pull/1788): [`sv.xyxy_to_xywh`](https://supervision.roboflow.com/0.26.0/detection/utils/converters/#supervision.detection.utils.converters.xyxy_to_xywh) function to convert bounding box coordinates from `(x_min, y_min, x_max, y_max)` format to `(x, y, width, height)` format.
+
+- Changed [#1820](https://github.com/roboflow/supervision/pull/1820): [`sv.LabelAnnotator`](https://supervision.roboflow.com/0.26.0/detection/annotators/#supervision.annotators.core.LabelAnnotator) now supports the `smart_position` parameter to automatically keep labels within frame boundaries, and the `max_line_length` parameter to control text wrapping for long or multi-line labels.
+
+- Changed [#1825](https://github.com/roboflow/supervision/pull/1825): [`sv.LabelAnnotator`](https://supervision.roboflow.com/0.26.0/detection/annotators/#supervision.annotators.core.LabelAnnotator) now supports non-string labels.
+
+- Changed [#1792](https://github.com/roboflow/supervision/pull/1792): [`sv.Detections.from_vlm`](https://supervision.roboflow.com/0.26.0/detection/core/#supervision.detection.core.Detections.from_vlm) now supports parsing bounding boxes and segmentation masks from responses generated by [Google Gemini models](https://ai.google.dev/gemini-api/docs/vision).
+
+    ```python
+    import supervision as sv
+
+    gemini_response_text = """```json
+        [
+            {"box_2d": [543, 40, 728, 200], "label": "cat", "id": 1},
+            {"box_2d": [653, 352, 820, 522], "label": "dog", "id": 2}
+        ]
+    ```"""
+
+    detections = sv.Detections.from_vlm(
+        sv.VLM.GOOGLE_GEMINI_2_5,
+        gemini_response_text,
+        resolution_wh=(1000, 1000),
+        classes=['cat', 'dog'],
+    )
+
+    detections.xyxy
+    # array([[543., 40., 728., 200.], [653., 352., 820., 522.]])
+
+    detections.data
+    # {'class_name': array(['cat', 'dog'], dtype='<U26')}
+
+    detections.class_id
+    # array([0, 1])
+    ```
+
+- Changed [#1878](https://github.com/roboflow/supervision/pull/1878): [`sv.Detections.from_vlm`](https://supervision.roboflow.com/0.26.0/detection/core/#supervision.detection.core.Detections.from_vlm) now supports parsing bounding boxes from responses generated by [Moondream](https://github.com/vikhyat/moondream).
+
+    ```python
+    import supervision as sv
+
+    moondream_result = {
+        'objects': [
+            {
+                'x_min': 0.5704046934843063,
+                'y_min': 0.20069346576929092,
+                'x_max': 0.7049859315156937,
+                'y_max': 0.3012596592307091
+            },
+            {
+                'x_min': 0.6210969910025597,
+                'y_min': 0.3300672620534897,
+                'x_max': 0.8417936339974403,
+                'y_max': 0.4961046129465103
+            }
+        ]
+    }
+
+    detections = sv.Detections.from_vlm(
+        sv.VLM.MOONDREAM,
+        moondream_result,
+        resolution_wh=(1000, 1000),
+    )
+
+    detections.xyxy
+    # array([[1752.28,  818.82, 2165.72, 1229.14],
+    #        [1908.01, 1346.67, 2585.99, 2024.11]])
+    ```
+
+- Changed [#1709](https://github.com/roboflow/supervision/pull/1790): [`sv.Detections.from_vlm`](https://supervision.roboflow.com/0.26.0/detection/core/#supervision.detection.core.Detections.from_vlm) now supports parsing bounding boxes from responses generated by [Qwen-2.5 VL](https://github.com/QwenLM/Qwen2.5-VL).
+
+    ```python
+    import supervision as sv
+
+    qwen_2_5_vl_result = """```json
+    [
+        {"bbox_2d": [139, 768, 315, 954], "label": "cat"},
+        {"bbox_2d": [366, 679, 536, 849], "label": "dog"}
+    ]
+    ```"""
+
+    detections = sv.Detections.from_vlm(
+        sv.VLM.QWEN_2_5_VL,
+        qwen_2_5_vl_result,
+        input_wh=(1000, 1000),
+        resolution_wh=(1000, 1000),
+        classes=['cat', 'dog'],
+    )
+
+    detections.xyxy
+    # array([[139., 768., 315., 954.], [366., 679., 536., 849.]])
+
+    detections.class_id
+    # array([0, 1])
+
+    detections.data
+    # {'class_name': array(['cat', 'dog'], dtype='<U10')}
+
+    detections.class_id
+    # array([0, 1])
+    ```
+
+- Changed [#1786](https://github.com/roboflow/supervision/pull/1786): Significantly improved the speed of HSV color mapping in [`sv.HeatMapAnnotator`](https://supervision.roboflow.com/0.26.0/detection/annotators/#supervision.annotators.core.HeatMapAnnotator), achieving approximately 28x faster performance on 1920x1080 frames.
+
+- Fixed [#1834](https://github.com/roboflow/supervision/pull/1834): Supervision’s [`sv.MeanAveragePrecision`](https://supervision.roboflow.com/0.26.0/metrics/mean_average_precision/#supervision.metrics.mean_average_precision.MeanAveragePrecision) is now fully aligned with [pycocotools](https://github.com/ppwwyyxx/cocoapi), the official COCO evaluation tool, ensuring accurate and standardized metrics. This update enabled us to launch a new version of the [Computer Vision Model Leaderboard](https://leaderboard.roboflow.com/).
+
+    ```python
+    import supervision as sv
+    from supervision.metrics import MeanAveragePrecision
+
+    predictions = sv.Detections(...)
+    targets = sv.Detections(...)
+
+    map_metric = MeanAveragePrecision()
+    map_metric.update(predictions, targets).compute()
+
+    # Average Precision (AP) @[ IoU=0.50:0.95 | area=   all | maxDets=100 ] = 0.464
+    # Average Precision (AP) @[ IoU=0.50      | area=   all | maxDets=100 ] = 0.637
+    # Average Precision (AP) @[ IoU=0.75      | area=   all | maxDets=100 ] = 0.203
+    # Average Precision (AP) @[ IoU=0.50:0.95 | area= small | maxDets=100 ] = 0.284
+    # Average Precision (AP) @[ IoU=0.50:0.95 | area=medium | maxDets=100 ] = 0.497
+    # Average Precision (AP) @[ IoU=0.50:0.95 | area= large | maxDets=100 ] = 0.629
+    ```
+
+- Fixed [#1767](https://github.com/roboflow/supervision/pull/1767): Fixed losing `sv.Detections.data` when detections filtering.
 
 ### 0.25.0 <small>Nov 12, 2024</small>
 
@@ -382,9 +637,9 @@ detections = sv.Detections.from_sam(sam_result=sam_result)
 
 - 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.
+- Fixed [#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/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`.
+- Fixed [#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
@@ -397,7 +652,7 @@ for frame in sv.get_video_frames_generator(
     ...
 ```
 
-- Fix [#1424](https://github.com/roboflow/supervision/pull/1424): `plot_image` function now clearly indicates that the size is in inches.
+- Fixed [#1424](https://github.com/roboflow/supervision/pull/1424): `plot_image` function now clearly indicates that the size is in inches.
 
 !!! failure "Removed"
 
@@ -1110,7 +1365,7 @@ array([
 
 ### 0.11.1 <small>June 29, 2023</small>
 
-- Fix [#165](https://github.com/roboflow/supervision/pull/165): [`as_folder_structure`](/0.11.1/dataset/core/#supervision.dataset.core.ClassificationDataset.as_folder_structure) fails to save [`sv.ClassificationDataset`](/0.11.1/dataset/core/#classificationdataset) when it is result of inference.
+- Fixed [#165](https://github.com/roboflow/supervision/pull/165): [`as_folder_structure`](/0.11.1/dataset/core/#supervision.dataset.core.ClassificationDataset.as_folder_structure) fails to save [`sv.ClassificationDataset`](/0.11.1/dataset/core/#classificationdataset) when it is result of inference.
 
 ### 0.11.0 <small>June 28, 2023</small>
 
@@ -1156,7 +1411,7 @@ array([
 
 - Added [#162](https://github.com/roboflow/supervision/pull/162): additional `start` and `end` arguments to [`sv.get_video_frames_generator`](/0.11.0/utils/video/#get_video_frames_generator) allowing to generate frames only for a selected part of the video.
 
-- Fix [#157](https://github.com/roboflow/supervision/pull/157): incorrect loading of YOLO dataset class names from `data.yaml`.
+- Fixed [#157](https://github.com/roboflow/supervision/pull/157): incorrect loading of YOLO dataset class names from `data.yaml`.
 
 ### 0.10.0 <small>June 14, 2023</small>
 

docs/deprecated.md

@@ -7,21 +7,19 @@ 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.
 
-- 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.
+- `sv.LMM` enum is deprecated and will be removed in `supervision-0.31.0`. Use `sv.VLM` instead.
+- [`sv.Detections.from_lmm`](https://supervision.roboflow.com/0.26.0/detection/core/#supervision.detection.core.Detections.from_lmm) property is deprecated and will be removed in `supervision-0.31.0`. Use [`sv.Detections.from_vlm`](https://supervision.roboflow.com/0.26.0/detection/core/#supervision.detection.core.Detections.from_vlm) instead.
 
 # Removed
 
-### 0.25.0
+### 0.26.0
+
+- The `sv.DetectionDataset.images` property has been 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. Also, constructing `sv.DetectionDataset` with parameter `images` as `Dict[str, np.ndarray]` is deprecated and has been removed in `supervision-0.26.0`. Please pass a list of paths `List[str]` instead.
+- The name `sv.BoundingBoxAnnotator` is deprecated and has been removed in `supervision-0.26.0`. It has been renamed to [`sv.BoxAnnotator`](https://supervision.roboflow.com/0.22.0/detection/annotators/#supervision.annotators.core.BoxAnnotator).
 
-No removals in this version!
 
 ### 0.24.0
 
@@ -35,12 +33,12 @@ No removals in this version!
 
 ### 0.22.0
 
-- `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()` 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__` was removed as of `supervision-0.22.0`. Use the attribute [`FPSMonitor.fps`](utils/video.md/#supervision.utils.video.FPSMonitor.fps) instead.
+- `sv.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 `sv.Color.white()` was removed as of `supervision-0.22.0`. Use the constant `sv.Color.WHITE` instead.
+- The method `sv.Color.black()` was removed as of `supervision-0.22.0`. Use the constant `sv.Color.BLACK` instead.
+- The method `sv.Color.red()` was removed as of `supervision-0.22.0`. Use the constant `sv.Color.RED` instead.
+- The method `sv.Color.green()` was removed as of `supervision-0.22.0`. Use the constant `sv.Color.GREEN` instead.
+- The method `sv.Color.blue()` was removed as of `supervision-0.22.0`. Use the constant `sv.Color.BLUE` instead.
+- The method `sv.ColorPalette.default()` was removed as of `supervision-0.22.0`. Use the constant [`ColorPalette.DEFAULT`](/utils/draw/#supervision.draw.color.ColorPalette.DEFAULT) instead.
+- `sv.BoxAnnotator` was removed as of `supervision-0.22.0`, however `sv.BoundingBoxAnnotator` was immediately renamed to `sv.BoxAnnotator`. Use [`BoxAnnotator`](detection/annotators.md/#supervision.annotators.core.BoxAnnotator) and [`LabelAnnotator`](detection/annotators.md/#supervision.annotators.core.LabelAnnotator) instead of the old `sv.BoxAnnotator`.
+- The method `sv.FPSMonitor.__call__` was removed as of `supervision-0.22.0`. Use the attribute [`sv.FPSMonitor.fps`](utils/video.md/#supervision.utils.video.FPSMonitor.fps) instead.

docs/detection/annotators.md

@@ -1,6 +1,5 @@
 ---
 comments: true
-status: new
 ---
 
 # Annotators
@@ -28,28 +27,26 @@ Annotators accept detections and apply box or mask visualizations to the detecti
 
     </div>
 
-    <!--
-    === "RoundBox"
+=== "RoundBox"
 
-        ```python
-        import supervision as sv
+    ```python
+    import supervision as sv
 
-        image = ...
-        detections = sv.Detections(...)
+    image = ...
+    detections = sv.Detections(...)
 
-        round_box_annotator = sv.RoundBoxAnnotator()
-        annotated_frame = round_box_annotator.annotate(
-            scene=image.copy(),
-            detections=detections
-        )
-        ```
+    round_box_annotator = sv.RoundBoxAnnotator()
+    annotated_frame = round_box_annotator.annotate(
+        scene=image.copy(),
+        detections=detections
+    )
+    ```
 
-        <div class="result" markdown>
+    <div class="result" markdown>
 
-        ![round-box-annotator-example](https://media.roboflow.com/supervision-annotator-examples/round-box-annotator-example-purple.png){ align=center width="800" }
+    ![round-box-annotator-example](https://media.roboflow.com/supervision-annotator-examples/round-box-annotator-example-purple.png){ align=center width="800" }
 
-        </div>
-    -->
+    </div>
 
 === "BoxCorner"
 

docs/detection/core.md

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

docs/detection/double_detection_filter.md

@@ -1,29 +0,0 @@
----
-comments: true
----
-
-# Double Detection Filter
-
-<div class="md-typeset">
-  <h2><a href="#supervision.detection.overlap_filter.OverlapFilter">OverlapFilter</a></h2>
-</div>
-
-:::supervision.detection.overlap_filter.OverlapFilter
-
-<div class="md-typeset">
-  <h2><a href="#supervision.detection.overlap_filter.box_non_max_suppression">box_non_max_suppression</a></h2>
-</div>
-
-:::supervision.detection.overlap_filter.box_non_max_suppression
-
-<div class="md-typeset">
-  <h2><a href="#supervision.detection.overlap_filter.mask_non_max_suppression">mask_non_max_suppression</a></h2>
-</div>
-
-:::supervision.detection.overlap_filter.mask_non_max_suppression
-
-<div class="md-typeset">
-  <h2><a href="#supervision.detection.overlap_filter.box_non_max_merge">box_non_max_merge</a></h2>
-</div>
-
-:::supervision.detection.overlap_filter.box_non_max_merge

docs/detection/tools/line_zone.md

@@ -1,6 +1,5 @@
 ---
 comments: true
-status: new
 ---
 
 <div class="md-typeset">

docs/detection/utils.md

@@ -1,120 +0,0 @@
----
-comments: true
-status: new
----
-
-# Detection Utils
-
-<div class="md-typeset">
-  <h2><a href="#supervision.detection.utils.box_iou_batch">box_iou_batch</a></h2>
-</div>
-
-:::supervision.detection.utils.box_iou_batch
-
-<div class="md-typeset">
-  <h2><a href="#supervision.detection.utils.mask_iou_batch">mask_iou_batch</a></h2>
-</div>
-
-:::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>
-
-:::supervision.detection.utils.polygon_to_mask
-
-<div class="md-typeset">
-  <h2><a href="#supervision.detection.utils.mask_to_xyxy">mask_to_xyxy</a></h2>
-</div>
-
-:::supervision.detection.utils.mask_to_xyxy
-
-<div class="md-typeset">
-  <h2><a href="#supervision.detection.utils.mask_to_polygons">mask_to_polygons</a></h2>
-</div>
-
-:::supervision.detection.utils.mask_to_polygons
-
-<div class="md-typeset">
-  <h2><a href="#supervision.detection.utils.polygon_to_xyxy">polygon_to_xyxy</a></h2>
-</div>
-
-:::supervision.detection.utils.polygon_to_xyxy
-
-<div class="md-typeset">
-  <h2><a href="#supervision.detection.utils.filter_polygons_by_area">filter_polygons_by_area</a></h2>
-</div>
-
-:::supervision.detection.utils.filter_polygons_by_area
-
-<div class="md-typeset">
-  <h2><a href="#supervision.detection.utils.move_boxes">move_boxes</a></h2>
-</div>
-
-:::supervision.detection.utils.move_boxes
-
-<div class="md-typeset">
-  <h2><a href="#supervision.detection.utils.move_masks">move_masks</a></h2>
-</div>
-
-:::supervision.detection.utils.move_masks
-
-<div class="md-typeset">
-  <h2><a href="#supervision.detection.utils.scale_boxes">scale_boxes</a></h2>
-</div>
-
-:::supervision.detection.utils.scale_boxes
-
-<div class="md-typeset">
-  <h2><a href="#supervision.detection.utils.clip_boxes">clip_boxes</a></h2>
-</div>
-
-:::supervision.detection.utils.clip_boxes
-
-<div class="md-typeset">
-  <h2><a href="#supervision.detection.utils.pad_boxes">pad_boxes</a></h2>
-</div>
-
-:::supervision.detection.utils.pad_boxes
-
-<div class="md-typeset">
-  <h2><a href="#supervision.detection.utils.xywh_to_xyxy">xywh_to_xyxy</a></h2>
-</div>
-
-:::supervision.detection.utils.xywh_to_xyxy
-
-<div class="md-typeset">
-  <h2><a href="#supervision.detection.utils.xyxy_to_xywh">xyxy_to_xywh</a></h2>
-</div>
-
-:::supervision.detection.utils.xyxy_to_xywh
-
-<div class="md-typeset">
-  <h2><a href="#supervision.detection.utils.xyxy_to_xcycarh">xyxy_to_xcycarh</a></h2>
-</div>
-
-:::supervision.detection.utils.xyxy_to_xcycarh
-
-<div class="md-typeset">
-  <h2><a href="#supervision.detection.utils.xcycwh_to_xyxy">xcycwh_to_xyxy</a></h2>
-</div>
-
-:::supervision.detection.utils.xcycwh_to_xyxy
-
-<div class="md-typeset">
-  <h2><a href="#supervision.detection.utils.contains_holes">contains_holes</a></h2>
-</div>
-
-:::supervision.detection.utils.contains_holes
-
-<div class="md-typeset">
-  <h2><a href="#supervision.detection.utils.contains_multiple_segments">contains_multiple_segments</a></h2>
-</div>
-
-:::supervision.detection.utils.contains_multiple_segments

docs/detection/utils/boxes.md

@@ -0,0 +1,35 @@
+---
+comments: true
+---
+
+# Boxes Utils
+
+<div class="md-typeset">
+  <h2><a href="#supervision.detection.utils.boxes.move_boxes">move_boxes</a></h2>
+</div>
+
+:::supervision.detection.utils.boxes.move_boxes
+
+<div class="md-typeset">
+  <h2><a href="#supervision.detection.utils.boxes.scale_boxes">scale_boxes</a></h2>
+</div>
+
+:::supervision.detection.utils.boxes.scale_boxes
+
+<div class="md-typeset">
+  <h2><a href="#supervision.detection.boxes.utils.clip_boxes">clip_boxes</a></h2>
+</div>
+
+:::supervision.detection.utils.boxes.clip_boxes
+
+<div class="md-typeset">
+  <h2><a href="#supervision.detection.utils.boxes.pad_boxes">pad_boxes</a></h2>
+</div>
+
+:::supervision.detection.utils.boxes.pad_boxes
+
+<div class="md-typeset">
+  <h2><a href="#supervision.detection.utils.boxes.denormalize_boxes">denormalize_boxes</a></h2>
+</div>
+
+:::supervision.detection.utils.boxes.denormalize_boxes

docs/detection/utils/converters.md

@@ -0,0 +1,66 @@
+---
+comments: true
+status: new
+---
+
+# Converters Utils
+
+<div class="md-typeset">
+  <h2><a href="#supervision.detection.utils.converters.xyxy_to_xywh">xyxy_to_xywh</a></h2>
+</div>
+
+:::supervision.detection.utils.converters.xyxy_to_xywh
+
+<div class="md-typeset">
+  <h2><a href="#supervision.detection.utils.converters.xywh_to_xyxy">xywh_to_xyxy</a></h2>
+</div>
+
+:::supervision.detection.utils.converters.xywh_to_xyxy
+
+<div class="md-typeset">
+  <h2><a href="#supervision.detection.utils.converters.xyxy_to_xcycarh">xyxy_to_xcycarh</a></h2>
+</div>
+
+:::supervision.detection.utils.converters.xyxy_to_xcycarh
+
+<div class="md-typeset">
+  <h2><a href="#supervision.detection.utils.converters.xcycwh_to_xyxy">xcycwh_to_xyxy</a></h2>
+</div>
+
+:::supervision.detection.utils.converters.xcycwh_to_xyxy
+
+<div class="md-typeset">
+  <h2><a href="#supervision.detection.utils.converters.xyxy_to_polygons">xyxy_to_polygons</a></h2>
+</div>
+
+:::supervision.detection.utils.converters.xyxy_to_polygons
+
+<div class="md-typeset">
+  <h2><a href="#supervision.detection.utils.converters.mask_to_xyxy">mask_to_xyxy</a></h2>
+</div>
+
+:::supervision.detection.utils.converters.mask_to_xyxy
+
+<div class="md-typeset">
+  <h2><a href="#supervision.detection.utils.converters.mask_to_polygons">mask_to_polygons</a></h2>
+</div>
+
+:::supervision.detection.utils.converters.mask_to_polygons
+
+<div class="md-typeset">
+  <h2><a href="#supervision.detection.utils.converters.polygon_to_mask">polygon_to_mask</a></h2>
+</div>
+
+:::supervision.detection.utils.converters.polygon_to_mask
+
+<div class="md-typeset">
+  <h2><a href="#supervision.detection.utils.converters.polygon_to_xyxy">polygon_to_xyxy</a></h2>
+</div>
+
+:::supervision.detection.utils.converters.polygon_to_xyxy
+
+<div class="md-typeset">
+  <h2><a href="#supervision.detection.utils.converters.xyxy_to_mask">xyxy_to_mask</a></h2>
+</div>
+
+:::supervision.detection.utils.converters.xyxy_to_mask

docs/detection/utils/iou_and_nms.md

@@ -0,0 +1,71 @@
+---
+comments: true
+---
+
+# IoU and NMS Utils
+
+<div class="md-typeset">
+  <h2><a href="#supervision.detection.utils.iou_and_nms.OverlapFilter">OverlapFilter</a></h2>
+</div>
+
+:::supervision.detection.utils.iou_and_nms.OverlapFilter
+
+<div class="md-typeset">
+  <h2><a href="#supervision.detection.utils.iou_and_nms.OverlapMetric">OverlapMetric</a></h2>
+</div>
+
+:::supervision.detection.utils.iou_and_nms.OverlapMetric
+
+<div class="md-typeset">
+  <h2><a href="#supervision.detection.utils.iou_and_nms.utils.box_iou">box_iou</a></h2>
+</div>
+
+:::supervision.detection.utils.iou_and_nms.box_iou
+
+<div class="md-typeset">
+  <h2><a href="#supervision.detection.utils.iou_and_nms.box_iou_batch">box_iou_batch</a></h2>
+</div>
+
+:::supervision.detection.utils.iou_and_nms.box_iou_batch
+
+<div class="md-typeset">
+  <h2><a href="#supervision.detection.utils.iou_and_nms.box_iou_batch_with_jaccard">box_iou_batch_with_jaccard</a></h2>
+</div>
+
+:::supervision.detection.utils.iou_and_nms.box_iou_batch_with_jaccard
+
+<div class="md-typeset">
+  <h2><a href="#supervision.detection.utils.iou_and_nms.mask_iou_batch">mask_iou_batch</a></h2>
+</div>
+
+:::supervision.detection.utils.iou_and_nms.mask_iou_batch
+
+<div class="md-typeset">
+  <h2><a href="#supervision.detection.utils.iou_and_nms.oriented_box_iou_batch">oriented_box_iou_batch</a></h2>
+</div>
+
+:::supervision.detection.utils.iou_and_nms.oriented_box_iou_batch
+
+<div class="md-typeset">
+  <h2><a href="#supervision.detection.utils.iou_and_nms.box_non_max_suppression">box_non_max_suppression</a></h2>
+</div>
+
+:::supervision.detection.utils.iou_and_nms.box_non_max_suppression
+
+<div class="md-typeset">
+  <h2><a href="#supervision.detection.utils.iou_and_nms.mask_non_max_suppression">mask_non_max_suppression</a></h2>
+</div>
+
+:::supervision.detection.utils.iou_and_nms.mask_non_max_suppression
+
+<div class="md-typeset">
+  <h2><a href="#supervision.detection.utils.iou_and_nms.box_non_max_merge">box_non_max_merge</a></h2>
+</div>
+
+:::supervision.detection.utils.iou_and_nms.box_non_max_merge
+
+<div class="md-typeset">
+  <h2><a href="#supervision.detection.utils.iou_and_nms.mask_non_max_merge">mask_non_max_merge</a></h2>
+</div>
+
+:::supervision.detection.utils.iou_and_nms.mask_non_max_merge

docs/detection/utils/masks.md

@@ -0,0 +1,30 @@
+---
+comments: true
+status: new
+---
+
+# Masks Utils
+
+<div class="md-typeset">
+  <h2><a href="#supervision.detection.utils.masks.move_masks">move_masks</a></h2>
+</div>
+
+:::supervision.detection.utils.masks.move_masks
+
+<div class="md-typeset">
+  <h2><a href="#supervision.detection.utils.masks.contains_holes">contains_holes</a></h2>
+</div>
+
+:::supervision.detection.utils.masks.contains_holes
+
+<div class="md-typeset">
+  <h2><a href="#supervision.detection.utils.masks.contains_multiple_segments">contains_multiple_segments</a></h2>
+</div>
+
+:::supervision.detection.utils.masks.contains_multiple_segments
+
+<div class="md-typeset">
+  <h2><a href="#supervision.detection.utils.masks.filter_segments_by_distance">filter_segments_by_distance</a></h2>
+</div>
+
+:::supervision.detection.utils.masks.filter_segments_by_distance

docs/detection/utils/polygons.md

@@ -0,0 +1,17 @@
+---
+comments: true
+---
+
+# Polygons Utils
+
+<div class="md-typeset">
+  <h2><a href="#supervision.detection.utils.polygons.filter_polygons_by_area">filter_polygons_by_area</a></h2>
+</div>
+
+:::supervision.detection.utils.polygons.filter_polygons_by_area
+
+<div class="md-typeset">
+  <h2><a href="#supervision.detection.utils.polygons.approximate_polygon">approximate_polygon</a></h2>
+</div>
+
+:::supervision.detection.utils.polygons.approximate_polygon

docs/detection/utils/vlms.md

@@ -0,0 +1,18 @@
+---
+comments: true
+status: new
+---
+
+# VLMs Utils
+
+<div class="md-typeset">
+  <h2><a href="#supervision.detection.utils.vlms.edit_distance">edit_distance</a></h2>
+</div>
+
+:::supervision.detection.utils.vlms.edit_distance
+
+<div class="md-typeset">
+  <h2><a href="#supervision.detection.utils.vlms.fuzzy_match_index">fuzzy_match_index</a></h2>
+</div>
+
+:::supervision.detection.utils.vlms.fuzzy_match_index

docs/how_to/benchmark_a_model.md

@@ -1,6 +1,5 @@
 ---
 comments: true
-status: new
 ---
 
 ![Corgi Example](https://media.roboflow.com/supervision/image-examples/how-to/benchmark-models/corgi-sorted-2.png)

docs/how_to/process_datasets.md

@@ -331,12 +331,9 @@ for i in range(16):
     annotated_image = label_annotator.annotate(annotated_image, annotations, labels)
     annotated_images.append(annotated_image)
 
-grid = sv.create_tiles(
+sv.plot_images_grid(
     annotated_images,
     grid_size=(4, 4),
-    single_tile_size=(400, 400),
-    tile_padding_color=sv.Color.WHITE,
-    tile_margin_color=sv.Color.WHITE
 )
 ```
 
@@ -398,7 +395,7 @@ increase the size and diversity of training datasets, leading to improved model
 performance and generalization.
 
 ```bash
-pip install augmentation
+pip install albumentations
 ```
 
 Albumentations provides a flexible and powerful API for image augmentation. The core of

docs/how_to/save_detections.md

@@ -234,7 +234,7 @@ with
     model = get_model(model_id="yolov8n-640")
     frames_generator = sv.get_video_frames_generator(<SOURCE_VIDEO_PATH>)
 
-    with sv.JSONSink(<TARGET_CSV_PATH>) as sink:
+    with sv.JSONSink(<TARGET_JSON_PATH>) as sink:
         for frame_index, frame in enumerate(frames_generator):
 
             results = model.infer(image)[0]
@@ -250,7 +250,7 @@ with
     model = YOLO("yolov8n.pt")
     frames_generator = sv.get_video_frames_generator(<SOURCE_VIDEO_PATH>)
 
-    with sv.JSONSink(<TARGET_CSV_PATH>) as sink:
+    with sv.JSONSink(<TARGET_JSON_PATH>) as sink:
         for frame_index, frame in enumerate(frames_generator):
 
             results = model(frame)[0]
@@ -268,7 +268,7 @@ with
     model = DetrForObjectDetection.from_pretrained("facebook/detr-resnet-50")
     frames_generator = sv.get_video_frames_generator(<SOURCE_VIDEO_PATH>)
 
-    with sv.JSONSink(<TARGET_CSV_PATH>) as sink:
+    with sv.JSONSink(<TARGET_JSON_PATH>) as sink:
         for frame_index, frame in enumerate(frames_generator):
 
             frame = sv.cv2_to_pillow(frame)

docs/how_to/track_objects.md

@@ -1,6 +1,5 @@
 ---
 comments: true
-status: new
 ---
 
 # Track Objects
@@ -177,9 +176,9 @@ offering a clear visual representation of each object's class and unique identif
         detections = tracker.update_with_detections(detections)
 
         labels = [
-            f"#{tracker_id} {results.names[class_id]}"
-            for class_id, tracker_id
-            in zip(detections.class_id, detections.tracker_id)
+            f"#{tracker_id} {class_name}"
+            for class_name, tracker_id
+            in zip(detections.data["class_name"], detections.tracker_id)
         ]
 
         annotated_frame = box_annotator.annotate(
@@ -212,9 +211,9 @@ offering a clear visual representation of each object's class and unique identif
         detections = tracker.update_with_detections(detections)
 
         labels = [
-            f"#{tracker_id} {results.names[class_id]}"
-            for class_id, tracker_id
-            in zip(detections.class_id, detections.tracker_id)
+            f"#{tracker_id} {class_name}"
+            for class_name, tracker_id
+            in zip(detections.data["class_name"], detections.tracker_id)
         ]
 
         annotated_frame = box_annotator.annotate(
@@ -260,9 +259,9 @@ movement patterns and interactions between objects in the video.
         detections = tracker.update_with_detections(detections)
 
         labels = [
-            f"#{tracker_id} {results.names[class_id]}"
-            for class_id, tracker_id
-            in zip(detections.class_id, detections.tracker_id)
+            f"#{tracker_id} {class_name}"
+            for class_name, tracker_id
+            in zip(detections.data["class_name"], detections.tracker_id)
         ]
 
         annotated_frame = box_annotator.annotate(
@@ -298,9 +297,9 @@ movement patterns and interactions between objects in the video.
         detections = tracker.update_with_detections(detections)
 
         labels = [
-            f"#{tracker_id} {results.names[class_id]}"
-            for class_id, tracker_id
-            in zip(detections.class_id, detections.tracker_id)
+            f"#{tracker_id} {class_name}"
+            for class_name, tracker_id
+            in zip(detections.data["class_name"], detections.tracker_id)
         ]
 
         annotated_frame = box_annotator.annotate(
@@ -345,7 +344,7 @@ Supervision is versatile and compatible with various models. Check this [link](/
 
 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).
+Let's immediately visualize the results with our [`EdgeAnnotator`](/latest/keypoint/annotators/#supervision.key_points.annotators.EdgeAnnotator) and [`VertexAnnotator`](https://supervision.roboflow.com/latest/keypoint/annotators/#supervision.key_points.annotators.VertexAnnotator).
 
 === "Ultralytics"
 
@@ -408,7 +407,7 @@ Let's immediately visualize the results with our [`EdgeAnnotator`](/latest/keypo
 
 ### 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.
+Keypoint tracking is currently supported via the conversion of `KeyPoints` to `Detections`. This is achieved with the [`KeyPoints.as_detections()`](/latest/keypoint/core/#supervision.key_points.core.KeyPoints.as_detections) function.
 
 Let's convert to detections and visualize the results with our [`BoxAnnotator`](/latest/detection/annotators/#supervision.annotators.core.BoxAnnotator).
 

docs/index.md

@@ -10,13 +10,19 @@ hide:
   <h1></h1>
 </div>
 
-<div align="center" id="logo">
+<div align="center" id="logo" style="padding-top: 1rem;">
   <a align="center" href="" target="_blank">
       <img width="850"
           src="https://media.roboflow.com/open-source/supervision/rf-supervision-banner.png?updatedAt=1678995927529">
   </a>
 </div>
 
+<style>
+    #hello {
+        margin: 0;
+    }
+</style>
+
 ## 👋 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!
@@ -31,7 +37,7 @@ We write your reusable computer vision tools. Whether you need to load your data
 ## 💻 Install
 
 You can install `supervision` in a
-[**Python>=3.8**](https://www.python.org/) environment.
+[**Python>=3.9**](https://www.python.org/) environment.
 
 !!! example "Installation"
 

docs/javascripts/cookbooks-card.js

@@ -59,7 +59,7 @@ document.addEventListener("DOMContentLoaded", function () {
             <div
                 class="author-container"
                 data-login="${authorData.login}-${elementIndex}"
-                style="margin-left: ${marginLeft}; z-index: ${zIndex};"
+                style="margin-left: ${marginLeft};"
             >
                 <a
                     href="https://github.com/${authorData.login}"
@@ -90,14 +90,17 @@ document.addEventListener("DOMContentLoaded", function () {
         ).join(',&nbsp;');
 
         let authorsHTML = `
-        <div class="authors">
+        <div class="authors" style="margin: 0;">
             ${authorAvatarsHTML}
             <div class="author-names">${authorNamesHTML}</div>
         </div>
         `;
 
         element.innerText = `
-            <div style="flex-direction: column; height: 100%; display: flex;
+            <div style="
+                display: grid !important;
+                grid-template-rows: auto;
+                height: 100%;
             font-family: -apple-system,BlinkMacSystemFont,Segoe UI,Helvetica,Arial,sans-serif,Apple Color Emoji,Segoe UI Emoji; background: ${theme.background}; font-size: 14px; line-height: 1.5; color: ${theme.color}">
             <div style="display: flex; align-items: center;">
                 <span style="font-weight: 700; font-size: 1rem; color: ${theme.linkColor};">
@@ -105,13 +108,14 @@ document.addEventListener("DOMContentLoaded", function () {
                 </span>
             </div>
             ${authorsHTML}
-            <div style="font-size: 12px; color: ${theme.color}; display: flex; flex: 0; justify-content: space-between">
+            <div style="font-size: 12px; color: ${theme.color}; display: grid; grid-template-columns: auto 3fr; justify-content: space-between; gap: 1rem;">
                 <div style="display: flex; align-items: center;">
                 <img src="/assets/supervision-lenny.png" aria-label="stars" width="20" height="20" role="img" />
                 &nbsp;
                 <span style="margin-left: 4px">${version}</span>
                 </div>
-                <div style="display: flex; align-items: center; flex-wrap: wrap">
+                <div style="display: flex; align-items: center; flex-wrap: wrap; align-content: right;
+  gap: 0.1rem;">
                 ${labelHTML}
                 </div>
             </div>

docs/javascripts/mathjax.js

@@ -0,0 +1,19 @@
+window.MathJax = {
+    tex: {
+      inlineMath: [["\\(", "\\)"]],
+      displayMath: [["\\[", "\\]"]],
+      processEscapes: true,
+      processEnvironments: true
+    },
+    options: {
+      ignoreHtmlClass: ".*|",
+      processHtmlClass: "arithmatex"
+    }
+  };
+
+  document$.subscribe(() => {
+    MathJax.startup.output.clearCache()
+    MathJax.typesetClear()
+    MathJax.texReset()
+    MathJax.typesetPromise()
+  })

docs/keypoint/annotators.md

@@ -1,6 +1,5 @@
 ---
 comments: true
-status: new
 ---
 
 # Annotators
@@ -79,19 +78,19 @@ status: new
     </div>
 
 <div class="md-typeset">
-  <h2><a href="#supervision.keypoint.annotators.VertexAnnotator">VertexAnnotator</a></h2>
+  <h2><a href="#supervision.key_points.annotators.VertexAnnotator">VertexAnnotator</a></h2>
 </div>
 
-:::supervision.keypoint.annotators.VertexAnnotator
+:::supervision.key_points.annotators.VertexAnnotator
 
 <div class="md-typeset">
-  <h2><a href="#supervision.keypoint.annotators.EdgeAnnotator">EdgeAnnotator</a></h2>
+  <h2><a href="#supervision.key_points.annotators.EdgeAnnotator">EdgeAnnotator</a></h2>
 </div>
 
-:::supervision.keypoint.annotators.EdgeAnnotator
+:::supervision.key_points.annotators.EdgeAnnotator
 
 <div class="md-typeset">
-  <h2><a href="#supervision.keypoint.annotators.VertexLabelAnnotator">VertexLabelAnnotator</a></h2>
+  <h2><a href="#supervision.key_points.annotators.VertexLabelAnnotator">VertexLabelAnnotator</a></h2>
 </div>
 
-:::supervision.keypoint.annotators.VertexLabelAnnotator
+:::supervision.key_points.annotators.VertexLabelAnnotator

docs/keypoint/core.md

@@ -1,8 +1,7 @@
 ---
 comments: true
-status: new
 ---
 
 # Keypoint Detection
 
-:::supervision.keypoint.core.KeyPoints
+:::supervision.key_points.core.KeyPoints

docs/metrics/common_values.md

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

docs/metrics/f1_score.md

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

docs/metrics/mean_average_precision.md

@@ -1,6 +1,5 @@
 ---
 comments: true
-status: new
 ---
 
 # Mean Average Precision
@@ -16,3 +15,9 @@ status: new
 </div>
 
 :::supervision.metrics.mean_average_precision.MeanAveragePrecisionResult
+
+<div class="md-typeset">
+    <h2><a href="#supervision.dataset.formats.coco.get_coco_class_index_mapping">get_coco_class_index_mapping</a></h2>
+</div>
+
+:::supervision.dataset.formats.coco.get_coco_class_index_mapping

docs/metrics/mean_average_recall.md

@@ -1,6 +1,5 @@
 ---
 comments: true
-status: new
 ---
 
 # Mean Average Recall

docs/metrics/precision.md

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

docs/metrics/recall.md

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

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

@@ -93,7 +93,7 @@
             },
             "outputs": [],
             "source": [
-                "!pip install -q inference-gpu \"supervision[assets]\""
+                "!pip install -q inference-gpu \"supervision\""
             ]
         },
         {
@@ -156,7 +156,7 @@
         },
         {
             "cell_type": "code",
-            "execution_count": 4,
+            "execution_count": null,
             "metadata": {
                 "colab": {
                     "base_uri": "https://localhost:8080/"
@@ -207,7 +207,6 @@
             ],
             "source": [
                 "import supervision as sv\n",
-                "from supervision.assets import download_assets, VideoAssets\n",
                 "from inference.models.utils import get_roboflow_model\n",
                 "\n",
                 "\n",

docs/notebooks/download-supervision-assets.ipynb

@@ -17,7 +17,7 @@
         },
         {
             "cell_type": "code",
-            "execution_count": 10,
+            "execution_count": null,
             "metadata": {
                 "vscode": {
                     "languageId": "shellscript"
@@ -25,7 +25,7 @@
             },
             "outputs": [],
             "source": [
-                "!pip install -q \"supervision[assets]\""
+                "pip install -q \"supervision\""
             ]
         },
         {

docs/notebooks/evaluating-alignment-of-text-to-image-diffusion-models.ipynb

@@ -101,7 +101,7 @@
             },
             "outputs": [],
             "source": [
-                "!pip install -q torch diffusers accelerate inference-gpu[yolo-world] dill git+https://github.com/openai/CLIP.git supervision==0.19.0rc5"
+                "!pip install -q torch diffusers accelerate inference-gpu[yolo-world] dill git+https://github.com/openai/CLIP.git supervision"
             ]
         },
         {

docs/notebooks/object-tracking.ipynb

@@ -92,7 +92,7 @@
             },
             "outputs": [],
             "source": [
-                "!pip install -q inference-gpu \"supervision[assets]\""
+                "!pip install -q inference-gpu \"supervision\""
             ]
         },
         {

docs/notebooks/occupancy_analytics.ipynb

@@ -72,7 +72,7 @@
             },
             "outputs": [],
             "source": [
-                "!pip install roboflow supervision==0.19.0 -q"
+                "!pip install roboflow supervision -q"
             ]
         },
         {

docs/notebooks/quickstart.ipynb

@@ -300,7 +300,7 @@
             },
             "outputs": [],
             "source": [
-                "!pip install -q \"ultralytics<=8.3.40\""
+                "!pip install -q ultralytics"
             ]
         },
         {
@@ -495,7 +495,7 @@
             "source": [
                 "from ultralytics import YOLO\n",
                 "\n",
-                "model = YOLO(\"yolov8x.pt\")\n",
+                "model = YOLO(\"yolo11x.pt\")\n",
                 "result = model(image, verbose=False)[0]\n",
                 "detections = sv.Detections.from_ultralytics(result)"
             ]
@@ -594,7 +594,7 @@
         },
         {
             "cell_type": "code",
-            "execution_count": 33,
+            "execution_count": null,
             "metadata": {
                 "id": "yM6dmicTRGl6"
             },
@@ -602,7 +602,7 @@
             "source": [
                 "from ultralytics import YOLO\n",
                 "\n",
-                "model = YOLO(\"yolov8x-seg.pt\")\n",
+                "model = YOLO(\"yolo11x-seg.pt\")\n",
                 "result = model(image, verbose=False)[0]\n",
                 "detections = sv.Detections.from_ultralytics(result)"
             ]
@@ -926,7 +926,7 @@
             },
             "outputs": [],
             "source": [
-                "!pip install -q supervision[assets]"
+                "!pip install -q supervision"
             ]
         },
         {

docs/notebooks/serialise-detections-to-json.ipynb

@@ -32,7 +32,7 @@
             },
             "outputs": [],
             "source": [
-                "!pip install -q inference requests tqdm supervision==0.21.0"
+                "!pip install -q inference requests tqdm supervision"
             ]
         },
         {
@@ -695,12 +695,12 @@
             "source": [
                 "###\u00a0Annotate Image with Detections\n",
                 "\n",
-                "Finally, we can annotate the image with the predictions. Since we are working with an object detection model, we will use the [`sv.BoundingBoxAnnotator`](https://supervision.roboflow.com/latest/detection/annotators/#supervision.annotators.core.BoundingBoxAnnotator) and [`sv.LabelAnnotator`](https://supervision.roboflow.com/latest/detection/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`](https://supervision.roboflow.com/latest/detection/annotators/#supervision.annotators.core.BoxAnnotator) and [`sv.LabelAnnotator`](https://supervision.roboflow.com/latest/detection/annotators/#supervision.annotators.core.LabelAnnotator) classes."
             ]
         },
         {
             "cell_type": "code",
-            "execution_count": 49,
+            "execution_count": null,
             "metadata": {
                 "colab": {
                     "base_uri": "https://localhost:8080/",
@@ -722,7 +722,7 @@
                 }
             ],
             "source": [
-                "bounding_box_annotator = sv.BoundingBoxAnnotator()\n",
+                "bounding_box_annotator = sv.BoxAnnotator()\n",
                 "label_annotator = sv.LabelAnnotator()\n",
                 "\n",
                 "annotated_frame = frame.copy()\n",

docs/stylesheets/cookbooks_card.css

@@ -15,7 +15,7 @@
 /* Large screens (1024px and up) */
 @media (min-width: 1024px) {
     .custom-grid {
-        grid-template-columns: repeat(3, minmax(0, 1fr));
+        grid-template-columns: repeat(4, minmax(0, 1fr));
     }
 }
 

docs/stylesheets/extra.css

@@ -1,7 +1,10 @@
-:root {
+:root, body {
   /* Default to light theme */
   --md-primary-fg-color:        #8315F9;
-  --md-accent-fg-color:         #00FFCE;
+  --md-code-hl-color:          #8315F9 !important;
+  --md-accent-fg-color:        #8315F9 !important;
+  --md-code-hl-color--light: #e8d2ff89 !important;
+  --md-footer-fg-color--light: rgb(111, 108, 121) !important;
 }
 
 body.light {
@@ -9,6 +12,202 @@ body.light {
   --md-text-color:              #000000;
   --md-h2-color:                #000000;
 }
+.md-grid {
+  max-width: 85%;
+  margin: auto;
+}
+.sublist {
+  display: none;
+  list-style: none;
+  padding-left: 0;
+  background: white;
+  position: absolute;
+  border-radius: 8px;
+  margin-top: 0.25rem;
+}
+.sublist {
+  transition: opacity 0.5s ease-in-out;
+  display: none;
+  position: absolute; /* Ensure it overlaps and doesn't break flow */
+  background: white;  /* So it's visible */
+  z-index: 1000;
+}
+.sublist li {
+  padding: 0.5rem;
+}
+#products-list *:hover .products-sublist {
+  display: block;
+}
+#resources-list *, #products-list * {
+  cursor: pointer;
+}
+.products-sublist, .resources-sublist {
+  padding: 0.25rem;
+}
+.products-sublist li:hover, .resources-sublist li:hover, .md-nav__link[href]:hover {
+  background: rgb(242, 241, 247) !important;
+  border-radius: 6px;
+  color: initial !important;
+}
+.md-search {
+  flex-grow: 2;
+}
+.portfolio-section .md-grid {
+  max-width: 100%;
+}
+.md-header__inner {
+  align-items: center;
+  display: grid;
+  grid-template-columns: 0.1fr 1.4fr 2fr 2fr;
+  padding-right: 1rem;
+}
+.md-search__inner {
+  max-width: 600px;
+  width: 100%;
+  min-width: 100%;
+}
+.md-search__input {
+  background: white;
+  border: 1px solid rgb(229, 231, 235);
+  border-radius: 8px;
+  color: rgb(111, 108, 121);
+}
+.md-search__form *, .md-search__icon, .md-search__input {
+  color: rgb(111, 108, 121);
+}
+.md-search__input::placeholder {
+  color: rgb(156, 163, 175);
+}
+.md-search__form {
+  background: none !important;
+}
+.md-footer, .md-footer-meta {
+  background-color: transparent;
+  color: rgb(111, 108, 121);
+}
+.md-typeset .tabbed-set > input:first-child:checked ~ .tabbed-labels > :first-child, .md-typeset .tabbed-set > input:nth-child(10):checked ~ .tabbed-labels > :nth-child(10), .md-typeset .tabbed-set > input:nth-child(11):checked ~ .tabbed-labels > :nth-child(11), .md-typeset .tabbed-set > input:nth-child(12):checked ~ .tabbed-labels > :nth-child(12), .md-typeset .tabbed-set > input:nth-child(13):checked ~ .tabbed-labels > :nth-child(13), .md-typeset .tabbed-set > input:nth-child(14):checked ~ .tabbed-labels > :nth-child(14), .md-typeset .tabbed-set > input:nth-child(15):checked ~ .tabbed-labels > :nth-child(15), .md-typeset .tabbed-set > input:nth-child(16):checked ~ .tabbed-labels > :nth-child(16), .md-typeset .tabbed-set > input:nth-child(17):checked ~ .tabbed-labels > :nth-child(17), .md-typeset .tabbed-set > input:nth-child(18):checked ~ .tabbed-labels > :nth-child(18), .md-typeset .tabbed-set > input:nth-child(19):checked ~ .tabbed-labels > :nth-child(19), .md-typeset .tabbed-set > input:nth-child(2):checked ~ .tabbed-labels > :nth-child(2), .md-typeset .tabbed-set > input:nth-child(20):checked ~ .tabbed-labels > :nth-child(20), .md-typeset .tabbed-set > input:nth-child(3):checked ~ .tabbed-labels > :nth-child(3), .md-typeset .tabbed-set > input:nth-child(4):checked ~ .tabbed-labels > :nth-child(4), .md-typeset .tabbed-set > input:nth-child(5):checked ~ .tabbed-labels > :nth-child(5), .md-typeset .tabbed-set > input:nth-child(6):checked ~ .tabbed-labels > :nth-child(6), .md-typeset .tabbed-set > input:nth-child(7):checked ~ .tabbed-labels > :nth-child(7), .md-typeset .tabbed-set > input:nth-child(8):checked ~ .tabbed-labels > :nth-child(8), .md-typeset .tabbed-set > input:nth-child(9):checked ~ .tabbed-labels > :nth-child(9) {
+  color: #8315F9;
+  border-bottom: 1px solid #8315F9;
+}
+.md-footer *, html .md-footer-meta.md-typeset a {
+  color: rgb(111, 108, 121);
+}
+.repo-card {
+  height: 100%;
+}
+.header-btn {
+  text-align: center;
+}
+.header-btn, .sublist {
+  box-shadow: rgb(255, 255, 255) 0px 0px 0px 0px, rgb(217, 215, 226) 0px 0px 0px 1px, rgb(217, 215, 226) 0px 1px 2px 0px;
+}
+.header-btn:hover {
+  box-shadow: rgb(255, 255, 255) 0px 0px 0px 0px, rgb(217, 215, 226) 0px 0px 0px 1px, rgb(217, 215, 226) 0px 1.0001px 2.00013px -0.0000327245px, rgba(0, 0, 0, 0) 0px 0.000065449px 0.000130898px -0.000065449px;
+}
+.md-typeset .headerlink:hover, .md-typeset .headerlink:target {
+  color: #8315F9;
+}
+.md-typeset h1, .md-header__title {
+  color: black;
+  font-weight: 800;
+}
+.md-typeset h1 {
+  font-weight: normal;
+  margin-bottom: 1rem;
+}
+body {
+  background: linear-gradient(to left bottom, rgb(243, 238, 255), rgb(255, 255, 255) 60%) no-repeat;
+}
+
+/* .md-nav__link:has([tabindex=""]) {
+  text-transform: uppercase;
+} */
+
+.header-list {
+  display: flex;
+  align-items: center;
+  gap: 1rem;
+  list-style: none;
+  font-size: 0.75rem;
+  justify-content: flex-end;
+}
+.md-nav__list label, .md-nav--secondary label {
+  /* text-transform: uppercase; */
+  color: rgb(29, 29, 31) !important;
+  font-size: 0.7rem;
+  margin-bottom: 0;
+}
+.md-nav--secondary label {
+  margin-left: 0.5rem;
+}
+
+.md-nav__link {
+  padding: 0.25rem;
+  padding-left: 0.5rem;
+  padding-right: 0.5rem;
+}
+
+.md-nav__link--active {
+  background: rgb(243, 238, 255);
+  border-radius: 6px;
+  padding-top: 0.25rem;
+}
+
+.md-tabs__item--active {
+  color: var(--md-primary-fg-color);
+  border-bottom: 2px solid var(--md-primary-fg-color);
+}
+
+.md-nav--secondary .md-nav__title {
+  background: transparent;
+  box-shadow: none;
+}
+
+.md-header, .md-tabs {
+  color: rgb(111, 108, 121);
+  background-color: transparent;
+}
+.md-header--shadow {
+  background: linear-gradient(to left bottom, rgb(243, 238, 255), rgb(255, 255, 255) 60%);
+  box-shadow: none;
+  border-bottom: 1px solid rgb(229, 231, 235);
+}
+
+#item-logo {
+  display: none;
+}
+.md-main__inner, .md-header__inner, .md-grid {
+  max-width: 100%;
+}
+@media (max-width: 1200px) {
+  .md-header__inner {
+    display: flex;
+  }
+  .header-list {
+    display: none;
+  }
+  #item-logo {
+    display: block;
+  }
+}
+.md-content {
+  max-width: 40rem;
+  margin: auto;
+}
+/* // if no md-sidebar--primary, make .md-content full width */
+.md-main__inner:has(.md-sidebar--primary[hidden]) .md-content {
+  max-width: 100%;
+}
+.md-sidebar--primary {
+  flex: 0 20%;
+}
+.md-tabs {
+  border-bottom: 1px solid rgb(229, 231, 235);
+}
+.md-main__inner {
+  padding-top: 1rem;
+  margin-top: 0;
+}
 
 body.dark {
   /* Dark theme */
@@ -29,3 +228,43 @@ body[data-md-url$="/cookbooks/"] .md-content {
     margin-left: 0;
     width: 100%;
 }
+
+.md-main, nav .md-grid, .md-header__inner {
+  max-width: 1600px;
+  width: 100%;
+  margin: auto;
+}
+.md-search__scrollwrap {
+  width: 100% !important;
+}
+.md-nav--secondary .md-nav__title {
+  position: initial !important;
+}
+
+.md-header__title .md-ellipsis {
+  overflow: initial !important;
+  text-overflow: initial !important;
+}
+.md-search {
+  flex-grow: 0;
+}
+
+/* Table style */
+
+th, td {
+  border: 1px solid var(--md-typeset-table-color);
+}
+
+.md-typeset__table {
+  line-height: 1.5;
+}
+
+.md-typeset__table table:not([class]) {
+  font-size: 0.6rem;
+  border-collapse: collapse;
+}
+
+.md-typeset__table table:not([class]) td,
+.md-typeset__table table:not([class]) th {
+  padding: 10px;
+}

docs/theme/cookbooks.html

@@ -12,15 +12,15 @@
     </div>
     <div class="custom-grid">
       <a href="/develop/notebooks/quickstart"> <p class="card repo-card" data-name="Supervision Quickstart" data-labels="ANNOTATOR,DETECTION,SAM"
-          data-version="v0.18.0" data-author="SkalskiP,onuralpszr"></p>
+          data-version="v0.26.0" data-author="SkalskiP,onuralpszr"></p>
       </a>
       <a href="/develop/notebooks/count-objects-crossing-the-line">
         <p class="card repo-card" data-name="Count Objects Crossing the Line"
-          data-labels="ANNOTATORS,LINE ZONE,TRACKING" data-version="v0.18.0" data-author="SkalskiP"></p>
+          data-labels="ANNOTATORS,LINE ZONE,TRACKING" data-version="v0.26.0" data-author="SkalskiP"></p>
       </a>
       <a href="/develop/notebooks/zero-shot-object-detection-with-yolo-world">
         <p class="card repo-card" data-name="Zero-Shot Object Detection with YOLO-World"
-          data-labels="ANNOTATORS,DETECTION,INFERENCE" data-version="v0.19.0" data-author="SkalskiP"></p>
+          data-labels="ANNOTATORS,DETECTION,INFERENCE" data-version="v0.26.0" data-author="SkalskiP"></p>
       </a>
       <a href="/develop/notebooks/download-supervision-assets">
         <p class="card repo-card" data-name="Downloading Supervision Assets" data-labels="ASSETS" data-version="v0.18.0"
@@ -28,7 +28,7 @@
       </a>
       <a href="/develop/notebooks/annotate-video-with-detections">
         <p class="card repo-card" data-name="Annotate Video with Detections" data-labels="INFERENCE,YOLOV8"
-          data-version="v0.18.0" data-author="nickherrig"></p>
+          data-version="v0.26.0" data-author="nickherrig"></p>
       </a>
       <a href="/develop/notebooks/object-tracking">
         <p class="card repo-card" data-name="Object Tracking" data-labels="TRACKING, ANNOTATOR" data-version="v0.18.0"
@@ -36,23 +36,23 @@
       </a>
       <a href="/develop/notebooks/occupancy_analytics">
         <p class="card repo-card" data-name="Analyzing Zone Occupancy" data-labels="ANNOTATOR,DETECTION,ZONES"
-          data-version="v0.19.0" data-author="stellasphere"></p>
+          data-version="v0.26.0" data-author="stellasphere"></p>
       </a>
       <a href="/develop/notebooks/evaluating-alignment-of-text-to-image-diffusion-models">
         <p class="card repo-card" data-name="Evaluating Alignment of Text-to-image Diffusion Models"
-          data-labels="ANNOTATORS,YOLO WORLD" data-version="v0.19.0rc5" data-author="iamhatesz"></p>
+          data-labels="ANNOTATORS,YOLO WORLD" data-version="v0.26.0" data-author="iamhatesz"></p>
       </a>
       <a href="/develop/notebooks/serialise-detections-to-csv">
         <p class="card repo-card" data-name="Serialise Detections to a CSV File"
-          data-labels="DETECTIONS,CSV SINK,INFERENCE" data-version="v0.21.0" data-author="onuralpszr"></p>
+          data-labels="DETECTIONS,CSV SINK,INFERENCE" data-version="v0.26.0" data-author="onuralpszr"></p>
       </a>
       <a href="/develop/notebooks/serialise-detections-to-json">
         <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>
+          data-labels="DETECTIONS,JSON SINK,INFERENCE" data-version="v0.26.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>
+          data-labels="DETECTIONS,SAHI,SMALL,OBJECT,INFERENCE" data-version="v0.26.0" data-author="ediardo"></p>
       </a>
     </div>
   </div>

docs/theme/partials/header.html

@@ -0,0 +1,181 @@
+{% set class = "md-header" %}
+{% if "navigation.tabs.sticky" in features %}
+  {% set class = class ~ " md-header--shadow md-header--lifted" %}
+{% elif "navigation.tabs" not in features %}
+  {% set class = class ~ " md-header--shadow" %}
+{% endif %}
+
+<!-- Header -->
+<header class="{{ class }}" data-md-component="header">
+  <nav
+    class="md-header__inner md-grid"
+    aria-label="{{ lang.t('header') }}"
+  >
+
+    <!-- Link to home -->
+    <a
+      href="{{ config.extra.homepage | d(nav.homepage.url, true) | url }}"
+      title="{{ config.site_name | e }}"
+      class="md-header__button md-logo"
+      aria-label="{{ config.site_name }}"
+      data-md-component="logo"
+    >
+      {% include "partials/logo.html" %}
+    </a>
+
+    <!-- Button to open drawer -->
+    <label class="md-header__button md-icon" for="__drawer">
+      {% set icon = config.theme.icon.menu or "material/menu" %}
+      {% include ".icons/" ~ icon ~ ".svg" %}
+    </label>
+
+    <!-- Header title -->
+    <div class="md-header__title" data-md-component="header-title">
+      <div class="md-header__ellipsis">
+        <div class="md-header__topic">
+          <span class="md-ellipsis">
+            {{ config.site_name }} Docs
+          </span>
+        </div>
+        <div class="md-header__topic" data-md-component="header-topic">
+          <span class="md-ellipsis" style="display: flex; align-items: center; gap: 0.5rem;">
+            <a
+            href="{{ config.extra.homepage | d(nav.homepage.url, true) | url }}"
+            title="{{ config.site_name | e }}"
+            class="md-header__button md-logo"
+            aria-label="{{ config.site_name }}"
+            data-md-component="logo"
+            id="item-logo"
+            >
+            {% include "partials/logo.html" %}
+            </a>
+            {% if page.meta and page.meta.title %}
+              {{ page.meta.title }}
+            {% else %}
+              {{ page.title }}
+            {% endif %}
+          </span>
+        </div>
+      </div>
+    </div>
+    <!-- Button to open search modal -->
+    {% if "material/search" in config.plugins %}
+      {% set search = config.plugins["material/search"] | attr("config") %}
+
+      <!-- Check if search is actually enabled - see https://t.ly/DT_0V -->
+      {% if search.enabled %}
+        <label class="md-header__button md-icon" for="__search">
+          {% set icon = config.theme.icon.search or "material/magnify" %}
+          {% include ".icons/" ~ icon ~ ".svg" %}
+        </label>
+
+        <!-- Search interface -->
+        {% include "partials/search.html" %}
+      {% endif %}
+    {% endif %}
+
+
+    <ul class="header-list">
+        <li style="align-items: center;" id="resources-list">
+            <label for="dropdown-resources"><span>Resources <img src="https://ka-p.fontawesome.com/releases/v6.6.0/svgs/regular/chevron-down.svg?v=2&token=a463935e93" style="height: 0.5rem;" /></span></label>
+            <input type="radio" name="dropdown" id="dropdown-resources" style="display: none;" />
+            <ul class="resources-sublist sublist">
+                <li><a href="https://blog.roboflow.com">Blog</a></li>
+                <li><a href="https://discuss.roboflow.com">Community Forum</a></li>
+                <li><a href="https://roboflow.com/sales">Contact Sales</a></li>
+                <li><a href="https://universe.roboflow.com">Universe</a></li>
+            </ul>
+        </li>
+        <li style="align-items: center;" id="products-list">
+            <label for="dropdown-products"><span>Docs <img src="https://ka-p.fontawesome.com/releases/v6.6.0/svgs/regular/chevron-down.svg?v=2&token=a463935e93" style="height: 0.5rem;" /></span></label>
+            <input type="radio" name="dropdown" id="dropdown-products" style="display: none;" />
+            <ul class="products-sublist sublist">
+                <li><a href="https://inference.roboflow.com">Inference</a></li>
+                <li><a href="https://supervision.roboflow.com">Supervision</a></li>
+                <li><a href="https://trackers.roboflow.com">Trackers</a></li>
+                <li><a href="https://maestro.roboflow.com">Maestro</a></li>
+                <li><a href="https://docs.roboflow.com">Roboflow</a></li>
+            </ul>
+        </li>
+        <script>
+          document.addEventListener('click', function(event) {
+            const resourcesList = document.getElementById('resources-list');
+            const productsList = document.getElementById('products-list');
+            const dropdownResources = document.getElementById('dropdown-resources');
+            const dropdownProducts = document.getElementById('dropdown-products');
+
+            if (!resourcesList.contains(event.target)) {
+              dropdownResources.checked = false;
+            }
+            if (!productsList.contains(event.target)) {
+              dropdownProducts.checked = false;
+            }
+          });
+          // on mouse over
+          document.getElementById('resources-list').addEventListener('mouseover', function() {
+            document.getElementById('dropdown-resources').checked = true;
+          });
+          document.getElementById('products-list').addEventListener('mouseover', function() {
+            document.getElementById('dropdown-products').checked = true;
+          });
+          // on mouse out
+          document.getElementById('resources-list').addEventListener('mouseout', function() {
+            // if not hovering over the sublist or the label, uncheck the dropdown
+            // wait 1 sec
+            setTimeout(function() {
+              if (!document.querySelector('.resources-sublist:hover') && !document.querySelector('#resources-list:hover')) {
+                document.getElementById('dropdown-resources').checked = false;
+              }
+            }, 350);
+          });
+          // if mouseout of sublist, uncheck immediately
+          document.querySelector('.resources-sublist').addEventListener('mouseout', function() {
+            setTimeout(function() {
+              if (!document.querySelector('.resources-sublist:hover') && !document.querySelector('#resources-list:hover')) {
+                document.getElementById('dropdown-resources').checked = false;
+              }
+            }, 450);
+          });
+          document.getElementById('products-list').addEventListener('mouseout', function() {
+            // if not hovering over the sublist, uncheck the dropdown
+            // wait 1 sec
+            setTimeout(function() {
+              if (!document.querySelector('.products-sublist:hover') && !document.querySelector('#products-list:hover')) {
+                document.getElementById('dropdown-products').checked = false;
+              }
+            }, 500);
+          });
+          // if mouseout of sublist, uncheck immediately
+          document.querySelector('.products-sublist').addEventListener('mouseout', function() {
+            setTimeout(function() {
+              if (!document.querySelector('.products-sublist:hover') && !document.querySelector('#products-list:hover')) {
+                document.getElementById('dropdown-products').checked = false;
+              }
+            }, 500);
+          });
+
+        </script>
+        <style>
+          #dropdown-resources:checked ~ .resources-sublist {
+            display: block;
+          }
+          #dropdown-products:checked ~ .products-sublist {
+            display: block;
+          }
+          /* Hide dropdown if clicking outside */
+          body:not(:has(#dropdown-resources:checked)) .resources-sublist,
+          body:not(:has(#dropdown-products:checked)) .products-sublist {
+            display: none;
+          }
+        </style>
+        <a href="https://github.com/roboflow/supervision"><li class="header-btn" style="border-radius: 5px; color: white; background: var(--md-typeset-a-color); padding-top: 0.25rem; padding-left: 0.5rem; padding-bottom: 0.25rem; padding-right: 0.5rem; border: 1px solid #8315F9;">Go to GitHub</li></a>
+    </ul>
+  </nav>
+
+  <!-- Navigation tabs (sticky) -->
+  {% if "navigation.tabs.sticky" in features %}
+    {% if "navigation.tabs" in features %}
+      {% include "partials/tabs.html" %}
+    {% endif %}
+  {% endif %}
+</header>

docs/trackers.md

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

docs/utils/image.md

@@ -1,5 +1,6 @@
 ---
 comments: true
+status: new
 ---
 
 # Image Utils
@@ -29,10 +30,22 @@ comments: true
 :::supervision.utils.image.letterbox_image
 
 <div class="md-typeset">
-    <h2><a href="#supervision.utils.image.overlay_image">overlay_image</a></h2>
+    <h2><a href="#supervision.utils.image.tint_image">tint_image</a></h2>
 </div>
 
-:::supervision.utils.image.overlay_image
+:::supervision.utils.image.tint_image
+
+<div class="md-typeset">
+    <h2><a href="#supervision.utils.image.grayscale_image">grayscale_image</a></h2>
+</div>
+
+:::supervision.utils.image.grayscale_image
+
+<div class="md-typeset">
+    <h2><a href="#supervision.utils.image.get_image_resolution_wh">get_image_resolution_wh</a></h2>
+</div>
+
+:::supervision.utils.image.get_image_resolution_wh
 
 <div class="md-typeset">
     <h2><a href="#supervision.utils.image.ImageSink">ImageSink</a></h2>

examples/count_people_in_zone/inference_example.py

@@ -1,7 +1,6 @@
 import argparse
 import json
 import os
-from typing import List, Tuple
 
 import cv2
 import numpy as np
@@ -14,7 +13,7 @@ import supervision as sv
 COLORS = sv.ColorPalette.DEFAULT
 
 
-def load_zones_config(file_path: str) -> List[np.ndarray]:
+def load_zones_config(file_path: str) -> list[np.ndarray]:
     """
     Load polygon zone configurations from a JSON file.
 
@@ -28,14 +27,14 @@ def load_zones_config(file_path: str) -> List[np.ndarray]:
     Returns:
     List[np.ndarray]: A list of polygons, each represented as a NumPy array.
     """
-    with open(file_path, "r") as file:
+    with open(file_path) as file:
         data = json.load(file)
         return [np.array(polygon, np.int32) for polygon in data["polygons"]]
 
 
 def initiate_annotators(
-    polygons: List[np.ndarray], resolution_wh: Tuple[int, int]
-) -> Tuple[List[sv.PolygonZone], List[sv.PolygonZoneAnnotator], List[sv.BoxAnnotator]]:
+    polygons: list[np.ndarray], resolution_wh: tuple[int, int]
+) -> tuple[list[sv.PolygonZone], list[sv.PolygonZoneAnnotator], list[sv.BoxAnnotator]]:
     line_thickness = sv.calculate_optimal_line_thickness(resolution_wh=resolution_wh)
     text_scale = sv.calculate_optimal_text_scale(resolution_wh=resolution_wh)
 
@@ -93,9 +92,9 @@ def detect(
 
 def annotate(
     frame: np.ndarray,
-    zones: List[sv.PolygonZone],
-    zone_annotators: List[sv.PolygonZoneAnnotator],
-    box_annotators: List[sv.BoxAnnotator],
+    zones: list[sv.PolygonZone],
+    zone_annotators: list[sv.PolygonZoneAnnotator],
+    box_annotators: list[sv.BoxAnnotator],
     detections: sv.Detections,
 ) -> np.ndarray:
     """

examples/count_people_in_zone/requirements.txt

@@ -1,5 +1,5 @@
 gdown
-inference==0.9.17
-supervision>=0.20.0
+inference
+supervision
 tqdm
-ultralytics<=8.3.40
+ultralytics

examples/count_people_in_zone/ultralytics_example.py

@@ -1,6 +1,5 @@
 import argparse
 import json
-from typing import List, Tuple
 
 import cv2
 import numpy as np
@@ -12,7 +11,7 @@ import supervision as sv
 COLORS = sv.ColorPalette.DEFAULT
 
 
-def load_zones_config(file_path: str) -> List[np.ndarray]:
+def load_zones_config(file_path: str) -> list[np.ndarray]:
     """
     Load polygon zone configurations from a JSON file.
 
@@ -26,14 +25,14 @@ def load_zones_config(file_path: str) -> List[np.ndarray]:
     Returns:
     List[np.ndarray]: A list of polygons, each represented as a NumPy array.
     """
-    with open(file_path, "r") as file:
+    with open(file_path) as file:
         data = json.load(file)
         return [np.array(polygon, np.int32) for polygon in data["polygons"]]
 
 
 def initiate_annotators(
-    polygons: List[np.ndarray], resolution_wh: Tuple[int, int]
-) -> Tuple[List[sv.PolygonZone], List[sv.PolygonZoneAnnotator], List[sv.BoxAnnotator]]:
+    polygons: list[np.ndarray], resolution_wh: tuple[int, int]
+) -> tuple[list[sv.PolygonZone], list[sv.PolygonZoneAnnotator], list[sv.BoxAnnotator]]:
     line_thickness = sv.calculate_optimal_line_thickness(resolution_wh=resolution_wh)
     text_scale = sv.calculate_optimal_text_scale(resolution_wh=resolution_wh)
 
@@ -90,9 +89,9 @@ def detect(
 
 def annotate(
     frame: np.ndarray,
-    zones: List[sv.PolygonZone],
-    zone_annotators: List[sv.PolygonZoneAnnotator],
-    box_annotators: List[sv.BoxAnnotator],
+    zones: list[sv.PolygonZone],
+    zone_annotators: list[sv.PolygonZoneAnnotator],
+    box_annotators: list[sv.BoxAnnotator],
     detections: sv.Detections,
 ) -> np.ndarray:
     """
@@ -135,7 +134,7 @@ if __name__ == "__main__":
     )
     parser.add_argument(
         "--source_weights_path",
-        default="yolov8x.pt",
+        default="yolo11x.pt",
         help="Path to the source weights file",
         type=str,
     )

examples/heatmap_and_track/requirements.txt

@@ -1,2 +1,2 @@
-supervision[assets]==0.19.0
-ultralytics<=8.3.40
+supervision
+ultralytics

examples/speed_estimation/requirements.txt

@@ -1,6 +1,6 @@
-supervision>=0.20.0
-tqdm==4.66.3
+supervision
+tqdm
 requests
-ultralytics==8.0.237
+ultralytics
 super-gradients==3.5.0
-inference==0.9.17
+inference

examples/speed_estimation/ultralytics_example.py

@@ -70,7 +70,7 @@ if __name__ == "__main__":
     args = parse_arguments()
 
     video_info = sv.VideoInfo.from_video_path(video_path=args.source_video_path)
-    model = YOLO("yolov8x.pt")
+    model = YOLO("yolo11x.pt")
 
     byte_track = sv.ByteTrack(
         frame_rate=video_info.fps, track_activation_threshold=args.confidence_threshold

examples/time_in_zone/inference_file_example.py

@@ -1,5 +1,4 @@
 import argparse
-from typing import List
 
 import cv2
 import numpy as np
@@ -22,7 +21,7 @@ def main(
     model_id: str,
     confidence: float,
     iou: float,
-    classes: List[int],
+    classes: list[int],
 ) -> None:
     model = get_model(model_id=model_id)
     tracker = sv.ByteTrack(minimum_matching_threshold=0.5)

examples/time_in_zone/inference_naive_stream_example.py

@@ -1,5 +1,4 @@
 import argparse
-from typing import List
 
 import cv2
 import numpy as np
@@ -22,7 +21,7 @@ def main(
     model_id: str,
     confidence: float,
     iou: float,
-    classes: List[int],
+    classes: list[int],
 ) -> None:
     model = get_model(model_id=model_id)
     tracker = sv.ByteTrack(minimum_matching_threshold=0.5)

examples/time_in_zone/inference_stream_example.py

@@ -1,5 +1,4 @@
 import argparse
-from typing import List
 
 import cv2
 import numpy as np
@@ -18,7 +17,7 @@ LABEL_ANNOTATOR = sv.LabelAnnotator(
 
 
 class CustomSink:
-    def __init__(self, zone_configuration_path: str, classes: List[int]):
+    def __init__(self, zone_configuration_path: str, classes: list[int]):
         self.classes = classes
         self.tracker = sv.ByteTrack(minimum_matching_threshold=0.5)
         self.fps_monitor = sv.FPSMonitor()
@@ -83,7 +82,7 @@ def main(
     model_id: str,
     confidence: float,
     iou: float,
-    classes: List[int],
+    classes: list[int],
 ) -> None:
     sink = CustomSink(zone_configuration_path=zone_configuration_path, classes=classes)
 

examples/time_in_zone/requirements.txt

@@ -1,5 +1,6 @@
-opencv-python
-supervision>=0.20.0
-ultralytics<=8.3.40
-inference==0.9.17
-pytube
+supervision
+ultralytics
+inference
+# https://github.com/pytube/pytube/issues/2044
+# pytube
+pytubefix

examples/time_in_zone/scripts/download_from_youtube.py

@@ -1,11 +1,12 @@
+from __future__ import annotations
+
 import argparse
 import os
-from typing import Optional
 
-from pytube import YouTube
+from pytubefix import YouTube
 
 
-def main(url: str, output_path: Optional[str], file_name: Optional[str]) -> None:
+def main(url: str, output_path: str | None, file_name: str | None) -> None:
     yt = YouTube(url)
     stream = yt.streams.get_highest_resolution()
 

examples/time_in_zone/scripts/draw_zones.py

@@ -1,7 +1,9 @@
+from __future__ import annotations
+
 import argparse
 import json
 import os
-from typing import Any, Optional, Tuple
+from typing import Any
 
 import cv2
 import numpy as np
@@ -19,10 +21,10 @@ COLORS = sv.ColorPalette.DEFAULT
 WINDOW_NAME = "Draw Zones"
 POLYGONS = [[]]
 
-current_mouse_position: Optional[Tuple[int, int]] = None
+current_mouse_position: tuple[int, int] | None = None
 
 
-def resolve_source(source_path: str) -> Optional[np.ndarray]:
+def resolve_source(source_path: str) -> np.ndarray | None:
     if not os.path.exists(source_path):
         return None
 

examples/time_in_zone/ultralytics_file_example.py

@@ -1,5 +1,4 @@
 import argparse
-from typing import List
 
 import cv2
 import numpy as np
@@ -23,7 +22,7 @@ def main(
     device: str,
     confidence: float,
     iou: float,
-    classes: List[int],
+    classes: list[int],
 ) -> None:
     model = YOLO(weights)
     tracker = sv.ByteTrack(minimum_matching_threshold=0.5)

examples/time_in_zone/ultralytics_naive_stream_example.py

@@ -1,5 +1,4 @@
 import argparse
-from typing import List
 
 import cv2
 import numpy as np
@@ -23,7 +22,7 @@ def main(
     device: str,
     confidence: float,
     iou: float,
-    classes: List[int],
+    classes: list[int],
 ) -> None:
     model = YOLO(weights)
     tracker = sv.ByteTrack(minimum_matching_threshold=0.5)

examples/time_in_zone/ultralytics_stream_example.py

@@ -1,5 +1,4 @@
 import argparse
-from typing import List
 
 import cv2
 import numpy as np
@@ -19,7 +18,7 @@ LABEL_ANNOTATOR = sv.LabelAnnotator(
 
 
 class CustomSink:
-    def __init__(self, zone_configuration_path: str, classes: List[int]):
+    def __init__(self, zone_configuration_path: str, classes: list[int]):
         self.classes = classes
         self.tracker = sv.ByteTrack(minimum_matching_threshold=0.8)
         self.fps_monitor = sv.FPSMonitor()
@@ -84,7 +83,7 @@ def main(
     device: str,
     confidence: float,
     iou: float,
-    classes: List[int],
+    classes: list[int],
 ) -> None:
     model = YOLO(weights)
 

examples/time_in_zone/utils/general.py

@@ -1,11 +1,11 @@
 import json
-from typing import Generator, List
+from collections.abc import Generator
 
 import cv2
 import numpy as np
 
 
-def load_zones_config(file_path: str) -> List[np.ndarray]:
+def load_zones_config(file_path: str) -> list[np.ndarray]:
     """
     Load polygon zone configurations from a JSON file.
 
@@ -19,12 +19,12 @@ def load_zones_config(file_path: str) -> List[np.ndarray]:
     Returns:
         List[np.ndarray]: A list of polygons, each represented as a NumPy array.
     """
-    with open(file_path, "r") as file:
+    with open(file_path) as file:
         data = json.load(file)
         return [np.array(polygon, np.int32) for polygon in data]
 
 
-def find_in_list(array: np.ndarray, search_list: List[int]) -> np.ndarray:
+def find_in_list(array: np.ndarray, search_list: list[int]) -> np.ndarray:
     """Determines if elements of a numpy array are present in a list.
 
     Args:

examples/time_in_zone/utils/timers.py

@@ -1,5 +1,4 @@
 from datetime import datetime
-from typing import Dict
 
 import numpy as np
 
@@ -26,7 +25,7 @@ class FPSBasedTimer:
         """
         self.fps = fps
         self.frame_id = 0
-        self.tracker_id2frame_id: Dict[int, int] = {}
+        self.tracker_id2frame_id: dict[int, int] = {}
 
     def tick(self, detections: sv.Detections) -> np.ndarray:
         """Processes the current frame, updating time durations for each tracker.
@@ -63,7 +62,7 @@ class ClockBasedTimer:
 
     def __init__(self) -> None:
         """Initializes the ClockBasedTimer."""
-        self.tracker_id2start_time: Dict[int, datetime] = {}
+        self.tracker_id2start_time: dict[int, datetime] = {}
 
     def tick(self, detections: sv.Detections) -> np.ndarray:
         """Processes the current frame, updating time durations for each tracker.

examples/tracking/requirements.txt

@@ -1,4 +1,4 @@
-inference==0.9.17
-supervision==0.19.0
+inference
+supervision
 tqdm
-ultralytics<=8.3.40
+ultralytics

examples/traffic_analysis/inference_example.py

@@ -1,6 +1,8 @@
+from __future__ import annotations
+
 import argparse
 import os
-from typing import Dict, Iterable, List, Optional, Set
+from collections.abc import Iterable
 
 import cv2
 import numpy as np
@@ -29,14 +31,14 @@ ZONE_OUT_POLYGONS = [
 
 class DetectionsManager:
     def __init__(self) -> None:
-        self.tracker_id_to_zone_id: Dict[int, int] = {}
-        self.counts: Dict[int, Dict[int, Set[int]]] = {}
+        self.tracker_id_to_zone_id: dict[int, int] = {}
+        self.counts: dict[int, dict[int, set[int]]] = {}
 
     def update(
         self,
         detections_all: sv.Detections,
-        detections_in_zones: List[sv.Detections],
-        detections_out_zones: List[sv.Detections],
+        detections_in_zones: list[sv.Detections],
+        detections_out_zones: list[sv.Detections],
     ) -> sv.Detections:
         for zone_in_id, detections_in_zone in enumerate(detections_in_zones):
             for tracker_id in detections_in_zone.tracker_id:
@@ -59,9 +61,9 @@ class DetectionsManager:
 
 
 def initiate_polygon_zones(
-    polygons: List[np.ndarray],
+    polygons: list[np.ndarray],
     triggering_anchors: Iterable[sv.Position] = [sv.Position.CENTER],
-) -> List[sv.PolygonZone]:
+) -> list[sv.PolygonZone]:
     return [
         sv.PolygonZone(
             polygon=polygon,
@@ -77,7 +79,7 @@ class VideoProcessor:
         roboflow_api_key: str,
         model_id: str,
         source_video_path: str,
-        target_video_path: Optional[str] = None,
+        target_video_path: str | None = None,
         confidence_threshold: float = 0.3,
         iou_threshold: float = 0.7,
     ) -> None:

examples/traffic_analysis/requirements.txt

@@ -1,5 +1,5 @@
 gdown
-inference==0.9.17
-supervision>=0.20.0
+inference
+supervision
 tqdm
-ultralytics<=8.3.40
+ultralytics

examples/traffic_analysis/ultralytics_example.py

@@ -1,5 +1,7 @@
+from __future__ import annotations
+
 import argparse
-from typing import Dict, Iterable, List, Optional, Set
+from collections.abc import Iterable
 
 import cv2
 import numpy as np
@@ -27,14 +29,14 @@ ZONE_OUT_POLYGONS = [
 
 class DetectionsManager:
     def __init__(self) -> None:
-        self.tracker_id_to_zone_id: Dict[int, int] = {}
-        self.counts: Dict[int, Dict[int, Set[int]]] = {}
+        self.tracker_id_to_zone_id: dict[int, int] = {}
+        self.counts: dict[int, dict[int, set[int]]] = {}
 
     def update(
         self,
         detections_all: sv.Detections,
-        detections_in_zones: List[sv.Detections],
-        detections_out_zones: List[sv.Detections],
+        detections_in_zones: list[sv.Detections],
+        detections_out_zones: list[sv.Detections],
     ) -> sv.Detections:
         for zone_in_id, detections_in_zone in enumerate(detections_in_zones):
             for tracker_id in detections_in_zone.tracker_id:
@@ -57,9 +59,9 @@ class DetectionsManager:
 
 
 def initiate_polygon_zones(
-    polygons: List[np.ndarray],
+    polygons: list[np.ndarray],
     triggering_anchors: Iterable[sv.Position] = [sv.Position.CENTER],
-) -> List[sv.PolygonZone]:
+) -> list[sv.PolygonZone]:
     return [
         sv.PolygonZone(
             polygon=polygon,
@@ -74,7 +76,7 @@ class VideoProcessor:
         self,
         source_weights_path: str,
         source_video_path: str,
-        target_video_path: Optional[str] = None,
+        target_video_path: str | None = None,
         confidence_threshold: float = 0.3,
         iou_threshold: float = 0.7,
     ) -> None:

mkdocs.yml

@@ -3,9 +3,8 @@ site_url: https://supervision.roboflow.com/
 site_author: Roboflow
 site_description: A set of easy-to-use utilities that will come in handy in any computer vision project.
 repo_name: roboflow/supervision
-repo_url: https://github.com/roboflow/supervision
 edit_uri: https://github.com/roboflow/supervision/tree/main/docs
-copyright: Roboflow 2024. All rights reserved.
+copyright: Roboflow 2025. All rights reserved.
 
 extra:
   social:
@@ -13,12 +12,8 @@ extra:
       link: https://github.com/roboflow
     - icon: fontawesome/brands/python
       link: https://pypi.org/project/supervision
-    - icon: fontawesome/brands/docker
-      link: https://hub.docker.com/u/roboflow
     - icon: fontawesome/brands/youtube
       link: https://www.youtube.com/roboflow
-    - icon: fontawesome/brands/linkedin
-      link: https://www.linkedin.com/company/roboflow-ai/
     - icon: fontawesome/brands/x-twitter
       link: https://twitter.com/roboflow
     - icon: fontawesome/brands/discord
@@ -31,10 +26,10 @@ extra:
 
 extra_css:
   - stylesheets/extra.css
-  - stylesheets/cookbooks-card.css
+  - stylesheets/cookbooks_card.css
 
 nav:
-  - Supervision: index.md
+  - Home: index.md
   - Learn:
       - Detect and Annotate: how_to/detect_and_annotate.md
       - Save Detections: how_to/save_detections.md
@@ -43,13 +38,16 @@ nav:
       - Track Objects on Video: how_to/track_objects.md
       - Process Datasets: how_to/process_datasets.md
       - Benchmark a Model: how_to/benchmark_a_model.md
-
-  - Reference - Code API:
+  - Reference:
       - Detection and Segmentation:
           - Core: detection/core.md
           - Annotators: detection/annotators.md
-          - Double Detection Filter: detection/double_detection_filter.md
-          - Utils: detection/utils.md
+          - Converters: detection/utils/converters.md
+          - IoU and NMS: detection/utils/iou_and_nms.md
+          - Boxes: detection/utils/boxes.md
+          - Masks: detection/utils/masks.md
+          - Polygons: detection/utils/polygons.md
+          - VLMs: detection/utils/vlms.md
       - Keypoint Detection:
           - Core: keypoint/core.md
           - Annotators: keypoint/annotators.md
@@ -83,12 +81,7 @@ nav:
           - Geometry: utils/geometry.md
       - Assets: assets.md
   - Cookbooks: cookbooks.md
-  - Cheatsheet: https://roboflow.github.io/cheatsheet-supervision/
-  - Contribute:
-      - Contributing: contributing.md
-      - Code of Conduct: code_of_conduct.md
-      - License: license.md
-  - Release Notes:
+  - Changelog:
       - Changelog: changelog.md
       - Deprecated: deprecated.md
 
@@ -106,6 +99,7 @@ theme:
     - content.tooltips
     - content.code.annotate
     - navigation.tabs
+    - navigation.tabs.sticky
 
   palette:
     # Palette for light mode
@@ -123,11 +117,8 @@ theme:
         name: Switch to light mode
 
   font:
-    text: Roboto
-    code: Roboto Mono
-    features:
-      - content.code.copy
-      - content.code.annotate
+    text: Inter
+    code: IBM Plex Mono
 
 plugins:
   - search
@@ -181,12 +172,16 @@ markdown_extensions:
       anchor_linenums: true
       line_spans: __span
       pygments_lang_class: true
+  - pymdownx.arithmatex:
+      generic: true
 
 extra_javascript:
   - "javascripts/init_kapa_widget.js"
   - "javascripts/cookbooks-card.js"
   - "javascripts/segment.js"
+  - "javascripts/mathjax.js"
   - "https://cdnjs.cloudflare.com/ajax/libs/dompurify/3.0.8/purify.min.js"
+  - "https://unpkg.com/mathjax@3/es5/tex-mml-chtml.js"
 
 # Messages shown during document build
 # Reference: https://www.mkdocs.org/user-guide/configuration/#validation

pyproject.toml

@@ -2,9 +2,9 @@
 name = "supervision"
 description = "A set of easy-to-use utils that will come in handy in any Computer Vision project"
 license = { text = "MIT" }
-version = "0.26.0rc7"
+version = "0.27.0"
 readme = "README.md"
-requires-python = ">=3.8"
+requires-python = ">=3.9"
 authors = [
     { name = "Piotr Skalski", email = "piotr.skalski92@gmail.com" }
 ]
@@ -58,6 +58,8 @@ Documentation = "https://supervision.roboflow.com/latest/"
 metrics = [
     "pandas>=2.0.0",
 ]
+
+[dependency-groups]
 dev = [
     "pytest>=7.2.2,<9.0.0",
     "tox>=4.11.4",
@@ -65,21 +67,22 @@ dev = [
     "ipywidgets>=8.1.1",
     "jupytext>=1.16.1",
     "nbconvert>=7.14.2",
-    "docutils!=0.21"
+    "docutils!=0.21",
+    "pre-commit>=3.8.0"
 ]
 docs = [
     "mkdocs-material[imaging]>=9.5.5",
-    "mkdocstrings>=0.25.2,<0.30.0",
+    "mkdocstrings>=0.25.2,<0.31.0",
     "mkdocstrings-python>=1.10.9",
     "mike>=2.0.0",
     "mkdocs-jupyter>=0.24.3",
-    "mkdocs-git-committers-plugin-2>=2.4.1; python_version >= '3.8' and python_version < '4'",
+    "mkdocs-git-committers-plugin-2>=2.4.1; python_version >= '3.9' and python_version < '4'",
     "mkdocs-git-revision-date-localized-plugin>=1.2.4"
 ]
 build = [
     "twine>=5.1.1,<7.0.0",
     "wheel>=0.40,<0.46",
-    "build>=0.10,<1.3"
+    "build>=0.10,<1.4"
 ]
 
 [tool.bandit]
@@ -91,7 +94,7 @@ check = true
 imports = ["cv2", "supervision"]
 
 [tool.ruff]
-target-version = "py38"
+target-version = "py39"
 
 # Exclude a variety of commonly ignored directories.
 exclude = [
@@ -126,7 +129,7 @@ indent-width = 4
 
 [tool.ruff.lint]
 # Enable pycodestyle (`E`) and Pyflakes (`F`) codes by default.
-select = ["E", "F", "I", "A", "Q", "W", "RUF"]
+select = ["E", "F", "I", "A", "Q", "W", "RUF", "UP"]
 ignore = []
 # Allow autofix for all enabled rules (when `--fix`) is provided.
 fixable = [

supervision/__init__.py

@@ -38,6 +38,7 @@ from supervision.dataset.core import (
     ClassificationDataset,
     DetectionDataset,
 )
+from supervision.dataset.formats.coco import get_coco_class_index_mapping
 from supervision.dataset.utils import mask_to_rle, rle_to_mask
 from supervision.detection.core import Detections
 from supervision.detection.line_zone import (
@@ -45,40 +46,55 @@ from supervision.detection.line_zone import (
     LineZoneAnnotator,
     LineZoneAnnotatorMulticlass,
 )
-from supervision.detection.overlap_filter import (
-    OverlapFilter,
-    box_non_max_merge,
-    box_non_max_suppression,
-    mask_non_max_suppression,
-)
 from supervision.detection.tools.csv_sink import CSVSink
 from supervision.detection.tools.inference_slicer import InferenceSlicer
 from supervision.detection.tools.json_sink import JSONSink
 from supervision.detection.tools.polygon_zone import PolygonZone, PolygonZoneAnnotator
 from supervision.detection.tools.smoother import DetectionsSmoother
-from supervision.detection.utils import (
-    box_iou_batch,
-    calculate_masks_centroids,
+from supervision.detection.utils.boxes import (
     clip_boxes,
-    contains_holes,
-    contains_multiple_segments,
-    filter_polygons_by_area,
-    mask_iou_batch,
+    denormalize_boxes,
+    move_boxes,
+    pad_boxes,
+    scale_boxes,
+)
+from supervision.detection.utils.converters import (
     mask_to_polygons,
     mask_to_xyxy,
-    move_boxes,
-    move_masks,
-    oriented_box_iou_batch,
-    pad_boxes,
     polygon_to_mask,
     polygon_to_xyxy,
-    scale_boxes,
     xcycwh_to_xyxy,
     xywh_to_xyxy,
+    xyxy_to_mask,
     xyxy_to_polygons,
     xyxy_to_xcycarh,
     xyxy_to_xywh,
 )
+from supervision.detection.utils.iou_and_nms import (
+    OverlapFilter,
+    OverlapMetric,
+    box_iou,
+    box_iou_batch,
+    box_iou_batch_with_jaccard,
+    box_non_max_merge,
+    box_non_max_suppression,
+    mask_iou_batch,
+    mask_non_max_merge,
+    mask_non_max_suppression,
+    oriented_box_iou_batch,
+)
+from supervision.detection.utils.masks import (
+    calculate_masks_centroids,
+    contains_holes,
+    contains_multiple_segments,
+    filter_segments_by_distance,
+    move_masks,
+)
+from supervision.detection.utils.polygons import (
+    approximate_polygon,
+    filter_polygons_by_area,
+)
+from supervision.detection.utils.vlms import edit_distance, fuzzy_match_index
 from supervision.detection.vlm import LMM, VLM
 from supervision.draw.color import Color, ColorPalette
 from supervision.draw.utils import (
@@ -94,24 +110,26 @@ from supervision.draw.utils import (
 )
 from supervision.geometry.core import Point, Position, Rect
 from supervision.geometry.utils import get_polygon_center
-from supervision.keypoint.annotators import (
+from supervision.key_points.annotators import (
     EdgeAnnotator,
     VertexAnnotator,
     VertexLabelAnnotator,
 )
-from supervision.keypoint.core import KeyPoints
+from supervision.key_points.core import KeyPoints
 from supervision.metrics.detection import ConfusionMatrix, MeanAveragePrecision
 from supervision.tracker.byte_tracker.core import ByteTrack
 from supervision.utils.conversion import cv2_to_pillow, pillow_to_cv2
 from supervision.utils.file import list_files_with_extensions
 from supervision.utils.image import (
     ImageSink,
-    create_tiles,
     crop_image,
+    get_image_resolution_wh,
+    grayscale_image,
     letterbox_image,
     overlay_image,
     resize_image,
     scale_image,
+    tint_image,
 )
 from supervision.utils.notebook import plot_image, plot_images_grid
 from supervision.utils.video import (
@@ -163,6 +181,7 @@ __all__ = [
     "MeanAveragePrecision",
     "OrientedBoxAnnotator",
     "OverlapFilter",
+    "OverlapMetric",
     "PercentageBarAnnotator",
     "PixelateAnnotator",
     "Point",
@@ -179,7 +198,10 @@ __all__ = [
     "VertexLabelAnnotator",
     "VideoInfo",
     "VideoSink",
+    "approximate_polygon",
+    "box_iou",
     "box_iou_batch",
+    "box_iou_batch_with_jaccard",
     "box_non_max_merge",
     "box_non_max_suppression",
     "calculate_masks_centroids",
@@ -188,7 +210,6 @@ __all__ = [
     "clip_boxes",
     "contains_holes",
     "contains_multiple_segments",
-    "create_tiles",
     "crop_image",
     "cv2_to_pillow",
     "draw_filled_polygon",
@@ -198,12 +219,19 @@ __all__ = [
     "draw_polygon",
     "draw_rectangle",
     "draw_text",
+    "edit_distance",
     "filter_polygons_by_area",
+    "filter_segments_by_distance",
+    "fuzzy_match_index",
+    "get_coco_class_index_mapping",
+    "get_image_resolution_wh",
     "get_polygon_center",
     "get_video_frames_generator",
+    "grayscale_image",
     "letterbox_image",
     "list_files_with_extensions",
     "mask_iou_batch",
+    "mask_non_max_merge",
     "mask_non_max_suppression",
     "mask_to_polygons",
     "mask_to_rle",
@@ -223,9 +251,11 @@ __all__ = [
     "rle_to_mask",
     "scale_boxes",
     "scale_image",
+    "tint_image",
     "xcycwh_to_xyxy",
     "xywh_to_xyxy",
+    "xyxy_to_mask",
     "xyxy_to_polygons",
-    "xyxy_to_xyah",
+    "xyxy_to_xcycarh",
     "xyxy_to_xywh",
 ]

supervision/annotators/base.py

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

supervision/annotators/utils.py

@@ -1,8 +1,12 @@
+from __future__ import annotations
+
+import textwrap
 from enum import Enum
-from typing import Optional, Tuple, Union
+from typing import Any
 
 import numpy as np
 
+from supervision.config import CLASS_NAME_DATA_FIELD
 from supervision.detection.core import Detections
 from supervision.draw.color import Color, ColorPalette
 from supervision.geometry.core import Position
@@ -33,7 +37,7 @@ class ColorLookup(Enum):
 def resolve_color_idx(
     detections: Detections,
     detection_idx: int,
-    color_lookup: Union[ColorLookup, np.ndarray] = ColorLookup.CLASS,
+    color_lookup: ColorLookup | np.ndarray = ColorLookup.CLASS,
 ) -> int:
     if detection_idx >= len(detections):
         raise ValueError(
@@ -70,10 +74,10 @@ def resolve_color_idx(
 
 
 def resolve_text_background_xyxy(
-    center_coordinates: Tuple[int, int],
-    text_wh: Tuple[int, int],
+    center_coordinates: tuple[int, int],
+    text_wh: tuple[int, int],
     position: Position,
-) -> Tuple[int, int, int, int]:
+) -> tuple[int, int, int, int]:
     center_x, center_y = center_coordinates
     text_w, text_h = text_wh
 
@@ -122,32 +126,199 @@ def resolve_text_background_xyxy(
         )
 
 
-def get_color_by_index(color: Union[Color, ColorPalette], idx: int) -> Color:
+def get_color_by_index(color: Color | ColorPalette, idx: int) -> Color:
     if isinstance(color, ColorPalette):
         return color.by_idx(idx)
     return color
 
 
 def resolve_color(
-    color: Union[Color, ColorPalette],
+    color: Color | ColorPalette,
     detections: Detections,
     detection_idx: int,
-    color_lookup: Union[ColorLookup, np.ndarray] = ColorLookup.CLASS,
+    color_lookup: ColorLookup | np.ndarray = ColorLookup.CLASS,
 ) -> Color:
     idx = resolve_color_idx(
         detections=detections,
         detection_idx=detection_idx,
         color_lookup=color_lookup,
     )
-    if color_lookup == ColorLookup.TRACK and idx == PENDING_TRACK_ID:
+    if (
+        isinstance(color_lookup, ColorLookup)
+        and color_lookup == ColorLookup.TRACK
+        and idx == PENDING_TRACK_ID
+    ):
         return PENDING_TRACK_COLOR
     return get_color_by_index(color=color, idx=idx)
 
 
+def wrap_text(text: Any, max_line_length=None) -> list[str]:
+    """
+    Wrap `text` to the specified maximum line length, respecting existing
+    newlines. Falls back to str() if `text` is not already a string.
+
+    Args:
+        text (Any): The text (or object) to wrap.
+        max_line_length (int | None): Maximum width for each wrapped line.
+
+    Returns:
+        list[str]: Wrapped lines.
+    """
+
+    if not text:
+        return [""]
+
+    if not isinstance(text, str):
+        text = str(text)
+
+    if max_line_length is None:
+        return text.splitlines() or [""]
+
+    if max_line_length <= 0:
+        raise ValueError("max_line_length must be a positive integer")
+
+    paragraphs = text.split("\n")
+    all_lines: list[str] = []
+
+    for paragraph in paragraphs:
+        if paragraph == "":
+            all_lines.append("")
+            continue
+
+        wrapped = textwrap.wrap(
+            paragraph,
+            width=max_line_length,
+            break_long_words=True,
+            replace_whitespace=False,
+            drop_whitespace=True,
+        )
+
+        all_lines.extend(wrapped or [""])
+
+    return all_lines or [""]
+
+
+def validate_labels(labels: list[str] | None, detections: Detections):
+    """
+    Validates that the number of provided labels matches the number of detections.
+
+    Args:
+        labels (Optional[List[str]]): A list of labels, one for each detection. Can
+                                        be None.
+        detections (Detections): The detections to be labeled.
+
+    Raises:
+        ValueError: If `labels` is not None and its length does not match the number
+        of detections.
+    """
+    if labels is not None and len(labels) != len(detections):
+        raise ValueError(
+            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."
+        )
+
+
+def get_labels_text(
+    detections: Detections, custom_labels: list[str] | None
+) -> list[str]:
+    """
+    Retrieves the text labels for the detections.
+
+    If `custom_labels` are provided, they are used. Otherwise, the labels are
+    extracted from the `detections` object, prioritizing the 'class_name' field,
+    then the `class_id`, and finally using the detection index as a string.
+
+    Args:
+        detections (Detections): The detections to get labels for.
+        custom_labels (Optional[List[str]]): An optional list of custom labels.
+
+    Returns:
+        List[str]: A list of text labels for each detection.
+    """
+    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 snap_boxes(xyxy: np.ndarray, resolution_wh: tuple[int, int]) -> np.ndarray:
+    """
+    Shifts `label` bounding boxes into the frame so that they are fully contained
+    within the given resolution, prioritizing the top/left edge.
+    Unlike `clip_boxes`, this function does not crop boxes.
+    It moves them entirely if they exceed the frame boundaries.
+
+    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)`.
+        resolution_wh (Tuple[int, int]): A tuple `(width, height)`
+            representing the resolution of the frame.
+
+    Returns:
+        np.ndarray: A numpy array of shape `(N, 4)` with boxes shifted into frame.
+
+    Examples:
+    ```python
+    import numpy as np
+
+    # Example boxes:
+    xyxy = np.array([
+        [-10, 10, 30, 50],     # Off left edge
+        [310, 200, 350, 250],  # Off right edge
+        [100, -20, 150, 30],   # Off top edge
+        [200, 220, 250, 270],  # Off bottom edge
+        [-20, 10, 350, 50],    # Wider than frame (370 vs 320)
+        [10, -20, 30, 260]     # Taller than frame (280 vs 240)
+    ])
+
+    resolution_wh = (320, 240)
+    snapped_boxes = snap_boxes(xyxy=xyxy, resolution_wh=resolution_wh)
+
+    # Results:
+    # [[  0  10  40  50]  # Left edge shifted right
+    #  [280 200 320 250]  # Right edge shifted left
+    #  [100   0 150  50]  # Top edge shifted down
+    #  [200 190 250 240]  # Bottom edge shifted up
+    #  [  0  10 370  50]  # Wide box aligned to left edge
+    #  [ 10   0  30 280]] # Tall box aligned to top edge
+    ```
+    """
+    result = np.copy(xyxy)
+    width, height = resolution_wh
+
+    # X-axis (prioritize left edge)
+    left_overflow = result[:, 0] < 0
+    result[left_overflow, 0:3:2] -= result[left_overflow, 0:1]
+
+    right_overflow = (~left_overflow) & (result[:, 2] > width)
+    right_shift = width - result[right_overflow, 2]
+    result[right_overflow, 0:3:2] += right_shift[:, np.newaxis]
+
+    # Y-axis (prioritize top edge)
+    top_overflow = result[:, 1] < 0
+    result[top_overflow, 1:4:2] -= result[top_overflow, 1:2]
+
+    bottom_overflow = (~top_overflow) & (result[:, 3] > height)
+    bottom_shift = height - result[bottom_overflow, 3]
+    result[bottom_overflow, 1:4:2] += bottom_shift[:, np.newaxis]
+
+    return result
+
+
 class Trace:
     def __init__(
         self,
-        max_size: Optional[int] = None,
+        max_size: int | None = None,
         start_frame_id: int = 0,
         anchor: Position = Position.CENTER,
     ) -> None:
@@ -163,7 +334,10 @@ class Trace:
         frame_id = np.full(len(detections), self.current_frame_id, dtype=int)
         self.frame_id = np.concatenate([self.frame_id, frame_id])
         self.xy = np.concatenate(
-            [self.xy, detections.get_anchors_coordinates(self.anchor)]
+            [
+                self.xy,
+                detections.get_anchors_coordinates(self.anchor),
+            ]
         )
         self.tracker_id = np.concatenate([self.tracker_id, detections.tracker_id])
 

supervision/assets/downloader.py

@@ -1,8 +1,9 @@
+from __future__ import annotations
+
 import os
 from hashlib import new as hash_new
 from pathlib import Path
 from shutil import copyfileobj
-from typing import Union
 
 from requests import get
 from tqdm.auto import tqdm
@@ -32,7 +33,7 @@ def is_md5_hash_matching(filename: str, original_md5_hash: str) -> bool:
     return computed_md5_hash.hexdigest() == original_md5_hash
 
 
-def download_assets(asset_name: Union[VideoAssets, str]) -> str:
+def download_assets(asset_name: VideoAssets | str) -> str:
     """
     Download a specified asset if it doesn't already exist or is corrupted.
 

supervision/assets/list.py

@@ -1,5 +1,4 @@
 from enum import Enum
-from typing import Dict, Tuple
 
 BASE_VIDEO_URL = "https://media.roboflow.com/supervision/video-examples/"
 
@@ -39,7 +38,7 @@ class VideoAssets(Enum):
         return list(map(lambda c: c.value, cls))
 
 
-VIDEO_ASSETS: Dict[str, Tuple[str, str]] = {
+VIDEO_ASSETS: dict[str, tuple[str, str]] = {
     VideoAssets.VEHICLES.value: (
         f"{BASE_VIDEO_URL}{VideoAssets.VEHICLES.value}",
         "8155ff4e4de08cfa25f39de96483f918",

supervision/classification/core.py

@@ -1,7 +1,7 @@
 from __future__ import annotations
 
 from dataclasses import dataclass
-from typing import Any, Optional, Tuple
+from typing import Any
 
 import numpy as np
 
@@ -28,7 +28,7 @@ def _validate_confidence(confidence: Any, n: int) -> None:
 @dataclass
 class Classifications:
     class_id: np.ndarray
-    confidence: Optional[np.ndarray] = None
+    confidence: np.ndarray | None = None
 
     def __post_init__(self) -> None:
         """
@@ -154,7 +154,7 @@ class Classifications:
         class_id = np.arange(len(confidence))
         return cls(class_id=class_id, confidence=confidence)
 
-    def get_top_k(self, k: int) -> Tuple[np.ndarray, np.ndarray]:
+    def get_top_k(self, k: int) -> tuple[np.ndarray, np.ndarray]:
         """
         Retrieve the top k class IDs and confidences,
             ordered in descending order by confidence.

supervision/dataset/core.py

@@ -2,10 +2,10 @@ from __future__ import annotations
 
 import os
 from abc import ABC, abstractmethod
+from collections.abc import Iterator
 from dataclasses import dataclass
 from itertools import chain
 from pathlib import Path
-from typing import Dict, Iterator, List, Optional, Tuple, Union
 
 import cv2
 import numpy as np
@@ -32,7 +32,7 @@ from supervision.dataset.utils import (
     train_test_split,
 )
 from supervision.detection.core import Detections
-from supervision.utils.internal import deprecated, warn_deprecated
+from supervision.utils.internal import warn_deprecated
 from supervision.utils.iterables import find_duplicates
 
 
@@ -45,9 +45,9 @@ class BaseDataset(ABC):
     def split(
         self,
         split_ratio: float = 0.8,
-        random_state: Optional[int] = None,
+        random_state: int | None = None,
         shuffle: bool = True,
-    ) -> Tuple[BaseDataset, BaseDataset]:
+    ) -> tuple[BaseDataset, BaseDataset]:
         pass
 
 
@@ -71,9 +71,9 @@ class DetectionDataset(BaseDataset):
 
     def __init__(
         self,
-        classes: List[str],
-        images: Union[List[str], Dict[str, np.ndarray]],
-        annotations: Dict[str, Detections],
+        classes: list[str],
+        images: list[str] | dict[str, np.ndarray],
+        annotations: dict[str, Detections],
     ) -> None:
         self.classes = classes
 
@@ -86,40 +86,7 @@ class DetectionDataset(BaseDataset):
         # Eliminate duplicates while preserving order
         self.image_paths = list(dict.fromkeys(images))
 
-        self._images_in_memory: Dict[str, np.ndarray] = {}
-        if isinstance(images, dict):
-            self._images_in_memory = images
-            warn_deprecated(
-                "Passing a `Dict[str, np.ndarray]` into `DetectionDataset` is "
-                "deprecated and will be removed in `supervision-0.26.0`. Use "
-                "a list of paths `List[str]` instead."
-            )
-            # TODO: when supervision-0.26.0 is released, and Dict[str, np.ndarray]
-            #       for images is no longer supported, also simplify the rest of
-            #       the code. E.g. list(images) is no longer needed, and merge can
-            #       be simplified.
-
-    @property
-    @deprecated(
-        "`DetectionDataset.images` property is deprecated and will be removed in "
-        "`supervision-0.26.0`. Iterate with `for path, image, annotation in dataset:` "
-        "instead."
-    )
-    def images(self) -> Dict[str, np.ndarray]:
-        """
-        Load all images to memory and return them as a dictionary.
-
-        !!! warning
-
-            Only use this when you need all images at once.
-            It is much more memory-efficient to initialize dataset with
-            image paths and use `for path, image, annotation in dataset:`.
-        """
-        if self._images_in_memory:
-            return self._images_in_memory
-
-        images = {image_path: cv2.imread(image_path) for image_path in self.image_paths}
-        return images
+        self._images_in_memory: dict[str, np.ndarray] = {}
 
     def _get_image(self, image_path: str) -> np.ndarray:
         """Assumes that image is in dataset"""
@@ -130,7 +97,7 @@ class DetectionDataset(BaseDataset):
     def __len__(self) -> int:
         return len(self._images_in_memory) or len(self.image_paths)
 
-    def __getitem__(self, i: int) -> Tuple[str, np.ndarray, Detections]:
+    def __getitem__(self, i: int) -> tuple[str, np.ndarray, Detections]:
         """
         Returns:
             Tuple[str, np.ndarray, Detections]: The image path, image data,
@@ -141,7 +108,7 @@ class DetectionDataset(BaseDataset):
         annotation = self.annotations[image_path]
         return image_path, image, annotation
 
-    def __iter__(self) -> Iterator[Tuple[str, np.ndarray, Detections]]:
+    def __iter__(self) -> Iterator[tuple[str, np.ndarray, Detections]]:
         """
         Iterate over the images and annotations in the dataset.
 
@@ -179,9 +146,9 @@ class DetectionDataset(BaseDataset):
     def split(
         self,
         split_ratio: float = 0.8,
-        random_state: Optional[int] = None,
+        random_state: int | None = None,
         shuffle: bool = True,
-    ) -> Tuple[DetectionDataset, DetectionDataset]:
+    ) -> tuple[DetectionDataset, DetectionDataset]:
         """
         Splits the dataset into two parts (training and testing)
             using the provided split_ratio.
@@ -215,8 +182,8 @@ class DetectionDataset(BaseDataset):
             shuffle=shuffle,
         )
 
-        train_input: Union[List[str], Dict[str, np.ndarray]]
-        test_input: Union[List[str], Dict[str, np.ndarray]]
+        train_input: list[str] | dict[str, np.ndarray]
+        test_input: list[str] | dict[str, np.ndarray]
         if self._images_in_memory:
             train_input = {path: self._images_in_memory[path] for path in train_paths}
             test_input = {path: self._images_in_memory[path] for path in test_paths}
@@ -239,7 +206,7 @@ class DetectionDataset(BaseDataset):
         return train_dataset, test_dataset
 
     @classmethod
-    def merge(cls, dataset_list: List[DetectionDataset]) -> DetectionDataset:
+    def merge(cls, dataset_list: list[DetectionDataset]) -> DetectionDataset:
         """
         Merge a list of `DetectionDataset` objects into a single
             `DetectionDataset` object.
@@ -333,8 +300,8 @@ class DetectionDataset(BaseDataset):
 
     def as_pascal_voc(
         self,
-        images_directory_path: Optional[str] = None,
-        annotations_directory_path: Optional[str] = None,
+        images_directory_path: str | None = None,
+        annotations_directory_path: str | None = None,
         min_image_area_percentage: float = 0.0,
         max_image_area_percentage: float = 1.0,
         approximation_percentage: float = 0.0,
@@ -507,9 +474,9 @@ class DetectionDataset(BaseDataset):
 
     def as_yolo(
         self,
-        images_directory_path: Optional[str] = None,
-        annotations_directory_path: Optional[str] = None,
-        data_yaml_path: Optional[str] = None,
+        images_directory_path: str | None = None,
+        annotations_directory_path: str | None = None,
+        data_yaml_path: str | None = None,
         min_image_area_percentage: float = 0.0,
         max_image_area_percentage: float = 1.0,
         approximation_percentage: float = 0.0,
@@ -574,7 +541,6 @@ class DetectionDataset(BaseDataset):
             force_masks (bool): If True,
                 forces masks to be loaded for all annotations,
                 regardless of whether they are present.
-
         Returns:
             DetectionDataset: A DetectionDataset instance containing
                 the loaded images and annotations.
@@ -609,8 +575,8 @@ class DetectionDataset(BaseDataset):
 
     def as_coco(
         self,
-        images_directory_path: Optional[str] = None,
-        annotations_path: Optional[str] = None,
+        images_directory_path: str | None = None,
+        annotations_path: str | None = None,
         min_image_area_percentage: float = 0.0,
         max_image_area_percentage: float = 1.0,
         approximation_percentage: float = 0.0,
@@ -681,9 +647,9 @@ class ClassificationDataset(BaseDataset):
 
     def __init__(
         self,
-        classes: List[str],
-        images: Union[List[str], Dict[str, np.ndarray]],
-        annotations: Dict[str, Classifications],
+        classes: list[str],
+        images: list[str] | dict[str, np.ndarray],
+        annotations: dict[str, Classifications],
     ) -> None:
         self.classes = classes
 
@@ -696,7 +662,7 @@ class ClassificationDataset(BaseDataset):
         # Eliminate duplicates while preserving order
         self.image_paths = list(dict.fromkeys(images))
 
-        self._images_in_memory: Dict[str, np.ndarray] = {}
+        self._images_in_memory: dict[str, np.ndarray] = {}
         if isinstance(images, dict):
             self._images_in_memory = images
             warn_deprecated(
@@ -714,7 +680,7 @@ class ClassificationDataset(BaseDataset):
     def __len__(self) -> int:
         return len(self._images_in_memory) or len(self.image_paths)
 
-    def __getitem__(self, i: int) -> Tuple[str, np.ndarray, Classifications]:
+    def __getitem__(self, i: int) -> tuple[str, np.ndarray, Classifications]:
         """
         Returns:
             Tuple[str, np.ndarray, Classifications]: The image path, image data,
@@ -725,7 +691,7 @@ class ClassificationDataset(BaseDataset):
         annotation = self.annotations[image_path]
         return image_path, image, annotation
 
-    def __iter__(self) -> Iterator[Tuple[str, np.ndarray, Classifications]]:
+    def __iter__(self) -> Iterator[tuple[str, np.ndarray, Classifications]]:
         """
         Iterate over the images and annotations in the dataset.
 
@@ -763,9 +729,9 @@ class ClassificationDataset(BaseDataset):
     def split(
         self,
         split_ratio: float = 0.8,
-        random_state: Optional[int] = None,
+        random_state: int | None = None,
         shuffle: bool = True,
-    ) -> Tuple[ClassificationDataset, ClassificationDataset]:
+    ) -> tuple[ClassificationDataset, ClassificationDataset]:
         """
         Splits the dataset into two parts (training and testing)
             using the provided split_ratio.
@@ -798,8 +764,8 @@ class ClassificationDataset(BaseDataset):
             shuffle=shuffle,
         )
 
-        train_input: Union[List[str], Dict[str, np.ndarray]]
-        test_input: Union[List[str], Dict[str, np.ndarray]]
+        train_input: list[str] | dict[str, np.ndarray]
+        test_input: list[str] | dict[str, np.ndarray]
         if self._images_in_memory:
             train_input = {path: self._images_in_memory[path] for path in train_paths}
             test_input = {path: self._images_in_memory[path] for path in test_paths}

supervision/dataset/formats/coco.py

@@ -1,7 +1,7 @@
 import os
 from datetime import datetime
 from pathlib import Path
-from typing import TYPE_CHECKING, Dict, List, Tuple
+from typing import TYPE_CHECKING
 
 import numpy as np
 import numpy.typing as npt
@@ -13,18 +13,15 @@ from supervision.dataset.utils import (
     rle_to_mask,
 )
 from supervision.detection.core import Detections
-from supervision.detection.utils import (
-    contains_holes,
-    contains_multiple_segments,
-    polygon_to_mask,
-)
+from supervision.detection.utils.converters import polygon_to_mask
+from supervision.detection.utils.masks import contains_holes, contains_multiple_segments
 from supervision.utils.file import read_json_file, save_json_file
 
 if TYPE_CHECKING:
     from supervision.dataset.core import DetectionDataset
 
 
-def coco_categories_to_classes(coco_categories: List[dict]) -> List[str]:
+def coco_categories_to_classes(coco_categories: list[dict]) -> list[str]:
     return [
         category["name"]
         for category in sorted(coco_categories, key=lambda category: category["id"])
@@ -32,8 +29,8 @@ def coco_categories_to_classes(coco_categories: List[dict]) -> List[str]:
 
 
 def build_coco_class_index_mapping(
-    coco_categories: List[dict], target_classes: List[str]
-) -> Dict[int, int]:
+    coco_categories: list[dict], target_classes: list[str]
+) -> dict[int, int]:
     source_class_to_index = {
         category["name"]: category["id"] for category in coco_categories
     }
@@ -43,7 +40,7 @@ def build_coco_class_index_mapping(
     }
 
 
-def classes_to_coco_categories(classes: List[str]) -> List[dict]:
+def classes_to_coco_categories(classes: list[str]) -> list[dict]:
     return [
         {
             "id": class_id,
@@ -55,8 +52,8 @@ def classes_to_coco_categories(classes: List[str]) -> List[dict]:
 
 
 def group_coco_annotations_by_image_id(
-    coco_annotations: List[dict],
-) -> Dict[int, List[dict]]:
+    coco_annotations: list[dict],
+) -> dict[int, list[dict]]:
     annotations = {}
     for annotation in coco_annotations:
         image_id = annotation["image_id"]
@@ -67,7 +64,7 @@ def group_coco_annotations_by_image_id(
 
 
 def coco_annotations_to_masks(
-    image_annotations: List[dict], resolution_wh: Tuple[int, int]
+    image_annotations: list[dict], resolution_wh: tuple[int, int]
 ) -> npt.NDArray[np.bool_]:
     return np.array(
         [
@@ -90,7 +87,10 @@ def coco_annotations_to_masks(
 
 
 def coco_annotations_to_detections(
-    image_annotations: List[dict], resolution_wh: Tuple[int, int], with_masks: bool
+    image_annotations: list[dict],
+    resolution_wh: tuple[int, int],
+    with_masks: bool,
+    use_iscrowd: bool = True,
 ) -> Detections:
     if not image_annotations:
         return Detections.empty()
@@ -102,15 +102,26 @@ def coco_annotations_to_detections(
     xyxy = np.asarray(xyxy)
     xyxy[:, 2:4] += xyxy[:, 0:2]
 
+    data = dict()
+    if use_iscrowd:
+        iscrowd = [
+            image_annotation["iscrowd"] for image_annotation in image_annotations
+        ]
+        area = [image_annotation["area"] for image_annotation in image_annotations]
+        data = dict(
+            iscrowd=np.asarray(iscrowd, dtype=int), area=np.asarray(area, dtype=float)
+        )
+
     if with_masks:
         mask = coco_annotations_to_masks(
             image_annotations=image_annotations, resolution_wh=resolution_wh
         )
-        return Detections(
-            class_id=np.asarray(class_ids, dtype=int), xyxy=xyxy, mask=mask
-        )
+    else:
+        mask = None
 
-    return Detections(xyxy=xyxy, class_id=np.asarray(class_ids, dtype=int))
+    return Detections(
+        class_id=np.asarray(class_ids, dtype=int), xyxy=xyxy, mask=mask, data=data
+    )
 
 
 def detections_to_coco_annotations(
@@ -120,7 +131,7 @@ def detections_to_coco_annotations(
     min_image_area_percentage: float = 0.0,
     max_image_area_percentage: float = 1.0,
     approximation_percentage: float = 0.75,
-) -> Tuple[List[Dict], int]:
+) -> tuple[list[dict], int]:
     coco_annotations = []
     for xyxy, mask, _, class_id, _, _ in detections:
         box_width, box_height = xyxy[2] - xyxy[0], xyxy[3] - xyxy[1]
@@ -159,16 +170,58 @@ def detections_to_coco_annotations(
     return coco_annotations, annotation_id
 
 
+def get_coco_class_index_mapping(annotations_path: str) -> dict[int, int]:
+    """
+    Generates a mapping from sequential class indices to original COCO class ids.
+
+    This function is essential when working with models that expect class ids to be
+    zero-indexed and sequential (0 to 79), as opposed to the original COCO
+    dataset where category ids are non-contiguous ranging from 1 to 90 but skipping some
+    ids.
+
+    Use Cases:
+        - Evaluating models trained with COCO-style annotations where class ids
+          are sequential ranging from 0 to 79.
+        - Ensuring consistent class indexing across training, inference and evaluation,
+          when using different tools or datasets with COCO format.
+        - Reproducing results from models that assume sequential class ids (0 to 79).
+
+    How it Works:
+        - Reads the COCO annotation file in its original format (`annotations_path`).
+        - Extracts and sorts all class names by their original COCO id (1 to 90).
+        - Builds a mapping from COCO class ids (not sequential with skipped ids) to
+          new class ids (sequential ranging from 0 to 79).
+        - Returns a dictionary mapping: `{new_class_id: original_COCO_class_id}`.
+
+    Args:
+        annotations_path (str): Path to COCO JSON annotations file
+        (e.g., `instances_val2017.json`).
+
+    Returns:
+        Dict[int, int]: A mapping from new class id (sequential ranging from 0 to 79)
+        to original COCO class id (1 to 90 with skipped ids).
+    """
+    coco_data = read_json_file(annotations_path)
+    classes = coco_categories_to_classes(coco_categories=coco_data["categories"])
+    class_mapping = build_coco_class_index_mapping(
+        coco_categories=coco_data["categories"], target_classes=classes
+    )
+    return {v: k for k, v in class_mapping.items()}
+
+
 def load_coco_annotations(
     images_directory_path: str,
     annotations_path: str,
     force_masks: bool = False,
-) -> Tuple[List[str], List[str], Dict[str, Detections]]:
+    use_iscrowd: bool = True,
+) -> tuple[list[str], list[str], dict[str, Detections]]:
     coco_data = read_json_file(file_path=annotations_path)
     classes = coco_categories_to_classes(coco_categories=coco_data["categories"])
+
     class_index_mapping = build_coco_class_index_mapping(
         coco_categories=coco_data["categories"], target_classes=classes
     )
+
     coco_images = coco_data["images"]
     coco_annotations_groups = group_coco_annotations_by_image_id(
         coco_annotations=coco_data["annotations"]
@@ -190,7 +243,9 @@ def load_coco_annotations(
             image_annotations=image_annotations,
             resolution_wh=(image_width, image_height),
             with_masks=force_masks,
+            use_iscrowd=use_iscrowd,
         )
+
         annotation = map_detections_class_id(
             source_to_target_mapping=class_index_mapping,
             detections=annotation,

supervision/dataset/formats/pascal_voc.py

@@ -1,6 +1,7 @@
+from __future__ import annotations
+
 import os
 from pathlib import Path
-from typing import Dict, List, Optional, Tuple
 from xml.etree.ElementTree import Element, SubElement
 
 import cv2
@@ -10,12 +11,12 @@ from defusedxml.minidom import parseString
 
 from supervision.dataset.utils import approximate_mask_with_polygons
 from supervision.detection.core import Detections
-from supervision.detection.utils import polygon_to_mask, polygon_to_xyxy
+from supervision.detection.utils.converters import polygon_to_mask, polygon_to_xyxy
 from supervision.utils.file import list_files_with_extensions
 
 
 def object_to_pascal_voc(
-    xyxy: np.ndarray, name: str, polygon: Optional[np.ndarray] = None
+    xyxy: np.ndarray, name: str, polygon: np.ndarray | None = None
 ) -> Element:
     root = Element("object")
 
@@ -51,9 +52,9 @@ def object_to_pascal_voc(
 
 def detections_to_pascal_voc(
     detections: Detections,
-    classes: List[str],
+    classes: list[str],
     filename: str,
-    image_shape: Tuple[int, int, int],
+    image_shape: tuple[int, int, int],
     min_image_area_percentage: float = 0.0,
     max_image_area_percentage: float = 1.0,
     approximation_percentage: float = 0.75,
@@ -138,7 +139,7 @@ def load_pascal_voc_annotations(
     images_directory_path: str,
     annotations_directory_path: str,
     force_masks: bool = False,
-) -> Tuple[List[str], List[str], Dict[str, Detections]]:
+) -> tuple[list[str], list[str], dict[str, Detections]]:
     """
     Loads PASCAL VOC XML annotations and returns the image name,
         a Detections instance, and a list of class names.
@@ -163,7 +164,7 @@ def load_pascal_voc_annotations(
         )
     ]
 
-    classes: List[str] = []
+    classes: list[str] = []
     annotations = {}
 
     for image_path in image_paths:
@@ -187,8 +188,8 @@ def load_pascal_voc_annotations(
 
 
 def detections_from_xml_obj(
-    root: Element, classes: List[str], resolution_wh, force_masks: bool = False
-) -> Tuple[Detections, List[str]]:
+    root: Element, classes: list[str], resolution_wh, force_masks: bool = False
+) -> tuple[Detections, list[str]]:
     """
     Converts an XML object in Pascal VOC format to a Detections object.
     Expected XML format:

supervision/dataset/formats/yolo.py

@@ -1,6 +1,8 @@
+from __future__ import annotations
+
 import os
 from pathlib import Path
-from typing import TYPE_CHECKING, Dict, List, Optional, Tuple
+from typing import TYPE_CHECKING
 
 import numpy as np
 from PIL import Image
@@ -8,7 +10,7 @@ from PIL import Image
 from supervision.config import ORIENTED_BOX_COORDINATES
 from supervision.dataset.utils import approximate_mask_with_polygons
 from supervision.detection.core import Detections
-from supervision.detection.utils import polygon_to_mask, polygon_to_xyxy
+from supervision.detection.utils.converters import polygon_to_mask, polygon_to_xyxy
 from supervision.utils.file import (
     list_files_with_extensions,
     read_txt_file,
@@ -21,7 +23,7 @@ if TYPE_CHECKING:
     from supervision.dataset.core import DetectionDataset
 
 
-def _parse_box(values: List[str]) -> np.ndarray:
+def _parse_box(values: list[str]) -> np.ndarray:
     x_center, y_center, width, height = values
     return np.array(
         [
@@ -40,12 +42,12 @@ def _box_to_polygon(box: np.ndarray) -> np.ndarray:
     )
 
 
-def _parse_polygon(values: List[str]) -> np.ndarray:
+def _parse_polygon(values: list[str]) -> np.ndarray:
     return np.array(values, dtype=np.float32).reshape(-1, 2)
 
 
 def _polygons_to_masks(
-    polygons: List[np.ndarray], resolution_wh: Tuple[int, int]
+    polygons: list[np.ndarray], resolution_wh: tuple[int, int]
 ) -> np.ndarray:
     return np.array(
         [
@@ -56,11 +58,11 @@ def _polygons_to_masks(
     )
 
 
-def _with_mask(lines: List[str]) -> bool:
+def _with_mask(lines: list[str]) -> bool:
     return any([len(line.split()) > 5 for line in lines])
 
 
-def _extract_class_names(file_path: str) -> List[str]:
+def _extract_class_names(file_path: str) -> list[str]:
     data = read_yaml_file(file_path=file_path)
     names = data["names"]
     if isinstance(names, dict):
@@ -74,8 +76,8 @@ def _image_name_to_annotation_name(image_name: str) -> str:
 
 
 def yolo_annotations_to_detections(
-    lines: List[str],
-    resolution_wh: Tuple[int, int],
+    lines: list[str],
+    resolution_wh: tuple[int, int],
     with_masks: bool,
     is_obb: bool = False,
 ) -> Detections:
@@ -127,7 +129,7 @@ def load_yolo_annotations(
     data_yaml_path: str,
     force_masks: bool = False,
     is_obb: bool = False,
-) -> Tuple[List[str], List[str], Dict[str, Detections]]:
+) -> tuple[list[str], list[str], dict[str, Detections]]:
     """
     Loads YOLO annotations and returns class names, images,
         and their corresponding detections.
@@ -204,8 +206,8 @@ def load_yolo_annotations(
 def object_to_yolo(
     xyxy: np.ndarray,
     class_id: int,
-    image_shape: Tuple[int, int, int],
-    polygon: Optional[np.ndarray] = None,
+    image_shape: tuple[int, int, int],
+    polygon: np.ndarray | None = None,
 ) -> str:
     h, w, _ = image_shape
     if polygon is None:
@@ -225,11 +227,11 @@ def object_to_yolo(
 
 def detections_to_yolo_annotations(
     detections: Detections,
-    image_shape: Tuple[int, int, int],
+    image_shape: tuple[int, int, int],
     min_image_area_percentage: float = 0.0,
     max_image_area_percentage: float = 1.0,
     approximation_percentage: float = 0.75,
-) -> List[str]:
+) -> list[str]:
     annotation = []
     for xyxy, mask, _, class_id, _, _ in detections:
         if class_id is None:
@@ -260,7 +262,7 @@ def detections_to_yolo_annotations(
 
 
 def save_yolo_annotations(
-    dataset: "DetectionDataset",
+    dataset: DetectionDataset,
     annotations_directory_path: str,
     min_image_area_percentage: float = 0.0,
     max_image_area_percentage: float = 1.0,
@@ -283,7 +285,7 @@ def save_yolo_annotations(
         save_text_file(lines=lines, file_path=yolo_annotations_path)
 
 
-def save_data_yaml(data_yaml_path: str, classes: List[str]) -> None:
+def save_data_yaml(data_yaml_path: str, classes: list[str]) -> None:
     data = {"nc": len(classes), "names": classes}
     Path(data_yaml_path).parent.mkdir(parents=True, exist_ok=True)
     save_yaml_file(data=data, file_path=data_yaml_path)

supervision/dataset/utils.py

@@ -1,19 +1,21 @@
+from __future__ import annotations
+
 import copy
 import os
 import random
 import shutil
 from pathlib import Path
-from typing import TYPE_CHECKING, Dict, List, Optional, Tuple, TypeVar, Union
+from typing import TYPE_CHECKING, TypeVar
 
 import cv2
 import numpy as np
 import numpy.typing as npt
 
 from supervision.detection.core import Detections
-from supervision.detection.utils import (
+from supervision.detection.utils.converters import mask_to_polygons
+from supervision.detection.utils.polygons import (
     approximate_polygon,
     filter_polygons_by_area,
-    mask_to_polygons,
 )
 
 if TYPE_CHECKING:
@@ -27,7 +29,7 @@ def approximate_mask_with_polygons(
     min_image_area_percentage: float = 0.0,
     max_image_area_percentage: float = 1.0,
     approximation_percentage: float = 0.75,
-) -> List[np.ndarray]:
+) -> list[np.ndarray]:
     height, width = mask.shape
     image_area = height * width
     minimum_detection_area = min_image_area_percentage * image_area
@@ -50,7 +52,7 @@ def approximate_mask_with_polygons(
     ]
 
 
-def merge_class_lists(class_lists: List[List[str]]) -> List[str]:
+def merge_class_lists(class_lists: list[list[str]]) -> list[str]:
     unique_classes = set()
 
     for class_list in class_lists:
@@ -61,8 +63,8 @@ def merge_class_lists(class_lists: List[List[str]]) -> List[str]:
 
 
 def build_class_index_mapping(
-    source_classes: List[str], target_classes: List[str]
-) -> Dict[int, int]:
+    source_classes: list[str], target_classes: list[str]
+) -> dict[int, int]:
     """Returns the index map of source classes -> target classes."""
     index_mapping = {}
 
@@ -79,7 +81,7 @@ def build_class_index_mapping(
 
 
 def map_detections_class_id(
-    source_to_target_mapping: Dict[int, int], detections: Detections
+    source_to_target_mapping: dict[int, int], detections: Detections
 ) -> Detections:
     if detections.class_id is None:
         raise ValueError("Detections must have class_id attribute.")
@@ -98,9 +100,7 @@ def map_detections_class_id(
     return detections_copy
 
 
-def save_dataset_images(
-    dataset: "DetectionDataset", images_directory_path: str
-) -> None:
+def save_dataset_images(dataset: DetectionDataset, images_directory_path: str) -> None:
     Path(images_directory_path).mkdir(parents=True, exist_ok=True)
     for image_path in dataset.image_paths:
         final_path = os.path.join(images_directory_path, Path(image_path).name)
@@ -112,11 +112,11 @@ def save_dataset_images(
 
 
 def train_test_split(
-    data: List[T],
+    data: list[T],
     train_ratio: float = 0.8,
-    random_state: Optional[int] = None,
+    random_state: int | None = None,
     shuffle: bool = True,
-) -> Tuple[List[T], List[T]]:
+) -> tuple[list[T], list[T]]:
     """
     Splits the data into two parts using the provided train_ratio.
 
@@ -140,7 +140,7 @@ def train_test_split(
 
 
 def rle_to_mask(
-    rle: Union[npt.NDArray[np.int_], List[int]], resolution_wh: Tuple[int, int]
+    rle: npt.NDArray[np.int_] | list[int], resolution_wh: tuple[int, int]
 ) -> npt.NDArray[np.bool_]:
     """
     Converts run-length encoding (RLE) to a binary mask.
@@ -195,7 +195,7 @@ def rle_to_mask(
     return decoded_rle.reshape((height, width), order="F")
 
 
-def mask_to_rle(mask: npt.NDArray[np.bool_]) -> List[int]:
+def mask_to_rle(mask: npt.NDArray[np.bool_]) -> list[int]:
     """
     Converts a binary mask into a run-length encoding (RLE).
 

supervision/detection/line_zone.py

@@ -1,8 +1,11 @@
+from __future__ import annotations
+
 import math
 import warnings
 from collections import Counter, defaultdict, deque
+from collections.abc import Iterable
 from functools import lru_cache
-from typing import Any, Deque, Dict, Iterable, List, Literal, Optional, Tuple
+from typing import Any, Literal
 
 import cv2
 import numpy as np
@@ -10,7 +13,7 @@ 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.detection.utils.internal import cross_product
 from supervision.draw.color import Color
 from supervision.draw.utils import draw_rectangle, draw_text
 from supervision.geometry.core import Point, Position, Rect, Vector
@@ -99,7 +102,7 @@ class LineZone:
         self.vector = Vector(start=start, end=end)
         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(
+        self.crossing_state_history: dict[int, deque[bool]] = defaultdict(
             lambda: deque(maxlen=self.crossing_history_length)
         )
         self._in_count_per_class: Counter = Counter()
@@ -107,7 +110,7 @@ class LineZone:
         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] = {}
+        self.class_id_to_name: dict[int, str] = {}
 
     @property
     def in_count(self) -> int:
@@ -118,14 +121,14 @@ class LineZone:
         return sum(self._out_count_per_class.values())
 
     @property
-    def in_count_per_class(self) -> Dict[int, int]:
+    def in_count_per_class(self) -> dict[int, int]:
         return dict(self._in_count_per_class)
 
     @property
-    def out_count_per_class(self) -> Dict[int, int]:
+    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]:
+    def trigger(self, detections: Detections) -> tuple[np.ndarray, np.ndarray]:
         """
         Update the `in_count` and `out_count` based on the objects that cross the line.
 
@@ -160,7 +163,7 @@ class LineZone:
             self._compute_anchor_sides(detections)
         )
 
-        class_ids: List[Optional[int]] = (
+        class_ids: list[int | None] = (
             list(detections.class_id)
             if detections.class_id is not None
             else [None] * len(detections)
@@ -200,7 +203,7 @@ class LineZone:
         return crossed_in, crossed_out
 
     @staticmethod
-    def _calculate_region_of_interest_limits(vector: Vector) -> Tuple[Vector, Vector]:
+    def _calculate_region_of_interest_limits(vector: Vector) -> tuple[Vector, Vector]:
         magnitude = vector.magnitude
 
         if magnitude == 0:
@@ -233,7 +236,7 @@ class LineZone:
 
     def _compute_anchor_sides(
         self, detections: Detections
-    ) -> Tuple[npt.NDArray[np.bool_], npt.NDArray[np.bool_], npt.NDArray[np.bool_]]:
+    ) -> 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.
@@ -324,8 +327,8 @@ class LineZoneAnnotator:
         text_scale: float = 0.5,
         text_offset: float = 1.5,
         text_padding: int = 10,
-        custom_in_text: Optional[str] = None,
-        custom_out_text: Optional[str] = None,
+        custom_in_text: str | None = None,
+        custom_out_text: str | None = None,
         display_in_count: bool = True,
         display_out_count: bool = True,
         display_text_box: bool = True,
@@ -471,7 +474,7 @@ class LineZoneAnnotator:
         text_height: int,
         is_in_count: bool,
         label_dimension: int,
-    ) -> Tuple[int, int]:
+    ) -> tuple[int, int]:
         """
         Calculate insertion anchor in frame to position the center of the count image.
 
@@ -663,7 +666,7 @@ class LineZoneAnnotator:
         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_args: dict[str, Any] = dict(
             text=text,
             text_anchor=annotation_center,
             text_scale=text_scale,
@@ -756,8 +759,8 @@ class LineZoneAnnotatorMulticlass:
     def annotate(
         self,
         frame: np.ndarray,
-        line_zones: List[LineZone],
-        line_zone_labels: Optional[List[str]] = None,
+        line_zones: list[LineZone],
+        line_zone_labels: list[str] | None = None,
     ) -> np.ndarray:
         """
         Draws a table with the number of objects of each class that crossed each line.

supervision/detection/overlap_filter.py

@@ -1,269 +0,0 @@
-from __future__ import annotations
-
-from enum import Enum
-from typing import List, Union
-
-import numpy as np
-import numpy.typing as npt
-
-from supervision.detection.utils import box_iou_batch, mask_iou_batch
-
-
-def resize_masks(masks: np.ndarray, max_dimension: int = 640) -> np.ndarray:
-    """
-    Resize all masks in the array to have a maximum dimension of max_dimension,
-    maintaining aspect ratio.
-
-    Args:
-        masks (np.ndarray): 3D array of binary masks with shape (N, H, W).
-        max_dimension (int): The maximum dimension for the resized masks.
-
-    Returns:
-        np.ndarray: Array of resized masks.
-    """
-    max_height = np.max(masks.shape[1])
-    max_width = np.max(masks.shape[2])
-    scale = min(max_dimension / max_height, max_dimension / max_width)
-
-    new_height = int(scale * max_height)
-    new_width = int(scale * max_width)
-
-    x = np.linspace(0, max_width - 1, new_width).astype(int)
-    y = np.linspace(0, max_height - 1, new_height).astype(int)
-    xv, yv = np.meshgrid(x, y)
-
-    resized_masks = masks[:, yv, xv]
-
-    resized_masks = resized_masks.reshape(masks.shape[0], new_height, new_width)
-    return resized_masks
-
-
-def mask_non_max_suppression(
-    predictions: np.ndarray,
-    masks: np.ndarray,
-    iou_threshold: float = 0.5,
-    mask_dimension: int = 640,
-) -> np.ndarray:
-    """
-    Perform Non-Maximum Suppression (NMS) on segmentation predictions.
-
-    Args:
-        predictions (np.ndarray): A 2D array of object detection predictions in
-            the format of `(x_min, y_min, x_max, y_max, score)`
-            or `(x_min, y_min, x_max, y_max, score, class)`. Shape: `(N, 5)` or
-            `(N, 6)`, where N is the number of predictions.
-        masks (np.ndarray): A 3D array of binary masks corresponding to the predictions.
-            Shape: `(N, H, W)`, where N is the number of predictions, and H, W are the
-            dimensions of each mask.
-        iou_threshold (float): The intersection-over-union threshold
-            to use for non-maximum suppression.
-        mask_dimension (int): The dimension to which the masks should be
-            resized before computing IOU values. Defaults to 640.
-
-    Returns:
-        np.ndarray: A boolean array indicating which predictions to keep after
-            non-maximum suppression.
-
-    Raises:
-        AssertionError: If `iou_threshold` is not within the closed
-            range from `0` to `1`.
-    """
-    assert 0 <= iou_threshold <= 1, (
-        "Value of `iou_threshold` must be in the closed range from 0 to 1, "
-        f"{iou_threshold} given."
-    )
-    rows, columns = predictions.shape
-
-    if columns == 5:
-        predictions = np.c_[predictions, np.zeros(rows)]
-
-    sort_index = predictions[:, 4].argsort()[::-1]
-    predictions = predictions[sort_index]
-    masks = masks[sort_index]
-    masks_resized = resize_masks(masks, mask_dimension)
-    ious = mask_iou_batch(masks_resized, masks_resized)
-    categories = predictions[:, 5]
-
-    keep = np.ones(rows, dtype=bool)
-    for i in range(rows):
-        if keep[i]:
-            condition = (ious[i] > iou_threshold) & (categories[i] == categories)
-            keep[i + 1 :] = np.where(condition[i + 1 :], False, keep[i + 1 :])
-
-    return keep[sort_index.argsort()]
-
-
-def box_non_max_suppression(
-    predictions: np.ndarray, iou_threshold: float = 0.5
-) -> np.ndarray:
-    """
-    Perform Non-Maximum Suppression (NMS) on object detection predictions.
-
-    Args:
-        predictions (np.ndarray): An array of object detection predictions in
-            the format of `(x_min, y_min, x_max, y_max, score)`
-            or `(x_min, y_min, x_max, y_max, score, class)`.
-        iou_threshold (float): The intersection-over-union threshold
-            to use for non-maximum suppression.
-
-    Returns:
-        np.ndarray: A boolean array indicating which predictions to keep after n
-            on-maximum suppression.
-
-    Raises:
-        AssertionError: If `iou_threshold` is not within the
-            closed range from `0` to `1`.
-    """
-    assert 0 <= iou_threshold <= 1, (
-        "Value of `iou_threshold` must be in the closed range from 0 to 1, "
-        f"{iou_threshold} given."
-    )
-    rows, columns = predictions.shape
-
-    # add column #5 - category filled with zeros for agnostic nms
-    if columns == 5:
-        predictions = np.c_[predictions, np.zeros(rows)]
-
-    # sort predictions column #4 - score
-    sort_index = np.flip(predictions[:, 4].argsort())
-    predictions = predictions[sort_index]
-
-    boxes = predictions[:, :4]
-    categories = predictions[:, 5]
-    ious = box_iou_batch(boxes, boxes)
-    ious = ious - np.eye(rows)
-
-    keep = np.ones(rows, dtype=bool)
-
-    for index, (iou, category) in enumerate(zip(ious, categories)):
-        if not keep[index]:
-            continue
-
-        # drop detections with iou > iou_threshold and
-        # same category as current detections
-        condition = (iou > iou_threshold) & (categories == category)
-        keep = keep & ~condition
-
-    return keep[sort_index.argsort()]
-
-
-def group_overlapping_boxes(
-    predictions: npt.NDArray[np.float64], iou_threshold: float = 0.5
-) -> List[List[int]]:
-    """
-    Apply greedy version of non-maximum merging to avoid detecting too many
-    overlapping bounding boxes for a given object.
-
-    Args:
-        predictions (npt.NDArray[np.float64]): An array of shape `(n, 5)` containing
-            the bounding boxes coordinates in format `[x1, y1, x2, y2]`
-            and the confidence scores.
-        iou_threshold (float): The intersection-over-union threshold
-            to use for non-maximum suppression. Defaults to 0.5.
-
-    Returns:
-        List[List[int]]: Groups of prediction indices be merged.
-            Each group may have 1 or more elements.
-    """
-    merge_groups: List[List[int]] = []
-
-    scores = predictions[:, 4]
-    order = scores.argsort()
-
-    while len(order) > 0:
-        idx = int(order[-1])
-
-        order = order[:-1]
-        if len(order) == 0:
-            merge_groups.append([idx])
-            break
-
-        merge_candidate = np.expand_dims(predictions[idx], axis=0)
-        ious = box_iou_batch(predictions[order][:, :4], merge_candidate[:, :4])
-        ious = ious.flatten()
-
-        above_threshold = ious >= iou_threshold
-        merge_group = [idx, *np.flip(order[above_threshold]).tolist()]
-        merge_groups.append(merge_group)
-        order = order[~above_threshold]
-    return merge_groups
-
-
-def box_non_max_merge(
-    predictions: npt.NDArray[np.float64],
-    iou_threshold: float = 0.5,
-) -> List[List[int]]:
-    """
-    Apply greedy version of non-maximum merging per category to avoid detecting
-    too many overlapping bounding boxes for a given object.
-
-    Args:
-        predictions (npt.NDArray[np.float64]): An array of shape `(n, 5)` or `(n, 6)`
-            containing the bounding boxes coordinates in format `[x1, y1, x2, y2]`,
-            the confidence scores and class_ids. Omit class_id column to allow
-            detections of different classes to be merged.
-        iou_threshold (float): The intersection-over-union threshold
-            to use for non-maximum suppression. Defaults to 0.5.
-
-    Returns:
-        List[List[int]]: Groups of prediction indices be merged.
-            Each group may have 1 or more elements.
-    """
-    if predictions.shape[1] == 5:
-        return group_overlapping_boxes(predictions, iou_threshold)
-
-    category_ids = predictions[:, 5]
-    merge_groups = []
-    for category_id in np.unique(category_ids):
-        curr_indices = np.where(category_ids == category_id)[0]
-        merge_class_groups = group_overlapping_boxes(
-            predictions[curr_indices], iou_threshold
-        )
-
-        for merge_class_group in merge_class_groups:
-            merge_groups.append(curr_indices[merge_class_group].tolist())
-
-    for merge_group in merge_groups:
-        if len(merge_group) == 0:
-            raise ValueError(
-                f"Empty group detected when non-max-merging detections: {merge_groups}"
-            )
-    return merge_groups
-
-
-class OverlapFilter(Enum):
-    """
-    Enum specifying the strategy for filtering overlapping detections.
-
-    Attributes:
-        NONE: Do not filter detections based on overlap.
-        NON_MAX_SUPPRESSION: Filter detections using non-max suppression. This means,
-            detections that overlap by more than a set threshold will be discarded,
-            except for the one with the highest confidence.
-        NON_MAX_MERGE: Merge detections with non-max merging. This means,
-            detections that overlap by more than a set threshold will be merged
-            into a single detection.
-    """
-
-    NONE = "none"
-    NON_MAX_SUPPRESSION = "non_max_suppression"
-    NON_MAX_MERGE = "non_max_merge"
-
-    @classmethod
-    def list(cls):
-        return list(map(lambda c: c.value, cls))
-
-    @classmethod
-    def from_value(cls, value: Union[OverlapFilter, str]) -> OverlapFilter:
-        if isinstance(value, cls):
-            return value
-        if isinstance(value, str):
-            value = value.lower()
-            try:
-                return cls(value)
-            except ValueError:
-                raise ValueError(f"Invalid value: {value}. Must be one of {cls.list()}")
-        raise ValueError(
-            f"Invalid value type: {type(value)}. Must be an instance of "
-            f"{cls.__name__} or str."
-        )

supervision/detection/tools/csv_sink.py

@@ -2,7 +2,7 @@ from __future__ import annotations
 
 import csv
 import os
-from typing import Any, Dict, List, Optional
+from typing import Any
 
 from supervision.detection.core import Detections
 
@@ -61,8 +61,8 @@ class CSVSink:
             None
         """
         self.file_name = file_name
-        self.file: Optional[open] = None
-        self.writer: Optional[csv.writer] = None
+        self.file: open | None = None
+        self.writer: csv.writer | None = None
         self.header_written = False
         self.field_names = []
 
@@ -72,9 +72,9 @@ class CSVSink:
 
     def __exit__(
         self,
-        exc_type: Optional[type],
-        exc_val: Optional[Exception],
-        exc_tb: Optional[Any],
+        exc_type: type | None,
+        exc_val: Exception | None,
+        exc_tb: Any | None,
     ) -> None:
         self.close()
 
@@ -104,8 +104,8 @@ class CSVSink:
 
     @staticmethod
     def parse_detection_data(
-        detections: Detections, custom_data: Optional[Dict[str, Any]] = None
-    ) -> List[Dict[str, Any]]:
+        detections: Detections, custom_data: dict[str, Any] | None = None
+    ) -> list[dict[str, Any]]:
         parsed_rows = []
         for i in range(len(detections.xyxy)):
             row = {
@@ -137,7 +137,7 @@ class CSVSink:
         return parsed_rows
 
     def append(
-        self, detections: Detections, custom_data: Optional[Dict[str, Any]] = None
+        self, detections: Detections, custom_data: dict[str, Any] | None = None
     ) -> None:
         """
         Append detection data to the CSV file.
@@ -173,8 +173,8 @@ class CSVSink:
 
     @staticmethod
     def parse_field_names(
-        detections: Detections, custom_data: Dict[str, Any]
-    ) -> List[str]:
+        detections: Detections, custom_data: dict[str, Any]
+    ) -> list[str]:
         dynamic_header = sorted(
             set(custom_data.keys()) | set(getattr(detections, "data", {}).keys())
         )

supervision/detection/tools/inference_slicer.py

@@ -1,24 +1,25 @@
+from __future__ import annotations
+
 import warnings
+from collections.abc import Callable
 from concurrent.futures import ThreadPoolExecutor, as_completed
-from typing import Callable, Optional, Tuple, Union
 
 import numpy as np
 
 from supervision.config import ORIENTED_BOX_COORDINATES
 from supervision.detection.core import Detections
-from supervision.detection.overlap_filter import OverlapFilter
-from supervision.detection.utils import move_boxes, move_masks, move_oriented_boxes
-from supervision.utils.image import crop_image
-from supervision.utils.internal import (
-    SupervisionWarnings,
-    warn_deprecated,
-)
+from supervision.detection.utils.boxes import move_boxes, move_oriented_boxes
+from supervision.detection.utils.iou_and_nms import OverlapFilter, OverlapMetric
+from supervision.detection.utils.masks import move_masks
+from supervision.draw.base import ImageType
+from supervision.utils.image import crop_image, get_image_resolution_wh
+from supervision.utils.internal import SupervisionWarnings
 
 
 def move_detections(
     detections: Detections,
     offset: np.ndarray,
-    resolution_wh: Optional[Tuple[int, int]] = None,
+    resolution_wh: tuple[int, int] | None = None,
 ) -> Detections:
     """
     Args:
@@ -50,107 +51,106 @@ def move_detections(
 
 class InferenceSlicer:
     """
-    InferenceSlicer performs slicing-based inference for small target detection. This
-    method, often referred to as
-    [Slicing Adaptive Inference (SAHI)](https://ieeexplore.ieee.org/document/9897990),
-    involves dividing a larger image into smaller slices, performing inference on each
-    slice, and then merging the detections.
+    Perform tiled inference on large images by slicing them into overlapping patches.
+
+    This class divides an input image into overlapping slices of configurable size
+    and overlap, runs inference on each slice through a user-provided callback, and
+    merges the resulting detections. The slicing process allows efficient processing
+    of large images with limited resources while preserving detection accuracy via
+    configurable overlap and post-processing of overlaps. Uses multi-threading for
+    parallel slice inference.
 
     Args:
-        slice_wh (Tuple[int, int]): Dimensions of each slice measured in pixels. The
-            tuple should be in the format `(width, height)`.
-        overlap_ratio_wh (Optional[Tuple[float, float]]): [⚠️ Deprecated: please set
-                to `None` and use `overlap_wh`] A tuple representing the
-            desired overlap ratio for width and height between consecutive slices.
-            Each value should be in the range [0, 1), where 0 means no overlap and
-            a value close to 1 means high overlap.
-        overlap_wh (Optional[Tuple[int, int]]): A tuple representing the desired
-            overlap for width and height between consecutive slices measured in pixels.
-            Each value should be greater than or equal to 0. Takes precedence over
-            `overlap_ratio_wh`.
-        overlap_filter (Union[OverlapFilter, str]): Strategy for
-            filtering or merging overlapping detections in slices.
-        iou_threshold (float): Intersection over Union (IoU) threshold
-            used when filtering by overlap.
-        callback (Callable): A function that performs inference on a given image
-            slice and returns detections.
-        thread_workers (int): Number of threads for parallel execution.
+        callback (Callable[[ImageType], Detections]): Inference function that takes
+            a sliced image and returns a `Detections` object.
+        slice_wh (int or tuple[int, int]): Size of each slice `(width, height)`.
+            If int, both width and height are set to this value.
+        overlap_wh (int or tuple[int, int]): Overlap size `(width, height)` between
+            slices. If int, both width and height are set to this value.
+        overlap_filter (OverlapFilter or str): Strategy to merge overlapping
+            detections (`NON_MAX_SUPPRESSION`, `NON_MAX_MERGE`, or `NONE`).
+        iou_threshold (float): IOU threshold used in merging overlap filtering.
+        overlap_metric (OverlapMetric or str): Metric to compute overlap
+            (`IOU` or `IOS`).
+        thread_workers (int): Number of threads for concurrent slice inference.
 
-    Note:
-        The class ensures that slices do not exceed the boundaries of the original
-        image. As a result, the final slices in the row and column dimensions might be
-        smaller than the specified slice dimensions if the image's width or height is
-        not a multiple of the slice's width or height minus the overlap.
+    Raises:
+        ValueError: If `slice_wh` or `overlap_wh` are invalid or inconsistent.
+
+    Example:
+        ```python
+        import cv2
+        import supervision as sv
+        from rfdetr import RFDETRMedium
+
+        model = RFDETRMedium()
+
+        def callback(tile):
+            return model.predict(tile)
+
+        slicer = sv.InferenceSlicer(callback, slice_wh=640, overlap_wh=100)
+
+        image = cv2.imread("example.png")
+        detections = slicer(image)
+        ```
+
+        ```python
+        import supervision as sv
+        from PIL import Image
+        from ultralytics import YOLO
+
+        model = YOLO("yolo11m.pt")
+
+        def callback(tile):
+            results = model(tile)[0]
+            return sv.Detections.from_ultralytics(results)
+
+        slicer = sv.InferenceSlicer(callback, slice_wh=640, overlap_wh=100)
+
+        image = Image.open("example.png")
+        detections = slicer(image)
+        ```
     """
 
     def __init__(
         self,
-        callback: Callable[[np.ndarray], Detections],
-        slice_wh: Tuple[int, int] = (320, 320),
-        overlap_ratio_wh: Optional[Tuple[float, float]] = (0.2, 0.2),
-        overlap_wh: Optional[Tuple[int, int]] = None,
-        overlap_filter: Union[OverlapFilter, str] = OverlapFilter.NON_MAX_SUPPRESSION,
+        callback: Callable[[ImageType], Detections],
+        slice_wh: int | tuple[int, int] = 640,
+        overlap_wh: int | tuple[int, int] = 100,
+        overlap_filter: OverlapFilter | str = OverlapFilter.NON_MAX_SUPPRESSION,
         iou_threshold: float = 0.5,
+        overlap_metric: OverlapMetric | str = OverlapMetric.IOU,
         thread_workers: int = 1,
     ):
-        if overlap_ratio_wh is not None:
-            warn_deprecated(
-                "`overlap_ratio_wh` in `InferenceSlicer.__init__` is deprecated and "
-                "will be removed in `supervision-0.27.0`. Please manually set it to "
-                "`None` and use `overlap_wh` instead."
-            )
+        slice_wh_norm = self._normalize_slice_wh(slice_wh)
+        overlap_wh_norm = self._normalize_overlap_wh(overlap_wh)
 
-        self._validate_overlap(overlap_ratio_wh, overlap_wh)
-        self.overlap_ratio_wh = overlap_ratio_wh
-        self.overlap_wh = overlap_wh
+        self._validate_overlap(slice_wh=slice_wh_norm, overlap_wh=overlap_wh_norm)
 
-        self.slice_wh = slice_wh
+        self.slice_wh = slice_wh_norm
+        self.overlap_wh = overlap_wh_norm
         self.iou_threshold = iou_threshold
+        self.overlap_metric = OverlapMetric.from_value(overlap_metric)
         self.overlap_filter = OverlapFilter.from_value(overlap_filter)
         self.callback = callback
         self.thread_workers = thread_workers
 
-    def __call__(self, image: np.ndarray) -> Detections:
+    def __call__(self, image: ImageType) -> Detections:
         """
-        Performs slicing-based inference on the provided image using the specified
-            callback.
+        Perform tiled inference on the full image and return merged detections.
 
         Args:
-            image (np.ndarray): The input image on which inference needs to be
-                performed. The image should be in the format
-                `(height, width, channels)`.
+            image (ImageType): The full image to run inference on.
 
         Returns:
-            Detections: A collection of detections for the entire image after merging
-                results from all slices and applying NMS.
-
-        Example:
-            ```python
-            import cv2
-            import supervision as sv
-            from ultralytics import YOLO
-
-            image = cv2.imread(SOURCE_IMAGE_PATH)
-            model = YOLO(...)
-
-            def callback(image_slice: np.ndarray) -> sv.Detections:
-                result = model(image_slice)[0]
-                return sv.Detections.from_ultralytics(result)
-
-            slicer = sv.InferenceSlicer(
-                callback=callback,
-                overlap_filter_strategy=sv.OverlapFilter.NON_MAX_SUPPRESSION,
-            )
-
-            detections = slicer(image)
-            ```
+            Detections: Merged detections across all slices.
         """
-        detections_list = []
-        resolution_wh = (image.shape[1], image.shape[0])
+        detections_list: list[Detections] = []
+        resolution_wh = get_image_resolution_wh(image)
+
         offsets = self._generate_offset(
             resolution_wh=resolution_wh,
             slice_wh=self.slice_wh,
-            overlap_ratio_wh=self.overlap_ratio_wh,
             overlap_wh=self.overlap_wh,
         )
 
@@ -164,125 +164,178 @@ class InferenceSlicer:
         merged = Detections.merge(detections_list=detections_list)
         if self.overlap_filter == OverlapFilter.NONE:
             return merged
-        elif self.overlap_filter == OverlapFilter.NON_MAX_SUPPRESSION:
-            return merged.with_nms(threshold=self.iou_threshold)
-        elif self.overlap_filter == OverlapFilter.NON_MAX_MERGE:
-            return merged.with_nmm(threshold=self.iou_threshold)
-        else:
-            warnings.warn(
-                f"Invalid overlap filter strategy: {self.overlap_filter}",
-                category=SupervisionWarnings,
+        if self.overlap_filter == OverlapFilter.NON_MAX_SUPPRESSION:
+            return merged.with_nms(
+                threshold=self.iou_threshold,
+                overlap_metric=self.overlap_metric,
+            )
+        if self.overlap_filter == OverlapFilter.NON_MAX_MERGE:
+            return merged.with_nmm(
+                threshold=self.iou_threshold,
+                overlap_metric=self.overlap_metric,
             )
-            return merged
 
-    def _run_callback(self, image, offset) -> Detections:
+        warnings.warn(
+            f"Invalid overlap filter strategy: {self.overlap_filter}",
+            category=SupervisionWarnings,
+        )
+        return merged
+
+    def _run_callback(self, image: ImageType, offset: np.ndarray) -> Detections:
         """
-        Run the provided callback on a slice of an image.
+        Run detection callback on a sliced portion of the image and adjust coordinates.
 
         Args:
-            image (np.ndarray): The input image on which inference needs to run
-            offset (np.ndarray): An array of shape `(4,)` containing coordinates
-                for the slice.
+            image (ImageType): The full image.
+            offset (numpy.ndarray): Coordinates `(x_min, y_min, x_max, y_max)` defining
+                the slice region.
 
         Returns:
-            Detections: A collection of detections for the slice.
+            Detections: Detections adjusted to the full image coordinate system.
         """
-        image_slice = crop_image(image=image, xyxy=offset)
+        image_slice: ImageType = crop_image(image=image, xyxy=offset)
         detections = self.callback(image_slice)
-        resolution_wh = (image.shape[1], image.shape[0])
-        detections = move_detections(
-            detections=detections, offset=offset[:2], resolution_wh=resolution_wh
-        )
+        resolution_wh = get_image_resolution_wh(image)
 
+        detections = move_detections(
+            detections=detections,
+            offset=offset[:2],
+            resolution_wh=resolution_wh,
+        )
         return detections
 
+    @staticmethod
+    def _normalize_slice_wh(
+        slice_wh: int | tuple[int, int],
+    ) -> tuple[int, int]:
+        if isinstance(slice_wh, int):
+            if slice_wh <= 0:
+                raise ValueError(
+                    f"`slice_wh` must be a positive integer. Received: {slice_wh}"
+                )
+            return slice_wh, slice_wh
+
+        if isinstance(slice_wh, tuple) and len(slice_wh) == 2:
+            width, height = slice_wh
+            if width <= 0 or height <= 0:
+                raise ValueError(
+                    f"`slice_wh` values must be positive. Received: {slice_wh}"
+                )
+            return width, height
+
+        raise ValueError(
+            "`slice_wh` must be an int or a tuple of two positive integers "
+            "(slice_w, slice_h). "
+            f"Received: {slice_wh}"
+        )
+
+    @staticmethod
+    def _normalize_overlap_wh(
+        overlap_wh: int | tuple[int, int],
+    ) -> tuple[int, int]:
+        if isinstance(overlap_wh, int):
+            if overlap_wh < 0:
+                raise ValueError(
+                    "`overlap_wh` must be a non negative integer. "
+                    f"Received: {overlap_wh}"
+                )
+            return overlap_wh, overlap_wh
+
+        if isinstance(overlap_wh, tuple) and len(overlap_wh) == 2:
+            overlap_w, overlap_h = overlap_wh
+            if overlap_w < 0 or overlap_h < 0:
+                raise ValueError(
+                    f"`overlap_wh` values must be non negative. Received: {overlap_wh}"
+                )
+            return overlap_w, overlap_h
+
+        raise ValueError(
+            "`overlap_wh` must be an int or a tuple of two non negative integers "
+            "(overlap_w, overlap_h). "
+            f"Received: {overlap_wh}"
+        )
+
     @staticmethod
     def _generate_offset(
-        resolution_wh: Tuple[int, int],
-        slice_wh: Tuple[int, int],
-        overlap_ratio_wh: Optional[Tuple[float, float]],
-        overlap_wh: Optional[Tuple[int, int]],
+        resolution_wh: tuple[int, int],
+        slice_wh: tuple[int, int],
+        overlap_wh: tuple[int, int],
     ) -> np.ndarray:
         """
-        Generate offset coordinates for slicing an image based on the given resolution,
-        slice dimensions, and overlap ratios.
+        Generate bounding boxes defining the coordinates of image slices with overlap.
 
         Args:
-            resolution_wh (Tuple[int, int]): A tuple representing the width and height
-                of the image to be sliced.
-            slice_wh (Tuple[int, int]): Dimensions of each slice measured in pixels. The
-            tuple should be in the format `(width, height)`.
-            overlap_ratio_wh (Optional[Tuple[float, float]]): A tuple representing the
-                desired overlap ratio for width and height between consecutive slices.
-                Each value should be in the range [0, 1), where 0 means no overlap and
-                a value close to 1 means high overlap.
-            overlap_wh (Optional[Tuple[int, int]]): A tuple representing the desired
-                overlap for width and height between consecutive slices measured in
-                pixels. Each value should be greater than or equal to 0.
+            resolution_wh (tuple[int, int]): Image resolution `(width, height)`.
+            slice_wh (tuple[int, int]): Size of each slice `(width, height)`.
+            overlap_wh (tuple[int, int]): Overlap size between slices `(width, height)`.
 
         Returns:
-            np.ndarray: An array of shape `(n, 4)` containing coordinates for each
-                slice in the format `[xmin, ymin, xmax, ymax]`.
-
-        Note:
-            The function ensures that slices do not exceed the boundaries of the
-                original image. As a result, the final slices in the row and column
-                dimensions might be smaller than the specified slice dimensions if the
-                image's width or height is not a multiple of the slice's width or
-                height minus the overlap.
+            numpy.ndarray: Array of shape `(num_slices, 4)` with each row as
+                `(x_min, y_min, x_max, y_max)` coordinates for a slice.
         """
         slice_width, slice_height = slice_wh
         image_width, image_height = resolution_wh
-        overlap_width = (
-            overlap_wh[0]
-            if overlap_wh is not None
-            else int(overlap_ratio_wh[0] * slice_width)
+        overlap_width, overlap_height = overlap_wh
+
+        stride_x = slice_width - overlap_width
+        stride_y = slice_height - overlap_height
+
+        def _compute_axis_starts(
+            image_size: int,
+            slice_size: int,
+            stride: int,
+        ) -> list[int]:
+            if image_size <= slice_size:
+                return [0]
+
+            if stride == slice_size:
+                return np.arange(0, image_size, stride).tolist()
+
+            last_start = image_size - slice_size
+            starts = np.arange(0, last_start, stride).tolist()
+            if not starts or starts[-1] != last_start:
+                starts.append(last_start)
+            return starts
+
+        x_starts = _compute_axis_starts(
+            image_size=image_width,
+            slice_size=slice_width,
+            stride=stride_x,
         )
-        overlap_height = (
-            overlap_wh[1]
-            if overlap_wh is not None
-            else int(overlap_ratio_wh[1] * slice_height)
+        y_starts = _compute_axis_starts(
+            image_size=image_height,
+            slice_size=slice_height,
+            stride=stride_y,
         )
 
-        width_stride = slice_width - overlap_width
-        height_stride = slice_height - overlap_height
+        x_min, y_min = np.meshgrid(x_starts, y_starts)
+        x_max = np.clip(x_min + slice_width, 0, image_width)
+        y_max = np.clip(y_min + slice_height, 0, image_height)
 
-        ws = np.arange(0, image_width, width_stride)
-        hs = np.arange(0, image_height, height_stride)
-
-        xmin, ymin = np.meshgrid(ws, hs)
-        xmax = np.clip(xmin + slice_width, 0, image_width)
-        ymax = np.clip(ymin + slice_height, 0, image_height)
-
-        offsets = np.stack([xmin, ymin, xmax, ymax], axis=-1).reshape(-1, 4)
+        offsets = np.stack(
+            [x_min, y_min, x_max, y_max],
+            axis=-1,
+        ).reshape(-1, 4)
 
         return offsets
 
     @staticmethod
     def _validate_overlap(
-        overlap_ratio_wh: Optional[Tuple[float, float]],
-        overlap_wh: Optional[Tuple[int, int]],
+        slice_wh: tuple[int, int],
+        overlap_wh: tuple[int, int],
     ) -> None:
-        if overlap_ratio_wh is not None and overlap_wh is not None:
+        overlap_w, overlap_h = overlap_wh
+        slice_w, slice_h = slice_wh
+
+        if overlap_w < 0 or overlap_h < 0:
             raise ValueError(
-                "Both `overlap_ratio_wh` and `overlap_wh` cannot be provided. "
-                "Please provide only one of them."
-            )
-        if overlap_ratio_wh is None and overlap_wh is None:
-            raise ValueError(
-                "Either `overlap_ratio_wh` or `overlap_wh` must be provided. "
-                "Please provide one of them."
+                "Overlap values must be greater than or equal to 0. "
+                f"Received: {overlap_wh}"
             )
 
-        if overlap_ratio_wh is not None:
-            if not (0 <= overlap_ratio_wh[0] < 1 and 0 <= overlap_ratio_wh[1] < 1):
-                raise ValueError(
-                    "Overlap ratios must be in the range [0, 1). "
-                    f"Received: {overlap_ratio_wh}"
-                )
-        if overlap_wh is not None:
-            if not (overlap_wh[0] >= 0 and overlap_wh[1] >= 0):
-                raise ValueError(
-                    "Overlap values must be greater than or equal to 0. "
-                    f"Received: {overlap_wh}"
-                )
+        if overlap_w >= slice_w or overlap_h >= slice_h:
+            raise ValueError(
+                "`overlap_wh` must be smaller than `slice_wh` in both dimensions "
+                f"to keep a positive stride. Received overlap_wh={overlap_wh}, "
+                f"slice_wh={slice_wh}."
+            )

supervision/detection/tools/json_sink.py

@@ -2,7 +2,7 @@ from __future__ import annotations
 
 import json
 import os
-from typing import Any, Dict, List, Optional
+from typing import Any
 
 from supervision.detection.core import Detections
 
@@ -51,8 +51,8 @@ class JSONSink:
             None
         """
         self.file_name = file_name
-        self.file: Optional[open] = None
-        self.data: List[Dict[str, Any]] = []
+        self.file: open | None = None
+        self.data: list[dict[str, Any]] = []
 
     def __enter__(self) -> JSONSink:
         self.open()
@@ -60,9 +60,9 @@ class JSONSink:
 
     def __exit__(
         self,
-        exc_type: Optional[type],
-        exc_val: Optional[Exception],
-        exc_tb: Optional[Any],
+        exc_type: type | None,
+        exc_val: Exception | None,
+        exc_tb: Any | None,
     ) -> None:
         self.write_and_close()
 
@@ -92,8 +92,8 @@ class JSONSink:
 
     @staticmethod
     def parse_detection_data(
-        detections: Detections, custom_data: Optional[Dict[str, Any]] = None
-    ) -> List[Dict[str, Any]]:
+        detections: Detections, custom_data: dict[str, Any] | None = None
+    ) -> list[dict[str, Any]]:
         parsed_rows = []
         for i in range(len(detections.xyxy)):
             row = {
@@ -126,7 +126,7 @@ class JSONSink:
         return parsed_rows
 
     def append(
-        self, detections: Detections, custom_data: Optional[Dict[str, Any]] = None
+        self, detections: Detections, custom_data: dict[str, Any] | None = None
     ) -> None:
         """
         Append detection data to the JSON file.

supervision/detection/tools/polygon_zone.py

@@ -1,12 +1,15 @@
+from __future__ import annotations
+
+from collections.abc import Iterable
 from dataclasses import replace
-from typing import Iterable, Optional
 
 import cv2
 import numpy as np
 import numpy.typing as npt
 
 from supervision import Detections
-from supervision.detection.utils import clip_boxes, polygon_to_mask
+from supervision.detection.utils.boxes import clip_boxes
+from supervision.detection.utils.converters import polygon_to_mask
 from supervision.draw.color import Color
 from supervision.draw.utils import draw_filled_polygon, draw_polygon, draw_text
 from supervision.geometry.core import Position
@@ -153,7 +156,7 @@ class PolygonZoneAnnotator:
         self.display_in_zone_count = display_in_zone_count
         self.opacity = opacity
 
-    def annotate(self, scene: np.ndarray, label: Optional[str] = None) -> np.ndarray:
+    def annotate(self, scene: np.ndarray, label: str | None = None) -> np.ndarray:
         """
         Annotates the polygon zone within a frame with a count of detected objects.
 

supervision/detection/tools/smoother.py

@@ -1,7 +1,8 @@
+from __future__ import annotations
+
 import warnings
 from collections import defaultdict, deque
 from copy import deepcopy
-from typing import Optional
 
 import numpy as np
 
@@ -95,7 +96,7 @@ class DetectionsSmoother:
 
         return self.get_smoothed_detections()
 
-    def get_track(self, track_id: int) -> Optional[Detections]:
+    def get_track(self, track_id: int) -> Detections | None:
         track = self.tracks.get(track_id, None)
         if track is None:
             return None

supervision/detection/tools/transformers.py

@@ -1,15 +1,17 @@
+from __future__ import annotations
+
 import io
-from typing import Any, Dict, Optional
+from typing import Any
 
 import numpy as np
 from PIL import Image
 
 from supervision.config import CLASS_NAME_DATA_FIELD
-from supervision.detection.utils import mask_to_xyxy
+from supervision.detection.utils.converters import mask_to_xyxy
 
 
 def process_transformers_detection_result(
-    detection_result: dict, id2label: Optional[Dict[int, str]]
+    detection_result: dict, id2label: dict[int, str] | None
 ) -> dict:
     """
     Process the result of Transformers object detection functions such as
@@ -38,7 +40,7 @@ def process_transformers_detection_result(
 
 
 def process_transformers_v4_segmentation_result(
-    segmentation_result: dict, id2label: Optional[Dict[int, str]]
+    segmentation_result: dict, id2label: dict[int, str] | None
 ) -> dict:
     """
     Process the result of Transformers segmentation functions such as
@@ -77,7 +79,7 @@ def process_transformers_v4_segmentation_result(
 
 
 def process_transformers_v5_segmentation_result(
-    segmentation_result: dict, id2label: Optional[Dict[int, str]]
+    segmentation_result: dict, id2label: dict[int, str] | None
 ) -> dict:
     """
     Process the result of Transformers segmentation functions such as
@@ -107,7 +109,7 @@ def process_transformers_v5_segmentation_result(
 
 
 def process_transformers_v5_semantic_or_instance_segmentation_result(
-    segmentation_result: dict, id2label: Optional[Dict[int, str]]
+    segmentation_result: dict, id2label: dict[int, str] | None
 ) -> dict:
     """
     Process the result of Transformers segmentation functions such as
@@ -143,7 +145,7 @@ def process_transformers_v5_semantic_or_instance_segmentation_result(
 
 
 def process_transformers_v4_panoptic_segmentation_result(
-    segmentation_result: dict, id2label: Optional[Dict[int, str]]
+    segmentation_result: dict, id2label: dict[int, str] | None
 ) -> dict:
     """
     Process the result of the Transformers function `post_process_panoptic` (v4).
@@ -177,7 +179,7 @@ def process_transformers_v4_panoptic_segmentation_result(
 
 
 def process_transformers_v5_panoptic_segmentation_result(
-    segmentation_array: np.ndarray, id2label: Optional[Dict[int, str]]
+    segmentation_array: np.ndarray, id2label: dict[int, str] | None
 ) -> dict:
     """
     Process the result of the Transformers function
@@ -220,9 +222,9 @@ def png_string_to_segmentation_array(png_string: bytes) -> np.ndarray:
 
 def append_class_names_to_data(
     class_ids: np.ndarray,
-    id2label: Optional[Dict[int, str]],
-    data: Optional[Dict[str, Any]] = None,
-) -> Dict[str, Any]:
+    id2label: dict[int, str] | None,
+    data: dict[str, Any] | None = None,
+) -> dict[str, Any]:
     """
     Helper function to create or append to a data dictionary with class names if
     available.

supervision/detection/utils/boxes.py

@@ -0,0 +1,343 @@
+from __future__ import annotations
+
+import numpy as np
+import numpy.typing as npt
+
+from supervision.detection.utils.iou_and_nms import box_iou_batch
+
+
+def clip_boxes(xyxy: np.ndarray, resolution_wh: tuple[int, int]) -> np.ndarray:
+    """
+    Clips bounding boxes coordinates to fit within the frame resolution.
+
+    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)`.
+        resolution_wh (Tuple[int, int]): A tuple of the form
+            `(width, height)` representing the resolution of the frame.
+
+    Returns:
+        np.ndarray: A numpy array of shape `(N, 4)` where each row
+            corresponds to a bounding box with coordinates clipped to fit
+            within the frame resolution.
+
+    Examples:
+        ```python
+        import numpy as np
+        import supervision as sv
+
+        xyxy = np.array([
+            [10, 20, 300, 200],
+            [15, 25, 350, 450],
+            [-10, -20, 30, 40]
+        ])
+
+        sv.clip_boxes(xyxy=xyxy, resolution_wh=(320, 240))
+        # array([
+        #     [ 10,  20, 300, 200],
+        #     [ 15,  25, 320, 240],
+        #     [  0,   0,  30,  40]
+        # ])
+        ```
+    """
+    result = np.copy(xyxy)
+    width, height = resolution_wh
+    result[:, [0, 2]] = result[:, [0, 2]].clip(0, width)
+    result[:, [1, 3]] = result[:, [1, 3]].clip(0, height)
+    return result
+
+
+def pad_boxes(xyxy: np.ndarray, px: int, py: int | None = None) -> np.ndarray:
+    """
+    Pads bounding boxes coordinates with a constant padding.
+
+    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)`.
+        px (int): The padding value to be added to both the left and right sides of
+            each bounding box.
+        py (Optional[int]): The padding value to be added to both the top and bottom
+            sides of each bounding box. If not provided, `px` will be used for both
+            dimensions.
+
+    Returns:
+        np.ndarray: A numpy array of shape `(N, 4)` where each row corresponds to a
+            bounding box with coordinates padded according to the provided padding
+            values.
+
+    Examples:
+        ```python
+        import numpy as np
+        import supervision as sv
+
+        xyxy = np.array([
+            [10, 20, 30, 40],
+            [15, 25, 35, 45]
+        ])
+
+        sv.pad_boxes(xyxy=xyxy, px=5, py=10)
+        # array([
+        #     [ 5, 10, 35, 50],
+        #     [10, 15, 40, 55]
+        # ])
+        ```
+    """
+    if py is None:
+        py = px
+
+    result = xyxy.copy()
+    result[:, [0, 1]] -= [px, py]
+    result[:, [2, 3]] += [px, py]
+
+    return result
+
+
+def denormalize_boxes(
+    xyxy: np.ndarray,
+    resolution_wh: tuple[int, int],
+    normalization_factor: float = 1.0,
+) -> np.ndarray:
+    """
+    Convert normalized bounding box coordinates to absolute pixel coordinates.
+
+    Multiplies each bounding box coordinate by image size and divides by
+    `normalization_factor`, mapping values from normalized `[0, normalization_factor]`
+    to absolute pixel values for a given resolution.
+
+    Args:
+        xyxy (`numpy.ndarray`): Normalized bounding boxes of shape `(N, 4)`,
+            where each row is `(x_min, y_min, x_max, y_max)`, values in
+            `[0, normalization_factor]`.
+        resolution_wh (`tuple[int, int]`): Target image resolution as `(width, height)`.
+        normalization_factor (`float`): Maximum value of input coordinate range.
+            Defaults to `1.0`.
+
+    Returns:
+        (`numpy.ndarray`): Array of shape `(N, 4)` with absolute coordinates in
+            `(x_min, y_min, x_max, y_max)` format.
+
+    Examples:
+        ```python
+        import numpy as np
+        import supervision as sv
+
+        xyxy = np.array([
+            [0.1, 0.2, 0.5, 0.6],
+            [0.3, 0.4, 0.7, 0.8],
+            [0.2, 0.1, 0.6, 0.5]
+        ])
+
+        sv.denormalize_boxes(xyxy, (1280, 720))
+        # array([
+        #     [128., 144., 640., 432.],
+        #     [384., 288., 896., 576.],
+        #     [256.,  72., 768., 360.]
+        # ])
+        ```
+
+        ```
+        import numpy as np
+        import supervision as sv
+
+        xyxy = np.array([
+            [256., 128., 768., 640.]
+        ])
+
+        sv.denormalize_boxes(xyxy, (1280, 720), normalization_factor=1024.0)
+        # array([
+        #     [320.,  90., 960., 450.]
+        # ])
+        ```
+    """
+    width, height = resolution_wh
+    result = xyxy.copy()
+
+    result[:, [0, 2]] = (result[:, [0, 2]] * width) / normalization_factor
+    result[:, [1, 3]] = (result[:, [1, 3]] * height) / normalization_factor
+
+    return result
+
+
+def move_boxes(
+    xyxy: npt.NDArray[np.float64], offset: npt.NDArray[np.int32]
+) -> npt.NDArray[np.float64]:
+    """
+    Parameters:
+        xyxy (npt.NDArray[np.float64]): An array of shape `(n, 4)` containing the
+            bounding boxes coordinates in format `[x1, y1, x2, y2]`
+        offset (np.array): An array of shape `(2,)` containing offset values in format
+            is `[dx, dy]`.
+
+    Returns:
+        npt.NDArray[np.float64]: Repositioned bounding boxes.
+
+    Examples:
+        ```python
+        import numpy as np
+        import supervision as sv
+
+        xyxy = np.array([
+            [10, 10, 20, 20],
+            [30, 30, 40, 40]
+        ])
+        offset = np.array([5, 5])
+
+        sv.move_boxes(xyxy=xyxy, offset=offset)
+        # array([
+        #    [15, 15, 25, 25],
+        #    [35, 35, 45, 45]
+        # ])
+        ```
+    """
+    return xyxy + np.hstack([offset, offset])
+
+
+def move_oriented_boxes(
+    xyxyxyxy: npt.NDArray[np.float64], offset: npt.NDArray[np.int32]
+) -> npt.NDArray[np.float64]:
+    """
+    Parameters:
+    xyxyxyxy (npt.NDArray[np.float64]): An array of shape `(n, 4, 2)` containing the
+    oriented bounding boxes coordinates in format
+    `[[x1, y1], [x2, y2], [x3, y3], [x3, y3]]`
+    offset (np.array): An array of shape `(2,)` containing offset values in format
+        is `[dx, dy]`.
+
+    Returns:
+    npt.NDArray[np.float64]: Repositioned bounding boxes.
+
+    Examples:
+    ```python
+    import numpy as np
+    import supervision as sv
+
+    xyxyxyxy = np.array([
+        [
+            [20, 10],
+            [10, 20],
+            [20, 30],
+            [30, 20]
+        ],
+        [
+            [30 ,30],
+            [20, 40],
+            [30, 50],
+            [40, 40]
+        ]
+    ])
+    offset = np.array([5, 5])
+
+    sv.move_oriented_boxes(xyxy=xyxy, offset=offset)
+    # array([
+    #     [
+    #         [25, 15],
+    #         [15, 25],
+    #         [25, 35],
+    #         [35, 25]
+    #     ],
+    #     [
+    #         [35, 35],
+    #         [25, 45],
+    #         [35, 55],
+    #         [45, 45]
+    #     ]
+    # ])
+    ```
+    """
+    return xyxyxyxy + offset
+
+
+def scale_boxes(
+    xyxy: npt.NDArray[np.float64], factor: float
+) -> npt.NDArray[np.float64]:
+    """
+    Scale the dimensions of bounding boxes.
+
+    Parameters:
+        xyxy (npt.NDArray[np.float64]): An array of shape `(n, 4)` containing the
+            bounding boxes coordinates in format `[x1, y1, x2, y2]`
+        factor (float): A float value representing the factor by which the box
+            dimensions are scaled. A factor greater than 1 enlarges the boxes, while a
+            factor less than 1 shrinks them.
+
+    Returns:
+        npt.NDArray[np.float64]: Scaled bounding boxes.
+
+    Examples:
+        ```python
+        import numpy as np
+        import supervision as sv
+
+        xyxy = np.array([
+            [10, 10, 20, 20],
+            [30, 30, 40, 40]
+        ])
+
+        sv.scale_boxes(xyxy=xyxy, factor=1.5)
+        # array([
+        #    [ 7.5,  7.5, 22.5, 22.5],
+        #    [27.5, 27.5, 42.5, 42.5]
+        # ])
+        ```
+    """
+    centers = (xyxy[:, :2] + xyxy[:, 2:]) / 2
+    new_sizes = (xyxy[:, 2:] - xyxy[:, :2]) * factor
+    return np.concatenate((centers - new_sizes / 2, centers + new_sizes / 2), axis=1)
+
+
+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)