ViTPose 仓库 Webcam 姿态估计实时演示(Pose Estimation Demo)实战指南

原创2026-10-14 17:06:121,718 阅读
文章标签:人工智能计算机视觉深度学习机器学习

ViTPose 仓库 Webcam 姿态估计实时演示(Pose Estimation Demo)实战指南

本指南以 tools/webcam/configs/examples/README.md(Pose Estimation Demo)为核心,系统讲解如何在 ViTPose 仓库中基于 MMPose Webcam API 启动一套"目标检测 → 人体/动物姿态估计 → 可视化"的实时摄像头演示程序,并深入剖析其运行原理、快捷键机制、节点化配置结构与模型替换方法。阅读完本文后,你将能够独立运行该演示、按需更换检测/姿态模型、切换 CPU 推理、并依据源码理解整个 Webcam 数据流的底层实现。

一、Demo 概览:一次启动,检测、估计与可视化全流程

Pose Estimation Demo 是 MMPose Webcam API 提供的入门示例:它从摄像头(或本地视频文件)逐帧读取画面,依次执行人体边界框检测(目标检测)与关键点检测(姿态估计),并把检测框、骨骼连线实时绘制回画面显示。该 Demo 同时串联了两个姿态估计模型——一个用于人体(whole-body 133 关键点),另一个用于猫、狗、马、羊、牛等动物(20 关键点),因此画面中可以同时为人物和动物标注姿态。

从仓库结构看,该 Demo 属于 tools/webcam 目录下的一个示例配置,与其并列的还有眼睛特效(sunglasses/bug-eye)、换脸(face swap)、赛亚人变身、新年鞭炮等交互应用,均基于同一套 Webcam API 搭建。本 Demo 对应的完整节点配置位于 pose_estimation.py。

二、运行前的环境准备

根据 tools/webcam/README.md 的说明,运行 Webcam 应用需要满足以下基础条件:

  • Python >= 3.7.0
  • MMPose >= 0.23.0
  • MMDetection >= 2.21.0
  • 一台带摄像头的计算机(自带摄像头或外接 USB 摄像头均可;GPU/CUDA 并非必需,可通过配置切换到 CPU 推理,详见后文)

特别要注意的是:Demo 中的检测节点 DetectorNode 依赖 MMDetection 的推理接口。在 mmdet_node.py 中有一段强制校验:

assert has_mmdet, 'Please install mmdet to run the demo.'

也就是说,必须安装 MMDetection 才能运行该 Demo,否则程序会在构建检测节点时直接报错退出。

三、启动演示:入口脚本与启动命令

Demo 的启动方式非常简单,在仓库根目录(即 mmpose 根目录)执行:

python tools/webcam/run_webcam.py --config tools/webcam/configs/examples/pose_estimation.py

启动脚本 run_webcam.py 的逻辑非常精简,可概括为三步:读取配置 → 构建 Runner → 调用 run() 启动。

def launch():
    args = parse_args()
    cfg = Config.fromfile(args.config)          # 1. 读取 config 文件
    cfg.merge_from_dict(args.cfg_options)       # 2. 合并命令行覆盖项
    runner = WebcamRunner(**cfg.runner)         # 3. 用 runner 字段构建 WebcamRunner
    runner.run()                                # 4. 启动

该脚本支持两个命令行参数:

参数 说明 示例
--config 指定要加载的 Webcam 配置文件(默认值为 tools/webcam/configs/meow_dwen_dwen/meow_dwen_dwen.py) --config tools/webcam/configs/examples/pose_estimation.py
--cfg-options 以 key=value 形式临时覆盖配置中的任意字段,支持嵌套路径与多个键值对 --cfg-options runner.camera_id=1 runner.synchronous=True

例如,若想在不修改配置文件的前提下切换摄像头,可直接运行:

python tools/webcam/run_webcam.py --config tools/webcam/configs/examples/pose_estimation.py \
    --cfg-options runner.camera_id=1

四、快捷键一览

Demo 运行期间,以下快捷键实时生效:

