MMDetection 可视化完全指南:从 Visualizer 配置到预测结果绘制
MMDetection 可视化完全指南:从 Visualizer 配置到预测结果绘制
MMDetection(OpenMMLab 检测工具箱)基于 MMEngine 的 Visualizer 机制,提供了一套从训练日志记录、验证结果绘制到数据集检查的完整可视化方案。本文以 docs/zh_cn/user_guides/visualization.md 为主线,结合仓库源码与配置,系统讲解如何在 MMDetection 中配置可视化后端(本地/TensorBoard/WandB)、通过 DetVisualizationHook 绘制并存储预测结果,以及如何借助 tools/test.py 与 tools/analysis_tools/browse_dataset.py 在不改配置的情况下快速可视化。读完本文,你将能够独立完成检测模型的训练监控、验证/测试结果可视化与数据集质量检查。
一、可视化体系概览:MMEngine Visualizer 与 MMDet 的预构建工具
MMDetection 的可视化能力构建在 MMEngine 的 Visualizer 之上。建议先了解 MMEngine 对 Visualizer 的定义与用法,它本质上承担三类职责:
- 通用绘图 API:例如
draw_bboxes绘制边界框、draw_lines绘制线条,为上层算法库提供统一的绘图原语; - 多后端写入:支持将可视化结果、学习率曲线、损失函数曲线以及验证精度曲线写入本地磁盘,以及 TensorBoard、WandB 等常见深度学习训练日志工具;
- 任意位置调用:支持在代码的任何位置调用,以可视化或记录模型在训练或测试期间的中间状态(如特征图、验证结果)。
基于此,MMDet 在仓库中提供了多种预构建的可视化工具,用户只需修改配置文件即可启用:
tools/analysis_tools/browse_dataset.py:数据集可视化脚本,可在数据经过数据转换(pipeline)后绘制图像和相应注释,用于检查数据增强效果与标注质量,详细说明见 可视化数据集;LoggerHook(来自 MMEngine):使用Visualizer将学习率、损失和评估结果写入后端。通过修改配置中Visualizer的vis_backends为TensorboardVISBackend或WandbVISBackend,即可将日志记录到对应训练工具,方便分析和监控训练过程;DetVisualizationHook(MMDet 实现):在验证或预测阶段使用Visualizer将预测结果可视化或存储到后端,同样可通过修改vis_backends将预测图像写入 TensorBoard 或 WandB。
二、配置 Visualizer:默认配置与两大组成
由于 MMDet 采用注册机制,Visualizer 的行为完全可以通过配置文件定制。默认配置定义在 configs/base/default_runtime.py:
vis_backends = [dict(type='LocalVisBackend')]
visualizer = dict(
type='DetLocalVisualizer', vis_backends=vis_backends, name='visualizer')
从上面的例子可以看到,Visualizer 的配置由两个主要部分组成:
| 配置项 | 说明 |
|---|---|
type |
Visualizer 的类型,默认为 DetLocalVisualizer,可直接用于可视化检测任务(目标检测、实例分割、语义分割、全景分割)的标签或预测结果 |
vis_backends |
可视化后端列表,MMDet 默认使用本地可视化后端 LocalVisBackend,将所有可视化结果与训练信息保存在本地文件夹 |
与 visualizer 配套的还有日志处理器与默认钩子,同样位于 configs/base/default_runtime.py:
default_hooks = dict(
timer=dict(type='IterTimerHook'),
logger=dict(type='LoggerHook', interval=50),
param_scheduler=dict(type='ParamSchedulerHook'),
checkpoint=dict(type='CheckpointHook', interval=1),
sampler_seed=dict(type='DistSamplerSeedHook'),
visualization=dict(type='DetVisualizationHook'))
log_processor = dict(type='LogProcessor', window_size=50, by_epoch=True)
其中 default_hooks.visualization 即训练/测试阶段负责绘制预测结果的钩子,默认启用但 draw=False(见下文第四节)。若需了解配置文件的继承与覆盖机制,可参考 配置教程。
2.1 DetLocalVisualizer 支持的完整参数
从源码 mmdet/visualization/local_visualizer.py 看,DetLocalVisualizer 除继承 MMEngine Visualizer 的 name、image、vis_backends、save_dir 参数外,还支持以下绘图参数:
| 参数 | 默认值 | 说明 |
|---|---|---|
bbox_color |
None |
边界框线条颜色;为 None 时自动从数据集 palette 获取(BGR 顺序) |
text_color |
(200, 200, 200) |
标注文本颜色,BGR 顺序 |
mask_color |
None |
掩码颜色;为 None 时自动从数据集 palette 获取 |
line_width |
3 |
边界框线条宽度(int 或 float) |
alpha |
0.8 |
边界框或掩码的透明度 |
三、存储:可视化后端与输出目录结构
MMDet 默认使用 LocalVisBackend 作为可视化后端。由 VisualizerHook 和 LoggerHook 存储的模型损失、学习率、模型评估精度和可视化信息,默认保存到 {work_dir}/{config_name}/{time}/{vis_data} 文件夹中。
除本地后端外,MMDet 还支持 TensorboardVisBackend 和 WandbVisBackend 等常见后端,只需要在配置文件中更改 vis_backends 类型即可。例如在继承 _base_ 的配置中插入以下代码块,即可同时将数据存储到本地、TensorBoard 与 WandB:
_base_.visualizer.vis_backends = [
dict(type='LocalVisBackend'),
dict(type='TensorboardVisBackend'),
dict(type='WandbVisBackend')]
3.1 三种后端的适用场景
| 后端类型 | 保存位置 | 适用场景 |
|---|---|---|
LocalVisBackend |
{work_dir}/{config_name}/{time}/{vis_data} |
默认后端,离线查看可视化文件,无第三方依赖 |
TensorboardVisBackend |
TensorBoard 事件文件 | 配合 tensorboard --logdir 在浏览器中监控训练曲线与预测图像 |
WandbVisBackend |
WandB 云端项目 | 团队协作、远程实验管理与对比,需配置 WandB 账号 |
需要说明的是,切换后端只影响可视化与日志数据的"出口"(即存储位置),并不影响 DetVisualizationHook 的绘制逻辑本身;绘制后的图像会以 add_image 的方式推送到所有已配置的后端。
四、绘图:DetVisualizationHook 的参数与工作原理
MMDet 主要使用 mmdet/engine/hooks/visualization_hook.py 中注册的 DetVisualizationHook 来绘制验证和测试的预测结果。默认情况下该钩子处于"关闭绘图"状态,其默认配置如下:
visualization = dict( # 用户可视化验证和测试结果
type='DetVisualizationHook',
draw=False,
interval=1,
show=False)
4.1 支持的参数
| 参数 | 描述 |
|---|---|
draw |
通过该 enable 参数打开和关闭钩子,默认状态为关闭(False) |
interval |
控制在钩子启用时存储或显示验证/测试结果的间隔,单位为迭代次数 |
show |
控制是否直接弹出窗口可视化验证或测试的结果 |
结合源码 visualization_hook.py,DetVisualizationHook 的完整构造参数还包括:
score_thr(默认0.3):可视化边界框和掩码的置信度阈值,低于该阈值的预测框不会被绘制;wait_time(默认0.):show=True时每个窗口的停留时间(秒);test_out_dir(默认None):测试过程中绘制图像的保存目录;backend_args(默认None):实例化文件后端(file client)的参数,用于读取远程/云存储中的图像。
4.2 钩子的内部工作流程(源码级)
DetVisualizationHook 通过两个回调方法挂载在 Runner 的验证与测试流程中:
after_val_iter(L79-L110):每interval次验证迭代,取当前 batch 的第一张图(outputs[0]),通过mmcv.imfrombytes以 RGB 顺序读取原图,然后调用self._visualizer.add_datasample(...)绘制。step取runner.iter + batch_idx,用于在曲线与图像时间轴上对齐;after_test_iter(L112-L151):测试阶段会遍历整个 batch 的每个样本(for data_sample in outputs),每张图递增_test_index。若指定了test_out_dir,则会拼接到{runner.work_dir}/{runner.timestamp}/{test_out_dir}下创建目录并逐张保存图像。
源码注释还明确了测试阶段三档行为的优先级(L26-L37):
show=True:仅弹窗展示预测结果,不存储数据,钩子会清空_vis_backends以避免同时写入后端;- 指定
test_out_dir:预测结果保存到该目录,同样排除vis_backends; - 两者均未指定:
vis_backends生效,可将预测结果存储到 WandB 或 TensorBoard。
此外,同一文件中还注册了面向多目标跟踪/视频实例分割任务的 TrackVisualizationHook(L154-L315,使用 frame_interval 控制抽帧间隔)以及面向开放词汇检测的 GroundingVisualizationHook(L345 起),说明可视化体系对不同任务均有专门实现。
五、在训练或测试期间启用预测结果可视化
如果您想在训练或测试期间启用 DetVisualizationHook 相关功能,只需修改配置文件。以 configs/rtmdet/rtmdet_tiny_8xb32-300e_coco.py 为例,同时绘制注释(GT)和预测(pred),并弹窗显示图像,配置文件可以修改如下:
visualization = _base_.default_hooks.visualization
visualization.update(dict(draw=True, show=True))
这里的 visualization.update 会覆盖基类配置(_base_ 继承自 rtmdet_s_8xb32-300e_coco.py 再向上继承 default_runtime.py)中的默认钩子设置:draw=True 打开绘图,show=True 在验证/测试时弹窗展示。
5.1 不修改配置:test.py 的 --show 与 --show-dir
tools/test.py 提供了 --show 和 --show-dir 参数,可以在测试过程中可视化注释和预测结果,而不需要修改配置文件,从而进一步简化测试过程:
# 展示测试结果
python tools/test.py configs/rtmdet/rtmdet_tiny_8xb32-300e_coco.py https://download.openmmlab.com/mmdetection/v3.0/rtmdet/rtmdet_tiny_8xb32-300e_coco/rtmdet_tiny_8xb32-300e_coco_20220902_112414-78e30dcc.pth --show
# 指定存储预测结果的位置
python tools/test.py configs/rtmdet/rtmdet_tiny_8xb32-300e_coco.py https://download.openmmlab.com/mmdetection/v3.0/rtmdet/rtmdet_tiny_8xb32-300e_coco/rtmdet_tiny_8xb32-300e_coco_20220902_112414-78e30dcc.pth --show-dir imgs/
注意:第一条命令中的 checkpoint 参数为官方预训练权重下载地址,实际使用时应替换为本地或自训的权重文件路径。
这两个参数生效的底层机制在 mmdet/engine/hooks/utils.py 的 trigger_visualization_hook 函数中:当传入 --show 或 --show-dir 时,tools/test.py 会调用该函数,将 default_hooks.visualization 中的 draw 置为 True,并根据命令行参数设置 show、wait_time 或 test_out_dir。也就是说,命令行参数最终仍是通过"改写配置中的可视化钩子"来实现的。
tools/test.py 还支持以下相关参数(见 parse_args):
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
--show |
store_true |
False |
弹窗展示预测结果 |
--show-dir |
str |
无 | 绘制图像的保存目录,实际保存到 work_dir/timestamp/show_dir |
--wait-time |
float |
2 |
弹窗展示的间隔时间(秒) |
--work-dir |
str |
无 | 评估结果等文件的保存目录,不指定时默认使用 ./work_dirs/{config_name} |
六、数据集可视化:browse_dataset.py
tools/analysis_tools/browse_dataset.py 用于检查数据集在经过数据转换 pipeline 之后的图像和标注,帮助排查数据增强配置或标注问题。其完整用法(见 useful_tools.md):
python tools/analysis_tools/browse_dataset.py ${CONFIG} [-h] [--output-dir ${OUTPUT_DIR}] [--not-show] [--show-interval ${SHOW_INTERVAL}]
支持的命令行参数(对应 parse_args):
| 参数 | 默认值 | 说明 |
|---|---|---|
config |
必填 | 训练配置文件路径(脚本会从 cfg.train_dataloader.dataset 构建数据集) |
--output-dir |
None |
无显示接口时,将绘制结果保存到该目录 |
--not-show |
False |
不弹窗展示(配合 --output-dir 在无 GUI 的服务器上使用) |
--show-interval |
2 |
弹窗展示间隔(秒) |
--cfg-options |
无 | 覆盖配置文件中的任意设置,格式为 key=value |
脚本主流程(main)值得注意的实现细节:
- 从配置中构建数据集
DATASETS.build(cfg.train_dataloader.dataset)与可视化器VISUALIZERS.build(cfg.visualizer),并把数据集的metainfo(类别、调色板)绑定到可视化器; - 遍历数据集,将 pipeline 输出的
inputs(CHW 张量)转为 HWC 的 RGB 图像,取出data_sample.gt_instances中的bboxes与masks(BitmapMasks/PolygonMasks统一转为布尔 ndarray); - 调用
visualizer.add_datasample(..., draw_pred=False, ...)只绘制 GT,draw_pred=False是因为数据集浏览场景没有预测结果。
七、深入源码:DetLocalVisualizer 如何绘制一幅检测图
DetLocalVisualizer.add_datasample(local_visualizer.py#L392-L506)是检测可视化的核心入口,理解它有助于掌握可视化结果的形态与行为:
- GT 与预测并列显示:当 GT 和预测同时绘制时,最终图像为
np.concatenate((gt_img_data, pred_img_data), axis=1)——左侧是 ground truth,右侧是预测结果(L485-L486); - 支持多任务数据:
add_datasample会依次检查data_sample中的gt_instances(实例级,调_draw_instances)、gt_sem_seg(语义分割,调_draw_sem_seg)与gt_panoptic_seg(全景分割,调_draw_panoptic_seg),预测侧同理(pred_instances/pred_sem_seg/pred_panoptic_seg); - 置信度过滤:预测实例会先按
pred_score_thr(默认0.3)过滤,pred_instances = pred_instances<a href="https://link.gitcode.com/i/59843692ff12075e52a405d4e0eb29d4" target="_blank">pred_instances.scores > pred_score_thr]([L465-L467),低分框不会出现在图中; - 自适应文本标注:在
_draw_instances(L108-L235)中,类别文本会附加置信度(如person: 92.3),字号根据框的面积自适应缩放(_get_adaptive_scales),文本框带半透明黑底以提高可读性;掩码则先转为多边形绘制白色轮廓,再以alpha透明度叠加彩色掩码,不同实例颜色由数据集palette生成并经jitter_color抖动; - 纯掩码模型兼容:对 SOLO 这类没有 bbox 分支的模型,代码通过
connectedComponentsWithStats计算掩码连通域质心,把类别标签画在实例中心(L196-L234); - 展示与保存分流:
show=True时调用self.show(...)弹窗显示;指定out_file时用mmcv.imwrite(drawn_img<a href="https://link.gitcode.com/i/dcfa0300bba1b3a9834c52c71a81d2a4" target="_blank">..., ::-1], out_file)写入(注意内部 BGR 转 RGB 的通道顺序);否则调用add_image推送到所有vis_backends([L500-L506)。
八、常见配置与使用要点小结
- 只想在验证时看几眼结果:在配置中修改
default_hooks.visualization,设draw=True, show=True,或直接使用tools/test.py --show; - 想把预测图保存成文件:
tools/test.py --show-dir imgs/,图像会落到work_dir/timestamp/imgs/;也可以直接设置钩子的test_out_dir; - 想用 TensorBoard/WandB 看预测图和训练曲线:把
visualizer.vis_backends追加TensorboardVisBackend/WandbVisBackend,训练、验证、测试的曲线与图像会自动同步; - 想检查数据增强后标注是否对齐:运行
tools/analysis_tools/browse_dataset.py ${CONFIG} --output-dir ${OUTPUT_DIR} --not-show,在无 GUI 服务器上批量导出可视化图; - 默认行为提醒:
DetVisualizationHook默认draw=False,即训练/验证过程默认不会额外绘制预测图,不会带来额外的 IO 开销;需要时再显式打开。
本文涉及的核心实现均可在本仓库中继续深入:可视化器源码 mmdet/visualization/local_visualizer.py、绘制钩子 mmdet/engine/hooks/visualization_hook.py、命令行入口 tools/test.py 与 tools/analysis_tools/browse_dataset.py,以及默认配置 configs/base/default_runtime.py。