Ultralytics RegionCounter 源码级解析实时视频多区域目标计数与 YOLO26 实践指南【免费下载链接】ultralyticsUltralytics YOLO26, YOLO11, YOLOv8 — object detection, instance segmentation, semantic segmentation, image classification, pose estimation, object tracking项目地址: https://gitcode.com/GitHub_Trending/ul/ultralytics导读本文围绕 Ultralytics 仓库中的 RegionCounter API 参考文档 与 区域计数实战指南深入讲解RegionCounter类的设计结构、逐帧计数工作原理、多区域配置方法、完整参数表与可编程读取方式。读完你可以在零售客流、道路车流、生产区域等多区域监控场景中用几行代码同时监控多个多边形区域的当前占用人数/物数并能理解其与跨界累计计数ObjectCounter的本质差异。什么是 RegionCounter一次推理、多个区域、逐帧占用计数RegionCounter是定义在 ultralytics/solutions/region_counter.py 中的一个解决方案类继承自 BaseSolution。它做的事情是对视频流中的每一帧执行 YOLO 检测与多目标跟踪然后判断每个被跟踪目标的检测框中心点落在你定义的哪些多边形区域内并在画面上实时绘制每个区域内部的当前目标数量。从源码结构可以概括出它的三大设计要点多区域并行region参数既可以传一个多边形点列表单区域也可以传区域名 → 点列表的字典多区域每个区域拥有独立命名、独立颜色、独立计数追踪内置计数依赖 YOLO 跟踪得到的track_id保持跨帧一致性无需另外接入追踪管线结果可编程读取每次处理返回的 SolutionResults 对象携带region_counts字典可对接仪表盘、告警或日志。需要特别强调的是语义RegionCounter显示的数值是当前帧内处于该区域中的目标数即占用数 occupancy而非累计进出总量。因为源码中每处理完一帧都会把计数重置为 0见下文process方法所以画面上的数字表示此刻有多少个目标在该区域内。若要统计穿越边界的累计进出量应改用 ObjectCounter。类结构RegionCounter的模块骨架RegionCounter类的声明文档与 Docstring 集中在 region_counter.py它自身只维护三个核心状态外加由BaseSolution继承的通用配置与追踪数据。关键属性属性类型说明region_templatedict创建新计数区域的模板含默认属性name默认Default Region、polygon、prepared_polygon、counts默认 0、region_color默认 BGR 白色(255, 255, 255)、text_color默认黑色(0, 0, 0)counting_regionslist已定义的所有区域每个元素由region_template拷贝并更新具体属性而来region_countsdict记录每个命名区域当前帧计数的字典键为区域名核心方法一览add_region(name, polygon_points, region_color, text_color)按模板新增一个计数区域initialize_regions()依据传入的region参数一次性完成区域初始化支持单个/多个区域process(im0)核心入口处理单帧图像并返回计数结果也是BaseSolution.__call__在内部回调的方法。区域初始化机制initialize_regions与add_region当构造RegionCounter时region_counter.py__init__先初始化模板与容器随即调用self.initialize_regions()把用户传入的region配置转换成内部区域对象。def initialize_regions(self): Initialize regions from self.region only once. if self.region is None: self.initialize_region() if not isinstance(self.region, dict): # 确保 self.region 是字典结构 self.region {Region#01: self.region} for i, (name, pts) in enumerate(self.region.items()): self.add_region(name, pts, colors(i, True), (255, 255, 255))这段代码揭示了三个关键细节单列表自动命名如果你传入的是纯点列表而非字典它会被自动包装成{Region#01: 点列表}即默认命名为Region#01默认兜底区域如果region为None会调用继承自BaseSolution的 initialize_region把区域回退为[(10, 200), (540, 200), (540, 180), (10, 180)]这一组默认坐标因此 CLI 中直接运行yolo solutions region showTrue也能有可演示的区域颜色自动分配第 i 个区域使用colors(i, True)Ultralytics 内置调色板作为区域颜色、白色作为区域内文本颜色保证多区域画面视觉可区分。add_region合法性与 shapely 预计算add_region 负责把用户数据落地为内部区域对象if len(polygon_points) 3: raise ValueError( fRegionCounter requires regions with at least 3 points to form a polygon, fbut got {len(polygon_points)} for {name}. ) polygon self.Polygon(polygon_points) region self.region_template.copy() region.update({ name: name, polygon: polygon, prepared_polygon: self.prep(polygon), region_color: region_color, text_color: text_color, })需要重点关注两点最少 3 个点多边形区域至少需要 3 个顶点否则直接抛出ValueError。这意味着线形区域2 点在此类中不受支持——这是与ObjectCounter支持 LineString 区域的关键差异之一shapely PreparedGeometry构造时把区域多边形交给 shapely 的prep()生成prepared_polygon用于后续大量点是否在多边形内判定时的性能优化。shapely 依赖在 BaseSolution.init中通过check_requirements(shapely2.0.0)强制校验即运行 RegionCounter 的前提是环境已安装shapely2.0.0。逐帧计数原理process的完整调用链RegionCounter.processregion_counter.py是整条流水线的核心每一帧按如下顺序执行。第一步检测 跟踪抽帧self.extract_tracks(im0) annotator SolutionAnnotator(im0, line_widthself.line_width) self.region_counts {region[name]: 0 for region in self.counting_regions}extract_tracks继承自 BaseSolution内部以self.model.track(sourceim0, persistTrue, classesself.classes, verboseFalse, **self.track_add_args)调用 YOLO 追踪推理然后抽出boxes、clss、track_ids、confs四组对齐数据。它同时兼容普通检测框与旋转框OBB模型——当tracks.obb存在时走 OBB 分支。本帧开始时region_counts先被统一清零保证统计的是当前帧的占用情况。第二步框中心点命中判断for box, cls, track_id, conf in zip(self.boxes, self.clss, self.track_ids, self.confs): annotator.box_label(box, labelself.adjust_box_label(cls, conf, track_id), colorcolors(track_id, True)) x0, y0, x1, y1 self.get_enclosing_box(box) center self.Point(((x0 x1) / 2, (y0 y1) / 2)) for region in self.counting_regions: if region[prepared_polygon].contains(center): region[counts] 1 self.region_counts[region[name]] region[counts]其判定算法非常直观对每个被跟踪目标先画出检测框标签标签由 adjust_box_label 生成受show_conf/show_labels控制通过get_enclosing_box归一化框坐标为[x1, y1, x2, y2]该工具方法对 OBB 的 4 角点格式也做外接矩形换算计算框中心点Point(((x0x1)/2, (y0y1)/2))遍历所有区域用预计算过的 shapely PreparedPolygon执行contains(center)命中测试命中则对应区域计数 1。因此判定口径是框中心点是否落在区域内部分越界的目标只要中心点仍在区域内就会被计入反之面积很大但中心点悬在区域外的目标不会被计入。第三步绘制与复位for region in self.counting_regions: poly region[polygon] pts list(map(tuple, np.array(poly.exterior.coords, dtypenp.int32))) (x1, y1), (x2, y2) [(int(poly.centroid.x), int(poly.centroid.y))] * 2 annotator.draw_region(pts, region[region_color], self.line_width * 2) annotator.adaptive_label( [x1, y1, x2, y2], labelstr(region[counts]), colorregion[region_color], txt_colorregion[text_color], marginself.line_width * 4, shaperect, ) region[counts] 0 # Reset for next frame plot_im annotator.result() self.display_output(plot_im) return SolutionResults(plot_implot_im, total_trackslen(self.track_ids), region_countsself.region_counts)绘制阶段调用 SolutionAnnotator 的两个方法draw_region用cv2.polylines闭合绘制多边形轮廓线宽为line_width * 2并在每个顶点画实心小圆点adaptive_label在多边形**质心centroid**位置绘制一个背景矩形标签内容为当前帧的计数值。注意最后一行region[counts] 0——每帧绘制完立即复位再次印证RegionCounter输出的是瞬时占用数。最终返回的SolutionResults包含三个可用字段字段类型含义plot_imnp.ndarray已绘制的标注帧可直接写入视频total_tracksint本帧被跟踪到的目标总数len(self.track_ids)region_countsdict区域名 → 当前帧计数调用__call__即regioncounter(im0)时BaseSolution.call还会额外附加result.speed计时信息track与solution两段毫秒耗时并在verboseTrue默认时按帧输出分辨率、类别统计与速度日志。快速上手CLI 与 Python 两种用法完整的可运行示例见 region-counting.md以下是两种入口。命令行方式CLI 中region关键字被 SOLUTION_MAP 映射为RegionCounter类# 使用默认演示视频与默认区域直接运行 yolo solutions region showTrue # 指定视频源 yolo solutions region sourcepath/to/video.mp4 # 指定自定义多边形区域一个列表即一个区域 yolo solutions region region[(20, 400), (1080, 400), (1080, 360), (20, 360)]CLI 由 handle_yolo_solutions 统一解析执行处理结果视频默认保存在runs/solutions/exp目录未提供source时在 CLI 模式下会自动下载 Ultralytics 资产仓库中的solutions_ci_demo.mp4作为演示源见 solutions.py。Python 方式推荐实战import cv2 from ultralytics import solutions cap cv2.VideoCapture(path/to/video.mp4) assert cap.isOpened(), Error reading video file # 方式一区域用点列表单区域自动命名为 Region#01 # region_points [(20, 400), (1080, 400), (1080, 360), (20, 360)] # 方式二区域用字典多区域保留各自命名 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) # 可编程读取区域计数 print(results.region_counts, total_tracks:, results.total_tracks) video_writer.write(results.plot_im) cap.release() video_writer.release() cv2.destroyAllWindows()RegionCounter类通过 solutions/init.py 对外导出因此直接from ultralytics import solutions后使用solutions.RegionCounter即可。模型默认会回退为yolo26n.pt见 solutions.py可根据精度需求替换为同系列的更大模型或专用权重。RegionCounter参数完整说明所有 Solutions 的参数最终由 SolutionConfig 数据类承载底层为ultralytics/cfg/default.yaml的解决方案子集通过构造时传入的**kwargs覆盖默认值。RegionCounter 涉及三类参数。基础参数参数类型默认值说明modelstrNone运行时回退yolo26n.pt用于推理的 Ultralytics YOLO 模型路径regionlist或dictNone感兴趣区域坐标(x, y)元组列表单区域或区域名 → 点列表字典RegionCounter多区域专用。为None时回退到默认区域line_widthint2所绘制的框、关键点与计数的线宽verboseboolTrue是否打印每帧的输入尺寸、类别统计与处理速度日志底层跟踪调用始终静默sourcestrNone输入视频/RTSP 等来源仅 CLI 可用imgszint640模型推理的输入图像尺寸对象跟踪参数由于计数依赖跟踪RegionCounter同步开放以下追踪相关参数默认值同样来自 SolutionConfig并通过BaseSolution.track_add_args透传给底层model.track()参数类型默认值说明trackerstrbotsort.yaml跟踪算法配置内置botsort.yaml、bytetrack.yaml、ocsort.yaml、deepocsort.yaml、fasttrack.yaml、tracktrack.yamlconffloat0.25检测置信度阈值调低会跟踪更多目标但可能引入误报ioufloat0.7NMS 的 IoU 阈值用于过滤重叠检测框classeslistNone仅跟踪指定类别索引例如classes[0]用 COCO 预训练模型时只统计行人devicestrNone推理设备如cpu、cuda:0或0max_detint300每帧允许的最大检测数quantizeint/strNone推理精度如16表示 FP16可视化参数参数类型默认值说明showboolFalse为True时弹窗实时显示标注画面需图形环境支持BaseSolution用check_imshow检测show_labelsboolTrue是否在目标框上显示类别标签show_confboolTrue是否在标签中附带置信度例如只统计某个区域内的行人并隐藏置信度显示regioncounter solutions.RegionCounter( modelyolo26n.pt, region{crosswalk: [(150, 300), (600, 300), (600, 420), (150, 420)]}, classes[0], # 仅 person 类 show_confFalse, conf0.3, trackerbytetrack.yaml, )典型场景与正确选型RegionCounter的典型用途包括零售门店分别统计不同货架区/结账区当前停留人数辅助排班与动线分析道路交通统计每个车道或路口等待区当前车辆占用数生产/仓储监控各工位、各缓存区的在制/在库数量判断区域是否拥挤。官方指南 region-counting.md 展示了零售店人流与市集人群计数两类可视化应用。选型边界务必注意瞬时占用需要此刻区域内有多少目标用RegionCounter穿越累计需要统计穿越线/区域边界累计进出数量用 ObjectCounter其region_counts为累计 in/out线形 2 点区域仅ObjectCounter支持单区域内跟随轨迹需要显示某区域内单个目标的运动轨迹时可参考 TrackZone。这些机制差异在对应源码中均可印证RegionCounter每帧末执行region[counts] 0复位而ObjectCounter的计数跨帧保留。测试验证与工程落点仓库测试 tests/test_solutions.py 将RegionCounter与Heatmap、ObjectBlurrer等同批纳入参数化用例使用REGION [(10, 200), (540, 200), (540, 180), (10, 180)]驱动真实视频逐帧调用tests/test_solutions.py并在每帧传入im0.copy()验证不会破坏原始帧。这为开发者提供了两个可直接套用的经验实例化时给region传一个坐标列表即可跑通最小用例若要在自己的代码里批量测试可按process_video的方式逐帧喂图并在收尾时cap.release()释放资源。相关文件索引region_counter.py、solutions.py、config.py、solutions/init.py、cfg/init.py、tests/test_solutions.py。常见问题RegionCounter 与 ObjectCounter 有何区别RegionCounter每帧复位、显示各多边形区域的当前占用数ObjectCounter跨帧累计、统计穿越线或区域边界的进出总量。需要实时占用监控选前者需要出入口累计人流/车流选后者此外线形区域2 点仅ObjectCounter支持。如何让每个区域有独立命名与颜色把region传为字典键是区域名会显示在画面上值是该区域的点列表每个区域会自动从 Ultralytics 调色板取不同颜色并在其质心绘制带计数的矩形标签。计数值每帧复位那怎么拿到稳定的业务数字在应用层按需读取返回值每次results regioncounter(im0)后results.region_counts即当前帧各区域占用数results.total_tracks为被跟踪目标总数results.plot_im为标注帧你可以自行决定采样间隔或对其做聚合处理源代码 solutions.py 定义了SolutionResults的全部可用字段。我可以只数某个类别吗可以跟踪参数中的classes按类别索引过滤例如 COCO 模型下classes[0]只统计 person。小结RegionCounter用YOLO 检测 多目标跟踪 shapely 点包含判定 区域质心绘制四步把多区域实时占用计数压缩成一次构造调用。理解其中心点判据、每帧复位、占位即当前数量这三条底层语义就能正确把它嵌入门店管理、交通监控、仓储巡检等场景而当需求变为累计穿越计数时请果断切换到仓库中定位互补的 ObjectCounter。相关模型与更多解决方案的横向对比可继续查阅 YOLO26 文档、追踪模式文档 与 Ultralytics Solutions 索引。【免费下载链接】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），仅供参考 Ultralytics RegionCounter 源码级解析：实时视频多区域目标计数与 YOLO26 实践指南
Ultralytics RegionCounter 源码级解析实时视频多区域目标计数与 YOLO26 实践指南【免费下载链接】ultralyticsUltralytics YOLO26, YOLO11, YOLOv8 — object detection, instance segmentation, semantic segmentation, image classification, pose estimation, object tracking项目地址: https://gitcode.com/GitHub_Trending/ul/ultralytics导读本文围绕 Ultralytics 仓库中的 RegionCounter API 参考文档 与 区域计数实战指南深入讲解RegionCounter类的设计结构、逐帧计数工作原理、多区域配置方法、完整参数表与可编程读取方式。读完你可以在零售客流、道路车流、生产区域等多区域监控场景中用几行代码同时监控多个多边形区域的当前占用人数/物数并能理解其与跨界累计计数ObjectCounter的本质差异。什么是 RegionCounter一次推理、多个区域、逐帧占用计数RegionCounter是定义在 ultralytics/solutions/region_counter.py 中的一个解决方案类继承自 BaseSolution。它做的事情是对视频流中的每一帧执行 YOLO 检测与多目标跟踪然后判断每个被跟踪目标的检测框中心点落在你定义的哪些多边形区域内并在画面上实时绘制每个区域内部的当前目标数量。从源码结构可以概括出它的三大设计要点多区域并行region参数既可以传一个多边形点列表单区域也可以传区域名 → 点列表的字典多区域每个区域拥有独立命名、独立颜色、独立计数追踪内置计数依赖 YOLO 跟踪得到的track_id保持跨帧一致性无需另外接入追踪管线结果可编程读取每次处理返回的 SolutionResults 对象携带region_counts字典可对接仪表盘、告警或日志。需要特别强调的是语义RegionCounter显示的数值是当前帧内处于该区域中的目标数即占用数 occupancy而非累计进出总量。因为源码中每处理完一帧都会把计数重置为 0见下文process方法所以画面上的数字表示此刻有多少个目标在该区域内。若要统计穿越边界的累计进出量应改用 ObjectCounter。类结构RegionCounter的模块骨架RegionCounter类的声明文档与 Docstring 集中在 region_counter.py它自身只维护三个核心状态外加由BaseSolution继承的通用配置与追踪数据。关键属性属性类型说明region_templatedict创建新计数区域的模板含默认属性name默认Default Region、polygon、prepared_polygon、counts默认 0、region_color默认 BGR 白色(255, 255, 255)、text_color默认黑色(0, 0, 0)counting_regionslist已定义的所有区域每个元素由region_template拷贝并更新具体属性而来region_countsdict记录每个命名区域当前帧计数的字典键为区域名核心方法一览add_region(name, polygon_points, region_color, text_color)按模板新增一个计数区域initialize_regions()依据传入的region参数一次性完成区域初始化支持单个/多个区域process(im0)核心入口处理单帧图像并返回计数结果也是BaseSolution.__call__在内部回调的方法。区域初始化机制initialize_regions与add_region当构造RegionCounter时region_counter.py__init__先初始化模板与容器随即调用self.initialize_regions()把用户传入的region配置转换成内部区域对象。def initialize_regions(self): Initialize regions from self.region only once. if self.region is None: self.initialize_region() if not isinstance(self.region, dict): # 确保 self.region 是字典结构 self.region {Region#01: self.region} for i, (name, pts) in enumerate(self.region.items()): self.add_region(name, pts, colors(i, True), (255, 255, 255))这段代码揭示了三个关键细节单列表自动命名如果你传入的是纯点列表而非字典它会被自动包装成{Region#01: 点列表}即默认命名为Region#01默认兜底区域如果region为None会调用继承自BaseSolution的 initialize_region把区域回退为[(10, 200), (540, 200), (540, 180), (10, 180)]这一组默认坐标因此 CLI 中直接运行yolo solutions region showTrue也能有可演示的区域颜色自动分配第 i 个区域使用colors(i, True)Ultralytics 内置调色板作为区域颜色、白色作为区域内文本颜色保证多区域画面视觉可区分。add_region合法性与 shapely 预计算add_region 负责把用户数据落地为内部区域对象if len(polygon_points) 3: raise ValueError( fRegionCounter requires regions with at least 3 points to form a polygon, fbut got {len(polygon_points)} for {name}. ) polygon self.Polygon(polygon_points) region self.region_template.copy() region.update({ name: name, polygon: polygon, prepared_polygon: self.prep(polygon), region_color: region_color, text_color: text_color, })需要重点关注两点最少 3 个点多边形区域至少需要 3 个顶点否则直接抛出ValueError。这意味着线形区域2 点在此类中不受支持——这是与ObjectCounter支持 LineString 区域的关键差异之一shapely PreparedGeometry构造时把区域多边形交给 shapely 的prep()生成prepared_polygon用于后续大量点是否在多边形内判定时的性能优化。shapely 依赖在 BaseSolution.init中通过check_requirements(shapely2.0.0)强制校验即运行 RegionCounter 的前提是环境已安装shapely2.0.0。逐帧计数原理process的完整调用链RegionCounter.processregion_counter.py是整条流水线的核心每一帧按如下顺序执行。第一步检测 跟踪抽帧self.extract_tracks(im0) annotator SolutionAnnotator(im0, line_widthself.line_width) self.region_counts {region[name]: 0 for region in self.counting_regions}extract_tracks继承自 BaseSolution内部以self.model.track(sourceim0, persistTrue, classesself.classes, verboseFalse, **self.track_add_args)调用 YOLO 追踪推理然后抽出boxes、clss、track_ids、confs四组对齐数据。它同时兼容普通检测框与旋转框OBB模型——当tracks.obb存在时走 OBB 分支。本帧开始时region_counts先被统一清零保证统计的是当前帧的占用情况。第二步框中心点命中判断for box, cls, track_id, conf in zip(self.boxes, self.clss, self.track_ids, self.confs): annotator.box_label(box, labelself.adjust_box_label(cls, conf, track_id), colorcolors(track_id, True)) x0, y0, x1, y1 self.get_enclosing_box(box) center self.Point(((x0 x1) / 2, (y0 y1) / 2)) for region in self.counting_regions: if region[prepared_polygon].contains(center): region[counts] 1 self.region_counts[region[name]] region[counts]其判定算法非常直观对每个被跟踪目标先画出检测框标签标签由 adjust_box_label 生成受show_conf/show_labels控制通过get_enclosing_box归一化框坐标为[x1, y1, x2, y2]该工具方法对 OBB 的 4 角点格式也做外接矩形换算计算框中心点Point(((x0x1)/2, (y0y1)/2))遍历所有区域用预计算过的 shapely PreparedPolygon执行contains(center)命中测试命中则对应区域计数 1。因此判定口径是框中心点是否落在区域内部分越界的目标只要中心点仍在区域内就会被计入反之面积很大但中心点悬在区域外的目标不会被计入。第三步绘制与复位for region in self.counting_regions: poly region[polygon] pts list(map(tuple, np.array(poly.exterior.coords, dtypenp.int32))) (x1, y1), (x2, y2) [(int(poly.centroid.x), int(poly.centroid.y))] * 2 annotator.draw_region(pts, region[region_color], self.line_width * 2) annotator.adaptive_label( [x1, y1, x2, y2], labelstr(region[counts]), colorregion[region_color], txt_colorregion[text_color], marginself.line_width * 4, shaperect, ) region[counts] 0 # Reset for next frame plot_im annotator.result() self.display_output(plot_im) return SolutionResults(plot_implot_im, total_trackslen(self.track_ids), region_countsself.region_counts)绘制阶段调用 SolutionAnnotator 的两个方法draw_region用cv2.polylines闭合绘制多边形轮廓线宽为line_width * 2并在每个顶点画实心小圆点adaptive_label在多边形**质心centroid**位置绘制一个背景矩形标签内容为当前帧的计数值。注意最后一行region[counts] 0——每帧绘制完立即复位再次印证RegionCounter输出的是瞬时占用数。最终返回的SolutionResults包含三个可用字段字段类型含义plot_imnp.ndarray已绘制的标注帧可直接写入视频total_tracksint本帧被跟踪到的目标总数len(self.track_ids)region_countsdict区域名 → 当前帧计数调用__call__即regioncounter(im0)时BaseSolution.call还会额外附加result.speed计时信息track与solution两段毫秒耗时并在verboseTrue默认时按帧输出分辨率、类别统计与速度日志。快速上手CLI 与 Python 两种用法完整的可运行示例见 region-counting.md以下是两种入口。命令行方式CLI 中region关键字被 SOLUTION_MAP 映射为RegionCounter类# 使用默认演示视频与默认区域直接运行 yolo solutions region showTrue # 指定视频源 yolo solutions region sourcepath/to/video.mp4 # 指定自定义多边形区域一个列表即一个区域 yolo solutions region region[(20, 400), (1080, 400), (1080, 360), (20, 360)]CLI 由 handle_yolo_solutions 统一解析执行处理结果视频默认保存在runs/solutions/exp目录未提供source时在 CLI 模式下会自动下载 Ultralytics 资产仓库中的solutions_ci_demo.mp4作为演示源见 solutions.py。Python 方式推荐实战import cv2 from ultralytics import solutions cap cv2.VideoCapture(path/to/video.mp4) assert cap.isOpened(), Error reading video file # 方式一区域用点列表单区域自动命名为 Region#01 # region_points [(20, 400), (1080, 400), (1080, 360), (20, 360)] # 方式二区域用字典多区域保留各自命名 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) # 可编程读取区域计数 print(results.region_counts, total_tracks:, results.total_tracks) video_writer.write(results.plot_im) cap.release() video_writer.release() cv2.destroyAllWindows()RegionCounter类通过 solutions/init.py 对外导出因此直接from ultralytics import solutions后使用solutions.RegionCounter即可。模型默认会回退为yolo26n.pt见 solutions.py可根据精度需求替换为同系列的更大模型或专用权重。RegionCounter参数完整说明所有 Solutions 的参数最终由 SolutionConfig 数据类承载底层为ultralytics/cfg/default.yaml的解决方案子集通过构造时传入的**kwargs覆盖默认值。RegionCounter 涉及三类参数。基础参数参数类型默认值说明modelstrNone运行时回退yolo26n.pt用于推理的 Ultralytics YOLO 模型路径regionlist或dictNone感兴趣区域坐标(x, y)元组列表单区域或区域名 → 点列表字典RegionCounter多区域专用。为None时回退到默认区域line_widthint2所绘制的框、关键点与计数的线宽verboseboolTrue是否打印每帧的输入尺寸、类别统计与处理速度日志底层跟踪调用始终静默sourcestrNone输入视频/RTSP 等来源仅 CLI 可用imgszint640模型推理的输入图像尺寸对象跟踪参数由于计数依赖跟踪RegionCounter同步开放以下追踪相关参数默认值同样来自 SolutionConfig并通过BaseSolution.track_add_args透传给底层model.track()参数类型默认值说明trackerstrbotsort.yaml跟踪算法配置内置botsort.yaml、bytetrack.yaml、ocsort.yaml、deepocsort.yaml、fasttrack.yaml、tracktrack.yamlconffloat0.25检测置信度阈值调低会跟踪更多目标但可能引入误报ioufloat0.7NMS 的 IoU 阈值用于过滤重叠检测框classeslistNone仅跟踪指定类别索引例如classes[0]用 COCO 预训练模型时只统计行人devicestrNone推理设备如cpu、cuda:0或0max_detint300每帧允许的最大检测数quantizeint/strNone推理精度如16表示 FP16可视化参数参数类型默认值说明showboolFalse为True时弹窗实时显示标注画面需图形环境支持BaseSolution用check_imshow检测show_labelsboolTrue是否在目标框上显示类别标签show_confboolTrue是否在标签中附带置信度例如只统计某个区域内的行人并隐藏置信度显示regioncounter solutions.RegionCounter( modelyolo26n.pt, region{crosswalk: [(150, 300), (600, 300), (600, 420), (150, 420)]}, classes[0], # 仅 person 类 show_confFalse, conf0.3, trackerbytetrack.yaml, )典型场景与正确选型RegionCounter的典型用途包括零售门店分别统计不同货架区/结账区当前停留人数辅助排班与动线分析道路交通统计每个车道或路口等待区当前车辆占用数生产/仓储监控各工位、各缓存区的在制/在库数量判断区域是否拥挤。官方指南 region-counting.md 展示了零售店人流与市集人群计数两类可视化应用。选型边界务必注意瞬时占用需要此刻区域内有多少目标用RegionCounter穿越累计需要统计穿越线/区域边界累计进出数量用 ObjectCounter其region_counts为累计 in/out线形 2 点区域仅ObjectCounter支持单区域内跟随轨迹需要显示某区域内单个目标的运动轨迹时可参考 TrackZone。这些机制差异在对应源码中均可印证RegionCounter每帧末执行region[counts] 0复位而ObjectCounter的计数跨帧保留。测试验证与工程落点仓库测试 tests/test_solutions.py 将RegionCounter与Heatmap、ObjectBlurrer等同批纳入参数化用例使用REGION [(10, 200), (540, 200), (540, 180), (10, 180)]驱动真实视频逐帧调用tests/test_solutions.py并在每帧传入im0.copy()验证不会破坏原始帧。这为开发者提供了两个可直接套用的经验实例化时给region传一个坐标列表即可跑通最小用例若要在自己的代码里批量测试可按process_video的方式逐帧喂图并在收尾时cap.release()释放资源。相关文件索引region_counter.py、solutions.py、config.py、solutions/init.py、cfg/init.py、tests/test_solutions.py。常见问题RegionCounter 与 ObjectCounter 有何区别RegionCounter每帧复位、显示各多边形区域的当前占用数ObjectCounter跨帧累计、统计穿越线或区域边界的进出总量。需要实时占用监控选前者需要出入口累计人流/车流选后者此外线形区域2 点仅ObjectCounter支持。如何让每个区域有独立命名与颜色把region传为字典键是区域名会显示在画面上值是该区域的点列表每个区域会自动从 Ultralytics 调色板取不同颜色并在其质心绘制带计数的矩形标签。计数值每帧复位那怎么拿到稳定的业务数字在应用层按需读取返回值每次results regioncounter(im0)后results.region_counts即当前帧各区域占用数results.total_tracks为被跟踪目标总数results.plot_im为标注帧你可以自行决定采样间隔或对其做聚合处理源代码 solutions.py 定义了SolutionResults的全部可用字段。我可以只数某个类别吗可以跟踪参数中的classes按类别索引过滤例如 COCO 模型下classes[0]只统计 person。小结RegionCounter用YOLO 检测 多目标跟踪 shapely 点包含判定 区域质心绘制四步把多区域实时占用计数压缩成一次构造调用。理解其中心点判据、每帧复位、占位即当前数量这三条底层语义就能正确把它嵌入门店管理、交通监控、仓储巡检等场景而当需求变为累计穿越计数时请果断切换到仓库中定位互补的 ObjectCounter。相关模型与更多解决方案的横向对比可继续查阅 YOLO26 文档、追踪模式文档 与 Ultralytics Solutions 索引。【免费下载链接】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），仅供参考