Eye Illumination Web Lab

用于小鸡、儿童和成人眼后极照明参数研究的本地 Web 程序，支持参数计算、批量扫描、报告导出和 Ansys Zemax OpticStudio 验证。

程序是本仓库的主体；MCP 只是可选的二级自动化接口。

1. Windows 三分钟启动

需要安装

• Windows 10 或 11（64 位）

• Python 3.11 或更高版本（64 位）

• Git 和 Git LFS

• 可访问 GitHub 的网络连接（仓库为公开仓库，克隆无需登录）

交互计算不需要 OpticStudio。只有执行 Zemax 验证时才需要已安装并授权的 OpticStudio。

第一次使用

在 PowerShell 中运行：

git lfs install
git clone https://github.com/dongzhaohe321418-lab/zemax-mcp.git
cd zemax-mcp
git lfs pull
.\experiments\eye_illumination\setup_web_gui.cmd

安装脚本会：

1. 在程序目录创建独立的 .venv；

2. 安装固定范围的 NumPy 依赖；

3. 检查 Python 与 NumPy；

4. 启动本地服务器并打开浏览器。

本仓库为公开仓库，克隆和 git lfs pull 无需 GitHub 登录。如果克隆失败，请先检查能否访问 https://github.com，并确认 Git LFS 已正确安装。

以后启动

双击：

experiments\eye_illumination\launch_web_gui.cmd

也可以在 PowerShell 中运行：

.\experiments\eye_illumination\launch_web_gui.cmd

程序地址是 http://127.0.0.1:8765/。右上角可在中文与 English 之间即时切换，动态计算、图表、Zemax 向导和 PDF 报告链接会同步切换。服务器只监听本机回环地址，不把实验参数发送到云端。关闭启动窗口或按 Ctrl+C 即可停止。

Related MCP server: COMSOL MCP Server

2. 最简单的使用流程

1. 选择“固定三焦距基准”或“PPT 参数范围探索”。

2. 选择眼模型、固定焦距、瞳孔和 60–120 D 物方需求。

3. 点击“运行当前工况”，查看候选光源尺寸、边缘角和工作 F 数。

4. 按需下载当前 JSON、结果 CSV 或全部 252 工况。

5. 需要 Zemax 复核时，继续使用页面底部的三步验证向导。

程序不会根据物距自动改变眼球等效焦距。固定焦距、眼轴、瞳孔、物距和可选外置负镜始终是相互独立的输入。

3. 在 OpticStudio 中验证

前置条件

• Windows 64 位 Python 3.11+

• 已安装并授权的 Ansys Zemax OpticStudio

• 安装目录中存在 ZOSAPI.dll、ZOSAPI_Interfaces.dll 和 ZOSAPI_NetHelper.dll

• Windows .NET Framework 64 位 C# 编译器

网页内三步验证

1. 滚动到“04 Zemax 验证向导”。

2. 点击“自动检测 OpticStudio”。这一步只读，不启动 Zemax，也不声称许可证有效。

3. 勾选确认框，点击“运行 1 工况连接测试”。

4. 等待 PARAXIAL PASS · 一致性通过。

5. 连接测试通过后，再运行当前结果表并下载证据 ZIP。

证据包包含输入、模型快照、OpticStudio 版本、许可证状态、结果 CSV、保存的 .zos 系统、独立校验报告和 SHA-256；不包含机器构建目录或原始日志。

PARAXIAL PASS 只证明解析 ABCD 模型与理想 OpticStudio Paraxial 面一致，不代表真实眼、绝对辐照度、光安全或生物学结果通过。完整步骤见《Zemax 连接与审计指南》。

4. 当前验证状态

模型适用性审计发现：252 个工况的最大源边缘—瞳孔边缘角均为 15.02°–37.59°，全部触发项目设置的 10° 真实光线复核线；140 个工况的工作 F 数低于 4。因此，当前结果适合用于候选机械空间、参数筛选和下一阶段真实模型设计，不能直接作为活体曝光设置。

5. 结果、报告与证据

6. 版本兼容性

• Web 计算程序支持 Windows 上的 Python 3.11+，不依赖特定 OpticStudio 版本。

• ZOS-API 实机证据来自 OpticStudio 24.1.0。

• 其他 OpticStudio 版本如果仍提供上述三个 ZOS-API DLL，通常可以由程序自动发现，但必须先通过“1 工况连接测试”，不能沿用旧版本的许可证或数值结论。

• 程序不会把 DLL 存在等同于许可证有效；许可证状态只由真实 ZOS-API 运行确认。

7. 常见问题

8. 开发与完整复现

普通用户不需要执行本节。

py -3.11 -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -e ".[dev,analysis]"
python -m pytest -q

包含许可版 OpticStudio、Notebook 和 HTML 报告的完整工作流：

powershell -ExecutionPolicy Bypass -File experiments\eye_illumination\run_all.ps1 `
  -OpticStudioDir "C:\path\to\installed\OpticStudio"

中英文 LaTeX/PDF 一次构建：

powershell -ExecutionPolicy Bypass -File experiments\eye_illumination\report\latex\build_report.ps1

脚本会生成并自检两份报告：25 页中文宋体版和 22 页英文版，同时检查 A4 页面、字体嵌入、关键文字、图片数量、引用和版面越界。

完整工作流会启动许可版 OpticStudio；运行前请保存其他 OpticStudio 工作并确认许可证可用。

9. 可选 MCP 自动化

MCP 不是运行本实验程序的必要条件。需要从 Codex、Claude Code 或其他 MCP 主机调用受限光学工具时，请阅读《可选 MCP 使用指南》。

10. 仓库结构

experiments/eye_illumination/      主程序、模型、结果、报告和 Zemax runner
experiments/eye_illumination/app/  本地 Web GUI 与三步 Zemax 验证向导
experiments/runs/                  不可覆盖的实验记录
experiments/artifacts/             Git LFS 管理的 Zemax/二进制证据
tests/                             模型、Web、批次和安全边界测试
backend/ + server.py               可选 MCP 接口
scripts/                           诊断和实验记录工具

每个重要实验里程碑都必须新增不可变记录、保存相关证据、运行测试并推送 GitHub；详细规则见 AGENTS.md。