快捷键 功能
v 开/关姿态可视化结果(切换 PoseVisualizerNode 的启用状态)
h 显示帮助信息(弹出 NoticeBoardNode 的内容面板)
m 显示监控/诊断信息(CPU、内存、各节点 FPS 与延迟等)
q 退出程序

从源码层面看,快捷键由 webcam_runner.py 中的 _on_keyboard_input 统一处理:按 q/Q 或 ESC(ASCII 27)会触发 _exit_ 事件结束程序;其他按键则被包装为键盘事件,分发给注册了对应 enable_key 的节点。例如 v、h、m 分别对应 PoseVisualizerNode、NoticeBoardNode、MonitorNode 的 enable_key 参数,节点内部通过 register_event 注册事件处理器,实现启用/禁用状态的切换(详见 node.py)。

此外需要注意:Demo 退出时会把整段输出视频自动保存为 record.mp4 文件(保存在当前工作目录),该行为由配置末尾的 RecorderNode 完成。

五、配置文件深度解析:8 个节点构成的流水线

pose_estimation.py 是 Demo 的核心配置。它本质上是一个 Python 字典 runner = dict(...),由 Runner 级基本参数与 nodes 节点列表两部分组成。下面按数据流顺序逐段解析。

5.1 Runner 基本参数

runner = dict(
    name='Pose Estimation',
    camera_id=0,
    camera_fps=20,
    synchronous=False,
    nodes=[...])

对应 WebcamRunner 的构造函数,各参数含义如下:

  • name:Runner 名称,同时用作显示窗口标题。
  • camera_id:摄像头 ID(默认 0 为系统默认摄像头)。也可以是本地视频文件路径或 URL,此时程序会改用该视频作为输入源。
  • camera_fps:视频读取的最大 FPS,默认 30,这里设置为 20。
  • synchronous:是否同步模式。默认 False(异步):模型推理较慢时,画面显示仍保持流畅,推理结果与当前帧异步绑定(见 5.5 节)。
  • 可选参数还包括 camera_frame_shape(设置摄像头采集分辨率 (width, height))与 buffer_sizes(自定义各缓冲区的容量)。

5.2 数据流与保留 Buffer:理解节点如何"接线"

Webcam API 的核心设计是用 Buffer 名字把节点连成一张有向无环图(DAG)。每个节点通过 input_buffer 指定输入、通过 output_buffer 指定输出,前一个节点的输出缓冲区正是后一个节点的输入缓冲区。

Runner 预置了三个保留名称的缓冲区(见 webcam_runner.py):

保留 Buffer 用途
_input_ 存放 runner 读入的视频帧,供模型推理类节点(耗时操作)使用
_frame_ 存放 runner 读入的视频帧,供可视化类节点实时绘制使用
_display_ 存放经过所有节点处理后的最终结果,由 runner 读出并显示

在 BufferManager 中,每个 Buffer 本质是有限长度的队列;默认 _frame_、_input_ 容量为 1,_display_ 容量为 0(无上限),用户自定义 buffer 默认容量为 1。当缓冲区已满时,写入采用 put_force 策略:不阻塞,而是把最早的一条数据挤出,从而保证实时性。

之所以同时提供 _input_ 与 _frame_ 两个输入,是因为检测/姿态估计等模型推理节点耗时较长;将这类耗时操作放在 _input_ 链路上,而可视化绘制走 _frame_ 链路,可以让节点在各自线程中异步运行,确保显示流畅不卡顿。

5.3 节点 1:DetectorNode —— 人体边界框检测

dict(
    type='DetectorNode',
    name='Detector',
    model_config='demo/mmdetection_cfg/'
    'ssdlite_mobilenetv2_scratch_600e_coco.py',
    model_checkpoint='https://download.openmmlab.com'
    '/mmdetection/v2.0/ssd/'
    'ssdlite_mobilenetv2_scratch_600e_coco/ssdlite_mobilenetv2_'
    'scratch_600e_coco_20210629_110627-974d9307.pth',
    input_buffer='_input_',  # `_input_` 是 runner 保留缓冲区
    output_buffer='det_result')

