Skip to content

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

8 Commits

Folders and files

Repository files navigation

Leap Control

Windows 11 应用,使用 Leap Motion Controller(一代)实现手势控制桌面。

功能

手势控制

手势 操作
手掌上下移动 页面滚动
手掌旋转(顺/逆时针) 音量增加/减少
握拳松开 暂停/播放媒体
快速左右滑动 切换虚拟桌面

GUI 窗口

  • Leap Motion 连接状态显示
  • 实时手势检测日志
  • 启用/禁用手势控制
  • 灵敏度调节滑块

安装

前置条件

必须安装:

  1. Windows 11(或 Windows 10)

  2. Leap Motion Controller(一代硬件设备)

  3. Ultraleap Tracking Software

  4. Git(仅从源码构建需要)

方式一:直接使用预编译 exe(推荐)

  1. 从 Releases 下载 leap-control.exe
  2. 确保 Ultraleap Tracking Service 正在运行
  3. 双击运行

方式二:从源码构建

第一次构建前,确保已安装:

  • 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

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages