最近帮朋友整理一套“用现成舞蹈视频做可复用动作模板”的流程，前前后后踩了不少坑：视频里人一跳快，关键点就跟着乱飞；换了机位，同一支舞导出的坐标完全对不上；导出的 JSON 拿到下游渲染，人物直接站在原地抽搐。网上关于“AI 舞蹈模板”的资料大多是成品展示，真正讲清楚从视频到骨骼序列这一步怎么落地、参数怎么调、出错怎么排的文章不多。所以这篇文章把整条流水线拆开讲一遍，包含完整的抽取、归一化、平滑、导出和渲染代码，读者可以直接复制到本地跑通。无论你是想给自己做的动画项目准备一套动作素材，还是想把动作数据接进前端 Canvas 或 3D 引擎，都可以按本文顺序一步步来。
本文不会绑定某一家 AI 产品的具体接口，因为这类产品的接口形态变化很快，写死某个类名和参数对读者没有太大帮助。真正稳定、可迁移的知识是中间那层数据结构和处理流程：视频怎么抽帧、关键点怎么表示、坐标系怎么统一、抖动怎么压下去、结果怎么组织成一份下游能直接消费的模板文件。这套东西学会之后，无论上游换成哪家的 AI 助手做创意和分镜，下游换成哪种渲染方案，中间的骨骼模板层都能复用。
1. 先搞清楚：AI 舞蹈模板到底是什么
1.1 从“一段视频”到“一套可复用模板”
很多人第一次接触这个概念，会把它理解成“让 AI 生成一段跳舞的视频”。这其实是两件事。生成视频属于内容生产，输出的是一段像素；而舞蹈模板属于数据结构，输出的是一串带时间轴的骨骼关键点。前者的产物只能看，后者的产物可以被驱动、被编辑、被拼接、被复用。你把一套模板套到不同角色上，就能得到不同的画面，这才是“模板”两个字的含义。
从工程角度看，一套舞蹈模板至少包含三样东西：每一帧的身体关键点坐标、帧率和时间戳信息、以及一份说明这份模板适用范围和采集条件的元数据。少了元数据，别人拿到你的模板根本不知道该按什么比例还原，动作不是被拉长就是被压扁。所以本文在做流水线的时候，会把源视频分辨率、帧率、归一化尺度基准这些信息一并写进输出文件，而不是只丢一个坐标数组出去。
在实际项目里，模板最常见的用途有三个方向。第一是驱动虚拟形象，把真人舞蹈迁移到 2D 或 3D 角色上，这是虚拟主播和动画短片的高频需求。第二是动作比对，比如教学场景里判断学员动作和标准动作的相似度。第三是动作检索，把一堆舞蹈视频先跑成骨骼模板，再按动作片段做相似度搜索，比直接比对原始视频效率高得多。这三种用途对精度的要求并不一样，驱动虚拟形象最怕抖动，动作比对最怕坐标不统一，动作检索最怕维度不一致，本文的处理流程会同时照顾这三点。
1.2 三条主流技术路线与取舍
做动作迁移这件事，业内大致有三条路线。第一条是 2D 骨骼驱动，从视频里估出 2D 关键点，直接驱动 2D 角色或者拿去重定向到 3D 骨骼。这条路线实现成本最低，依赖也最少，一个姿态估计模型加一个渲染器就能跑起来，缺点是当人物侧身或者被遮挡时，深度信息缺失会导致动作看起来“扁平”。第二条是 3D 姿态估计，直接输出带深度的三维关键点，动作更立体，但对模型和算力的要求明显更高，且在遮挡场景下的稳定性反而不如 2D 方案。
第三条是视频扩散类的方法，直接把动作当作生成条件去合成新视频。这条路线的画面质量上限最高，但可控性最差，同一份输入两次生成的结果可能不一致，而且对硬件的要求通常不是普通开发者能承受的。更关键的是，这类方法产出的是一段视频，不是一个结构化模板，你想二次编辑某一帧的姿势基本无从下手。
本文选择的是第一条路线，也就是 2D 骨骼驱动。理由很实际：它能在普通笔记本上跑通，处理逻辑完全透明，每一步的中间结果都可以可视化检查，出错的时候能定位到具体是哪一环。对于绝大部分个人项目和小型团队来说，先把 2D 这条链路做扎实，比一上来就追 3D 更划算。等你把 2D 模板的坐标系、平滑和重定向都摸清楚了，再往 3D 迁移，思路是相通的。
1.3 容易混淆的几组概念
第一组要区分的是“姿态估计”和“动作识别”。姿态估计回答的是“这一帧里人的关节在什么位置”，输出的是坐标；动作识别回答的是“这段视频里的人在做什么动作”，输出的是类别标签。两者经常被一起使用，但解决的问题完全不同。本文做的是前者，动作识别可以在这套模板之上再做一层分类模型，但那属于另一个话题。
第二组是“骨骼关键点”和“骨骼拓扑”。关键点是空间中的一组点，拓扑是这些点之间谁连着谁。同一个姿态估计模型输出的关键点编号顺序是固定的，但你拿去渲染的时候，用哪套拓扑连线是你自己决定的。有的模型给 33 个点，有的给 17 个点，编号含义还不一样。跨模型迁移的时候，如果不做编号映射，画出来的骨架会完全错乱，这是新手非常容易踩的坑。
第三组是“模板”和“片段”。模板通常指一段完整、可复用的动作序列，片段则是从模板里截出来的局部。在工程上建议把两者分开管理：模板文件保存完整的动作数据和元信息，片段只保存起始帧、结束帧和对模板的引用。这样当模板需要重新采集或修正时，所有基于它截出来的片段会自动跟着更新，不用一个个去改。
2. 环境准备与版本说明
2.1 硬件、系统与 Python 环境
本文的示例在 Windows 和 Linux 上都能跑，macOS 也可以。硬件方面没有硬性门槛，普通四核 CPU 就能完成一段几分钟视频的关键点抽取，只是速度慢一些；如果你有独立显卡，姿态估计模型的部分环节可以走 GPU 加速，但本文的代码默认走 CPU，避免因为显卡驱动版本差异导致读者跑不起来。
Python 版本建议使用 3.9 到 3.11 之间。太老的版本在安装部分科学计算依赖时会遇到预编译包缺失的问题，太新的版本又可能碰上某些依赖还没跟上。具体用哪个小版本，请以你本机已有的、能正常安装依赖的环境为准，本文不强行锁定一个小版本号。
# 查看当前 Python 版本 python --version # 建议在虚拟环境里操作，避免污染全局依赖 python -m venv venv # Windows 激活 venv\Scripts\activate # Linux / macOS 激活 source venv/bin/activate虚拟环境这一步别省。姿态估计相关的依赖树比较深，直接装在全局环境里，后面想换版本会非常麻烦。尤其是当你同时在做多个项目的时候，不同项目对同一套依赖的版本要求经常会打架，用虚拟环境隔离是最省事的做法。
2.2 核心依赖安装
本文用到的核心依赖有四个：opencv-python负责视频读写和图像处理，mediapipe负责姿态估计，numpy负责数值计算，pyyaml负责读取配置文件。这四个包在 PyPI 上都能直接装到，不需要编译。
pip install opencv-python mediapipe numpy pyyaml需要提醒的是，mediapipe的版本迭代比较快，不同大版本之间在 API 命名和返回值结构上偶有调整。本文的代码基于mp.solutions.pose这套接口编写，这套接口在多个版本中长期存在，兼容性较好。如果你安装后发现mp.solutions下找不到pose，说明版本差异较大，请对照你所用版本的官方文档核对一下调用方式，不要直接照抄。
安装完成后可以用一行命令验证环境是否正常：
python -c "import cv2, mediapipe as mp, numpy, yaml; print('cv2', cv2.__version__); print('mediapipe ok')"能正常打印出版本号，说明基础环境就绪。如果这里就报错，先解决依赖问题，别急着往下走，后面所有代码都依赖这一层。
2.3 示例项目目录结构
为了让代码好维护，一开始就把目录结构规划好。下面这套结构把原始素材、中间产物、最终模板和脚本分开存放，后面加功能的时候不会乱。
dance-template/ ├── config/ │ └── pipeline.yaml # 流水线参数配置 ├── data/ │ ├── raw/ # 原始舞蹈视频 │ ├── processed/ # 中间产物（关键点 JSON） │ └── template/ # 最终模板文件 ├── scripts/ │ ├── extract_pose.py # 抽取关键点 │ ├── normalize.py # 归一化与对齐 │ ├── smooth.py # 时序平滑 │ ├── build_template.py # 串起整条流水线 │ └── render_skeleton.py # 骨架预览渲染 └── requirements.txt这里有一个设计上的考虑：为什么中间产物要单独存一份 JSON，而不是一步到位直接输出模板？因为调试的时候你几乎一定需要回看中间结果。比如发现渲染出来的动作不对，你是想重新跑一遍视频解码，还是直接读中间 JSON 换种方式处理？显然后者快得多，尤其是视频较长的时候，重新抽取一次可能要几分钟。
3. 核心原理拆解：骨骼关键点是怎么算出来的
3.1 人体姿态估计的基本流程
姿态估计模型的输入是一张图像，输出是一组关键点的位置。中间大致经历几个阶段：先做人体检测，把画面里的人框出来；再在框内做关键点回归，得到每个关节的坐标；最后根据置信度做筛选和修正。这套流程听起来简单，但里面有个细节对结果影响很大——模型是逐帧独立处理的，它在处理第 N 帧时并不知道第 N-1 帧的结果。
这就带来一个直接后果：相邻两帧的检测结果会有细微差异，人物静止不动的时候关键点也在小幅跳动。如果你的视频是 30 帧每秒，这种跳动在渲染出来之后会非常明显，看起来像整个人在发抖。所以后续必须做时序平滑，这一点在后面 3.4 节会展开讲。
另一个需要注意的点是可见度（visibility）。姿态估计模型不只输出坐标，还会输出每个关键点的可见度分数，表示这个点在当前帧里是否被可靠地检测到。当人物转身、被遮挡，或者某个关节跑出画面时，这个分数会明显下降，对应的坐标也就不可信了。工程上必须对可见度做阈值过滤，否则这些不可信的点会被当成真实数据参与后续计算，导致整段动作崩掉。
# 文件路径：scripts/extract_pose.py（片段，演示单帧处理逻辑） import cv2 import mediapipe as mp mp_pose = mp.solutions.pose pose = mp_pose.Pose( static_image_mode=False, # 视频流用 False，会启用帧间跟踪 model_complexity=1, # 0/1/2，越大越准也越慢 smooth_landmarks=True, # 开启内置平滑 min_detection_confidence=0.5, # 首次检测阈值 min_tracking_confidence=0.5, # 跟踪阈值 ) cap = cv2.VideoCapture("data/raw/dance.mp4") ok, frame = cap.read() if ok: rgb = cv2.cvtColor(frame, cv2.COLOR_BGR2RGB) rgb.flags.writeable = False # 只读，能让内部少一次拷贝 result = pose.process(rgb) if result.pose_landmarks: for idx, lm in enumerate(result.pose_landmarks.landmark): print(idx, round(lm.x, 4), round(lm.y, 4), round(lm.visibility, 3)) cap.release() pose.close()这段代码里有两个参数值得单独说明。static_image_mode=False表示你处理的是连续视频而不是孤立图片，模型会启用帧间跟踪，速度和稳定性都会好一些；如果你把它设成True，每帧都当独立图片处理，结果是精度略有提升但相邻帧的一致性变差，抖动反而更明显。smooth_landmarks=True是模型自带的平滑开关，它能缓解一部分抖动，但远远不够，后面还是要自己做滤波。
3.2 关键点编号、坐标系与可见度
本文使用的关键点集合一共 33 个点，覆盖了面部、上肢、躯干和下肢。编号是固定的，比如 0 号是鼻子，11 和 12 是左右肩，23 和 24 是左右髋，27 到 32 是脚踝和脚尖。写代码的时候不要凭记忆写编号，最好在文件顶部定义成常量，需要的时候引用名字而不是数字，否则过几周回来看代码，你自己都不知道 25 是什么部位。
坐标系的处理是最容易出错的地方。模型输出的 x 和 y 是相对于图像宽高的归一化值，取值范围在 0 到 1 之间，原点在左上角，y 轴向下。这个坐标系有个很大的问题：它和画面尺寸绑定。同一支舞，用 1080p 拍的和你用 720p 拍的，导出的坐标数值完全不一样，但动作本身是一模一样的。如果你的模板要跨素材复用，直接拿这个坐标去用，动作比例一定会错。
z 坐标表示深度，是相对于髋部中心的估计值，量级和 x、y 不同，不能直接和它们混在一起算距离。在 2D 方案里，z 一般只用来做遮挡判断或者作为辅助特征，不要指望它能给出精确的前后关系。很多新手会拿 z 直接去做 3D 渲染，结果人物看起来像是被压扁了，原因就在这里。
# 文件路径：scripts/landmark_defs.py """关键点编号常量，避免代码里到处出现魔法数字。""" NOSE = 0 LEFT_SHOULDER = 11 RIGHT_SHOULDER = 12 LEFT_ELBOW = 13 RIGHT_ELBOW = 14 LEFT_WRIST = 15 RIGHT_WRIST = 16 LEFT_HIP = 23 RIGHT_HIP = 24 LEFT_KNEE = 25 RIGHT_KNEE = 26 LEFT_ANKLE = 27 RIGHT_ANKLE = 28 LEFT_HEEL = 29 RIGHT_HEEL = 30 LEFT_FOOT_INDEX = 31 RIGHT_FOOT_INDEX = 32 # 用于渲染的骨骼连线，按 (起点, 终点) 组织 BONES = [ (LEFT_SHOULDER, RIGHT_SHOULDER), (LEFT_SHOULDER, LEFT_ELBOW), (LEFT_ELBOW, LEFT_WRIST), (RIGHT_SHOULDER, RIGHT_ELBOW), (RIGHT_ELBOW, RIGHT_WRIST), (LEFT_SHOULDER, LEFT_HIP), (RIGHT_SHOULDER, RIGHT_HIP), (LEFT_HIP, RIGHT_HIP), (LEFT_HIP, LEFT_KNEE), (LEFT_KNEE, LEFT_ANKLE), (RIGHT_HIP, RIGHT_KNEE), (RIGHT_KNEE, RIGHT_ANKLE), (LEFT_ANKLE, LEFT_HEEL), (LEFT_HEEL, LEFT_FOOT_INDEX), (RIGHT_ANKLE, RIGHT_HEEL), (RIGHT_HEEL, RIGHT_FOOT_INDEX), ]把编号和拓扑定义成常量，还有一个好处：将来如果你要换成别的姿态估计模型，只需要改这个映射文件，业务代码几乎不用动。这种把易变部分隔离出去的写法，在长期维护的项目里价值很高。
3.3 动作归一化：让模板不受机位和身材影响
归一化要解决的问题是：同一支舞，不同人在不同距离下跳，采集到的坐标差异巨大。你不希望模板里写着“右手在 x=0.72”，因为换个人、换个机位，这个数字立刻失效。你希望模板描述的是“右手相对身体中心往右偏了 0.8 个肩髋距离”，这种相对描述才具备跨素材的可比性。
实现思路分两步。第一步定原点，通常选左右髋的中点作为身体中心，因为这个点相对稳定，不像手和脚那样动来动去。第二步定尺度，最常用的基准是肩中点到髋中点的距离，也就是躯干长度。用这个距离去除所有坐标，得到的就是无量纲的相对坐标。人物离镜头近，躯干在画面里长，所有坐标一起被这个更长的距离除，比值不变；人物离得远则相反。这样就实现了尺度无关。
# 文件路径：scripts/normalize.py """把绝对坐标转换为以髋部中心为原点、以躯干长度为尺度的相对坐标。""" import numpy as np from landmark_defs import LEFT_HIP, RIGHT_HIP, LEFT_SHOULDER, RIGHT_SHOULDER def normalize_frame(landmarks, min_visibility=0.3): """ landmarks: 长度为 33 的列表，每项含 x / y / v 返回: norm -> (33, 2) 的归一化坐标 valid -> (33,) 的布尔数组，表示该点是否可信 torso -> 当前帧的躯干长度（归一化前的像素比例值） """ pts = np.array([[p["x"], p["y"]] for p in landmarks], dtype=np.float32) vis = np.array([p["v"] for p in landmarks], dtype=np.float32) hip_center = (pts[LEFT_HIP] + pts[RIGHT_HIP]) / 2.0 shoulder_center = (pts[LEFT_SHOULDER] + pts[RIGHT_SHOULDER]) / 2.0 torso = float(np.linalg.norm(shoulder_center - hip_center)) if torso < 1e-6: torso = 1.0 # 退化情况兜底，避免除零 valid = vis >= min_visibility norm = (pts - hip_center) / torso return norm.astype(np.float32), valid, round(torso, 6)这里有个退化情况必须处理：如果某一帧里左右髋或者左右肩同时没检测到，算出来的躯干长度可能是 0，直接做除法会得到无穷大或者 NaN，整个数组就废了。代码里加了1e-6的兜底判断，虽然这一帧的数据依然不可用，但至少不会污染后续计算。
还有一点要注意，归一化之后 y 轴方向仍然是向下的，因为原始坐标就是向下的。如果你下游的渲染环境是 y 轴向上（很多 3D 引擎和 Canvas 都是），记得在导出时翻转一下符号，否则人物会上下颠倒。这个坑非常隐蔽，因为骨架连线的拓扑还是对的，看起来只是“倒过来了”，新手常常以为是模型的问题。
3.4 时间轴平滑：解决抖动和跳变
平滑这一步决定了最终成品的观感。前面说过，逐帧独立检测会带来高频抖动，直接渲染就是整个人在哆嗦。解决办法有很多种，从简单的移动平均到复杂的卡尔曼滤波都有。考虑到大部分读者的实际需求，本文采用指数移动平均（EMA），它的优点是实现简单、只需一个参数、实时性好，缺点是对突发的大幅动作响应会有一点滞后。
EMA 的核心公式是当前输出 = α × 当前输入 + (1 - α) × 上次输出。α 越大越贴近原始数据，平滑效果越弱；α 越小越平滑，但动作会变迟钝。经验值一般在 0.3 到 0.6 之间，动作快的舞蹈建议取大一点，慢动作或者静态姿势可以取小一点。这个参数最好做成可配置项，不同素材用不同值，而不是写死在代码里。
除了抖动，还有一种更麻烦的情况叫跳变。当人物被短暂遮挡，或者手快速摆出画面再回来，关键点会突然跳到别的位置，下一帧又跳回来。EMA 对这种情况只能缓解不能根治，因为它本质上还是在做加权平均。更稳妥的做法是在平滑之前先做一次无效帧修补：把可见度低于阈值的帧标记出来，用前一帧的有效值填充，或者做线性插值。
# 文件路径：scripts/smooth.py """时序平滑与无效帧修补。""" import numpy as np def repair_invalid_frames(seq, valid, max_gap=15): """ seq: (T, K, 2) 坐标序列 valid: (T, K) 布尔序列 对每个关键点，把连续无效的帧用前后有效值线性插值填上。 连续无效超过 max_gap 帧的，直接沿用最后一个有效值。 """ out = seq.copy() t_total, k_total, _ = seq.shape for k in range(k_total): col_valid = valid[:, k] if not col_valid.any(): continue # 整个视频都没检测到这个点，放弃 idx_valid = np.where(col_valid)[0] for t in range(t_total): if col_valid[t]: continue prev = idx_valid[idx_valid < t] nxt = idx_valid[idx_valid > t] if prev.size and nxt.size and (nxt[0] - prev[-1]) <= max_gap: p0, p1 = prev[-1], nxt[0] ratio = (t - p0) / (p1 - p0) out[t, k] = seq[p0, k] * (1 - ratio) + seq[p1, k] * ratio elif prev.size: out[t, k] = seq[prev[-1], k] elif nxt.size: out[t, k] = seq[nxt[0], k] return out def ema_smooth(seq, alpha=0.4, keep=()): """ seq: (T, K, 2) 坐标序列 alpha: 平滑系数，越小越平滑 keep: 需要保持原样的关键点编号（比如脚本自身不参与平滑） """ arr = np.asarray(seq, dtype=np.float32) out = arr.copy() for k in range(arr.shape[1]): if k in keep: continue for t in range(1, arr.shape[0]): out[t, k] = alpha * arr[t, k] + (1 - alpha) * out[t - 1, k] return outrepair_invalid_frames里有一个max_gap参数，含义是“连续缺失多少帧以内做插值”。这个值不要设太大，因为长时间的遮挡意味着那一段动作本身就缺失了，硬插值出来的是凭空捏造的运动轨迹，看起来会很怪。一般来说，15 帧差不多是半秒，超过这个长度建议直接标记为“模板缺失段”，在元数据里注明，让下游知道这段不可用。
3.5 用 AI 助手辅助整理分镜与提示词
在正式跑流水线之前，还有一步准备工作值得单独说说：素材和创意的前期整理。现在用 AI 助手帮忙做这件事已经很普遍了，但很多人用不好，原因是提示词给得太随意，得到的结果也只能是泛泛而谈的套话。想要拿到能直接用的东西，提示词里必须包含明确的角色、输出格式和约束条件。
一个比较有效的结构是这样：先说清楚你要它扮演什么角色，再描述你的具体场景和约束，然后明确要求输出格式，最后给出评判标准让它自查。比如你想让它帮你把一段舞蹈拆成分镜，就不要只写“帮我分析这段舞蹈”，而要写明“你是舞蹈教学视频的分镜策划，我需要把一段 60 秒的舞蹈拆成 8 个镜头，每个镜头包含时间区间、主要动作描述、建议机位，用表格输出，动作描述不超过 20 个字”。约束越具体，输出越可用。
需要提醒的是，AI 助手给你的分镜和动作描述只是文字层面的参考，不能当作精确的动作数据。它没法告诉你第 37 帧左手腕在什么位置，这必须靠姿态估计模型去算。把 AI 助手定位成“前期创意和文案助手”，把姿态估计定位成“数据采集环节”，两者的职责不要混淆，这是用好这类工具的前提。
4. 完整实战：搭一条舞蹈模板抽取流水线
4.1 初始化项目与安装依赖
先把目录建起来，把依赖清单固定下来。requirements.txt里不要写死具体的补丁版本号，因为在不同平台上可用的版本可能不同，写太死会导致别人装不上。用大于等于的写法更稳妥。
# 文件路径：requirements.txt opencv-python>=4.5 mediapipe>=0.9 numpy>=1.21 pyyaml>=6.0mkdir -p dance-template/{config,data/raw,data/processed,data/template,scripts} cd dance-template pip install -r requirements.txt目录建好之后，把你准备好的舞蹈视频放到data/raw/下面。建议先用一段 10 到 20 秒的短视频做验证，确认整条链路跑通之后再换长视频，这样调试成本最低。
4.2 第一步：从视频抽取骨骼关键点
这一步的完整脚本如下。它把视频逐帧喂给姿态估计模型，把每一帧的关键点（如果检测到的话）写进一个 JSON 文件，同时记录源视频的分辨率、帧率这些元信息。
# 文件路径：scripts/extract_pose.py """从舞蹈视频中抽取人体骨骼关键点序列，输出 JSON。""" import argparse import json import os import cv2 import mediapipe as mp def build_pose(model_complexity=1): mp_pose = mp.solutions.pose return mp_pose.Pose( static_image_mode=False, model_complexity=model_complexity, smooth_landmarks=True, enable_segmentation=False, min_detection_confidence=0.5, min_tracking_confidence=0.5, ) def extract(video_path, out_path, model_complexity=1, max_frames=None): cap = cv2.VideoCapture(video_path) if not cap.isOpened(): raise FileNotFoundError(f"无法打开视频文件: {video_path}") fps = cap.get(cv2.CAP_PROP_FPS) or 25.0 width = int(cap.get(cv2.CAP_PROP_FRAME_WIDTH)) height = int(cap.get(cv2.CAP_PROP_FRAME_HEIGHT)) pose = build_pose(model_complexity) frames = [] idx = 0 while True: ok, frame = cap.read() if not ok: break if max_frames is not None and idx >= max_frames: break rgb = cv2.cvtColor(frame, cv2.COLOR_BGR2RGB) rgb.flags.writeable = False result = pose.process(rgb) if result.pose_landmarks: landmarks = [ { "x": round(lm.x, 6), "y": round(lm.y, 6), "z": round(lm.z, 6), "v": round(lm.visibility, 4), } for lm in result.pose_landmarks.landmark ] else: landmarks = None frames.append({"frame": idx, "landmarks": landmarks}) idx += 1 pose.close() cap.release() payload = { "source": os.path.basename(video_path), "fps": fps, "width": width, "height": height, "frame_count": len(frames), "frames": frames, } out_dir = os.path.dirname(os.path.abspath(out_path)) os.makedirs(out_dir, exist_ok=True) with open(out_path, "w", encoding="utf-8") as f: json.dump(payload, f, ensure_ascii=False) detected = sum(1 for x in frames if x["landmarks"] is not None) print(f"[extract] 总帧数={len(frames)} 检测成功={detected} -> {out_path}") if __name__ == "__main__": parser = argparse.ArgumentParser() parser.add_argument("--video", required=True) parser.add_argument("--out", required=True) parser.add_argument("--complexity", type=int, default=1) parser.add_argument("--max-frames", type=int, default=None) args = parser.parse_args() extract(args.video, args.out, args.complexity, args.max_frames)运行方式：
python scripts/extract_pose.py \ --video data/raw/dance.mp4 \ --out data/processed/pose.json \ --complexity 1运行结束后会打印出总帧数和检测成功的帧数。这两个数字的比例很重要，如果成功率低于 80%，说明素材本身有问题，比如人物太小、光线太暗、遮挡严重，这时候调后面的参数没用，得先换素材或者重新拍摄。
4.3 第二步：归一化与坐标对齐
拿到关键点之后，做归一化。这一步的输出是每个关键点相对于髋部中心的坐标，单位是躯干长度。
# 文件路径：scripts/build_template.py """把抽取出来的关键点串成归一化、平滑后的模板。""" import argparse import json import numpy as np from landmark_defs import LEFT_HIP, RIGHT_HIP, LEFT_SHOULDER, RIGHT_SHOULDER from normalize import normalize_frame from smooth import ema_smooth, repair_invalid_frames def load_pose(path): with open(path, "r", encoding="utf-8") as f: return json.load(f) def to_arrays(frames, frame_count): """把 JSON 里的关键点转成 (T, K, 2) 和 (T, K) 两个数组。""" k_total = 33 coords = np.zeros((frame_count, k_total, 2), dtype=np.float32) valid = np.zeros((frame_count, k_total), dtype=bool) last_valid = None for i, item in enumerate(frames): if item["landmarks"] is None: if last_valid is not None: coords[i] = last_valid[0] valid[i] = last_valid[1] continue norm, ok, _ = normalize_frame(item["landmarks"]) coords[i] = norm valid[i] = ok last_valid = (norm, ok) return coords, valid def build(pose_path, out_path, min_visibility=0.3, ema_alpha=0.4): data = load_pose(pose_path) frames = data["frames"] frame_count = data["frame_count"] coords, valid = to_arrays(frames, frame_count) # 1. 先修补无效帧，避免脏数据进入平滑环节 repaired = repair_invalid_frames(coords, valid, max_gap=15) # 2. 再做指数移动平均，压掉高频抖动 smoothed = ema_smooth(repaired, alpha=ema_alpha) template = { "meta": { "source": data["source"], "fps": data["fps"], "width": data["width"], "height": data["height"], "frame_count": frame_count, "keypoint_count": 33, "origin": "hip_center", "scale": "shoulder_hip_distance", "y_axis": "down", "ema_alpha": ema_alpha, }, "valid_ratio": float(valid.mean()), "keypoints": np.round(smoothed, 5).tolist(), "valid": valid.tolist(), } with open(out_path, "w", encoding="utf-8") as f: json.dump(template, f, ensure_ascii=False) print(f"[build] 模板帧数={frame_count} 有效点比例={valid.mean():.2%} -> {out_path}") if __name__ == "__main__": parser = argparse.ArgumentParser() parser.add_argument("--pose", required=True) parser.add_argument("--out", required=True) parser.add_argument("--alpha", type=float, default=0.4) args = parser.parse_args() build(args.pose, args.out, ema_alpha=args.alpha)这段代码里有几个设计点值得说明。第一，to_arrays在处理完全没有检测到人的帧时，会沿用上一个有效帧的数据，并在valid里把这些点标记为 False。这样既保证数组形状一致，又保留了“这一帧是假的”这个信息，下游可以据此决定要不要跳过。第二，处理顺序是先修补再平滑，不能反。如果先平滑，无效的零值会污染邻近的有效帧，把整段数据拉向原点，这个问题在长视频里会累积得非常严重。
第三，模板的meta字段记录了origin、scale、y_axis三个关键约定。这三个字段看起来不起眼，但它们决定了别人拿到你的模板之后能不能正确还原。现实中大量模板文件因为缺了这几行说明，导致下游只能靠猜，猜错了动作就变形。养成写清楚约定信息的习惯，长期看能省下大量沟通成本。
4.4 第三步：时序平滑与无效帧修复
平滑在build_template.py里已经调用了，这里单独把参数调优的实践说清楚。alpha的取值和素材的节奏强相关。对于节奏明快、动作幅度大的舞蹈，建议从 0.5 开始试；对于慢速的、以姿态展示为主的舞蹈，可以从 0.35 开始试。判断标准很简单：把渲染出来的骨架和原视频叠在一起看，如果骨架明显滞后于真人，说明alpha太小了；如果骨架还在抖，说明太大了。
min_visibility这个阈值也要根据素材调整。默认 0.3 适用于大多数正常光线的室内场景。如果素材背景复杂或者光线条件一般，模型给出的可见度普遍偏低，这时候阈值设太高会把大量本来可用的点判为无效，导致修补环节工作量大增。反过来，如果素材质量很好，适当提高阈值到 0.5 能过滤掉更多噪声点。
一个实用的做法是做一次参数扫描。选一小段有代表性的素材（比如 100 帧），用几组不同的参数各跑一遍，把结果渲染成对比视频。虽然多花十几分钟，但比凭感觉瞎调要靠谱得多。参数定下来之后就写进配置文件，不要每次运行都靠命令行传参，容易传错。
4.5 第四步：导出模板并渲染预览
模板文件产出了，但还不能直接用，因为你不知道里面到底是什么。必须做一次可视化验证，这是排查问题最有效的手段。下面的脚本读模板文件，把归一化坐标映射回画布，画成火柴人并输出成视频。
# 文件路径：scripts/render_skeleton.py """把模板渲染成火柴人预览视频，用于人工检查动作是否正确。""" import argparse import json import cv2 import numpy as np from landmark_defs import BONES CANVAS = 720 MARGIN = 60 def to_canvas(pt): """归一化坐标 -> 画布像素坐标。相对坐标范围约 [-1.5, 1.5]。""" scale = (CANVAS - 2 * MARGIN) / 3.0 x = CANVAS / 2 + pt[0] * scale y = CANVAS / 2 + pt[1] * scale return int(round(x)), int(round(y)) def render(template_path, out_path, fps=None): with open(template_path, "r", encoding="utf-8") as f: tpl = json.load(f) meta = tpl["meta"] frames = np.array(tpl["keypoints"], dtype=np.float32) out_fps = fps or meta.get("fps", 25) writer = cv2.VideoWriter( out_path, cv2.VideoWriter_fourcc(*"mp4v"), out_fps, (CANVAS, CANVAS), ) for frame in frames: canvas = np.zeros((CANVAS, CANVAS, 3), dtype=np.uint8) canvas[:] = (18, 18, 18) for start, end in BONES: p0 = to_canvas(frame[start]) p1 = to_canvas(frame[end]) cv2.line(canvas, p0, p1, (80, 200, 255), 3, cv2.LINE_AA) for idx in range(frame.shape[0]): cv2.circle(canvas, to_canvas(frame[idx]), 3, (255, 255, 255), -1, cv2.LINE_AA) writer.write(canvas) writer.release() print(f"[render] 共 {len(frames)} 帧 -> {out_path}") if __name__ == "__main__": parser = argparse.ArgumentParser() parser.add_argument("--template", required=True) parser.add_argument("--out", required=True) parser.add_argument("--fps", type=float, default=None) args = parser.parse_args() render(args.template, args.out, args.fps)运行：
python scripts/render_skeleton.py \ --template data/template/dance.json \ --out data/processed/preview.mp4渲染的to_canvas函数里，scale的计算方式是把相对坐标的大致范围[-1.5, 1.5]映射到画布中央区域。这个范围是根据归一化后的实际数值估算的，因为坐标是以躯干长度为单位的，正常人抬手的高度大概在躯干长度的 1 到 1.5 倍之间。如果你的动作幅度特别大，比如大幅跳跃，可以把分母调大一点，避免画到画布外面去。
4.6 运行验证与输出说明
把整条链路跑一遍，完整的命令序列是这样：
# 1. 抽取关键点 python scripts/extract_pose.py \ --video data/raw/dance.mp4 \ --out data/processed/pose.json # 2. 生成模板 python scripts/build_template.py \ --pose data/processed/pose.json \ --out data/template/dance.json \ --alpha 0.4 # 3. 渲染预览 python scripts/render_skeleton.py \ --template data/template/dance.json \ --out data/processed/preview.mp4三步都成功的话，终端会依次输出类似下面的内容：
[extract] 总帧数=1830 检测成功=1812 -> data/processed/pose.json [build] 模板帧数=1830 有效点比例=96.34% -> data/template/dance.json [render] 共 1830 帧 -> data/processed/preview.mp4打开preview.mp4，如果看到的是一个动作流畅、和原视频节奏基本一致的火柴人，说明整条流水线跑通了。判断标准有三个：一是动作幅度和原视频接近，如果明显变小，说明归一化的尺度算错了；二是没有上下颠倒，说明 y 轴方向处理正确；三是不抖，说明平滑参数合适。这三条都满足，模板就可以交付给下游使用了。
最终模板文件的结构大概长这样：
{ "meta": { "source": "dance.mp4", "fps": 30.0, "width": 1920, "height": 1080, "frame_count": 1830, "keypoint_count": 33, "origin": "hip_center", "scale": "shoulder_hip_distance", "y_axis": "down", "ema_alpha": 0.4 }, "valid_ratio": 0.9634, "keypoints": [ [[0.0, 0.0], [0.12, -0.85], "..."], ["..."] ], "valid": [[true, true, "..."]] }下游拿到这份文件，只需要读meta里的约定，就知道该按什么比例还原、y 轴该不该翻转，不用再来问你要说明文档。
5. 常见问题与排查思路
5.1 高频报错速查表
下面这张表整理了在跑这条流水线时最常遇到的几类问题，包括报错、现象和对应的处理方式。实际排查的时候建议按表里的顺序从上往下走，因为很多看起来复杂的问题，根源都在最基础的环境或者路径上。
| 问题现象 | 常见原因 | 解决思路 |
|---|---|---|
ModuleNotFoundError: No module named 'cv2' | 依赖未安装或装到了别的虚拟环境 | 确认激活的是项目虚拟环境，重新执行pip install opencv-python |
打开视频失败，抛出FileNotFoundError | 路径写错或视频编码不受支持 | 先用绝对路径试，再检查视频能否用播放器正常打开 |
| 检测成功帧数为 0 | 视频解码失败或首帧就是黑屏 | 打印fps和frame_count确认是否读到数据 |
| 检测成功率低于 50% | 人物在画面中占比太小 | 裁剪画面或重新拍摄，确保人物占画面高度的一半以上 |
| 预览视频里人物上下颠倒 | 下游坐标系 y 轴向上 | 导出时对 y 取反，或在下游渲染时翻转 |
| 预览里动作幅度明显偏小 | 归一化尺度算错 | 检查躯干长度是否用了肩髋距离，确认没有用图像宽高 |
| 动作整体滞后于原视频 | alpha取值过小 | 把alpha调到 0.5 以上重新生成 |
| 骨架持续抖动 | alpha取值过大或未做平滑 | 检查smooth_landmarks和ema_smooth是否都生效 |
| 某几帧人物突然飞到画面外 | 关键点跳变未修补 | 降低min_visibility，让修补环节介入 |
| 导出 JSON 体积过大 | 未做数值压缩 | round保留 5 到 6 位即可，精度再高下游也感知不到 |
5.2 检测不到人的三类原因
第一类是画面内容问题。人物在画面里占比太小是最常见的原因，尤其是从远处拍摄的舞蹈视频，人在画面里只占很小一块，模型很难稳定地检测出全部关节。解决方式是裁剪或者重新拍摄，让人物至少占据画面高度的一半。光线过暗、逆光、背景过于杂乱也会显著降低检测率，这些都属于素材问题，调代码参数解决不了。
第二类是解码问题。有些视频的编码格式在 OpenCV 里读不出来，表现是cap.isOpened()返回 False，或者读到的帧全是黑色。遇到这种情况，先用播放器确认视频本身正常，再考虑用其他方式转一道格式。转格式之后重新跑，成功率通常能恢复正常。
第三类是代码参数问题。min_detection_confidence设得太高，模型会变得非常保守，稍微不确定就不输出结果。默认 0.5 一般够用，如果你的素材质量确实一般，可以适当降到 0.4 试试，但要接受误检率上升的代价。相反，如果素材质量很好但你想过滤掉偶发的误检，可以提高这个阈值。
5.3 抖动、漂移与动作错位
抖动和漂移是两种不同的现象，处理方式也不一样。抖动是高频的小幅波动，相邻帧之间来回跳，针对它用 EMA 或者滑动平均就能压下去。漂移是低频的缓慢偏移，比如归一化的原点随着时间慢慢移动，导致整个人物在画布里逐渐往一边跑。漂移的根源通常是髋部关键点检测不稳定，因为原点就是靠它算的。
解决漂移有个很实用的技巧：不要逐帧独立计算髋部中心，而是先对髋部中心序列做一次强平滑，再拿平滑后的中心去做归一化。因为髋部在这个动作里本来就不应该剧烈移动，如果它动了，多半是检测噪声。这个改动很小，但对稳定性的提升非常明显。
动作错位指的是模板和原视频的时间对不上，通常表现为骨架的动作比真人慢半拍。除了alpha过大导致的滞后之外，还有一种可能是帧率不匹配。如果你的视频是可变帧率的，OpenCV 读出来的fps可能不准，用这个值去驱动渲染，时间轴就会歪。遇到这种情况，建议先统一转成固定帧率再处理。
6. 最佳实践与工程建议
6.1 素材来源与授权边界
这一条必须放在最前面说，因为它涉及法律风险。使用他人的舞蹈视频作为素材来生成模板，一定要确认授权情况。即便是公开平台上可以观看的视频，也不等于可以随意二次加工和分发。如果只是自己学习研究，风险相对可控；如果要做成产品、要商用、要公开发布，必须拿到明确授权，或者使用自己拍摄的素材、明确标注可商用的素材。
工程上的建议是把素材来源信息也写进模板的元数据里。不要只写个文件名，要写清楚来源、获取时间、授权方式。将来项目做大了需要做合规审查，这些信息能帮你快速定位哪些素材可以用、哪些必须替换。很多团队一开始图省事不记录，等到要上线的时候才发现根本追溯不了，只能全部重做。
另外，处理含有人脸的素材时要注意隐私。虽然本文的处理流程不涉及人脸识别，但原始视频里的人是真实存在的。对外分享模板时，建议只分享骨骼数据，不要附带原始视频帧。骨骼数据本身已经去掉了绝大部分身份信息，风险要低得多。
6.2 配置管理与参数治理
参数不要散落在代码里。前面提到的min_visibility、ema_alpha、model_complexity、max_gap这几个值，都应该集中在一份配置文件里管理。这样做的好处是：换素材的时候只改配置不动代码，出问题的时候能快速对比不同参数的结果，团队协作时大家用的是同一套参数。
# 文件路径：config/pipeline.yaml input_video: data/raw/dance.mp4 output_pose: data/processed/pose.json output_template: data/template/dance.json output_preview: data/processed/preview.mp4 pose: model_complexity: 1 min_detection_confidence: 0.5 min_tracking_confidence: 0.5 normalize: min_visibility: 0.30 smooth: ema_alpha: 0.40 max_gap: 15 render: canvas: 720 line_width: 3配置文件管理还有一个容易被忽略的点：版本记录。参数调整往往是一个反复试错的过程，今天调好了明天又觉得不对想调回去，如果没有记录，根本不知道上次用的是什么。建议每次调整参数都写一行注释说明原因，比如“# 2024-xx 这段素材偏暗，可见度普遍低，阈值从 0.3 降到 0.25”。
6.3 性能优化：批处理与降采样
处理长视频的时候性能会成为瓶颈。一段 5 分钟、30 帧每秒的视频有 9000 帧，逐帧跑姿态估计在普通 CPU 上可能要十几分钟。有几个优化方向可以按需采用。
第一个方向是降采样。如果你的下游应用只需要 15 帧每秒的动作数据，那就没必要按 30 帧处理，隔帧取一帧即可，处理时间直接省一半。实现上在读取循环里加一个计数器，跳过奇数帧就行。需要注意的是降采样之后要把fps元数据改成实际值，否则下游播放速度会不对。
第二个方向是降分辨率。姿态估计的精度对分辨率不是特别敏感，把 1080p 缩到 720p 处理，速度能提升不少，精度损失通常在可接受范围内。但不要缩得太狠，因为关键点的相对位置精度会跟着下降。
第三个方向是模型复杂度。model_complexity从 1 降到 0，速度会有明显提升，代价是关键点精度略低，极端姿势下更容易出错。这个取舍要结合你的用途来定，动作比对场景对精度要求高，宁慢勿错；只是做个预览的话，用 0 完全够。
6.4 生产落地要关注的几个点
如果这套流水线不只是自己用，而是要接进一个更大的系统，有几个地方需要额外注意。第一是错误处理，不要把异常直接抛到外面，要区分“素材问题”和“代码问题”，分别给出明确的错误码和提示信息。用户上传一个根本没有人物的视频，你返回一个栈溢出信息，体验非常差。
第二是产物校验。模板生成之后，最好自动做一次健康检查：有效点比例是否高于某个阈值、动作幅度是否在合理范围内、有没有异常的跳变帧。检查不通过的模板直接标记为不可用，不要让它流到下游，否则问题会在更靠后的环节暴露，排查成本高得多。
第三是存储和传输。骨骼数据虽然比视频小很多，但一段长视频的模板文件也不小。如果模板数量多，建议做数值精度压缩和字段名缩写，能省下可观的存储空间。传输的时候如果走 HTTP，记得开启 gzip 压缩，JSON 的压缩率通常很高。
第四是可复现性。同样的输入素材和同样的参数，应该产出同样的模板。这看起来是理所当然的，但如果你的流水线里混入了随机性或者依赖了某些不稳定的外部状态，就可能做不到。建议在模板的元数据里记录一版参数快照，将来出问题能精确回溯。
7. 学习路线与下一步方向
7.1 从骨骼模板到真实渲染
跑通本文的流水线之后，你手上有了一个结构化的骨骼模板，但它还只是一个火柴人。下一步最自然的延伸是把它接到真实的渲染上。如果做 2D，可以把模板的点位映射到一张切好的角色立绘上，用旋转和位移驱动各个部件，这就是俗称的“切图动画”。实现的关键是建立模板关键点和角色部件之间的绑定关系，比如左手腕关键点绑定左手部件。
如果做 3D，就需要做重定向。你手上的模板是 2D 的关键点，而 3D 角色有完整的骨骼层级和旋转信息，中间要做一步映射。这个环节的难点在于如何处理深度缺失：2D 模板没有可靠的 z 信息，重定向到 3D 之后手臂可能穿模，或者前后关系混乱。常见的做法是根据姿态先验做推测，比如根据肩膀和肘部的相对位置判断手臂朝向，但这需要额外的规则或模型。
7.2 继续深入的方向
第一个方向是把 2D 升级到 3D 姿态估计。思路上文的归一化和平滑逻辑是通用的，主要区别在于要多处理一个维度和骨骼旋转。如果你已经理解了本文的坐标系处理，迁移到 3D 不会太困难，只是需要额外注意旋转的表示方式（四元数还是欧拉角）以及不同坐标系的转换。
第二个方向是做动作检索。把一批舞蹈模板都生成出来之后，可以做相似度搜索：把每段动作切成固定长度的窗口，计算特征向量，建一个索引，然后按查询片段找出最相似的结果。这块可以结合现成的向量检索方案，实现难度不高，但对内容管理类应用价值很大。
第三个方向是做动作质量评估。在舞蹈教学场景里，判断学员动作和标准动作差多少是核心需求。本文的模板可以直接拿来做逐帧对比，但直接算欧氏距离效果不好，因为节奏上的微小偏差会让距离暴涨。更合适的做法是做动态时间规整，允许时间轴上的弹性对齐，这样评出来的分数才符合人的直觉。
想把这条链路真正用起来，建议先拿一段自己熟悉的短素材完整跑一遍，把每个中间产物都打开看看。很多时候问题不是出在你以为的那一步，而是前面某一步的产物就已经不对了。等你能一眼看出中间 JSON 哪里有问题，这套东西才算真正掌握。后面再换素材、换角色、换渲染目标，无非是同一套流程换个出口而已。
