roboflow / supervision

roboflow/supervision

open_in_new前往仓库

我们编写可复用的计算机视觉工具。💜

项目概览

项目概述

Supervision 是 Roboflow 开源维护的 Python 计算机视觉工具库（GitHub: roboflow/supervision），官方定位为“可复用的计算机视觉工具箱”。它提供从模型输出解析、数据加载、目标跟踪、区域计数、图像/视频标注到模型评估的通用组件，使开发者可以围绕已有模型快速构建视觉应用。仓库描述为 “We write your reusable computer vision tools. 💜”。

核心功能

  • 模型无关的统一检测结果 API：以 sv.Detections 为核心，支持边界框、置信度、类别、掩码、轨迹 ID、自定义 data 与 metadata。
  • 丰富标注器（Annotators）：包括 BoxAnnotator、LabelAnnotator、MaskAnnotator、HaloAnnotator、PolygonAnnotator、TraceAnnotator、HeatMapAnnotator、BlurAnnotator、PixelateAnnotator、OrientedBoxAnnotator 等。
  • 数据集工具：支持 COCO、YOLO、Pascal VOC、CreateML、LabelMe 等格式的加载、保存、划分、合并与转换。
  • 跟踪与计数：ByteTrack（已弃用，官方推荐迁移至外部 trackers 包）、LineZone（越线计数）、PolygonZone（区域计数）。
  • 视频处理：get_video_frames_generator、process_video、VideoSink、FPSMonitor，支持多线程处理与音频保留。
  • 模型评估：MeanAveragePrecision、Precision、Recall、F1Score、ConfusionMatrix 等指标，支持常规边界框与定向边界框（OBB）。
  • 关键点与姿态：KeyPoints、EdgeAnnotator、VertexAnnotator、VertexLabelAnnotator 等。
  • 高级能力：CompactMask 紧凑掩码存储、InferenceSlicer 切片推理/SAHI 小目标检测、VLM 输出解析（Gemini、Qwen VL、DeepSeek VL 2、Moondream 等）。

适用与不适用场景

适用场景：

  • 目标检测、实例分割、姿态估计结果的后处理、过滤、NMS/NMM、跟踪与可视化。
  • 将 Ultralytics、Transformers、MMDetection、Inference、Detectron2、PaddleDetection 等模型输出统一为 sv.Detections。
  • 数据标注格式转换（COCO/YOLO/Pascal VOC/CreateML/LabelMe）、数据集划分与合并。
  • 视频分析应用，例如停留时间分析、越线计数、车速估计、轨迹绘制。
  • 小目标检测、大图切片推理、GeoTIFF 分块推理。
  • 模型性能评估与基准测试。

不适用场景：

  • 不提供模型训练或微调流程（仓库资料未提供训练器）。
  • 不是完整的模型服务/部署网关（仓库资料未提供服务端部署方案）。
  • 移动端、嵌入式端专项支持说明未在仓库资料中提供。
  • 桌面 GUI 仅提供有限的 tkinter ImageWindow，且依赖系统安装 python3-tk。

技术架构与依赖

  • 语言/运行时：Python >= 3.10。supervision-0.30.0 起终止 Python 3.9 支持。
  • 核心数据结构：sv.Detections、sv.Classification、sv.KeyPoints，以 NumPy 数组为主要数据载体。
  • 媒体格式：图像支持 NumPy 数组（OpenCV BGR）与 Pillow 图像；视频提供帧生成器、视频写入器与处理管线。
  • 依赖变化：supervision-0.30.0 起默认不再安装 OpenCV，改由内置的 cv2-free fallback 后端（NumPy、Pillow、PyAV，要求 av>=14.2）提供基础媒体操作；若环境中存在兼容 cv2，则自动优先使用 OpenCV。
  • 模型集成：通过可选 connectors 支持 Ultralytics、Transformers、MMDetection、Inference、Detectron2、PaddleDetection、YOLO-NAS、NCNN、Azure AI Vision、timm、CLIP、EasyOCR、SAM/SAM3 等，具体可用性以官方文档为准。
  • 可选安装：文档中明确出现 supervision[metrics] 与 supervision[geotiff]；仓库资料未提供完整 extras 清单。

安装与快速开始

在 Python>=3.10 环境中使用 pip 安装：

