supervision

基于计算机视觉的可复用工具集，提供模型无关的数据加载、标注、跟踪、区域计数等能力，支持 Ultralytics、Transformers 等多种模型后端。亮点在于模块化设计，大幅降低 CV 应用开发门槛，配合 Roboflow 生态可快速完成从数据到部署的全流程，社区活跃且文档丰富。

README

notebooks | inference | autodistill | maestro

👋 你好

我们是你的计算机视觉核心工具集。 从数据加载到实时区域统计，我们提供基础模块，让你专注于围绕模型构建应用。🤝

💻 安装

在 Python>=3.9 环境中通过 pip 安装 supervision 包。

pip install supervision

关于 conda、mamba 以及从源码安装的更多信息，请参阅我们的指南。

🔥 快速开始

模型

Supervision 被设计为模型无关的。只需插入任意分类、检测或分割模型。为方便起见，我们为最流行的库（如 Ultralytics、Transformers、MMDetection 或 Inference）创建了连接器。其他集成，如 rfdetr，直接返回 sv.Detections。

在示例中安装可选依赖：pip install pillow rfdetr。

import supervision as sv
from PIL import Image
from rfdetr import RFDETRSmall

image = Image.open(...)
model = RFDETRSmall()
detections = model.predict(image, threshold=0.5)

len(detections)
# 5

👉 更多模型连接器

inference

使用 Inference 需要 Roboflow API 密钥。

import supervision as sv
from PIL import Image
from inference import get_model

image = Image.open(...)
model = get_model(model_id="rfdetr-small", api_key="ROBOFLOW_API_KEY")
result = model.infer(image)[0]
detections = sv.Detections.from_inference(result)

len(detections)
# 5

标注器

Supervision 提供了广泛的高度可定制的标注器，让你能够为你的用例组合出完美的可视化效果。

import cv2
import supervision as sv

image = cv2.imread(...)
detections = sv.Detections(...)

box_annotator = sv.BoxAnnotator()
annotated_frame = box_annotator.annotate(scene=image.copy(), detections=detections)

https://github.com/roboflow/supervision/assets/26109316/691e219c-0565-4403-9218-ab5644f39bce

数据集

Supervision 提供一组工具，让你能够以支持的格式之一加载、拆分、合并和保存数据集。

import supervision as sv
from roboflow import Roboflow

project = Roboflow().workspace("WORKSPACE_ID").project("PROJECT_ID")
dataset = project.version("PROJECT_VERSION").download("coco")

ds = sv.DetectionDataset.from_coco(
    images_directory_path=f"{dataset.location}/train",
    annotations_path=f"{dataset.location}/train/_annotations.coco.json",
)

path, image, annotation = ds[0]
# 按需加载图像

for path, image, annotation in ds:
    # 按需加载图像
    pass

👉 更多数据集工具

加载

dataset = sv.DetectionDataset.from_yolo(
    images_directory_path=...,
    annotations_directory_path=...,
    data_yaml_path=...,
)

dataset = sv.DetectionDataset.from_pascal_voc(
    images_directory_path=...,
    annotations_directory_path=...,
)

dataset = sv.DetectionDataset.from_coco(
    images_directory_path=...,
    annotations_path=...,
)

拆分

train_dataset, test_dataset = dataset.split(split_ratio=0.7)
test_dataset, valid_dataset = test_dataset.split(split_ratio=0.5)

len(train_dataset), len(test_dataset), len(valid_dataset)
# (700, 150, 150)

合并

ds_1 = sv.DetectionDataset(...)
len(ds_1)
# 100
ds_1.classes
# ['dog', 'person']

ds_2 = sv.DetectionDataset(...)
len(ds_2)
# 200
ds_2.classes
# ['cat']

ds_merged = sv.DetectionDataset.merge([ds_1, ds_2])
len(ds_merged)
# 300
ds_merged.classes
# ['cat', 'dog', 'person']

保存

dataset.as_yolo(
    images_directory_path=...,
    annotations_directory_path=...,
    data_yaml_path=...,
)

dataset.as_pascal_voc(
    images_directory_path=...,
    annotations_directory_path=...,
)

dataset.as_coco(
    images_directory_path=...,
    annotations_path=...,
)

转换

sv.DetectionDataset.from_yolo(
    images_directory_path=...,
    annotations_directory_path=...,
    data_yaml_path=...,
).as_pascal_voc(
    images_directory_path=...,
    annotations_directory_path=...,
)