跑姿分析（千悦体育 AI 跑姿初筛）
> 出品方：千悦体育（QIANYUE SPORTS）
> 方法论来源：千悦体育《跑姿分析标准》五项指标；角度代理量取自《千悦体育 AI 跑姿分析指标说明文档》。
> 判读手法来源：千悦体育《跑姿分析》系列教程（第一期 / 第二期 / 第九期 / 第十期 / 第十一期 / 第十二期 / 第十三期 / 第十四期）＋培训视频 27–31 期（总教练 王贝克）。
> 版权：保留所有权利，详见 LICENSE。可自由安装使用与原样分享，但请保留署名，不得改名换品牌发布或用于商业销售。
版本沿革
| 版本 | 主线 |
|---|---|
| v2.0.0 | 结构整理：把「历史补丁堆叠」改写成一条线性管线（体检 → 尺度 → 事件 → 判读 → 目视 → 交付）；机器通道 5 脚本合 1 条命令（126 s 视频 159 s → 32 s）；新增窗口级尺度分簇、跨线带宽保护、左右臂自洽性。 |
| v2.1.0 | 口径校正：并入第十四期判据（左右均衡为首查项、单轴＝轴上下起伏、夹角与位置分离），并修正三处机器侧误用——单帧退化误报、取帧时刻不记录、足跟落地膝角当真值。详见 §5.4。 |
| v2.2.0 | 判据定义补强：并入培训视频 27–31 期（总教练王贝克）的采集规范、触地帧双判据、力向三分、支点同侧取点、刹车效应根因链、假前倾成因、摆臂耸肩判据；屈膝带口径差异仅登记备查（判定与报告口径均保持 150–160° / >165° 不变，留待大版本更新时再决策）。详见 §5.6。 |
v2.1.0 的三处修正（一句话版）
| 修正 | 纠了什么 |
|---|---|
| 单帧退化误报 | 「两踝高差 < 3%」只对窗口统计成立；单帧套用会把着地瞬间误判成退化（相位假象）→ 单帧改用关键点置信度。 |
| 取帧时刻 | 同一屈膝窗 1.6 s 内膝角可差 9° → 取帧必须紧贴 APP 数值首稳帧，且必须记录时刻。 |
| 足跟落地膝角 | 足跟落地素材机器膝角系统性偏大 10°+，且与像素尺度无关（559 px「良好档」素材照样偏）→ 只作方向参考。 |
v2.2.0 的三处补充（一句话版）
| 补充 | 要点 |
|---|---|
| 采集规范 | 采样帧须在跑者位于画面正中间时取；起段（斜前方）与末段（斜后方）都有系统性偏差。 |
| 触地帧双判据 | ① 鞋底阴影完全消失＝真正触地；② 触地后脚不再向前位移＝踩实承重。阴影还在、或仍有前移 → 都是排除帧。 |
| 屈膝口径锁定 | 总教练培训讲 160–170° 合理 / >170° 不足，与本文档 150–160° / >165° 不同 → 判定与报告口径一律不变，差异仅登记备查，留待大版本更新时再决策。 |
0. 三十秒上手
# ① 机器复核（可选但强烈建议）：出数值底稿 stats.md / stats.json
python scripts/pose_measure.py <跑步视频> # 自动选段
python scripts/pose_measure.py <视频> --win "着地:8:24;摆臂:62:86" # 指定环节窗
python scripts/pose_readings.py <视频> 32.4 75.6 # 指定时刻的单帧读数
# ② 生成报告 → ③ 出图（出图是强制步骤）→ ④ 核验
python scripts/build_report_template.py <素材目录> [输出.html]
node scripts/export_report_images.js <报告.html> <输出目录> --prefix 跑姿报告 --width 750 --lang zh
python scripts/check_report_images.py <输出目录> # 退出码 0 才算通过
| 产出 | 说明 |
|---|---|
pose_out/stats.md |
教练侧数值底稿：尺度与可信度、五项指标读数（带不确定度）、置信度摘要 |
<报告>.html |
交给客户的中文单语 · 手机大字版报告 |
<前缀>_zh_长图.png + <前缀>_zh_01.png… |
整页长图 + 章节分片，可直接发布 |
1. 十四条铁律（先读这十四条，其余都是细节）
| # | 铁律 | 为什么 |
|---|---|---|
| 1 | 凡是角度，必须同时给出不确定度 u；禁止裸数字 | 142 px 跑者的小腿前倾角 u = ±6–9°，带宽才 6° —— 裸数字是伪精度 |
| 2 | 先过尺度门槛，再谈度数 | 骨架身高 < 200 px 时任何角度都不可用 |
| 3 | 窗口统计必须先做尺度分簇 | 同窗内常混入特写/远景两种尺度，整窗中位数是混合值（实测比值低至 0.19） |
| 4 | 跨阈值判定必须先做带宽保护 | |读数−阈值| < 2u 时只能判「临界」，不能判合格/不合格 |
| 5 | 支撑腿 = 两踝中更低的那条（标签无关） | 侧面视角下左右腿标签逐帧翻转，「按腿」的时间序列全是假的 |
| 6 | 躯干角必须先按朝向归正 | 朝左跑与朝右跑的原始符号相反，不归正会把前倾判成后仰 |
| 7 | 耳/鼻不取模型读数 | APP 会把工具线与角度数值叠加在跑者身上，耳点被污染（实测距鼻 50–58 px） |
| 8 | 「两踝竖直高差 < 身高 3%」只用于窗口统计 | 整窗含摆动相，高差才反映真实抬腿；单帧（尤其着地瞬间）两脚本就常同处低位，套用会误判退化。置信度高 ≠ 姿态对 |
| 9 | 只描述现象，不给处方式结论 | 措辞红线见 §6；不得出现命令句 |
| 10 | 报告不展示判定标准条文 | 150–160° / <10° / ≤90° 等阈值只用于内部分级，不出现在客户报告里 |
| 11 | 每次取帧必须记录并报告时刻 | 13.mp4 同一屈膝窗 1.6 s（43 帧）内膝角 152.2° → 161.0°，差 9°。读数打架时先核对取帧，再怀疑模型 |
| 12 | 足跟落地素材的机器膝角只作方向参考 | 足跟触地时踝点被鞋帮/裤脚抬高 → 小腿段变短 → 膝角系统性偏大 10°+，且与像素尺度无关（559 px「良好档」素材照样偏，实测 165.1° vs 教程 154°） |
| 13 | 取帧必须取「跑者位于画面正中间」的那些帧 | 跑者刚进画面时是斜前方、快出画时是斜后方，透视会带来系统性偏差；画面正中（及其下一帧）才是全片最准的两次数据 |
| 14 | 触地帧用「阴影消失 + 不再前移」双判据定位 | 鞋底阴影还在＝脚仍悬空；触地后仍有向前位移＝还没踩实。两个条件都满足的那一帧才是真正触地承重帧 |
2. 何时触发
触发：跑姿分析 / 跑姿评估 / 跑姿初筛 / 跑步动作分析 / 步态分析 / 看我跑姿 /
帮我分析这段跑步视频；或出现指标名（着地部位、屈膝角度、支撑膝角、落脚点、躯干前倾角、摆臂角）；
或上传跑步视频、关键帧截图并问动作问题（「我落地是不是太靠前」「我摆臂紧不紧」）。
不触发：
- 与跑步无关的运动（游泳、骑行、力量训练动作纠错）→ 走通用分析；
- 医疗诊断需求（膝痛病因、韧带损伤）→ 明确告知本技能不做诊断，转医疗建议；
- 单纯问「跑步有什么好处」这类科普 → 正常问答。
3. 输入要求与前置检查
| 检查项 | 要求 | 不达标时的处理 |
|---|---|---|
| 素材类型 | 跑步视频（优先）或连续关键帧图片 | 只有单张静态图 → 只能做「单帧姿态观察」，无法给周期类结论 |
| 视频时长 | 建议 15–30 秒，至少覆盖 1 个完整跑步周期 | < 5 秒 → 必须标注「样本量不足，仅作初步动作识别」 |
| 拍摄角度 | 正侧面（90°）最佳，允许正/背面辅助 | 斜侧 > 30° 或俯拍 → 角度类指标可信度下降，须在复核限制中说明 |
| 画面条件 | 全身入镜（含脚与头）、光线充足、地面平整、无遮挡 | 下肢被裁切 → 无法算膝角/落脚点，只能建议重拍 |
| 分辨率 | 建议 ≥ 720p，帧率 ≥ 30 fps | 模糊/低帧率 → 关键帧识别可能失败，标注识别置信度 |
抽帧一律用 OpenCV（cv2）。本环境 PATH 中通常没有 ffmpeg；
❌ mediapipe / ultralytics 在 Python 3.13 无 wheel，不要尝试（pip 会长时间挂起）。
⚠️ 不要一次性把整段视频读进内存——179 s / 544×960 素材会到 ~7 GB。
逐帧 grab() 顺序走帧，需要哪帧才 retrieve()。
⚠️ 随机 cap.set(CAP_PROP_POS_FRAMES, i) 每帧跳读的代价是顺序解码的 16 倍（27.8 vs 445.7 帧/s）。
4. 流程（六步，按顺序做）
Step 0 — 素材体检
确认分辨率 / 帧率 / 时长 / 亮度，并判断走「观察型报告」还是「定量+观察型报告」。
亮度均值偏低（< 80）或跑者占画面高 < 22% 时，直接预期下肢数字不可用。
Step 1 — 尺度体检与分簇（决定「能不能给数字」）
- 量像素尺度：用骨架关键点算身高（鼻→踝），不要用背景差分包围盒
（包围盒含运动模糊与地面阴影，系统性高估约 20%：实测同一段包围盒 176 px、骨架仅 142 px）。 - 第一道闸 — 尺度：≥400 px 良好／200–400 px 一般（给数值但必须标误差）／<200 px 禁止给数值。
- 第二道闸 — 不确定度 vs 带宽：
u = atan(2·eps / L)（eps 取 2–3 px），
r = u / 带宽；r ≤ 1/3 可给数值（须带 ±u），1/3–1/2 只给区间，> 1/2 禁止数值。 - 窗口级尺度分簇（v2.0.0 新增）：同窗内
min(身高)/max(身高) < 0.55→ 判尺度混叠，
禁用整窗中位数，按簇重算，只取达标主簇（阈值max(200 px, 身高P10)），并记录剔除帧数。 - 下肢关键点退化快筛（标签无关，仅用于窗口统计）：窗口内
两踝竖直高差 ÷ 身高 < 3%
→ 屈膝 / 落脚点 / 着地部位全部不判读。
⚠️ 不要把这个判据套到单帧上（尤其着地瞬间）——那时两脚本就同在低位，比值天然小，
是相位假象而非关键点崩坏；单帧改用关键点置信度（c_ank/c_elb/c_wri）。 - 第三道闸 — 左右腿标签一致性：冲突率高时撤掉分侧结论，只给合并范围 + 倾向。
- 「核心窗」单独复核（v2.1.0 强调）：核心窗是最容易踩闸的窗口——实测 12/14 两期该窗
身高只有 145 / 187 px（偏低档）、剔除率 100%，而同一管线其他四窗都是 480–640 px。
核心窗尺度取决于 APP 那段演示镜头的推拉节奏，不可跨期沿用秒数；不达标时不得以
「模型读不出」结案，改用耳髋角目视等效（教程口径）并在报告中写明该窗为目视结论。
> 完整判据、实测锚点与反例（为什么不能用 corr(knL, knR) 判退化、为什么送模端补救无效）
> 见 references/pipeline.md §三。
Step 2 — 事件定位（触地帧）
先定「在哪取」（v2.2.0）：跑者位于画面正中间（及其下一帧）的两步是全片最准的两次数据。
画面起段跑者处于斜前方、末段快出画时处于斜后方，透视偏差会污染角度 → 这两段不取帧（铁律 13）。
触地瞬间才是教程口径的取帧点。机器侧按「支撑踝 y 的局部极大值（踝点最低）+ 横移最小」定位触地帧候选，
再在候选 ±0.12 s 内逐帧精算。不要去取「门槛最高的那些帧」（那会混入蹬地帧）。
触地帧双判据（v2.2.0，铁律 14）：肉眼复核时用两条判据确认「真正触地承重」——
① 放大看鞋底阴影：阴影完全消失才是触地，阴影还在＝脚仍悬空；
② 看位移：触地后脚不再向前移动才算踩实，仍有小幅前移＝这一帧还没着地。
（这两条同时是「排除帧」的显式说法，用来否掉相邻的悬空帧与未踩实帧。）
取帧必须记录时刻（v2.1.0 新增，铁律 11）：与教程 APP 读数比对时，
取帧点须紧贴 APP 数值首次稳定显示的那一帧（下称「首稳帧」；教程侧规则：以教练口播确认的值为准，
APP 拖动过程中的中间值不作数），并在底稿里写明 t = xx.x s。
实测 13.mp4 屈膝窗内 t=38.4 s 得 152.2°、t=40.0 s 得 161.0°——
1.6 s 之差就是 9°。两次读数不一致时，先核对取帧时刻，再怀疑模型。
Step 3 — 五项指标判读（核心表）
> 判定标准出处：references/standards.md。主口径＝《跑姿分析标准》，判定以此为准；
> 代理量（角度）仅作内部可测量化。
| # | 展示名 | 判据 | 标准（主口径） | 怎么读 | 机器能不能测 |
|---|---|---|---|---|---|
| 一 | 着地部位 | 触地首帧的承重区域；并看足轴向（外八）与左右脚是否一致；并说明施力方向 | 前脚掌 / 全脚掌 / 接近全脚掌 / 后脚掌；足轴向正常 / 偏外八；左右一致 / 不均衡。力向三分：前脚掌、全脚掌＝由上向下（基本垂直）；脚跟着地＝由后向前 | 只描述触地类型，不直接评价好坏；若为脚跟着地须点明力向由后向前、致伤几率在三种里最高 | ❌ 模型无足部朝向输出 → 目视 |
| 二 | 屈膝角度 | 着地瞬间支撑腿膝角 ∠髋-膝-踝 | 约 150～160°；> 165° 屈膝不足；< 150° 过分屈膝。⚠️ 总教练培训另讲 160–170°／>170° 不足 → 本档锁定 150–160° / >165° 不变，差异仅登记备查（见 §5.6） | 偏小=屈膝多；偏大=腿偏直 | ✅ 可测（须过三道闸；跨 165° 线不作硬判据）。⚠️ 足跟落地素材机器值系统性偏大 10°+ → 只作方向参考；同一窗内膝角逐帧变化可达 9° → 必须记取帧时刻 |
| 三 | 落脚点的合理性 | 着地点（着地部位最后端）距同侧股骨大转子正下方的距离，与自身一个脚长比较 | 小于一个脚长=合理；大于=不合理；施力方向由后向前＝刹车效应、不合理 | 落在髋正下方一带更稳；落在前方过多=跨步偏大。根因链：步幅若靠前摆小腿＋锁死伸膝而非屈髋抬大腿获得 → 落脚点前移 → 刹车效应。重心取同侧大转子（右脚着地取右侧髋） | ✅ foot_len = 支撑踝−髋中 ÷ 一个脚长 |
| 四 | 核心的表现力 | 轴心盒子（躯干）的前倾角；另须判「假前倾／坐着跑」「身体后仰」「含胸圆肩／撅臀」 | 躯干挺拔、垂直于地面做平行前移，前倾 < 10° 为好；> 10° 过分前倾；后仰轻度即判「过分后仰」 | 太小=直立僵直；太大=前倾过多；假前倾的成因是「屈髋过多」（髋屈 > 伸髋），挺胸做得好也可能前倾；头前伸而肩在位＝假前倾（坐着跑） | ✅ 前倾角可测（须先归正朝向）；❌ 骨盆倾角/含胸量不到 → 目视。⚠️ 本项用核心窗，而核心窗最易踩闸（实测 145/187 px）→ 先核验尺度，不达标改耳髋角目视 |
| 五 | 摆臂的合理性 | 肘关节夹角 + 前摆/后摆位置 + 单轴原则 + 是否耸肩 | 前摆肘不超躯干、后摆手不超躯干；前摆与后摆全程肘角 ≤ 90°；只以肩关节为轴（单轴）、左右摆幅大致对称、肘不过身体中线；双肩放松下沉、手臂紧贴身体、腕微攥拳 | 看自然、对称、不过度紧张；必须提到肘关节；耸肩判据＝耳垂到肩峰的距离是否明显缩短 | ✅ 肘角可测（须带 u）；前后越界用 wrist_off/elbow_off 复核。⚠️ 「夹角」与「位置」是两个独立维度，必须分别给结论——夹角合格 ≠ 摆臂合理（14 期 86° 合格但前露肘；13 期 77–79° 合格但超中线）。肘角取中位数，极值帧可能来自关键点崩坏（14 期 t=66 s elbowL=27.0°、c_wri=0.60）不作结论 |
Step 4 — 关键帧画面复核（不可省略）
每个超出范围的指标都要回看关键帧，用画面描述佐证：
- 落脚点 → 脚是否明显落在身体前方（首选复核点）；
- 膝角 → 支撑瞬间膝盖是否明显屈曲或锁死；
- 躯干 → 是否过度前倾、后仰、含胸圆肩；
- 摆臂 → 肘是否自然弯曲、双手是否越过身体中线。
模型量不到的项，一律在这一步目视判读，见 §5.3。
Step 5 — 出报告 → 出图 → 核验
AI 跑姿辅助分析（中文单语 · 手机大字版 · 结论化判读）
├─ ① 学员可能存在的问题 （**第一部分**，直述，读者一眼看到重点）
├─ ② 关键帧动作观察 （关键帧拼图 + 画面说明）
├─ ③ 五项跑姿指标 （一~五：本次观察结论 + 一句说明；**不列判定标准条文**）
├─ ④ 训练建议 （3–5 条，方向性、可落地、分项对应）
├─ ⑤ 复核限制 （正向表述）
└─ 免责声明 （固定文本）
报告形态要求（v1.6.1 起）：删除几何辅助示意、机器核验与尺度判定、成套训练计划、英文版本；
指标一律结论化判读（基本合理 / 建议关注 / 中性描述），数值作为「画面估算」给出；
全篇只在「复核限制」里一次性说明估算性质，不在每张卡上重复「未定量／无法评估」。
训练建议：按「摆臂 / 躯干前倾 / 落地缓冲 / 重拍复核」等分类，每条对应一个本次可观察的项目，
不允许无依据给建议；不再出具「组数×次数」处方。
出图必守的 4 条（报告为中文单语，只出一套中文图）：
- 按报告实际语言量边界。现报告为中文单语；若未来恢复双语，须每种语言各自量一遍章节边界
（中英换行不同，整页高度可差 700–1500 px，共用边界会切坏另一种语言）。 - 分片只能切在
<h2>章节边界上，绝不切断表格、图注或卡片；首片从y=0起。 - 静态图里隐藏语言切换按钮（脚本已注入 CSS）。
- 出图后必须回读核验：
python scripts/check_report_images.py <输出目录>，退出码 0 才算通过。
> ⚠️ 整页长图有纹理上限：Chromium 单张图约 16384 px。高(px) × 倍率 超过安全值（脚本取 16000）
> 时会自动降倍率重出并打印提示。报告越长越容易撞到这条，不要手动硬撑 2x。
5. 准确性改动史（v2.0.0 → v2.2.0）
> 5.1–5.3 为 v2.0.0 引入的规则（仍有效）；5.4–5.5 为 v2.1.0 新增；5.6 为 v2.2.0 新增。
5.1 新增判据（v2.0.0）
| 判据 | 规则 | 实测依据 |
|---|---|---|
| 窗口级尺度分簇 | 同窗 min(身高)/max(身高) < 0.55 → 判混叠，禁用整窗中位数 |
11.mp4 着地窗 0.19／摆臂窗 0.30；12.mp4 摆臂窗 0.21（67% 特写 + 32% 全景）；回检 6.mp4 着地窗 0.24、10.mp4 屈膝窗 0.42 |
| 跨线阈值带宽保护 | \|读数 − 阈值\| < 2u → 判「临界」，不判合格/不合格 |
12.mp4 摆臂 u=2.5°：机器 96.1–98.5 可判超 90，但教程 85° 距 90 仅 5°≈2u → 只能写「临界争议」 |
| 左右臂自洽性检查 | 同帧两臂肘角差 > 2u → 该帧肘角只报范围 | 11.mp4 t=75.6s：elbowL 143.2 / elbowR 107.2，差 36° ≫ 2u=8.2°（但两臂都 >90，方向性结论仍成立） |
| 支点取点随承重区域变化 | 足跟落地取最后端；全脚掌落地取中心；前脚掌取前端 | 第十三期教程原话（v1.9.0 统一写「最后端」→ 本次修正） |
| 「超身体中线」分两视角 | 侧面 = 前后越界（前摆肘超躯干前缘 / 后摆手超躯干后缘）；正面 = 左右越界 | 第十三期在侧面视角即判「向前摆臂幅度过大、超过身体中线」（v1.9.0 原写「只在正面可判」→ 本次放宽） |
| 持物时的摆臂处置 | 位置类（前露肘/后露手）照常判并注明干扰源；夹角类数值降级为参考 | 第十二期：持物 → 仍判「向后漏手」+ 建议空手跑（v1.9.0 原写「直接判无法评估」→ 本次收窄） |
| 教程读数取用规则 | 以教练口播确认的数值为准，APP 拖动过程中刷新的中间值不作数 | 第十一期实测 t=31.2s 屏显 147 → t=32.4s 起稳定 161，教练采用 161° |
| 朝向归正（承 v1.9.0） | 归正角 = 原始角 × FORWARD（朝左 −1 / 朝右 +1）；归正后正值 = 前倾 | 朝左素材原始负值代表前倾，与朝右素材符号相同含义相反 |
5.2 修正的一条旧结论（v2.0.0）
v1.9.0 把「6.mp4 教程 164° vs 机器窗口中位 152.9°」全部归因于「单帧 ≠ 窗口」。
按尺度簇重算后：大簇（≈485 px，n=14）155.2° / 小簇（≈172 px，n=48）151.2° ——
其中约 2.3° 来自尺度混叠，其余才来自取帧时刻不同。两条原因都要写。
5.3 模型量不到、必须目视的项（清单）
外八着地 / 足轴向 · 着地部位档位 · 撅臀（骨盆前倾）· 含胸圆肩 · 头部前伸的具体角度 ·
左右脚落地是否平衡 · 前后摆幅的越界程度。
> 理由与替代做法见 references/tutorial_method.md 第六、七节。
5.4 v2.1.0 新增与修正（第十四期教程 + 三期复核）
a) 并入第十四期教程的 4 条判据
| 判据 | 规则 | 出处 |
|---|---|---|
| 左右均衡是明确的首查项 | 第十四期把「左右脚落地是否均衡」放在工序第一步，用双屏对比（左右脚后跟分别取帧对照）判定 | 第十四期（房教练） |
| 单轴原则的可操作判法 | 教程首次给出可操作说法：「轴有一点上下起伏 → 需改善」——即在侧面视角看肘/腕轨迹的竖直抖动，而非只看夹角 | 第十四期 |
| 夹角合格 ≠ 摆臂合理 | 同一期里夹角 86°（合格）同时判「前摆较大 → 前露肘（有待改善）」→ 两个维度必须分开 | 第十四期 |
| 五项工序次序不固定 | 「屈膝 / 支点」的先后逐期可变，不要按第一期的固定 1→5 顺序硬套 | 第十二 / 十三 / 十四期对照 |
b) 修正三处机器侧误用（详见 §1 铁律 8 / 11 / 12）
| 修正 | 触发实测 | 处置 |
|---|---|---|
| 单帧退化误报 | 14.mp4 着地瞬间 t=28.8 s 两踝高差 2.7% 被判「退化」，但该帧踝置信度 0.95 | 该判据只用于窗口统计；单帧改用 c_ank/c_elb/c_wri |
| 取帧时刻未记录 | 13.mp4 同屈膝窗 1.6 s 内 152.2° → 161.0°（差 9°） | 取帧紧贴 APP 首稳帧，底稿必须写 t = xx.x s |
| 足跟落地膝角当真值 | 14.mp4（720×1280 原生、身高 559 px「良好档」）机器 165.1° vs 教程 154°，差 11.1° 而 u 仅 ±0.7° | 足跟落地素材膝角只作方向参考，复核限制里必须说明 |
c) 摆臂肘角取中位数，极值帧不作结论
14.mp4 t=66.0 s（前摆最大）elbowL = 27.0°、c_wri = 0.60（关键点崩坏）。
窗口统计已出 med/IQR，极值只作提示。
5.5 三期复核的尺度对照（v2.1.0 实测锚点）
| 期 | 素材 | 着地 | 屈膝 | 支点 | 核心 | 摆臂 | 备注 |
|---|---|---|---|---|---|---|---|
| 12 | 12.mp4 | 495 px | 496 px | 484 px | 145 px · LOW | 634 px · 混叠 0.22 | 核心窗 100% 剔除 |
| 13 | 13.mp4 | 290 px | 282 px | 289 px | 222 px | 214 px | 唯一五窗全 ok、无混叠 |
| 14 | 14.mp4 | 565 px | 558 px | 548 px | 187 px · LOW | 487 px · 混叠 0.33 | 屈膝窗虽 558 px 但两踝高差 2.0% → 退化 |
> 读法：13 期素材最"干净"，却仍在摆臂上差教程 36–45° → 说明摆臂的口径差异
> 来自「教程量肘夹角 vs 模型量整条手臂链」的定义不同，不是尺度问题（见 references/tutorial_method.md §三·4）。
5.6 v2.2.0 新增（培训视频 27–31 期 · 总教练王贝克）
a) 补入的判据与操作法
| 判据 | 规则 | 出处 |
|---|---|---|
| 采集规范 | 取帧须在跑者位于画面正中间时；起段斜前方、末段斜后方有系统性偏差 | 27 期 |
| 触地帧双判据 | 鞋底阴影消失＝触地；触地后不再前移＝踩实 | 27 期 |
| 力向三分 | 前脚掌／全脚掌＝由上向下（垂直）；脚跟着地＝由后向前（致伤几率三种里最高，因地面回弹为反向力） | 27 期 |
| 支点取同侧大转子 | 重心取同侧股骨大转子正下方（右脚着地取右侧髋） | 29 期 |
| 刹车效应根因链 | 步幅靠前摆小腿＋锁死伸膝而非屈髋抬腿获得 → 落脚点前移 → 支点不合理 → 刹车效应 | 29 期 |
| 假前倾成因 | 屈髋过多（髋屈 > 伸髋）；挺胸可以做得很好但仍前倾，含胸圆肩不是必要成分 | 30 期 |
| 后仰幅度口径 | 只要躯干整体出现轻度后仰，即判「过分后仰」 | 30 期 |
| 摆臂耸肩判据 | 耳垂到肩峰的距离明显缩短＝耸肩 | 31 期 |
b) 屈膝带口径差异——仅登记，不改判定（锁定 150–160°）
| 来源 | 合理带 | 不足线 |
|---|---|---|
| 本档主口径（《跑姿分析标准》docx ＋ 云教练 APP 屏显）＋既有七期教程实测 151–158° | 150–160° | > 165° |
| 培训视频 28 期（总教练王贝克） | 160–170° | > 170° |
- 判定与报告口径一律保持不变（锁定 150–160° / >165°）——培训视频不是替换口径的依据，差异只登记。
- 留待「大版本更新」时再决定是否调整；届时须向客户明确提出选项再做决定。
- 机器读数与两侧口径均存在 ±10–15° 级差异（28 期实测：屏显 172° / 167° vs 机器 162.2° / 154.8°），
故任何情况下都不把机器膝角当跨 165° 线的硬判据（承铁律 4、12）。
6. 措辞红线（强制）
| 禁止 | 应写 |
|---|---|
| 模型认为你跑姿不好 | 系统初筛提示某项需结合画面复核 |
| 你的跑姿有 X% 问题 | 该项超出参考范围，建议教练复核 |
| 命令句（必须做…） | 可尝试… / 建议在教练指导下… |
| 自定义百分比、把内部辅助量当行业标准 | 只输出角度值与参考范围 |
| 未定量 / 无法评估（逐条刷屏） | 基本合理 / 建议关注 / 中性描述；估算性质在复核限制说一次 |
| 「单一侧面视角，无法评估左右对称」 | 正向拍摄建议（不向客户暴露该限制） |
| 在报告里列出判定标准条文 | 报告只给结论；标准留在教练侧文档 |
| 医疗诊断口吻 | 本报告不构成医疗诊断 |
每项指标必须配关键帧截图 + 一句解释。摆臂部分必须提到肘关节。
内部 vs 对外分开：内部按三道闸严格判定、绝不伪造数字；对外只把「测量信度」翻译成
客户能用的动作结论。真的无法判读时（遮挡、持物且关键点崩），对外写「本次受画面遮挡，暂不判读」
或直接省略该项，不得凭空给出正向结论。
7. 交付前自查清单
尺度与可信度
- [ ] 骨架像素身高是否已量（而非用包围盒）？是否过了第一道闸？
- [ ] 每个角度是否都带不确定度 u？是否算过 r = u/带宽？
- [ ] 窗口统计前是否做了尺度分簇？混叠窗口是否换用主簇、并写明剔除帧数？
- [ ] 跨阈值结论是否过了带宽保护（|读数−阈值| ≥ 2u 才给合格/不合格）？
- [ ] 两踝竖直高差/身高 < 3% 时，下肢三项是否已停止判读？（只对窗口判；单帧不得套用该判据）
- [ ] 核心窗是否单独核验过尺度？不达标时是否改用耳髋角目视并写明？（而非以「模型读不出」结案）
- [ ] 躯干角是否已按朝向归正（朝左 −1 / 朝右 +1）？
- [ ] 是否没有取耳/鼻的模型读数？（只作目视提示）
判读完整性
- [ ] 四 核心项是否分别判了「前倾角」与「有无假前倾（坐着跑）／含胸圆肩／撅臀／身体后仰」？
- [ ] 三 落脚点是否按着地部位选了支点取点（足跟最后端 / 全脚掌中心 / 前脚掌前端）？
- [ ] 一 着地部位与足轴向、左右脚落地是否均衡（首查项 + 双屏对比）是否已目视并写明「模型无此输出」？
- [ ] 五 摆臂是否提到了肘关节？前不露肘 / 后不露手 / 单轴原则（有无上下起伏）是否都查了？
- [ ] 五 摆臂是否分别给了「夹角」与「位置」两条结论？（不得因夹角合格就写"摆臂合理"）
- [ ] 摆臂肘角是否取中位数？是否没有把极值帧（c_wri < 0.7）当结论？
- [ ] 与教程 APP 读数比对时，是否记录了取帧时刻（t = xx.x s）并贴近 APP 首稳帧？
- [ ] 足跟落地素材的膝角是否只作方向参考，且已在复核限制里说明？
- [ ] 画面若有 APP／字幕／工具叠加，是否已放弃耳/鼻读数、改由目视？（含「NN 号区」标记的识别）
- [ ] 持物素材是否按「位置类照判、夹角降级」处理，并写明干扰源？
- [ ] 取帧时跑者是否位于画面正中间？（起段斜前方、末段斜后方不取帧）
- [ ] 触地帧是否用「阴影消失 + 不再前移」两条判据确认过？
- [ ] 三 落脚点的重心是否取了同侧股骨大转子？着地部位最后端是否按足跟/全掌/前掌条件化取点？
- [ ] 一 着地部位若为脚跟着地，是否点明其力向由后向前与致伤风险？（前掌／全掌为垂直）
- [ ] 四 核心是否按「轴心盒子」口径判了垂直度，并写明假前倾的屈髋过多成因？
- [ ] 五 摆臂是否查了耸肩（耳垂–肩峰距明显缩短）？
交付
- [ ] 报告是否未展示判定标准条文？（不出现 150–160°／<10°／≤90° 等阈值列表）
- [ ] 报告第一部分是否为「学员可能存在的问题」？
- [ ] 报告模板改写时，HTML 构建部分的硬编码文案（如关键帧说明「未见持物或明显遮挡」）是否已按本次实际改写？
（模板变量区之外的文案最容易漏，实测漏改会与正文结论自相矛盾）
- [ ] 是否已出图并用 check_report_images.py 核验通过（退出码 0）？
- [ ] 是否已跑 python scripts/verify_skill_consistency.py（退出码 0）？
8. 参考文件与脚本索引
文档
| 文件 | 内容 |
|---|---|
references/standards.md |
主口径 =《跑姿分析标准》五项指标 + 可测量代理量（双层结构）；含屈膝带口径差异登记（判定锁定不变）与五项命名映射 |
references/indicators.md |
每个代理量的定义、计算式、阈值 |
references/pipeline.md |
实现与性能：一条命令的用法、性能实测（解码/并行/帧选择）、判定链路（尺度门槛→不确定度→带宽保护→尺度分簇→退化快筛→标签一致性→左右臂自洽→取帧时刻）、调参与坑、环境事实 |
references/tutorial_method.md |
教程判读法：固定工序、十四期教程判据（含假前倾/坐着跑、身体后仰、撅臀、左右均衡+双屏对比、外八、大转子、接近全脚掌、单轴原则及其上下起伏判法、方形工具法、触地首帧、超中线两视角、持物处置）＋培训视频 27–31 期判据（采集规范／触地双判据／力向三分／支点同侧取点／刹车根因链／假前倾成因／后仰幅度／摆臂耸肩判据）、教程 vs 机器五条口径差异、各期基准读数 |
references/report_template.md |
报告六段骨架与文案规范 |
脚本
| 脚本 | 作用 |
|---|---|
scripts/pose_lib.py |
共享底层：常量与口径表、几何、不确定度与判定、推理、逐帧指标抽取 |
scripts/pose_measure.py |
主入口：体检 → 选段 → 事件 → 精算 → 分簇统计 → stats.json / stats.md |
scripts/pose_readings.py |
指定时刻的单帧读数（用于和教程 APP 读数「单帧对单帧」比对） |
scripts/build_report_template.py |
生成自包含中文单语手机大字版 HTML 报告 |
scripts/export_report_images.js |
报告出图（整页长图 + 章节分片） |
scripts/check_report_images.py |
出图核验（必做）：宽度/白占比/分段非空/章节对齐/长图高度 |
scripts/verify_render.js |
HTML 无头渲染可见性核验 |
scripts/clip_sections.js |
只截指定区块，便于目视校对版面 |
scripts/verify_skill_consistency.py |
技能自检（改动后必跑），退出码 0 才算过 |
scripts/_legacy/ |
v1.9.0 及更早的旧脚本归档，不再维护，仅供历史对照 |
环境依赖（技能只用标准库也能跑通主流程，下列为按需增强项）
| 组件 | 用途 | 必装 |
|---|---|---|
| Python 3.9+ | 画面处理、生成报告、核验 | ✅ |
| Pillow、numpy | 出图核验 | ✅ pip install -r requirements.txt |
| Node + puppeteer-core | HTML 渲染核验、报告出图 | ✅ npm i（见 package.json） |
| Chromium 内核浏览器 | 无头渲染（Chrome/Edge/Chromium 任一，路径自动探测，非默认位置设 CHROME_PATH） |
✅ |
| opencv-python、onnxruntime | 机器定量通道 | ⭕️ 可选 pip install opencv-python onnxruntime |
| YOLOv8n-pose ONNX（约 13.5 MB） | 同上；走 hf-mirror.com 下（HuggingFace 直连在本环境会 502） | ⭕️ 可选 |
> 没装 opencv / onnxruntime 时，技能不会失败，而是自动降级为纯观察型报告——
> 如实写「未做机器定量复核」即可，禁止凭想象补数字。
