> 🌱 Deep Garden 游泳训练体系 · 个人 IP 内容。本技能由 Deep Garden 整理沉淀，与「游泳训练追踪」技能同属 Deep Garden 运动健康方向。同作者 SkillHub 投资研究系列：DeepGarden。转载 / 二次创作请注明出处「Deep Garden」。
游泳动作GIF对照
何时用
用户发来游泳训练视频（或指向含视频的文件夹），要求：
- 把视频里「我的错误动作」做成动图（GIF）
- 同时呈现「标准动作」的对应 GIF，便于对照学习
- （可选）自动识别泳姿错误：用 MediaPipe 在本地离线分析人体 33 个关键点，给出错误清单 + 标红关节点 GIF，无需人工逐帧看
- 把两组 GIF 用于「我的看板」或（可选）Obsidian 复盘报告
> ✅ 不装 Obsidian 也能完整使用本技能。 Obsidian 只是可选的复盘笔记工具，不是前置依赖。
> ✅ 自动识别全程本地离线：视频与关节坐标不上传任何第三方服务器，隐私安全。
前置环境（通用，不绑定特定机器）
- 推荐按
安装说明.md安装基础依赖（OpenCV / imageio / imageio-ffmpeg / numpy），并可选安装 MediaPipe（自动识别用）。 - 手动安装：
- 基础（必装）：
pip install opencv-python-headless imageio imageio-ffmpeg numpy - 自动识别（可选）：
pip install mediapipe - 模型文件
assets/pose_landmarker_full.task首次使用时会自动从 MediaPipe 官方地址下载到本地，无需手动放置。若你环境无法联网，可手动下载并放到assets/。 - 本技能自带
scripts/gen_gifs.py，可直接运行：
python scripts/gen_gifs.py 你的错误视频1.mp4 [错误视频2.mp4 ...]
脚本会：① 为传入的每个视频生成wrong_xxx.gif（错误动作截段）；② 自动生成correct_freestyle.gif/correct_breaststroke.gif（标准动作关节示意动画）。 - 若装了 mediapipe，脚本会自动为每个视频追加：③
report_xxx.json（结构化错误清单）；④annotated_xxx.gif（标红问题关节/肢体的动画）。不装 mediapipe 则只产出 ①②，自动跳过识别。 - 输出目录默认
./output_gifs，可用环境变量GIF_OUT覆盖。 - 若你本机已有一个隔离的 OpenCV 环境，可在运行前设置
PYTHONPATH指向它；脚本对此做了兼容。
自动识别（MediaPipe，可选增强）
- 原理：用 MediaPipe Tasks Vision 的
PoseLandmarker（本地.task模型，33 个全身关键点）逐帧识别，提取肩/肘/腕/髋/膝/踝等角度与对称性，按游泳专项规则判定错误。 - 置信度过滤：关键点
visibility < 0.6直接舍弃；跨多帧平滑；以完整划手周期的平均角度判定，避免单帧抖动误报。 - 判定覆盖：
- 自由泳：拖肘（低肘划水）/ 顺拐（同侧手脚发力）/ 抬头换气（应侧转换气）/ 转体不足
- 蛙泳：宽膝（宽蛙腿、膝外扩过大）/ 蹬水无效（无蹬夹推进）
- 仰泳 / 蝶泳：基础错误（如蝶泳二次腿时机、仰泳头位偏移）
- 输出：
report_xxx.json含每个错误的name / harm / standard / correction / encourage / confidence；annotated_xxx.gif把问题肢体/关节标红，直观定位。 - 泳姿判定：默认按文件名或
--stroke参数；也可不改参数让其按文件名中的freestyle/breaststroke/backstroke/butterfly关键词自动选。
可靠度边界（重要 · 预期管理）
自动识别不是 100% 准确，请如实告知用户它的能力上限，避免售后落差：
- ✅ 侧面全身清晰、水面齐平机位、光线充足：检出率与判定准确率 ≥ 90%，可作为可靠纠错参考。
- ⚠️ 以下情况会显著误判/漏判，工具会诚实报告并建议重拍：
- 水下/夜拍/逆光导致画面过暗 → 人体检出率骤降（实测水下视频检出率低至 0–18%，此时脚本会输出"检出率=0% 跳过分析"而非编造错误）
- 俯拍、跟拍、局部特写（只拍上半身）→ 关键下肢/全身关键点缺失，角度无法计算
- 多人同框、严重遮挡 → 只取单人且遮挡帧自动剔除
- 🔒 侧面纯视角局限：左右肩/膝重合，凡涉及"左右对称"的错误（如顺拐、宽膝）置信度自动降级并提示"建议 3/4 侧前方机位复测"，绝不编造高置信结论。
- 📌 定位：自动识别是"辅助初筛 + 标红引导"，最终纠错仍以真人教练或用户对照标准 GIF 自判为准。报告里永远带 reliability_note 诚实说明本次检出质量。
步骤
- （可选）自动识别初筛：若装了 mediapipe，直接跑
gen_gifs.py，它会产出report_xxx.json+annotated_xxx.gif，先看这份初筛结论与标红位置。 - 抽帧核查（可选补充）：用 cv2 把视频均匀抽 ~10 帧到
./_frames/，逐帧看，判断泳姿与主要错误点。判定标准优先参考../swim-training-tracker/ima/ima-knowledge-base/的08 自由泳打腿节奏（数一个完整划手周期的打腿次数匹配二次/四次/六次腿）、09 蛙泳休闲与竞速（头部抬升高度、膝盖收腿宽度、手脚节奏区分休闲/竞速）、10 AI视频抽帧比对规则（错误→影响→标准→整改练习→正向鼓励的输出结构）。 - 生成错误 GIF：
scripts/gen_gifs.py读原始 mp4 → 截中间段 (0.18–0.82) → 降采样 6fps → 缩放到 380 宽 → 写 GIF(loop=0)。单段控制在 ~40 帧、≤3MB。 - 生成标准 GIF：脚本自动用 cv2 逐帧画关节 stick-figure 动画（浅灰空气区 + 浅蓝水区，水面线 y=150）：
- 自由泳：侧转换气（下巴贴肩、头不抬）、高肘（肘始终高于手连线）、小幅打腿；阶段标注 ENTRY/CATCH/PULL/RECOVERY/BREATH
- 蛙泳：收腿膝外展 → 翻 → 蹬夹 → 并拢滑行 (GLIDE)；抬头只在蹬夹瞬间短促；阶段 OUT-SWEEP/CATCH/RECOVER/EXTEND/KICK
- ⚠️ cv2.putText 不支持中文，GIF 内只用英文阶段标签，中文解释放看板/报告里 - 落盘到输出文件夹：GIF 默认写在
./output_gifs/（或GIF_OUT指定的目录）。 - 消费方式（二选一，都不强制 Obsidian）：
- 方式 A · 进看板（推荐，零 Obsidian）：把wrong_*.gif与correct_*.gif（以及可选annotated_*.gif）复制到 swim-training-tracker 看板的assets/目录，并在swim-data.json的strokeGifLog里登记，看板「动作对照」面板自动并排展示「我的 vs 标准」。
- 方式 B · 进 Obsidian 复盘（可选）：若你用 Obsidian，把 GIFcp到你的 vault 子目录（如<你的vault>/动作对照/），在报告加「★ 动作对照」章节，表格并排![[动作对照/wrong_xxx.gif]]与![[动作对照/correct_xxx.gif]]，配中文「看哪里」说明，并注明标准 GIF 为示意动画非真实录像。
Obsidian vault 注意（仅方式 B 需要）
- 报告必须落在「已注册的 vault」子目录，否则 Obsidian 看不到。注册新 vault：编辑 Obsidian 配置（
vaults字段）并建.obsidian/workspace.json，再重启 Obsidian。 - 不同用户 vault 路径不同，脚本不硬编码，请自行 cp 到你的 vault。
- 不装 Obsidian 的用户直接走方式 A 即可。
参考脚本
scripts/gen_gifs.py—— GIF 生成主入口（含 wrong/correct × freestyle/breaststroke，已中性化、不依赖特定机器路径；自动检测 mediapipe 是否安装）scripts/pose_analyze.py—— MediaPipe 姿态识别与游泳专项判定模块（含ERROR_LIB错误库，镜像 IMA 知识库 11–14 的内容；PoseAnalyzer.analyze()返回 report dict；make_annotated_gif()生成标红动画）assets/pose_landmarker_full.task—— MediaPipe 本地模型（首次使用自动下载，也可手动放置）
