Ultralytics 推理结果可视化与保存参数详解从 show、save 到标注控制【免费下载链接】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/macros/visualization-args.md 为主线系统讲解 YOLO26、YOLO11、YOLOv8 等在预测predict与各类 Solutions 应用计数、热力图、测速、姿态监测等中通用的可视化与结果输出参数。读完本文你将掌握show、save、save_frames、save_txt、save_crop、show_labels、show_conf、show_boxes、line_width等 10 个参数的确切语义、默认值、适用场景以及它们在 Python API 与 CLI 调用下的行为差异与底层实现链路。一、这套参数是什么、定义在哪里visualization-args.md并不是一份孤立的说明文档而是 Ultralytics 文档站基于 MkDocs Jinja2 宏机制定义的一段可复用参数表模板。它导出param_table宏把可视化与结果输出参数整理成统一的一张表格供多篇文档共同引用预测模式文档 docs/en/modes/predict.mdInference / Visualization arguments 小节配置总览文档 docs/en/usage/cfg.md 的Predict Settings一节Solutions 应用类文档如 docs/en/solutions/index.md 以及 object-counting、heatmaps、speed-estimation、parking-management、queue-management、workouts-monitoring 等 guides。宏同时支持全量表格与子集表格两种渲染方式不传参时输出全部参数如{{ param_table() }}传入参数名列表时只输出指定子集如 docs/en/solutions/index.md 中{{ param_table([show, show_conf, show_labels]) }}从而保证同一份参数口径在多篇文档间保持完全一致、不会出现前后矛盾。在代码侧这组参数的真实默认值定义于配置文件 ultralytics/cfg/default.yaml并被 ultralytics/cfg/init.py 解析为CFG_BOOL_KEYS布尔型与CFG_INT_KEYS整型统一管理。二、完整参数表与默认值以下即为param_table()宏输出的 10 个可视化/输出参数的完整定义来自 docs/macros/visualization-args.md可对照 ultralytics/cfg/default.yaml 中的实际取值ArgumentTypeDefaultDescriptionshowboolFalse若为True将标注后的图像或视频实时显示在窗口中便于在开发调试阶段即时获得视觉反馈。saveboolFalse or True是否将标注结果保存为文件便于存档、二次分析或结果分享。CLI 下默认TruePython 下默认False。save_framesboolFalse处理视频时将每一帧单独保存为图片便于抽取关键帧或做逐帧分析。save_txtboolFalse将检测结果写入文本文件行格式为[class] [x_center] [y_center] [width] [height] [confidence]方便接入其他分析工具。save_confboolFalse是否把置信度一并写入save_txt输出的文本文件中为后处理与分析提供更细粒度的信息。save_cropboolFalse将每个检测目标单独裁剪保存为图片可用于数据增强、分析或构建面向特定目标的数据集。show_labelsboolTrue在可视化结果上绘制每个检测的类别标签如person便于快速理解检测到的物体。show_confboolTrue在标签旁显示每个检测的置信度分数反映模型对每个预测的把握程度。show_boxesboolTrue围绕检测目标绘制边界框是图像或视频帧中视觉定位目标的必要手段。line_widthint or NoneNone指定边界框的线宽。为None时根据图像尺寸自动缩放兼顾美观与清晰度。三、参数分组语义解析这 10 个参数可按用途划分为四组便于理解与记忆。1. 交互显示showshow决定是否把标注结果弹出窗口实时展示。其窗口逻辑在 ultralytics/engine/predictor.py 的show()方法中实现调用cv2.imshow前会先创建可缩放、保持宽高比的窗口Linux/Windows 下自动按屏幕分辨率适配窗口尺寸单张图片停留约 300ms视频逐帧显示任意时刻按q键即可中断推理循环抛出StopIteration。该参数更适合桌面交互式调试在无显示环境如纯服务器运行时建议保持False改用save。2. 结果落盘save / save_frames / save_txt / save_conf / save_crop这一组控制结果以什么形态保存到磁盘是实际业务中最常用的一组save保存标注后的图像/视频本身。在 ultralytics/engine/predictor.py 的save_vid_or_img()中单张图片以.jpg落盘视频则按平台自动选择编码macOS 输出.mp4(avc1)Windows 输出.avi(WMV2)其余平台输出.avi(MJPG)帧率沿用源视频fps。save_frames仅对视频生效打开后会创建名为视频名_frames/的独立目录逐帧写入视频名_帧号.jpg与整段视频输出互不干扰方便逐帧复核。save_txt把结构化检测结果落成纯文本。在 ultralytics/engine/results.py 的save_txt()中每个检测目标输出一行。核心判断是否追加置信度列由save_conf控制若推理带跟踪 IDTrack 模式行尾还会追加 id 列。这种[class] [x_center] [y_center] [width] [height] [confidence]的极简格式非常利于与下游脚本、数据库对接。save_conf与save_txt协同的开关追加置信度列见上。save_crop将每个目标按框裁剪为独立图片。需注意并非所有任务都支持代码在 ultralytics/engine/results.py 中对classify分类、obb旋转框、semantic语义分割、depth深度任务打印警告并不执行裁剪仅detect/segment/pose等基于框的结果支持。3. 标注内容show_labels / show_conf / show_boxes这组控制框里画什么、框上标什么show_boxesTrue时才会在图上逐框调用annotator.box_label()绘制边界框show_labelsTrue时框标签文字为类别名跟踪场景还会加id:编号前缀show_confTrue时在标签后附加保留两位小数的置信度值如person 0.92。三者协同的落点在 ultralytics/engine/predictor.py 的write_results()它把self.args.show_boxes、self.args.show_conf、self.args.show_labels分别透传给Results.plot(conf..., labels..., boxes...)而 ultralytics/engine/results.py 的plot()再用Annotator完成实际的绘制。也就是说你完全可以只画框不写字show_labelsFalse, show_confFalse或只要类别名不要置信度。4. 绘制外观line_widthline_width控制边界框线宽。其为None时绘图底层会根据图像尺寸自动计算合适线宽见 ultralytics/engine/results.py 中plot()对line_width的说明If None, scaled to image size处理大分辨率图像时无需手工调参对线宽有严格美学/展示要求时再显式传入整数像素值。它被登记在CFG_INT_KEYS中只接受整数。四、Python API 与 CLI 的调用差异同一组参数在两种入口下的写法与默认行为略有差异这一点由save的默认值最能体现宏定义中明确标注CLI 下默认保存、Python 下默认不保存。Python API例如 docs/en/modes/predict.md 中的示例from ultralytics import YOLO model YOLO(yolo26n.pt) # 保存标注图、另存检测 txt、并按框裁剪目标、输出线宽 2 model.predict(https://ultralytics.com/images/bus.jpg, saveTrue, save_txtTrue, save_cropTrue, line_width2)CLIyolo predict modelyolo26n.pt sourcehttps://ultralytics.com/images/bus.jpg saveTrue save_txtTrue showFalse line_width2还可以通过命令行的取反写法快速关闭默认开启的开关例如show_labelsFalse、show_confFalse隐藏标签文字只保留纯框输出。另外对老版本记忆中的参数名无需担心——配置解析层 ultralytics/cfg/init.py 内置了别名兼容映射boxes → show_boxes、hide_labels → show_labels布尔取反、hide_conf → show_conf布尔取反、line_thickness → line_width历史脚本传入旧名时会自动转换并给出弃用提示。五、底层实现链路与关键证据要真正理解这些参数看一遍推理管线的调用链会更直观。核心在 ultralytics/engine/predictor.pywrite_results()中只要verbose、save、save_txt、save_crop、show任一开启就会执行结果后处理把show_boxes / show_conf / show_labels / line_width传给Results.plot()绘框、写标签、画置信度save_txt开启时调用result.save_txt(txt_path, save_conf...)save_crop开启时调用result.save_crop(save_dir, file_name)视频帧保存与逐帧落图统一由save_vid_or_img()完成。同时这些布尔开关全部收录于 ultralytics/cfg/init.py 的CFG_BOOL_KEYS意味着任意来源YAML、CLI、Python 参数字典都会经过统一的类型校验与默认值合并不会出现某入口可用、某入口失效的问题。如果你希望对某几类任务做带返回值的细粒度自定义可视化例如只返回标注好的数组而不落盘也可以直接复用Results.plot(conf..., labels..., boxes..., line_width...)拿到np.ndarray后再自行处理。六、与 Ultralytics Solutions 的组合使用这套参数不仅作用于模型推理也被Ultralytics Solutions物体计数、热力图、区域计数、测速、停车管理、队列管理、工作流监测、距离计算、安检、analytics 等广泛复用。以 docs/en/solutions/index.md 为例其中明确提示 You can useshow_conf,show_labels, and other mentioned arguments to customize the visualization并仅选取show、show_conf、show_labels三个与标注展示最相关的参数渲染子表。典型写法from ultralytics import solutions counter solutions.ObjectCounter( modelyolo11n.pt, conf0.5, showTrue, # 弹出实时预览窗口 show_confTrue, # 显示置信度 show_labelsTrue, # 显示类别标签 )例如在 docs/en/guides/object-counting.md、docs/en/guides/heatmaps.md、docs/en/guides/speed-estimation.md、docs/en/guides/workouts-monitoring.md 等 Guides 页面中都会在参数说明区嵌入同一份param_table保证推理模式与业务化 Solutions 场景的参数语义完全统一。Solutions 的show窗口响应逻辑同样在 ultralytics/cfg/init.py 中统一处理cv2.waitKeyq键退出。七、配置落点与快速参考全部 10 个参数的默认值都能在 ultralytics/cfg/default.yaml 中查到作为运行时未显式指定时的取值基准save: True # (bool) 训练检查点与预测结果是否保存Python API 下默认为 False show: False # (bool) 是否在窗口中展示图像/视频需图形环境 save_frames: False # (bool) 视频预测时逐帧保存图片 save_txt: False # (bool) 结果另存为 .txtxywh 归一化格式 save_conf: False # (bool) 结果文本中附带置信度 save_crop: False # (bool) 裁剪保存每个预测区域 show_labels: True # (bool) 图像上绘制类别标签如 person show_conf: True # (bool) 图像上绘制置信度如 0.99 show_boxes: True # (bool) 图像上绘制边界框 line_width: # (int, 可选) 边界框线宽未设置时随图像尺寸自动缩放在使用上可遵循几条经验原则开发调试用showTrue结果归档与分享用saveTruePython 下需显式开启对接后端分析管线用save_txtTrue配合save_confTrue保留置信度列构建目标数据集或做裁剪样本用save_cropTrue处理视频需逐帧取图用save_framesTrue追求无干扰的纯框可视化则关掉show_labels/show_conf。需要留意的是show依赖桌面图形环境服务器/容器内推理建议配合save使用save_crop不适用于分类、OBB、语义分割与深度估计任务line_width应传整数缺省时由框架按图像尺寸自动适配无需手工微调即可获得清晰的可视化效果。【免费下载链接】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），仅供参考