当多模态 AI 遇上太极会发生什么近期 Lumos NIX 的太极招式展示刷了一波技术圈的好感背后并不是什么“玄学”而是一套成熟的视觉动作理解、姿态估计与时序动作生成链路。本文将以“太极招式展示”为业务场景拆解这套能力从视频输入到骨架提取、再到动作匹配与展示的完整实现思路。不管你是在做 AI 健身、体感游戏还是动作教学类应用这套方案都有很高的参考价值。1. 背景与核心概念1.1 Lumos NIX 是什么Lumos 可以理解为一个面向多模态交互的实验性项目而 NIX 是这个项目中负责动作理解与生成的核心模块。两者的组合在近期因为一段“太极招式展示”而受到关注输入一段太极视频系统能够识别出招式的关键帧、肢体动作轨迹并以骨架动画或语义描述的方式把招式重新“展示”出来。这种能力听起来很酷但拆开来看本质上是三个经典技术问题的串联视频中的人体姿态估计Human Pose Estimation。骨骼关键点在时间轴上的序列建模。动作语义与标准动作库的匹配或生成。1.2 太极招式展示的技术含义太极招式不是简单的肢体位移它包含抬手、转身、重心转移、节奏快慢等多个维度。要让系统“看懂”并“展示”太极招式至少需要做到以下几件事从视频帧中识别出人体关键点例如肩膀、手肘、手腕、髋关节、膝盖、脚踝等。把连续帧的关键点坐标组合成时序数据。对时序数据做归一化去除身高、镜头距离带来的尺度差异。与标准动作模板进行比较输出相似度或者生成可读的动作描述。所以所谓的“展示”既可以是以骨架动画形式的视觉化回放也可以是以 “第3式白鹤亮翅右手上举左手下按” 这样的语义描述输出。1.3 这类技术能用在哪里抛开太极这个具体场景这套技术方案的应用面很广运动健身 App 中的动作次数统计与姿势纠正。体感游戏中的玩家动作识别。舞蹈教学中的动作拆解与对比。康复训练中的肢体活动度评估。传统武术、八段锦、健身操等标准化动作教学。换句话说掌握了这套链路你就能在大部分“视频动作理解”场景中快速落地。2. 环境准备与版本说明本文示例使用 Python 作为主力语言。Python 在 AI 和计算机视觉领域生态最完整适合快速验证。2.1 基础环境依赖项说明操作系统Windows 10/11、Ubuntu 20.04 均可Python3.9 或 3.10OpenCV视频读取与图像处理MediaPipe人体姿态关键点检测NumPy关键点坐标数组处理PyTorch 或 TensorFlow时序动作分类可选版本需要根据你的项目实际情况调整本文示例以常见环境为例重点演示配置思路。在你的虚拟环境中可以执行以下命令安装基础依赖pip install opencv-python mediapipe numpy如果后续需要做动作分类再补充安装深度学习框架pip install torch torchvision2.2 项目目录结构为了方便管理建议按照下面的结构组织代码tai-chi-demo/ ├── main.py # 主流程负责读取视频、提取关键点、展示结果 ├── pose_utils.py # 姿态提取工具函数 ├── action_matcher.py # 动作匹配逻辑 ├── samples/ │ └── taichi_demo.mp4 # 示例太极视频 └── output/ └── skeleton_result.mp4 # 输出骨架展示视频3. 核心原理拆解在写代码之前需要先理解几个核心概念。3.1 人体姿态估计人体姿态估计的目标是从图像中定位人体的关键点。MediaPipe 提供了一套基于 BlazePose 的解决方案可以检测 33 个人体关键点包括面部、躯干、手臂和腿部。MediaPipe 的检测结果中每个关键点包含归一化的 x、y 坐标以及可见性 visibility。坐标值是基于图像宽度和高度的比例范围在 0 到 1 之间。这一设计让关键点坐标天然具备一定程度的尺度不变性但依然会受到人体在画面中位置的影响。3.2 坐标归一化由于每个人的身高、体型不同同样的动作在画面中呈现的关键点坐标差异可能很大。为了让动作对比更公平需要做归一化处理。常见做法是以髋部中心为原点将全部关键点平移到原点。以左肩到右肩的距离为基准对坐标做等比例缩放。这样处理后不同体型、不同位置的同一种动作关键点坐标就能对齐。3.3 时序建模单一帧的关键点只能反映瞬间姿态无法表达太极招式中的“动势”。因此需要把连续帧的关键点序列输入到时序模型中例如 LSTM、TCN 或 Transformer。对于简单场景也可以使用动态时间规整DTWDynamic Time Warping算法计算两个动作序列的相似度这种方式不需要训练模型适合原型验证。3.4 动作展示的两种形式骨架动画形式将关键点连接成骨骼线条绘制在画面上生成一段骨架视频。语义描述形式通过动作分类模型输出招式名称或者通过规则生成中文描述。本文的实战案例会同时演示骨架展示和基于距离匹配的招式识别。4. 完整实战案例下面我们以一个太极视频为例走通“读取视频 - 提取关键点 - 绘制骨架 - 动作匹配”的完整流程。4.1 提取人体关键点先实现一个工具模块封装 MediaPipe 的姿态检测逻辑。文件路径pose_utils.pyimport cv2 import mediapipe as mp import numpy as np class PoseExtractor: def __init__(self): self.mp_pose mp.solutions.pose self.pose self.mp_pose.Pose( static_image_modeFalse, model_complexity1, smooth_landmarksTrue, min_detection_confidence0.5, min_tracking_confidence0.5, ) def extract(self, frame): 从一帧图像中提取人体关键点。 返回 (landmarks, skeleton_image) landmarks: 33 个关键点的归一化坐标列表 skeleton_image: 绘制了骨架的 RGB 图像 rgb_frame cv2.cvtColor(frame, cv2.COLOR_BGR2RGB) results self.pose.process(rgb_frame) if not results.pose_landmarks: return None, frame landmarks [] for lm in results.pose_landmarks.landmark: landmarks.append([lm.x, lm.y, lm.visibility]) skeleton_frame frame.copy() self.mp_pose_draw mp.solutions.drawing_utils self.mp_pose_draw.draw_landmarks( skeleton_frame, results.pose_landmarks, self.mp_pose.POSE_CONNECTIONS, landmark_drawing_specself.mp_pose_draw.DrawingSpec( color(0, 255, 0), thickness2, circle_radius2 ), connection_drawing_specself.mp_pose_draw.DrawingSpec( color(0, 0, 255), thickness2 ), ) return np.array(landmarks), skeleton_frame def close(self): self.pose.close()这段代码的核心逻辑很简单将 OpenCV 读取的 BGR 图像转换为 RGB因为 MediaPipe 的输入要求是 RGB。pose.process()返回检测结果。遍历pose_landmarks.landmark收集所有关键点的归一化坐标。用draw_landmarks把骨架绘制到画面中。4.2 坐标归一化处理接下来实现坐标归一化函数把关键点对齐到统一坐标系。文件路径pose_utils.py追加内容def normalize_landmarks(landmarks): 以髋部中心为原点以肩宽为单位长度对关键点做归一化。 landmarks: shape (33, 3) 的数组 if landmarks is None or len(landmarks) 0: return None lm landmarks.copy() # 提取髋部中心左髋 index23右髋 index24 left_hip lm[23][:2] right_hip lm[24][:2] hip_center (left_hip right_hip) / 2.0 # 平移到原点 lm[:, 0] - hip_center[0] lm[:, 1] - hip_center[1] # 计算肩宽左肩 index11右肩 index12 left_shoulder lm[11][:2] right_shoulder lm[12][:2] shoulder_width np.linalg.norm(right_shoulder - left_shoulder) if shoulder_width 1e-6: return None # 等比例缩放 lm[:, 0] / shoulder_width lm[:, 1] / shoulder_width return lm归一化之后不同体型的人做同一个动作时关键点坐标会比较接近后续匹配的准确率会更高。4.3 动作匹配逻辑太极招式是时序动作这里用两种方式进行匹配演示单帧姿势匹配适合静态站桩姿势例如“起势”“十字手”。简单 DTW 序列匹配适合动态招式。为了控制篇幅先实现一个基于均值姿势模板的匹配逻辑。文件路径action_matcher.pyimport numpy as np class ActionMatcher: def __init__(self, templates): templates: dict, 格式为 { 起势: np.array([...]), # shape (33, 2) 归一化关键点均值 白鹤亮翅: np.array([...]), } self.templates templates staticmethod def euclidean_distance(pose_a, pose_b): diff pose_a - pose_b distance np.sqrt(np.sum(diff ** 2)) return distance def match(self, normalized_landmarks): 输入归一化关键点返回最匹配的招式名称和距离。 if normalized_landmarks is None: return unknown, 9999.0 # 只取前 33 个关键点的 x, y 坐标忽略 visibility current_pose normalized_landmarks[:, :2] best_name unknown best_distance 9999.0 for name, template in self.templates.items(): distance self.euclidean_distance(current_pose, template) if distance best_distance: best_distance distance best_name name return best_name, best_distance由于标准模板需要从真实太极视频中提取这里提供一个“从样本视频生成模板”的工具方法方便你在自己的数据集上构建模板库。def build_template_from_video(video_path, pose_extractor, frame_indicesNone): 从视频中提取多帧关键点计算平均姿势作为模板。 frame_indices: 指定取哪些帧默认取全部帧的平均值 cap cv2.VideoCapture(video_path) landmarks_list [] if frame_indices is None: frame_indices [] index 0 while True: ret, frame cap.read() if not ret: break if not frame_indices or index in frame_indices: landmarks, _ pose_extractor.extract(frame) if landmarks is not None: normalized normalize_landmarks(landmarks) if normalized is not None: landmarks_list.append(normalized[:, :2]) index 1 cap.release() if not landmarks_list: return None return np.mean(landmarks_list, axis0)注意这里为了演示省略cv2的 import完整代码中需要补上。4.4 主流程读取视频并输出骨架展示文件路径main.pyimport cv2 import numpy as np from pose_utils import PoseExtractor, normalize_landmarks from action_matcher import ActionMatcher def main(video_path, output_path, templatesNone): cap cv2.VideoCapture(video_path) # 获取视频信息用于创建输出视频 fps int(cap.get(cv2.CAP_PROP_FPS)) width int(cap.get(cv2.CAP_PROP_FRAME_WIDTH)) height int(cap.get(cv2.CAP_PROP_FRAME_HEIGHT)) fourcc cv2.VideoWriter_fourcc(*mp4v) writer cv2.VideoWriter(output_path, fourcc, fps, (width, height)) pose_extractor PoseExtractor() matcher ActionMatcher(templates or {}) frame_count 0 while True: ret, frame cap.read() if not ret: break landmarks, skeleton_frame pose_extractor.extract(frame) if landmarks is not None: normalized normalize_landmarks(landmarks) matched_name, distance matcher.match(normalized) # 在画面左上角展示识别结果 text fAction: {matched_name} (dist{distance:.2f}) cv2.putText( skeleton_frame, text, (20, 50), cv2.FONT_HERSHEY_SIMPLEX, 1.0, (0, 255, 255), 2, ) writer.write(skeleton_frame) frame_count 1 cap.release() writer.release() pose_extractor.close() print(f处理完成共处理 {frame_count} 帧输出文件{output_path}) if __name__ __main__: main( video_pathsamples/taichi_demo.mp4, output_pathoutput/skeleton_result.mp4, )运行方式python main.py如果没有提供模板库程序会正常读取视频并输出骨架动画但动作名称会显示为 “unknown”这属于预期结果。4.5 构建简单的太极模板库为了让展示更完整你需要准备两段短视频一段是标准动作视频例如“起势”。另一段是待识别的测试视频。先生成模板import cv2 from pose_utils import PoseExtractor, normalize_landmarks, build_template_from_video pose_extractor PoseExtractor() template_qishi build_template_from_video( samples/qishi_standard.mp4, # 标准起势视频 pose_extractor, frame_indices[10, 15, 20, 25], ) print(起势模板形状:, template_qishi.shape)得到的template_qishi是一个 shape 为(33, 2)的 NumPy 数组。你可以将多个模板保存为.npy文件方便后续加载np.save(templates/qishi.npy, template_qishi)然后在主流程中加载templates { 起势: np.load(templates/qishi.npy), } main( video_pathsamples/taichi_demo.mp4, output_pathoutput/skeleton_result.mp4, templatestemplates, )这样当测试视频中的动作与“起势”模板足够接近时画面左上角就会实时显示 “Action: 起势”。5. 常见问题与排查思路在实际运行这套流程时可能会遇到各种问题。下面按优先级整理一份排查清单。问题现象常见原因解决思路MediaPipe 找不到人体关键点画质差、人物太小、画面模糊提高视频分辨率让人物占据画面更大比例关键点抖动严重未开启平滑参数或置信度阈值过低调大min_detection_confidence和min_tracking_confidence输出视频没有骨架画面视频编码不支持尝试改用avc1或mp4v编码动作匹配结果一直为 unknown没有设置模板或模板与测试动作差异过大确认模板已加载增加更多标准动作模板坐标归一化后出现 NaN肩宽接近于 0通常是因为人体未完整露出增加shoulder_width 1e-6的防御处理视频处理速度很慢每帧都运行完整姿态估计可以跳帧处理比如每 2 帧取 1 帧匹配准确率低只用欧氏距离对时序变化不敏感换用 DTW 或训练小型时序分类模型5.1 一个典型问题关键点坐标系与 OpenCV 不一致MediaPipe 输出的 x、y 是归一化坐标需要乘以图像宽高才能得到像素坐标。如果在绘制骨架时发现位置错乱优先检查是否漏掉了这一步。height, width frame.shape[:2] x_pixel int(landmark[0] * width) y_pixel int(landmark[1] * height)5.2 一个问题动态招式匹配不准用均值姿势模板做动态招式匹配时本质上丢掉了时间信息。太极拳中“云手”“野马分鬃”这类动作手的位置随时间变化剧烈均值模板很容易混淆不同招式。解决办法是使用 DTW 或 LSTM 对关键点序列建模。DTW 不需要训练适合快速原型验证LSTM 等模型需要更多标注数据但泛化能力更强。6. 最佳实践与工程建议6.1 数据采集与标注拍摄标准动作视频时尽量让表演者正对镜头避免侧面角度造成关键点自遮挡。每个动作至少采集 3 到 5 段视频覆盖不同节奏和幅度。标注时记录动作的起止帧方便后续截取有效片段。训练分类模型时注意正负样本均衡除了目标招式还要加入“非招式”样本作为负例。6.2 模型选择与推理性能MediaPipe 提供了 Lite、Full、Heavy 三档模型复杂度。移动端推荐 Lite服务器端可以使用 Full 或 Heavy。在视频处理场景可以先用运动检测判断画面中是否存在人体减少无效帧的推理开销。如果需要实时处理建议把姿态估计放到 GPU 上时序匹配放到 CPU 上两条流水线并行。6.3 异常处理与日志记录姿态估计在真实环境中难免出错。建议在代码中增加以下处理连续多帧检测不到关键点时记录 warning 日志而不是直接抛出异常。对关键点做插值补全短暂丢失的帧。关键点的 visibility 低于阈值时在匹配阶段剔除对应点。# 示例只使用高可见性关键点参与匹配 visible_mask normalized[:, 2] 0.7 filtered_pose normalized[visible_mask][:, :2]6.4 安全与合规本文涉及的视频数据可能包含人脸等个人信息。在真实项目中请遵循最小必要原则只处理任务必需的视频帧不长期留存原始视频。对视频中人脸区域进行模糊处理。涉及用户上传内容时明确告知数据使用范围并获得授权。7. 总结与学习路线本文围绕 Lumos NIX 的太极招式展示场景梳理了一套从视频输入到关键点提取、坐标归一化、动作匹配与骨架展示的完整实现链路。你可以直接运行文中的示例代码在自己的太极视频上生成骨架动画并体验动作匹配的基本流程。如果想把准确率做得更高下一步建议按这个路线深入学习掌握 DTW 算法用序列相似度替换单帧欧氏距离。学习 LSTM 或 TCN对关键点序列做端到端分类。了解 Transformer 在骨骼动作识别中的应用例如 PoseFormer。针对太极招式库整理标准动作数据集训练专属分类模型。对于实际项目建议先把“骨架展示”这个基础功能做稳定再逐步叠加动作识别、节奏分析、教学评分等高级能力。这套思路同样适合健身、舞蹈、康复训练等方向。动手跑一遍代码你就能真正理解多模态动作展示的底层逻辑。
当多模态 AI 遇上太极会发生什么近期 Lumos NIX 的太极招式展示刷了一波技术圈的好感背后并不是什么“玄学”而是一套成熟的视觉动作理解、姿态估计与时序动作生成链路。本文将以“太极招式展示”为业务场景拆解这套能力从视频输入到骨架提取、再到动作匹配与展示的完整实现思路。不管你是在做 AI 健身、体感游戏还是动作教学类应用这套方案都有很高的参考价值。1. 背景与核心概念1.1 Lumos NIX 是什么Lumos 可以理解为一个面向多模态交互的实验性项目而 NIX 是这个项目中负责动作理解与生成的核心模块。两者的组合在近期因为一段“太极招式展示”而受到关注输入一段太极视频系统能够识别出招式的关键帧、肢体动作轨迹并以骨架动画或语义描述的方式把招式重新“展示”出来。这种能力听起来很酷但拆开来看本质上是三个经典技术问题的串联视频中的人体姿态估计Human Pose Estimation。骨骼关键点在时间轴上的序列建模。动作语义与标准动作库的匹配或生成。1.2 太极招式展示的技术含义太极招式不是简单的肢体位移它包含抬手、转身、重心转移、节奏快慢等多个维度。要让系统“看懂”并“展示”太极招式至少需要做到以下几件事从视频帧中识别出人体关键点例如肩膀、手肘、手腕、髋关节、膝盖、脚踝等。把连续帧的关键点坐标组合成时序数据。对时序数据做归一化去除身高、镜头距离带来的尺度差异。与标准动作模板进行比较输出相似度或者生成可读的动作描述。所以所谓的“展示”既可以是以骨架动画形式的视觉化回放也可以是以 “第3式白鹤亮翅右手上举左手下按” 这样的语义描述输出。1.3 这类技术能用在哪里抛开太极这个具体场景这套技术方案的应用面很广运动健身 App 中的动作次数统计与姿势纠正。体感游戏中的玩家动作识别。舞蹈教学中的动作拆解与对比。康复训练中的肢体活动度评估。传统武术、八段锦、健身操等标准化动作教学。换句话说掌握了这套链路你就能在大部分“视频动作理解”场景中快速落地。2. 环境准备与版本说明本文示例使用 Python 作为主力语言。Python 在 AI 和计算机视觉领域生态最完整适合快速验证。2.1 基础环境依赖项说明操作系统Windows 10/11、Ubuntu 20.04 均可Python3.9 或 3.10OpenCV视频读取与图像处理MediaPipe人体姿态关键点检测NumPy关键点坐标数组处理PyTorch 或 TensorFlow时序动作分类可选版本需要根据你的项目实际情况调整本文示例以常见环境为例重点演示配置思路。在你的虚拟环境中可以执行以下命令安装基础依赖pip install opencv-python mediapipe numpy如果后续需要做动作分类再补充安装深度学习框架pip install torch torchvision2.2 项目目录结构为了方便管理建议按照下面的结构组织代码tai-chi-demo/ ├── main.py # 主流程负责读取视频、提取关键点、展示结果 ├── pose_utils.py # 姿态提取工具函数 ├── action_matcher.py # 动作匹配逻辑 ├── samples/ │ └── taichi_demo.mp4 # 示例太极视频 └── output/ └── skeleton_result.mp4 # 输出骨架展示视频3. 核心原理拆解在写代码之前需要先理解几个核心概念。3.1 人体姿态估计人体姿态估计的目标是从图像中定位人体的关键点。MediaPipe 提供了一套基于 BlazePose 的解决方案可以检测 33 个人体关键点包括面部、躯干、手臂和腿部。MediaPipe 的检测结果中每个关键点包含归一化的 x、y 坐标以及可见性 visibility。坐标值是基于图像宽度和高度的比例范围在 0 到 1 之间。这一设计让关键点坐标天然具备一定程度的尺度不变性但依然会受到人体在画面中位置的影响。3.2 坐标归一化由于每个人的身高、体型不同同样的动作在画面中呈现的关键点坐标差异可能很大。为了让动作对比更公平需要做归一化处理。常见做法是以髋部中心为原点将全部关键点平移到原点。以左肩到右肩的距离为基准对坐标做等比例缩放。这样处理后不同体型、不同位置的同一种动作关键点坐标就能对齐。3.3 时序建模单一帧的关键点只能反映瞬间姿态无法表达太极招式中的“动势”。因此需要把连续帧的关键点序列输入到时序模型中例如 LSTM、TCN 或 Transformer。对于简单场景也可以使用动态时间规整DTWDynamic Time Warping算法计算两个动作序列的相似度这种方式不需要训练模型适合原型验证。3.4 动作展示的两种形式骨架动画形式将关键点连接成骨骼线条绘制在画面上生成一段骨架视频。语义描述形式通过动作分类模型输出招式名称或者通过规则生成中文描述。本文的实战案例会同时演示骨架展示和基于距离匹配的招式识别。4. 完整实战案例下面我们以一个太极视频为例走通“读取视频 - 提取关键点 - 绘制骨架 - 动作匹配”的完整流程。4.1 提取人体关键点先实现一个工具模块封装 MediaPipe 的姿态检测逻辑。文件路径pose_utils.pyimport cv2 import mediapipe as mp import numpy as np class PoseExtractor: def __init__(self): self.mp_pose mp.solutions.pose self.pose self.mp_pose.Pose( static_image_modeFalse, model_complexity1, smooth_landmarksTrue, min_detection_confidence0.5, min_tracking_confidence0.5, ) def extract(self, frame): 从一帧图像中提取人体关键点。 返回 (landmarks, skeleton_image) landmarks: 33 个关键点的归一化坐标列表 skeleton_image: 绘制了骨架的 RGB 图像 rgb_frame cv2.cvtColor(frame, cv2.COLOR_BGR2RGB) results self.pose.process(rgb_frame) if not results.pose_landmarks: return None, frame landmarks [] for lm in results.pose_landmarks.landmark: landmarks.append([lm.x, lm.y, lm.visibility]) skeleton_frame frame.copy() self.mp_pose_draw mp.solutions.drawing_utils self.mp_pose_draw.draw_landmarks( skeleton_frame, results.pose_landmarks, self.mp_pose.POSE_CONNECTIONS, landmark_drawing_specself.mp_pose_draw.DrawingSpec( color(0, 255, 0), thickness2, circle_radius2 ), connection_drawing_specself.mp_pose_draw.DrawingSpec( color(0, 0, 255), thickness2 ), ) return np.array(landmarks), skeleton_frame def close(self): self.pose.close()这段代码的核心逻辑很简单将 OpenCV 读取的 BGR 图像转换为 RGB因为 MediaPipe 的输入要求是 RGB。pose.process()返回检测结果。遍历pose_landmarks.landmark收集所有关键点的归一化坐标。用draw_landmarks把骨架绘制到画面中。4.2 坐标归一化处理接下来实现坐标归一化函数把关键点对齐到统一坐标系。文件路径pose_utils.py追加内容def normalize_landmarks(landmarks): 以髋部中心为原点以肩宽为单位长度对关键点做归一化。 landmarks: shape (33, 3) 的数组 if landmarks is None or len(landmarks) 0: return None lm landmarks.copy() # 提取髋部中心左髋 index23右髋 index24 left_hip lm[23][:2] right_hip lm[24][:2] hip_center (left_hip right_hip) / 2.0 # 平移到原点 lm[:, 0] - hip_center[0] lm[:, 1] - hip_center[1] # 计算肩宽左肩 index11右肩 index12 left_shoulder lm[11][:2] right_shoulder lm[12][:2] shoulder_width np.linalg.norm(right_shoulder - left_shoulder) if shoulder_width 1e-6: return None # 等比例缩放 lm[:, 0] / shoulder_width lm[:, 1] / shoulder_width return lm归一化之后不同体型的人做同一个动作时关键点坐标会比较接近后续匹配的准确率会更高。4.3 动作匹配逻辑太极招式是时序动作这里用两种方式进行匹配演示单帧姿势匹配适合静态站桩姿势例如“起势”“十字手”。简单 DTW 序列匹配适合动态招式。为了控制篇幅先实现一个基于均值姿势模板的匹配逻辑。文件路径action_matcher.pyimport numpy as np class ActionMatcher: def __init__(self, templates): templates: dict, 格式为 { 起势: np.array([...]), # shape (33, 2) 归一化关键点均值 白鹤亮翅: np.array([...]), } self.templates templates staticmethod def euclidean_distance(pose_a, pose_b): diff pose_a - pose_b distance np.sqrt(np.sum(diff ** 2)) return distance def match(self, normalized_landmarks): 输入归一化关键点返回最匹配的招式名称和距离。 if normalized_landmarks is None: return unknown, 9999.0 # 只取前 33 个关键点的 x, y 坐标忽略 visibility current_pose normalized_landmarks[:, :2] best_name unknown best_distance 9999.0 for name, template in self.templates.items(): distance self.euclidean_distance(current_pose, template) if distance best_distance: best_distance distance best_name name return best_name, best_distance由于标准模板需要从真实太极视频中提取这里提供一个“从样本视频生成模板”的工具方法方便你在自己的数据集上构建模板库。def build_template_from_video(video_path, pose_extractor, frame_indicesNone): 从视频中提取多帧关键点计算平均姿势作为模板。 frame_indices: 指定取哪些帧默认取全部帧的平均值 cap cv2.VideoCapture(video_path) landmarks_list [] if frame_indices is None: frame_indices [] index 0 while True: ret, frame cap.read() if not ret: break if not frame_indices or index in frame_indices: landmarks, _ pose_extractor.extract(frame) if landmarks is not None: normalized normalize_landmarks(landmarks) if normalized is not None: landmarks_list.append(normalized[:, :2]) index 1 cap.release() if not landmarks_list: return None return np.mean(landmarks_list, axis0)注意这里为了演示省略cv2的 import完整代码中需要补上。4.4 主流程读取视频并输出骨架展示文件路径main.pyimport cv2 import numpy as np from pose_utils import PoseExtractor, normalize_landmarks from action_matcher import ActionMatcher def main(video_path, output_path, templatesNone): cap cv2.VideoCapture(video_path) # 获取视频信息用于创建输出视频 fps int(cap.get(cv2.CAP_PROP_FPS)) width int(cap.get(cv2.CAP_PROP_FRAME_WIDTH)) height int(cap.get(cv2.CAP_PROP_FRAME_HEIGHT)) fourcc cv2.VideoWriter_fourcc(*mp4v) writer cv2.VideoWriter(output_path, fourcc, fps, (width, height)) pose_extractor PoseExtractor() matcher ActionMatcher(templates or {}) frame_count 0 while True: ret, frame cap.read() if not ret: break landmarks, skeleton_frame pose_extractor.extract(frame) if landmarks is not None: normalized normalize_landmarks(landmarks) matched_name, distance matcher.match(normalized) # 在画面左上角展示识别结果 text fAction: {matched_name} (dist{distance:.2f}) cv2.putText( skeleton_frame, text, (20, 50), cv2.FONT_HERSHEY_SIMPLEX, 1.0, (0, 255, 255), 2, ) writer.write(skeleton_frame) frame_count 1 cap.release() writer.release() pose_extractor.close() print(f处理完成共处理 {frame_count} 帧输出文件{output_path}) if __name__ __main__: main( video_pathsamples/taichi_demo.mp4, output_pathoutput/skeleton_result.mp4, )运行方式python main.py如果没有提供模板库程序会正常读取视频并输出骨架动画但动作名称会显示为 “unknown”这属于预期结果。4.5 构建简单的太极模板库为了让展示更完整你需要准备两段短视频一段是标准动作视频例如“起势”。另一段是待识别的测试视频。先生成模板import cv2 from pose_utils import PoseExtractor, normalize_landmarks, build_template_from_video pose_extractor PoseExtractor() template_qishi build_template_from_video( samples/qishi_standard.mp4, # 标准起势视频 pose_extractor, frame_indices[10, 15, 20, 25], ) print(起势模板形状:, template_qishi.shape)得到的template_qishi是一个 shape 为(33, 2)的 NumPy 数组。你可以将多个模板保存为.npy文件方便后续加载np.save(templates/qishi.npy, template_qishi)然后在主流程中加载templates { 起势: np.load(templates/qishi.npy), } main( video_pathsamples/taichi_demo.mp4, output_pathoutput/skeleton_result.mp4, templatestemplates, )这样当测试视频中的动作与“起势”模板足够接近时画面左上角就会实时显示 “Action: 起势”。5. 常见问题与排查思路在实际运行这套流程时可能会遇到各种问题。下面按优先级整理一份排查清单。问题现象常见原因解决思路MediaPipe 找不到人体关键点画质差、人物太小、画面模糊提高视频分辨率让人物占据画面更大比例关键点抖动严重未开启平滑参数或置信度阈值过低调大min_detection_confidence和min_tracking_confidence输出视频没有骨架画面视频编码不支持尝试改用avc1或mp4v编码动作匹配结果一直为 unknown没有设置模板或模板与测试动作差异过大确认模板已加载增加更多标准动作模板坐标归一化后出现 NaN肩宽接近于 0通常是因为人体未完整露出增加shoulder_width 1e-6的防御处理视频处理速度很慢每帧都运行完整姿态估计可以跳帧处理比如每 2 帧取 1 帧匹配准确率低只用欧氏距离对时序变化不敏感换用 DTW 或训练小型时序分类模型5.1 一个典型问题关键点坐标系与 OpenCV 不一致MediaPipe 输出的 x、y 是归一化坐标需要乘以图像宽高才能得到像素坐标。如果在绘制骨架时发现位置错乱优先检查是否漏掉了这一步。height, width frame.shape[:2] x_pixel int(landmark[0] * width) y_pixel int(landmark[1] * height)5.2 一个问题动态招式匹配不准用均值姿势模板做动态招式匹配时本质上丢掉了时间信息。太极拳中“云手”“野马分鬃”这类动作手的位置随时间变化剧烈均值模板很容易混淆不同招式。解决办法是使用 DTW 或 LSTM 对关键点序列建模。DTW 不需要训练适合快速原型验证LSTM 等模型需要更多标注数据但泛化能力更强。6. 最佳实践与工程建议6.1 数据采集与标注拍摄标准动作视频时尽量让表演者正对镜头避免侧面角度造成关键点自遮挡。每个动作至少采集 3 到 5 段视频覆盖不同节奏和幅度。标注时记录动作的起止帧方便后续截取有效片段。训练分类模型时注意正负样本均衡除了目标招式还要加入“非招式”样本作为负例。6.2 模型选择与推理性能MediaPipe 提供了 Lite、Full、Heavy 三档模型复杂度。移动端推荐 Lite服务器端可以使用 Full 或 Heavy。在视频处理场景可以先用运动检测判断画面中是否存在人体减少无效帧的推理开销。如果需要实时处理建议把姿态估计放到 GPU 上时序匹配放到 CPU 上两条流水线并行。6.3 异常处理与日志记录姿态估计在真实环境中难免出错。建议在代码中增加以下处理连续多帧检测不到关键点时记录 warning 日志而不是直接抛出异常。对关键点做插值补全短暂丢失的帧。关键点的 visibility 低于阈值时在匹配阶段剔除对应点。# 示例只使用高可见性关键点参与匹配 visible_mask normalized[:, 2] 0.7 filtered_pose normalized[visible_mask][:, :2]6.4 安全与合规本文涉及的视频数据可能包含人脸等个人信息。在真实项目中请遵循最小必要原则只处理任务必需的视频帧不长期留存原始视频。对视频中人脸区域进行模糊处理。涉及用户上传内容时明确告知数据使用范围并获得授权。7. 总结与学习路线本文围绕 Lumos NIX 的太极招式展示场景梳理了一套从视频输入到关键点提取、坐标归一化、动作匹配与骨架展示的完整实现链路。你可以直接运行文中的示例代码在自己的太极视频上生成骨架动画并体验动作匹配的基本流程。如果想把准确率做得更高下一步建议按这个路线深入学习掌握 DTW 算法用序列相似度替换单帧欧氏距离。学习 LSTM 或 TCN对关键点序列做端到端分类。了解 Transformer 在骨骼动作识别中的应用例如 PoseFormer。针对太极招式库整理标准动作数据集训练专属分类模型。对于实际项目建议先把“骨架展示”这个基础功能做稳定再逐步叠加动作识别、节奏分析、教学评分等高级能力。这套思路同样适合健身、舞蹈、康复训练等方向。动手跑一遍代码你就能真正理解多模态动作展示的底层逻辑。
平方复杂度无法被常规优化消除｜TaoToken 统一 Key 通道实测)
