Merge pull request #663 from roboflow/develop

`supervision-0.17.1` release

.github/requirements-dev-min.txt

@@ -8,7 +8,7 @@ idna==3.4
 iniconfig==2.0.0
 kiwisolver==1.4.5
 matplotlib==3.5.0
-numpy==1.24.4
+numpy==1.21.2
 opencv-python==4.5.5.64
 packaging==23.2
 Pillow==10.1.0

.github/requirements-dev.txt

@@ -1,17 +0,0 @@
-contourpy==1.1.0 ; python_version >= "3.8" and python_full_version < "3.12.0"
-cycler==0.11.0 ; python_version >= "3.8" and python_full_version < "3.12.0"
-fonttools==4.41.1 ; python_version >= "3.8" and python_full_version < "3.12.0"
-importlib-resources==6.0.0 ; python_version >= "3.8" and python_version < "3.10"
-kiwisolver==1.4.4 ; python_version >= "3.8" and python_full_version < "3.12.0"
-matplotlib==3.7.2 ; python_version >= "3.8" and python_full_version < "3.12.0"
-numpy==1.24.4 ; python_version >= "3.8" and python_version < "3.12"
-opencv-python-headless==4.8.0.74 ; python_version >= "3.8" and python_full_version < "3.12.0"
-packaging==23.1 ; python_version >= "3.8" and python_full_version < "3.12.0"
-pillow==10.0.1 ; python_version >= "3.8" and python_full_version < "3.12.0"
-pyparsing==3.0.9 ; python_version >= "3.8" and python_full_version < "3.12.0"
-python-dateutil==2.8.2 ; python_version >= "3.8" and python_full_version < "3.12.0"
-pyyaml==6.0.1 ; python_version >= "3.8" and python_full_version < "3.12.0"
-scipy==1.10.1 ; python_version >= "3.8" and python_version < "3.12"
-six==1.16.0 ; python_version >= "3.8" and python_full_version < "3.12.0"
-zipp==3.16.2 ; python_version >= "3.8" and python_version < "3.10"
-pytest==7.4.0 ; python_version >= "3.8" and python_full_version < "3.12.0"

.github/workflows/docs.yml

@@ -17,7 +17,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - uses: actions/setup-python@v4
+      - uses: actions/setup-python@v5
         with:
           python-version: 3.x
       - run: pip install mkdocs-material

.github/workflows/publish-test.yml

@@ -19,7 +19,7 @@ jobs:
         uses: actions/checkout@v4
 
       - name: 🐍 Set up Python 3.8 environment for build
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v5
         with:
           python-version: "3.8"
 

.github/workflows/publish.yml

@@ -21,7 +21,7 @@ jobs:
         with:
           ref: ${{ github.head_ref }}
       - name: 🐍 Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v5
         with:
           python-version: ${{ matrix.python-version }}
 

.github/workflows/test-min.yml

@@ -14,7 +14,7 @@ jobs:
       - name: 🛎️ Checkout
         uses: actions/checkout@v4
       - name: 🐍 Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v5
         # id based on python version
         id: python-setup
         with:

.github/workflows/test.yml

@@ -9,24 +9,21 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: ["3.8", "3.9", "3.10","3.11"]
+        python-version: ["3.8", "3.9", "3.10", "3.11", "3.12"]
     steps:
       - name: 🛎️ Checkout
         uses: actions/checkout@v4
       - name: 🐍 Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v4
-        # id based on python version
-        id: python-setup
+        uses: actions/setup-python@v5
         with:
           python-version: ${{ matrix.python-version }}
           check-latest: true
-          cache: 'pip'
-          cache-dependency-path: '**/requirements-dev.txt'
 
       - name: 📦 Install dependencies
         run: |
           python -m pip install --upgrade pip
-          pip install -r .github/requirements-dev.txt
+          pip install .
+          pip install pytest
 
       - name: 🧪 Test
         run: "python -m pytest ./test"

README.md

@@ -31,10 +31,10 @@
 ## 💻 install
 
 Pip install the supervision package in a
