# fish

**Repository Path**: ai_software/fish

## Basic Information

- **Project Name**: fish
- **Description**: 摸鱼用的
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-06
- **Last Updated**: 2026-04-07

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Recognition Console V1.0

Recognition Console V1.0 是一个面向 Windows 的本地识别控制台，用于把摄像头识别结果和桌面自动化动作连接起来。系统在本机运行，不依赖云端服务，适合做桌面切换、程序切换、音量联动、串口通信等识别触发场景。

## V1.0 已实现功能

- 多摄像头自动扫描与实时预览
- 本地 Web 控制台，统一完成配置、上传、规则管理和日志查看
- 参考图上传、命名、删除
- 三类识别规则
  - 人脸
  - 人体
  - 其他图像
- **四类**动作规则
  - 切回桌面
  - 切换到指定程序，并尽量恢复、最大化、置前
  - 设置系统主音量百分比
  - **COM 串口发送（向指定串口发送字符串）**
- 规则开关、冷却时间、连续命中次数、限定摄像头
- 成功动作后的全局暂停检测
- 摄像头墙右侧显示识别名字、相似度、当前启用规则的匹配类型
- 本地模型状态查看，并支持点击打开模型所在位置
- Windows 一键启动脚本
  - 自动创建或修复 `.venv`
  - 自动安装依赖
  - 自动准备人脸模型
  - 优先使用 `git + git lfs` 拉取模型
  - 如果 `git lfs` 不可用，则自动回退为直接下载 ONNX 模型

## 技术路线

- Web：FastAPI + Jinja2 + 原生 JavaScript
- 摄像头采集：OpenCV
- 人体检测：YOLO
- 人脸检测与识别：YuNet + SFace
- 其他图像匹配：ORB 特征匹配 + 单应性定位
- Windows 动作：`pywin32` + `ctypes` + `pycaw`
- **串口通信：`pyserial`**

## 目录结构

```text
recognition/
├─ app/
│  ├─ __init__.py
│  ├─ main.py
│  ├─ models.py
│  ├─ config.py
│  ├─ utils.py
│  ├─ services/
│  │  ├─ controller.py
│  │  ├─ storage.py
│  │  ├─ model_manager.py
│  │  ├─ detection_engine.py
│  │  ├─ reference_library.py
│  │  ├─ similarity.py
│  │  ├─ camera_manager.py
│  │  └─ windows_actions.py
│  └─ web/
│     ├─ templates/
│     │  └─ index.html
│     └─ static/
│        ├─ app.js
│        └─ style.css
├─ data/
│  ├─ config.json
│  └─ references/
├─ models/
├─ requirements.txt
├─ run.ps1
└─ run.bat
```

## 运行环境

- Windows 10 / Windows 11
- 至少 1 个可用摄像头
- 建议联网首次启动
- 建议使用普通桌面环境，不要在远程裁剪过度的虚拟桌面中运行

说明：

- 启动脚本会优先尝试自动安装 Python 3.12
- 模型和依赖首次准备时间会比后续启动更长
- 所有动作能力目前都是 Windows 专用

## 一键启动

直接双击：

```bat
run.bat
```

或在 PowerShell 中执行：

```powershell
.\run.ps1
```

默认访问地址：

```text
http://127.0.0.1:8000
```

## 启动脚本会做什么

`run.ps1` 会自动完成以下步骤：

1. 检查 Python，必要时尝试通过 `winget` 安装。
2. 检查 `.venv` 是否可用。
3. 如果 `.venv` 是从别的机器拷贝来的、已损坏或无法启动，则自动删除并重建。
4. 根据 `requirements.txt` 自动安装依赖。
5. 检查 YuNet / SFace 模型。
6. 优先使用 `git + git lfs` 克隆 Hugging Face 模型仓库。
7. 若 `git lfs` 无法使用，则回退为直接下载 ONNX 模型文件。
8. 启动本地 Web 服务。

## 使用流程

### 1. 启动系统

运行 `run.bat` 或 `run.ps1`，浏览器打开本地页面。

### 2. 准备参考图

可以使用任一方式：

- 在网页中直接上传图片
- 手动把图片放入 `data/references/` 后点击"重载参考图库"

上传后可以给参考图命名，也可以删除参考图。规则面板会优先显示用户设置的参考图名称。

### 3. 创建识别规则

