1# 方法 1：pip (最常用)
 2pip install supervision
 3
 4# 方法 2：uv (快)
 5uv pip install supervision
 6
 7# 方法 3：含 metrics extras (pandas)
 8pip install "supervision[metrics]"
 9
10# 方法 4：從 source 裝最新 dev 版
11pip install git+https://github.com/roboflow/supervision.git@develop

 1import supervision as sv
 2print(sv.__version__)  # 應為 0.28.0 或更新
 3
 4# 建一個假的 Detections 看 import 是否正常
 5import numpy as np
 6detections = sv.Detections(
 7    xyxy=np.array([[100, 100, 200, 200]]),
 8    confidence=np.array([0.95]),
 9    class_id=np.array([0]),
10)
11print(len(detections))  # 1

 1# YOLO 系列
 2pip install ultralytics            # YOLOv8 / v11
 3pip install rfdetr                 # Roboflow DETR
 4
 5# Transformers 系列 (DETR / OwlViT)
 6pip install transformers torch pillow
 7
 8# Roboflow Inference server (有 RF API key 的人)
 9pip install inference
10
11# Dataset 工具 (COCO / YOLO / VOC)
12pip install pycocotools

 1                  ┌───────────────────────────────┐
 2                  │      Model (you choose)       │
 3                  │  YOLO / DETR / SAM / Owl /…   │
 4                  └──────────────┬────────────────┘
 5                                 │
 6                                 ▼
 7                  ┌───────────────────────────────┐
 8                  │  sv.Detections.from_xxx(...)  │ ── 統一輸入
 9                  │  sv.Detections.from_ultralytics
10                  │  sv.Detections.from_inference
11                  │  sv.Detections.from_transformers
12                  │  sv.Detections.from_lmm        │
13                  └──────────────┬────────────────┘
14                                 ▼
15                ┌────────────────┴────────────────┐
16                ▼                                 ▼
17      ┌─────────────────┐              ┌─────────────────┐
18      │  Annotators     │              │  Tools / Logic  │
19      │  Box / Label /  │              │  PolygonZone    │
20      │  Mask / Halo /  │              │  LineZone       │
21      │  Heatmap /      │              │  InferenceSlicer│
22      │  Trace / …      │              │  Smoother       │
23      └─────────────────┘              │  CSVSink        │
24                                       └─────────────────┘
25                ▼                                 ▼
26      visualization                       business logic
27                                            (counts, etc)
28                                                 │
29                                                 ▼
30                  ┌───────────────────────────────┐
31                  │  sv.metrics (mAP / P / R)     │
32                  └───────────────────────────────┘

1class Detections:
2    xyxy: np.ndarray         # (N, 4) bounding box [x1, y1, x2, y2]
3    mask: Optional[np.ndarray]      # (N, H, W) instance masks
4    confidence: Optional[np.ndarray]  # (N,) 信心
5    class_id: Optional[np.ndarray]    # (N,) 類別 id
6    tracker_id: Optional[np.ndarray]  # (N,) 追蹤 id (跑 tracker 後才有)
7    data: Dict[str, np.ndarray]       # 任意 extra 欄位 (如 keypoints, age, gender)
8    metadata: Dict[str, Any]          # frame-level metadata

 1# Slicing
 2high_conf = detections[detections.confidence > 0.7]    # 過濾
 3person_only = detections[detections.class_id == 0]     # 類別過濾
 4detections.xyxy.shape  # (N, 4)
 5len(detections)        # N
 6
 7# Iteration（會慢，盡量避免）
 8for xyxy, mask, conf, cid, tid, data in detections:
 9    pass
10
11# 合併
12merged = sv.Detections.merge([dets_frame1, dets_frame2])

 1import cv2, supervision as sv
 2
 3image = cv2.imread("frame.jpg")
 4detections = sv.Detections.from_ultralytics(yolo.predict(image)[0])
 5
 6box_annotator = sv.BoxAnnotator(thickness=2)
 7label_annotator = sv.LabelAnnotator(text_thickness=1, text_scale=0.5)
 8trace_annotator = sv.TraceAnnotator(trace_length=30)
 9
10annotated = image.copy()
11annotated = box_annotator.annotate(annotated, detections)
12annotated = label_annotator.annotate(annotated, detections, labels=[
13    f"{cls} {conf:.2f}" for cls, conf in zip(detections.class_id, detections.confidence)
14])
15annotated = trace_annotator.annotate(annotated, detections)

 1# 載入
 2ds = sv.DetectionDataset.from_coco(images_directory_path=..., annotations_path=...)
 3ds = sv.DetectionDataset.from_yolo(images_directory_path=..., annotations_directory_path=..., data_yaml_path=...)
 4ds = sv.DetectionDataset.from_pascal_voc(images_directory_path=..., annotations_directory_path=...)
 5
 6# 切分 / 合併
 7train, test = ds.split(split_ratio=0.7)
 8ds_merged = sv.DetectionDataset.merge([ds1, ds2])
 9
