# 光圈形态与位置 Benchmark cases

版本：`0.2.0-halo-draft`。目标是让 Agent 对术后可能出现的光圈作**可量化、可反事实检验的预测**。不是每位术后患者、每种照明都会出现光圈；圆环、弧段、宽光晕、光芒和反射鬼像也不能当作同一种现象。

本次新增 **14 个可运行成对病例 / 28 个条件 + 6 个研究病例**。可读输入与任务要求在 `tasks/halo_cases.json`；源定义在 `iclbench/halo_cases.py`。前 14 例的真值限于给定合成模型；后 6 例不使用薄相位模型冒充真实 ICL 真值。

## 1. Agent 到底需要预测什么

每个光源分别报告：

| 预测量 | 定义 |
|---|---|
| 灯芯位置 | 光源主像的位置；与输入光源角度分开记录 |
| 光圈中心 | 相对于注视点的 `(x,y)`；不能用整图亮度质心自动替代 |
| 相对偏移 | 光圈中心减灯芯位置；与整个图样的棱镜平移区分 |
| 半径/宽度 | 圆环可报半径及径向 FWHM；非圆形报方向半径、轮廓或长短轴及适用性 |
| 完整性 | 完整圆、弧段、断裂/多环；若只有一段弧，不强行声称观测到完整圆 |
| 方位亮度 | 沿不同角度的能量分布、明暗不均及热点 |
| 环数/环峰 | 按注册峰检测规则报告，不能将每个噪声峰都算一环 |
| 能量与对比 | 环带能量、灯芯/背景对比；保留线性数值和统一显示条件 |
| 可见性与不确定度 | 区分光学信号、指定阈值下的可检出性和患者感知；信息不足则输出区间或 unknown |

复杂病例的正确答案可以是“不存在稳定单圆拟合”“多个峰融合”“不能唯一确定中心”。渲染图和结构化预测应相互一致。真实感知病例应采用预注册心理物理测量，不能直接由图像阈值宣称可见概率。

## 2. 固定坐标，防止位置题被错误评分

可运行集使用**等效观察角切平面**：注视点为 `(0,0)`，向右为 `+x`、向上为 `+y`，单位 arcmin；1 arcmin = 60 arcsec。数组列增加为 `+x`，行增加为模型 `+y`，图库因此在显示时上下翻转。每图 512×512，4 arcsec/像素，视场约 34.1×34.1 arcmin。

所有病例都记录输入光源角位置、主像/环位置及二者差值。不自动将光源或 PSF 重新居中，也不做逐图归一化曝光。完整眼的专业病例需要额外校准视网膜倒像到视觉坐标的映射；这里的符号并非未经验证的人眼视网膜解剖映射。

当前模型是局部等晕、平移不变模型。H01/H14 的光源移动是已声明模型内的平移测试；不能据此声称真实离轴 ICL 光圈只是整幅图平移。真实离轴传播由 R16 考察。

## 3. 十四个可运行病例

通用参数：均匀圆瞳孔 3.2 mm、550 nm、等效光焦度 `+8/-8 D`、光学区 6 mm、无孔、无散光、无偏心。仅在表中指定处修改。参数都是合成输入，不是某患者或厂家的设计。