在"识别规则设置"中可配置：

- 规则名称
- 参考图
- 匹配类型
- 触发阈值
- 连续命中次数
- 冷却时间
- 限定摄像头编号
- 动作类型
- 是否启用

### 4. 配置动作

#### 切回桌面

命中后立即执行 Windows 桌面切换（Win + D）。

#### 切换到程序

建议填写以下信息中的至少一部分：

- 程序路径
- 窗口标题关键字
- 进程名
- 工作目录

行为说明：

- 如果程序已在运行，系统会尝试切换、恢复、最大化并置前
- 如果程序未运行，且启用了"如果未运行则自动启动程序"，系统会先启动再切换

#### 设置音量

可设置 `0 - 100` 的系统主音量百分比。

说明：

- `0` 表示静音
- 该动作调整的是当前默认播放设备的主音量

#### COM 串口发送

向指定串口发送字符串。需要配置：

- **端口号**：如 COM3 或 3（自动补全为 COM3）
- **波特率**：110 - 2000000，默认 9600
- **校验位**：无(N) / 偶校验(E) / 奇校验(O) / Mark(M) / Space(S)
- **停止位**：1 / 1.5 / 2
- **要发送的字符串**：如 AT+RST 等指令

说明：

- 点击动作类型选择"COM发送"后，会自动弹出 COM 参数配置弹窗
- 在规则编辑表单中也可以点击"编辑 COM 参数"按钮修改串口配置
- 支持在规则编辑时验证 COM 端口是否可用

## 系统配置说明

### 识别灵敏度

共 5 档：

- 1 档最宽松，更容易触发
- 5 档最严格，需要更高相似度

### 冷却时间

某一条规则触发成功后，这条规则在冷却时间内不会再次触发；其他规则仍可继续工作。

### 动作后暂停检测

任意规则动作执行成功后，系统会对所有规则统一暂停检测一段时间，用于降低重复触发和节省资源。

### 连续命中次数

同一规则需要连续命中多少次后才真正执行动作。

### 摄像机后端

- `AUTO`：自动尝试
- `CAP_DSHOW`：常见于部分 USB 摄像头，兼容性较好
- `CAP_MSMF`：Windows 原生多媒体后端，某些设备上更稳定

如果某台电脑上摄像头打不开、延迟高或报索引错误，可以切换这个选项再试。

## 模型说明

V1.0 使用以下人脸模型：

- YuNet：人脸检测
- SFace：人脸识别

模型位置默认在：

```text
models/
```

模型来源：

- `https://huggingface.co/opencv/face_detection_yunet`
- `https://huggingface.co/opencv/face_recognition_sface`

如果网页中的模型状态显示可用，说明当前模型文件已经准备完成。

## 配置与数据

主要数据位置：

- 系统配置：`data/config.json`
- 参考图：`data/references/`
- 模型文件：`models/`

迁移到另一台 Windows 电脑时，建议保留：

- `data/config.json`
- `data/references/`
- `models/`（可选，不带也可以，启动时会自动重新下载）

不建议直接拷贝：

- `.venv/`

原因：

- 虚拟环境通常与机器路径、Python 安装位置、DLL 状态相关
- V1.0 启动脚本已经支持自动识别失效的 `.venv` 并重建，但最稳妥的方式仍然是不迁移 `.venv`

## 已检查的 V1.0 收尾项

本次对 V1.0 做了收尾检查，并补强了以下跨设备问题：

- 修复了音量动作对新版本 `pycaw` 的兼容性
- 启动脚本现在会识别并重建失效的 `.venv`
- 模型准备新增了 `git/git lfs` 失败时的直接下载回退
- README 已与当前实现对齐

## 已知限制

- 仅支持 Windows
- 多摄像头和高频识别会明显占用 CPU
- 人脸识别效果依赖参考图质量、光照和角度
- 设置音量只作用于当前默认输出设备
- 不同电脑上的摄像头驱动差异较大，`camera_backend` 可能需要手动调整

## 手动开发启动

如果不使用一键脚本，也可以手动执行：

```powershell
python -m venv .venv
.\.venv\Scripts\python -m pip install --upgrade pip
.\.venv\Scripts\python -m pip install -r requirements.txt
.\.venv\Scripts\python -m app.main
```

## V1.0 命名

本版本正式命名为：

**Recognition Console V1.0**