该节点接收摄像头帧(来自 _input_),用 MMDetection 的目标检测模型推理出所有目标的边界框与类别,输出到 det_result 缓冲区。核心参数:

  • model_config:检测模型配置文件路径。示例用的是 ssdlite_mobilenetv2_scratch_600e_coco.py——一个基于 MobileNetV2 + SSD 轻量检测头的单阶段检测器,COCO 80 类(num_classes=80),输入尺寸 320×320,兼顾速度与精度,适合实时 Webcam 场景。
  • model_checkpoint:预训练权重 URL。程序会自动下载该权重并加载。
  • device:推理设备,默认 'cuda:0';无 GPU 时可设为 'cpu'。

从 mmdet_node.py 的实现看,节点构建时调用 init_detector(model_config, model_checkpoint, device=...) 完成模型初始化;每处理一帧则调用 inference_detector 推理,并经过 _post_process 将结果打包为 {'preds': [...], 'model_cfg': ...} 结构,每个预测对象包含 cls_id(类别索引)、label(类别名,如 person、cat)、bbox(边界框)与可选的 mask(分割掩码)。这些结果以 add_detection_result 的方式挂载到当前帧的 FrameMessage 上。

5.4 节点 2 & 3:TopDownPoseEstimatorNode —— 人体与动物姿态估计

Demo 中并排配置了两个姿态估计节点,分别处理人类与动物,这体现了该 Demo 最有价值的一个特性:同一个数据流中,可以为不同类别的目标挂接不同的姿态模型。

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'),
dict(
    type='TopDownPoseEstimatorNode',
    name='Animal Pose Estimator',
    model_config='configs/animal/2d_kpt_sview_rgb_img/topdown_heatmap'
    '/animalpose/hrnet_w32_animalpose_256x256.py',
    model_checkpoint='https://download.openmmlab.com/mmpose/animal/'
    'hrnet/hrnet_w32_animalpose_256x256-1aa7f075_20210426.pth',
    cls_names=['cat', 'dog', 'horse', 'sheep', 'cow'],
    input_buffer='human_pose',
    output_buffer='animal_pose')

模型选择:本 Demo 使用的两个 top-down 姿态模型分别为:

  • 人体模型 vipnas_mbv3_coco_wholebody_256x192_dark.py:基于 ViPNAS_MobileNetV3 轻量骨干,输出 133 个 whole-body 关键点(num_output_channels=133),输入尺寸 256×192,推理时开启水平翻转测试(flip_test=True)与 post_process='unbiased'(无偏解码)。
  • 动物模型 hrnet_w32_animalpose_256x256.py:基于 HRNet-W32 骨干,输出 20 个动物关键点,输入尺寸 256×256。

类别过滤机制:cls_names 是这两个节点最关键的参数。从 mmpose_node.py 的源码可以看到,节点会先读取检测结果,然后按 cls_ids(类别索引)或 cls_names(类别名)过滤出自己关心的目标:

  • 人体节点只接收 cls_names=['person'] 的检测框;
  • 动物节点接收 cls_names=['cat', 'dog', 'horse', 'sheep', 'cow'] 的检测框;
  • 由于动物节点的 input_buffer='human_pose' 直接串联在人体节点之后,其输入实际上是人体节点输出携带了检测结果的同一帧消息,通过 get_detection_results() 仍能取到全部检测结果再做过滤。

其他重要参数:

  • bbox_thr:边界框置信度阈值,默认 0.5,低于该分数的框不会送入姿态模型。
  • device:推理设备,默认 'cuda:0'。
  • 姿态追踪:节点内部维护 track_info(next_id、last_pose_preds、last_time),每帧通过 get_track_id 为关键点结果分配跨帧的跟踪 ID(tracking_thr=0.3、use_one_euro=True),因此画面中的同一目标会获得稳定 ID。

5.5 节点 4:ModelResultBindingNode —— 把推理结果绑定到当前帧

dict(
    type='ModelResultBindingNode',
    name='ResultBinder',
    frame_buffer='_frame_',  # `_frame_` 是 runner 保留缓冲区
    result_buffer='animal_pose',
    output_buffer='frame')

