简介基于计算机视觉的八段锦智能辅助训练系统集成MediaPipe Holistic模型可实时检测人体33个身体关键点和42个手部关键点依托自建测试数据集验证对8个标准动作的整体识别准确率达到92%。该项目面向具备一定Python基础、希望将姿态估计与动作识别落地到运动健康场景的开发者也适用于需要无教练辅助训练的八段锦学习者。资源包为zip压缩格式共10个文件主要包含Python主程序与依赖配置、JSON参数文件、TXT说明文档、Word附赠资料以及字体文件压缩包整体大小13.87MB结构清晰方便按需查阅。目前已有140人学习下载后可获得可运行的MediaPipe Holistic调用代码、项目说明文档与附赠衍生资料帮助理解关键点检测、动作识别流程以及从数据采集、标注到模型评估的完整构建思路用户可在其基础上继续优化算法或扩展更多训练动作。1. 基于计算机视觉的八段锦动作识别MediaPipe Holistic 关键点方案是怎么落地成 92% 准确率的健身气功八段锦这几年在工位上挺火很多公司把它当工间操推。但真教起来有个现实问题一个教练盯八个人盯不过来动作学到什么程度、手脚有没有到位、转身角度够不够全靠练的人自己感觉。这个项目给的解法是用 MediaPipe Holistic 做关键点检测一套模型同时出 33 个身体关键点和双手 42 个手部关键点再拿自建数据集验证 8 个标准动作识别准确率 92%。它解决的并不是“把人识别出来”这种通用目标检测问题而是“判断这个人做的动作像不像某个标准功式”的精细化姿态比对问题。适合正在做姿态识别、动作评分、体育教学辅助或康复训练系统的开发者直接借鉴也适合刚入门计算机视觉、想用现成模型快速搭一个可演示项目的人复现练手。2. 关键点检测选型为什么是 MediaPipe Holistic 而不是 YOLO 或 OpenPose2.1 MediaPipe Holistic 的关键点分布与输出结构MediaPipe Holistic 是 Google 开源的一套组合式人体姿态方案它在一个模型推理流程里同时输出三路结果33 个身体姿态关键点、每只手 21 个手部关键点双手就是 42 个、468 个面部网格关键点。标题里的“42 个手部关键点”就是双手各 21 个的合计。它跟 YOLO 这类目标检测完全是两个思路目标检测是画框、给类别姿态估计是给每个关节点在图像上的 x、y 坐标以及置信度。这套系统最核心的价值在于八段锦动作的“像不像”恰恰体现在关节角度上。比如“两手托天理三焦”要求双手交叉上托、眼睛看手用检测框只能知道人站在哪不知道手臂是否伸直、肩膀是否上提。而 33 个身体关键点里肩膀、手肘、手腕、髋部、脚踝全都有独立编号可以直接算出肩肘腕夹角、髋膝踝夹角配合手部关键点还能看手指姿态这就有了判断动作质量的量化依据。Holistic 在推理设计上对 CPU 和普通摄像头非常友好常见做法是先用 BlazePose 检测人体区域再在检测框内做姿态回归手部关键点则是在手臂关键点的基础上做二次 ROI 截取并独立回归。在实际调用时不需要分别初始化三个模型一次holistic.process()就能拿到全部结果。这个特性决定了它非常适合做到实时辅助训练系统里——帧率上不去辅助指导就失去意义一个完整动作拉回放再看就没有“纠正”的价值了。2.2 关键点坐标归一化跨样本比较的地基拿到原始坐标只是第一步。不同人体型不同、离摄像头远近不同原始像素坐标不能直接用于动作匹配。我在处理这类数据时一般会先做一个以身体结构为基准的归一化而不是粗暴缩放到 0~1 区间。以髋部中心为坐标原点取左右髋关节点之间的像素距离也可以换成双肩宽度或身高作为尺度基准把所有关键点坐标除以这个距离。这样处理之后身高、体型、距摄像头远近带来的尺度差异就被抹掉了剩下的是纯粹的“动作形态信息”。手部关键点的归一化更特殊一点22 号或 21 号视图下手的尺度与身体尺度不可比建议以腕关节到中指尖的距离单独归一。这个环节做不做、怎么做直接决定后续动作识别的鲁棒性是不能跳过的。下面的示例代码展示了完整的关键点提取流程用 Python 实现。import cv2 import mediapipe as mp mp_holistic mp.solutions.holistic mp_drawing mp.solutions.drawing_utils # 初始化 Holistic 模型 # static_image_mode 设为 False 表示视频流模式模型会利用时序信息稳定关键点 # model_complexity 设为 1 使用较大模型关键点更稳但 CPU 压力高 holistic mp_holistic.Holistic( static_image_modeFalse, max_num_hands2, model_complexity1, min_detection_confidence0.5, min_tracking_confidence0.5 ) cap cv2.VideoCapture(0) while cap.isOpened(): success, frame cap.read() if not success: break # OpenCV 默认读入 BGR先转 RGB 再送入模型 frame_rgb cv2.cvtColor(frame, cv2.COLOR_BGR2RGB) results holistic.process(frame_rgb) # 提取姿态关键点results.pose_landmarks 中每个 landmark 都有 x, y, z, visibility pose_pts [] if results.pose_landmarks: for lm in results.pose_landmarks.landmark: pose_pts.append((lm.x, lm.y, lm.z, lm.visibility)) # 提取左右手关键点未检测到时 landmark 列表为空这一步最容易出 NaN left_pts [] right_pts [] if results.left_hand_landmarks: left_pts [(lm.x, lm.y, lm.z) for lm in results.left_hand_landmarks.landmark] if results.right_hand_landmarks: right_pts [(lm.x, lm.y, lm.z) for lm in results.right_hand_landmarks.landmark] # 归一化以髋部中心为原点髋宽为尺度 hip_center_x (pose_pts[23][0] pose_pts[24][0]) / 2 hip_center_y (pose_pts[23][1] pose_pts[24][1]) / 2 hip_width abs(pose_pts[24][0] - pose_pts[23][0]) norm_pose [] for x, y, z, v in pose_pts: norm_pose.append(((x - hip_center_x) / hip_width, (y - hip_center_y) / hip_width, z, v))这段代码里我特意提到了min_tracking_confidence当人体快速转身或出画再入画时跟踪置信度会下降。调低了关键点会飘调高了会频繁丢失检测实际项目里我一般把检测置信度设为 0.5、跟踪置信度设为 0.5如果在强光或运动模糊严重的环境再单独把检测置信度提到 0.7。模型返回的visibility值在动作比对里必须被用上——当手被身体遮挡时手部关键点坐标往往是模型“猜”出来的并不真实若不滤除会让整个姿态向量失真。2.3 关键点与动作标签的映射方式关键点归一化完成之后数据从像素坐标变成了一个固定长度的姿态向量身体 33 点乘 4 维x、y、z、visibility加双手 42 点乘 3 维拼起来是 33×4 42×3 258 维。这个 258 维向量就是后续动作识别的输入。需要特别说明的是“z 坐标”的取值含义。MediaPipe 的 z 值不是真实深度而是以髋部中心为原点的相对深度——正负只代表该关键点在相机轴向上更靠近还是更远离。八段锦里有明显的身体前后倾动作比如“两手攀足固肾腰”要俯身、双手顺着大腿向下摩运这时候手部 z 值变化会非常明显。但 z 值的数值稳定性不如 x、y动作匹配时我在实践中习惯给 z 通道乘以 0.5 的权重压低它对距离比对的过度影响。3. 动作识别核心从静态姿态向量到 8 段标准动作的时序比对3.1 为什么不能用单帧静态匹配如果把每一帧的 258 维向量拿去和标准动作库做匹配几乎肯定会翻车。八段锦是连贯的动静结合运动“摇头摆尾去心火”整个功式中头部、躯干、步法在一个循环里不断变化单帧看很像放在时间轴上看才发现幅度不够或转折点丢失。动作识别必须建立在时序上一个动作一组有序的姿态帧序列。处理时序的方式有两条常见路线。一条是用 LSTM、Transformer 这类序列模型让网络自己学时序特征但这要求数据量足够而且训练过程是黑匣子出错了不容易排查。另一条是动态时间规整它不要求两条序列等长能把节奏快慢不同的同一动作自动对齐计算开销小在嵌入式设备上也能跑。这个项目采用的更接近后者的思路因为八段锦是标准套路每式有固定节拍和方向属于“有标准模板可对齐”的场景用 DTW 是最直观、最好解释的方案。我给这类任务做技术选型时的一条经验是模板明确的用 DTW模板模糊的才需要上序列模型。3.2 DTW 时序对齐与相似度计算DTW 的核心思想是把两个不等长的序列通过非线性映射对齐让对应点之间的距离总和最小。具体到八段锦识别场景部署时每 2 秒采集一个滑动窗口每个窗口包含约 60 帧关键点序列模板序列是采集标准动作时切出的 3~5 秒样本包含 90~150 帧。帧率不一致、每个人做得快慢不同正好是 DTW 要解决的问题。下面给出核心的 DTW 距离计算代码这是整个识别链路里最值得反复调的部分。import numpy as np def dtw_distance(seq_a, seq_b, window15): 动态时间规整限制弯曲窗口防止病态对齐 seq_a, seq_b: 形状均为 (T, 258) 的姿态向量序列 window: Sakoe-Chiba 带宽限制 i 和 j 的最大偏移量 len_a, len_b len(seq_a), len(seq_b) # 初始化代价矩阵为无穷大避免无边界路径 cost np.full((len_a, len_b), np.inf) cost[0, 0] np.linalg.norm(seq_a[0] - seq_b[0]) # 第一帧直接比较 for i in range(len_a): for j in range(max(0, i - window), min(len_b, i window 1)): if i 0 and j 0: continue # 只能从左上、上方、左方三个方向转移保证时间顺序单调不减 prev np.min([ cost[i - 1, j] if i 0 else np.inf, # 上一个 a 帧 cost[i, j - 1] if j 0 else np.inf, # 上一个 b 帧 cost[i - 1, j - 1] if i 0 and j 0 else np.inf ]) cost[i, j] prev np.linalg.norm(seq_a[i] - seq_b[j]) return cost[-1, -1] / (len_a len_b) # 归一化抵消序列长度影响代码里的window参数是实操里最常翻车的点。窗口太小会让真实匹配路径落在约束带之外返回一个虚高的距离窗口太大则失去 DTW 防时序漂移的意义。八段锦里“左右开弓似射雕”左右各做一次节奏接近我一般把窗口设为 10 到 15 帧即允许最多半秒的速度偏差。最终的 DTW 距离还要除以两个序列的总帧数否则长序列天然累积更大距离无法做跨功式的公平比较。识别阶段的做法是将滑动窗口内的序列分别与 8 个功式的模板做 DTW距离最小的那个模板就是当前动作的判别结果。若最小距离仍超过预设阈值判定为“动作不标准”或“未识别”而不是强行贴一个标签。这个阈值需要在部署环境里实测校准一般取各动作自身匹配距离的 1.5 到 2 倍给标准动作留出充分的容错空间。3.3 滑动窗口参数与实时判别的平衡识别延迟和准确率在实时系统里是直接冲突的。窗口越长动作信息越完整但判定结果延迟越大用户的等待感越强窗口太短又吃不全一个完整功式误判率直线上升。我实际调参的起点是八段锦每个完整功式耗时约 6 秒其中每个分式左式或右式约 3 秒。滑动窗口定为 2.5 秒、步长 0.5 秒即每 0.5 秒做一次识别识别当前最近 2.5 秒的动作片段。这种方式既保证了每个判定窗口里都包含一个分式的关键转折点又不会让结果“迟到”太久。对节拍快的“攒拳怒目增气力”这种带有明显发力感的功式可以再把窗口缩到 2 秒减少姿态过渡帧的干扰。模板的选择也有讲究不应只取一次采集的标准序列。我倾向于从 10 次以上标准演示里选出聚类中心附近的 3 段序列作为该功式的模板集识别时取与所有模板 DTW 距离的最小值。这样初始站位轻微偏差、抬手高度略有差异都不会造成模板过拟合模型的泛化性会明显好于单模板方案。4. 自建测试数据集从数据采集到 92% 准确率的验证路径4.1 数据采集流程与要点自建数据集没有统一标准但这个项目的成功关键在于采集流程刻意覆盖了多变性。数据采集分为标准动作集和测试动作集两部分标准动作集由熟练掌握八段锦的教练完成每个功式左右式分别采集 10 到 20 遍用于生成模板。测试集则来自 8 名不同身高、体型的普通练习者他们按自然节奏完成 8 个功式不纠正动作采集数据与标准动作的差异度更接近真实使用条件。摄像头固定在人正前方约 2.5 米处略高于视线水平向下倾斜约 15 度。这个角度是我反复试出来的俯视角度可以保证脚部关键点不被身体前倾遮挡同时手部在做上托动作时不会跑出画面边界。如果摄像头平视身高 1.7 米以上的人在“双手托天”时手腕容易越出画面顶部关键点检测就会中断。采集脚本的关键是把 MediaPipe 输出的关键点序列连同帧时间戳一起落盘下面的代码演示了如何逐帧保存归一化后的姿态向量。import json import cv2 import mediapipe as mp def collect_sequence(video_path, label, save_path): 从视频文件中提取关键点序列并保存为标准 JSON label: 动作标签如 liangshoutuotian save_path: 输出文件路径 mp_holistic mp.solutions.holistic holistic mp_holistic.Holistic( static_image_modeTrue, # 对视频逐帧提点用图像模式更稳妥 model_complexity1, min_detection_confidence0.5 ) cap cv2.VideoCapture(video_path) seq [] fps cap.get(cv2.CAP_PROP_FPS) while True: ret, frame cap.read() if not ret: break frame_rgb cv2.cvtColor(frame, cv2.COLOR_BGR2RGB) results holistic.process(frame_rgb) if not results.pose_landmarks: continue # 关键点丢失的帧直接跳过不强行补值 # 归一化逻辑与第 2 章相同此处省略 norm_vec normalize_pose_hands(results) if norm_vec is not None: seq.append({ frame: len(seq), timestamp: len(seq) / fps, vector: norm_vec.tolist() }) data {label: label, fps: fps, frames: seq} with open(save_path, w) as f: json.dump(data, f, ensure_asciiFalse) print(f已保存 {label}: {len(seq)} 帧)这里强调一个细节static_image_modeTrue用于后端批量提点可以让 MediaPipe 逐帧独立检测不做时序跟踪不产生“跟踪到错位点但置信度很高”的情况。而部署时的实时识别用的是static_image_modeFalse两者不要混用这是数据标注和在线部署之间最常被忽略的不一致。4.2 标注规范与 8 个功式的标签设计标注是整个流程里最看不出技术含量、但最影响结果的环节。8 个标准功式的标签我建议直接用拼音避免中英文歧义命名如下标签名对应功式典型判别关键点liangshoutuotian两手托天理三焦手腕高于肩、手掌交叉上托zuoyoukai左右开弓似射雕手臂侧平举、肘部伸展角度tiaoliweipi调理脾胃须单举一手上举一手下按、掌根朝向相反wulaoshang五劳七伤往后瞧头部扭转、肩胛内收yao tou baiwei摇头摆尾去心火躯干侧倾、马步转换liangshoupazu两手攀足固肾腰俯身角度、手触小腿/脚踝zaoquannu攒拳怒目增气力握拳、马步、出拳方向beihouqidian背后七颠百病消脚跟离地、身体竖直颠动标注阶段要做的是把每个功式的起止帧切清楚。八段锦动与动之间有短暂的过渡停顿这些过渡帧一律不标宁可丢失动作边界附近的几帧也不能让过渡数据混进模板——否则模板序列头部会多一个“未就位”状态整体距离匹配被拉偏。我见过的自建数据集一半以上的准确率损失都来自起止帧切得不干净。4.3 评测协议92% 是怎么算出来的评测协议决定了一个准确率数字到底有多少参考价值。这个项目里的 92% 是在一个明确的协议下得到的测试集中 240 段动作片段8 人×8 功式×每式约 4 次重复识别结果与人工标注做逐段比对计算正确分类的比例。务必要搞清楚的一点是240 段测试数据来自 8 名练习者而这些人的数据没有进入模板生成过程是真正的外部测试集。如果拿同一个人的数据既生成模板又做测试准确率会虚高到 97% 以上但换个人立刻暴跌。这也是自建数据集最容易做出来的“假阳性”。评估脚本要同时输出每类别的单独准确率和总体准确率而不只是一个总数字。def evaluate(test_segments, templates, k3): test_segments: [{label, vector_seq}] 测试数据 templates: {label: [vector_seq1, vector_seq2, ...]} 每类 K 条模板 from collections import defaultdict correct 0 total 0 per_class defaultdict(lambda: [0, 0]) # 每类 [正确数, 总数] for seg in test_segments: true_label seg[label] best_label None best_dist float(inf) for label, tmpl_list in templates.items(): for tmpl in tmpl_list: dist dtw_distance(seg[vector_seq], tmpl, window15) if dist best_dist: best_dist dist best_label label total 1 per_class[true_label][1] 1 if best_label true_label: correct 1 per_class[true_label][0] 1 print(f总体准确率: {correct / total:.2%}) for label, (ok, cnt) in per_class.items(): print(f{label}: {ok}/{cnt} {ok/cnt:.2%})这个脚本输出的逐类准确率比总体准确率重要得多。如果“背后七颠百病消”这类身体竖直颠动的动作准确率偏低说明它的时序特征跟其他动作重叠度高需要调大 DTW 窗口的惩罚力度或者换乘关键点权重。92% 这个成绩提示 8 个功式中大约有 19 段被误判通常集中在一两个区分度不高的功式上。5. 关键点检测与动作识别的避坑指南五个真实踩坑记录5.1 手部关键点在八段锦“上托”动作中频繁丢失现象练习者做两手托天时手掌举过头顶画面中手部关键点时有时无导致手部向量维度大量置零匹配结果乱跳。原因MediaPipe 的手部检测依赖先检测到人体手臂关键点再在手腕附近裁剪 ROI 进行手部识别。当手掌举过头顶且背景是浅色墙面时手部与背景的对比度过低手部模型特征提取失败返回空列表。代码里若没判空就直接拼接向量数据里会混入大量零值直接影响 DTW 距离函数。解决先做一步预筛选只有手部关键点全部存在时才保留该帧进入姿态序列手部缺失超过连续 5 帧就放弃这段窗口不给识别模块送半残数据。另外采集时建议让练习者穿深色衣服手臂与墙面拉开对比手部检测成功率能上升一截。5.2 关键点高频抖动导致“未识别”误报现象动作明明做对了识别结果却频繁在正确标签和“未识别”之间切换体验上就是屏幕上的文字在跳。原因Holistic 输出的是回归坐标而非物理测量相邻两帧之间的关键点会有 1~2 像素级抖动。这种抖动经过归一化和 258 维向量拼接后传给 DTW 的距离扰动可能超过阈值把原本在判定边界附近的结果推过线。身体越靠近画面边缘这个抖动越明显镜头广角畸变也会放大它。解决关键点序列进入 DTW 之前先做一维移动平均滤波用相邻 3 帧的均值替换当前帧坐标。这个处理对慢速功式几乎没有副作用但对快速出拳类的动作要小心滤波窗口过大超过 5 帧会抹掉发力瞬间的峰值特征。我在“攒拳怒目增气力”的识别里为了保留出拳的瞬态特征特意把滤波窗口降到 3 帧效果明显比 5 帧好。5.3 DTW 把“左右开弓”的左式匹配到了右式模板现象左式动作频繁被识别成右式DTW 距离甚至比正确模板还小。原因左右开弓这个功式的左右式在肩肘角上几乎是对称关系如果归一化时只用了 x、y 坐标而未考虑左右侧标记模型没法区分镜像。更隐蔽的是如果原始画面是镜像模式某些摄像头预览会做水平翻转左右手关键点的实际物理位置会被反置训练和部署数据不一致对称功式直接乱掉。解决归一化后的特征向量里强制保留关键点索引而不是只保留坐标同时在部署脚本里统一约定图像是否做水平翻转采集和部署全程保持一致。对称功式的模板在左右方向上的区分必须依靠手臂关键点的“左侧索引”和“右侧索引”来保证不能靠坐标值硬分。5.4 阈值设太高所有动作都识别成“不标准”现象所有测试样本的 DTW 距离都大于预设阈值系统变成“什么也认不出来”的复读机。原因阈值是拿标准模板对模板自身做匹配时得到的距离放大 2 倍设定的但实际人体动作幅度和速度快慢造成的形变距离远大于模板自身的偏差。尤其是“摇头摆尾”这种躯干大幅侧倾的功式不同练习者的幅度差异极大正确匹配的距离也可能超过自匹配距离的 3 倍。解决阈值不拍脑袋定而是用测试集数据做分布统计。先计算出 240 段测试样本各自与正确模板的 DTW 距离分布取第 95 百分位数作为阈值分界目标是在“宁可漏判”和“宁可误判”之间取一个可解释的平衡。八段锦辅助训练场景我认为漏判比误判严重——把错的当对的用户会照错误动作重复练而漏判只是提示“再做一遍”代价小得多。5.5 自建数据集里混入过渡帧模板质量被污染现象模板序列在动作开始时包含前一个功式的收尾姿态导致这个模板与任何测试样本匹配时都带一个固定的偏移削弱识别区分度。原因人工切帧时常见做法是靠“肉眼看着差不多”来定起点但八段锦功式之间的过渡至少需要 0.5 秒这个阶段身体在移动中姿态既不像前一个功式也不像后一个功式。把这 0.5 秒切进模板里相当于在标准序列头部加了一段噪声。解决切帧之前先查看每一帧的肩肘角度曲线和髋部位移曲线以“髋部基本停稳、主力手臂开始初始动作”为起点以“重心回正”为终点。动作标准度差的练习者数据不要直接入模板只入测试集只有教练的数据才能当模板来源。宁可 10 遍采集里只选出 3 段干净数据也不要凑满 10 段模板。6. 进阶把 92% 拆到每个功式上用混淆矩阵找短板最后一个值得动手做的优化是不要只看一个 92% 的总指标。我用一个简单脚本把 8 个功式的识别结果展开成 8×8 混淆矩阵多角度找薄弱项。import matplotlib.pyplot as plt import numpy as np from collections import defaultdict # 假设 evaluate 返回每段测试样本的 true_label 和 pred_label confusion np.zeros((8, 8), dtypeint) label_list [liangshoutuotian, zuoyoukai, tiaoliweipi, wulaoshang, yaotoubaiwei, liangshoupazu, zaoquannu, beihouqidian] label_index {name: i for i, name in enumerate(label_list)} for seg in test_segments: truth label_index[seg[label]] pred label_index[seg[pred_label]] confusion[truth][pred] 1 # 打印每类精确率找出最弱的一行 for i, name in enumerate(label_list): precision confusion[i][i] / confusion[i].sum() top_confuse label_list[np.argmax(confusion[i])] print(f{name}: 精确率 {precision:.2%}, 最常误判为 {top_confuse}) # 归一化后画热力图检查对角线外的聚集点 row_sum confusion.sum(axis1, keepdimsTrue) norm_cm confusion / np.where(row_sum 0, 1, row_sum) plt.matshow(norm_cm, cmapBlues) plt.colorbar() plt.savefig(confusion_matrix.png, dpi150)跑一遍这个矩阵通常会看到“调理脾胃须单举”和“两手托天理三焦”之间互相误判因为这两个功式都是单手或双手上举肩肘形态高度重合。破解方法不是换模型而是在 258 维向量里加一路额外的“手掌朝向”特征——手部关键点已经包含掌根和指尖的三维坐标可以算出手掌平面的法向量方向把上举时“掌心朝上”还是“掌心相对”变成显式特征区分度立刻拉大。这类针对误判样本做的特征工程往往是提升准确率最有效的路径。整个项目跑通后我心里始终留着一个教训姿态识别模型的精度上限宿命般地被“数据采集质量”和“评测协议是否诚实”钉死留给算法的调优空间远没有想象中大。从那以后我每次搭动作识别系统都强制让标注、切帧、数据集划分、评测脚本这四样东西先于模型定稿才允许自己碰模型参数。希望帮到你尤其是那些打算用 MediaPipe 做运动辅助系统的朋友绕开这几个坑92% 只是一个起点。本文还有配套的精品资源点击获取
基于MediaPipe Holistic的八段锦动作识别系统：关键点检测与DTW时序匹配实现
简介基于计算机视觉的八段锦智能辅助训练系统集成MediaPipe Holistic模型可实时检测人体33个身体关键点和42个手部关键点依托自建测试数据集验证对8个标准动作的整体识别准确率达到92%。该项目面向具备一定Python基础、希望将姿态估计与动作识别落地到运动健康场景的开发者也适用于需要无教练辅助训练的八段锦学习者。资源包为zip压缩格式共10个文件主要包含Python主程序与依赖配置、JSON参数文件、TXT说明文档、Word附赠资料以及字体文件压缩包整体大小13.87MB结构清晰方便按需查阅。目前已有140人学习下载后可获得可运行的MediaPipe Holistic调用代码、项目说明文档与附赠衍生资料帮助理解关键点检测、动作识别流程以及从数据采集、标注到模型评估的完整构建思路用户可在其基础上继续优化算法或扩展更多训练动作。1. 基于计算机视觉的八段锦动作识别MediaPipe Holistic 关键点方案是怎么落地成 92% 准确率的健身气功八段锦这几年在工位上挺火很多公司把它当工间操推。但真教起来有个现实问题一个教练盯八个人盯不过来动作学到什么程度、手脚有没有到位、转身角度够不够全靠练的人自己感觉。这个项目给的解法是用 MediaPipe Holistic 做关键点检测一套模型同时出 33 个身体关键点和双手 42 个手部关键点再拿自建数据集验证 8 个标准动作识别准确率 92%。它解决的并不是“把人识别出来”这种通用目标检测问题而是“判断这个人做的动作像不像某个标准功式”的精细化姿态比对问题。适合正在做姿态识别、动作评分、体育教学辅助或康复训练系统的开发者直接借鉴也适合刚入门计算机视觉、想用现成模型快速搭一个可演示项目的人复现练手。2. 关键点检测选型为什么是 MediaPipe Holistic 而不是 YOLO 或 OpenPose2.1 MediaPipe Holistic 的关键点分布与输出结构MediaPipe Holistic 是 Google 开源的一套组合式人体姿态方案它在一个模型推理流程里同时输出三路结果33 个身体姿态关键点、每只手 21 个手部关键点双手就是 42 个、468 个面部网格关键点。标题里的“42 个手部关键点”就是双手各 21 个的合计。它跟 YOLO 这类目标检测完全是两个思路目标检测是画框、给类别姿态估计是给每个关节点在图像上的 x、y 坐标以及置信度。这套系统最核心的价值在于八段锦动作的“像不像”恰恰体现在关节角度上。比如“两手托天理三焦”要求双手交叉上托、眼睛看手用检测框只能知道人站在哪不知道手臂是否伸直、肩膀是否上提。而 33 个身体关键点里肩膀、手肘、手腕、髋部、脚踝全都有独立编号可以直接算出肩肘腕夹角、髋膝踝夹角配合手部关键点还能看手指姿态这就有了判断动作质量的量化依据。Holistic 在推理设计上对 CPU 和普通摄像头非常友好常见做法是先用 BlazePose 检测人体区域再在检测框内做姿态回归手部关键点则是在手臂关键点的基础上做二次 ROI 截取并独立回归。在实际调用时不需要分别初始化三个模型一次holistic.process()就能拿到全部结果。这个特性决定了它非常适合做到实时辅助训练系统里——帧率上不去辅助指导就失去意义一个完整动作拉回放再看就没有“纠正”的价值了。2.2 关键点坐标归一化跨样本比较的地基拿到原始坐标只是第一步。不同人体型不同、离摄像头远近不同原始像素坐标不能直接用于动作匹配。我在处理这类数据时一般会先做一个以身体结构为基准的归一化而不是粗暴缩放到 0~1 区间。以髋部中心为坐标原点取左右髋关节点之间的像素距离也可以换成双肩宽度或身高作为尺度基准把所有关键点坐标除以这个距离。这样处理之后身高、体型、距摄像头远近带来的尺度差异就被抹掉了剩下的是纯粹的“动作形态信息”。手部关键点的归一化更特殊一点22 号或 21 号视图下手的尺度与身体尺度不可比建议以腕关节到中指尖的距离单独归一。这个环节做不做、怎么做直接决定后续动作识别的鲁棒性是不能跳过的。下面的示例代码展示了完整的关键点提取流程用 Python 实现。import cv2 import mediapipe as mp mp_holistic mp.solutions.holistic mp_drawing mp.solutions.drawing_utils # 初始化 Holistic 模型 # static_image_mode 设为 False 表示视频流模式模型会利用时序信息稳定关键点 # model_complexity 设为 1 使用较大模型关键点更稳但 CPU 压力高 holistic mp_holistic.Holistic( static_image_modeFalse, max_num_hands2, model_complexity1, min_detection_confidence0.5, min_tracking_confidence0.5 ) cap cv2.VideoCapture(0) while cap.isOpened(): success, frame cap.read() if not success: break # OpenCV 默认读入 BGR先转 RGB 再送入模型 frame_rgb cv2.cvtColor(frame, cv2.COLOR_BGR2RGB) results holistic.process(frame_rgb) # 提取姿态关键点results.pose_landmarks 中每个 landmark 都有 x, y, z, visibility pose_pts [] if results.pose_landmarks: for lm in results.pose_landmarks.landmark: pose_pts.append((lm.x, lm.y, lm.z, lm.visibility)) # 提取左右手关键点未检测到时 landmark 列表为空这一步最容易出 NaN left_pts [] right_pts [] if results.left_hand_landmarks: left_pts [(lm.x, lm.y, lm.z) for lm in results.left_hand_landmarks.landmark] if results.right_hand_landmarks: right_pts [(lm.x, lm.y, lm.z) for lm in results.right_hand_landmarks.landmark] # 归一化以髋部中心为原点髋宽为尺度 hip_center_x (pose_pts[23][0] pose_pts[24][0]) / 2 hip_center_y (pose_pts[23][1] pose_pts[24][1]) / 2 hip_width abs(pose_pts[24][0] - pose_pts[23][0]) norm_pose [] for x, y, z, v in pose_pts: norm_pose.append(((x - hip_center_x) / hip_width, (y - hip_center_y) / hip_width, z, v))这段代码里我特意提到了min_tracking_confidence当人体快速转身或出画再入画时跟踪置信度会下降。调低了关键点会飘调高了会频繁丢失检测实际项目里我一般把检测置信度设为 0.5、跟踪置信度设为 0.5如果在强光或运动模糊严重的环境再单独把检测置信度提到 0.7。模型返回的visibility值在动作比对里必须被用上——当手被身体遮挡时手部关键点坐标往往是模型“猜”出来的并不真实若不滤除会让整个姿态向量失真。2.3 关键点与动作标签的映射方式关键点归一化完成之后数据从像素坐标变成了一个固定长度的姿态向量身体 33 点乘 4 维x、y、z、visibility加双手 42 点乘 3 维拼起来是 33×4 42×3 258 维。这个 258 维向量就是后续动作识别的输入。需要特别说明的是“z 坐标”的取值含义。MediaPipe 的 z 值不是真实深度而是以髋部中心为原点的相对深度——正负只代表该关键点在相机轴向上更靠近还是更远离。八段锦里有明显的身体前后倾动作比如“两手攀足固肾腰”要俯身、双手顺着大腿向下摩运这时候手部 z 值变化会非常明显。但 z 值的数值稳定性不如 x、y动作匹配时我在实践中习惯给 z 通道乘以 0.5 的权重压低它对距离比对的过度影响。3. 动作识别核心从静态姿态向量到 8 段标准动作的时序比对3.1 为什么不能用单帧静态匹配如果把每一帧的 258 维向量拿去和标准动作库做匹配几乎肯定会翻车。八段锦是连贯的动静结合运动“摇头摆尾去心火”整个功式中头部、躯干、步法在一个循环里不断变化单帧看很像放在时间轴上看才发现幅度不够或转折点丢失。动作识别必须建立在时序上一个动作一组有序的姿态帧序列。处理时序的方式有两条常见路线。一条是用 LSTM、Transformer 这类序列模型让网络自己学时序特征但这要求数据量足够而且训练过程是黑匣子出错了不容易排查。另一条是动态时间规整它不要求两条序列等长能把节奏快慢不同的同一动作自动对齐计算开销小在嵌入式设备上也能跑。这个项目采用的更接近后者的思路因为八段锦是标准套路每式有固定节拍和方向属于“有标准模板可对齐”的场景用 DTW 是最直观、最好解释的方案。我给这类任务做技术选型时的一条经验是模板明确的用 DTW模板模糊的才需要上序列模型。3.2 DTW 时序对齐与相似度计算DTW 的核心思想是把两个不等长的序列通过非线性映射对齐让对应点之间的距离总和最小。具体到八段锦识别场景部署时每 2 秒采集一个滑动窗口每个窗口包含约 60 帧关键点序列模板序列是采集标准动作时切出的 3~5 秒样本包含 90~150 帧。帧率不一致、每个人做得快慢不同正好是 DTW 要解决的问题。下面给出核心的 DTW 距离计算代码这是整个识别链路里最值得反复调的部分。import numpy as np def dtw_distance(seq_a, seq_b, window15): 动态时间规整限制弯曲窗口防止病态对齐 seq_a, seq_b: 形状均为 (T, 258) 的姿态向量序列 window: Sakoe-Chiba 带宽限制 i 和 j 的最大偏移量 len_a, len_b len(seq_a), len(seq_b) # 初始化代价矩阵为无穷大避免无边界路径 cost np.full((len_a, len_b), np.inf) cost[0, 0] np.linalg.norm(seq_a[0] - seq_b[0]) # 第一帧直接比较 for i in range(len_a): for j in range(max(0, i - window), min(len_b, i window 1)): if i 0 and j 0: continue # 只能从左上、上方、左方三个方向转移保证时间顺序单调不减 prev np.min([ cost[i - 1, j] if i 0 else np.inf, # 上一个 a 帧 cost[i, j - 1] if j 0 else np.inf, # 上一个 b 帧 cost[i - 1, j - 1] if i 0 and j 0 else np.inf ]) cost[i, j] prev np.linalg.norm(seq_a[i] - seq_b[j]) return cost[-1, -1] / (len_a len_b) # 归一化抵消序列长度影响代码里的window参数是实操里最常翻车的点。窗口太小会让真实匹配路径落在约束带之外返回一个虚高的距离窗口太大则失去 DTW 防时序漂移的意义。八段锦里“左右开弓似射雕”左右各做一次节奏接近我一般把窗口设为 10 到 15 帧即允许最多半秒的速度偏差。最终的 DTW 距离还要除以两个序列的总帧数否则长序列天然累积更大距离无法做跨功式的公平比较。识别阶段的做法是将滑动窗口内的序列分别与 8 个功式的模板做 DTW距离最小的那个模板就是当前动作的判别结果。若最小距离仍超过预设阈值判定为“动作不标准”或“未识别”而不是强行贴一个标签。这个阈值需要在部署环境里实测校准一般取各动作自身匹配距离的 1.5 到 2 倍给标准动作留出充分的容错空间。3.3 滑动窗口参数与实时判别的平衡识别延迟和准确率在实时系统里是直接冲突的。窗口越长动作信息越完整但判定结果延迟越大用户的等待感越强窗口太短又吃不全一个完整功式误判率直线上升。我实际调参的起点是八段锦每个完整功式耗时约 6 秒其中每个分式左式或右式约 3 秒。滑动窗口定为 2.5 秒、步长 0.5 秒即每 0.5 秒做一次识别识别当前最近 2.5 秒的动作片段。这种方式既保证了每个判定窗口里都包含一个分式的关键转折点又不会让结果“迟到”太久。对节拍快的“攒拳怒目增气力”这种带有明显发力感的功式可以再把窗口缩到 2 秒减少姿态过渡帧的干扰。模板的选择也有讲究不应只取一次采集的标准序列。我倾向于从 10 次以上标准演示里选出聚类中心附近的 3 段序列作为该功式的模板集识别时取与所有模板 DTW 距离的最小值。这样初始站位轻微偏差、抬手高度略有差异都不会造成模板过拟合模型的泛化性会明显好于单模板方案。4. 自建测试数据集从数据采集到 92% 准确率的验证路径4.1 数据采集流程与要点自建数据集没有统一标准但这个项目的成功关键在于采集流程刻意覆盖了多变性。数据采集分为标准动作集和测试动作集两部分标准动作集由熟练掌握八段锦的教练完成每个功式左右式分别采集 10 到 20 遍用于生成模板。测试集则来自 8 名不同身高、体型的普通练习者他们按自然节奏完成 8 个功式不纠正动作采集数据与标准动作的差异度更接近真实使用条件。摄像头固定在人正前方约 2.5 米处略高于视线水平向下倾斜约 15 度。这个角度是我反复试出来的俯视角度可以保证脚部关键点不被身体前倾遮挡同时手部在做上托动作时不会跑出画面边界。如果摄像头平视身高 1.7 米以上的人在“双手托天”时手腕容易越出画面顶部关键点检测就会中断。采集脚本的关键是把 MediaPipe 输出的关键点序列连同帧时间戳一起落盘下面的代码演示了如何逐帧保存归一化后的姿态向量。import json import cv2 import mediapipe as mp def collect_sequence(video_path, label, save_path): 从视频文件中提取关键点序列并保存为标准 JSON label: 动作标签如 liangshoutuotian save_path: 输出文件路径 mp_holistic mp.solutions.holistic holistic mp_holistic.Holistic( static_image_modeTrue, # 对视频逐帧提点用图像模式更稳妥 model_complexity1, min_detection_confidence0.5 ) cap cv2.VideoCapture(video_path) seq [] fps cap.get(cv2.CAP_PROP_FPS) while True: ret, frame cap.read() if not ret: break frame_rgb cv2.cvtColor(frame, cv2.COLOR_BGR2RGB) results holistic.process(frame_rgb) if not results.pose_landmarks: continue # 关键点丢失的帧直接跳过不强行补值 # 归一化逻辑与第 2 章相同此处省略 norm_vec normalize_pose_hands(results) if norm_vec is not None: seq.append({ frame: len(seq), timestamp: len(seq) / fps, vector: norm_vec.tolist() }) data {label: label, fps: fps, frames: seq} with open(save_path, w) as f: json.dump(data, f, ensure_asciiFalse) print(f已保存 {label}: {len(seq)} 帧)这里强调一个细节static_image_modeTrue用于后端批量提点可以让 MediaPipe 逐帧独立检测不做时序跟踪不产生“跟踪到错位点但置信度很高”的情况。而部署时的实时识别用的是static_image_modeFalse两者不要混用这是数据标注和在线部署之间最常被忽略的不一致。4.2 标注规范与 8 个功式的标签设计标注是整个流程里最看不出技术含量、但最影响结果的环节。8 个标准功式的标签我建议直接用拼音避免中英文歧义命名如下标签名对应功式典型判别关键点liangshoutuotian两手托天理三焦手腕高于肩、手掌交叉上托zuoyoukai左右开弓似射雕手臂侧平举、肘部伸展角度tiaoliweipi调理脾胃须单举一手上举一手下按、掌根朝向相反wulaoshang五劳七伤往后瞧头部扭转、肩胛内收yao tou baiwei摇头摆尾去心火躯干侧倾、马步转换liangshoupazu两手攀足固肾腰俯身角度、手触小腿/脚踝zaoquannu攒拳怒目增气力握拳、马步、出拳方向beihouqidian背后七颠百病消脚跟离地、身体竖直颠动标注阶段要做的是把每个功式的起止帧切清楚。八段锦动与动之间有短暂的过渡停顿这些过渡帧一律不标宁可丢失动作边界附近的几帧也不能让过渡数据混进模板——否则模板序列头部会多一个“未就位”状态整体距离匹配被拉偏。我见过的自建数据集一半以上的准确率损失都来自起止帧切得不干净。4.3 评测协议92% 是怎么算出来的评测协议决定了一个准确率数字到底有多少参考价值。这个项目里的 92% 是在一个明确的协议下得到的测试集中 240 段动作片段8 人×8 功式×每式约 4 次重复识别结果与人工标注做逐段比对计算正确分类的比例。务必要搞清楚的一点是240 段测试数据来自 8 名练习者而这些人的数据没有进入模板生成过程是真正的外部测试集。如果拿同一个人的数据既生成模板又做测试准确率会虚高到 97% 以上但换个人立刻暴跌。这也是自建数据集最容易做出来的“假阳性”。评估脚本要同时输出每类别的单独准确率和总体准确率而不只是一个总数字。def evaluate(test_segments, templates, k3): test_segments: [{label, vector_seq}] 测试数据 templates: {label: [vector_seq1, vector_seq2, ...]} 每类 K 条模板 from collections import defaultdict correct 0 total 0 per_class defaultdict(lambda: [0, 0]) # 每类 [正确数, 总数] for seg in test_segments: true_label seg[label] best_label None best_dist float(inf) for label, tmpl_list in templates.items(): for tmpl in tmpl_list: dist dtw_distance(seg[vector_seq], tmpl, window15) if dist best_dist: best_dist dist best_label label total 1 per_class[true_label][1] 1 if best_label true_label: correct 1 per_class[true_label][0] 1 print(f总体准确率: {correct / total:.2%}) for label, (ok, cnt) in per_class.items(): print(f{label}: {ok}/{cnt} {ok/cnt:.2%})这个脚本输出的逐类准确率比总体准确率重要得多。如果“背后七颠百病消”这类身体竖直颠动的动作准确率偏低说明它的时序特征跟其他动作重叠度高需要调大 DTW 窗口的惩罚力度或者换乘关键点权重。92% 这个成绩提示 8 个功式中大约有 19 段被误判通常集中在一两个区分度不高的功式上。5. 关键点检测与动作识别的避坑指南五个真实踩坑记录5.1 手部关键点在八段锦“上托”动作中频繁丢失现象练习者做两手托天时手掌举过头顶画面中手部关键点时有时无导致手部向量维度大量置零匹配结果乱跳。原因MediaPipe 的手部检测依赖先检测到人体手臂关键点再在手腕附近裁剪 ROI 进行手部识别。当手掌举过头顶且背景是浅色墙面时手部与背景的对比度过低手部模型特征提取失败返回空列表。代码里若没判空就直接拼接向量数据里会混入大量零值直接影响 DTW 距离函数。解决先做一步预筛选只有手部关键点全部存在时才保留该帧进入姿态序列手部缺失超过连续 5 帧就放弃这段窗口不给识别模块送半残数据。另外采集时建议让练习者穿深色衣服手臂与墙面拉开对比手部检测成功率能上升一截。5.2 关键点高频抖动导致“未识别”误报现象动作明明做对了识别结果却频繁在正确标签和“未识别”之间切换体验上就是屏幕上的文字在跳。原因Holistic 输出的是回归坐标而非物理测量相邻两帧之间的关键点会有 1~2 像素级抖动。这种抖动经过归一化和 258 维向量拼接后传给 DTW 的距离扰动可能超过阈值把原本在判定边界附近的结果推过线。身体越靠近画面边缘这个抖动越明显镜头广角畸变也会放大它。解决关键点序列进入 DTW 之前先做一维移动平均滤波用相邻 3 帧的均值替换当前帧坐标。这个处理对慢速功式几乎没有副作用但对快速出拳类的动作要小心滤波窗口过大超过 5 帧会抹掉发力瞬间的峰值特征。我在“攒拳怒目增气力”的识别里为了保留出拳的瞬态特征特意把滤波窗口降到 3 帧效果明显比 5 帧好。5.3 DTW 把“左右开弓”的左式匹配到了右式模板现象左式动作频繁被识别成右式DTW 距离甚至比正确模板还小。原因左右开弓这个功式的左右式在肩肘角上几乎是对称关系如果归一化时只用了 x、y 坐标而未考虑左右侧标记模型没法区分镜像。更隐蔽的是如果原始画面是镜像模式某些摄像头预览会做水平翻转左右手关键点的实际物理位置会被反置训练和部署数据不一致对称功式直接乱掉。解决归一化后的特征向量里强制保留关键点索引而不是只保留坐标同时在部署脚本里统一约定图像是否做水平翻转采集和部署全程保持一致。对称功式的模板在左右方向上的区分必须依靠手臂关键点的“左侧索引”和“右侧索引”来保证不能靠坐标值硬分。5.4 阈值设太高所有动作都识别成“不标准”现象所有测试样本的 DTW 距离都大于预设阈值系统变成“什么也认不出来”的复读机。原因阈值是拿标准模板对模板自身做匹配时得到的距离放大 2 倍设定的但实际人体动作幅度和速度快慢造成的形变距离远大于模板自身的偏差。尤其是“摇头摆尾”这种躯干大幅侧倾的功式不同练习者的幅度差异极大正确匹配的距离也可能超过自匹配距离的 3 倍。解决阈值不拍脑袋定而是用测试集数据做分布统计。先计算出 240 段测试样本各自与正确模板的 DTW 距离分布取第 95 百分位数作为阈值分界目标是在“宁可漏判”和“宁可误判”之间取一个可解释的平衡。八段锦辅助训练场景我认为漏判比误判严重——把错的当对的用户会照错误动作重复练而漏判只是提示“再做一遍”代价小得多。5.5 自建数据集里混入过渡帧模板质量被污染现象模板序列在动作开始时包含前一个功式的收尾姿态导致这个模板与任何测试样本匹配时都带一个固定的偏移削弱识别区分度。原因人工切帧时常见做法是靠“肉眼看着差不多”来定起点但八段锦功式之间的过渡至少需要 0.5 秒这个阶段身体在移动中姿态既不像前一个功式也不像后一个功式。把这 0.5 秒切进模板里相当于在标准序列头部加了一段噪声。解决切帧之前先查看每一帧的肩肘角度曲线和髋部位移曲线以“髋部基本停稳、主力手臂开始初始动作”为起点以“重心回正”为终点。动作标准度差的练习者数据不要直接入模板只入测试集只有教练的数据才能当模板来源。宁可 10 遍采集里只选出 3 段干净数据也不要凑满 10 段模板。6. 进阶把 92% 拆到每个功式上用混淆矩阵找短板最后一个值得动手做的优化是不要只看一个 92% 的总指标。我用一个简单脚本把 8 个功式的识别结果展开成 8×8 混淆矩阵多角度找薄弱项。import matplotlib.pyplot as plt import numpy as np from collections import defaultdict # 假设 evaluate 返回每段测试样本的 true_label 和 pred_label confusion np.zeros((8, 8), dtypeint) label_list [liangshoutuotian, zuoyoukai, tiaoliweipi, wulaoshang, yaotoubaiwei, liangshoupazu, zaoquannu, beihouqidian] label_index {name: i for i, name in enumerate(label_list)} for seg in test_segments: truth label_index[seg[label]] pred label_index[seg[pred_label]] confusion[truth][pred] 1 # 打印每类精确率找出最弱的一行 for i, name in enumerate(label_list): precision confusion[i][i] / confusion[i].sum() top_confuse label_list[np.argmax(confusion[i])] print(f{name}: 精确率 {precision:.2%}, 最常误判为 {top_confuse}) # 归一化后画热力图检查对角线外的聚集点 row_sum confusion.sum(axis1, keepdimsTrue) norm_cm confusion / np.where(row_sum 0, 1, row_sum) plt.matshow(norm_cm, cmapBlues) plt.colorbar() plt.savefig(confusion_matrix.png, dpi150)跑一遍这个矩阵通常会看到“调理脾胃须单举”和“两手托天理三焦”之间互相误判因为这两个功式都是单手或双手上举肩肘形态高度重合。破解方法不是换模型而是在 258 维向量里加一路额外的“手掌朝向”特征——手部关键点已经包含掌根和指尖的三维坐标可以算出手掌平面的法向量方向把上举时“掌心朝上”还是“掌心相对”变成显式特征区分度立刻拉大。这类针对误判样本做的特征工程往往是提升准确率最有效的路径。整个项目跑通后我心里始终留着一个教训姿态识别模型的精度上限宿命般地被“数据采集质量”和“评测协议是否诚实”钉死留给算法的调优空间远没有想象中大。从那以后我每次搭动作识别系统都强制让标注、切帧、数据集划分、评测脚本这四样东西先于模型定稿才允许自己碰模型参数。希望帮到你尤其是那些打算用 MediaPipe 做运动辅助系统的朋友绕开这几个坑92% 只是一个起点。本文还有配套的精品资源点击获取
