Supervision 使用指南用统一 Detections 对象完成检测、跟踪、区域计数与数据集处理的计算机视觉工具箱【免费下载链接】supervisionWe write your reusable computer vision tools. 项目地址: https://gitcode.com/GitHub_Trending/su/supervision本文是 docs/index.md 所承载的 Supervision 项目首页内容的全量技术导读面向想要在检测、分割模型之上快速搭建可视化、跟踪、区域统计与数据流水线的开发者。读完本文你将掌握 Supervision 的核心抽象统一的Detections对象、完整的多包管理器安装方式pip / poetry / uv / rye / conda / mamba、一条从“模型推理 → 结果归一化 → 标注渲染”的最小可用链路以及项目提供的全套进阶向导的入口位置可直接对照仓库内对应源码与文档继续深入。Supervision 是什么面向复用计算机视觉组件的开源库Supervision 是由 Roboflow 开发并公开维护的 Python 计算机视觉库官方在首页用一句话概括其使命We write your reusable computer vision tools.见 docs/index.md。它的目标不是替代任何模型推理框架而是把「拿到模型输出之后」的高频工程动作——给图像和视频绘制边界框、掩码与标签为跨帧物体分配持久 ID 进行跟踪在多边形区域内计数与过滤检测结果在 YOLO / COCO / Pascal VOC 三种数据集格式间转换以及用 mAP、混淆矩阵等指标评测模型——沉淀为一套与具体模型框架解耦的组件。需要明确的技术定位是Supervision 是模型无关model-agnostic的后处理与工具层。仓库的mkdocs.yml在站点描述中给出的完整表述为“Model-agnostic Python library for computer vision. Annotate, track, filter, and export detections from supported model outputs”见 mkdocs.yml支持范围覆盖 RF-DETR、Roboflow Inference、Transformers、SAM、Detectron2、MMDetection、Ultralytics 与 VLM 解析器。推荐搭配RF-DETR 直接返回 Detections文档明确说明与 Supervision 配对使用的推荐检测与分割模型是RF-DETR其model.predict()会原生返回一个Detections对象无需任何转换步骤。这在本仓库的 API 参考文档 docs/detection/core.md 与源码 src/supervision/detection/core.py 的Detectionsdocstring 中均有对应示例佐证。import cv2 import supervision as sv from rfdetr import RFDETRMedium model RFDETRMedium() image cv2.imread(image.jpg) detections model.predict(image[:, :, ::-1]) # 直接得到 sv.Detections注意示例中image[:, :, ::-1]的通道反转RF-DETR 以 RGB 顺序消费输入而cv2.imread读取的是 BGR 排列因此需要先反转通道。核心能力概览综合 docs/index.md 与仓库实际提供的模块__init__.py的导出列表见 src/supervision/init.pySupervision 覆盖如下能力族标注Annotators边界框、掩码、标签、关键点、热力图、光晕、圆点、轮廓等 20 标注器统一从 src/supervision/annotators/core.py 导出API 参考见 docs/detection/annotators.md跟踪Tracking基于 ByteTrack 的多目标跟踪为检测结果赋予持久tracker_id实现代码位于 src/supervision/tracker/byte_tracker区域计数与过滤ZonesPolygonZone/PolygonZoneAnnotator实现多边形区域内的计数LineZone/LineZoneAnnotator实现越线计数源码见 src/supervision/detection/tools/polygon_zone.py 与 src/supervision/detection/line_zone.py数据集转换Datasets在 YOLO、COCO、Pascal VOC 三种标注格式之间加载与转换实现位于 src/supervision/dataset指标评测MetricsmAP、mAR、Precision、Recall、F1 与混淆矩阵等参考 docs/metrics 目录。环境要求与安装五种包管理器全覆盖根据 pyproject.toml 的项目元数据当前仓库对应版本为0.31.0.dev0要求Python 3.10并在 3.10–3.14 各版本分类器下被 CI 覆盖。核心运行时依赖包括numpy1.21.2、opencv-python经可选依赖管理、matplotlib3.6、pillow9.4、scipy1.10、pyyaml5.3、requests2.26、av14.2视频处理等。可选依赖方面还提供geotiff基于rasterio1.3的大影像分块推理与metrics基于pandas2的指标计算两个 extras。pip推荐pip install supervisionpoetrypoetry add supervisionuv对于全局环境使用uv pip install supervision对于由 uv 管理的项目则使用uv add supervisionryerye add supervisionconda / mambaconda-forge 频道# conda conda install -c conda-forge supervision # mamba mamba install -c conda-forge supervision源码安装开发模式若要参与开发或体验develop分支的最新特性可以克隆仓库后以可编辑模式安装。文档提供了两套流程virtualenv 方案# 克隆仓库并进入根目录 git clone --depth 1 -b develop https://github.com/roboflow/supervision.git cd supervision # 创建并激活 Python 环境 python3 -m venv venv source venv/bin/activate pip install --upgrade pip # 可编辑安装 pip install -e .uv 方案# 克隆仓库并进入根目录 git clone --depth 1 -b develop https://github.com/roboflow/supervision.git cd supervision # 创建并激活环境 uv venv source .venv/bin/activate # 安装全部依赖与 extras uv pip install -r pyproject.toml -e . --all-extras仓库目录布局中实际包代码位于src/supervision/pyproject.toml中[tool.setuptools] packages.find.where [src]测试位于 tests完整可运行的示例工程位于 examples。统一的 Detections 数据契约Supervision 全库的中枢数据结构是sv.Detectionssrc/supervision/detection/core.py。它是一个dataclass核心字段定义在 src/supervision/detection/core.py字段类型语义xyxyNDArray[np.number]每个目标的轴对齐边界框格式为[x1, y1, x2, y2]绝对像素坐标maskNDArray[np.bool_] \| CompactMask \| None可选的分割掩码boolean 数组或更省内存的CompactMaskconfidenceNDArray[np.floating] \| None每个检测的置信度分数class_idNDArray[np.integer] \| None类别索引tracker_idNDArray[np.integer] \| None跟踪器赋予的跨帧持久 IDdatadict附加元数据字典如class_name正是因为几乎所有模型框架都通过类方法归一化到这一份数据契约下游的标注器、过滤器和区域工具才能写出「只面向Detections」的通用逻辑。支持框架与对应的转换类方法除 RF-DETR 原生返回Detections外其余框架的输出需要一步转换。从 src/supervision/detection/core.py 中可确认的类方法classmethod包括Detections.from_inferenceRoboflow Inferencecore.pyDetections.from_ultralyticsUltralytics YOLOcore.pyDetections.from_transformersHugging Face Transformerscore.pyDetections.from_detectron2Detectron2core.pyDetections.from_mmdetectionMMDetectioncore.pyDetections.from_sam/from_sam3Segment Anything Modelcore.pyDetections.from_yolo_nasYOLO-NAScore.pyDetections.from_deepsparsecore.py、Detections.from_yolov5core.py、Detections.from_tensorflowcore.py、Detections.from_azure_analyze_imagecore.py、Detections.from_paddledetcore.py、Detections.from_ncnncore.py等Detections.from_vlm/from_lmm视觉语言模型输出如 Florence-2、PaliGemma、Qwen-VL、Gemini 等core.py这些from_*转换是让 Supervision“无论检测结果来自哪个模型都能被同样的下游组件消费”的关键机制也是推荐使用 RF-DETR 时“少一次转换”的便捷性来源。快速开始一个从推理到标注的最小链路文档首页给出的最小示例见 docs/index.md展示了三个步骤运行推理 → 标注边界框 → 叠加类别标签。import cv2 import supervision as sv from rfdetr import RFDETRMedium model RFDETRMedium() image cv2.imread(image.jpg) detections model.predict(image[:, :, ::-1]) box_annotator sv.BoxAnnotator() label_annotator sv.LabelAnnotator() annotated_image box_annotator.annotate(sceneimage, detectionsdetections) annotated_image label_annotator.annotate(sceneannotated_image, detectionsdetections)两个值得注意的工程细节标注器链式调用每个annotator.annotate(...)返回渲染后的新图像仍为同一 NumPy 数组对象原地叠加后返回因此可以将多个标注器串在一起把上一个的输出作为下一个的scene输入。这使「先画框、再叠加标签」「先画框、再叠掩码」等组合变得非常自然。BoxAnnotator与LabelAnnotator职责分离画框与写字是两种不同的视觉操作分开建模让你可以单独定制每个环节的颜色、线宽、文字位置等参数。使用其他模型框架的完整流程如果使用 Roboflow Inference / Ultralytics / Transformers完整链路多一步转换。以 docs/how_to/detect_and_annotate.md 为例三种框架的核心代码模式分别是InferenceRoboflow 云端/本地推理服务import cv2 import supervision as sv from inference import get_model model get_model(model_idrfdetr-small) image cv2.imread(dog.jpeg) results model.infer(image)[0] detections sv.Detections.from_inference(results) box_annotator sv.BoxAnnotator() label_annotator sv.LabelAnnotator() annotated_image box_annotator.annotate(sceneimage, detectionsdetections) annotated_image label_annotator.annotate(sceneannotated_image, detectionsdetections)Ultralytics YOLOimport cv2 import supervision as sv from ultralytics import YOLO model YOLO(yolov8n.pt) image cv2.imread(dog.jpeg) results model(image)[0] detections sv.Detections.from_ultralytics(results) # 检测与分割输出均可 box_annotator sv.BoxAnnotator() label_annotator sv.LabelAnnotator() annotated_image box_annotator.annotate(sceneimage, detectionsdetections) annotated_image label_annotator.annotate(sceneannotated_image, detectionsdetections)Hugging Face TransformersDETR 系列import torch import supervision as sv from PIL import Image from transformers import DetrImageProcessor, DetrForObjectDetection processor DetrImageProcessor.from_pretrained(facebook/detr-resnet-50) model DetrForObjectDetection.from_pretrained(facebook/detr-resnet-50) image Image.open(dog.jpeg) inputs processor(imagesimage, return_tensorspt) with torch.no_grad(): outputs model(**inputs) width, height image.size target_size torch.tensor([[height, width]]) results processor.post_process_object_detection( outputsoutputs, target_sizestarget_size)[0] detections sv.Detections.from_transformers( transformers_resultsresults, id2labelmodel.config.id2label) box_annotator sv.BoxAnnotator() label_annotator sv.LabelAnnotator() annotated_image box_annotator.annotate(sceneimage, detectionsdetections) annotated_image label_annotator.annotate(sceneannotated_image, detectionsdetections)无论使用哪个框架转换之后的所有下游代码标注、过滤、区域统计完全一致——这正是统一Detections抽象的设计收益。使用分割掩码MaskAnnotator当你运行的是分割模型时sv.MaskAnnotator是BoxAnnotator的“即插即用”替代品文档原话是 drop-in replacement用来绘制掩码而不是框。结合LabelAnnotator(text_positionsv.Position.CENTER_OF_MASS)可以把类别标签放到每个分割对象的质心处mask_annotator sv.MaskAnnotator() label_annotator sv.LabelAnnotator(text_positionsv.Position.CENTER_OF_MASS) annotated_image mask_annotator.annotate(sceneimage, detectionsdetections) annotated_image label_annotator.annotate( sceneannotated_image, detectionsdetections) sv.plot_image(annotated_image) # 在 Notebook 中显示结果对应的 Ultralytics 分割模型加载方式为YOLO(yolov8n-seg.pt)Transformers 侧则使用DetrForSegmentation与post_process_segmentation。你可以自由组合BoxAnnotator画完框后再用MaskAnnotator在同一张scene上叠加掩码。自定义标签文本LabelAnnotator的默认行为是优先使用每个检测的class_name若连接器提供了该字段它会被写入detections.data[class_name]否则回退到class_id再否则回退到检测索引。要显示自定义文本通过labels参数显式传入字符串列表即可例如把类别名与置信度拼接成一行labels [ f{class_name} {confidence:.2f} for class_name, confidence in zip(detections[class_name], detections.confidence) ] annotated_image label_annotator.annotate( sceneannotated_image, detectionsdetections, labelslabels)从入门到实战官方推荐的进阶路径首页 Quickstart 部分按“能力卡片”的方式组织进阶入口且这些能力在本仓库中都有对应的 How-to 文档与源码模块。下表给出每个能力及其在仓库中的落地位置能力解决的问题仓库中的指南与实现Detect and Annotate把各类检测/分割模型的预测画到图上docs/how_to/detect_and_annotate.md标注器实现见 src/supervision/annotators/core.pyTrack Objects视频分析中的跨帧目标跟踪docs/how_to/track_objects.mdByteTrack 实现见 src/supervision/tracker/byte_trackerDetect Small Objects在图像中检测小目标docs/how_to/detect_small_objects.md配套分块推理工具InferenceSlicer位于 src/supervision/detection/tools/inference_slicer.py参考文档 docs/detection/tools/inference_slicer.mdCount Objects Crossing Line统计越过预设直线/区域的目标数越线计数 Notebook 见 docs/notebooks/count-objects-crossing-the-line.ipynbLineZone/PolygonZone实现见 src/supervision/detection/line_zone.py 与 src/supervision/detection/tools/polygon_zone.pyFilter Objects in Zone在多边形区域内过滤与聚焦目标docs/how_to/count_in_zone.md更多 How-to过滤检测、处理数据集、评测模型、OpenCV 迁移等docs/how_to 目录下的各篇指南此外还有两个值得一提的直接相关能力入口在视频上做检测标注视频处理既可以用sv.VideoSink输出标注后的视频也可以配合跟踪器实现逐帧持久 ID示例见 docs/notebooks/annotate-video-with-detections.ipynb。数据集格式转换与基准评测DetectionDataset及 COCO/YOLO/Pascal VOC 适配器位于 src/supervision/dataset处理指南见 docs/how_to/process_datasets.md模型评测指南见 docs/how_to/benchmark_a_model.mdmAP、混淆矩阵等指标模块见 docs/metrics。如果你习惯在 Notebook 中边读边跑仓库还内置了十余个官方 Notebookdocs/notebooks覆盖目标跟踪、越线计数、YOLO-World 零样本检测、面向边界框等场景可作为进阶实战的配套材料。常用问题速查如何用 supervision 检测并标注物体把任一支持模型的输出交给sv.Detections.from_model()生成统一Detections再传给sv.BoxAnnotator或sv.MaskAnnotator绘制到图像上。能否同时标注边界框与掩码可以。在同一个scene上先调用BoxAnnotator画框、再叠加MaskAnnotator画掩码即可标注器可任意链式组合。如何显示类别名标签用sv.LabelAnnotator并通过labels参数传入自定义文本若连接器提供了类别名则它们存储在detections[class_name]中省略labels时标注器会依次回退使用类别名、类别 ID、检测索引。能否搭配 Hugging Face 模型使用可以sv.Detections.from_transformers()接受受支持的 HF 检测与分割输出VLM 输出则通过sv.Detections.from_vlm(...)处理例如sv.VLM.FLORENCE_2或sv.VLM.PALIGEMMA。项目状态与许可Supervision 采用MIT 许可证见仓库根目录 LICENSE.md采用“在 GitHub 上公开开发”的模式服务生产级计算机视觉工作流。文档首页同时提供了两个被广泛引用的采用度数据接近 50,000 的 GitHub Star 与每月超过 100 万的 PyPI 下载量仓库的 mkdocs.yml 中也记录了截至 2026-09-02 的 Star 快照约为 49,848供后续刷新采用度声明时参考。这些数据均出自仓库自带文档/配置本仓库当前代码版本为 pyproject.toml 中标注的0.31.0.dev0。若要进一步了解具体模块的 API 签名与参数可以从本仓库的 docs 目录按nav结构导航定义见 mkdocs.yml例如Detections的完整 API 参考在 docs/detection/core.md各标注器的参数说明在 docs/detection/annotators.md。这些页面中的示例代码与当前源码保持一致可以作为你在本项目之上二次开发的第一手资料。【免费下载链接】supervisionWe write your reusable computer vision tools. 项目地址: https://gitcode.com/GitHub_Trending/su/supervision创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Supervision 使用指南：用统一 Detections 对象完成检测、跟踪、区域计数与数据集处理的计算机视觉工具箱
Supervision 使用指南用统一 Detections 对象完成检测、跟踪、区域计数与数据集处理的计算机视觉工具箱【免费下载链接】supervisionWe write your reusable computer vision tools. 项目地址: https://gitcode.com/GitHub_Trending/su/supervision本文是 docs/index.md 所承载的 Supervision 项目首页内容的全量技术导读面向想要在检测、分割模型之上快速搭建可视化、跟踪、区域统计与数据流水线的开发者。读完本文你将掌握 Supervision 的核心抽象统一的Detections对象、完整的多包管理器安装方式pip / poetry / uv / rye / conda / mamba、一条从“模型推理 → 结果归一化 → 标注渲染”的最小可用链路以及项目提供的全套进阶向导的入口位置可直接对照仓库内对应源码与文档继续深入。Supervision 是什么面向复用计算机视觉组件的开源库Supervision 是由 Roboflow 开发并公开维护的 Python 计算机视觉库官方在首页用一句话概括其使命We write your reusable computer vision tools.见 docs/index.md。它的目标不是替代任何模型推理框架而是把「拿到模型输出之后」的高频工程动作——给图像和视频绘制边界框、掩码与标签为跨帧物体分配持久 ID 进行跟踪在多边形区域内计数与过滤检测结果在 YOLO / COCO / Pascal VOC 三种数据集格式间转换以及用 mAP、混淆矩阵等指标评测模型——沉淀为一套与具体模型框架解耦的组件。需要明确的技术定位是Supervision 是模型无关model-agnostic的后处理与工具层。仓库的mkdocs.yml在站点描述中给出的完整表述为“Model-agnostic Python library for computer vision. Annotate, track, filter, and export detections from supported model outputs”见 mkdocs.yml支持范围覆盖 RF-DETR、Roboflow Inference、Transformers、SAM、Detectron2、MMDetection、Ultralytics 与 VLM 解析器。推荐搭配RF-DETR 直接返回 Detections文档明确说明与 Supervision 配对使用的推荐检测与分割模型是RF-DETR其model.predict()会原生返回一个Detections对象无需任何转换步骤。这在本仓库的 API 参考文档 docs/detection/core.md 与源码 src/supervision/detection/core.py 的Detectionsdocstring 中均有对应示例佐证。import cv2 import supervision as sv from rfdetr import RFDETRMedium model RFDETRMedium() image cv2.imread(image.jpg) detections model.predict(image[:, :, ::-1]) # 直接得到 sv.Detections注意示例中image[:, :, ::-1]的通道反转RF-DETR 以 RGB 顺序消费输入而cv2.imread读取的是 BGR 排列因此需要先反转通道。核心能力概览综合 docs/index.md 与仓库实际提供的模块__init__.py的导出列表见 src/supervision/init.pySupervision 覆盖如下能力族标注Annotators边界框、掩码、标签、关键点、热力图、光晕、圆点、轮廓等 20 标注器统一从 src/supervision/annotators/core.py 导出API 参考见 docs/detection/annotators.md跟踪Tracking基于 ByteTrack 的多目标跟踪为检测结果赋予持久tracker_id实现代码位于 src/supervision/tracker/byte_tracker区域计数与过滤ZonesPolygonZone/PolygonZoneAnnotator实现多边形区域内的计数LineZone/LineZoneAnnotator实现越线计数源码见 src/supervision/detection/tools/polygon_zone.py 与 src/supervision/detection/line_zone.py数据集转换Datasets在 YOLO、COCO、Pascal VOC 三种标注格式之间加载与转换实现位于 src/supervision/dataset指标评测MetricsmAP、mAR、Precision、Recall、F1 与混淆矩阵等参考 docs/metrics 目录。环境要求与安装五种包管理器全覆盖根据 pyproject.toml 的项目元数据当前仓库对应版本为0.31.0.dev0要求Python 3.10并在 3.10–3.14 各版本分类器下被 CI 覆盖。核心运行时依赖包括numpy1.21.2、opencv-python经可选依赖管理、matplotlib3.6、pillow9.4、scipy1.10、pyyaml5.3、requests2.26、av14.2视频处理等。可选依赖方面还提供geotiff基于rasterio1.3的大影像分块推理与metrics基于pandas2的指标计算两个 extras。pip推荐pip install supervisionpoetrypoetry add supervisionuv对于全局环境使用uv pip install supervision对于由 uv 管理的项目则使用uv add supervisionryerye add supervisionconda / mambaconda-forge 频道# conda conda install -c conda-forge supervision # mamba mamba install -c conda-forge supervision源码安装开发模式若要参与开发或体验develop分支的最新特性可以克隆仓库后以可编辑模式安装。文档提供了两套流程virtualenv 方案# 克隆仓库并进入根目录 git clone --depth 1 -b develop https://github.com/roboflow/supervision.git cd supervision # 创建并激活 Python 环境 python3 -m venv venv source venv/bin/activate pip install --upgrade pip # 可编辑安装 pip install -e .uv 方案# 克隆仓库并进入根目录 git clone --depth 1 -b develop https://github.com/roboflow/supervision.git cd supervision # 创建并激活环境 uv venv source .venv/bin/activate # 安装全部依赖与 extras uv pip install -r pyproject.toml -e . --all-extras仓库目录布局中实际包代码位于src/supervision/pyproject.toml中[tool.setuptools] packages.find.where [src]测试位于 tests完整可运行的示例工程位于 examples。统一的 Detections 数据契约Supervision 全库的中枢数据结构是sv.Detectionssrc/supervision/detection/core.py。它是一个dataclass核心字段定义在 src/supervision/detection/core.py字段类型语义xyxyNDArray[np.number]每个目标的轴对齐边界框格式为[x1, y1, x2, y2]绝对像素坐标maskNDArray[np.bool_] \| CompactMask \| None可选的分割掩码boolean 数组或更省内存的CompactMaskconfidenceNDArray[np.floating] \| None每个检测的置信度分数class_idNDArray[np.integer] \| None类别索引tracker_idNDArray[np.integer] \| None跟踪器赋予的跨帧持久 IDdatadict附加元数据字典如class_name正是因为几乎所有模型框架都通过类方法归一化到这一份数据契约下游的标注器、过滤器和区域工具才能写出「只面向Detections」的通用逻辑。支持框架与对应的转换类方法除 RF-DETR 原生返回Detections外其余框架的输出需要一步转换。从 src/supervision/detection/core.py 中可确认的类方法classmethod包括Detections.from_inferenceRoboflow Inferencecore.pyDetections.from_ultralyticsUltralytics YOLOcore.pyDetections.from_transformersHugging Face Transformerscore.pyDetections.from_detectron2Detectron2core.pyDetections.from_mmdetectionMMDetectioncore.pyDetections.from_sam/from_sam3Segment Anything Modelcore.pyDetections.from_yolo_nasYOLO-NAScore.pyDetections.from_deepsparsecore.py、Detections.from_yolov5core.py、Detections.from_tensorflowcore.py、Detections.from_azure_analyze_imagecore.py、Detections.from_paddledetcore.py、Detections.from_ncnncore.py等Detections.from_vlm/from_lmm视觉语言模型输出如 Florence-2、PaliGemma、Qwen-VL、Gemini 等core.py这些from_*转换是让 Supervision“无论检测结果来自哪个模型都能被同样的下游组件消费”的关键机制也是推荐使用 RF-DETR 时“少一次转换”的便捷性来源。快速开始一个从推理到标注的最小链路文档首页给出的最小示例见 docs/index.md展示了三个步骤运行推理 → 标注边界框 → 叠加类别标签。import cv2 import supervision as sv from rfdetr import RFDETRMedium model RFDETRMedium() image cv2.imread(image.jpg) detections model.predict(image[:, :, ::-1]) box_annotator sv.BoxAnnotator() label_annotator sv.LabelAnnotator() annotated_image box_annotator.annotate(sceneimage, detectionsdetections) annotated_image label_annotator.annotate(sceneannotated_image, detectionsdetections)两个值得注意的工程细节标注器链式调用每个annotator.annotate(...)返回渲染后的新图像仍为同一 NumPy 数组对象原地叠加后返回因此可以将多个标注器串在一起把上一个的输出作为下一个的scene输入。这使「先画框、再叠加标签」「先画框、再叠掩码」等组合变得非常自然。BoxAnnotator与LabelAnnotator职责分离画框与写字是两种不同的视觉操作分开建模让你可以单独定制每个环节的颜色、线宽、文字位置等参数。使用其他模型框架的完整流程如果使用 Roboflow Inference / Ultralytics / Transformers完整链路多一步转换。以 docs/how_to/detect_and_annotate.md 为例三种框架的核心代码模式分别是InferenceRoboflow 云端/本地推理服务import cv2 import supervision as sv from inference import get_model model get_model(model_idrfdetr-small) image cv2.imread(dog.jpeg) results model.infer(image)[0] detections sv.Detections.from_inference(results) box_annotator sv.BoxAnnotator() label_annotator sv.LabelAnnotator() annotated_image box_annotator.annotate(sceneimage, detectionsdetections) annotated_image label_annotator.annotate(sceneannotated_image, detectionsdetections)Ultralytics YOLOimport cv2 import supervision as sv from ultralytics import YOLO model YOLO(yolov8n.pt) image cv2.imread(dog.jpeg) results model(image)[0] detections sv.Detections.from_ultralytics(results) # 检测与分割输出均可 box_annotator sv.BoxAnnotator() label_annotator sv.LabelAnnotator() annotated_image box_annotator.annotate(sceneimage, detectionsdetections) annotated_image label_annotator.annotate(sceneannotated_image, detectionsdetections)Hugging Face TransformersDETR 系列import torch import supervision as sv from PIL import Image from transformers import DetrImageProcessor, DetrForObjectDetection processor DetrImageProcessor.from_pretrained(facebook/detr-resnet-50) model DetrForObjectDetection.from_pretrained(facebook/detr-resnet-50) image Image.open(dog.jpeg) inputs processor(imagesimage, return_tensorspt) with torch.no_grad(): outputs model(**inputs) width, height image.size target_size torch.tensor([[height, width]]) results processor.post_process_object_detection( outputsoutputs, target_sizestarget_size)[0] detections sv.Detections.from_transformers( transformers_resultsresults, id2labelmodel.config.id2label) box_annotator sv.BoxAnnotator() label_annotator sv.LabelAnnotator() annotated_image box_annotator.annotate(sceneimage, detectionsdetections) annotated_image label_annotator.annotate(sceneannotated_image, detectionsdetections)无论使用哪个框架转换之后的所有下游代码标注、过滤、区域统计完全一致——这正是统一Detections抽象的设计收益。使用分割掩码MaskAnnotator当你运行的是分割模型时sv.MaskAnnotator是BoxAnnotator的“即插即用”替代品文档原话是 drop-in replacement用来绘制掩码而不是框。结合LabelAnnotator(text_positionsv.Position.CENTER_OF_MASS)可以把类别标签放到每个分割对象的质心处mask_annotator sv.MaskAnnotator() label_annotator sv.LabelAnnotator(text_positionsv.Position.CENTER_OF_MASS) annotated_image mask_annotator.annotate(sceneimage, detectionsdetections) annotated_image label_annotator.annotate( sceneannotated_image, detectionsdetections) sv.plot_image(annotated_image) # 在 Notebook 中显示结果对应的 Ultralytics 分割模型加载方式为YOLO(yolov8n-seg.pt)Transformers 侧则使用DetrForSegmentation与post_process_segmentation。你可以自由组合BoxAnnotator画完框后再用MaskAnnotator在同一张scene上叠加掩码。自定义标签文本LabelAnnotator的默认行为是优先使用每个检测的class_name若连接器提供了该字段它会被写入detections.data[class_name]否则回退到class_id再否则回退到检测索引。要显示自定义文本通过labels参数显式传入字符串列表即可例如把类别名与置信度拼接成一行labels [ f{class_name} {confidence:.2f} for class_name, confidence in zip(detections[class_name], detections.confidence) ] annotated_image label_annotator.annotate( sceneannotated_image, detectionsdetections, labelslabels)从入门到实战官方推荐的进阶路径首页 Quickstart 部分按“能力卡片”的方式组织进阶入口且这些能力在本仓库中都有对应的 How-to 文档与源码模块。下表给出每个能力及其在仓库中的落地位置能力解决的问题仓库中的指南与实现Detect and Annotate把各类检测/分割模型的预测画到图上docs/how_to/detect_and_annotate.md标注器实现见 src/supervision/annotators/core.pyTrack Objects视频分析中的跨帧目标跟踪docs/how_to/track_objects.mdByteTrack 实现见 src/supervision/tracker/byte_trackerDetect Small Objects在图像中检测小目标docs/how_to/detect_small_objects.md配套分块推理工具InferenceSlicer位于 src/supervision/detection/tools/inference_slicer.py参考文档 docs/detection/tools/inference_slicer.mdCount Objects Crossing Line统计越过预设直线/区域的目标数越线计数 Notebook 见 docs/notebooks/count-objects-crossing-the-line.ipynbLineZone/PolygonZone实现见 src/supervision/detection/line_zone.py 与 src/supervision/detection/tools/polygon_zone.pyFilter Objects in Zone在多边形区域内过滤与聚焦目标docs/how_to/count_in_zone.md更多 How-to过滤检测、处理数据集、评测模型、OpenCV 迁移等docs/how_to 目录下的各篇指南此外还有两个值得一提的直接相关能力入口在视频上做检测标注视频处理既可以用sv.VideoSink输出标注后的视频也可以配合跟踪器实现逐帧持久 ID示例见 docs/notebooks/annotate-video-with-detections.ipynb。数据集格式转换与基准评测DetectionDataset及 COCO/YOLO/Pascal VOC 适配器位于 src/supervision/dataset处理指南见 docs/how_to/process_datasets.md模型评测指南见 docs/how_to/benchmark_a_model.mdmAP、混淆矩阵等指标模块见 docs/metrics。如果你习惯在 Notebook 中边读边跑仓库还内置了十余个官方 Notebookdocs/notebooks覆盖目标跟踪、越线计数、YOLO-World 零样本检测、面向边界框等场景可作为进阶实战的配套材料。常用问题速查如何用 supervision 检测并标注物体把任一支持模型的输出交给sv.Detections.from_model()生成统一Detections再传给sv.BoxAnnotator或sv.MaskAnnotator绘制到图像上。能否同时标注边界框与掩码可以。在同一个scene上先调用BoxAnnotator画框、再叠加MaskAnnotator画掩码即可标注器可任意链式组合。如何显示类别名标签用sv.LabelAnnotator并通过labels参数传入自定义文本若连接器提供了类别名则它们存储在detections[class_name]中省略labels时标注器会依次回退使用类别名、类别 ID、检测索引。能否搭配 Hugging Face 模型使用可以sv.Detections.from_transformers()接受受支持的 HF 检测与分割输出VLM 输出则通过sv.Detections.from_vlm(...)处理例如sv.VLM.FLORENCE_2或sv.VLM.PALIGEMMA。项目状态与许可Supervision 采用MIT 许可证见仓库根目录 LICENSE.md采用“在 GitHub 上公开开发”的模式服务生产级计算机视觉工作流。文档首页同时提供了两个被广泛引用的采用度数据接近 50,000 的 GitHub Star 与每月超过 100 万的 PyPI 下载量仓库的 mkdocs.yml 中也记录了截至 2026-09-02 的 Star 快照约为 49,848供后续刷新采用度声明时参考。这些数据均出自仓库自带文档/配置本仓库当前代码版本为 pyproject.toml 中标注的0.31.0.dev0。若要进一步了解具体模块的 API 签名与参数可以从本仓库的 docs 目录按nav结构导航定义见 mkdocs.yml例如Detections的完整 API 参考在 docs/detection/core.md各标注器的参数说明在 docs/detection/annotators.md。这些页面中的示例代码与当前源码保持一致可以作为你在本项目之上二次开发的第一手资料。【免费下载链接】supervisionWe write your reusable computer vision tools. 项目地址: https://gitcode.com/GitHub_Trending/su/supervision创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考