# mouse_control

一种基于神经网络来模拟人手移动鼠标的方法。

## 简介

本项目源于该死的轨迹检测。我们用一个简单的三层全连接神经网络去拟合真人鼠标移动轨迹。

<img src="./imgs/Figure_1.png">

上图为真人轨迹移动得到的散点图——用 10 个关键点拟合一条轨迹。可以看到，人手移动和 PID、贝塞尔等曲线有明显区别，因此用神经网络来拟合更合适。

**网络结构**：

- 输入：`(dx, dy)` —— 目标点相对当前位置的偏移
- 三层全连接：`Linear(2 → 64) → ReLU → Linear(64 → 32) → ReLU → Linear(32 → 20)`
- 输出：`(10, 2)` —— 10 个轨迹点

仓库内含 `data/` 下的 400 条采集数据和 `src/mouse_control/assets/mouse.onnx` 预训练模型，clone 之后可以直接 `mouse-visualize` 看效果。

## 安装

本项目不发布到 PyPI，始终通过 git 源码 + tag 管理。要求 Python ≥ 3.12。

**在你自己的项目里引用**（用 [uv](https://docs.astral.sh/uv/)）：

```bash
# 指定 tag（推荐）
uv add 'git+https://git.vercanti.com/yellowdog/mouse_control.git@v0.1.0'

# 跟随 main
uv add 'git+https://git.vercanti.com/yellowdog/mouse_control.git'

# 指定 commit
uv add 'git+https://git.vercanti.com/yellowdog/mouse_control.git@<sha>'
```

**本仓库内开发**：

```bash
uv sync                   # 安装依赖（含 dev 组的 pytest）
uv run pytest             # 跑测试
uv build                  # 产出 wheel + sdist
```

## 项目结构

```
mouse_control/
├── pyproject.toml
├── README.md
├── data/                       # 训练 / 测试数据 (380 + 20 条)
│   ├── mouse_data.csv
│   └── mouse_data_test.csv
├── imgs/                       # README 图片
└── src/mouse_control/          # 包源码 (src layout)
    ├── __init__.py             # 公共 API
    ├── model.py                # SimpleNet 网络定义
    ├── collect.py              # 数据采集 GUI
    ├── train.py                # 训练 + ONNX 导出
    ├── visualize.py            # 轨迹可视化
    ├── inference.py            # 模型加载 / 推理辅助
    └── assets/
        └── mouse.onnx          # 随包发布的预训练模型
```

## 命令行用法

安装后可以直接调用三个命令（也可以用 `uv run <cmd>`）：

### 1. 采集真人鼠标轨迹

```bash
uv run mouse-collect -o data/mouse_data.csv -n 100
```

<img src="./imgs/collect.png">

全屏界面：点**红球**开始记录、移动到**蓝球**点击结束记录，每条轨迹保存 10 个关键点到 CSV。

- 默认采集 100 条后自动退出，按 `Esc` 提前退出
- 推荐采集 ≥ 300 条以获得较好的训练效果

### 2. 划分训练 / 测试集

把 `mouse_data.csv` 里**剪切**若干行（10-20 条）到 `mouse_data_test.csv` 即可。

### 3. 训练模型

```bash
uv run mouse-train \
  --train-csv data/mouse_data.csv \
  --test-csv data/mouse_data_test.csv \
  --output mouse.onnx \
  --epochs 1000
```

训练结束后在当前目录生成 `mouse.onnx`。其它参数 `--batch-size` `--lr` 可调。

### 4. 可视化效果

```bash
uv run mouse-visualize --n-trajectories 10 --seed 42
```

<img src="./imgs/Figure_2.png">

随机生成若干目标点，每条轨迹包含 10 个模型输出点 + 80 个三次样条插值点。`--no-show` 跳过 GUI 窗口、只写 PNG；`--model` 指定其它 ONNX 文件。

## Python API

```python
import mouse_control as mc

# 加载模型：优先 ./mouse.onnx，否则回退到包内打包的预训练模型
session = mc.load_model()

# 推理：输入 (dx, dy)，输出 (10, 2) 轨迹点
pts = mc.predict(session, 120, -80)
# -> ndarray, shape (10, 2), dtype float32

# 直接使用模型类（用于自训练 / 微调）
from mouse_control import SimpleNet
```

## ONNX 推理（其它语言）

### Python (onnxruntime)

```python
import numpy as np
import onnxruntime as ort

session = ort.InferenceSession("mouse.onnx")
inp = np.array([[[100.0, 200.0]]], dtype=np.float32)  # dx=100, dy=200
output = session.run(None, {"input": inp})[0]          # shape (1, 10, 2)
```

### C++ (OpenCV DNN)

```cpp
cv::dnn::Net net = cv::dnn::readNetFromONNX("mouse.onnx");
cv::Mat blob(1, 2, CV_32F, cv::Scalar(100, 100));  // 输入 dx=100, dy=100
net.setInput(blob, "input");
cv::Mat output = net.forward("output");            // 输出 1*10*2
std::cout << output.at<float>(0, 8, 0) << std::endl;
```

## 打包

```bash
uv build
# -> dist/mouse_control-0.1.0-py3-none-any.whl
# -> dist/mouse_control-0.1.0.tar.gz
```

wheel 内含 `assets/mouse.onnx` 预训练模型，安装后直接 `mc.load_model()` 即可使用。

## 发版（tag 驱动）

`pyproject.toml` 里的 `version` 字段是手动维护的，必须和 git tag 保持同步。
发版步骤：

```bash
# 1. 改版本号
$EDITOR pyproject.toml          # version = "0.2.0"

# 2. 提交并打 tag
git add pyproject.toml
git commit -m "Release v0.2.0"
git tag v0.2.0
git push && git push --tags
```

下游再 `uv add 'git+...@v0.2.0'` 就拿到对应版本。