Merge pull request #1486 from roboflow/develop

`supervision-0.23.0` release

Author: LinasKo

.github/workflows/notebook-bot.yml

@@ -0,0 +1,64 @@
+name: Notebook Check Pull Request
+
+on:
+  pull_request_target:
+    types: [opened, reopened]
+
+permissions:
+  contents: read
+
+jobs:
+  comment-welcome:
+    permissions:
+      contents: read
+      pull-requests: write
+
+    runs-on: ubuntu-latest
+    steps:
+    - name: Fetch pull request branch
+      uses: actions/checkout@v4
+      with:
+        repository: ${{ github.event.pull_request.head.repo.full_name }}
+        ref: ${{ github.event.pull_request.head.sha }}
+    - name: Fetch base develop branch
+      run: git fetch -u "$GITHUB_SERVER_URL/$GITHUB_REPOSITORY" develop:develop
+    - name: Create message
+      env:
+        HEAD_REPOSITORY: ${{ github.event.pull_request.head.repo.full_name }}
+        HEAD_REF: ${{ github.event.pull_request.head.ref }}
+        PR_NUM: ${{ github.event.pull_request.number }}
+      run: |
+        # Preview links and tool usage only needed for notebook changes.
+        readarray -t changed_notebooks < <(git diff --name-only develop | grep '\.ipynb$' || true)
+        if [[ ${#changed_notebooks[@]} == 0 ]]; then
+          echo "No notebooks modified in this pull request."
+        else
+          msg="<h4>Preview</h4>\n"
+          msg+="Preview and run these notebook edits with Google Colab:\n<ul>\n"
+          # Link to PR branch in user's fork that is always current.
+          for fp in "${changed_notebooks[@]}"; do
+            gh_path="${HEAD_REPOSITORY}/blob/${HEAD_REF}/${fp}"
+            colab_url="https://colab.research.google.com/github/${gh_path}"
+            msg+="<li><a href='${colab_url}'>${fp}</a></li>\n"
+          done
+          msg+="</ul>\n"
+
+          reviewnb_url="https://app.reviewnb.com/${GITHUB_REPOSITORY}/pull/${PR_NUM}/files/"
+          msg+="Rendered <a href='${reviewnb_url}'>notebook diffs</a> available on ReviewNB.com.\n"
+
+          msg+="If commits are added to the pull request, synchronize your local branch: <code>git pull origin $HEAD_REF</code>\n"
+        fi
+        echo "MESSAGE=$msg" >> $GITHUB_ENV
+    - name: Post comment
+      env:
+        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        ISSUE_URL: ${{ github.event.pull_request.issue_url }}
+      run: |
+        # Env var defined in previous step. Escape string for JSON.
+        body="$(echo -n -e $MESSAGE | python3 -c 'import json,sys; print(json.dumps(sys.stdin.read()))')"
+        # Add comment to pull request.
+        curl -X POST \
+          -H "Accept: application/vnd.github.v3+json" \
+          -H "Authorization: token $GITHUB_TOKEN" \
+          "${ISSUE_URL}/comments" \
+          --data "{\"body\": $body}"

.github/workflows/test-doc.yml

@@ -14,21 +14,8 @@ jobs:
         uses: actions/setup-python@v5
         with:
           python-version: '3.10'
-      - name: 📦 Install mkdocs-material
-        run: pip install "mkdocs-material[all]"
-      - name: 📦 Install mkdocstrings[python]
-        run: pip install "mkdocstrings[python]"
-      - name: 📦 Install mkdocs-material[imaging]
-        run: pip install "mkdocs-material[imaging]"
-      - name: 📦 Install mike
-        run: pip install "mike"
-      - name: 📦 Install mkdocs-git-revision-date-localized-plugin
-        run: pip install "mkdocs-git-revision-date-localized-plugin"
-      - name: 📦 Install JupyterLab
-        run: pip install jupyterlab
-      - name: 📦 Install mkdocs-jupyter
-        run: pip install mkdocs-jupyter
-      - name: 📦 Install mkdocs-git-committers-plugin-2
-        run: pip install mkdocs-git-committers-plugin-2
-      - name: 🧪 Test documentation build
-        run: mkdocs build --verbose
+      - name:  🏗️ Install dependencies and Test Docs Build
+        run: |
+          python -m pip install --upgrade pip
+          pip install "mkdocs-material" "mkdocstrings[python]" "mkdocs-material[imaging]" mike "mkdocs-git-revision-date-localized-plugin" jupyterlab mkdocs-jupyter mkdocs-git-committers-plugin-2
+          mkdocs build --verbose

.pre-commit-config.yaml

@@ -9,7 +9,6 @@ repos:
   - repo: https://github.com/pre-commit/pre-commit-hooks
     rev: v4.6.0
     hooks:
-      - id: end-of-file-fixer
       - id: trailing-whitespace
         exclude: test/.*\.py
       - id: check-yaml
@@ -19,33 +18,21 @@ repos:
       - id: check-case-conflict
       - id: check-added-large-files
       - id: detect-private-key
-      - id: forbid-new-submodules
       - id: pretty-format-json
         exclude: demo.ipynb
         args: ['--autofix', '--no-sort-keys', '--indent=4']
       - id: end-of-file-fixer
       - id: mixed-line-ending
 
-
   -   repo: https://github.com/PyCQA/bandit
       rev: '1.7.9'
       hooks:
       -   id: bandit
           args: ["-c", "pyproject.toml"]
           additional_dependencies: ["bandit[toml]"]
 
-  -   repo: https://github.com/pycqa/isort
-      rev: 5.13.2
-      hooks:
-      -   id: isort
-          name: isort (python)
-      -   id: isort
-          name: isort (pyi)
-          types: [pyi]
-
-
   -   repo: https://github.com/astral-sh/ruff-pre-commit
-      rev: v0.5.1
+      rev: v0.6.2
       hooks:
       -   id: ruff
           args: [--fix, --exit-non-zero-on-fix]

CONTRIBUTING.md

@@ -173,7 +173,7 @@ Furthermore, we have integrated a pre-commit GitHub Action into our workflow. Th
 
 To run the pre-commit tool, follow these steps:
 
-1. Install pre-commit by running the following command: `poetry install`. It will not only install pre-commit but also install all the deps and dev-deps of project
+1. Install pre-commit by running the following command: `poetry install --with dev`. It will not only install pre-commit but also install all the deps and dev-deps of project
 
 2. Once pre-commit is installed, navigate to the project's root directory.
 

README.md

@@ -16,6 +16,7 @@
 
 [![version](https://badge.fury.io/py/supervision.svg)](https://badge.fury.io/py/supervision)
 [![downloads](https://img.shields.io/pypi/dm/supervision)](https://pypistats.org/packages/supervision)
+[![snyk](https://snyk.io/advisor/python/supervision/badge.svg)](https://snyk.io/advisor/python/supervision)
 [![license](https://img.shields.io/pypi/l/supervision)](https://github.com/roboflow/supervision/blob/main/LICENSE.md)
 [![python-version](https://img.shields.io/pypi/pyversions/supervision)](https://badge.fury.io/py/supervision)
 [![colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/roboflow/supervision/blob/main/demo.ipynb)
@@ -110,18 +111,21 @@ Supervision provides a set of [utils](https://supervision.roboflow.com/latest/da
 
 ```python
 import supervision as sv
+from roboflow import Roboflow
 
-dataset = sv.DetectionDataset.from_yolo(
-    images_directory_path=...,
-    annotations_directory_path=...,
-    data_yaml_path=...
+project = Roboflow().workspace(<WORKSPACE_ID>).project(<PROJECT_ID>)
+dataset = project.version(<PROJECT_VERSION>).download("coco")
+
+ds = sv.DetectionDataset.from_coco(
+    images_directory_path=f"{dataset.location}/train",
+    annotations_path=f"{dataset.location}/train/_annotations.coco.json",
 )
 
-dataset.classes
-['dog', 'person']
+path, image, annotation = ds[0]
+    # loads image on demand
 
-len(dataset)
-# 1000
+for path, image, annotation in ds:
+    # loads image on demand
 ```
 
 <details close>

demo.ipynb

@@ -972,7 +972,7 @@
     }
    ],
    "source": [
-    "from supervision.assets import download_assets, VideoAssets\n",
+    "from supervision.assets import VideoAssets, download_assets\n",
     "\n",
     "download_assets(VideoAssets.VEHICLES)\n",
     "VIDEO_PATH = VideoAssets.VEHICLES.value"

docs/changelog.md

@@ -1,3 +1,136 @@
+### 0.23.0 <small>Aug 28, 2024</small>
+
+- Added [#930](https://github.com/roboflow/supervision/pull/930): `IconAnnotator`, a [new annotator](https://supervision.roboflow.com/latest/detection/annotators/#supervision.annotators.core.IconAnnotator) that allows drawing icons on each detection. Useful if you want to draw a specific icon for each class.
+
+```python
+import supervision as sv
+from inference import get_model
+
+image = <SOURCE_IMAGE_PATH>
+icon_dog = <DOG_PNG_PATH>
+icon_cat = <CAT_PNG_PATH>
+
+model = get_model(model_id="yolov8n-640")
+results = model.infer(image)[0]
+detections = sv.Detections.from_inference(results)
+
+icon_paths = []
+for class_name in detections.data["class_name"]:
+    if class_name == "dog":
+        icon_paths.append(icon_dog)
+    elif class_name == "cat":
+        icon_paths.append(icon_cat)
+    else:
+        icon_paths.append("")
+
+icon_annotator = sv.IconAnnotator()
+annotated_frame = icon_annotator.annotate(
+    scene=image.copy(),
+    detections=detections,
+    icon_path=icon_paths
+)
+```
+
+- Added [#1385](https://github.com/roboflow/supervision/pull/1385): [`BackgroundColorAnnotator`](https://supervision.roboflow.com/latest/detection/annotators/#supervision.annotators.core.BackgroundColorAnnotator), that draws an overlay on the background images of the detections.
+
+```python
+import supervision as sv
+from inference import get_model
+
+image = <SOURCE_IMAGE_PATH>
+
+model = get_model(model_id="yolov8n-640")
+results = model.infer(image)[0]
+detections = sv.Detections.from_inference(results)
+
+background_overlay_annotator = sv.BackgroundOverlayAnnotator()
+annotated_frame = background_overlay_annotator.annotate(
+    scene=image.copy(),
+    detections=detections
+)
+```
+
+- Added [#1386](https://github.com/roboflow/supervision/pull/1386): Support for Transformers v5 functions in [`sv.Detections.from_transformers`](https://supervision.roboflow.com/latest/detection/core/#supervision.detection.core.Detections.from_transformers). This includes the `DetrImageProcessor` methods `post_process_object_detection`, `post_process_panoptic_segmentation`, `post_process_semantic_segmentation`, and `post_process_instance_segmentation`.
+
+```python
+import torch
+import supervision as sv
+from PIL import Image
+from transformers import DetrImageProcessor, DetrForObjectDetection
+
+processor = DetrImageProcessor.from_pretrained("facebook/detr-resnet-50")
+model = DetrForObjectDetection.from_pretrained("facebook/detr-resnet-50")
+
+image = Image.open(<SOURCE_IMAGE_PATH>)
+inputs = processor(images=image, return_tensors="pt")
+
+with torch.no_grad():
+    outputs = model(**inputs)
+
+width, height = image.size
+target_size = torch.tensor([[height, width]])
+results = processor.post_process_object_detection(
+    outputs=outputs, target_sizes=target_size)[0]
+detections = sv.Detections.from_transformers(
+    transformers_results=results,
+    id2label=model.config.id2label)
+```
+
+- Added [#1354](https://github.com/roboflow/supervision/pull/1354): Ultralytics SAM (Segment Anything Model) support in [`sv.Detections.from_ultralytics`](https://supervision.roboflow.com/latest/detection/core/#supervision.detection.core.Detections.from_ultralytics). [SAM2](https://sam2.metademolab.com/) was released during this update, and is already supported via [`sv.Detections.from_sam`](https://supervision.roboflow.com/latest/detection/core/#supervision.detection.core.Detections.from_sam).
+
+```python
+import supervision as sv
+from segment_anything import (
+    sam_model_registry,
+    SamAutomaticMaskGenerator
+)
+
+sam_model_reg = sam_model_registry[MODEL_TYPE]
+sam = sam_model_reg(checkpoint=CHECKPOINT_PATH).to(device=DEVICE)
+mask_generator = SamAutomaticMaskGenerator(sam)
+sam_result = mask_generator.generate(IMAGE)
+detections = sv.Detections.from_sam(sam_result=sam_result)
+```
+
+- Added [#1458](https://github.com/roboflow/supervision/pull/1458): `outline_color` options for [`TriangleAnnotator`](https://supervision.roboflow.com/latest/detection/annotators/#supervision.annotators.core.TriangleAnnotator) and [`DotAnnotator`](https://supervision.roboflow.com/latest/detection/annotators/#supervision.annotators.core.DotAnnotator).
+
+- Added [#1409](https://github.com/roboflow/supervision/pull/1409): `text_color` option for [`VertexLabelAnnotator`](https://supervision.roboflow.com/latest/keypoint/annotators/#supervision.keypoint.annotators.VertexLabelAnnotator) keypoint annotator.
+
+- Changed [#1434](https://github.com/roboflow/supervision/pull/1434): [`InferenceSlicer`](https://supervision.roboflow.com/latest/detection/tools/inference_slicer/) now features an `overlap_ratio_wh` parameter, making it easier to compute slice sizes when handling overlapping slices.
+
+- Fix [#1448](https://github.com/roboflow/supervision/pull/1448): Various annotator type issues have been resolved, supporting expanded error handling.
+
+- Fix [#1348](https://github.com/roboflow/supervision/pull/1348): Introduced a new method for [seeking to a specific video frame](https://supervision.roboflow.com/latest/utils/video/#supervision.utils.video.get_video_frames_generator), addressing cases where traditional seek methods were failing. It can be enabled with `iterative_seek=True`.
+
+```python
+import supervision as sv
+
+for frame in sv.get_video_frames_generator(
+    source_path=<SOURCE_VIDEO_PATH>,
+    start=60,
+    iterative_seek=True
+):
+    ...
+```
+
+- Fix [#1424](https://github.com/roboflow/supervision/pull/1424): `plot_image` function now clearly indicates that the size is in inches.
+
+!!! failure "Removed"
+
+    The `track_buffer`, `track_thresh`, and `match_thresh` parameters in [`ByteTrack`](trackers.md/#supervision.tracker.byte_tracker.core.ByteTrack) are deprecated and were removed as of `supervision-0.23.0`. Use `lost_track_buffer,` `track_activation_threshold`, and `minimum_matching_threshold` instead.
+
+!!! failure "Removed"
+
+    The `triggering_position ` parameter in [`sv.PolygonZone`](detection/tools/polygon_zone.md/#supervision.detection.tools.polygon_zone.PolygonZone) was removed as of `supervision-0.23.0`. Use `triggering_anchors ` instead.
+
+!!! failure "Deprecated"
+
+    `overlap_filter_strategy` in `InferenceSlicer.__init__` is deprecated and will be removed in `supervision-0.27.0`. Use `overlap_strategy` instead.
+
+!!! failure "Deprecated"
+
+    `overlap_ratio_wh` in `InferenceSlicer.__init__` is deprecated and will be removed in `supervision-0.27.0`. Use `overlap_wh` instead.
+
 ### 0.22.0 <small>Jul 12, 2024</small>
 
 - Added [#1326](https://github.com/roboflow/supervision/pull/1326): [`sv.DetectionsDataset`](https://supervision.roboflow.com/latest/datasets/core/#supervision.dataset.core.DetectionDataset) and [`sv.ClassificationDataset`](https://supervision.roboflow.com/latest/datasets/core/#supervision.dataset.core.ClassificationDataset) allowing to load the images into memory only when necessary (lazy loading).
@@ -360,7 +493,7 @@ annotated_frame = crop_annotator.annotate(
 
 !!! failure "Deprecated"
 
-    The `track_buffer`, `track_thresh`, and `match_thresh` parameters in `sv.ByterTrack` are deprecated and will be removed in `supervision-0.23.0`. Use `lost_track_buffer,` `track_activation_threshold`, and `minimum_matching_threshold` instead.
+    The `track_buffer`, `track_thresh`, and `match_thresh` parameters in `sv.ByteTrack` are deprecated and will be removed in `supervision-0.23.0`. Use `lost_track_buffer,` `track_activation_threshold`, and `minimum_matching_threshold` instead.
 
 - Changed [#910](https://github.com/roboflow/supervision/pull/910): [`sv.PolygonZone`](/0.19.0/detection/tools/polygon_zone/#supervision.detection.tools.polygon_zone.PolygonZone) to now accept a list of specific box anchors that must be in zone for a detection to be counted.
 

docs/datasets/core.md

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

docs/deprecated.md

@@ -7,15 +7,24 @@ status: deprecated
 
 These features are phased out due to better alternatives or potential issues in future versions. Deprecated functionalities are supported for **five subsequent releases**, providing time for users to transition to updated methods.
 
-- The `track_buffer`, `track_thresh`, and `match_thresh` parameters in [`ByterTrack`](trackers.md/#supervision.tracker.byte_tracker.core.ByteTrack) are deprecated and will be removed in `supervision-0.23.0`. Use `lost_track_buffer,` `track_activation_threshold`, and `minimum_matching_threshold` instead.
-- The `triggering_position ` parameter in [`sv.PolygonZone`](detection/tools/polygon_zone.md/#supervision.detection.tools.polygon_zone.PolygonZone) will be removed in `supervision-0.23.0`. Use `triggering_anchors ` instead.
 - The `frame_resolution_wh ` parameter in [`sv.PolygonZone`](detection/tools/polygon_zone.md/#supervision.detection.tools.polygon_zone.PolygonZone) will be removed in `supervision-0.24.0`.
-- Constructing `DetectionDataset` and `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.
+
+- 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` has been removed. `BoundingBoxAnnotator` will be removed in `supervision-0.26.0`.
+- `BoundingBoxAnnotator` has been renamed to `BoxAnnotator` after the old implementation of [`BoxAnnotator`](https://supervision.roboflow.com/latest/detection/annotators/#supervision.annotators.core.BoxAnnotator) has been removed. `BoundingBoxAnnotator` will be removed in `supervision-0.26.0`.
+
+- `overlap_filter_strategy` in [`InferenceSlicer.__init__`](https://supervision.roboflow.com/latest/detection/tools/inference_slicer/) is deprecated and will be removed in `supervision-0.27.0`. Use `overlap_strategy` instead.
+- `overlap_ratio_wh` in [`InferenceSlicer.__init__`](https://supervision.roboflow.com/latest/detection/tools/inference_slicer/) is deprecated and will be removed in `supervision-0.27.0`. Use `overlap_wh` instead.
 
 # Removed
 
+### 0.23.0
+
+- The `track_buffer`, `track_thresh`, and `match_thresh` parameters in [`ByteTrack`](trackers.md/#supervision.tracker.byte_tracker.core.ByteTrack) are deprecated and were removed as of `supervision-0.23.0`. Use `lost_track_buffer,` `track_activation_threshold`, and `minimum_matching_threshold` instead.
+- The `triggering_position ` parameter in [`sv.PolygonZone`](detection/tools/polygon_zone.md/#supervision.detection.tools.polygon_zone.PolygonZone) was removed as of `supervision-0.23.0`. Use `triggering_anchors ` instead.
+
+### 0.22.0
+
 - [`Detections.from_froboflow`](detection/core.md/#supervision.detection.core.Detections.from_roboflow) is removed as of `supervision-0.22.0`. Use [`Detections.from_inference`](detection/core.md/#supervision.detection.core.Detections.from_inference) instead.
 - 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.