模型推理节点耗时较长,推理结果对应的帧与当前正在显示的帧往往不是同一帧。该节点负责把最新一次推理结果绑定到当前帧上(注释中明确说明"帧图像与推理结果可能是异步的")。在异步模式(synchronous=False)下,它会缓存最新的推理结果消息,一旦拿到新帧就把缓存结果合并进该帧再向下游传递;在同步模式下则直接输出结果来源的那一帧。

该节点还统计了 result_fps、result_lag (ms)、frame_fps、frame_lag (ms) 等指标,供 MonitorNode 显示(见 helper_node.py)。

5.6 节点 5:PoseVisualizerNode —— 可视化(快捷键 v)

dict(
    type='PoseVisualizerNode',
    name='Visualizer',
    enable_key='v',
    frame_buffer='frame',
    output_buffer='vis')

从 frame_effect_node.py 的实现看,该节点继承自 FrameDrawingNode,通过 draw() 方法在画面上绘制:

  • 检测边界框(通过 imshow_bboxes),默认按类别着色:person 为 (148, 139, 255)、cat/dog 为 (255, 255, 0);
  • 关键点与骨架连线(通过 imshow_keypoints),骨架、关键点配色由各模型配置的 dataset_info 决定(节点通过 DatasetInfo(model_cfg.dataset_info) 解析)。

可调参数包括 kpt_thr(关键点分数阈值,默认 0.3)、radius(关键点半径,默认 4)、thickness(骨架线宽,默认 2)以及 bbox_color(可传入颜色字典按类别着色)。enable_key='v' 使该节点支持用 v 键实时开关可视化。

5.7 节点 6:NoticeBoardNode —— 帮助面板(快捷键 h)

dict(
    type='NoticeBoardNode',
    name='Helper',
    enable_key='h',
    enable=True,
    frame_buffer='vis',
    output_buffer='vis_notice',
    content_lines=[...])

该节点把一段文本(如帮助信息)以半透明公告板的形式叠加在画面左上角,默认 enable=True(运行即显示)。content_lines 逐行定义显示内容;Demo 中它同时列出了 "v"、"s"、"b"、"h"、"m"、"q" 等按键的功能说明(其中 "s"、"b" 对应眼镜与凸眼特效,可自行在配置中追加对应特效节点启用)。可通过 x_offset、y_offset、y_delta、text_color、background_color、text_scale 微调面板外观。

5.8 节点 7:MonitorNode —— 诊断面板(快捷键 m)

dict(
    type='MonitorNode',
    name='Monitor',
    enable_key='m',
    enable=False,
    frame_buffer='vis_notice',
    output_buffer='display')

用于调试与监控:在画面上叠加每个节点途经信息的半透明面板,包括各节点 FPS、时间戳、模型结果 FPS/延迟,以及(在安装了 psutil 时)进程的 CPU(%) 与 Memory(%)。默认 enable=False,即默认不显示,按 m 键唤起。

5.9 节点 8:RecorderNode —— 视频录制

dict(
    type='RecorderNode',
    name='Recorder',
    out_video_file='record.mp4',
    frame_buffer='display',
    output_buffer='_display_'  # `_display_` 是 runner 保留缓冲区
)

把最终画面实时写入本地视频文件。从 helper_node.py 的实现看,RecorderNode 内部维护一个容量 30 的写入队列,并另起一个独立线程通过 cv2.VideoWriter 写盘(编码格式 mp4v,out_video_fps 默认 30),避免阻塞主数据流。这也印证了 README 中"Demo 会自动把输出视频保存为 record.mp4"的说明——文件名可通过 out_video_file 随意修改。

5.10 整条流水线小结

将上述节点按 buffer 名字串联,数据流为:

摄像头帧
  ├─ _input_ → Detector → det_result → Human Pose Estimator → human_pose → Animal Pose Estimator → animal_pose
  └─ _frame_ ──────────────────────────────────────────────────────────→ ResultBinder(绑定最新推理结果)
      → frame → Visualizer(v) → vis → Helper(h) → vis_notice → Monitor(m) → display → Recorder → _display_ → 窗口显示