10# 存成另一個格式
11ds.as_yolo(images_directory_path=..., annotations_directory_path=..., data_yaml_path=...)
12ds.as_coco(images_directory_path=..., annotations_path=...)
13ds.as_pascal_voc(images_directory_path=..., annotations_directory_path=...)

 1from supervision.metrics import MeanAveragePrecision, MetricTarget
 2
 3predictions = [...]  # list of sv.Detections, one per image
 4targets = [...]      # list of sv.Detections (ground truth)
 5
 6map_metric = MeanAveragePrecision()
 7result = map_metric.update(predictions, targets).compute()
 8print(result.map50_95)  # COCO-style mAP @[0.5:0.95]
 9print(result.map50)     # mAP @ 0.5
10print(result.map75)     # mAP @ 0.75
11
12# Confusion Matrix
13from supervision.metrics import ConfusionMatrix
14cm = ConfusionMatrix(num_classes=80)
15cm.update(predictions, targets).compute().plot()  # matplotlib heatmap

 1from supervision.detection.utils import (
 2    box_iou_batch,                  # (N, 4) vs (M, 4) → (N, M) IoU 矩陣
 3    box_non_max_suppression,         # NMS, returns boolean mask
 4    box_non_max_merge,               # Non-Max Merge (合併重疊 box)
 5    mask_iou_batch, mask_non_max_suppression, mask_non_max_merge,
 6    oriented_box_iou_batch,          # OBB IoU
 7)
 8
 9# 直接在 Detections 上呼叫
10detections = detections.with_nms(threshold=0.5, class_agnostic=False)
11detections = detections.with_nmm(threshold=0.2, overlap_metric=sv.OverlapMetric.IOU)

 1from supervision.detection.utils import (
 2    mask_to_polygons,    # (H, W) bool mask → list of (N, 2) polygons
 3    polygon_to_mask,     # (N, 2) polygon → (H, W) bool mask
 4    mask_to_xyxy,        # mask → bounding box
 5    mask_to_rle,         # mask → COCO RLE
 6    rle_to_mask,         # COCO RLE → mask
 7    polygon_to_xyxy,
 8    xyxy_to_mask,
 9    xyxy_to_polygons,
10)

 1from supervision.draw.color import Color, ColorPalette
 2from supervision.draw.utils import draw_text, draw_polygon, draw_filled_rectangle
 3
 4# 色票
 5ColorPalette.LEGACY    # 舊版預設色
 6ColorPalette.ROBOFLOW  # Roboflow 品牌色
 7custom = ColorPalette.from_hex(["#FF0000", "#00FF00", "#0000FF"])
 8
 9# 取顏色
10color = custom.by_idx(0)            # 第 0 個
11color = Color.from_hex("#FF5733")   # 從 hex

 1import supervision as sv
 2
 3# 一個一個讀 frame (generator)
 4for frame in sv.get_video_frames_generator(source_path="input.mp4"):
 5    pass
 6
 7# 用 callback 處理整個 video，自動寫 output (含 trace 等)
 8def callback(frame, frame_index):
 9    detections = sv.Detections.from_ultralytics(yolo.predict(frame)[0])
10    return box_annotator.annotate(frame, detections)
11
12sv.process_video(
13    source_path="input.mp4",
14    target_path="output.mp4",
15    callback=callback,
16)
17
18# 取得 video metadata
19info = sv.VideoInfo.from_video_path("input.mp4")
20print(info.fps, info.width, info.height, info.total_frames)

 1import cv2, numpy as np, supervision as sv
 2from ultralytics import YOLO
 3
 4model = YOLO("yolov8n.pt")
 5zone_polygon = np.array([[100, 100], [400, 100], [400, 400], [100, 400]])
 6zone = sv.PolygonZone(polygon=zone_polygon)
 7
 8box_annotator = sv.BoxAnnotator()
 9zone_annotator = sv.PolygonZoneAnnotator(zone=zone, color=sv.Color.GREEN, thickness=2)
10
11def callback(frame, _):
12    result = model(frame)[0]
13    detections = sv.Detections.from_ultralytics(result)
14    detections = detections[detections.class_id == 0]  # person
15    zone.trigger(detections=detections)
16    annotated = box_annotator.annotate(frame.copy(), detections)
17    annotated = zone_annotator.annotate(annotated)
18    return annotated
19
20sv.process_video("store_camera.mp4", "out.mp4", callback)
21print(f"Total people in zone (cumulative): {zone.current_count}")

 1line = sv.LineZone(start=sv.Point(0, 540), end=sv.Point(1920, 540))
 2line_annotator = sv.LineZoneAnnotator(thickness=4, text_thickness=2, text_scale=2)
 3
 4def callback(frame, _):
 5    result = model(frame)[0]
 6    dets = sv.Detections.from_ultralytics(result)
 7    dets = dets[np.isin(dets.class_id, [2, 3, 5, 7])]  # car/motor/bus/truck
 8    dets = byte_tracker.update_with_detections(dets)
 9    line.trigger(detections=dets)  # 自動判斷哪些 cross
