Merge pull request #1742 from roboflow/develop

`supervision-0.26.0` release

docs/changelog.md

@@ -1,5 +1,180 @@
 # Changelog
 
+### 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.
+
+- Fix [#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
+    ```
+
+- Fix [#1767](https://github.com/roboflow/supervision/pull/1767): Fixed losing `sv.Detections.data` when detections filtering.
+
 ### 0.25.0 <small>Nov 12, 2024</small>
 
 - No removals or deprecations in this release!

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

@@ -28,28 +28,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/keypoint/core.md

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

pyproject.toml

@@ -2,7 +2,7 @@
 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.0rc8"
+version = "0.26.0"
 readme = "README.md"
 requires-python = ">=3.9"
 authors = [

supervision/detection/core.py

@@ -867,6 +867,53 @@ class Detections:
             ```
 
         !!! example "Qwen2.5-VL"
+
+            ??? tip "Prompt engineering"
+
+                To get the best results from Qwen2.5-VL, use clear and descriptive prompts
+                that specify exactly what you want to detect.
+
+                **For general object detection, use this comprehensive prompt:**
+
+                ```
+                Detect all objects in the image and return their locations and labels.
+                ```
+
+                **For specific object detection with detailed descriptions:**
+
+                ```
+                Detect the red object that is leading in this image and return its location and label.
+                ```
+
+                **For simple, targeted detection:**
+
+                ```
+                leading blue truck
+                ```
+
+                **Additional effective prompts:**
+
+                ```
+                Find all people and vehicles in this scene
+                ```
+
+                ```
+                Locate all animals in the image
+                ```
+
+                ```
+                Identify traffic signs and their positions
+                ```
+
+                **Tips for better results:**
+
+                - Use descriptive language that clearly specifies what to look for
+                - Include color, size, or position descriptors when targeting specific objects
+                - Be specific about the type of objects you want to detect
+                - The model responds well to both detailed instructions and concise phrases
+                - Results are returned in JSON format with `bbox_2d` coordinates and `label` fields
+
+
             ```python
             import supervision as sv
 
@@ -1023,6 +1070,23 @@ class Detections:
             ```
 
         !!! example "Moondream"
+
+
+            ??? tip "Prompt engineering"
+
+                To get the best results from Moondream, use optimized prompts that leverage
+                its object detection capabilities effectively.
+
+                **For general object detection, use this simple prompt:**
+
+                ```
+                objects
+                ```
+
+                This single-word prompt instructs Moondream to detect all visible objects
+                and return them in the proper JSON format with normalized coordinates.
+
+
             ```python
             import supervision as sv
 
@@ -1137,6 +1201,53 @@ class Detections:
             ```
 
         !!! example "Qwen2.5-VL"
+
+            ??? tip "Prompt engineering"
+
+                To get the best results from Qwen2.5-VL, use clear and descriptive prompts
+                that specify exactly what you want to detect.
+
+                **For general object detection, use this comprehensive prompt:**
+
+                ```
+                Detect all objects in the image and return their locations and labels.
+                ```
+
+                **For specific object detection with detailed descriptions:**
+
+                ```
+                Detect the red object that is leading in this image and return its location and label.
+                ```
+
+                **For simple, targeted detection:**
+
+                ```
+                leading blue truck
+                ```
+
+                **Additional effective prompts:**
+
+                ```
+                Find all people and vehicles in this scene
+                ```
+
+                ```
+                Locate all animals in the image
+                ```
+
+                ```
+                Identify traffic signs and their positions
+                ```
+
+                **Tips for better results:**
+
+                - Use descriptive language that clearly specifies what to look for
+                - Include color, size, or position descriptors when targeting specific objects
+                - Be specific about the type of objects you want to detect
+                - The model responds well to both detailed instructions and concise phrases
+                - Results are returned in JSON format with `bbox_2d` coordinates and `label` fields
+
+
             ```python
             import supervision as sv
 
@@ -1293,6 +1404,23 @@ class Detections:
             ```
 
         !!! example "Moondream"
+
+
+            ??? tip "Prompt engineering"
+
+                To get the best results from Moondream, use optimized prompts that leverage
+                its object detection capabilities effectively.
+
+                **For general object detection, use this simple prompt:**
+
+                ```
+                objects
+                ```
+
+                This single-word prompt instructs Moondream to detect all visible objects
+                and return them in the proper JSON format with normalized coordinates.
+
+
             ```python
             import supervision as sv