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.
PolygonZonecounts entries and exits per class and reports dwell time for every tracked object.Detections.from_semantic_segmentationturns a class map into one masked detection per class; Ultralytics and Inference results load too.KeyPointsDatasetreads and writes YOLO pose datasets.box_weighted_box_fusionmerges overlapping boxes from several models instead of throwing most of them away.VertexAnnotatorand 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)
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)
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)
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_confidencePublic 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.PolygonZonecounts tracked objects entering and leaving, with per-class counts,current_count_per_class,reset(), and the newminimum_crossing_thresholdandmax_absent_framesoptions that smooth over boundary flicker and short occlusions. (#2770) - Zone dwell time β
sv.PolygonZone.time_in_zonereports seconds or frames inside per tracked object, andtriggertakes an optionaltimestamp. (#2770) - Zone occupancy β
sv.PolygonZone.occupancy_ratioreturns the fraction of the zone covered by masks, oriented boxes or boxes. (#1667) - Camera-mapped zone drawing β
sv.PolygonZoneAnnotator.annotateandsv.LineZoneAnnotator.annotateacceptcoord_transform. (#2760) - Semantic segmentation β
sv.Detections.from_semantic_segmentation,from_inferencefor Inference semantic results, andfrom_ultralyticsfortask="semantic"results. (#2898, #2915) - YOLO pose datasets β
sv.KeyPointsDatasetwith lazy loading,split,merge,from_yoloandas_yolo. (#2745) - Weighted Box Fusion β
sv.box_weighted_box_fusion. (#2455) - Class remapping β
sv.Detections.remap_classesrenames, filters and re-indexes classes against a target list. (#1846, #2986) - Compact YOLO masks β
sv.DetectionDataset.from_yolo(..., compact_masks=True)keeps segmentation masks assv.CompactMask. (#2834) - COCO mask rasterizer β
sv.DetectionDataset.from_coco(..., mask_rasterizer=...)and the newsupervision[coco]extra forpycocotools. (#2714) - Key point annotator palettes β
sv.ColorPaletteandcolor_lookupsupport, includingsv.ColorLookup.KEYPOINT. (#2343) - Example video output β the
time_in_zoneUltralytics file example saves the annotated video with--output_video_path. (#1964)
π± Changed
- The
time_in_zoneexamples now usesv.PolygonZone.time_in_zoneinstead 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.areasums runs in chunked NumPy reductions withint64accumulation, 3β9Γ faster in benchmarks for 100β500 masks. (#2744)
ποΈ Deprecated
- Passing a
list[sv.Color]ascolorortext_colortosv.VertexLabelAnnotatoris deprecated; pass a singlesv.Color, or asv.ColorPalettewithcolor_lookup=sv.ColorLookup.KEYPOINTto keep one color per key point. Removed in 0.35.0. (#2343) resolve_color,resolve_color_idxandget_color_by_indexinsupervision.annotators.utilsare deprecated and removed in 0.35.0. (#2343)- Relying on the default
mask_rasterizerinsv.DetectionDataset.from_cocofor 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.Detectionsandsv.KeyPointsvalidate on construction. (#3019) merge_inner_detection_object_pair,merge_inner_detections_objectsandmerge_inner_detections_objects_without_iou, deprecated since 0.29.0. Usesv.Detections.merge(...).with_nmm(class_agnostic=True). (#3019)sv.KeyPoints.confidenceand theconfidenceconstructor argument, deprecated since 0.29.0. Usekeypoint_confidence. (#3019)
π§ Fixed
sv.metrics.MeanAverageRecallno 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)andsv.letterbox_imageno longer lose one pixel on the fitted axis. (#2952)sv.xyxy_to_xywhno longer wraps around on large integer boxes; integer input returnsint64, orfloat64past theint64range. (#2951)sv.JSONSinknow raises when extra data uses a built-in detection field name, instead of silently overwriting the field. (#2949)
π Contributors
- Piotr Skalski (@SkalskiP, LinkedIn) β added
ColorPaletteandcolor_lookupsupport to the key point annotators and deprecated the loose color-resolution helpers. - Rahul Sangamker (@rs-03) β added
box_weighted_box_fusionfor Weighted Box Fusion. - Miral Amin (@aminmiral, LinkedIn) β added
KeyPointsDatasetfor YOLO pose datasets with lazy loading, split, merge and export. - Advait Shukla (@AdvaitS) β added
PolygonZoneentry/exit counting, per-class counts andtime_in_zonedwell time. - Archit H Barve (@AHB102) β added
PolygonZone.occupancy_ratio. - Aashish Anand (@AshAnand34) β added
Detections.remap_classes. - Christoph Deil (@cdeil, LinkedIn) β added a
pycocotoolsmask rasterizer option and thecocoextra forDetectionDataset.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_transformto the polygon and line zone annotators. - A Aswanth Raj (@aswanth-07, LinkedIn) β sped up
remap_classesand dataset merging with class-name lookups. - Jorge Asenjo (@jorge-asenjo, LinkedIn) β sped up
CompactMask.areawith chunked reductions and overflow-safe accumulation. - Ahmet Mert Γzacar (@AhmetMert01, LinkedIn) β made
JSONSinkreject colliding field names and fixedxyxy_to_xywhinteger overflow. - Vlad Voropaev (@voropaevv, LinkedIn) β fixed
MeanAverageRecallmask copying and non-copyable metadata. - Pranjal Mishra (@pmxlr8, LinkedIn) β fixed one-pixel loss in
resize_imageandletterbox_image. - Mehmet Emin Aruk (@eminaruk, LinkedIn) β added video output saving to the
time_in_zoneUltralytics 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
PolygonZoneper-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