10    annotated = box_annotator.annotate(frame.copy(), dets)
11    annotated = line_annotator.annotate(annotated, line_counter=line)
12    return annotated
13
14# line.in_count / line.out_count 兩個方向計數

1from supervision import InferenceSlicer
2
3def callback(slice_image: np.ndarray) -> sv.Detections:
4    result = model(slice_image)[0]
5    return sv.Detections.from_ultralytics(result)
6
7slicer = InferenceSlicer(callback=callback, slice_wh=(640, 640), overlap_ratio_wh=(0.2, 0.2))
8detections = slicer(image=large_image)  # 自動 tile + inference + 合併 + NMS

1# 把同事給的 COCO 格式 dataset 轉成 YOLO 給 Ultralytics 訓練
2ds = sv.DetectionDataset.from_coco(images_directory_path="data/coco/images",
3                                   annotations_path="data/coco/annotations.json")
4ds.as_yolo(images_directory_path="data/yolo/images",
5           annotations_directory_path="data/yolo/labels",
6           data_yaml_path="data/yolo/data.yaml")

1[絕對信任]   supervision 純 Python library，無 hooks / 無 binary / 無外部 process
2[條件信任]   ↓
3            上游 model (YOLO / DETR / SAM 等)：你自己選的，由你信任
4[條件信任]   ↓
5            COCO / YOLO / VOC dataset 檔案：解析 VOC XML 用 defusedxml 防 XXE
6[一般風險]   ↓
7            video / image 解碼依賴 OpenCV / Pillow，這兩者本身有歷史 CVE，建議套件保持最新

1from supervision.metrics import MeanAveragePrecision
2result = MeanAveragePrecision().update(preds, targets).compute()
3print(result.map50_95)

1detections = sv.Detections(
2    xyxy=my_model_boxes,
3    confidence=my_model_scores,
4    class_id=my_model_class_ids,
5)

1detections.data["age"] = np.array([25, 35, 18])
2detections.data["custom_id"] = np.array(["A1", "B2", "C3"])
3
4# slicing 會自動帶過去
5high_conf = detections[detections.confidence > 0.7]
6print(high_conf.data["age"])  # 自動篩選

1from supervision.draw.color import ColorPalette
2palette = ColorPalette.from_hex(["#1A73E8", "#34A853", "#FBBC05", "#EA4335"])
3box_annotator = sv.BoxAnnotator(color=palette)
4label_annotator = sv.LabelAnnotator(color=palette, text_color=sv.Color.WHITE)

1sv.process_video(
2    source_path="in.mp4",
3    target_path="out.mp4",
4    callback=my_callback,
5    show_progress=True,
6)

1csv_sink = sv.CSVSink(file_name="detections.csv")
2with csv_sink as sink:
3    for frame_idx, frame in enumerate(sv.get_video_frames_generator("video.mp4")):
4        dets = sv.Detections.from_ultralytics(model(frame)[0])
5        sink.append(dets, custom_data={"frame_index": frame_idx})

1smoother = sv.DetectionsSmoother(length=5)
2for frame in frames:
3    dets = sv.Detections.from_ultralytics(model(frame)[0])
4    dets = byte_tracker.update_with_detections(dets)
5    dets = smoother.update_with_detections(dets)  # 5 frame 滑動平均

1slicer = sv.InferenceSlicer(
2    callback=lambda img: sv.Detections.from_ultralytics(model(img)[0]),
3    slice_wh=(640, 640),
4    overlap_ratio_wh=(0.2, 0.2),
5    iou_threshold=0.5,    # 合併重疊 detections
6)
7detections = slicer(image=large_image)

1roboflow Inference (server)  ─→  sv.Detections.from_inference  ─→  supervision tools
2roboflow datasets             ─→  sv.DetectionDataset.from_yolo / from_coco
3roboflow notebooks            ─→  Jupyter 教學整合
4roboflow trackers (new!)      ─→  ByteTrack / DeepSORT / SORT (從 supervision 拆出)
5autodistill                   ─→  用 foundation model 自動標註，產 dataset 給 supervision 處理
6multimodal-maestro            ─→  VLM prompting → sv.Detections.from_lmm

1import json
2serialized = {
3    "boxes": detections.xyxy.tolist(),
4    "classes": detections.class_id.tolist(),
5    "scores": detections.confidence.tolist(),
6}
7prompt = f"Analyze this scene: {json.dumps(serialized)}. What's happening?"

1import gradio as gr, supervision as sv
2def predict(image):
3    detections = sv.Detections.from_ultralytics(model(image)[0])
4    return box_annotator.annotate(image.copy(), detections)
5gr.Interface(predict, gr.Image(), gr.Image()).launch()