## 项目概述

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 安装：

```bash
pip install supervision
```

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

```bash
pip install pillow rfdetr
```

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

```python
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
```

使用标注器进行可视化：

```python
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` 等。
- 数据集加载与转换：

```python
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="...",
)
```

- 视频处理：

```python
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,
)
```

- 模型评估：

```python
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 或额外授权条款。

## 官方链接

- GitHub 仓库：https://github.com/roboflow/supervision
- 官方文档：https://supervision.roboflow.com （另见 https://roboflow.github.io/supervision）
- PyPI 包：https://pypi.org/project/supervision/
- Notebooks：https://github.com/roboflow/notebooks
- Roboflow Inference：https://github.com/roboflow/inference
- 社区支持（Discord）：https://discord.gg/GbfgXGJ8Bk
- 最新发布：https://github.com/roboflow/supervision/releases/tag/0.30.0

## 信息来源和分析时间

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