检测与姿态估计走 _input_ 链路(耗时、异步),绘制与显示走 _frame_ 链路(实时、流畅),两条链路在 ModelResultBindingNode 汇合,最终经 RecorderNode 输出到保留缓冲区 _display_,由 runner 读取并在窗口中显示。

六、自定义配置实战

6.1 更换检测模型

用户可以从 MMDetection 的模型库中挑选任意检测模型,只需修改 DetectorNode 的两个参数,权重会被自动下载并加载:

dict(
    type='DetectorNode',
    name='Detector',
    model_config='demo/mmdetection_cfg/'
    'ssdlite_mobilenetv2_scratch_600e_coco.py',
    model_checkpoint='https://download.openmmlab.com'
    '/mmdetection/v2.0/ssd/'
    'ssdlite_mobilenetv2_scratch_600e_coco/ssdlite_mobilenetv2_'
    'scratch_600e_coco_20210629_110627-974d9307.pth',
    input_buffer='_input_',
    output_buffer='det_result')

本仓库 demo/mmdetection_cfg 目录下还提供了 faster_rcnn_r50_fpn_1class.py、faster_rcnn_r50_fpn_coco.py、cascade_rcnn_x101_64x4d_fpn_1class.py、mask_rcnn_r50_fpn_2x_coco.py、yolov3_d53_320_273e_coco.py 等可选的检测配置,可直接引用。

6.2 更换或追加姿态模型

姿态模型同样通过 model_config + model_checkpoint 指定。若希望在同一画面中对不同类型的目标使用不同的姿态模型,只需在 nodes 列表中追加多个 TopDownPoseEstimatorNode,并分别设置 cls_names/cls_ids 即可,这正是 Demo 同时处理"人"和"猫狗马牛羊"的实现方式。本仓库 configs 下按数据集分门别类存放了大量 top-down 姿态模型配置(如人体 configs/body/2d_kpt_sview_rgb_img/topdown_heatmap、动物 configs/animal/2d_kpt_sview_rgb_img/topdown_heatmap、全身 configs/wholebody/2d_kpt_sview_rgb_img/topdown_heatmap 等),可按需选取。

6.3 无 GPU 环境下运行(纯 CPU 推理)

如果设备没有 GPU 与 CUDA,只需把所有模型节点的 device 都设置为 'cpu',Demo 即可纯 CPU 运行。例如检测节点:

dict(
    type='DetectorNode',
    name='Detector',
    model_config='demo/mmdetection_cfg/'
    'ssdlite_mobilenetv2_scratch_600e_coco.py',
    model_checkpoint='https://download.openmmlab.com'
    '/mmdetection/v2.0/ssd/'
    'ssdlite_mobilenetv2_scratch_600e_coco/ssdlite_mobilenetv2_'
    'scratch_600e_coco_20210629_110627-974d9307.pth',
    device='cpu',
    input_buffer='_input_',
    output_buffer='det_result')

注意:两个 TopDownPoseEstimatorNode 的 device 也要一并改为 'cpu'。CPU 模式下建议选择轻量模型(如示例中的 SSDLite-MobileNetV2 与 ViPNAS-MobileNetV3),以保证实时性。

6.4 调试摄像头与显示

如果摄像头取流或画面显示异常,可以用仓库自带的调试配置启动,只保留监控与录制两个节点,快速验证摄像头是否可用:

python tools/webcam/run_webcam.py --config tools/webcam/configs/examples/test_camera.py

test_camera.py 的配置非常简单:MonitorNode 直接读取保留缓冲区 _frame_ 叠加诊断信息,RecorderNode 把画面录制为 webcam_output.mp4。若运行该配置能正常看到画面,说明摄像头与显示链路没有问题,问题大概率出在模型推理环节。

6.5 其他常用调参项

根据 example_cn.md 的总结,以下参数也常用于自定义应用:

  • 切换输入源:camera_id 除了摄像头 ID,还可以设为本地视频文件路径,把应用从"实时摄像头"变成"视频文件回放"。
  • 快捷键开关:任何支持 enable_key 的节点都可以通过 enable_key 设定快捷键、enable 设定启动时的默认开/关状态(如本 Demo 中 MonitorNode 默认关闭、NoticeBoardNode 默认开启)。
  • 提示信息:通过 NoticeBoardNode 的 content_lines 自定义画面上的操作指引。
  • 覆盖运行参数:也可不修改配置文件,直接用 --cfg-options 临时覆盖,例如 --cfg-options runner.camera_id=1 runner.synchronous=True。

