手势空中操纵 PPT（yrns-air-ppt）
一、技能简介
「AR 进课堂」：老师站在教室任意位置，摄像头识别手势即可直接操纵课件演示——
挥掌翻页、食指空中指点、捏合单击、比 V 开激光笔、握拳黑屏。
纯本地离线运行（MediaPipe + OpenCV），不联网、不消耗任何积分，一套课件通用
PowerPoint / WPS 演示。
二、使用场景
- 公开课 / 优质课评比：离开讲台，走到学生中间也能控制课件
- 微课录制：录制时顺手做手势即可翻页，无需剪辑补救
- 无翻页笔 / 翻页笔没电时的应急方案
- 培训讲座、家长会等需要边走动边演示的场合
三、架构须知（重要）
- WorkBuddy 只能看懂你的话、输出文字指令，但它碰不到你电脑上的 PPT。
想要 PPT 真的动起来，必须再加一个本地小程序接收指令、替你按键模拟：
WorkBuddy 负责「听懂、下命令」，本地程序负责「执行命令控制 PPT」，缺一不可。 - 本技能的
scripts/air_ppt.py就是那个本地小程序——它用摄像头抓画面、识别手势，
再通过 pyautogui 向当前活动窗口（即正在放映的 PPT 窗口）发送键盘/鼠标信号，
从而实现「隔空翻页 / 指点 / 激光笔 / 黑屏」。 - 摄像头画面与 MediaPipe 推理全部在本地离线运行；首次运行会自动从 Google 下载手部模型（约 7.5MB），下载后永久本地缓存，不再联网。不联网也能跑（只要模型已缓存）。
四、环境要求
- Windows 10/11（Mac/Linux 可直接运行 scripts/air_ppt.py）
- 摄像头一个（笔记本内置或外接均可）
- Python 3.11（WorkBuddy 已内置；其他环境自行安装亦可）
五、安装（一键化，零操作）
任何人点开本技能，都会自动触发 scripts/start.py：
- 第一次：在当前技能目录下创建独立 venv，从清华镜像下载 mediapipe / opencv-python / pyautogui / numpy（约 100MB，之后离线可用）
- 后续：直接跳过安装、立即启动摄像头识别
手动自启动命令（任选其一）：
python scripts/start.py
python scripts/start.py --no-preview
python scripts/start.py --selftest
安装失败时，可手动走一遍：
python -m venv venv
venv\Scripts\python.exe -m pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple
Python 路径若找不到，用 WorkBuddy 内置的：
C:\Users\Administrator\.workbuddy\binaries\python\versions\3.11.9\python.exe -m venv venv
venv\Scripts\python.exe -m pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple
六、快速开始
- 一键启动：
python scripts/start.py（会自动装依赖并启动，看到预览窗+手部骨架即正常） - 打开 PPT/WPS 演示，按 F5 进入放映，并用鼠标点一下演示窗口让它成为当前活动窗口
- 对摄像头做手势（见下表），按 Q 或 ESC 退出
后台静默版（正式上课推荐）：python scripts/start.py --no-preview
自检模式：python scripts/start.py --selftest
七、手势对照表
| 手势 | 动作 | 效果 |
|---|---|---|
| ☝️ 伸食指 | 移动 | 空中鼠标指针（平滑跟随食指指尖） |
| 🤏 拇指食指捏合 | 快速捏合 | 单击 |
| 🖐 张开手掌左右挥 | 快速挥动 3 帧 | 向左挥 = 下一页，向右挥 = 上一页（SWIPE_SPEED 越小越灵敏，默认 8） |
| ✌️ V 字 | 保持 1 秒 | 开/关激光笔（放映中 Ctrl+L） |
| ✊ 握拳 | 保持 1 秒 | 黑屏 / 恢复（b 键） |
八、参数调优（命令行参数）
python scripts/start.py --camera 0 --no-preview
--camera 0：换摄像头编号（0/1/2）--no-preview：后台静默运行，不弹预览窗（正式上课推荐）--mirror 0：不镜像画面（默认镜像，符合直觉）--selftest：仅自检依赖与摄像头
灵敏度在 scripts/air_ppt.py 顶部可改：
- SWIPE_SPEED（默认 8）：越小越灵敏翻页；遇到误触发就调大，遇到翻不动就调小
- SWIPE_COOLDOWN（默认 0.8 秒）：两次翻页最短间隔
- SMOOTHING（默认 0.45）：指针平滑度，调大更跟手、调小更稳
九、故障排查
| 现象 | 处理 |
|---|---|
| 打不开摄像头 | 关闭占用摄像头的软件（腾讯会议等）；换 --camera 1 |
| 手势不灵 | 保证光照充足，手离摄像头 0.5~2 米，掌心朝向镜头 |
| 翻页误触发 | 调大 SWIPE_SPEED；翻页时才张开手掌，其余时间握拳或放下手 |
| 翻页无效 | 确认 PPT 处于放映状态（F5），且演示窗口是当前活动窗口 |
| 激光笔没反应 | Ctrl+L 仅在 PowerPoint/WPS 放映中生效 |
| 安装失败 | 检查网络；或手动 pip 逐个安装 requirements.txt 中的包 |
十、边界与注意
- 逆光 / 暗光环境下识别率下降，建议面光而坐、避免背对窗户
- 一次只识别一只手，双手同入镜会随机取一只
- 程序只向「当前活动窗口」发送按键，放映前先点一下演示窗口
- 摄像头画面仅本地处理，不上传任何数据
十一、文件清单
yrns-air-ppt/
├── SKILL.md 本说明
├── README.md 面向使用者的快速上手
├── requirements.txt 依赖清单
├── start.py 一键启动器（自动装依赖 + 启动摄像头）
└── scripts/
├── air_ppt.py 主程序（MediaPipe Tasks 手势识别 + pyautogui 控制）
└── hand_landmarker.task 手部关键点模型（随包分发，离线可用）
