Ultralytics 区域计数（Region Counter）实战指南：用 YOLO 在视频流中对指定多边形区域进行对象计数

Ultralytics 区域计数Region Counter实战指南用 YOLO 在视频流中对指定多边形区域进行对象计数【免费下载链接】ultralyticsUltralytics YOLO26, YOLO11, YOLOv8 — object detection, instance segmentation, semantic segmentation, image classification, pose estimation, object tracking项目地址: https://gitcode.com/GitHub_Trending/ul/ultralytics导读区域计数Region Counting是一种在视频画面中预先划定若干区域多边形/矩形实时统计落入每个区域内对象数量的计算机视觉技术。本指南以 YOLOv8-Region-Counter 示例 为主线完整讲解基于 Ultralytics YOLO11 的独立脚本实现从环境安装、命令行运行、参数定制到鼠标交互拖拽区域、自定义多边形区域与计数逻辑的源码级原理同时介绍其官方演进版本RegionCounter解决方案位于 region-counting.md帮助读者从「跑通示例」进阶到「读懂实现、按需改造」最终能独立完成客流统计、车流监控、多区域同时计数等实战任务。注意本示例脚本目前仍保留在仓库中但已不再积极维护官方推荐使用 Ultralytics Solutions 中的 RegionCounter 解决方案 获取持续更新的功能。什么是区域计数区域计数是指在视频流的每一帧中对预先定义的区域Region / Zone内的对象数量进行统计。与「跨线计数」不同区域计数关注的是某个时刻某个区域内有多少对象即区域的当前占有率occupancy。该技术尤其适合同时监控多个互不重叠的区域例如零售门店分析统计不同货架通道、收银区的人流量交通分析统计路口各车道、各方向的车辆数安防监控统计仓库作业区、禁入区域的占用情况工业质检统计传送带分拣区内工件数量。本示例脚本支持通过鼠标左键点击并拖拽的方式在视频播放过程中实时调整计数区域的位置无需修改代码即可适配不同的画面布局。Step 1环境安装示例位于仓库的examples/YOLOv8-Region-Counter/目录下运行前需要 Python 环境以及 PyTorch、OpenCV 等依赖。# 克隆 ultralytics 仓库 git clone https://gitcode.com/GitHub_Trending/ul/ultralytics # 进入示例目录 cd ultralytics/examples/YOLOv8-Region-Counter # 安装所需依赖如尚未安装 pip install ultralytics shapely依赖说明ultralytics提供 YOLO 模型加载、推理、跟踪与可视化能力shapely用于多边形几何定义与「点是否在多边形内」的包含判定。官方RegionCounter解决方案要求shapely2.0.0见 solutions.py 中的check_requirements。Step 2运行区域计数脚本入口为 yolov8_region_counter.py通过--source指定输入视频即可运行# 对视频进行推理保存结果并实时显示 python yolov8_region_counter.py --source path/to/video.mp4 --save-img --view-img # 使用 CPU 进行推理 python yolov8_region_counter.py --source path/to/video.mp4 --save-img --view-img --device cpu # 指定具体的 YOLO11 模型文件 python yolov8_region_counter.py --source path/to/video.mp4 --save-img --weights path/to/yolo11n.pt # 只检测指定类别如类别 0 和 2 python yolov8_region_counter.py --source path/to/video.mp4 --classes 0 2 --weights path/to/yolo11m.pt # 仅实时显示不保存输出视频 python yolov8_region_counter.py --source path/to/video.mp4 --view-img交互操作说明视频播放窗口的标题为Ultralytics YOLO Region Counter Movable打开后即可进行交互左键点击区域内部选中该计数区域按住左键拖拽整体平移该区域到新位置所有顶点同步移动松开左键完成本次拖拽区域固定在新位置。该交互由源码中的mouse_callback回调实现见 yolov8_region_counter.pycv2.EVENT_LBUTTONDOWN时遍历counting_regions用region[polygon].contains(Point((x, y)))判断鼠标点是否落在某个区域内并记录拖拽偏移量cv2.EVENT_MOUSEMOVE时按坐标增量dx/dy重建多边形cv2.EVENT_LBUTTONUP时结束拖拽。命令行参数说明Usage Options脚本通过argparse解析参数见 parse_opt全部参数如下参数类型/默认值说明--sourcestr必填输入视频文件路径--weightsstr默认yolo11n.ptYOLO 模型权重路径.pt--devicestr默认空计算设备cpu或 GPU ID如0--view-imgstore_true布尔开关实时显示输出视频流--save-imgstore_true布尔开关保存带检测结果的输出帧/视频--exist-okstore_true允许复用已有输出目录而不自动递增编号--classesnargsint 列表按类别 ID 过滤检测结果如--classes 0 2 3--line-thicknessint默认2检测框bounding box线宽--track-thicknessint默认2对象跟踪轨迹线线宽--region-thicknessint默认4计数区域边界线宽几点使用细节对应run函数实现见 yolov8_region_counter.py设备切换源码中model.to(cuda) if device 0 else model.to(cpu)仅将字符串0映射到 CUDA其余一律走 CPU如需使用其他 GPU 编号或cuda:0写法需要自行调整该判断逻辑。输出目录保存结果写入ultralytics_rc_output/exp通过increment_path自动递增编号避免覆盖视频以mp4v编码、与输入同帧率尺寸输出为.avi文件。跟踪与计数逐帧调用model.track(frame, persistTrue, classesclasses)对每个跟踪对象计算检测框中心((x1x2)/2, (y1y2)/2)再用 shapely 的polygon.contains(Point(...))判断是否落入某区域命中则region[counts] 1。每帧处理结束后所有区域计数会被重置为 0见第 216-217 行因此画面上的数字是「当前帧该区域内对象数」而非累计值。跟踪轨迹每个 track_id 保留最近 30 个中心点并绘制轨迹折线track-thickness控制线宽。退出方式显示窗口时按q键结束。自定义计数区域Region 配置默认配置在脚本顶部以列表counting_regions定义见 yolov8_region_counter.py每个区域是一个字典字段含义如下from shapely.geometry import Polygon counting_regions [ { name: Region 1 (Pentagon), polygon: Polygon([(50, 80), (250, 20), (450, 80), (400, 350), (100, 350)]), # 5 点多边形 counts: 0, dragging: False, region_color: (255, 42, 4), # 区域颜色OpenCV BGR 格式 text_color: (255, 255, 255), # 区域内计数文字颜色BGR }, { name: Region 2 (Rectangle), polygon: Polygon([(200, 250), (440, 250), (440, 550), (200, 550)]), # 4 点矩形 counts: 0, dragging: False, region_color: (37, 255, 225), # BGR text_color: (0, 0, 0), # BGR }, ]自定义要点任意多边形Polygon接受任意数量顶点坐标至少 3 个点矩形只是 4 点的特殊多边形顶点坐标为像素坐标(x, y)需与视频分辨率匹配区域颜色注意这里是BGR顺序OpenCV 约定(255, 42, 4)实际显示为橙红色交互状态dragging在运行时由鼠标回调维护初始为False数量无上限列表中可以添加任意多个区域脚本会为每个区域独立绘制边界并显示独立计数。区域可视化由run函数末尾的绘制循环完成见 yolov8_region_counter.py先以cv2.getTextSize测量数字尺寸在区域质心polygon.centroid处绘制带背景色的计数文本再以cv2.polylines闭合绘制区域边界。FAQ常见问题与进阶话题Q1区域计数支持自定义区域形状吗支持。区域既可以是任意多边形也可以是矩形矩形即 4 点多边形坐标、名称、颜色均可直接在脚本中修改底层使用 shapely 的Polygon完成几何定义与包含判定。Q2为什么要将区域计数与 YOLO 结合Ultralytics YOLO 系列模型擅长视频流中的目标检测与跟踪。将区域计数叠加在检测跟踪之上即可在「知道画面里有什么对象、对象在哪」的基础上进一步量化「特定区域里有多少对象」支撑人群密度监控、车流分析、零售到店客流统计等场景。Q3如何排查运行问题确认--source视频路径与--weights模型路径正确无误脚本会在启动时检查源路径是否存在不存在会抛出FileNotFoundError脚本没有专用的--debug参数可以在源码中插入print语句检查变量或使用标准 Python 调试工具若安装了完整版 Ultralytics 文档可参考其 FAQ 中的常见问题说明FAQ。Q4可以使用其他 YOLO 版本或自定义模型吗可以。通过--weights指定任意 Ultralytics 兼容的.pt文件即可包括 YOLOv5、YOLOv9、YOLOv10、YOLO11 等官方模型或你自己训练得到的模型文件。自定义模型的训练方式参见 训练模式文档。进阶官方 RegionCounter 解决方案作为本示例的官方演进版本Ultralytics Solutions 中的RegionCounter见 region_counter.py提供了更工程化、持续维护的替代实现支持传入多个命名区域并以可编程方式读取计数结果。其核心差异与优势如下区域定义更灵活region参数既可以是单个点列表自动命名为Region#01也可以是「区域名 → 点列表」的字典实现多区域独立计数结果可编程读取每次调用返回SolutionResults对象包含plot_im标注帧、region_counts区域名 → 计数、total_tracks跟踪对象总数等字段见 solutions.py内置跟踪管线底层BaseSolution.extract_tracks直接调用model.track见 solutions.py无需额外接线支持跟踪/可视化参数可配置tracker、conf、iou、classes、device以及show、show_conf、show_labels等。官方版本运行示例CLI 方式更多用法见 region-counting.md# 运行默认区域计数示例 yolo solutions region showTrue # 指定输入视频 yolo solutions region sourcepath/to/video.mp4 # 指定自定义区域 yolo solutions region region[(20, 400), (1080, 400), (1080, 360), (20, 360)]Python 方式多区域 结果读取import cv2 from ultralytics import solutions cap cv2.VideoCapture(path/to/video.mp4) assert cap.isOpened(), Error reading video file # 以字典形式传入多个命名区域 region_points { region-01: [(50, 50), (250, 50), (250, 250), (50, 250)], region-02: [(640, 640), (780, 640), (780, 720), (640, 720)], } # 视频写出器 w, h, fps (int(cap.get(x)) for x in (cv2.CAP_PROP_FRAME_WIDTH, cv2.CAP_PROP_FRAME_HEIGHT, cv2.CAP_PROP_FPS)) video_writer cv2.VideoWriter(region_counting.avi, cv2.VideoWriter_fourcc(*mp4v), fps, (w, h)) # 初始化区域计数器 regioncounter solutions.RegionCounter( showTrue, # 实时显示画面 regionregion_points, # 传入区域点 modelyolo26n.pt, # 计数所用模型如 yolo26s.pt ) while cap.isOpened(): success, im0 cap.read() if not success: print(Video frame is empty or processing is complete.) break results regioncounter(im0) # results.region_counts: {region-01: n, region-02: n} —— 可在业务代码中直接使用 video_writer.write(results.plot_im) cap.release() video_writer.release() cv2.destroyAllWindows()官方 RegionCounter 参数速查基础参数来自 solutions-args.md参数类型默认值说明modelstrNone默认yolo26n.ptUltralytics YOLO 模型文件路径regionlist 或 dictNone区域点(x, y)元组列表或「区域名 → 点列表」字典仅RegionCounter支持字典为None时使用内置默认区域line_widthint2检测框、关键点与计数的绘制线宽verboseboolTrue逐帧输出输入尺寸、类别统计与处理速度日志跟踪参数来自 solutions-track-args.md参数类型默认值说明trackerstrbotsort.yaml跟踪算法配置内置botsort.yaml、bytetrack.yaml、ocsort.yaml、deepocsort.yaml、fasttrack.yaml、tracktrack.yaml见 trackers 配置目录conffloat0.25检测置信度阈值调低会跟踪更多对象但可能引入误检ioufloat0.7重叠检测框过滤的 IoU 阈值classeslistNone按类别索引过滤如classes[0]仅计数人COCO 预训练模型devicestrNone推理设备如cpu、cuda:0或0可视化参数来自 visualization-args.md参数类型默认值说明showboolFalse是否弹出窗口实时显示标注画面show_confboolTrue是否在标签中显示置信度show_labelsboolTrue是否显示检测标签官方版本的工作原理RegionCounter继承自BaseSolution见 solutions.py每帧的处理流程对应process方法见 region_counter.py为通过extract_tracks完成 YOLO 检测与跟踪取出每个对象的检测框、类别、跟踪 ID 与置信度对每个跟踪对象用get_enclosing_box归一化检测框兼容普通检测框与 OBB 四点框计算框中心坐标并逐一与各区域的预编译多边形prepared_polygon基于 shapelyprep加速包含查询做包含判定命中区域则累加计数随后在区域质心处以背景色块 文本方式绘制当前计数每帧处理结束后重置计数返回SolutionResults其中region_counts字典可直接对接看板、告警或日志系统。值得注意的语义差异官方RegionCounter与示例脚本一样显示的是「当前帧的区域占用数」而非累计通过数。若需要统计对象跨越区域/线段边界的累计进出数量应改用 ObjectCounter 解决方案object_counting.py若需要在一个区域内持续跟随单个对象可参考 TrackZone。小结通过本指南你可以掌握两类区域计数落地方式轻量示例脚本yolov8_region_counter.py开箱即用支持鼠标拖拽实时调整区域、按类别过滤、CPU/GPU 切换适合快速验证与教学官方RegionCounter解决方案region_counter.py多命名区域、结果可编程读取、参数体系完整适合集成到正式业务系统中。无论选择哪种方式其核心逻辑是一致的检测跟踪对象 → 计算检测框中心 → 判断中心是否落在多边形区域内 → 绘制并输出每帧区域计数。理解这一原理后你就能根据实际场景自由扩展区域数量、形状与业务逻辑。相关资源示例说明文档examples/YOLOv8-Region-Counter/README.md官方区域计数指南docs/en/guides/region-counting.md解决方案源码ultralytics/solutions/region_counter.py 与基类 ultralytics/solutions/solutions.py跟踪器配置ultralytics/cfg/trackers/其他解决方案边界跨越累计计数 ObjectCounter、单区域对象跟随 TrackZone【免费下载链接】ultralyticsUltralytics YOLO26, YOLO11, YOLOv8 — object detection, instance segmentation, semantic segmentation, image classification, pose estimation, object tracking项目地址: https://gitcode.com/GitHub_Trending/ul/ultralytics创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考