github roboflow/supervision 0.32.0
supervision-0.32.0

51 minutes ago

v0.32.0: Zone counting, dwell time and semantic segmentation

πŸ“‹ Summary

supervision now counts objects entering and leaving a zone, times how long each one stays, and loads semantic segmentation results.

  • PolygonZone counts entries and exits per class and reports dwell time for every tracked object.
  • Detections.from_semantic_segmentation turns a class map into one masked detection per class; Ultralytics and Inference results load too.
  • KeyPointsDataset reads and writes YOLO pose datasets.
  • box_weighted_box_fusion merges overlapping boxes from several models instead of throwing most of them away.
  • VertexAnnotator and its siblings take a color palette and can color each joint by its index.

Most projects can upgrade as is, but the public validate_* helpers, merge_inner_* and KeyPoints.confidence are gone and a few edge cases changed, so check the Migration guide.

✨ Spotlights / highlights

Zones that count entries, exits and dwell time

sv.PolygonZone now follows each tracker_id across frames. It counts objects entering and leaving (in_count, out_count and the per-class versions are named the same as on sv.LineZone), reports the current count per class, and measures how long each tracked object has been inside with time_in_zone. Pass a timestamp to trigger for seconds, or leave it out for frames. occupancy_ratio reports how much of the zone the detections cover, and sv.PolygonZoneAnnotator and sv.LineZoneAnnotator accept a coord_transform to draw at camera-mapped positions. (#2770, #1667, #2760)

01-zones-entries-exits-dwell.mp4
import numpy as np
import supervision as sv

zone = sv.PolygonZone(polygon=np.array([[0, 0], [100, 0], [100, 100], [0, 100]]))

# A car drives in from the left, stays a while, then leaves on the right.
for frame, cx in enumerate([-10, 30, 50, 70, 90, 130]):
    car = sv.Detections(
        xyxy=np.array([[cx - 10, 40.0, cx + 10, 60.0]]),
        tracker_id=np.array([1]),
        class_id=np.array([0]),
    )
    zone.trigger(car, timestamp=frame * 0.5)
    if frame == 4:
        zone.time_in_zone(car)  # array([1.5]) seconds inside so far

zone.in_count, zone.out_count  # (1, 1)
zone.in_count_per_class  # {0: 1}

Semantic segmentation maps load into Detections

sv.Detections.from_semantic_segmentation converts a class map, a base64 PNG or an integer array, into one detection per class with a mask of all its pixels and its class name. The background id 0 is dropped unless you pass background_id=None. from_inference now routes Roboflow Inference semantic results, such as RF-DETR semantic models, through it, and from_ultralytics loads Ultralytics task="semantic" results that used to come back empty. (#2898, #2915)

A house photo next to its semantic segmentation result, one labelled mask per class

import numpy as np
import supervision as sv

class_map = np.zeros((6, 8), dtype=np.int64)
class_map[2:, :4] = 1  # road
class_map[:3, 5:] = 2  # sky

detections = sv.Detections.from_semantic_segmentation(
    class_map, class_map={1: "road", 2: "sky"}
)
detections.data["class_name"]  # array(['road', 'sky'], dtype='<U4')
detections.mask.shape  # (2, 6, 8)

YOLO pose datasets as sv.KeyPointsDataset

Load, split, merge and write YOLO pose datasets. Images load lazily, the dataset supports indexing, and for labels with three values per point (x, y, visibility), the raw visibility stays under data["keypoint_visibility"]. (#2745)

import numpy as np
import supervision as sv

key_points = sv.KeyPoints(
    xy=np.array([[[20, 20], [50, 30], [40, 80]]], dtype=np.float32),
    class_id=np.array([0]),
)
dataset = sv.KeyPointsDataset(
    classes=["person"],
    images=["images/a.jpg"],
    annotations={"images/a.jpg": key_points},
    keypoint_count=3,
    value_dim=2,
)
dataset.as_yolo(
    images_directory_path="out/images",
    annotations_directory_path="out/labels",
    data_yaml_path="out/data.yaml",
)
restored = sv.KeyPointsDataset.from_yolo("out/images", "out/labels", "out/data.yaml")

Weighted Box Fusion for ensembles

Where NMS keeps the best box of an overlapping group, sv.box_weighted_box_fusion replaces the group with one box whose coordinates are the confidence-weighted average. The fused score is the group's mean confidence, so revisit any confidence filter tuned for NMS. (#2455)

Boxes from three models, NMS result and weighted box fusion result on the same photo

import numpy as np
import supervision as sv

# Columns: x1, y1, x2, y2, confidence, class_id.
predictions = np.array(
    [
        [10, 10, 50, 50, 0.9, 0],
        [12, 11, 52, 50, 0.6, 0],
        [100, 100, 140, 140, 0.8, 1],
    ],
    dtype=float,
)
sv.box_weighted_box_fusion(predictions, iou_threshold=0.5)
# array([[100. , 100. , 140. , 140. ,   0.8,   1. ],
#        [ 10.8,  10.4,  50.8,  50. ,   0.75,  0. ]])

Key point annotators with color palettes

sv.VertexAnnotator, sv.EdgeAnnotator and sv.VertexLabelAnnotator accept a sv.ColorPalette and a color_lookup. The new sv.ColorLookup.KEYPOINT colors each point by its index in the skeleton, so a joint keeps its color across people. sv.ColorLookup.TRACK isn't supported for key points and is rejected. (#2343)

The same skeletons drawn with one color and with one color per joint

import numpy as np
import supervision as sv

scene = np.zeros((100, 100, 3), dtype=np.uint8)
key_points = sv.KeyPoints(
    xy=np.array([[[20, 20], [50, 30], [40, 80]]], dtype=np.float32),
    class_id=np.array([0]),
)
annotator = sv.VertexAnnotator(
    color=sv.ColorPalette.DEFAULT, color_lookup=sv.ColorLookup.KEYPOINT
)
annotated = annotator.annotate(scene.copy(), key_points)

πŸ”„ Migration guide

No breaking changes. Every API removed in 0.32.0 was deprecated in 0.29.0 and scheduled for removal, and warned on use since, so code that runs warning-free on 0.31 needs no change. If you still use one:

sv.KeyPoints.confidence: pass and read keypoint_confidence instead.

# before
key_points = sv.KeyPoints(xy=xy, confidence=scores)
scores = key_points.confidence

# after
key_points = sv.KeyPoints(xy=xy, keypoint_confidence=scores)
scores = key_points.keypoint_confidence

Public validate_* helpers (in supervision.validators, supervision.annotators.utils, supervision.detection.core, supervision.detection.vlm and supervision.metrics.detection, plus sv.PercentageBarAnnotator.validate_custom_values) have no public replacement. sv.Detections and sv.KeyPoints validate their own fields on construction.

# before
from supervision.validators import validate_xyxy

validate_xyxy(xyxy)

# after: constructing the object validates it and raises ValueError on bad input
detections = sv.Detections(xyxy=xyxy)

merge_inner_detection_object_pair, merge_inner_detections_objects and merge_inner_detections_objects_without_iou: merge the detections and run with_nmm across classes. It needs confidence, which the old helpers did not. To fuse boxes from several models, use sv.box_weighted_box_fusion.

# before
from supervision.detection.core import merge_inner_detections_objects

merged = merge_inner_detections_objects(single_object_detections, threshold=0.5)

# after
merged = sv.Detections.merge(single_object_detections).with_nmm(
    threshold=0.5, class_agnostic=True
)

Two edge-case behaviours also changed: sv.JSONSink raises on extra data that reuses a built-in detection field name, and sv.xyxy_to_xywh returns int64 for integer input.

Three new deprecations will be removed in 0.35.0 at the earliest: a list[sv.Color] passed to sv.VertexLabelAnnotator (pass a sv.ColorPalette with color_lookup=sv.ColorLookup.KEYPOINT to keep one color per key point), resolve_color, resolve_color_idx and get_color_by_index (use a palette with color_lookup), and the default mask_rasterizer in sv.DetectionDataset.from_coco. Two re-exported import paths also warn until then: load_coco_annotations from supervision.dataset.core and get_detection_size_category from supervision.metrics.mean_average_recall; import them from supervision.dataset.formats.coco and supervision.metrics.utils.object_size.

πŸ“ Notable changes

πŸš€ Added

  • Zone entry and exit counts β€” sv.PolygonZone counts tracked objects entering and leaving, with per-class counts, current_count_per_class, reset(), and the new minimum_crossing_threshold and max_absent_frames options that smooth over boundary flicker and short occlusions. (#2770)
  • Zone dwell time β€” sv.PolygonZone.time_in_zone reports seconds or frames inside per tracked object, and trigger takes an optional timestamp. (#2770)
  • Zone occupancy β€” sv.PolygonZone.occupancy_ratio returns the fraction of the zone covered by masks, oriented boxes or boxes. (#1667)
  • Camera-mapped zone drawing β€” sv.PolygonZoneAnnotator.annotate and sv.LineZoneAnnotator.annotate accept coord_transform. (#2760)
  • Semantic segmentation β€” sv.Detections.from_semantic_segmentation, from_inference for Inference semantic results, and from_ultralytics for task="semantic" results. (#2898, #2915)
  • YOLO pose datasets β€” sv.KeyPointsDataset with lazy loading, split, merge, from_yolo and as_yolo. (#2745)
  • Weighted Box Fusion β€” sv.box_weighted_box_fusion. (#2455)
  • Class remapping β€” sv.Detections.remap_classes renames, filters and re-indexes classes against a target list. (#1846, #2986)
  • Compact YOLO masks β€” sv.DetectionDataset.from_yolo(..., compact_masks=True) keeps segmentation masks as sv.CompactMask. (#2834)
  • COCO mask rasterizer β€” sv.DetectionDataset.from_coco(..., mask_rasterizer=...) and the new supervision[coco] extra for pycocotools. (#2714)
  • Key point annotator palettes β€” sv.ColorPalette and color_lookup support, including sv.ColorLookup.KEYPOINT. (#2343)
  • Example video output β€” the time_in_zone Ultralytics file example saves the annotated video with --output_video_path. (#1964)

🌱 Changed

  • The time_in_zone examples now use sv.PolygonZone.time_in_zone instead of their own timers, so dwell restarts when an object leaves and returns. (#2770)
  • Dataset merging builds a class-name lookup per dataset instead of rescanning the merged list. (#3017)
  • sv.CompactMask.area sums runs in chunked NumPy reductions with int64 accumulation, 3–9Γ— faster in benchmarks for 100–500 masks. (#2744)

πŸ—‘οΈ Deprecated

  • Passing a list[sv.Color] as color or text_color to sv.VertexLabelAnnotator is deprecated; pass a single sv.Color, or a sv.ColorPalette with color_lookup=sv.ColorLookup.KEYPOINT to keep one color per key point. Removed in 0.35.0. (#2343)
  • resolve_color, resolve_color_idx and get_color_by_index in supervision.annotators.utils are deprecated and removed in 0.35.0. (#2343)
  • Relying on the default mask_rasterizer in sv.DetectionDataset.from_coco for files with polygon segmentation now warns; the default changes to "pycocotools" no earlier than 0.35.0. (#2714)

❌ Removed

  • The public validate_* helpers, deprecated since 0.29.0. Supervision uses private _validate_* helpers; sv.Detections and sv.KeyPoints validate on construction. (#3019)
  • merge_inner_detection_object_pair, merge_inner_detections_objects and merge_inner_detections_objects_without_iou, deprecated since 0.29.0. Use sv.Detections.merge(...).with_nmm(class_agnostic=True). (#3019)
  • sv.KeyPoints.confidence and the confidence constructor argument, deprecated since 0.29.0. Use keypoint_confidence. (#3019)

πŸ”§ Fixed

  • sv.metrics.MeanAverageRecall no longer copies masks for every size range and no longer fails on metadata that cannot be deep-copied. (#2953)
  • sv.resize_image(keep_aspect_ratio=True) and sv.letterbox_image no longer lose one pixel on the fitted axis. (#2952)
  • sv.xyxy_to_xywh no longer wraps around on large integer boxes; integer input returns int64, or float64 past the int64 range. (#2951)
  • sv.JSONSink now raises when extra data uses a built-in detection field name, instead of silently overwriting the field. (#2949)

πŸ† Contributors

  • Piotr Skalski (@SkalskiP, LinkedIn) β€” added ColorPalette and color_lookup support to the key point annotators and deprecated the loose color-resolution helpers.
  • Rahul Sangamker (@rs-03) β€” added box_weighted_box_fusion for Weighted Box Fusion.
  • Miral Amin (@aminmiral, LinkedIn) β€” added KeyPointsDataset for YOLO pose datasets with lazy loading, split, merge and export.
  • Advait Shukla (@AdvaitS) β€” added PolygonZone entry/exit counting, per-class counts and time_in_zone dwell time.
  • Archit H Barve (@AHB102) β€” added PolygonZone.occupancy_ratio.
  • Aashish Anand (@AshAnand34) β€” added Detections.remap_classes.
  • Christoph Deil (@cdeil, LinkedIn) β€” added a pycocotools mask rasterizer option and the coco extra for DetectionDataset.from_coco.
  • Wentao Tong (@tongwentao) β€” added compact mask loading to DetectionDataset.from_yolo.
  • NIKHIL (@Nikhi00718, LinkedIn) β€” loaded Ultralytics semantic segmentation results in Detections.from_ultralytics.
  • Kari Pikkarainen (@kari-pikkarainen, LinkedIn) β€” added coord_transform to the polygon and line zone annotators.
  • A Aswanth Raj (@aswanth-07, LinkedIn) β€” sped up remap_classes and dataset merging with class-name lookups.
  • Jorge Asenjo (@jorge-asenjo, LinkedIn) β€” sped up CompactMask.area with chunked reductions and overflow-safe accumulation.
  • Ahmet Mert Γ–zacar (@AhmetMert01, LinkedIn) β€” made JSONSink reject colliding field names and fixed xyxy_to_xywh integer overflow.
  • Vlad Voropaev (@voropaevv, LinkedIn) β€” fixed MeanAverageRecall mask copying and non-copyable metadata.
  • Pranjal Mishra (@pmxlr8, LinkedIn) β€” fixed one-pixel loss in resize_image and letterbox_image.
  • Mehmet Emin Aruk (@eminaruk, LinkedIn) β€” added video output saving to the time_in_zone Ultralytics example.
  • @udayraj1238 (LinkedIn) β€” improved docstrings, including the YOLO pose YAML helpers.
  • Raed (@Raed2180416) β€” pinned the SAHI cookbook install.
  • Dongze Li (@lidongze1002) β€” improved documentation.
  • Jang Byungkun (@8rulerstar, LinkedIn) β€” updated a cookbook.
  • Thibaud-Vdb (@Totara-thib, LinkedIn) β€” improved CI workflows.
  • Alex Norell (@alexnorell, LinkedIn) β€” improved CI workflows.
  • Vishnu Prasad M (@Vishnu-2345) β€” added PolygonZone per-class counting tests.
  • Jirka Borovec (@Borda, LinkedIn) β€” added semantic segmentation loading (from_semantic_segmentation, from_inference), removed the APIs deprecated since 0.29.0, and maintained docs, CI and release infrastructure.

Automated contributions: dependabot[bot] dependency updates.


Full changelog: 0.31.0...0.32.0

Don't miss a new supervision release

NewReleases is sending notifications on new releases.