10 分钟上手 supervision：把 YOLO 输出变成会数人头、画轨迹的成品应用

10 分钟上手 supervision把 YOLO 输出变成会数人头、画轨迹的成品应用【免费下载链接】supervisionWe write your reusable computer vision tools. 项目地址: https://gitcode.com/GitHub_Trending/su/supervision跑通一个 YOLO 检测模型只需几十行代码但真正把它变成能用的产品——给检测框上色、写类别标签、统计某块区域里进了几个人、画出每个人的运动轨迹、把结果存成带字幕的视频——这些推理之后的活往往比训练模型本身更让人头疼。每个项目都要重写一遍 OpenCV 绘图、计数、坐标转换的胶水代码换一个模型框架又得重来一次。这正是 Roboflow 开源的 supervision 想要解决的问题它定位在模型层与业务系统之间用统一的Detections数据结构把 YOLO、RT-DETR、SAM、Hugging Face Transformers 等异构输出翻译成一套标准接口再提供标注、追踪、区域计数、视频处理等即插即用的成品工具。这个库长期霸榜 GitHub 热门仓库社区热度同样可观一度登顶 GitHub 日榜、月下载量超过 110 万次也被 HelloGitHub 等开源社区持续收录。本文不聊理论直接带着源码证据从安装到跑通区域计数 轨迹绘制的完整应用全程控制在 10 分钟的量级。一、安装与最小示例从检测结果到可视化只差三行supervision 对运行环境的要求很低Python3.10即可见 README.md一条命令完成安装pip install supervision安装完成后核心用法就是把任意模型的输出转换成sv.Detections再交给标注器渲染。以最常见的 Ultralytics YOLO 为例官方教程 docs/how_to/detect_and_annotate.md 给出了标准流程——模型推理、结果转换、链式标注import 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)从模型输出到带框带标签的成品图真正的逻辑代码只有三行from_ultralytics负责转换BoxAnnotator画框LabelAnnotator写字。这也是 supervision 贯穿始终的设计哲学——Annotator 家族是可组合的积木。查看 src/supervision/init.py 的导出清单能看到 20 多个标注器MaskAnnotator掩膜、BoxCornerAnnotator角框、HaloAnnotator光晕、HeatMapAnnotator热力图、TraceAnnotator轨迹、PixelateAnnotator打码等等任意组合叠加到同一帧画面上即可互不干扰。为什么能这样统一关键在于Detections这个数据结构。在 src/supervision/detection/core.py 中它被定义为一个 dataclass固定承载六个字段xyxy边界框坐标、mask分割掩膜、confidence置信度、class_id类别编号、tracker_id追踪编号以及附加的data字典。无论你用的是 Ultralytics、Roboflow Inference、Detectron2 还是 Transformers最后都折叠进这一套字段下游所有工具只认这一种输入。文档中对应的方法有from_ultralytics、from_inference、from_transformers、from_detectron2、from_sam等多个适配器换模型只换一行转换代码其余管线原样复用。二、区域计数与行人轨迹一个场景跑通核心能力如果说标注可视化只是锦上添花那么区域计数和轨迹绘制才是 supervision 被大量工程落地方案选中的硬核能力——社区里已有人用它搭建了地铁环境和公路车流的行人计数与轨迹追踪系统。2.1 区域计数PolygonZone 的锚点判定区域计数的核心类在 src/supervision/detection/tools/polygon_zone.py。PolygonZone的判定逻辑很值得细读它默认取每个检测框的BOTTOM_CENTER底部中心作为触发锚点把多边形区域预先生成一张二值 mask每帧调用zone.trigger(detections)时只需做一次数组索引查表——锚点是否落在 mask 内命中数量即current_count。这种锚点 查表的设计避免了逐帧多边形裁剪的开销是它能跑实时视频的原因之一。官方教程 docs/how_to/count_in_zone.md 展示了完整用法先用多边形坐标构造多个PolygonZone配上各自颜色的PolygonZoneAnnotator渲染区域边框和计数文字与BoxAnnotator渲染框然后在逐帧回调里触发计数zones [sv.PolygonZone(polygonpolygon) for polygon in polygons] zone_annotators [ sv.PolygonZoneAnnotator( zonezone, colorcolors.by_idx(index), thickness4, text_thickness8, text_scale4, ) for index, zone in enumerate(zones) ] def process_frame(frame: np.ndarray, i) - np.ndarray: detections model.predict(frame[:, :, ::-1]) for zone, zone_annotator, box_annotator in zip(zones, zone_annotators, box_annotators): mask zone.trigger(detectionsdetections) detections_filtered detections[mask] frame box_annotator.annotate(sceneframe, detectionsdetections_filtered) frame zone_annotator.annotate(sceneframe) return frame sv.process_video(source_pathVIDEO, target_pathresult.mp4, callbackprocess_frame)注意sv.process_video这个封装传入一个回调函数supervision 自动完成逐帧读取、回调、写盘的全流程视频处理的样板代码同样被压缩成一行。仓库里还提供了可直接运行的多区域示例 examples/count_people_in_zone/inference_example.py配套了四种区域配置文件examples/count_people_in_zone/data/下的横向、纵向、多区域、四宫格 JSON并演示了两种输出方式用sv.VideoSink写出成品视频或用sv.ImageWindow弹窗实时预览——后者正是成品应用的雏形。2.2 越线计数LineZone 的方向判断与区域驻留统计互补的是越线计数。LineZonesrc/supervision/detection/line_zone.py统计穿越一条线的进出人数返回(crossed_in, crossed_out)两个布尔数组并维护in_count/out_count计数。它的内部实现比表面看起来严谨得多通过叉积判断检测框四个角相对直线的左右侧用连续minimum_crossing_threshold帧保持在新一侧才确认一次穿越从而过滤掉检测框抖动造成的误计对 ByteTrack 单帧丢帧的coasting间隙也会保留穿越状态不会过早重置。但LineZone有一个硬性前提必须传入tracker_id。同一物体在相邻帧之间是谁只有追踪器能回答。这也自然引出下一个能力。2.3 画轨迹追踪让检测拥有身份追踪的本质是把逐帧独立的检测结果关联成同一物体的时间序列。参考仓库示例 examples/tracking/inference_example.py集成 ByteTrack 的代码非常直观from trackers import ByteTrackTracker tracker ByteTrackTracker(track_activation_thresholdconfidence_threshold) ... detections sv.Detections.from_inference(results) detections tracker.update(detections) detections detections[detections.tracker_id ! -1] # 丢弃未确认的轨迹拿到稳定的tracker_id后轨迹可视化交给TraceAnnotatorsrc/supervision/annotators/core.py 中的实现。它以tracker_id为 key 维护每个目标的历史坐标点默认保留最近 30 帧位置并连成折线smoothTrue时还会用样条插值把折线磨成平滑曲线让轨迹不再是一根根生硬的线段。如果检测框本身抖动严重还可以叠加DetectionsSmoothersrc/supervision/detection/tools/smoother.py对每个 track 的历史做平滑先稳框、再画线、再计数一套流水线下来输出质量会明显提升。把区域计数和轨迹绘制拼到一起就是社区案例里客流量分析统计系统的完整骨架检测 → 追踪 → 区域计数 / 轨迹渲染 → 视频写出所有环节都由 supervision 的标准积木搭成。三、进阶钩子置信度过滤、颜色定制与实时性能3.1 置信度过滤与 NMS一行搞定后处理在 src/supervision/detection/core.py 的文档示例中Detections支持 NumPy 风格的布尔索引detections detections[detections.confidence 0.5] # 置信度过滤 detections detections[detections.class_id 0] # 类别过滤底层是__getitem__实现的select逻辑切片、列表、布尔数组都能直接索引xyxy、confidence、class_id等所有字段同步截取不会出现框和分数对不上的经典 bug。此外还有with_nms/with_soft_nms方法做非极大值抑制IoU 阈值与是否类别无关均可配置多模型叠加出框的脏活也被收编成方法调用。3.2 颜色定制从调色板到按轨迹着色supervision 的颜色体系在 src/supervision/draw/color.py 中定义Color是单一颜色ColorPalette.DEFAULT是默认多色调色板。区域计数示例里用colors.by_idx(index)给每个区域分配不同颜色实现一区一色。更精细的定制靠color_lookup参数它支持CLASS同类同色、INDEX按检测顺序循环取色和TRACK同一追踪目标恒为同一色。其中TRACK模式对轨迹应用尤其重要——只有按tracker_id恒定着色观众才能从颜色上直观分辨这条线是哪个人走的。3.3 实时性能自适应绘制与监控工具面向实时场景supervision 提供了几项实用设计分辨率自适应sv.calculate_optimal_line_thickness与sv.calculate_optimal_text_scale会根据视频分辨率自动计算合适的线宽和字号避免在高清视频里画出又细又小的标注见 examples/count_people_in_zone/inference_example.pyFPS 监控sv.FPSMonitor可以统计实际处理帧率判断你的管线是否达到实时要求定义于 src/supervision/utils/video.py视频 IO 全套封装get_video_frames_generator生成逐帧迭代器、VideoInfo读取元数据、VideoSink以上下文管理器写出成品视频配合ImageWindow弹窗预览一套完整的读取 → 处理 → 展示/落盘闭环不需要手写任何 OpenCV 样板代码。值得一提的是supervision 本身不做模型推理它只负责推理之后的一切因此天然与任何检测、分割、关键点乃至视觉语言模型VLM兼容——from_vlm甚至能把 Gemini、Qwen-VL 等大模型的文本输出解析回检测框。这意味着你当前使用的模型框架完全不影响迁移成本换模型只换一行转换代码。从三行出图到区域计数 轨迹绘制 视频落盘supervision 把 CV 工程里最高频、最重复的胶水逻辑全部标准化了。如果你正在为检测结果的可视化、统计和追踪重复造轮子与其继续手写 OpenCV 循环不如把它加进依赖清单——它很可能就是你下一套 CV 应用的最后一公里。【免费下载链接】supervisionWe write your reusable computer vision tools. 项目地址: https://gitcode.com/GitHub_Trending/su/supervision创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考