手势空中操纵 PPT（yrns-air-ppt）

一、技能简介

「AR 进课堂」：老师站在教室任意位置，摄像头识别手势即可直接操纵课件演示—— 挥掌翻页、食指空中指点、捏合单击、比 V 开激光笔、握拳黑屏。 纯本地离线运行（MediaPipe + OpenCV），不联网、不消耗任何积分，一套课件通用 PowerPoint / WPS 演示。

二、使用场景

• 公开课 / 优质课评比：离开讲台，走到学生中间也能控制课件
• 微课录制：录制时顺手做手势即可翻页，无需剪辑补救
• 无翻页笔 / 翻页笔没电时的应急方案
• 培训讲座、家长会等需要边走动边演示的场合

三、环境要求

• Windows 10/11（Mac/Linux 可直接运行 scripts/air_ppt.py）
• 摄像头一个（笔记本内置或外接均可）
• Python 3.11（WorkBuddy 已内置；其他环境自行安装亦可）

四、安装（一次性，复制粘贴即可）

在 yrns-air-ppt 目录下打开 PowerShell，逐行执行：

python -m venv venv
venv\Scripts\python.exe -m pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

若提示找不到 python，用 WorkBuddy 内置的 Python：

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

自动创建独立 venv 并从清华镜像安装 mediapipe / opencv-python / pyautogui（约 100MB，仅首次）。

五、快速开始

1. 启动：venv\Scripts\python.exe scripts\air_ppt.py，弹出预览窗口，看到手部骨架即正常
2. 打开 PPT 并按 F5 进入放映
3. 对摄像头做手势（见下表），按 Q 或 ESC 退出

验证安装：venv\Scripts\python.exe scripts\air_ppt.py --selftest

六、手势对照表

七、参数调优（命令行参数）

venv\Scripts\python.exe scripts\air_ppt.py --camera 0 --no-preview

• --camera 0：换摄像头编号（0/1/2）
• --no-preview：后台静默运行，不弹预览窗（正式上课推荐）
• --mirror 0：不镜像画面（默认镜像，符合直觉）

灵敏度在 scripts/air_ppt.py 顶部可改：

• SWIPE_SPEED（默认 28）：调小更灵敏，翻页更容易触发
• SWIPE_COOLDOWN（默认 1.0 秒）：两次翻页最短间隔
• SMOOTHING（默认 0.45）：指针平滑度，调大更跟手、调小更稳

八、故障排查

九、边界与注意

• 逆光 / 暗光环境下识别率下降，建议面光而坐、避免背对窗户
• 一次只识别一只手，双手同入镜会随机取一只
• 程序只向「当前活动窗口」发送按键，放映前先点一下演示窗口
• 摄像头画面仅本地处理，不上传任何数据

十、文件清单

yrns-air-ppt/
├── SKILL.md            本说明
├── README.md           面向使用者的快速上手
├── requirements.txt    依赖清单
└── scripts/
    ├── air_ppt.py            主程序（MediaPipe Tasks 手势识别）
    └── hand_landmarker.task  手部关键点模型（随包分发，离线可用）