| ID | 具体对照 | 要求的预测 | 可检验答案或判据 |
|---|---|---|---|
| H01 | 点光源 `(0,0)` → `(3,-2)` arcmin | 环中心、相对灯芯偏移、形态 | 在这个等晕校准模型中整体平移 `(3,-2)`，环半径不变；不能仍画在图心 |
| H02 | 两点光源 `(-1,0)/(1,0)` → `(-4,0)/(4,0)`；孔 0.36 mm | 两组光晕的中心、重叠区域与各自贡献 | 保留两个独立光源贡献，线性相加；不把重叠亮区解释为第三个独立光源环 |
| H03 | 450 → 650 nm；无像差圆孔 | 首衍射亮环半径和宽度 | 首亮环约 `0.7904 → 1.1417 arcmin`；尺度比 `650/450`，不预设临床孔相关环同样变化 |
| H04 | 瞳孔 2.8 → 4.8 mm；无像差 | 首衍射亮环半径和宽度 | 半径约 `1.1041 → 0.6440 arcmin`；这是纯衍射对照，不能推广为所有术后光晕规律 |
| H05 | 入射总能量 0.25 → 1 | 同一环的几何、线性亮度及阈值问题 | 全部线性像素乘 4，几何不变；曝光与感知阈值另行说明 |
| H06 | 点光源 → 直径 1.5 arcmin 的均匀非相干圆盘；总能量相同 | 环的模糊、融合及是否仍可分辨 | 对有限光源积分/卷积；不强制规定必有一个锐利圆环，不用后期 bloom 替代传播 |
| H07 | 等效 ICL 功率 -8 → -7.5 D | 径向多峰、宽度、能量转移 | 由相位改变计算二维图和径向曲线；不给未经验证的“离焦一定产生某半径圆环”答案 |
| H08 | 0.75 D 柱镜，轴 0° → 45° | 不圆形结构、方位亮度及方向变化 | 比较二维场和角向剖面；不能用单一径向平均抹平散光，也不要求形态必是一个椭圆 |
| H09 | 无孔理想矫正，ICL 偏心 x:0 → 0.2 mm | 绝对位移与环相对灯芯偏移 | 本等效模型为纯棱镜对照，图样向 -x 移约 `5.5004 arcmin`，环与灯芯仍共心；半径约 0.9661 arcmin |
| H10 | 透明孔 0 → 0.36 mm | 弱光晕差分、径向结构和通光能量 | 孔透光但不接受材料区矫正相位，瞳面通光率不因黑盘遮挡而下降；不把结果当真实孔壁环真值 |
| H11 | 孔 0.36 mm、柱镜 0.35 D/20°；偏心 `(0,0)` → `(0.15,0.10)` mm | 整体位移、非对称性、角向热点 | 保留二维结构；允许多峰/不唯一中心，不要求一个固定圆 |
| H12 | 550 nm → 450/550/650 nm，权重 0.2/0.5/0.3 | 多尺度叠加后的峰、宽度与对比 | 在共同角网格非相干叠加强度；没有材料色散/颜色知觉模型，不能直接报患者看见的色名 |
| H13 | 入射光源能量 0 → 1 | 有没有可归因于外部光源的光圈 | 无源时本理想光学模型输出严格零；不能默认每例都有光圈。未模拟暗噪声或内源性视觉现象 |
| H14 | 光源 `(0,0)` → `(16.5,0.5)` arcmin | 可记录弧段、完整环的几何、缺失能量 | 首环部分出探测窗口；报告记录覆盖比例，不回卷到另一侧；探测器裁切不等于人眼真实视野缺失 |

### 为什么选这些对照

H01/H09 用来区分**环固定在屏幕、跟着灯芯移动、相对灯芯偏心**三种不同判断。H03/H04/H05 同时检查尺度与辐射度定律，能揭穿固定圈素材。H06/H08/H11 强制处理非理想和非圆形结构。H02 防止把叠加光场误读为单个环。H13 是明确的无光学信号负例。H14 防止把裁切和 FFT 回卷误作物理光圈。

## 4. 可用解析真值，不能混淆亮环和暗环

对均匀圆孔、单色、无像差、远场条件：首暗环角半径约 `1.22 λ/D`；**首个旁瓣亮环**约 `1.635 λ/D`。H01 等校准病例使用后者。550 nm、D=3.2 mm 时首亮环半径约 0.9661 arcmin。这是光学公式下的校准特征，不是患者 ICL 术后出现的大环的尺寸预测。

环宽在本轨道定义为径向强度峰的 FWHM，位置以固定角坐标表示。对多峰、散光、弧形或偏心结构，不调用单圆拟合给出一个虚假精确半径。

参考的校准环测量器仅适用于已声明的共心圆对照：用中央主像局部强度估计中心，在解析首亮环附近检测有显著性的局部峰，并报告半高宽和探测窗覆盖比例。它不是通用的真实 ICL 光圈检测器。复杂病例保存完整二维场、96 个半径和72 个角度的剖面，不强制给环标签。

## 5. 六个直接面向真实术后问题的研究病例

这些病例已写成任务卡，但**没有填入伪造数值答案**，不计入当前合成分数。

| ID | 临床/专业问题 | 决定形态位置所必需的输入 | 真值建立方式 |
|---|---|---|---|
| R15 | 中央孔相关的环到底在哪里 | 厚 ICL 前后曲面、孔壁、材料、全眼结构及源角度 | 独立非顺序路径/波动模型 + 模型眼实测；通孔/填充/无孔消融 |
| R16 | 灯不动、改变凝视，光圈怎么走 | 世界光源坐标、眼球姿态和旋转中心、厚全眼、视觉角映射 | 多视场扫描，分别报告注视坐标与相对灯芯轨迹 |
| R17 | 暗处瞳孔变大，出现整环还是弧 | 瞳孔大小及中心、实际光学区和周边/支撑几何 | 边缘/孔壁/反射分别消融 + 光学台 |
| R18 | 反射路径能否形成另一组鬼像/环 | 界面曲率、反射率/镀膜、带宽、路径能量 | 独立 Fresnel 分光路径与单界面关闭实验 |
| R19 | 宽光晕来自散射、泪膜还是结构 | 同眼重复测量、独立散射/泪膜参数、标定曝光 | 机制正交干预与模型失配诊断；单图可能多解 |
| R20 | 患者感到的环，是否等于光学计算图 | 获准的结构测量、校准心理物理记录、术后时间、单/双眼条件 | 预注册感知匹配/绘图实验、患者分组留出及专家审核 |

