# head-mouse

**Repository Path**: zhangshenjia/head-mouse

## Basic Information

- **Project Name**: head-mouse
- **Description**: 用摄像头控制鼠标，给不能直接控制鼠标的残障人士提供帮助
- **Primary Language**: Python
- **License**: 0BSD
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-17
- **Last Updated**: 2026-09-24

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 猫头鹰鼠标（Head Mouse）

通过摄像头识别面部动作，实现免双手的鼠标控制。屏幕上会显示一只跟随操作的「猫头鹰」浮层，用于指示当前状态并提供语音提示。

---

## 系统要求

- **操作系统**：macOS（推荐）或 Windows
- **硬件**：可用摄像头
- **权限**（macOS）：
  - **摄像头**：用于面部追踪
  - **辅助功能**：用于移动鼠标、点击等操作（系统设置 → 隐私与安全性 → 辅助功能）
- **权限**（Windows）：首次运行时允许摄像头访问；若控制无效，请检查杀毒软件或 UAC 限制

---

## 安装与启动

### 从源码运行

```bash
pip install -r requirements.txt
python head_mouse.py
```

### 打包为 macOS 应用

```bash
./scripts/build_mac_app.sh
```

构建完成后，在 `dist/猫头鹰鼠标.app` 中双击启动。用户配置与校准数据保存在：

```
~/Library/Application Support/Head Mouse/
```

> 未签名的应用首次打开时，若被系统拦截，请右键 → **打开**。

### 打包为 DMG 安装镜像

```bash
./scripts/build_dmg.sh
```

在 `.app` 构建完成后运行，生成 `dist/猫头鹰鼠标.dmg`（拖入「应用程序」即可安装，内附使用说明）。

---

## 界面说明

| 元素 | 说明 |
|------|------|
| **猫头鹰浮层** | 显示在屏幕上的半透明角色，实时反映眼睛、嘴巴状态 |
| **语音气泡** | 猫头鹰旁的文字提示，并伴随语音播报 |
| **启动画面** | 启动时短暂显示，约 1.5 秒后进入校准 |

猫头鹰表情含义：

- **眼睛**：绿色/睁开 = 睁眼，红色/闭合 = 闭眼
- **嘴巴**：张开或闭合对应当前嘴部检测状态

---

## 首次使用：校准

启动后会自动进入 **三步校准**（中心 → 左上角 → 右下角）：

1. **第 1 步（中心）**：面向摄像头，跟随提示转动头部；系统记录面部中心位置
2. **第 2 步（左上角）**：猫头鹰移动到屏幕左上角，**张嘴**进入采样，再转向左上角并保持脸部在画面内
3. **第 3 步（右下角）**：同上，完成右下角采样后校准结束

### 校准技巧

- 全程保持脸部在摄像头画面内
- 每个角落后按提示 **张嘴** 开始采样
- 采样过程中继续 **转头跟踪猫头鹰**
- 按 **空格** 可跳过当前校准步骤
- 第 1 步提示出现后，**闭嘴后再张嘴** 可跳过整个校准（使用默认映射）

校准成功后数据自动保存；更换显示器或分辨率变化后，请在菜单中选择 **重新校准**。

---

## 基本操作

### 头部控制光标

校准完成后，**转头** 即可移动鼠标。头部小幅静止时，光标会在「静止容错距离」内不再抖动（可在设置中调整）。

**物理鼠标优先**：若你用手移动了物理鼠标，头控会暂时停止；鼠标静止一段时间（默认 2 秒，可设置）后自动恢复。

### 嘴巴：点击与拖拽

| 动作 | 效果 |
|------|------|
| **快速张嘴再闭嘴**（≤ 1 秒） | 左键单击；连续两次则为双击 |
| **张嘴保持约 1 秒** | 右键单击 |
| **张嘴同时明显转头** | 进入拖拽模式（按住左键拖动） |
| **连续张嘴约 3 秒** | 暂停 / 恢复头控 |

> 头控暂停期间，张嘴点击、拖拽等鼠标动作不会生效。

### 单眼闭眼：滚轮

在头控激活且 **未张嘴** 时：

