MMDetection 可视化完全指南:从 Visualizer 配置到预测结果绘制

原创2026-09-19 19:26:341,682 阅读
文章标签:计算机视觉深度学习

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):

  1. show=True:仅弹窗展示预测结果,不存储数据,钩子会清空 _vis_backends 以避免同时写入后端;
  2. 指定 test_out_dir:预测结果保存到该目录,同样排除 vis_backends;
  3. 两者均未指定: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)值得注意的实现细节:

  1. 从配置中构建数据集 DATASETS.build(cfg.train_dataloader.dataset) 与可视化器 VISUALIZERS.build(cfg.visualizer),并把数据集的 metainfo(类别、调色板)绑定到可视化器;
  2. 遍历数据集,将 pipeline 输出的 inputs(CHW 张量)转为 HWC 的 RGB 图像,取出 data_sample.gt_instances 中的 bboxes 与 masks(BitmapMasks/PolygonMasks 统一转为布尔 ndarray);
  3. 调用 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)。

八、常见配置与使用要点小结

  1. 只想在验证时看几眼结果:在配置中修改 default_hooks.visualization,设 draw=True, show=True,或直接使用 tools/test.py --show;
  2. 想把预测图保存成文件:tools/test.py --show-dir imgs/,图像会落到 work_dir/timestamp/imgs/;也可以直接设置钩子的 test_out_dir;
  3. 想用 TensorBoard/WandB 看预测图和训练曲线:把 visualizer.vis_backends 追加 TensorboardVisBackend / WandbVisBackend,训练、验证、测试的曲线与图像会自动同步;
  4. 想检查数据增强后标注是否对齐:运行 tools/analysis_tools/browse_dataset.py ${CONFIG} --output-dir ${OUTPUT_DIR} --not-show,在无 GUI 服务器上批量导出可视化图;
  5. 默认行为提醒: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。

登录后查看全文
mmdetection