Ultralytics Solutions 参数全解析solutions-args 统一参数表从宏定义到源码落地的完整指南【免费下载链接】ultralyticsUltralytics YOLO26, YOLO11, YOLOv8 — object detection, instance segmentation, semantic segmentation, image classification, pose estimation, object tracking项目地址: https://gitcode.com/GitHub_Trending/ul/ultralytics导读Ultralytics 仓库内的solutions-args.md是全部视觉 AI 解决方案Solutions模块共享参数的单一事实来源single source of truth。它通过 MkDocs 的 Jinja2 宏机制把 24 个通用参数模型路径、计数区域、画线宽度、测速标定、姿态阈值等渲染成统一的 Markdown 参数表供各解决方案指南页面按需引用。本文以该宏为骨架结合 SolutionConfig 配置类 与 BaseSolution 基类 的源码实现逐项讲解每个参数的类型、默认值、作用域与底层消费链路帮助你为对象计数、热力图、测速、安防报警等任务正确配置参数。参数宏是什么、被谁引用solutions-args.md本身并非一篇普通文档而是一个定义在 MkDocs 宏目录下的 Jinja2 模板片段。它导出一个名为param_table的宏宏内部维护了一个 Python 字典default_params统一存放每个参数的参数名 - [类型, 默认值, 功能描述]三元组最终生成如下结构的表格ArgumentTypeDefaultDescription当页面按{{ param_table() }}全量调用时宏会渲染全部 24 个参数当页面按{{ param_table([model, line_width, verbose]) }}传入子集时宏会过滤字典、只输出指定的行——这正是各专题指南的做法。同一个宏被仓库内众多文档复用的证据均为仓库内的真实调用Solutions 总览页{{ param_table() }}全量渲染是该宏最主要的展示位热力图指南只取model, colormap, show_in, show_out, region, line_width, verbose对象计数指南只取model, show_in, show_out, region, line_width, verbose车速估算指南只取model, fps, max_hist, meter_per_pixel, max_speed, line_width, verbose健身动作监测指南只取model, up_angle, down_angle, kpts, line_width, verbose停车场管理指南只取model, json_file, line_width, verbose此外还被 区域计数、队列管理、TrackZone、目标模糊、安防报警、VisionEye、距离计算、实例分割与跟踪、Analytics、目标裁剪 以及 训练参数总览页 引用。完整参数参考表宏全量输出以下是宏在没有params参数时输出的完整表格共 24 个参数覆盖当前所有 Solutions 模块ArgumentTypeDefaultDescriptionmodelstrNonePath to an Ultralytics YOLO model file.regionlistordictNonePoints defining the region of interest, either a list of(x, y)tuples or a dictionary mapping region names to point lists for multiple regions (RegionCounteronly). WhenNone, solutions that require a region fall back to a predefined default.show_inboolTrueFlag to control whether to display the in counts on the video stream.show_outboolTrueFlag to control whether to display the out counts on the video stream.analytics_typestrlineType of graph, i.e.,line,bar,area, orpie.colormapintcv2.COLORMAP_DEEPGREENColormap to use for the heatmap.line_widthint2Line thickness for the boxes, keypoints and counts the solution draws.verboseboolTrueEnables the solutions per-frame log of input shape, class counts and processing speed. The tracking call itself is always silent.json_filestrNonePath to the JSON file that contains all parking coordinates data.up_anglefloat145.0Angle threshold for the up pose.kptslist[int][6, 8, 10]List of three keypoint indices used for monitoring workouts. These keypoints correspond to body joints or parts, such as shoulders, elbows, and wrists, for exercises like push-ups, pull-ups, squats, and ab-workouts.down_angleint90Angle threshold for the down pose.blur_ratiofloat0.5Adjusts percentage of blur intensity, with values in range0.1 - 1.0.crop_dirstrcropped-detectionsDirectory name for storing cropped detections.recordsint5Total detections count to trigger an email with security alarm system.vision_pointtuple[int, int](20, 20)The point where vision will track objects and draw paths using VisionEye Solution.sourcestrNonePath to the input source (video, RTSP, etc.). Only usable with Solutions command line interface (CLI).figsizetuple[float, float](12.8, 7.2)Figure size for analytics charts such as heatmaps or graphs.fpsfloat30.0Frames per second used for speed calculations.max_histint5Maximum historical points to track per object for speed/direction calculations.meter_per_pixelfloat0.05Scaling factor used for converting pixel distance to real-world units.max_speedint120Maximum speed limit in visual overlays (used in alerts).datastrimagesPath to image directory used for similarity search.imgszint640Input image size for model inference.参数按功能域分组详解为便于查阅可按功能将 24 个参数分成以下六组。所有默认值均可被用户传入的关键字参数覆盖。模型与推理基础model、source、imgsz、verbosemodelstr默认None指向 Ultralytics YOLO 模型文件的路径。虽然宏里标注默认值为None但运行层有一个兜底逻辑在 BaseSolution.init中当配置里model is None时会被自动替换为yolo26n.pt。因此即使不显式传模型Solutions 也会加载官方 YOLO26 nano 权重该文件会在首次使用时自动下载。sourcestr默认None输入源路径视频文件、RTSP 流等。宏中特别注明仅适用于 Solutions CLI 场景因为 Python API 中帧由调用方逐帧送入。代码层进一步验证了这一约束当is_cliTrue且未提供source时BaseSolution 会告警并自动下载演示视频solutions_ci_demo.mp4模型名含-pose时下载solution_ci_pose_demo.mp4。imgszint默认640送入模型推理的输入图像尺寸。该值通过track_add_args直接转发给底层model.track()调用在目标裁剪ObjectCropper中还会用作slicing前的推理尺寸见 object_cropper.py 处imgszself.CFG[imgsz]。默认 640 与 YOLO 系列标准训练尺寸一致。verbosebool默认True开启后Solutions 每处理一帧会记录输入形状、各类别计数与处理耗时同时宏和源码都强调“跟踪调用本身始终静默”extract_tracks中传给model.track的verboseFalse避免每帧重复打印。日志开关实际位于 solutions.py 附近的帧日志分支。区域、计数与统计region、show_in、show_outregionlist 或 dict默认None定义感兴趣区域ROI的坐标。支持两种形态list of(x, y)元组单个多边形或线段被 ObjectCounter、QueueManager、TrackZone、Heatmap 等使用dict 映射将区域名映射到多个点列表仅RegionCounter支持用于在同一画面中建立多个命名计数区类内add_region模板见 region_counter.py。当为None时initialize_region 会回退到预置区域[(10, 200), (540, 200), (540, 180), (10, 180)]并依据点数决定构建Polygon≥3 点还是LineString2 点线段底层依赖 shapely 的prep做预编译空间查询以提升性能。show_in/show_outbool默认均True控制是否在画面中叠加显示“进入/离开”区域的累计计数值。二者由 object_counter.py 读取in_count、out_count、classwise_count也会随SolutionResults对象返回给调用方。图表与可视化样式analytics_type、figsize、colormap、line_widthanalytics_typestr默认lineAnalytics 模块的图表类型取值line、bar、area、pie在 analytics.py 中赋给实例属性self.type决定绘图分支。figsizetuple默认(12.8, 7.2)matplotlib 图表画布尺寸在 analytics.py 中被解读为输出分辨率 1280×720供热力图/统计图生成时使用。colormapint默认cv2.COLORMAP_DEEPGREENHeatmap 模块的 OpenCV 颜色映射常量用于把密度值映射为伪彩色叠加层可在 OpenCV 的COLORMAP_*常量族中任意替换见 heatmap.py。line_widthint默认2所有 Solutions 绘制元素的统一线宽——检测框、关键点连线、计数文本底框等。它在 BaseSolution.init被提前取出作为实例属性self.line_width供全部子类复用。姿态与动作计数up_angle、down_angle、kptsAIGym健身动作监测通过三段式夹角判定动作状态up / down / 计数三个参数集中在 ai_gym.pyup_anglefloat默认145.0判定为“抬起”状态的夹角阈值如俯卧撑撑起时肘关节接近伸直、角度变大。down_angleint默认90判定为“下放”状态的夹角阈值。kptslist[int]默认[6, 8, 10]构成夹角的三个关键点索引默认对应 COCO 姿态模型中的肩(6)、肘(8)、腕(10)适用于俯卧撑、引体向上、深蹲、卷腹等动作。如需监测髋/膝/踝组成的下蹲动作可改为[11, 13, 15]髋、膝、踝等组合。面向特定模块的功能参数blur_ratio、crop_dir、vision_point、records、json_fileblur_ratiofloat默认0.5范围0.1–1.0ObjectBlurrer 的模糊强度比例由 object_blurrer.py 读取并作为高斯核大小的缩放系数值越大目标越不可辨识。crop_dirstr默认cropped-detectionsObjectCropper 保存裁剪结果的目标目录名见 object_cropper.py可结合imgsz调整裁剪前推理分辨率。vision_pointtuple默认(20, 20)VisionEye仿人眼视角映射模块的参考“注视点”所有目标质心会向该点连线并绘制轨迹路径见 vision_eye.py。recordsint默认5SecurityAlarm 触发邮件报警所需的累计检测记录数阈值见 security_alarm.py。达到该数值后系统发送告警邮件并重置计数。json_filestr默认NoneParkingManagement 读取的停车位坐标 JSON 文件路径由 parking_management.py 加载用于把预标注的每个车位多边形绑定到画面。测速换算与相似搜索fps、max_hist、meter_per_pixel、max_speed、datafpsfloat默认30.0SpeedEstimator 假定或指定的视频帧率用于把“每帧位移”折算成“每秒位移”见 speed_estimation.py。max_histint默认5正式计算速度前保留的每个目标的轨迹历史点数历史点数不足时不会输出速度避免瞬时抖动造成误判见 speed_estimation.py。meter_per_pixelfloat默认0.05像素到真实世界的尺度因子每像素对应多少米/其他单位取决于摄像机安装高度与视角需按实际场景标定见 speed_estimation.py。max_speedint默认120叠加层中的速度上限阈值超速时触发高亮告警提示见 speed_estimation.py。datastr默认imagesSimilaritySearchCLIP 语义检索扫描的图像目录。若目录不存在similarity_search.py 会告警并自动下载images.zip演示集首次运行会把目录内图片路径缓存到paths.npy二次启动直接加载。参数默认值的权威来源SolutionConfig宏中给出的默认值并非写死在模板里——它们与运行时的配置类是同源镜像。仓库中的 SolutionConfig 是一个dataclass逐字段定义了相同的默认值例如region: list[tuple[int, int]] | None None colormap: int | None cv2.COLORMAP_DEEPGREEN up_angle: float 145.0 kpts: list[int] field(default_factorylambda: [6, 8, 10]) blur_ratio: float 0.5 meter_per_pixel: float 0.05 fps: float 30.0 max_hist: int 5 max_speed: int 120 verbose: bool True imgsz: int 640除宏中列出的 24 个参数外SolutionConfig 还维护了一批“配套”字段classes类别过滤、show/show_conf/show_labels/show_boxes可视化开关、conf/iou/max_det/device/tracker/quantize跟踪与推理。值得关注的是SolutionConfig.update(**kwargs)方法见 config.py它承担两件事合法性校验逐 key 用hasattr校验若传入配置对象中不存在的参数会抛出ValueError提示用户查看 Solutions Arguments 文档——正是本文所分析的宏渲染出的那张表废弃参数桥接兼容旧的half布尔参数收到后会打印弃用告警并映射为新的quantize字段halfTrue→quantize16即 FP16。参数如何进入运行时BaseSolution 的消费链路在 BaseSolution.init中可完整追踪参数的落地点构造SolutionConfig()并调用update(**kwargs)随后用vars()转成字典self.CFG——用户传入的 kwargs 在此覆盖默认值逐字段取出常用配置region、line_width、classes、show_conf、show_labels、device等被缓存为实例属性组装跟踪转发参数track_add_args仅把跟踪相关的键iou、conf、device、max_det、quantize、tracker、imgsz透传给底层model.track()每帧处理时 extract_tracks 调用self.model.track(sourceim0, persistTrue, classesself.classes, verboseFalse, **self.track_add_args)兼容 OBB 与普通检测框两种track_data形态随后把boxes / clss / track_ids / confs解包供各子类使用。也就是说宏表格里看到的conf、iou、device、tracker等跟踪参数虽然不单独占用 Solutions 自己的字段但会经SolutionConfig原样转发给 YOLO 的 track 调用因此它们同样可以在任何 Solutions 构造函数或 CLI 中直接设置。与跟踪参数宏的配套关系Solutions 的文档体系把参数分成三层彼此无缝对接Solutions 参数本宏 solutions-args.md上述 24 个应用层参数跟踪参数宏 solutions-track-args.mdtracker默认botsort.yaml内置还支持bytetrack.yaml、ocsort.yaml、deepocsort.yaml、fasttrack.yaml、tracktrack.yaml配置文件位于 cfg/trackers、conf默认0.25、iou默认0.7、classes默认None、device默认None可视化参数宏 visualization-args.mdshow、show_conf、show_labels等。在各指南页面中这三张表往往连续出现例如 heatmaps.md 依次渲染 Solutions 参数、跟踪参数、可视化参数并伴有!!! note提示块说明“tracker、conf、iou、classes、device会被转发给track”index.md。参数与各解决方案模块的对应速查综合各指南调用与源码字段读取位置可将主要模块与高频参数归纳如下模块类主要相关参数参考指南ObjectCounterregion、show_in、show_out、line_width对象计数RegionCounterregiondict 多区区域计数QueueManagerregion队列管理TrackZoneregion区域跟踪Heatmapcolormap、show_in、show_out、region热力图AIGymup_angle、down_angle、kpts动作监测SpeedEstimatorfps、max_hist、meter_per_pixel、max_speed测速ObjectBlurrerblur_ratio目标模糊ObjectCroppercrop_dir、imgsz目标裁剪VisionEyevision_pointVisionEyeSecurityAlarmrecords安防报警ParkingManagementjson_file停车场管理Analyticsanalytics_type、figsizeAnalyticsDistanceCalculationline_width距离计算VisualAISearchdata相似度搜索注意相似度搜索不使用目标跟踪因此不依赖conf、iou、tracker等跟踪参数此外按 index.md 的说明除 Similarity Search 外每个 Solutions 的process调用都会返回SolutionResults对象其中包含in_count、out_count、classwise_count等字段。实战宏之外的代码用法宏负责“文档里的参数说明”而真正使用这些参数的方式是 Python API 或 CLI。以下用法均可直接从仓库的类导出__all__见 solutions/init.py共导出 18 个公开类import cv2 from ultralytics import solutions im0 cv2.imread(path/to/frame.jpg) region_points [(20, 400), (1080, 400), (1080, 360), (20, 360)] # 画面上任意多边形 # 对象计数覆盖 show_in/show_out/region/line_width 等宏中参数 counter solutions.ObjectCounter( modelyolo26n.pt, # model 参数不传则回退 yolo26n.pt regionregion_points, # region 参数None 时用内置默认区域 show_inTrue, show_outTrue, line_width2, # 全模块通用线宽 classes[0], # 只计数 person ) out counter.count(im0) # 返回携带 in_count/out_count 的 SolutionResults命令行同样可用此时source参数才生效yolo solution solve sourcepath/to/video.mp4 modelyolo26n.pt若要临时关闭逐帧日志、减少画面干扰只需把宏表中的verboseFalse、show_outFalse等传入即可无需改动任何默认配置文件。小结solutions-args.md虽然以 Jinja2 宏的形式存在但它实质上是 Ultralytics Solutions 应用层的“参数 API 契约”文档侧由它统一生成 24 个参数的参考表运行侧由 SolutionConfig 提供同源默认值再由 BaseSolution 分发给模型加载、区域初始化与跟踪调用。理解这张参数表就理解了所有 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），仅供参考