Ultralytics 停车管理解决方案源码级解析ParkingPtsSelection 与 ParkingManagement【免费下载链接】ultralyticsUltralytics YOLO26, YOLO11, YOLOv8 — object detection, instance segmentation, semantic segmentation, image classification, pose estimation, object tracking项目地址: https://gitcode.com/GitHub_Trending/ul/ultralytics本文围绕 Ultralytics 仓库中 docs/en/reference/solutions/parking_management.md 所定义的parking_management模块展开系统讲解其两个核心类——用于车位标注的ParkingPtsSelection与用于实时车位占用监控的ParkingManagement。文章覆盖类的职责划分、GUI 标注工具的使用方式、车位区域 JSON 文件格式、完整的 Python/CLI 接入流程、全部可配置参数以及process()背后的跟踪与点包含判定原理。读完本文你将具备从标注车位到实时输出占用/空闲统计的端到端搭建能力并理解其底层实现机制。一、模块定位一条完整的停车监控链路在 Ultralytics 的 Solutions 组件体系中parking_management模块负责基于视频流的停车位占用监控。它与传统检测方案的最大区别在于车位布局通过 JSON 文件预定义运行时不再依赖检测框与车位的一一匹配而是用跟踪到的车辆中心点去判定其是否落入某个车位多边形。模块被集中实现在 ultralytics/solutions/parking_management.py并已在 ultralytics/solutions/init.py 中导出ParkingManagement与ParkingPtsSelection因此可通过from ultralytics import solutions直接使用。该模块对外提供两个职责完全分离的类类职责运行形态ParkingPtsSelection图形化标注车位上传图片、鼠标点选多边形、保存 JSONTkinter 桌面 GUI需要显示环境ParkingManagement实时监控车位模型跟踪车辆并判断车位占用状态继承BaseSolution逐帧process()其中ParkingPtsSelection继承object是一个独立 GUI 工具ParkingManagement则继承 ultralytics/solutions/solutions.py 中的BaseSolution复用其模型加载、跟踪、绘图等通用能力。从类层级与__init__.py的导出可见仓库把标注阶段与监控阶段拆成了两个互相独立的组件二者通过 JSON 文件衔接这正是该方案可迁移、可复用的关键设计。二、ParkingPtsSelection可视化车位标注工具在车位上拉取准确多边形是整个系统中最耗时、最容易出错的环节仓库因此提供了图形化的ParkingPtsSelection。根据其类 docstringparking_management.py该工具支持上传图片、逐点点击定义停车区域并将结果写入 JSON 文件。2.1 环境前置条件ParkingPtsSelection依赖tkinterGUI、PIL/Pillow图像加载与缩放以及可用的图形显示环境。构造函数在启动时会做两类检查Tkinter 可用性检查若import tkinter失败会按操作系统给出安装建议并直接返回parking_management.pyLinuxDebian/Ubuntusudo apt install python3-tkFedorasudo dnf install python3-tkinterArchsudo pacman -S tkWindows重新安装 Python 并在Optional Features中勾选tcl/tk and IDLEmacOS重新安装带 Tk 的 Python 或brew install python-tk显示环境检查调用check_imshow(warnTrue)若处于无显示器如纯服务器、CI环境则无法启动 GUI。2.2 交互流程与内部方法工具启动后弹出标题为 Ultralytics Parking Zones Points Selector 的主窗口顶部有三个按钮Upload Image、Remove Last Bounding Box、Saveparking_management.py。其核心成员与交互对应如下成员类型说明rg_datalist[list[tuple[int,int]]]已确认的车位框集合每个框由 4 个点构成current_boxlist[tuple[int,int]]正在绘制的当前框的临时点集imgw/imghint原始图片宽高用于坐标缩放canvas_max_width/canvas_max_heightint画布上限默认1280 × 720各按钮与方法一一对应upload_image()弹窗选择*.png *.jpg *.jpeg图片按宽高比将图片缩放适配到画布后显示并绑定鼠标左键事件on_canvas_clickon_canvas_click()每点击一次向current_box追加一个点并画一个红色圆点标记当点满4 个时该框被写入rg_data并通过draw_box()用蓝色折线闭合连接成多边形然后清空current_box继续下一个车位remove_last_bounding_box()撤销最近一次确认的车位框并调用redraw_canvas()重绘无框可删时弹出警告redraw_canvas()清空画布后重贴底图并重画所有已保存框save_to_json()计算缩放比例后把所有框写入bounding_boxes.json。2.3 保存时的坐标缩放与 JSON 格式由于标注发生在缩放后的画布上而推理输入是原始分辨率帧save_to_json()会在保存时做坐标还原parking_management.pyscale_w, scale_h self.imgw / self.canvas.winfo_width(), self.imgh / self.canvas.winfo_height() data [{points: [(int(x * scale_w), int(y * scale_h)) for x, y in box]} for box in self.rg_data]即把画布坐标乘以原始图宽/画布宽、原始图高/画布高还原为图像原分辨率坐标。最终写入工作目录下固定文件名的bounding_boxes.json内容形如[ { points: [ [334, 267], [608, 259], [613, 424], [330, 431] ] }, { points: [ [12, 58], [260, 52], [262, 206], [10, 209] ] } ]每个元素是一个车位points是 4 个[x, y]角点。该结构正是ParkingManagement运行时读取同一份 JSON 的依据两个类由此在数据层面完成了衔接。三、ParkingManagement实时车位占用监控核心类ParkingManagement继承BaseSolution类 docstringparking_management.py给出最小使用示例from ultralytics.solutions import ParkingManagement parking_manager ParkingManagement(modelyolo26n.pt, json_fileparking_regions.json) print(fOccupied spaces: {parking_manager.pr_info[Occupancy]}) print(fAvailable spaces: {parking_manager.pr_info[Available]})3.1 初始化JSON 参数强制校验构造函数parking_management.py在调用super().__init__(**kwargs)完成通用配置合并后专门处理车位数据self.json_file self.CFG[json_file] if not self.json_file: LOGGER.warning(ParkingManagement requires json_file with parking region coordinates.) raise ValueError(❌ JSON file path cannot be empty.) with open(self.json_file, encodingutf-8) as f: self.json json.load(f)json_file是必填参数缺省时直接抛ValueError终止初始化这是模块与其它 Solutions多数以region传区域最大的不同——车位多边形必须来自外部 JSON。同时构造函数初始化统计字典与三类可视化颜色BGR属性值语义pr_info{Occupancy: 0, Available: 0}占用数 / 可用数统计arc(0, 0, 255)可用车位绘制颜色BGR 红occ(0, 255, 0)已占车位绘制颜色BGR 绿dc(255, 0, 189)检测目标中心点颜色BGR 品红当前用于物体标签标注3.2 可配置参数总表ParkingManagement的配置统一由 ultralytics/solutions/config.py 的SolutionConfigdataclass 承接BaseSolution会把用户 kwargs 合并进CFGsolutions.py。以下是与该方案直接相关的参数Argument类型默认值说明modelstrNone实际回退yolo26n.ptYOLO 模型文件路径支持检测、OBB 等模型json_filestrNone必填包含所有车位坐标数据的 JSON 文件路径line_widthint2标注线宽同时影响框/标签/统计信息绘制verboseboolTrue是否打印逐帧日志输入尺寸、类别计数、耗时方案底层走的是track 模式见 4.2 节因此可透传下列跟踪参数Argument类型默认值说明trackerstrbotsort.yaml跟踪算法内置botsort.yaml、bytetrack.yaml、ocsort.yaml、deepocsort.yaml、fasttrack.yaml、tracktrack.yamlconffloat0.25检测置信度阈值调低可召回更多目标但易混入误检ioufloat0.7重叠检测框 NMS 的 IoU 阈值classeslistNone类别过滤如classes[2, 7]只跟踪指定类车辆devicestrNone推理设备如cpu、cuda:0或0此外支持可视化参数show默认False置True时在窗口中实时展示结果帧。方案也接受imgsz推理输入尺寸默认640等SolutionConfig通用参数。四、完整实战流程从标注到实时监控完整的接入链路在 docs/en/guides/parking-management.md 中有配套讲解共四步。4.1 Step 1-3获取帧并使用标注工具生成 JSON首先从待管理的视频/相机流中截取一帧作为底图俯视或正对停车场的机位效果最佳随后启动标注 GUIfrom ultralytics import solutions solutions.ParkingPtsSelection()在弹出的窗口中点击Upload Image选择截取的帧用鼠标依次点击车位四角每满 4 点自动生成一个蓝色框逐个框选全部车位后点击Save。工具会将缩放还原后的坐标写入当前工作目录的bounding_boxes.json——这正是后续监控脚本默认读取的文件名。4.2 Step 4运行实时监控Python 方式ultralytics/solutions/parking_management.py 的process(im0)处理单帧下面的完整脚本演示读取视频、逐帧处理并写出带标注的新视频import cv2 from ultralytics import solutions # 视频读取 cap cv2.VideoCapture(path/to/video.mp4) assert cap.isOpened(), Error reading video file # 视频写出 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(parking management.avi, cv2.VideoWriter_fourcc(*mp4v), fps, (w, h)) # 初始化停车管理对象 parkingmanager solutions.ParkingManagement( modelyolo26n.pt, # 模型文件路径 json_filebounding_boxes.json, # 车位标注文件路径 ) while cap.isOpened(): ret, im0 cap.read() if not ret: break results parkingmanager(im0) # 传入单帧返回 SolutionResults video_writer.write(results.plot_im) # 写入处理后的帧 cap.release() video_writer.release() cv2.destroyAllWindows()调用parkingmanager(im0)会经由BaseSolution.__call__solutions.py自动为结果补充speed计时字段并执行verbose日志。返回的SolutionResultssolutions.py在本方案中填充以下字段字段含义plot_im带标注的处理后图像可直接写视频/展示filled_slots已占用车位数available_slots空闲车位数total_tracks当帧跟踪到的目标总数speed{track: ...ms, solution: ...ms}性能计时由__call__注入CLI 方式标注完成后可用 Solutions CLI 免写代码运行yolo solutions parking sourcepath/to/video.mp4 json_filebounding_boxes.json showTrue注意必须先通过ParkingPtsSelection()生成车位标注 JSON再将其路径传给 CLI 的json_file参数。CLI 下showTrue会弹出实时可视化窗口按q键关闭对应 solutions.py 中display_output的实现。五、process() 运行原理跟踪、点包含判定与可视化要理解并正确使用该方案需要拆解process()parking_management.py的四个阶段。5.1 阶段一跟踪而非纯检测self.extract_tracks(im0) # 提取跟踪目标extract_trackssolutions.py内部调用self.model.track(sourceim0, persistTrue, ...)并把结果区分为两种数据形态检测模型跟踪数据取tracks.boxes框为轴对齐的[x1, y1, x2, y2]OBB 旋转框模型跟踪数据取tracks.obb框为(4, 2)的xyxyxyxy四角点。随后boxes、clss、track_ids、confs被同步提取。get_enclosing_box静态方法solutions.py负责把上述两种格式统一归一化为轴对齐[x1, y1, x2, y2]从而兼容旋转框模型。5.2 阶段二逐车位做中心点入多边形判定available_slots, occupied_slots len(self.json), 0 for region in self.json: region_polygon np.array(region[points], dtypenp.int32).reshape((-1, 1, 2)) region_occupied False for box, cls in zip(self.boxes, self.clss): x0, y0, x1, y1 self.get_enclosing_box(box) xc, yc int((x0 x1) / 2), int((y0 y1) / 2) inside_distance cv2.pointPolygonTest(region_polygon, (xc, yc), False) if inside_distance 0: region_occupied True break实现细节非常直观每个车位多边形由 JSON 中region[points]的 4 个角点按(N, 1, 2)形状构造对每个跟踪框求几何中心(xc, yc)再用 OpenCV 的cv2.pointPolygonTest(..., False)判断中心点与多边形位置关系——返回值≥ 0 即视为中心在车位内等于 0 表示恰好落在边界上此时该车位标记为已占用并跳出内层循环。这一中心点判定策略计算开销极低适合单路视频流的实时处理。5.3 阶段三可视化与统计更新被判定占用的目标会在图像上绘制类别标签调用annotator.display_objects_labels颜色来自dc与文本色(104, 31, 17)/(255, 255, 255)。随后每个车位用cv2.polylines勾勒轮廓占用车位画绿色、空闲车位画红色cv2.polylines(im0, [region_polygon], isClosedTrue, colorself.occ if region_occupied else self.arc, thickness2)帧末更新统计字典并叠加实时读数self.pr_info[Occupancy], self.pr_info[Available] occupied_slots, available_slots annotator.display_analytics(im0, self.pr_info, (104, 31, 17), (255, 255, 255), 10)5.4 阶段四返回结构化结果处理完成后通过display_output在showTrue且有显示环境时弹窗展示并以SolutionResults封装返回plot_im、filled_slots、available_slots、total_tracks。值得注意total_tracks由len(self.track_ids)计算反映的是跟踪目标总数而非在场车辆数二者在单车辆被误分为多轨迹时可能不一致。六、测试与稳定性保障该模块在仓库测试中覆盖度较好tests/test_solutions.py 提供了三层验证端到端视频测试test_solution参数化矩阵中注册了ParkingManager用例test_solutions.py使用专用车位模型与车位 JSON 资产、imgsz320逐帧跑完整视频验证初始化与推理不崩溃。注释还特别说明该用例使用yolo26n-obb.pt与停车视频素材用于覆盖OBB 旋转框路径——因为get_enclosing_box需处理四角点格式单帧崩溃回归测试test_solutions.py对ParkingManagement等方案只处理parking_video的首帧快速暴露 json 文件解析 / 多边形构造 类崩溃点缺参优雅失败测试test_parking_json_nonetest_solutions.py专门验证缺省 JSON 时抛错的预期行为与构造函数中raise ValueError的实现互相印证。这些测试表明只要提供格式正确的json_file与任一款可跟踪的 YOLO 模型检测或 OBB模块即可稳定运转而自定义场景的主要工作量集中在车位标注与模型类别选择上。七、FAQ 与常见调优如何为自有停车场适配布局最关键的参数是json_file——用ParkingPtsSelection为你的俯视画面重新框选车位并另存 JSON 即可切换新布局其余代码零改动。如何只统计车辆而不是行人/自行车通过classes参数按类别索引过滤例如 COCO 数据集中轿车/卡车等车辆类索引传入classes[2, 5, 7]附近取值也可conf提升到更高阈值剔除虚检或切换到更合适的tracker。监控画面有抖动、计数不稳定怎么办因为判定依赖跨帧一致的目标身份跟踪稳定性直接影响计数可从三方面入手保持persistTrue的连续帧输入、选用botsort.yaml/deepocsort.yaml等对短遮挡更鲁棒的跟踪器、必要时提升输入分辨率imgsz以改善远距离小目标检测。运行时报 JSON file path cannot be empty表明未传json_file属预期强校验参考 parking_management.py检查构造参数拼写并确认 JSON 路径存在即可。返回结果的字段与处理帧如何取用results.plot_im直接用于cv2.VideoWriter写出或cv2.imshow展示results.filled_slots/results.available_slots可进一步接入业务侧的大屏看板或日志系统results.total_tracks表示当前跟踪目标数。若把结果叠加输出到终端可打印或自定义接入与监控数据形成完整的上报闭环。【免费下载链接】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），仅供参考