# vision-test **Repository Path**: lutherluov/vision-test ## Basic Information - **Project Name**: vision-test - **Description**: Ai 视力检测项目 - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-11-20 - **Last Updated**: 2026-11-20 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # AI 视力检查 单页面、扁平风格、严谨医疗色调的 AI 视力筛查演示系统。前端采集摄像头画面,按 1 帧/秒推送到 Python 后台;后台识别手掌方向、逐轮下发字号与方向,最终统计正确率与视力等级并归档,支持历史查询。 ## 功能流程 1. 填写姓名、性别、年龄,阅读检测方法; 2. 进入画中画检测界面:中央显示字母 F(10 级字号,5cm → 3mm,方向随机),左下角摄像头实时画面; 3. 右上角状态灯为**绿色**时表示正在出题、可以作答(此时显示 F);判定完成后不提示对错,灯变为**白色**并隐藏 F,约 1 秒后绿色再次亮起并自动出下一题; 4. 10 题结束自动给出正确率、小数视力、五分记录与综合评定; 5. 结果写入本地 SQLite,可按姓名查询历史并查看逐轮明细。 ## 启动方式 ### 一键启动(Windows) 双击项目根目录的 `start.bat`,稍等片刻浏览器会自动打开 `http://127.0.0.1:8765`。 ### Linux 服务器(含 RISC-V) 项目根目录执行(脚本会自动检查依赖并沿用已激活的虚拟环境): ```bash cd /path/to/AI视力检查 bash start.sh # 前台运行,Ctrl+C 停止 bash start.sh daemon # 后台运行,写 server.log 与 server.pid bash start.sh stop # 停止后台服务 bash start.sh status # 查看状态 ``` 查看后台日志:`tail -f backend/server.log`。 如需指定解释器或端口:`VISION_PYTHON=/path/to/python VISION_PORT=9000 bash start.sh daemon`。 > 目录要求:`frontend/` 与 `backend/` 必须同级,脚本所在目录就是项目根目录。 > 若你把 `backend/` 单独放到了别处,请把 `frontend/` 一起放到它的上一级。 #### 远程访问必须用 HTTPS(否则摄像头被浏览器禁用) 从自己电脑用 `http://服务器IP:8765` 打开时,浏览器会判定为非安全上下文, 直接禁用摄像头,预览框会提示「当前页面无法使用摄像头」。服务端已内置 HTTPS, 无需装 Nginx: ```bash bash start.sh https # 前台 HTTPS bash start.sh https-daemon # 后台 HTTPS ``` 首次打开 `https://服务器IP:8765` 时浏览器会提示证书不安全(自签证书), 点「高级」→「继续访问」即可;之后摄像头权限正常,WebSocket 也会自动切到 WSS。 脚本会自动生成自签证书到 `certs/`,有效期 10 年,已包含 `localhost`、`127.0.0.1` 和本机所有网卡 IP。若你通过域名、公网 IP 或端口转发访问,需要把这些地址写进证书: ```bash VISION_SAN_DNS=eye.example.com VISION_SAN_IP=1.2.3.4 VISION_FORCE_CERT=1 \ bash start.sh https-daemon ``` 生产环境有正式域名时,更推荐用 Nginx + Let's Encrypt 证书反代到 `127.0.0.1:8765`,这样不会有证书告警。 > 临时方案:Chrome 打开 `chrome://flags/#unsafely-treat-insecure-origin-as-secure`, > 把 `http://服务器IP:8765` 加白名单后重启浏览器。仅限调试,不建议长期使用。 > 摄像头不可用时仍可用页面右下角的方向按钮手动作答,或勾选演示模式。 > > 若预览窗口黑屏,看预览框内的文字提示即可定位:`未启动/权限被拒绝` 多为浏览器 > 未授权;`未检测到摄像头设备` 为设备未连接;`被其他程序占用` 需关闭占用程序; > `无法使用摄像头` 则是通过普通 HTTP 远程访问导致(`mediaDevices` 被浏览器禁用)。 > 授权后可点预览框内的「重试摄像头」,无需重新走检测流程。 ### 手动启动 ```bash cd backend pip install -r requirements.txt python -m uvicorn main:app --host 127.0.0.1 --port 8765 ``` 然后浏览器访问 `http://127.0.0.1:8765`。 > 摄像头权限:首次进入检测页时浏览器会请求摄像头权限,请允许。若无法使用摄像头,可用界面右下角的方向按钮手动作答;也可勾选「演示模式」自动走完整流程。 ### 摄像头:接在浏览器设备 还是 接在服务器? 支持两种取流方式,自动按配置选择: | 模式 | 适用场景 | 配置 | |---|---|---| | 浏览器本地摄像头(默认) | 受试者坐在自己电脑/手机前 | 无需配置,页面会请求摄像头权限 | | **服务器摄像头** | 摄像头接在部署服务器上(一体机、开发板、监控位) | 设置 `VISION_CAMERA_SOURCE` | 浏览器出于安全限制,`getUserMedia` **只能读取浏览器所在设备的摄像头**,读不到服务器上的摄像头。 所以摄像头接在 192.168.3.26 这类服务器上时,必须用服务端摄像头模式:后台用 OpenCV 直接读摄像头,把画面推到左下角画中画显示,手势也在后台识别。此模式同样受 HTTP/HTTPS 限制影响较小(不依赖浏览器摄像头权限),但页面本身仍建议 HTTPS。 ```bash # 摄像头接在服务器上,自动探测 VISION_CAMERA_SOURCE=auto bash start.sh https-daemon # 明确指定设备节点或索引 VISION_CAMERA_SOURCE=/dev/video0 bash start.sh https-daemon VISION_CAMERA_SOURCE=0 bash start.sh daemon # 网络摄像头 VISION_CAMERA_SOURCE=rtsp://user:pass@192.168.3.26:554/stream bash start.sh https-daemon ``` Linux 下确认设备节点:`ls -l /dev/video*`。若提示无法打开,检查用户是否在 `video` 组 (`sudo usermod -aG video $USER`,重新登录生效)、设备是否被其他程序占用。 打开失败时画中画会显示原因,排查后可点「重试摄像头」原地重连。 其他可选参数:`VISION_CAMERA_FPS=10`、`VISION_CAMERA_WIDTH=640`、 `VISION_CAMERA_HEIGHT=480`、`VISION_CAMERA_MIRROR=1`(画面左右镜像)。 画面在后台以约 10fps 推给前端预览,手势识别按 1fps 进行,与浏览器模式逻辑一致。 前端手动方向按钮、演示模式在两种模式下都可用。 ### RISC-V / 无 MediaPipe 预编译包的平台(如 spacemit K1) MediaPipe 官方只提供 x86_64 / aarch64 的预编译包,在 RISC-V 上执行 `pip install mediapipe` 会报 `No matching distribution found`。本项目已把 mediapipe 设为可选依赖(`requirements.txt` 中默认注释),直接执行上面的 `pip install -r requirements.txt` 即可,不会再被它卡住。 此时后端会自动切换到**纯 OpenCV 手势识别**(肤色分割 + 轮廓 PCA),不需要 模型文件,检测、统计、历史查询功能完全一致。识别精度低于 MediaPipe,建议: - 手掌平伸、五指并拢,正对摄像头,背景简洁、光线充足; - 若识别不稳定,可用界面右下角方向按钮手动作答,或勾选演示模式。 需要强制使用 OpenCV 引擎时:`VISION_GESTURE_ENGINE=opencv python -m uvicorn main:app --host 127.0.0.1 --port 8765`。 如果想恢复 MediaPipe 精度,在有预编译包的平台上取消 `requirements.txt` 中 `mediapipe` 那行的注释即可。 ## 项目结构 ``` AI视力检查/ ├── frontend/index.html 单页前端(信息填写 / 检测 / 结果 / 历史) ├── backend/ │ ├── main.py FastAPI 服务、WebSocket 状态机、REST 接口 │ ├── server_camera.py 服务端摄像头采集(OpenCV,推流 + 识别) │ ├── gesture_detector.py MediaPipe 关键点识别 + OpenCV 兜底(自动切换) │ ├── vision_calc.py 字号序列、正确率与视力等级换算 │ ├── db.py SQLite 持久化 │ ├── models/hand_landmarker.task 手部关键点模型(随项目打包,离线可用) │ ├── requirements.txt │ └── smoke_test.py 端到端自测脚本 ├── start.bat 一键启动(Windows) ├── start.sh 一键启动(Linux,支持 HTTPS) └── README.md ``` ## WebSocket 协议 客户端 → 服务端: | type | 字段 | 说明 | |---|---|---| | `start` | name / gender / age / total / demo | 开始检测 | | `frame` | data(base64 JPEG) | 摄像头帧,1 帧/秒 | | `manual` | direction | 手动作答(备用) | | `skip` / `stop` | - | 跳过本题 / 提前结束 | 服务端 → 客户端: | type | 字段 | 说明 | |---|---|---| | `started` | total / gesture_available / demo | 会话已建立 | | `stimulus` | round / size_mm / size_px / direction | 下发当前字母 | | `detected` | direction / confidence | 实时识别状态 | | `feedback` | correct / expected / detected / source | 本题判定 | | `hint` | message | 长时间未识别到手势的提示 | | `finished` | result | 最终结果与记录编号 | REST 接口:`GET /api/config`、`GET /api/records?name=`、`GET /api/records/{id}`、`DELETE /api/records`。 ## 重要说明 - 真实临床视力表需要严格的光学标定、距离与照明控制。本项目按 1 米距离实现了**简化换算模型**(3mm 对应 1.0 / 5.0,字号每增大 10 倍视力降为 1/10),用于流程演示与相对比较,**不作为医学诊断依据**。 - 摄像头画面仅用于实时方向识别,按 1fps 传输,不落盘、不保存原始图像;仅保存统计结果与逐轮判定。 - MediaPipe C++ 层在 Windows 下无法打开中文路径,模型会在启动时被复制到系统临时目录后加载,不影响使用。 - 连续 2 帧识别到同一方向才采纳作答;换题后 1.5 秒内忽略手势,避免沿用上一题答案。