快速开始

本指南带您从一个视频文件走到一次完整的阈值测量。首次运行请预留约一小时，其中大部分时间用于手工标记击球帧。

所需条件

一台已安装先机的 iPad（iPadOS 17 及以上）
一台已安装 ffmpeg 与 Python 3.11 的 Mac 或 Linux 电脑
接球方视角的对手击球录像 — 见拍摄规范
约 60 个可用击球，以完成一次完整测试

步骤

1. 从接球方位置拍摄

相机置于中线、底线后 0.5–1.0 m、高度 1.6–1.8 m。120 fps、1080p、高速快门、关闭防抖，全部参数锁定。

侧面视角会训练运动员读取接球方在实战中根本看不到的线索。它同样会产出数值，但那些数值没有意义。

2. 标记击球帧

播放视频并将帧号叠加显示：

ffplay -vf "drawtext=text='%{n}':fontsize=48:fontcolor=yellow:x=20:y=20" VIDEO.MOV

记录每次球拍击球的帧号。写成 CSV，每行一个击球 — contact_frame,zone[,shot_type]：

4127,BL,clear
5200,FR
6890,FC,drop

羽毛球区域代码：FL FC FR BL BC BR。

3. 切分片段

python -m zhanyan_pipeline.handmake VIDEO.MOV shots.csv \
    --sport badminton_singles \
    --out ./out/2026-08-10-club-a/ \
    --viewpoint receiver

输出 manifest.json 与 clips/ 文件夹。详见准备素材。

4. 传输到 iPad

将整个输出文件夹放入 iPad 的「文件」App —— 隔空投送、iCloud 云盘或数据线均可。务必保持 manifest.json 与 clips/ 在一起。

5. 导入

打开先机，点击 导入素材，再次点击 导入素材，在文件浏览器中选择 manifest.json。

应出现绿色的 已导入 N 个击球 确认卡片。请阅读任何琥珀色警告 — 详见导入素材。

6. 确认击球帧

点击 素材 → 标注击球帧。对每个击球：在帧条上找到精确的击球帧，在场地图上点击区域，点击确认。

进入节奏后目标为每个击球 5 秒。请一次性完成整个队列 —— 中途退出会丢失本次的标注工作。

7. 运行测试

点击 开始测试，选择 60 个试次，点击 开始测试，然后把 iPad 交给运动员。

每个试次：注视十字、片段播放、击球前屏幕变黑、运动员点击一个区域。

8. 记录结果

结果页显示阈值及其标准误。

离开该页面前请把数值抄下来。 应用目前尚无历史记录功能。