真实全眼病例的视场必须覆盖预期环及杂散光范围，不能把当前约 34 arcmin 的合成输出窗口默认为充分。缺少产品曲面时可使用明确标注的合成厚设计，不能编造厂家参数。

外部文献在本次尝试中仍被 `/browse` 地址安全检查阻断；上述研究卡是实验设计，不是已从论文核验的病例库或机制发生率结论。

## 6. 可运行集的提交与自动评分

每条件交 `<id>.npz`：

- `components`：`[光源数,512,512]`，每个光源的线性贡献，包含输入 flux，不逐图归一化。
- `scene`：`[512,512]`，严格等于贡献之和。
- `angular_pixel_arcsec`：标量 4。

多源病例必须保留来源归因。负能量、NaN、未声明能量增益、尺寸/采样错误或场景与贡献不一致均计该条件 0 分。缺失条件计 0，分母不缩小。

评分从原始数组计算，显示图不参与数值评分：

| 项 | 权重 | 误差尺度 |
|---|---:|---:|
| 固定角坐标全图 L1 / 参考能量 | 25% | 0.10 |
| 主瓣外光晕区域 L1 / 参考光晕能量 | 35%；复杂场 45% | 0.30 |
| 固定锚点极坐标光强差，按半径积分权重 | 15% | 0.30 |
| 有限探测场光强质心误差 | 10% | 0.10 arcmin |
| 记录能量相对误差 | 5% | 0.03 |
| 共心校准环中心与半径相对误差 | 10%；复杂场不使用 | 0.10 |

每项采用 `exp(-误差/尺度)`。质心指标用于约束整体位置，**不将质心声称为一般病例的环中心**。校准环几何以采样参考测量作数值对照，独立解析期望另外保存/检验。无源条件按原始漏光能量评分；零源强条件也不得生成外部光源光圈。

两条件的差分以未归一化光源贡献计算，按参考差分 L1（下限0.002）归一；成对分为 `100 exp(-差分相对误差/0.30)`。每病例 `70% 两条件均分 + 30% 成对分`，14 病例等权。上述尺度为开发选择，未经临床阈值或真实 Agent 排序校准。

复杂场的几何解释、预测区间及真实病例仍需独立物理/专家审核。本自动分数只叫 `halo_development_score`，`clinical_score` 与 `professional_score` 为 null。不能把它发布为真实患者光圈预测准确率。

### 核心数值处理

生成参考时，传播支持窗口至少覆盖探测半宽 + 最大光源平移 + 扩展光源半径，再进行线性卷积/平移和最终探测窗裁切。避免先把 PSF 裁得太小，丢失本该进入窗口的远端光强。所有卷积补零，不使用周期回卷。仍需通过采样、探测角分辨率与支持窗口的独立收敛研究确认最终精度。

## 7. 运行

```sh
python -m iclbench halo-generate --output halo-release
# 打开 halo-release/gallery/index.html；仅供评测方看答案和病例对照

# 格式自检，不能算模型成绩
python -m iclbench halo-baseline --release halo-release --output runs/halo-reference
python -m iclbench halo-evaluate --release halo-release --submission runs/halo-reference --output runs/halo-reference/score.json

# 三种错误模型：位置错、只算灯芯、画固定圆环
python -m iclbench halo-baseline --release halo-release --output runs/halo-wrong-position --mode wrong-position
python -m iclbench halo-baseline --release halo-release --output runs/halo-no-halo --mode no-halo
python -m iclbench halo-baseline --release halo-release --output runs/halo-fixed-circle --mode fixed-circle
```

给参评 Agent 的只有 `halo-release/public/`。`private/`、图库、参考实现和可由其直接生成答案的环境不可同时向从头建设轨道开放。当前发布的是公开开发集，不是保密模型榜单测试。拆分时将同一病例及所有对照放在同一 split，避免成对答案泄漏。

专业结构化预测格式见 `tasks/halo_prediction_example.json`。自动评分当前只读取线性数组；自由形态轮廓、语义环数、可辨识性与感知预测需要另行审核，不冒充已经实现的临床自动评分。