-[**3.11>=Python>=3.8**](https://www.python.org/) environment.
+[**Python>=3.8**](https://www.python.org/) environment.
 
 ```bash
-pip install supervision[desktop]
+pip install supervision
 ```
 
 Read more about desktop, headless, and local installation in our [guide](https://roboflow.github.io/supervision/).

demo.ipynb

@@ -226,7 +226,7 @@
                     "output_type": "stream",
                     "text": [
                         "\u001b[?25l     \u001b[90m━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\u001b[0m \u001b[32m0.0/45.4 kB\u001b[0m \u001b[31m?\u001b[0m eta \u001b[36m-:--:--\u001b[0m\r\u001b[2K     \u001b[90m━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\u001b[0m \u001b[32m45.4/45.4 kB\u001b[0m \u001b[31m3.4 MB/s\u001b[0m eta \u001b[36m0:00:00\u001b[0m\n",
-                        "\u001b[?25h0.16.0\n"
+                        "\u001b[?25h0.17.0\n"
                     ]
                 }
             ],
@@ -803,6 +803,15 @@
                 "**NOTE:** During our demo, we will need some example videos."
             ]
         },
+        {
+            "cell_type": "code",
+            "execution_count": null,
+            "metadata": {},
+            "outputs": [],
+            "source": [
+                "!pip install -q supervision[assets]"
+            ]
+        },
         {
             "cell_type": "code",
             "execution_count": 63,
@@ -831,9 +840,7 @@
             },
             "outputs": [],
             "source": [
-                "%cd {HOME}/videos\n",
-                "\n",
-                "!wget --load-cookies /tmp/cookies.txt \"https://docs.google.com/uc?export=download&confirm=$(wget --quiet --save-cookies /tmp/cookies.txt --keep-session-cookies --no-check-certificate 'https://docs.google.com/uc?export=download&id=1pz68D1Gsx80MoPg-_q-IbEdESEmyVLm-' -O- | sed -rn 's/.*confirm=([0-9A-Za-z_]+).*/\\1\\n/p')&id=1pz68D1Gsx80MoPg-_q-IbEdESEmyVLm-\" -O vehicle-counting.mp4 && rm -rf /tmp/cookies.txt"
+                "%cd {HOME}/videos"
             ]
         },
         {
@@ -844,7 +851,9 @@
             },
             "outputs": [],
             "source": [
-                "VIDEO_PATH = f\"{HOME}/videos/vehicle-counting.mp4\""
+                "from supervision.assets import download_assets, VideoAssets\n",
+                "download_assets(VideoAssets.VEHICLES)\n",
+                "VIDEO_PATH = f\"{HOME}/videos/vehicle.mp4\""
             ]
         },
         {

docs/annotators.md

@@ -40,7 +40,7 @@
 
     </div>
 
-=== "BoxMask"
+=== "Color"
 
     ```python
     >>> import supervision as sv
@@ -48,8 +48,8 @@
     >>> image = ...
     >>> detections = sv.Detections(...)
 
-    >>> box_mask_annotator = sv.BoxMaskAnnotator()
-    >>> annotated_frame = box_mask_annotator.annotate(
+    >>> color_annotator = sv.ColorAnnotator()
+    >>> annotated_frame = color_annotator.annotate(
     ...     scene=image.copy(),
     ...     detections=detections
     ... )
@@ -103,6 +103,27 @@
 
     </div>
 
+=== "Triangle"
+
+    ```python
+    >>> import supervision as sv
+
+    >>> image = ...
+    >>> detections = sv.Detections(...)
+
+    >>> triangle_annotator = sv.TriangleAnnotator()
+    >>> annotated_frame = triangle_annotator.annotate(
+    ...     scene=image.copy(),
+    ...     detections=detections
+    ... )
+    ```
+
+    <div class="result" markdown>
+
+    ![triangle-annotator-example](https://media.roboflow.com/supervision-annotator-examples/triangle-annotator-example.png){ align=center width="800" }
+
+    </div>
+
 === "Ellipse"
 
     ```python
@@ -318,9 +339,9 @@
 
 :::supervision.annotators.core.BoxCornerAnnotator
 
-## BoxMaskAnnotator
+## ColorAnnotator
 
-:::supervision.annotators.core.BoxMaskAnnotator
+:::supervision.annotators.core.ColorAnnotator
 
 ## CircleAnnotator
 
@@ -330,6 +351,10 @@
 
 :::supervision.annotators.core.DotAnnotator
 
+## TriangleAnnotator
+
+:::supervision.annotators.core.TriangleAnnotator
+
 ## EllipseAnnotator
 
 :::supervision.annotators.core.EllipseAnnotator

docs/changelog.md

@@ -1,3 +1,56 @@
+### 0.17.0 <small>December 06, 2023</small>
+
+- Added [#633](https://github.com/roboflow/supervision/pull/633): [`sv.PixelateAnnotator`](https://supervision.roboflow.com/annotators/#supervision.annotators.core.PixelateAnnotator) allowing to pixelate objects on images and videos.
+
+- Added [#652](https://github.com/roboflow/supervision/pull/652): [`sv.TriangleAnnotator`](https://supervision.roboflow.com/annotators/#supervision.annotators.core.TriangleAnnotator) allowing to annotate images and videos with triangle markers.
+
+- Added [#602](https://github.com/roboflow/supervision/pull/602): [`sv.PolygonAnnotator`](https://supervision.roboflow.com/annotators/#supervision.annotators.core.PolygonAnnotator) allowing to annotate images and videos with segmentation mask outline.
+
+```python
+>>> import supervision as sv
+
+>>> image = ...
+>>> detections = sv.Detections(...)
+
+>>> polygon_annotator = sv.PolygonAnnotator()
+>>> annotated_frame = polygon_annotator.annotate(
+...     scene=image.copy(),
+...     detections=detections
+... )
+```
+
+- Added [#476](https://github.com/roboflow/supervision/pull/476): [`sv.assets`](https://supervision.roboflow.com/assets/) allowing download of video files that you can use in your demos.
+
+```python
+>>> from supervision.assets import download_assets, VideoAssets
+>>> download_assets(VideoAssets.VEHICLES)
+"vehicles.mp4"
+```
+
+- Added [#605](https://github.com/roboflow/supervision/pull/605): [`Position.CENTER_OF_MASS`](https://supervision.roboflow.com/geometry/core/#position) allowing to place labels in center of mass of segmentation masks.
+
+- Added [#651](https://github.com/roboflow/supervision/pull/651): [`sv.scale_boxes`](https://supervision.roboflow.com/detection/utils/#supervision.detection.utils.scale_boxes) allowing to scale [`sv.Detections.xyxy`](https://supervision.roboflow.com/detection/core/#supervision.detection.core.Detections) values.
+
+- Added [#637](https://github.com/roboflow/supervision/pull/637): [`sv.calculate_dynamic_text_scale`](https://supervision.roboflow.com/draw/utils/#supervision.draw.utils.calculate_dynamic_text_scale) and [`sv.calculate_dynamic_line_thickness`](https://supervision.roboflow.com/draw/utils/#supervision.draw.utils.calculate_dynamic_line_thickness) allowing text scale and line thickness to match image resolution.
+
+- Added [#620](https://github.com/roboflow/supervision/pull/620): [`sv.Color.as_hex`](https://supervision.roboflow.com/draw/color/#supervision.draw.color.Color.as_hex) allowing to extract color value in HEX format.
+
+- Added [#572](https://github.com/roboflow/supervision/pull/572): [`sv.Classifications.from_timm`](https://supervision.roboflow.com/classification/core/#supervision.classification.core.Classifications.from_timm) allowing to load classification result from [timm](https://huggingface.co/docs/hub/timm) models.
+
+- Added [#478](https://github.com/roboflow/supervision/pull/478): [`sv.Classifications.from_clip`](https://supervision.roboflow.com/classification/core/#supervision.classification.core.Classifications.from_clip) allowing to load classification result from [clip](https://github.com/openai/clip) model.
+
+- Added [#571](https://github.com/roboflow/supervision/pull/571): [`sv.Detections.from_azure_analyze_image`](https://supervision.roboflow.com/detection/core/#supervision.detection.core.Detections.from_azure_analyze_image) allowing to load detection results from [Azure Image Analysis](https://learn.microsoft.com/en-us/azure/ai-services/computer-vision/concept-object-detection-40).
+
+- Changed [#646](https://github.com/roboflow/supervision/pull/646): `sv.BoxMaskAnnotator` renaming it to [`sv.ColorAnnotator`](https://supervision.roboflow.com/annotators/#supervision.annotators.core.ColorAnnotator).
+
+- Changed [#606](https://github.com/roboflow/supervision/pull/606): [`sv.MaskAnnotator`](https://supervision.roboflow.com/annotators/#supervision.annotators.core.MaskAnnotator) to make it **5x faster**.
+
+- Fixed [#584](https://github.com/roboflow/supervision/pull/584): [`sv.DetectionDataset.from_yolo`](https://supervision.roboflow.com/datasets/#supervision.dataset.core.DetectionDataset.from_yolo) to ignore empty lines in annotation files.
+
+- Fixed [#555](https://github.com/roboflow/supervision/pull/555): [`sv.BlurAnnotator`](https://supervision.roboflow.com/annotators/#supervision.annotators.core.BlurAnnotator) to trim negative coordinates before bluring detections.
+
+- Fixed [#511](https://github.com/roboflow/supervision/pull/511): [`sv.TraceAnnotator`](https://supervision.roboflow.com/annotators/#supervision.annotators.core.TraceAnnotator) to respect trace position.
+
 ### 0.16.0 <small>October 19, 2023</small>
 
 - Added [#422](https://github.com/roboflow/supervision/pull/422): [`sv.BoxMaskAnnotator`](https://supervision.roboflow.com/annotators/#supervision.annotators.core.BoxMaskAnnotator) allowing to annotate images and videos with mox masks.

docs/detection/utils.md

@@ -25,3 +25,11 @@
 ## filter_polygons_by_area
 
 :::supervision.detection.utils.filter_polygons_by_area
+
+## move_boxes
+
+:::supervision.detection.utils.move_boxes
+
+## scale_boxes
+
+:::supervision.detection.utils.scale_boxes

docs/index.md

@@ -16,7 +16,7 @@ We write your reusable computer vision tools. Whether you need to load your data
 ## 💻 Install
 
 You can install `supervision` with pip in a
-[**3.11>=Python>=3.8**](https://www.python.org/) environment.
+[**Python>=3.8**](https://www.python.org/) environment.
 
 !!! example "pip install (recommended)"
 

examples/tracking/README.md

@@ -9,6 +9,16 @@ detection and Supervision for tracking and annotation.
 pip install -r requirements.txt
 ```
 
+## ⚙️ run
+
+```bash
+python script.py \
+--source_weights_path yolov8s.pt \
+--source_video_path input.mp4 \
+--target_video_path tracking_result.mp4
+```
+
+
 ## ⚙️ parameters
 
 | parameter                | required | description                                                                       |

examples/tracking/script.py

@@ -17,7 +17,7 @@ def process_video(
 
     tracker = sv.ByteTrack()
     box_annotator = sv.BoundingBoxAnnotator()
-    label_annotator = sv.LabelAnnotator(classes=model.names)
+    label_annotator = sv.LabelAnnotator()
     frame_generator = sv.get_video_frames_generator(source_path=source_video_path)
     video_info = sv.VideoInfo.from_video_path(video_path=source_video_path)
 

examples/traffic_analysis/requirements.txt

@@ -1,4 +1,4 @@
-supervision>=0.15.0rc1
+supervision
 tqdm
 ultralytics
 gdown

pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "supervision"
-version = "0.17.0rc7"
+version = "0.17.1"
 description = "A set of easy-to-use utils that will come in handy in any Computer Vision project"
 authors = ["Piotr Skalski <piotr.skalski92@gmail.com>"]
 maintainers = ["Piotr Skalski <piotr.skalski92@gmail.com>"]
@@ -10,7 +10,7 @@ packages = [{include = "supervision"}]
 homepage = "https://github.com/roboflow/supervision"
 repository = "https://github.com/roboflow/supervision"
 documentation = "https://github.com/roboflow/supervision/blob/main/README.md"
-keywords = ["machine-learning", "deep-learning", "vision", "ML", "DL", "AI", "YOLOv5", "YOLOv8", "Roboflow"]
+keywords = ["machine-learning", "deep-learning", "vision", "ML", "DL", "AI", "Roboflow"]
 
 classifiers=[
     'Development Status :: 4 - Beta',
@@ -19,10 +19,6 @@ classifiers=[
     'Intended Audience :: Science/Research',
     'License :: OSI Approved :: MIT License',
     'Programming Language :: Python :: 3',
-    'Programming Language :: Python :: 3.8',
-    'Programming Language :: Python :: 3.9',
-    'Programming Language :: Python :: 3.10',
-    'Programming Language :: Python :: 3.11',
     'Programming Language :: Python :: 3 :: Only',
     'Topic :: Software Development',
     'Topic :: Scientific/Engineering',
@@ -35,14 +31,14 @@ classifiers=[
 ]
 
 [tool.poetry.dependencies]
-python = ">=3.8,<3.12.0"
-numpy = ">=1.24.0,>=1.26.1"
-matplotlib = ">=3.5.0,>=3.8.1"
-pyyaml = ">=5.3,<=6.0.1"
-pillow = ">=9.4,<=10.1.0"
+python = "^3.8"
+numpy = ">=1.21.2"
+scipy =  ">=1.9.0"
+matplotlib = ">=3.5.0"
+pyyaml = ">=5.3"
+pillow = ">=9.4"
 opencv-python = { version = ">=4.5.5.64,<=4.8.1.78", optional = true }
 opencv-python-headless = ">=4.5.5.64,<=4.8.1.78"
-scipy = ">=1.9.0,<=2.0.0"
 requests = { version = ">=2.26.0,<=2.31.0", optional = true }
 tqdm = { version = ">=4.62.3,<=4.66.1", optional = true }
 
@@ -54,15 +50,15 @@ assets = ["requests","tqdm"]
 [tool.poetry.group.dev.dependencies]
 twine = "^4.0.2"
 pytest = "^7.2.2"
-wheel = ">=0.40,<0.42"
+wheel = ">=0.40,<0.43"
 notebook = ">=6.5.3,<8.0.0"
 build = ">=0.10,<1.1"
-ruff = ">=0.0.280,<0.1.7"
+ruff = ">=0.0.280,<0.1.8"
 isort = "^5.12.0"
 black = "^23.7.0"
 mypy = "^1.4.1"
 pre-commit = "^3.3.3"
-flake8 = { version = "*", python = ">=3.8.1,<3.12.0" }
+flake8 = { version = "*", python = ">=3.8.1" }
 
 
 [tool.poetry.group.docs.dependencies]

supervision/__init__.py

@@ -10,8 +10,8 @@ from supervision.annotators.core import (
     BlurAnnotator,
     BoundingBoxAnnotator,
     BoxCornerAnnotator,
-    BoxMaskAnnotator,
     CircleAnnotator,
+    ColorAnnotator,
     DotAnnotator,
     EllipseAnnotator,
     HaloAnnotator,
@@ -21,6 +21,7 @@ from supervision.annotators.core import (
     PixelateAnnotator,
     PolygonAnnotator,
     TraceAnnotator,
+    TriangleAnnotator,
 )
 from supervision.annotators.utils import ColorLookup
 from supervision.classification.core import Classifications
@@ -40,9 +41,11 @@ from supervision.detection.utils import (
     filter_polygons_by_area,
     mask_to_polygons,
     mask_to_xyxy,
+    move_boxes,
     non_max_suppression,
     polygon_to_mask,
     polygon_to_xyxy,
+    scale_boxes,
 )
 from supervision.draw.color import Color, ColorPalette
 from supervision.draw.utils import (

supervision/annotators/core.py

@@ -260,7 +260,7 @@ class PolygonAnnotator(BaseAnnotator):
         return scene
 
 
-class BoxMaskAnnotator(BaseAnnotator):
+class ColorAnnotator(BaseAnnotator):
     """
     A class for drawing box masks on an image using provided detections.
     """
@@ -308,8 +308,8 @@ class BoxMaskAnnotator(BaseAnnotator):
             >>> image = ...
             >>> detections = sv.Detections(...)
 
-            >>> box_mask_annotator = sv.BoxMaskAnnotator()
-            >>> annotated_frame = box_mask_annotator.annotate(
+            >>> color_annotator = sv.ColorAnnotator()
+            >>> annotated_frame = color_annotator.annotate(
             ...     scene=image.copy(),
             ...     detections=detections
             ... )
@@ -1030,8 +1030,7 @@ class TraceAnnotator:
                 Options are `INDEX`, `CLASS`, `TRACK`.
         """
         self.color: Union[Color, ColorPalette] = color
-        self.position = position
-        self.trace = Trace(max_size=trace_length)
+        self.trace = Trace(max_size=trace_length, anchor=position)
         self.thickness = thickness
         self.color_lookup: ColorLookup = color_lookup
 
@@ -1263,3 +1262,93 @@ class PixelateAnnotator(BaseAnnotator):
             scene[y1:y2, x1:x2] = scaled_down_roi
 
         return scene
+
+
+class TriangleAnnotator(BaseAnnotator):
+    """
+    A class for drawing triangle markers on an image at specific coordinates based on
+    provided detections.
+    """
+
+    def __init__(
+        self,
+        color: Union[Color, ColorPalette] = ColorPalette.default(),
+        base: int = 10,
+        height: int = 10,
+        position: Position = Position.TOP_CENTER,
+        color_lookup: ColorLookup = ColorLookup.CLASS,
+    ):
+        """
+        Args:
+            color (Union[Color, ColorPalette]): The color or color palette to use for
+                annotating detections.
+            base (int): The base width of the triangle.
+            height (int): The height of the triangle.
+            position (Position): The anchor position for placing the triangle.
+            color_lookup (ColorLookup): Strategy for mapping colors to annotations.
+                Options are `INDEX`, `CLASS`, `TRACK`.
+        """
+        self.color: Union[Color, ColorPalette] = color
+        self.base: int = base
+        self.height: int = height
+        self.position: Position = position
+        self.color_lookup: ColorLookup = color_lookup
+
+    def annotate(
+        self,
+        scene: np.ndarray,
+        detections: Detections,
+        custom_color_lookup: Optional[np.ndarray] = None,
+    ) -> np.ndarray:
+        """
+        Annotates the given scene with triangles based on the provided detections.
+
+        Args:
+            scene (np.ndarray): The image where triangles will be drawn.
+            detections (Detections): Object detections to annotate.
+            custom_color_lookup (Optional[np.ndarray]): Custom color lookup array.
+                Allows to override the default color mapping strategy.
+
+        Returns:
+            np.ndarray: The annotated image.
+
+        Example:
+            ```python
+            >>> import supervision as sv
+
+            >>> image = ...
+            >>> detections = sv.Detections(...)
+
+            >>> triangle_annotator = sv.TriangleAnnotator()
+            >>> annotated_frame = triangle_annotator.annotate(
+            ...     scene=image.copy(),
+            ...     detections=detections
+            ... )
+            ```
+
+        ![triangle-annotator-example](https://media.roboflow.com/
+        supervision-annotator-examples/triangle-annotator-example.png)
+        """
+        xy = detections.get_anchors_coordinates(anchor=self.position)
+        for detection_idx in range(len(detections)):
+            color = resolve_color(
+                color=self.color,
+                detections=detections,
+                detection_idx=detection_idx,
+                color_lookup=self.color_lookup
+                if custom_color_lookup is None
+                else custom_color_lookup,
+            )
+            tip_x, tip_y = int(xy[detection_idx, 0]), int(xy[detection_idx, 1])
+            vertices = np.array(
+                [
+                    [tip_x - self.base // 2, tip_y - self.height],
+                    [tip_x + self.base // 2, tip_y - self.height],
+                    [tip_x, tip_y],
+                ],
+                np.int32,
+            )
+
+            cv2.fillPoly(scene, [vertices], color.as_bgr())
+
+        return scene

supervision/detection/core.py

@@ -1,7 +1,7 @@
 from __future__ import annotations
 
 from dataclasses import astuple, dataclass
-from typing import Any, Iterator, List, Optional, Tuple, Union
+from typing import Any, Dict, Iterator, List, Optional, Tuple, Union
 
 import numpy as np
 
@@ -64,6 +64,7 @@ def _validate_tracker_id(tracker_id: Any, n: int) -> None:
 class Detections:
     """
     Data class containing information about the detections in a video frame.
+
     Attributes:
         xyxy (np.ndarray): An array of shape `(n, 4)` containing
             the bounding boxes coordinates in format `[x1, y1, x2, y2]`
@@ -461,7 +462,7 @@ class Detections:
             >>> 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)
@@ -484,6 +485,93 @@ class Detections:
         xyxy = xywh_to_xyxy(boxes_xywh=xywh)
         return cls(xyxy=xyxy, mask=mask)
 
+    @classmethod
+    def from_azure_analyze_image(
+        cls, azure_result: dict, class_map: Optional[Dict[int, str]] = None
+    ) -> Detections:
+        """
+        Creates a Detections instance from [Azure Image Analysis 4.0](
+        https://learn.microsoft.com/en-us/azure/ai-services/computer-vision/
+        concept-object-detection-40).
+
+        Args:
+            azure_result (dict): The result from Azure Image Analysis. It should
+                contain detected objects and their bounding box coordinates.
+            class_map (Optional[Dict[int, str]]): A mapping ofclass IDs (int) to class
+                names (str). If None, a new mapping is created dynamically.
+
+        Returns:
+            Detections: A new Detections object.
+
+        Example:
+            ```python
+            >>> import requests
+            >>> import supervision as sv
+
+            >>> image = open(input, "rb").read()
+
+            >>> endpoint = "https://.cognitiveservices.azure.com/"
+            >>> subscription_key = "..."
+
+            >>> headers = {
+            ...    "Content-Type": "application/octet-stream",
+            ...    "Ocp-Apim-Subscription-Key": subscription_key
+            ... }
+
+            >>> response = requests.post(endpoint,
+            ...     headers=self.headers,
+            ...     data=image
+            ... ).json()
+
+            >>> detections = sv.Detections.from_azure_analyze_image(response)
+            ```
+        """
+        if "error" in azure_result:
+            raise ValueError(
+                f'Azure API returned an error {azure_result["error"]["message"]}'
+            )
+
+        xyxy, confidences, class_ids = [], [], []
+
+        is_dynamic_mapping = class_map is None
+        if is_dynamic_mapping:
+            class_map = {}
+
+        class_map = {value: key for key, value in class_map.items()}
+
+        for detection in azure_result["objectsResult"]["values"]:
+            bbox = detection["boundingBox"]
+
+            tags = detection["tags"]
+
+            x0 = bbox["x"]
+            y0 = bbox["y"]
+            x1 = x0 + bbox["w"]
+            y1 = y0 + bbox["h"]
+
+            for tag in tags:
+                confidence = tag["confidence"]
+                class_name = tag["name"]
+                class_id = class_map.get(class_name, None)
+
+                if is_dynamic_mapping and class_id is None:
+                    class_id = len(class_map)
+                    class_map[class_name] = class_id
+
+                if class_id is not None:
+                    xyxy.append([x0, y0, x1, y1])
+                    confidences.append(confidence)
+                    class_ids.append(class_id)
+
+        if len(xyxy) == 0:
+            return Detections.empty()
+
+        return cls(
+            xyxy=np.array(xyxy),
+            class_id=np.array(class_ids),
+            confidence=np.array(confidences),
+        )
+
     @classmethod
     def from_paddledet(cls, paddledet_result) -> Detections:
         """

supervision/detection/utils.py

@@ -383,18 +383,65 @@ def process_roboflow_result(
 
 def move_boxes(xyxy: np.ndarray, offset: np.ndarray) -> np.ndarray:
     """
-    Args:
+    Parameters:
         xyxy (np.ndarray): 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:
-        (np.ndarray) repositioned bounding boxes
+        np.ndarray: Repositioned bounding boxes.
+
+    Example:
+        ```python
+        >>> import numpy as np
+        >>> import supervision as sv
+
+        >>> boxes = np.array([[10, 10, 20, 20], [30, 30, 40, 40]])
+        >>> offset = np.array([5, 5])
+        >>> sv.move_boxes(boxes, offset)
+        ... array([
+        ...     [15, 15, 25, 25],
+        ...     [35, 35, 45, 45]
+        ... ])
+        ```
     """
     return xyxy + np.hstack([offset, offset])
 
 
+def scale_boxes(xyxy: np.ndarray, factor: float) -> np.ndarray:
+    """
+    Scale the dimensions of bounding boxes.
+
+    Parameters:
+        xyxy (np.ndarray): 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:
+        np.ndarray: Scaled bounding boxes.
+
+    Example:
+        ```python
+        >>> import numpy as np
+        >>> import supervision as sv
+
+        >>> boxes = np.array([[10, 10, 20, 20], [30, 30, 40, 40]])
+        >>> factor = 1.5
+        >>> sv.scale_boxes(boxes, factor)
+        ... 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 calculate_masks_centroids(masks: np.ndarray) -> np.ndarray:
     """
     Calculate the centroids of binary masks in a tensor.

test/detection/test_utils.py

@@ -11,6 +11,7 @@ from supervision.detection.utils import (
     move_boxes,
     non_max_suppression,
     process_roboflow_result,
+    scale_boxes,
 )
 
 TEST_MASK = np.zeros((1, 1000, 1000), dtype=bool)
@@ -504,6 +505,52 @@ def test_move_boxes(
         assert np.array_equal(result, expected_result)
 
 
+@pytest.mark.parametrize(
+    "xyxy, factor, expected_result, exception",
+    [
+        (
+            np.empty(shape=(0, 4)),
+            2.0,
+            np.empty(shape=(0, 4)),
+            DoesNotRaise(),
+        ),  # empty xyxy array
+        (
+            np.array([[0, 0, 10, 10]]),
+            1.0,
+            np.array([[0, 0, 10, 10]]),
+            DoesNotRaise(),
+        ),  # single box with factor equal to 1.0
+        (
+            np.array([[0, 0, 10, 10]]),
+            2.0,
+            np.array([[-5, -5, 15, 15]]),
+            DoesNotRaise(),
+        ),  # single box with factor equal to 2.0
+        (
+            np.array([[0, 0, 10, 10]]),
+            0.5,
+            np.array([[2.5, 2.5, 7.5, 7.5]]),
+            DoesNotRaise(),
+        ),  # single box with factor equal to 0.5
+        (
+            np.array([[0, 0, 10, 10], [10, 10, 30, 30]]),
+            2.0,
+            np.array([[-5, -5, 15, 15], [0, 0, 40, 40]]),
+            DoesNotRaise(),
+        ),  # two boxes with factor equal to 2.0
+    ],
+)
+def test_scale_boxes(
+    xyxy: np.ndarray,
+    factor: float,
+    expected_result: np.ndarray,
+    exception: Exception,
+) -> None:
+    with exception:
+        result = scale_boxes(xyxy=xyxy, factor=factor)
+        assert np.array_equal(result, expected_result)
+
+
 @pytest.mark.parametrize(
     "masks, expected_result, exception",
     [