自助智能视力检测系统（EyeFocus）是一款融合智能算法、嵌入式硬件、无线交互的全自动视力筛查设备，以“无人值守、精准高效、自助便捷”为核心理念，致力于替代传统人工视力检测，打造智能化、标准化、低成本的视力筛查新方案，助力青少年近视防控与医疗体检智能化升级。
EyeFocus 基于 Godot Engine 4.6 开发，严格遵循 GB 11533-2011 国家标准对数视力表（E 字视标），在屏幕上实现物理精确的视力测量，并支持热敏打印机输出标准化报告。
- 🔥 国标级测视算法：内置像素级视标校准算法与自适应阶梯检测算法，实现全自动、无人工判读的精准视力检测。
- 🔥 嵌入式热敏打印：自研专用驱动电路，集成 EM5820H 热敏打印机，检测完成后自动输出标准化视力报告。
- 🔥 双模式无线交互：支持蓝牙体感枪（AriGun）与远程控制键盘双模式，受检者全程自助响应，无需医护人员干预。
系统具备零人工干预、检测精准、效率极高、部署灵活、数据可追溯等优势，适配医院诊前分流、体检中心自助检测、校园大规模筛查、社区公益检测与家庭日常自测，应用场景广泛。
| 特性 | 说明 |
|---|---|
| 标准对数视力表 | 14 级标准（0.10 ~ 2.00），严格遵循国标 |
| 物理精确算法 | 根据显示器尺寸、分辨率、距离精确换算视标像素 |
| DPI 自适应 | 自动读取窗口物理像素，缩放显示器也能精确换算 |
| 双 / 单眼模式 | 左眼、右眼独立测试，数据分开记录 |
| 自适应网格 | 视标网格动态排列，智能计算行列数与间距 |
| 防猜测判据 | 单等级累计答对 10 次方判定，随机蒙对概率极低 |
| 自适应阶梯 | 连续答对 3 次升级（变小），答错 2 次降级（变大） |
| 专注全屏模式 | 一键隐藏 UI 与光标，全屏仅视标，沉浸测试 |
| 深色 / 白天主题 | 一键切换深色与浅色配色 |
| 参数校准 | 自定义显示器尺寸、分辨率、测试距离 |
| 热敏打印 | 支持 EM5820H 串口打印机输出报告（含模拟模式） |
| 红圈呼吸 | 目标视标由红色呼吸动画圆环标记 |
极简风格，三分栏横屏布局，1280 × 720 分辨率，支持深色 / 白天双主题。
- Godot Engine 4.6+（推荐 .NET 版本）
- 任意支持 Godot 4 的操作系统（Windows / macOS / Linux）
- 热敏打印（可选）：EM5820H 串口打印机
git clone https://github.com/Euler-lne/eye-focus.git
cd eye-focus
# 用 Godot 4.6 打开项目根目录的 project.godot，按 F5 运行仓库 realse/ 目录已包含导出产物，可直接使用：
realse/windows/EyeFocus.7z— Windows 独立可执行文件realse/web/EyeFocus.html— Web 版本（浏览器直接运行）
在 Godot 编辑器中选择 项目 > 导出，按需配置导出模板即可生成独立可执行文件或 Web 版本。
① 选择模式 → ② 参数校准 → ③ 遮挡眼睛 → ④ 判断朝向 → ⑤ 按键作答 → ⑥ 打印报告
- 启动应用后，在左侧面板选择检测模式（左眼 / 右眼 / 双眼依次）。
- 点击「参数校准」输入显示器对角线尺寸与测试距离。
- 根据提示遮挡相应眼睛，与屏幕保持 5 米标准距离。
- 观察中央区域被红圈标记的 E 字视标，判断开口方向。
- 使用方向按钮或键盘快捷键作答。
- 测试完成后点击「生成最终结果」，连接打印机一键打印报告。
| 按键 | 功能 |
|---|---|
| W / ↑ | 开口朝上 |
| A / ← | 开口朝左 |
| S / ↓ | 开口朝下 |
| D / → | 开口朝右 |
| ESC | 退出专注模式 |
- 左眼模式 — 仅测试左眼，请遮挡右眼；切换时仅清空该眼累计计数。
- 右眼模式 — 仅测试右眼，请遮挡左眼。
- 双眼依次 — 先测左眼再测右眼，数据分别记录；某眼达标后自动切换至另一眼并重置为 1.0。
为确保视力结果准确，测试前务必校准！
物理像素密度（px/mm）由显示器对角线尺寸与分辨率共同决定，直接影响视标物理尺寸换算，校准错误会导致视力结果偏差。需要填写：
- 显示器对角线尺寸（英寸）
- 屏幕分辨率（宽 × 高，应用会自动读取窗口物理像素并填入）
- 测试距离（米，建议 5 米）
提示：默认 24 英寸、当前窗口分辨率、5 米。笔记本电脑或小尺寸显示器请务必手动测量对角线后填写。窗口大小改变时，应用会自动重新读取物理分辨率并重新校准。
点击「专注模式」隐藏所有 UI 面板和鼠标光标，全屏仅显示视标，适合远距离沉浸测试。按 ESC 退出。
应用内置对 EM5820H 热敏打印机的支持，通过串口连接后即可打印格式化视力报告：
EyeFocus
专业视力自测报告
================
时间: 2026-05-21 14:35
标准: GB11533 距离:5m
================
左眼视力: 1.00
右眼视力: 1.00
================
正常视力 >= 1.0
视力正常 定期复查
================
仅供参考
如有异常请就医
未检测到打印机时自动切换为终端模拟模式，在控制台输出相同格式的报告，便于无硬件调试。
EyeFocus 的检测精度与可靠性建立在四套核心算法之上：国标视标尺寸换算决定“画多大”，自适应阶梯 + 累计达标判据决定“测多准”，自适应网格布局决定“怎么排”，ESC/POS 打印协议决定“怎么打印”。
视力的本质是最小分辨角：标准视力 V=1.0 时，眼睛能分辨 1 角分（1/60 度）所对应的细节。E 字视标采用 5×5 栅格设计，笔画宽度（即开口宽度）恰好对应这个最小分辨角。
笔画宽 (mm) = tan( (1/60)° / V ) × 测试距离 (mm)
视标边长 (mm) = 5 × 笔画宽 （5×5 栅格，5 个等宽单元）
像素密度 px/mm = √(宽² + 高²) (px) / (对角线英寸 × 25.4)
视标边长 (px) = 视标边长 (mm) × 像素密度 (px/mm)
实现见 VisionCalculator.gd。像素密度由屏幕对角线像素数与物理对角线毫米数之比求得，因此校准参数必须准确。
验证：V=1.0、距离 5 m → 视标边长 ≈ 7.272 mm，与国标规定完全吻合。
为支持高 DPI / 缩放显示器，应用通过 DisplayServer.screen_get_scale() 将逻辑窗口尺寸换算为真实物理像素（Main.gd:166），保证缩放环境下视标尺寸依然精确，并在窗口尺寸变化时自动重新校准。
这是 EyeFocus 区别于传统“逐行往下读”视力表的核心。它由两套并行机制组成（VisionLevelManager.gd）：
1. 视标大小的动态调整（阶梯策略）
| 触发条件 | 动作 |
|---|---|
| 连续答对 3 次（且非最高级） | 升级一档，视力值增大、视标变小 |
| 连续答错 2 次（且非最低级） | 降级一档，视力值减小、视标变大 |
14 级标准对数视力表（默认从 1.0，即第 10 级开始）：
0.10 → 0.12 → 0.15 → 0.20 → 0.25 → 0.30 → 0.40 → 0.50
→ 0.60 → 0.80 → 1.00 → 1.20 → 1.50 → 2.00
阶梯策略让测试始终围绕受检者的真实视力水平快速收敛，只影响当前视标大小，不直接决定最终结果。
2. 最终视力的确定（累计达标判据）
- 每个视力等级独立累计答对次数，每答对一次该等级计数器 +1（答错不清零累计计数，只清零连续计数）。
- 当某等级累计答对达到 10 次（
CORRECT_THRESHOLD）时，该等级即被判定为该眼最终视力。 - 若多个等级同时达标，取最高等级。
- 左右眼计数器完全独立存储，互不影响。
为何用“累计 10 次”而非“连续”？
- 抗随机猜测：E 字四方向纯随机蒙对单次概率 1/4，在某一等级累计蒙对 10 次的概率极低（≈ 0.25¹⁰ ≈ 0.0001%），有效排除运气成分。
- 允许失误：不要求连续，偶尔答错不会重置累计进度，更贴合真实测试场景。
双眼依次模式收敛流程（Main.gd:398）：
左眼从 1.0 开始 → 阶梯升降 + 后台累计
↓ 某等级累计满 10 次
记录左眼最终视力 → 切换右眼、计数清零、等级重置为 1.0
↓ 右眼某等级累计满 10 次
记录右眼最终视力 → 自动弹出结果窗口
双眼依次并非简单取两次独立测量的平均值，而是依靠阶梯策略与累计达标判据获得更稳定、更符合实际视力水平的结果。
重置与切换规则：
- 重置测试：左右眼所有等级累计计数清零，当前等级恢复 1.0，连续正确/错误计数清零。
- 单眼模式切换：仅清空目标眼的累计计数，另一只眼状态保留。
E 字视标绘制（EyeChart.gd）：基于 Godot _draw() 用矩形拼出标准 5×5 栅格 E 字，根据开口方向（上/下/左/右）绘制对应的笔画组合，笔画宽恰为边长的 1/5，严格符合国标比例。
自适应网格布局（OptotypeContainer.gd）：为避免单个视标过于孤立、便于受检者聚焦，中央区域会铺满多个随机方向的视标，再用红圈标记目标。布局算法：
- 依据容器尺寸、视标边长、最小间距与边距，计算理论最大行列数。
- 从大到小试探行列组合，求出能完全容纳的最优行列数，并动态计算实际间距以充分利用空间。
- 网格整体居中，浮点安全校验防止溢出。
- 随机选定一个视标作为目标，红圈以呼吸动画（正弦振荡）环绕标记。
- 每次刷新通过
reselect_target_except()确保新目标方向与上一次不同，避免连续相同方向被记忆。
PrinterManager.gd 通过 GdSerial 串口插件（115200 波特率）向 EM5820H 发送 ESC/POS 指令：
- 指令封装：初始化
ESC @、对齐ESC a、加粗ESC E、字号GS !、走纸ESC d、切纸GS V、打印浓度ESC 7等。 - 分块节流：报告按“标题区 / 信息区 / 左眼 / 右眼 / 参考区 / 走纸切纸”分块发送，每块之间
await等待CHUNK_DELAY，防止打印机缓冲区溢出导致截断。 - 中文编码：内置常用汉字的 GBK 码表，将报告中文字符逐字转为 GBK 双字节，ASCII 字符直传，未收录字符以
?占位。 - 智能建议：依据左右眼最差视力分级输出建议（正常 / 轻度下降 / 中度下降 / 明显下降）。
- 模拟模式：未检测到串口插件或未连接时，自动降级为终端输出，保证无硬件也能演示完整流程。
eye-focus/
├── project.godot # 项目配置
├── icon.svg # 应用图标
├── index.html # 项目展示网页（含演示视频）
├── export_presets.cfg # 导出预设
├── font/
│ └── SourceHanSansSC-Regular-2.otf # 思源黑体
├── scenes/
│ └── main.tscn # 主场景 UI 布局
├── scripts/
│ ├── Main.gd # 主控制器：UI 协调、主题、信号、校准
│ ├── EyeChart.gd # E 字视标渲染（5×5 栅格四方向）
│ ├── OptotypeContainer.gd # 视标网格容器与红圈呼吸动画
│ ├── TestController.gd # 答题验证与视标刷新
│ ├── VisionCalculator.gd # GB 11533 视标像素换算
│ ├── VisionLevelManager.gd # 14 级标准表、阶梯与累计达标算法
│ ├── PrinterManager.gd # EM5820H ESC/POS 串口打印
│ └── CalibrationPanel.gd # 校准面板
├── addons/
│ └── gdserial/ # GdSerial 跨平台串口通信插件
├── realse/ # 导出产物（Windows / Web）
├── videos/ # 演示视频
└── imgs/ # 截图与电路图（EyeFocus.pdf）
| 模块 | 文件 | 职责 |
|---|---|---|
| 主控制器 | Main.gd |
UI 协调、事件处理、主题切换、信号转发 |
| 视标渲染 | EyeChart.gd |
_draw() 绘制标准 E 字，四方向开口 |
| 网格布局 | OptotypeContainer.gd |
动态行列计算，红圈呼吸动画，目标去重 |
| 测试流程 | TestController.gd |
答题验证、状态更新、视标刷新 |
| 视力计算 | VisionCalculator.gd |
GB 11533 公式，DPI 像素换算 |
| 等级管理 | VisionLevelManager.gd |
14 级标准表，阶梯 + 累计 10 次判定 |
| 打印管理 | PrinterManager.gd |
EM5820H ESC/POS 串口打印，终端模拟 |
键盘 / 按钮 → Main._on_answer()
→ TestController.process_answer()
├─ VisionLevelManager.record_correct / record_wrong （更新计数与等级）
│ └─ signal eye_final_vision_determined （达标 → Main 切眼 / 出结果）
└─ OptotypeContainer.refresh() （按新视力重绘视标网格）
仓库 videos/ 目录内已包含录屏与真人演示，index.html 展示页也已嵌入：
videos/screen_record.mp4— 屏幕录制，含参数校准、单眼/双眼检测流程与打印示例。videos/live_demo.mp4— 真人操作示范。
| 项目 | 说明 |
|---|---|
| 引擎版本 | Godot 4.6 |
| 开发语言 | GDScript（纯原生） |
| 渲染器 | GL Compatibility |
| 分辨率 | 1280 × 720（横屏 16:9） |
| 拉伸模式 | canvas_items |
| 视力标准 | GB 11533-2011 / ISO 8596 |
| 打印机 | EM5820H 热敏打印机（串口 115200） |
| 打印协议 | ESC/POS + GBK 中文编码 |
| 串口插件 | GdSerial v0.3.0（跨平台） |
| 运行平台 | Windows / macOS / Linux / Web |
本项目仅供学习和个人使用。如需商用请咨询作者。