0.26.0

> [!WARNING]  
> `supervision-0.26.0` drops `python3.8` support and upgrade all codes to `python3.9` syntax style.

> [!TIP]
> Our [docs page](https://supervision.roboflow.com/) 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

- Added 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). ([#1788](https://github.com/roboflow/supervision/pull/1788))

    https://github.com/user-attachments/assets/f1917032-29d8-4b88-b871-65c2e28a756e

- Added 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). ([#1774](https://github.com/roboflow/supervision/pull/1774))

    ```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 [`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. ([#1874](https://github.com/roboflow/supervision/pull/1874))

- Added 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). ([#1816](https://github.com/roboflow/supervision/pull/1816))

- Added [`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`. ([#1823](https://github.com/roboflow/supervision/pull/1823))

- Added [`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. ([#1788](https://github.com/roboflow/supervision/pull/1788))

## 🌱 Changed

- [`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. ([#1820](https://github.com/roboflow/supervision/pull/1820))

    https://github.com/user-attachments/assets/361c17c7-0810-466d-907d-c752e91bc6f7

    <img width="1600" height="1400" alt="Snap (25)" src="https://github.com/user-attachments/assets/7945dafc-e646-46e5-ae62-492685d1bbc0" />

- [`sv.LabelAnnotator`](https://supervision.roboflow.com/0.26.0/detection/annotators/#supervision.annotators.core.LabelAnnotator) now supports non-string labels. ([#1825](https://github.com/roboflow/supervision/pull/1825))

- [`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). You can test Gemini prompting, result parsing, and visualization with Supervision using [this example notebook](https://colab.research.google.com/github/roboflow-ai/notebooks/blob/main/notebooks/zero-shot-object-detection-and-segmentation-with-google-gamini-2-5.ipynb). ([#1792](https://github.com/roboflow/supervision/pull/1792))

   ```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])
    ```
    
<img width="2200" height="1500" alt="Snap (27)" src="https://github.com/user-attachments/assets/b53c6670-49f7-49b0-99e5-90a1e8bf78f2" />

- [`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). ([#1878](https://github.com/roboflow/supervision/pull/1878))

    ```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]])
    ```

- [`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). You can test Qwen2.5-VL prompting, result parsing, and visualization with Supervision using [this example notebook](https://colab.research.google.com/github/roboflow-ai/notebooks/blob/main/notebooks/zero-shot-object-detection-with-qwen2-5-vl.ipynb). ([#1709](https://github.com/roboflow/supervision/pull/1790))

    ```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])
    ```

- 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. ([#1786](https://github.com/roboflow/supervision/pull/1786))

## 🔧 Fixed

- 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. ([#1834](https://github.com/roboflow/supervision/pull/1834))

    ```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
    ```

> [!TIP]
> The updated mAP implementation enabled us to build an updated version of the [Computer Vision Model Leaderboard](https://leaderboard.roboflow.com/).

<img width="1492" height="1014" alt="imageedit_1_8427510007" src="https://github.com/user-attachments/assets/1f46b877-abbc-486b-b8f9-2829f43716e1" />


- Fix [#1767](https://github.com/roboflow/supervision/pull/1767): Fixed losing `sv.Detections.data` when detections filtering.

## ⚠️ Deprecated

- `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

- 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. 
- Cconstructing `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).

## 🏆 Contributors

@onuralpszr ([Onuralp SEZER](https://www.linkedin.com/in/osezer/)), @SkalskiP ([Piotr Skalski](https://www.linkedin.com/in/skalskip92/)), @SunHao-AI ([Hao Sun](https://github.com/SunHao-AI)), @rafaelpadilla [Rafael Padilla](https://www.linkedin.com/in/rafael-padilla/), @Ashp116 ([Ashp116](https://github.com/Ashp116)), @capjamesg ([James Gallagher](https://www.linkedin.com/in/jg12927/)), @blakeburch ([Blake Burch](https://www.linkedin.com/in/blakeburch/)), @hidara2000 ([hidara2000](https://github.com/hidara2000)), @Armaggheddon ([Alessandro Brunello](https://www.linkedin.com/in/brunelloalessandro/)), @soumik12345 ([Soumik Rakshit](https://www.linkedin.com/in/soumikrakshit/)).