mouse_control/README.md

mouse_control

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

简介

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

上图为真人轨迹移动得到的散点图——用 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）：

# 指定 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>'

本仓库内开发：

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. 采集真人鼠标轨迹

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

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

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

2. 划分训练 / 测试集

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

3. 训练模型

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. 可视化效果

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

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

Python API

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)

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)

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;

打包

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 保持同步。 发版步骤：

# 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' 就拿到对应版本。