EXP-MEASUREMENT-PLANNING-ORACLE-V1 协议（MEASUREMENT_PLANNING_TASK_V1）
目的： 这是 BUDGETED-MEASUREMENT-PLANNING 研究线的第一阶段，即 oracle 余量审计。设定是 RGB 与相机免费、深度测量有预算。要检验的是："在哪些帧上请求深度"这个决策，是否存在简单启发式没有吃掉的余量。本阶段不训练任何模型。
判定规则见 preregistration.md，机器可读的契约在 task_contract.json、information_contract.json、baseline_contract.json、scene_manifest.json、frame_role_lock.json。
1. 任务
- episode： 一条记录加一个上下文角色（A 或 B）。
- 初始上下文： 该角色的 3 个 RGB-D 帧（
context_a或context_b，含共享的 anchor 帧），在任何决策之前融合。 - 候选池：
- 记录中不属于任何角色的帧，按帧序排列：不是两个角色的上下文、不是查询，也不是 stream、ignored、far_query；
- EVAL-V3/V4、EVAL-FAR、Replica、DEV 的每条记录都是 9 帧；
- 两个角色共用同一个池。
- 动作： 对候选帧请求深度（REQUEST_DEPTH），共 K 次。后端对所选帧取并集，所以请求顺序不影响最终重建。
- 预算： 主判定 K ∈ {1, 2, 4}；预算曲线 K = 0 到池的大小。
- 查询： 主分析用
primary_query的 2 帧；EVAL-FAR 的次要分析用far_query的 2 帧。 - 信息设定（离线）：
- 轨迹已知，全部候选帧的 RGB 与相机在决策前都可见；
- 逐帧到达、看不到后续帧的在线设定留到以后；
- 离线设定给启发式更多信息，所以对"存在余量"这一结论是保守的。
- 可部署策略能看到： 初始上下文的 RGB、深度与相机；全部候选帧的 RGB 与相机；已请求候选帧的深度。
- 可部署策略看不到： 未请求候选帧的深度；查询帧的 RGB、深度与相机；另一个角色的上下文帧；任何 oracle 输出。
- 强制方式：
MeasurementEnv只持有一份净化过的记录，其中只有本角色的上下文帧和候选帧，查询帧根本不在其中。request_depth检查候选身份、不重复和预算，每一次读取都按用途写入访问记录，并在计算阶段逐一审计。
2. 重建后端（冻结、无模型）
- 重建： 所选候选帧与初始上下文的全部测量点，用冻结的 1 像素 z-buffer 重投影到查询相机，再用冻结的调和补洞（REPROJ_HARMONIC）填补空洞。
- 实现： 用到的函数全部从冻结脚本导入，不改写：
run_rgbd_geometric_baselines.py的context_points、reproject，run_rgbd_inpaint_baselines.py的harmonic_fill、ray_cosine、near_mask。 - 计算方式： z-buffer 逐像素取最小值，所以每帧先单独重投影一次，任意子集取这些图的逐像素最小值。合成场景上的测试确认，这与把多帧拼在一起重投影逐位相同。
- K=0 复核： 结果必须与
~/cv_work/depthsplat/probe_eval34、probe_dev中封存的 REPROJ_HARMONIC 一致：最大绝对差不超过 1e-9 m，NEAR 掩码完全相同。DEV 彩排的实测最大差为 7.1e-15 m。 - 区域： NEAR 与 FAR 由初始上下文的命中像素按冻结的 8 像素规则确定，对所有子集保持不变。
- 覆盖率：
coverage_all：有效查询像素中，离任何已测命中点不超过 8 像素的比例；coverage_far：初始 FAR 像素中满足同一条件的比例。
- 完全没有命中时的常数： TRAIN 常数 2.3736 m，读自 V17 训练契约。
3. 指标与聚合
- AbsRel： 按 arms 评估器的方法，在 GT 有效像素上计算 ALL、NEAR、FAR 三个区域。
- 聚合： episode 的值是其查询的平均，场景的值是两个角色的平均，统计单位是场景。
- 主指标： ALL AbsRel。
- bootstrap： 10,000 次，种子 20260928，使用项目的
describe与paired。报告均值、中位数、95% 区间、变好/持平/变差的场景数、LOSO，以及排名前 1、前 3 的场景贡献占比。
4. 方法
可部署的选择规则（10 个），只通过 MeasurementEnv 行动，打平时取较早的帧：
| 名称 | 定义 |
|---|---|
| UNIFORM | 候选序上的居中分层：取第 ⌊(i + ½)·n/k⌋ 个 |
| TEMPORAL_EVEN | 在候选帧序跨度上等距取 k 个目标位置，各取最近的候选帧 |
| LATEST | 最新的 k 个候选帧 |
| RANDOM_SEEDED | 每个 episode 和预算用固定种子（20261006、场景、角色、k）抽一次 |
| POSE_FARTHEST | 贪心：离已测或已选相机最远；距离 = 平移（m）+ 1 m/rad × 旋转角 |
| MAX_UNCOVERED | 按初始上下文重投影到候选视角后的未覆盖比例（8 像素规则）取前 k 个 |
| MAX_NOVELTY3D | 按候选视角的预测表面中，离所有已测点超过深度 2% 的比例取前 k 个。预测表面由已测点 z-buffer 的冻结调和补洞得到 |
| GREEDY_COVERAGE | 贪心未覆盖比例；每请求一帧，就把它的深度加入已测几何再重新打分 |
| GREEDY_FILL_DISTANCE | 贪心：候选像素到最近已测命中点的平均距离（上限 32 像素），作为不确定性的代理 |
| GREEDY_PHOTOMETRIC | 贪心光度残差：把已测 RGB-D 重投影到候选视角后与候选 RGB 的平均差，没有命中的像素记为 1 |
诊断量（只走教师路径，不可部署）：
| 名称 | 定义 |
|---|---|
| ORACLE | 每个 episode 中，大小为 K、使 episode 平均 ALL AbsRel 最小的子集（样本内） |
| XORACLE | 交叉查询 oracle：用 episode 中另一个查询选子集，在这一个查询上打分 |
| RANDOM_EXPECTED | 大小为 K 的全部子集的精确平均，即均匀随机策略的期望 |
| WORST | 最差子集，只用来看范围 |
| QUERY_NEAREST | 离任一查询相机最近的 K 个候选帧（用到查询相机） |
最佳启发式： 每个 K 下，在同一数据上取场景平均 ALL AbsRel 最低的可部署规则。这样选出的启发式偏强，所以对余量判定是保守的。
5. 队列
| 名称 | 场景 | 用途 |
|---|---|---|
| EVAL34 | EVAL-V3 ∪ EVAL-V4，83 个 | 主判定 |
| EVAL34_GAP3 | 同一批场景，只保留帧序距每个查询都 ≥ 3 的候选帧（每条记录 4–9 个） | 次要：排除相邻帧效应 |
| EVAL_FAR | EVAL-FAR，79 个 | 次要：远处查询，与所有候选帧都相距很远 |
| REPLICA | 8 个 | 描述：跨数据集 |
| DEV | 8 个 | 只用于彩排，不进入结果 |
次要的学习式后端： 已测区域（距任何已测命中点不超过 8 像素）用调和补洞，其余用 G1。G1 的预测来自封存的探针：EVAL34 用 1 个 seed，DEV 用 3 个 seed。只作描述，字段为 g1_*。
6. 第一阶段问题与对应的量
| 问题 | 量 |
|---|---|
| Q1 NO_DEPTH 到 best-1 的改善 | 调和插值 − ORACLE_1 |
| Q2 best-2/best-4 是否收益递减 | ORACLE 的逐 K 增量，以及按历史大小分组的边际效用 |
| Q3 最强启发式离 oracle 多远 | BEST_H_K − ORACLE_K、BEST_H_K − XORACLE_K、余量比例 |
| Q4 最优帧是否因场景而异 | best-1 在池中位置的分布，以及众数位置的占比（低于 0.5 记为因场景而异） |
| Q5 位姿或覆盖规则是否已接近 oracle | 各规则的余量比例 |
| Q6 效用是否有可预测的结构 | 单步效用与每个可部署特征的 episode 内 Spearman，及其 top-1 一致率 |
| Q7–Q9 覆盖与效用的错位 | 未覆盖比例高但效用低的候选帧数，以及反过来的情况 |
| Q10–Q11 是否值得训练效用预测器 | 由判定决定 |
| Q12 与 NBV / active mapping 的边界 | 见 docs/measurement_planning_related_work.md |
可预测性按单个特征的平均 |Spearman| 标记：大于 0.6 为 STRONG，0.3–0.6 为 MODERATE，小于 0.3 为 WEAK。这只是描述，不用于判定。
7. 完整性
- K=0 复核：误差不超过 1e-9 m，NEAR 掩码相同。
- 读取审计：每个可部署规则的读取全部合法，且正好有 K 次候选深度读取。
- 教师路径的读取用途只有三种：
ORACLE_TEACHER_ONLY、QUERY_CAMERA_TEACHER_ONLY、SEALED_QUERY_EVALUATION。 - 分析在同一份原始数据上运行两次，结果必须逐字节相同。
- 原始表格按 sha256 登记。
tests/test_measurement_planning_oracle_v1.py（41 项）覆盖以下检查：- 候选深度在请求前隐藏；
- 查询帧与另一个角色的帧不可达；
- 预算计数准确；
- 每个规则正好请求 k 次且读取合法；
- 选择规则拒绝教师对象；
- 未请求的候选深度不影响选择；
- 随机种子固定；
- 子集并集与冻结多帧路径逐位相同；
- 教师不把查询帧融合进状态；
- 分析结果确定；
- 受保护场景与重复场景会被拒绝。
8. 不做的事
- 不训练任何选择器或预测器；
- 不打开受保护的保留集；
- 不下载新数据；
- 不推送 GitHub；
- 不删除、不覆盖任何旧实验的输出。