pip install supervision

若运行 README 中的 RF-DETR 示例，需要额外安装：

pip install pillow rfdetr

模型输出统一为 sv.Detections 的快速示例：

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

image = Image.open("path/to/image.jpg")
model = RFDETRSmall()
detections = model.predict(image, threshold=0.5)

len(detections)
# 5

使用标注器进行可视化：

import cv2
import supervision as sv

image = cv2.imread("path/to/image.jpg")
# 假设 detections 来自某个模型
detections = sv.Detections(...)

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

典型使用方法

  • 从模型结果构建 sv.Detections：例如 sv.Detections.from_inference(result)、sv.Detections.from_ultralytics(result)、sv.Detections.from_transformers(...)、sv.Detections.from_vlm(...)。
  • 标注与可视化：组合使用 BoxAnnotator、LabelAnnotator、MaskAnnotator、TraceAnnotator 等。
  • 数据集加载与转换：
import supervision as sv

ds = sv.DetectionDataset.from_coco(
    images_directory_path="...",
    annotations_path="...",
)

train_ds, test_ds = ds.split(split_ratio=0.7)

# 导出为 YOLO 格式
ds.as_yolo(
    images_directory_path="...",
    annotations_directory_path="...",
    data_yaml_path="...",
)
  • 视频处理：
import supervision as sv

def callback(frame, index):
    # 运行模型并返回标注后的帧
    return annotated_frame

sv.process_video(
    source_path="input_video.mp4",
    target_path="output_video.mp4",
    callback=callback,
)
  • 模型评估：
from supervision.metrics import MeanAveragePrecision

predictions = sv.Detections(...)
targets = sv.Detections(...)

map_metric = MeanAveragePrecision()
map_result = map_metric.update(predictions, targets).compute()

配置与部署要点

  • 若使用 Roboflow Inference 云服务，需要配置 ROBOFLOW_API_KEY；该要求已明确写在 README 示例中。
  • supervision-0.30.0 起 OpenCV 不再随包安装；若需要 OpenCV 专有行为，应自行安装且仅安装一个 wheel 家族（如 opencv-python-headless 或 opencv-python），然后重启进程。
  • 使用 sv.ImageWindow 需要系统安装 python3-tk（例如 Debian/Ubuntu 的 sudo apt-get install python3-tk），pip 无法安装该依赖。
  • 视频处理默认采用多线程 reader/processor/writer 管线；process_video(preserve_audio=True) 依赖 ffmpeg 进行音频混流。
  • 数据集 API 文档标注“仍可能变动”，建议在依赖中冻结 supervision 版本。
  • sv.ByteTrack 已弃用，官方建议迁移到外部 trackers 包（pip install trackers），更新方法由 update_with_detections() 改为 update()。
  • 仓库资料未提供 Docker、Kubernetes、云原生部署或自建推理服务网关的配置示例。

限制、风险与许可证

  • 许可证：MIT（仓库元数据与 PyPI badge 均显示 MIT）。
  • Python 3.9 已终止支持，必须使用 Python>=3.10。
  • 无 OpenCV 时使用 fallback 后端，导入时会发出 UserWarning；部分 OpenCV 专有行为可能不一致。
  • 指标与文档 API 仍处于演进中，存在破坏性变更（例如 JSONSink 的 JSON 类型、混合 mask 合并返回类型等）。
  • 大型分割任务中 dense mask 可能占用大量内存，可使用 sv.CompactMask 缓解。
  • 安全方面：仓库修复过 COCO 路径穿越等安全问题；安全报告建议通过 GitHub 私有漏洞报告或 Roboflow 官方渠道。仓库资料未提供独立的安全公告页面。
  • 除上述外，仓库资料未提供商业支持、SLA 或额外授权条款。

官方链接

信息来源和分析时间

  • 信息来源：仓库 README、docs/about.md、docs/changelog.md、docs/detection/*、docs/datasets/core.md、仓库元数据（topics、license、language）及 latestRelease 信息。
  • 分析说明：本次分析仅基于上述仓库资料，未访问网络或仓库之外内容。
  • 分析时间：以仓库最新发布 supervision-0.30.0 的发布时间为参照（2026-08-04）；仓库资料未提供其他更精确的分析时间戳。