Supervision 项目深度解析以 Detections 为核心的模型无关计算机视觉工具链【免费下载链接】supervisionWe write your reusable computer vision tools. 项目地址: https://gitcode.com/GitHub_Trending/su/supervision本篇基于 Supervision 仓库的 关于文档 及其源码解析这个由 Roboflow 维护的开源 Python 计算机视觉库。Supervision 的定位是为开发者提供一套模型无关model-agnostic的工具包加载模型预测结果、在图像与视频上画标注、跨帧跟踪、区域计数、数据集格式转换以及模型性能评估。读完本文你将理解其核心数据结构Detections为何是整个库的“通用语言”、它支持哪些模型输出转换器、如何安装配置以及标注、跟踪、数据集与指标等各模块的源码落点从而能把它接入自己的视觉流水线而不必为更换模型重写后处理代码。项目定位把模型输出统一为一种数据表示Supervision 的核心思路可以概括为一句话先把“模型说了什么”统一成Detections再用一套与模型无关的工具去处理它。官方关于文档指出该库围绕一个统一的DetectionsAPI 展开并为 Ultralytics、Roboflow Inference、Hugging Face Transformers、SAM、Detectron2、MMDetection、YOLO-NAS、PaddleDet、NCNN、Azure AI Vision 以及 Florence-2、PaliGemma、Qwen VL、Gemini、DeepSeek VL 2、Moondream 等 VLM 解析器提供了转换器converters。这种设计的直接收益是团队更换检测/分割/视觉语言模型时标注、过滤、跟踪、数据集处理与指标评估等下游代码无需重写——它们只消费Detections。仓库 首页 进一步说明与 RF-DETR 搭配时model.predict()会原生返回Detections连转换步骤都省掉。Supervision 由 Roboflow 与开源贡献者社区共同维护采用 MIT 许可证见 LICENSE.md在 GitHub 公开开发并发布到 PyPI。关于文档列出的核心维护与贡献者包括 Piotr Skalski、Borda、onuralpszr、Soumik Mandal 等这一事实也可在 pyproject.toml 的元数据中得到印证——maintainers字段登记了 Piotr Skalskipiotrroboflow.comauthors为 “Roboflow et al.”。安装与环境要求关于文档与 llms.txt 给出的安装方式非常简洁核心是 pippip install supervision其中metrics为可选依赖仅在需要指标相关功能时按需安装pip install supervision[metrics]示例资产下载工具sample asset utilities包含在基础包内的supervision.assets模块中。环境要求以仓库元数据为准。从 pyproject.toml 的requires-python 3.10可知最低 Python 版本为 3.10classifierspyproject.toml声明了 3.10 至 3.14 各版本以及 macOS / Windows / Linux 三大平台。当前开发版本号为 pyproject.toml 中的0.31.0.dev0。基础依赖pyproject.toml包括av、defusedxml、matplotlib、numpy、pillow、pydeprecate、pyyaml、requests、scipy、tqdm可选依赖还有geotiffrasterio用于地理栅格切片与metricspandas用于指标计算。核心数据结构 Detections库的“通用语言”Detections是整个库的枢纽每一个连接器connector、标注器annotator、跟踪器tracker都以它为输入或输出。它实现于 src/supervision/detection/core.py是一个dataclass字段定义清晰地列出了它能携带的信息xyxy形状(n, 4)的框坐标数组格式为[x1, y1, x2, y2]mask形状(n, H, W)的分割掩码bool类型无掩码时为None也可为更紧凑的CompactMaskconfidence形状(n,)的置信度缺失时为Noneclass_id形状(n,)的类别 ID缺失时为Nonetracker_id形状(n,)的跟踪器 ID缺失时为Nonedata字典用于存放逐检测per-detection的任意附加元数据如class_name每个 key 对应一个 NumPy 数组或列表metadata字典存放作用于整个检测集合的集合级元数据如视频名、相机参数、时间戳。在对象构造时会通过__post_init__调用_validate_detections_fields对各字段做一致性校验core.py保证各字段长度对齐。它实现了__len__、__iter__逐检测产出(xyxy, mask, confidence, class_id, tracker_id, data)元组与__eq__并支持 NumPy 风格的布尔索引可按类别、置信度、面积与空间区域进行过滤——这让“筛选检测”变成一行 NumPy 式表达式。模型连接器一套 from_* 类方法覆盖主流输出关于文档强调的“支持多种模型转换器”在源码层面落地为Detections上的一系列from_*类方法。以 core.py 中的定义为例from_ultralyticscore.py接受 Ultralytics 检测与分割结果from_inferencecore.py接受 Roboflow Inference 的检测与分割结果from_transformerscore.py接受 Hugging Face Transformers 输出需传入id2labelfrom_samcore.py与from_sam3接受 SAM 系列结果from_detectron2、from_mmdetection、from_yolo_nas、from_paddledet、from_ncnn、from_azure_analyze_image、from_tensorflow、from_deepsparse、from_easyocr等。core.py 顶部的 import 还引入了from_florence_2、from_paligemma、from_qwen_2_5_vl、from_qwen_3_vl、from_google_gemini_*、from_deepseek_vl_2、from_moondream等 VLM 解析器与from_lmm/from_vlm类方法配套覆盖视觉语言模型场景。一个典型调用模式来自 core.py 的文档示例from supervision import _cv2 as cv2 import supervision as sv from ultralytics import YOLO model YOLO(yolov8n.pt) image cv2.imread(SOURCE_IMAGE_PATH) results model(image)[0] detections sv.Detections.from_ultralytics(results)一旦得到Detections后续所有工具都只与它打交道模型来源的差异被隔离在from_*这一步之内——这正是“模型无关”的具体含义。工具链全景标注、跟踪、区域计数、数据集与指标Detections之上是一组围绕它构建的可组合工具。从 src/supervision/init.py 导出的公共 API__all__可以完整看到库的能力边界按用途分组如下标注annotatorsBoxAnnotator、MaskAnnotator、LabelAnnotator、RichLabelAnnotator、TraceAnnotator、HeatMapAnnotator、PixelateAnnotator、BlurAnnotator、OrientedBoxAnnotator、RoundBoxAnnotator等。标注器统一暴露annotate(scene..., detections...)传入输入图像与Detections即可得到画好标注的输出。LabelAnnotator可使用显式labels或回退到detections[class_name]、类别 ID、检测索引颜色可按类别分配或手动指定。跟踪tracker内置sv.ByteTrack通过update_with_detections()接受Detections并为跨帧对象分配持久 ID。需要注意根据 llms.txt 的说明该包装器已弃用deprecated转而推荐使用外部trackers包中的ByteTrackTracker对应方法名为update()。在源码里可以印证这一点ByteTrack被放入__all__但实际通过模块级__getattr__懒加载并附带弃用导出逻辑见init.py实现位于 src/supervision/tracker/byte_tracker/core.py。跟踪后的Detections可与sv.TraceAnnotator配合可视化轨迹。区域计数zonesv.PolygonZone用于任意多边形区域trigger(detections)返回“当前在多边形内”的检测布尔掩码sv.LineZone用于线穿越计数trigger(detections)返回(crossed_in, crossed_out)数组且依赖detections.tracker_id以跨帧匹配同一对象。两者通常搭配对应区域标注器使用。数据集datasetssv.DetectionDataset支持在 YOLO、COCO JSON、Pascal VOC、CreateML、LabelMe 五种格式间加载、合并、切分与转换见 src/supervision/dataset/core.py格式实现位于 src/supervision/dataset/formats/。sv.ClassificationDataset则通过from_folder_structure()导入、as_folder_structure()导出文件夹结构数据集。小目标检测sv.InferenceSlicer提供 SAHI 式推理切片——把高分辨率图像切成带重叠的瓦片、逐瓦片检测、再用 NMS 或 NMMnon-maximum merge合并结果瓦片重叠用像素单位的overlap_wh配置实现见 src/supervision/detection/tools/inference_slicer.py。结果落盘sv.CSVSink与sv.JSONSink以上下文管理器方式使用调用sink.append(detections, custom_data...)后每个检测写出一行/一个对象包含框坐标、置信度、类别 ID、跟踪 ID 与data字段。指标metrics用于基准测试。关于 mAP0.5:0.95官方建议从源码结构看使用supervision.metrics.MeanAveragePrecision通过update(...)累积预测与真值、再调用compute()而不是已弃用的顶层sv.MeanAveragePrecision.from_detections()混淆矩阵则用sv.ConfusionMatrix.from_detections(predictions..., targets..., classes...)生成实现位于 src/supervision/metrics/。一个可运行的最小示例仓库 首页 给出的快速示例展示了“模型 → Detections → 标注”的完整闭环可直接复制运行以 RF-DETR 为例需另装rfdetrimport 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)如果使用的是 Ultralytics / Inference / SAM 等模型则把model.predict(...)换成对应模型的推理结果再调用对应的sv.Detections.from_*得到Detections即可——标注器之后的流程完全一致。这正是关于文档所说的“更换模型而不重写下游代码”的直观体现。仓库examples/目录提供了多个贴近实战的完整脚本可作参考examples/tracking、examples/traffic_analysis、examples/count_people_in_zone、examples/heatmap_and_track、examples/speed_estimation、examples/time_in_zone 与 examples/compact_mask均配套各自的 README 与 requirements。文档与获取帮助Supervision 的文档站点允许通用爬虫与部分 AI 爬虫访问robots.txt明确放行 GPTBot、ClaudeBot、PerplexityBot、CCBot、GoogleOther 等见 llms.txt 的 “AI Access” 一节llms.txt同时整理了关键 API、How-To 指南、参考文档、Cookbooks 与 FAQ 的导航可作为检索入口。项目链接来自关于文档源码仓库 github.com/roboflow/supervision、PyPI 包 pypi.org/project/supervision、社区 Roboflow Discord 与 roboflow.com。引用与许可证如果 Supervision 用于研究或生产系统可引用项目仓库根目录提供了 CITATION.cffcff-version 1.2.0type: softwarelicense: MIT作者 Roboflow以及 llms.txt 中给出的 BibTeX 引用块software{supervision, author{Roboflow}, title{Supervision: Computer Vision Toolkit}, url{...}, year{2023}。许可证方面Supervision 采用 MIT 许可证完整条款见 LICENSE.md。小结Supervision 的价值在于把一个高度重复、且常被“换个模型就重写一遍”的环节——检测结果的表示与后处理——沉淀为一个稳定的核心数据结构Detectionscore.py与一组只与它交互的通用工具。理解这一点就抓住了 关于文档 的主线统一表示Detections与各from_*连接器是主体标注、跟踪、区域计数、数据集转换、小目标切片与指标评估都是围绕它生长的可组合工具。对开发者而言只要把模型输出落到Detections后续所有能力都能以一致、可复用的方式接入这正是该库“模型无关”承诺的技术基础。【免费下载链接】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本篇基于 Supervision 仓库的 关于文档 及其源码解析这个由 Roboflow 维护的开源 Python 计算机视觉库。Supervision 的定位是为开发者提供一套模型无关model-agnostic的工具包加载模型预测结果、在图像与视频上画标注、跨帧跟踪、区域计数、数据集格式转换以及模型性能评估。读完本文你将理解其核心数据结构Detections为何是整个库的“通用语言”、它支持哪些模型输出转换器、如何安装配置以及标注、跟踪、数据集与指标等各模块的源码落点从而能把它接入自己的视觉流水线而不必为更换模型重写后处理代码。项目定位把模型输出统一为一种数据表示Supervision 的核心思路可以概括为一句话先把“模型说了什么”统一成Detections再用一套与模型无关的工具去处理它。官方关于文档指出该库围绕一个统一的DetectionsAPI 展开并为 Ultralytics、Roboflow Inference、Hugging Face Transformers、SAM、Detectron2、MMDetection、YOLO-NAS、PaddleDet、NCNN、Azure AI Vision 以及 Florence-2、PaliGemma、Qwen VL、Gemini、DeepSeek VL 2、Moondream 等 VLM 解析器提供了转换器converters。这种设计的直接收益是团队更换检测/分割/视觉语言模型时标注、过滤、跟踪、数据集处理与指标评估等下游代码无需重写——它们只消费Detections。仓库 首页 进一步说明与 RF-DETR 搭配时model.predict()会原生返回Detections连转换步骤都省掉。Supervision 由 Roboflow 与开源贡献者社区共同维护采用 MIT 许可证见 LICENSE.md在 GitHub 公开开发并发布到 PyPI。关于文档列出的核心维护与贡献者包括 Piotr Skalski、Borda、onuralpszr、Soumik Mandal 等这一事实也可在 pyproject.toml 的元数据中得到印证——maintainers字段登记了 Piotr Skalskipiotrroboflow.comauthors为 “Roboflow et al.”。安装与环境要求关于文档与 llms.txt 给出的安装方式非常简洁核心是 pippip install supervision其中metrics为可选依赖仅在需要指标相关功能时按需安装pip install supervision[metrics]示例资产下载工具sample asset utilities包含在基础包内的supervision.assets模块中。环境要求以仓库元数据为准。从 pyproject.toml 的requires-python 3.10可知最低 Python 版本为 3.10classifierspyproject.toml声明了 3.10 至 3.14 各版本以及 macOS / Windows / Linux 三大平台。当前开发版本号为 pyproject.toml 中的0.31.0.dev0。基础依赖pyproject.toml包括av、defusedxml、matplotlib、numpy、pillow、pydeprecate、pyyaml、requests、scipy、tqdm可选依赖还有geotiffrasterio用于地理栅格切片与metricspandas用于指标计算。核心数据结构 Detections库的“通用语言”Detections是整个库的枢纽每一个连接器connector、标注器annotator、跟踪器tracker都以它为输入或输出。它实现于 src/supervision/detection/core.py是一个dataclass字段定义清晰地列出了它能携带的信息xyxy形状(n, 4)的框坐标数组格式为[x1, y1, x2, y2]mask形状(n, H, W)的分割掩码bool类型无掩码时为None也可为更紧凑的CompactMaskconfidence形状(n,)的置信度缺失时为Noneclass_id形状(n,)的类别 ID缺失时为Nonetracker_id形状(n,)的跟踪器 ID缺失时为Nonedata字典用于存放逐检测per-detection的任意附加元数据如class_name每个 key 对应一个 NumPy 数组或列表metadata字典存放作用于整个检测集合的集合级元数据如视频名、相机参数、时间戳。在对象构造时会通过__post_init__调用_validate_detections_fields对各字段做一致性校验core.py保证各字段长度对齐。它实现了__len__、__iter__逐检测产出(xyxy, mask, confidence, class_id, tracker_id, data)元组与__eq__并支持 NumPy 风格的布尔索引可按类别、置信度、面积与空间区域进行过滤——这让“筛选检测”变成一行 NumPy 式表达式。模型连接器一套 from_* 类方法覆盖主流输出关于文档强调的“支持多种模型转换器”在源码层面落地为Detections上的一系列from_*类方法。以 core.py 中的定义为例from_ultralyticscore.py接受 Ultralytics 检测与分割结果from_inferencecore.py接受 Roboflow Inference 的检测与分割结果from_transformerscore.py接受 Hugging Face Transformers 输出需传入id2labelfrom_samcore.py与from_sam3接受 SAM 系列结果from_detectron2、from_mmdetection、from_yolo_nas、from_paddledet、from_ncnn、from_azure_analyze_image、from_tensorflow、from_deepsparse、from_easyocr等。core.py 顶部的 import 还引入了from_florence_2、from_paligemma、from_qwen_2_5_vl、from_qwen_3_vl、from_google_gemini_*、from_deepseek_vl_2、from_moondream等 VLM 解析器与from_lmm/from_vlm类方法配套覆盖视觉语言模型场景。一个典型调用模式来自 core.py 的文档示例from supervision import _cv2 as cv2 import supervision as sv from ultralytics import YOLO model YOLO(yolov8n.pt) image cv2.imread(SOURCE_IMAGE_PATH) results model(image)[0] detections sv.Detections.from_ultralytics(results)一旦得到Detections后续所有工具都只与它打交道模型来源的差异被隔离在from_*这一步之内——这正是“模型无关”的具体含义。工具链全景标注、跟踪、区域计数、数据集与指标Detections之上是一组围绕它构建的可组合工具。从 src/supervision/init.py 导出的公共 API__all__可以完整看到库的能力边界按用途分组如下标注annotatorsBoxAnnotator、MaskAnnotator、LabelAnnotator、RichLabelAnnotator、TraceAnnotator、HeatMapAnnotator、PixelateAnnotator、BlurAnnotator、OrientedBoxAnnotator、RoundBoxAnnotator等。标注器统一暴露annotate(scene..., detections...)传入输入图像与Detections即可得到画好标注的输出。LabelAnnotator可使用显式labels或回退到detections[class_name]、类别 ID、检测索引颜色可按类别分配或手动指定。跟踪tracker内置sv.ByteTrack通过update_with_detections()接受Detections并为跨帧对象分配持久 ID。需要注意根据 llms.txt 的说明该包装器已弃用deprecated转而推荐使用外部trackers包中的ByteTrackTracker对应方法名为update()。在源码里可以印证这一点ByteTrack被放入__all__但实际通过模块级__getattr__懒加载并附带弃用导出逻辑见init.py实现位于 src/supervision/tracker/byte_tracker/core.py。跟踪后的Detections可与sv.TraceAnnotator配合可视化轨迹。区域计数zonesv.PolygonZone用于任意多边形区域trigger(detections)返回“当前在多边形内”的检测布尔掩码sv.LineZone用于线穿越计数trigger(detections)返回(crossed_in, crossed_out)数组且依赖detections.tracker_id以跨帧匹配同一对象。两者通常搭配对应区域标注器使用。数据集datasetssv.DetectionDataset支持在 YOLO、COCO JSON、Pascal VOC、CreateML、LabelMe 五种格式间加载、合并、切分与转换见 src/supervision/dataset/core.py格式实现位于 src/supervision/dataset/formats/。sv.ClassificationDataset则通过from_folder_structure()导入、as_folder_structure()导出文件夹结构数据集。小目标检测sv.InferenceSlicer提供 SAHI 式推理切片——把高分辨率图像切成带重叠的瓦片、逐瓦片检测、再用 NMS 或 NMMnon-maximum merge合并结果瓦片重叠用像素单位的overlap_wh配置实现见 src/supervision/detection/tools/inference_slicer.py。结果落盘sv.CSVSink与sv.JSONSink以上下文管理器方式使用调用sink.append(detections, custom_data...)后每个检测写出一行/一个对象包含框坐标、置信度、类别 ID、跟踪 ID 与data字段。指标metrics用于基准测试。关于 mAP0.5:0.95官方建议从源码结构看使用supervision.metrics.MeanAveragePrecision通过update(...)累积预测与真值、再调用compute()而不是已弃用的顶层sv.MeanAveragePrecision.from_detections()混淆矩阵则用sv.ConfusionMatrix.from_detections(predictions..., targets..., classes...)生成实现位于 src/supervision/metrics/。一个可运行的最小示例仓库 首页 给出的快速示例展示了“模型 → Detections → 标注”的完整闭环可直接复制运行以 RF-DETR 为例需另装rfdetrimport 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)如果使用的是 Ultralytics / Inference / SAM 等模型则把model.predict(...)换成对应模型的推理结果再调用对应的sv.Detections.from_*得到Detections即可——标注器之后的流程完全一致。这正是关于文档所说的“更换模型而不重写下游代码”的直观体现。仓库examples/目录提供了多个贴近实战的完整脚本可作参考examples/tracking、examples/traffic_analysis、examples/count_people_in_zone、examples/heatmap_and_track、examples/speed_estimation、examples/time_in_zone 与 examples/compact_mask均配套各自的 README 与 requirements。文档与获取帮助Supervision 的文档站点允许通用爬虫与部分 AI 爬虫访问robots.txt明确放行 GPTBot、ClaudeBot、PerplexityBot、CCBot、GoogleOther 等见 llms.txt 的 “AI Access” 一节llms.txt同时整理了关键 API、How-To 指南、参考文档、Cookbooks 与 FAQ 的导航可作为检索入口。项目链接来自关于文档源码仓库 github.com/roboflow/supervision、PyPI 包 pypi.org/project/supervision、社区 Roboflow Discord 与 roboflow.com。引用与许可证如果 Supervision 用于研究或生产系统可引用项目仓库根目录提供了 CITATION.cffcff-version 1.2.0type: softwarelicense: MIT作者 Roboflow以及 llms.txt 中给出的 BibTeX 引用块software{supervision, author{Roboflow}, title{Supervision: Computer Vision Toolkit}, url{...}, year{2023}。许可证方面Supervision 采用 MIT 许可证完整条款见 LICENSE.md。小结Supervision 的价值在于把一个高度重复、且常被“换个模型就重写一遍”的环节——检测结果的表示与后处理——沉淀为一个稳定的核心数据结构Detectionscore.py与一组只与它交互的通用工具。理解这一点就抓住了 关于文档 的主线统一表示Detections与各from_*连接器是主体标注、跟踪、区域计数、数据集转换、小目标切片与指标评估都是围绕它生长的可组合工具。对开发者而言只要把模型输出落到Detections后续所有能力都能以一致、可复用的方式接入这正是该库“模型无关”承诺的技术基础。【免费下载链接】supervisionWe write your reusable computer vision tools. 项目地址: https://gitcode.com/GitHub_Trending/su/supervision创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考