Windows 11 应用,使用 Leap Motion Controller(一代)实现手势控制桌面。
| 手势 | 操作 |
|---|---|
| 手掌上下移动 | 页面滚动 |
| 手掌旋转(顺/逆时针) | 音量增加/减少 |
| 握拳松开 | 暂停/播放媒体 |
| 快速左右滑动 | 切换虚拟桌面 |
- Leap Motion 连接状态显示
- 实时手势检测日志
- 启用/禁用手势控制
- 灵敏度调节滑块
必须安装:
-
Windows 11(或 Windows 10)
-
Leap Motion Controller(一代硬件设备)
-
Ultraleap Tracking Software
- 下载地址:https://developer.leapmotion.com/tracking-software-download
- 推荐版本:Gemini v5.x 或 Hyperion v6.x
- 安装后确保 Ultraleap Tracking Service 正在运行(可在任务管理器 → 服务中查看)
-
Git(仅从源码构建需要)
- 下载地址:https://git-scm.com/download/win
- 用于克隆 Leap Python SDK
- 从 Releases 下载
leap-control.exe - 确保 Ultraleap Tracking Service 正在运行
- 双击运行
第一次构建前,确保已安装:
- Ultraleap Tracking Software(会在
C:\Program Files\Ultraleap\LeapSDK\安装 SDK) - Git(用于克隆依赖)
一键构建:
# 1. 打开命令提示符或 PowerShell
# 2. 进入项目目录
cd d:\Code\leap-control
# 3. 运行构建脚本
.\build_windows.bat构建脚本会自动完成以下步骤:
- 下载 Python 3.12 便携版(如果不存在)
- 安装 pip 和所有依赖包
- 从 Ultraleap SDK 复制 leapc_cffi 模块
- 从 GitHub 克隆 leap Python bindings
- 使用 PyInstaller 打包成单文件 exe
构建输出:
C:\temp\leap-control-build\project\dist\leap-control.exe
构建完成后会自动打开输出目录。
如果你想在开发模式下运行(不打包成 exe):
# 需要 Python 3.10+
# 使用 uv(推荐)
uv sync
uv run python src/main.py
# 或使用 pip
pip install -r requirements.txt
python src/main.py注意:开发模式下需要手动配置 leap 和 leapc_cffi 模块的路径。
# 运行所有测试
uv run pytest
# 运行测试并显示覆盖率
uv run pytest --cov=src --cov-report=term-missing
# 运行特定模块测试
uv run pytest tests/test_gesture_detector.py -v配置文件 config.json(首次运行后自动创建):
{
"scroll_sensitivity": 1.0,
"volume_sensitivity": 1.0,
"dead_zone": 30,
"cooldown_ms": 100,
"gestures_enabled": true
}| 参数 | 说明 | 默认值 |
|---|---|---|
| scroll_sensitivity | 滚动灵敏度 | 1.0 |
| volume_sensitivity | 音量灵敏度 | 1.0 |
| dead_zone | 死区阈值 (mm/s) | 30 |
| cooldown_ms | 冷却时间 (ms) | 100 |
| gestures_enabled | 启用手势 | true |
leap-control/
├── src/
│ ├── main.py # 入口点
│ ├── config.py # 配置管理
│ ├── actions.py # 系统操作(滚动、音量、媒体键)
│ ├── gesture_detector.py # 手势识别状态机
│ ├── leap_handler.py # Leap Motion 连接管理
│ └── gui.py # GUI 窗口(wxPython)
├── patches/
│ └── leap_init_patch.py # PyInstaller 兼容性补丁
├── tests/ # 测试套件
├── assets/ # 资源文件(图标等)
├── build_windows.bat # Windows 一键构建脚本
└── pyproject.toml # 项目配置
Q: 程序显示"服务未运行"
- 确保 Ultraleap Tracking Service 正在运行
- 打开任务管理器 → 服务 → 找到 "UltraleapTracking" → 右键启动
Q: 程序显示"未检测到设备"
- 检查 Leap Motion Controller 是否正确连接到 USB 端口
- 尝试更换 USB 端口或数据线
- 在 Ultraleap Control Panel 中确认设备已被识别
Q: 构建时卡住不动
- 如果卡在 "Installing dependencies...",等待 pip 安装完成(可能需要几分钟)
- 如果卡在 "Cloning...",检查网络连接或手动克隆 GitHub 仓库
Q: 手势没有反应
- 确保 GUI 窗口中"手势"按钮显示为"禁用手势"(表示已启用)
- 调高灵敏度滑块
- 确保手在 Leap Motion 的有效检测范围内(约 10-60 cm 高度)
MIT