| 动作 | 效果 |
|------|------|
| **仅闭左眼 ≥ 1 秒** | 向上滚动；≥ 2 秒后开始连续上滚 |
| **仅闭右眼 ≥ 1 秒** | 向下滚动；≥ 2 秒后开始连续下滚 |
| **双眼同时闭合** | 不触发滚轮（见下方屏幕键盘） |

### 双眼闭合：屏幕键盘

| 动作 | 效果 |
|------|------|
| **双眼闭合 ≥ 1 秒** | 打开 / 关闭屏幕键盘 |
| **键盘打开时** | 用头移动光标悬停按键，**张嘴再闭嘴** 输入该键 |
| **再次闭眼** | 需先 **睁眼** 后才能重新计时，避免误触 |

屏幕键盘出现在当前光标附近，支持字母、数字、删除、回车、空格等。macOS 下键盘不会抢占前台应用焦点，输入会发送到之前使用的应用。

---

## 猫头鹰交互

### 鼠标拖动（手控）

- **macOS**：可直接用鼠标拖动猫头鹰
- **Windows**：在猫头鹰浮层上按住左键拖动

### 嘴巴 + 猫头鹰：菜单与拖动

当 **鼠标光标位于猫头鹰上** 时：

| 动作 | 效果 |
|------|------|
| **快速张嘴再闭嘴**（≤ 0.25 秒） | 弹出右键菜单 |
| **张嘴超过约 0.25 秒** | 用 **头部** 拖动猫头鹰位置（闭嘴结束） |

### 右键菜单

在猫头鹰上 **右键**（macOS 原生浮层）或通过上述嘴部手势打开，包含：

- **设置** — 调整检测参数
- **重新校准** — 重新进行三步校准
- **关于** — 查看项目信息
- **退出** — 关闭程序

菜单打开后，在菜单 **外** 快速张嘴可关闭菜单。

### 头控暂停时点击猫头鹰

头控暂停后，**单击猫头鹰**（未拖动）可立即恢复头控。

---

## 设置

通过菜单 → **设置** 打开，可调整：

| 选项 | 说明 | 默认值 |
|------|------|--------|
| 头控静止容错距离 | 头部不动时，目标位置在此半径（像素）内不移动光标 | 20 px |
| 物理鼠标让路时间 | 检测到物理鼠标后，无操作多久恢复头控 | 2 秒 |
| 张嘴检测阈值 | 值越小越容易判定为张嘴 | 0.05 |
| 眼睛闭合检测阈值 | 值越小越容易判定为闭眼 | 0.25 |

点击 **保存** 后，前两项写入 `config.txt`；张嘴 / 闭眼阈值立即生效。若检测不准，可微调阈值后重新测试。

---

## 快捷键

| 按键 | 作用 |
|------|------|
| **Esc** | 退出程序 |
| **空格** | 校准过程中跳过当前步骤 |

---

## 数据文件

| 文件 | 位置（源码运行） | 位置（macOS 打包应用） |
|------|------------------|------------------------|
| `calibration.json` | 项目根目录 | `~/Library/Application Support/Head Mouse/` |
| `config.txt` | 项目根目录 | 同上 |

删除 `calibration.json` 可在下次启动时触发重新校准（若屏幕分辨率与保存时一致则会自动加载）。

---

## 常见问题

**光标不动或点击无效（macOS）**  
请在「系统设置 → 隐私与安全性 → 辅助功能」中，允许 **Head Mouse.app**（或运行时的终端 / Python）控制电脑。

**摄像头无画面 / 无法检测人脸**  
确认摄像头未被其他程序占用，并在系统隐私设置中允许访问摄像头。

**头控过于灵敏或迟钝**  
在设置中调整「静止容错距离」；校准时尽量加大头部转动幅度。

**张嘴 / 闭眼误触发**  
在设置中适当 **提高** 张嘴阈值或闭眼阈值（数值变大 = 需要更明显的动作）。

**屏幕键盘输入到了错误窗口（macOS）**  
打开键盘前请先点击目标输入框；程序会尝试将焦点还给之前的应用。

---

## 退出

- 按 **Esc**
- 或菜单 → **退出**

---

## 作者

猫头鹰鼠标 — 作者：李彤萱、袁舒同 · 指导老师：张砷镓