ViTPose 项目 Webcam 背景抠像(Matting Effects)Demo 实战指南
ViTPose 项目 Webcam 背景抠像(Matting Effects)Demo 实战指南
本指南围绕 ViTPose 仓库中 tools/webcam/configs/background/README.md 讲解的"背景抠像"(Background Matting)Webcam Demo 展开,完整覆盖启动命令、快捷键、节点式配置结构、检测模型选择、CPU 运行与摄像头调试等实操内容,并结合仓库源码(节点实现、数据处理工具、Runner 机制)深入剖析其底层工作原理。读完本文,你将能够一键运行背景更换 Demo,并理解如何替换模型、切换背景、排查摄像头问题以及将同样的"节点管线"思想复用到其他 Webcam 应用中。
一、功能简介:给实时视频换背景
Matting(抠像)是视频处理中的经典需求:把画面中的前景人物从原始背景中"抠"出来,再合成到另一张背景图上。ViTPose 仓库通过 MMPose Webcam API 提供了一个开箱即用的 Matting Effects Demo,运行后摄像头画面中的人物前景会被保留,背景则被替换为一张静态图片,并且支持按 b 键实时切换特效开关。
整个 Demo 由 tools/webcam/run_webcam.py 启动脚本与 背景抠像配置 共同驱动,核心数据流为:目标检测(输出实例分割掩码)→ 人体姿态估计 → 结果与帧绑定 → 背景抠像绘制 → 帮助面板 → 监控面板 → 显示。
二、快速启动:一条命令运行 Demo
从 ViTPose 仓库根目录执行以下命令即可启动:
python tools/webcam/run_webcam.py --config tools/webcam/configs/background/background.py
启动脚本 tools/webcam/run_webcam.py 的逻辑非常简洁:先用 mmcv.Config.fromfile 读取配置,再用 WebcamRunner(**cfg.runner) 构建 Runner 并调用 run() 启动程序。运行前请确保环境满足 Webcam API 的依赖要求(详见 tools/webcam/README.md):
- Python >= 3.7.0
- MMPose >= 0.23.0
- MMDetection >= 2.21.0(本 Demo 必须安装,因为需要实例分割模型输出掩码)
首次运行需要联网,因为检测模型与姿态模型权重会按配置中的 URL 自动下载并加载。
快捷键一览
Demo 运行后会弹出显示窗口,支持以下快捷键:
| Hotkey | Function |
|---|---|
| b | Toggle the background matting effect on/off.(切换背景抠像特效开关) |
| h | Show help information.(显示帮助信息面板) |
| m | Show the monitoring information.(显示系统监控/诊断信息) |
| q | Exit.(退出程序) |
其中 b、h、m 分别对应配置中 BackgroundNode、NoticeBoardNode、MonitorNode 的 enable_key 参数;而 q(以及 ESC、Q)是 Runner 级别保留的退出键,见 webcam_runner.py 中 _on_keyboard_input 的实现:if key in (27, ord('q'), ord('Q')) 会触发 _exit_ 事件关闭整个程序。
注:按 README 说明,Demo 运行过程中会自动将输出视频保存到文件
record.mp4。需要说明的是,当前 background.py 配置中并未显式声明RecorderNode,若你的版本未自动生成录像文件,可以参考 test_camera.py 中的RecorderNode(其out_video_file参数可指定输出文件名,例如webcam_output.mp4)自行追加录像节点。
三、配置解析:一条由 6 个节点组成的处理管线
背景抠像 Demo 的全部逻辑都定义在 tools/webcam/configs/background/background.py 中。整个 runner 配置由两部分组成:Runner 基本参数(name、camera_id、camera_fps、synchronous)与 nodes 节点列表。每个节点通过 type(节点类名)、name(节点名)、input_buffer/output_buffer(输入输出缓冲名)以及各自的专属参数来声明。
3.1 Runner 基本参数
runner = dict(
name='Matting Effects',
camera_id=0,
camera_fps=10,
synchronous=False,
...
)
camera_id:摄像头 ID,0通常指默认摄像头;也可以传入视频文件路径或图片路径作为输入源(webcam_runner.py 中会根据is_image_file(camera_id)判断使用cv2.VideoCapture还是ImageCapture)。camera_fps:视频读取的最大 FPS,这里设为 10 是为了给耗时较长的模型推理留出余量。synchronous=False:异步模式。此时检测/姿态估计等耗时节点与显示解耦,保证画面流畅;ModelResultBindingNode会把"最新一次推理结果"绑定到"当前帧"上(两者可能存在时间差,这正是异步模式的预期行为)。
3.2 节点 1:DetectorNode(目标检测 + 实例分割)
dict(
type='DetectorNode',
name='Detector',
model_config='demo/mmdetection_cfg/mask_rcnn_r50_fpn_2x_coco.py',
model_checkpoint='https://download.openmmlab.com/'
'mmdetection/v2.0/mask_rcnn/mask_rcnn_r50_fpn_2x_coco/'
'mask_rcnn_r50_fpn_2x_coco_bbox_mAP-0.392'
'__segm_mAP-0.354_20200505_003907-3e542a40.pth',
input_buffer='_input_', # `_input_` is a runner-reserved buffer
output_buffer='det_result'),
DetectorNode 的实现位于 mmdet_node.py。它通过 init_detector(model_config, model_checkpoint, device) 加载 MMDetection 模型,并对每帧调用 inference_detector,随后在 _post_process 中把原始输出整理成统一的 preds 列表,每个元素包含:
cls_id:类别索引;label:类别名(如'person');bbox:边界框[x1, y1, x2, y2, score];mask:实例分割掩码。
关键前提:要进行背景抠像,检测模型必须能输出分割掩码(mask),因此这里的模型配置必须是 Mask R-CNN 这类带 mask head 的模型,而不是纯检测模型。当前使用的 mask_rcnn_r50_fpn_2x_coco.py 是一个标准的 Mask R-CNN + FPN(ResNet-50 骨干,COCO 80 类)配置,其 roi_head 中同时包含 bbox_head 与 mask_head(FCNMaskHead),推理时会返回 (dets, segms) 元组,DetectorNode._post_process 正是通过判断 isinstance(preds, tuple) 来分别提取边界框与分割掩码的。
3.3 节点 2:TopDownPoseEstimatorNode(人体姿态估计)
dict(
type='TopDownPoseEstimatorNode',
name='Human Pose Estimator',
model_config='configs/wholebody/2d_kpt_sview_rgb_img/'
'topdown_heatmap/coco-wholebody/'
'vipnas_mbv3_coco_wholebody_256x192_dark.py',
model_checkpoint='https://openmmlab-share.oss-cn-hangz'
'hou.aliyuncs.com/mmpose/top_down/vipnas/vipnas_mbv3_co'
'co_wholebody_256x192_dark-e2158108_20211205.pth',
cls_names=['person'],
input_buffer='det_result',
output_buffer='human_pose'),
TopDownPoseEstimatorNode(见 mmpose_node.py)使用 MMPose 的 top-down 姿态估计模型,输入依赖检测结果。实现要点:
cls_names=['person']:按类别名过滤检测结果,只对'person'实例做姿态估计(也支持用cls_ids按类别 ID 过滤)。bbox_thr=0.5(默认值):低于该分数的检测框会被跳过。- 底层调用
inference_top_down_pose_model完成推理,并通过get_track_id进行简单的跨帧目标跟踪(基于 OKS 阈值与 One-Euro 滤波平滑),为多人场景提供稳定的track_id。
这里使用的姿态模型是 ViPNAS-MBV3(COCO-WholeBody,256×192,DarkPose 解码),对应模型说明见 vipnas_dark_coco-wholebody.md。注意:在背景抠像 Demo 中,姿态估计结果本身不参与抠像,主要用于演示"检测 → 姿态估计"的标准管线串联能力。
3.4 节点 3:ModelResultBindingNode(结果与帧绑定)
dict(
type='ModelResultBindingNode',
name='ResultBinder',
frame_buffer='_frame_', # `_frame_` is a runner-reserved buffer
result_buffer='human_pose',
output_buffer='frame'),
ModelResultBindingNode(见 helper_node.py)负责把异步到达的模型推理结果绑定到对应的视频帧上。在 synchronous=False 时,它缓存"最新一次推理结果",并将其合并到当前帧消息中输出;同时会统计 result_fps、result_lag、frame_fps、frame_lag 等指标,供 MonitorNode 展示。它是保证"推理慢、显示流畅"这一异步设计得以成立的关键衔接节点。
3.5 节点 4:BackgroundNode(背景抠像特效)
dict(
type='BackgroundNode',
name='Visualizer',
enable_key='b',
enable=True,
frame_buffer='frame',
output_buffer='vis_bg',
cls_names=['person']),
这是本 Demo 的核心特效节点,对应 frame_effect_node.py 中的 BackgroundNode 类:
enable_key='b':绑定b键,用于实时开关背景特效;enable=True:默认开启;cls_names=['person']:只对person类别的掩码做抠像合成。
BackgroundNode.draw 的处理流程为:先按 cls_ids 或 cls_names 过滤检测结果,再调用 apply_background_effect。apply_background_effect 会选取得分最高的一个检测结果,将其实例掩码与边界框交给工具函数 copy_and_paste(位于 utils/misc.py)完成合成:
- 将掩码与前景区域裁剪到实例边界框内;
- 根据
effect_region(归一化坐标(x1, y1, x2, y2),默认(0.2, 0.2, 0.8, 0.8))计算目标区域并等比缩放实例; - 把掩码为 1 的像素从原帧"复制粘贴"到背景图上。
背景图默认可通过 src_img_path 参数指定(默认使用仓库作者提供的在线示例图),draw 中会先把背景图 cv2.resize 到与画布一致的分辨率再合成。若一帧中没有任何检测结果,则直接返回纯背景图。
3.6 节点 5、6:NoticeBoardNode 与 MonitorNode
dict(
type='NoticeBoardNode',
name='Helper',
enable_key='h',
frame_buffer='vis_bg',
output_buffer='vis',
content_lines=[
'This is a demo for background changing effects. Have fun!',
'', 'Hot-keys:', '"b": Change background',
'"h": Show help information',
'"m": Show diagnostic information', '"q": Exit'
],
),
dict(
type='MonitorNode',
name='Monitor',
enable_key='m',
enable=False,
frame_buffer='vis',
output_buffer='_display_')
NoticeBoardNode:按h键弹出帮助面板,content_lines即面板上逐行显示的文字内容(对应 README 中h键的说明)。MonitorNode:按m键展示诊断信息,enable=False表示默认关闭。它会在画面中叠加各节点上报的 FPS、延迟、CPU/内存占用等状态(通过psutil获取,未安装 psutil 时仅显示路由信息)。_display_是 Runner 保留缓冲:所有节点处理完的最终画面会被写入该缓冲,由 webcam_runner.py 的_display线程读出并cv2.imshow到窗口。
四、更换检测模型:从 MMDetection 模型库中选择
README 指出,用户可以从 MMDetection Model Zoo 中选择其他检测模型,只需要修改 DetectorNode 的 model_config 与 model_checkpoint 两个参数,模型会自动下载并加载。仓库在 demo/docs/mmdet_modelzoo.md 中整理了可用于 Webcam Demo 的 MMDetection 模型清单(如 Faster R-CNN、Cascade R-CNN、SSD、YOLOv3 等)。
更换时的两个硬性约束:
- 模型必须能够输出分割掩码。若选择的是纯目标检测模型(如 Faster R-CNN),
DetectorNode._post_process中segms会退化为[None] * len(dets),BackgroundNode因拿不到有效 mask 而无法完成抠像。务必选择 Mask R-CNN 一类带 mask head 的实例分割模型。 model_config与model_checkpoint必须配套,且model_config使用仓库根目录下的相对路径(例如demo/mmdetection_cfg/mask_rcnn_r50_fpn_2x_coco.py)。
五、无 GPU 环境:纯 CPU 运行
若设备没有 GPU 与 CUDA,Demo 依然可以运行,只需将所有模型节点的 device 参数设为 'cpu'。以 DetectorNode 为例:
dict(
type='DetectorNode',
name='Detector',
model_config='demo/mmdetection_cfg/mask_rcnn_r50_fpn_2x_coco.py',
model_checkpoint='https://download.openmmlab.com/'
'mmdetection/v2.0/mask_rcnn/mask_rcnn_r50_fpn_2x_coco/'
'mask_rcnn_r50_fpn_2x_coco_bbox_mAP-0.392'
'__segm_mAP-0.354_20200505_003907-3e542a40.pth',
device='cpu',
input_buffer='_input_', # `_input_` is a runner-reserved buffer
output_buffer='det_result'),
从源码看,device 是每个模型节点构造函数的显式参数:DetectorNode 与 TopDownPoseEstimatorNode 的默认值均为 'cuda:0',init_detector / init_pose_model 均接收 device 并调用 .lower() 归一化。CPU 推理速度较慢,建议同步把 camera_fps 调低(background.py 中已是 10),或配合 synchronous=True 使用,避免画面撕裂与队列堆积。
六、调试摄像头与显示:test_camera 配置
如果启动后摄像头无画面或显示异常,可以先运行调试配置:
python tools/webcam/run_webcam.py --config tools/webcam/configs/examples/test_camera.py
test_camera.py 仅包含两个节点:
MonitorNode:按m键在画面中叠加摄像头信息(Camera ID、分辨率、源 FPS)与各节点诊断数据;RecorderNode:将输出帧写入webcam_output.mp4(out_video_fps默认 30,编码默认mp4v)。
该配置不含任何模型节点,用于隔离验证摄像头读取、显示与录像链路是否正常,是排查问题时的首选最小化配置。若确认摄像头正常,再回到背景抠像配置排查模型加载与推理环节。
七、工作原理小结:Runner、Node 与 Buffer
理解本 Demo 的另一种视角是把握 Webcam API 的三个核心抽象(详见 tools/webcam/docs/get_started_cn.md):
- Runner:程序主体,负责视频读入、显示输出与事件分发。
WebcamRunner.run()会为每个 Node 启动独立线程(Node继承自threading.Thread,见 node.py),并由BufferManager统一管理各节点间的数据缓冲。 - Node:功能模块,模型推理、结果绑定、特效绘制、帮助面板等都以 Node 形式实现,通过
input_buffer/output_buffer串成有向无环图。 - Buffer:有限长度的数据队列。写满时"挤掉最旧数据"而不是阻塞(默认帧缓冲大小为 1)。
_input_(供推理)、_frame_(供可视化)、_display_(供最终显示)是三个 Runner 保留缓冲名。
背景抠像 Demo 正是这套机制的典型应用:DetectorNode 从 _input_ 读帧推理(耗时长),_frame_ 上的可视化链路保持实时,ModelResultBindingNode 弥合两者时间差,最终 BackgroundNode 依据实例分割掩码完成前景保留、背景替换的抠像合成。
八、常见问题与调试建议
- 提示
Please install mmdet to run the demo.:DetectorNode在导入mmdet.apis失败时会直接断言报错,说明 MMDetection 未安装或版本过低,请安装 MMDetection >= 2.21.0。 - 背景没有变化:检查
DetectorNode所用模型是否带 mask head;确认BackgroundNode的cls_names(或cls_ids)与检测模型的类别名一致(本 Demo 为'person');确认画布中确实存在得分足够的检测框。 - 画面卡顿:CPU 环境下适当降低
camera_fps,或将synchronous设为True;MonitorNode(m键)可实时查看各节点 FPS 与延迟,定位瓶颈节点。 - 更换背景图片:修改
BackgroundNode的src_img_path,可以指向本地图片路径或在线图片 URL(工具函数load_image_from_disk_or_url会按需自动下载)。