七、从源码理解底层运行机制

7.1 Runner:三线程协作

WebcamRunner.run() 启动后,程序由三部分协作:

  1. _read_camera 线程:循环读取视频帧,同时放入 _frame_(显示用)与 _input_(推理用)两个缓冲区;读到视频末尾时向 _frame_ 放入 VideoEndingMessage 广播结束信号。
  2. 各 Node 线程:每个节点都是一个 threading.Thread(继承自 Node),在各自线程中异步循环处理数据。
  3. 主线程 _display:从 _display_ 缓冲区取最终画面,cv2.imshow 显示窗口,并用 cv2.waitKey(1) 捕获键盘输入。

7.2 Node 的运行循环

Node.run() 定义了每个节点的通用运行逻辑:

  1. 检查 _exit_ 事件,若已设置则调用 on_exit() 退出;
  2. 检查输入缓冲区是否就绪(essential 输入未就绪则短暂休眠等待);
  3. 若收到 VideoEndingMessage,直接向下游广播并结束;
  4. 根据 _enabled 状态调用 process()(启用)或 bypass()(禁用),并将输出写入注册的输出缓冲区。

对支持快捷键开关的节点,enable_key 会注册一个键盘事件处理器 _toggle_enable,按键即翻转 _enabled 状态,配合 bypass() 实现"关闭时原样透传画面"的默认行为。

7.3 节点间通信的数据结构:FrameMessage

节点间传递的数据载体是 FrameMessage,它封装一帧视频的所有信息,并提供下列接口:

  • get_image() / set_image():读取/设置帧图像;
  • add_detection_result() / get_detection_results():添加/读取目标检测结果;
  • add_pose_result() / get_pose_results():添加/读取姿态估计结果;
  • get_full_results() / set_full_results():整体获取/设置全部模型预测(供 ModelResultBindingNode 把推理结果从一个消息绑定到另一个消息)。

每条消息还带 route_info(途经节点记录)与 timestamp,这正是 MonitorNode 能逐节点展示 FPS 与延迟的依据。

八、常见问题与注意事项

  1. 提示"Please install mmdet to run the demo.":DetectorNode 强制要求安装 MMDetection(>= 2.21.0),请先完成 MMDetection 安装。
  2. record.mp4 从哪来:RecorderNode 会把最终画面实时写入 out_video_file 指定的文件(默认 record.mp4),路径相对当前工作目录,退出程序后即可查看。
  3. 画面卡顿但检测正常:模型推理耗时节点走 _input_ 链路、绘制走 _frame_ 链路,两者异步,通常显示仍流畅;若仍卡顿可尝试降低 camera_fps,或改用更轻量的模型、切到 CPU/更低分辨率。
  4. 多类别姿态模型共存:多个 TopDownPoseEstimatorNode 串联时,后置节点通过 get_detection_results() 读取全部检测结果,再依据各自的 cls_names/cls_ids 过滤,互不冲突。
  5. 想进一步扩展:参考 example_cn.md 可以学习如何继承 FrameDrawingNode 编写自定义特效节点(如给猫戴太阳镜),并通过 @NODES.register_module() 注册后在配置中直接以 type='SunglassesNode' 形式引用。

九、总结

Pose Estimation Demo 是理解 MMPose Webcam API 的最佳入口:它用一份不足百行的配置,串起"目标检测 → 多模型姿态估计 → 结果绑定 → 可视化 → 帮助/监控面板 → 视频录制"的完整实时交互链路,且无需编写任何业务代码即可运行。透过配置文件与 webcam_apis 源码,你可以掌握 Runner/Node 模型、Buffer 数据流、键盘事件、异步推理绑定等核心概念,并以此为基础自由组合模型、特效与交互逻辑,搭建属于自己的 Webcam 应用。

登录后查看全文
ViTPose