17-EFT.WP.Methods.Imaging v1.0 | 附录A 接口参考（I20 全集）

目录 ／ 文档-技术白皮书 ／ 17-EFT.WP.Methods.Imaging v1.0

附录A 接口参考（I20 全集）

一句话目标：汇总本卷实现绑定接口 I20-* 的签名、输入输出、不变量、错误语义与跨卷依赖，支撑从采集到发布的成像流水线复用与审计。

I. 约定与编号

• 统一编号：本卷实现绑定接口记为 I20-*；公设 P2x-*、最小方程 S2x-*、流程 M2x-* 见各章。
• 形参与返回采用英文与符号形式，单位与量纲通过 unit(x), dim(x) 指定；凡出现积分、除号或复合算符，显式测度与路径。
• 时基：内部在 tau_mono 上计算与窗口化，对外以 ts 发布并记录 offset/skew/J（见第13章与《Methods.Cleaning v1.0》第5章）。
• 到达时两口径：并行计算
  T_arr = ( 1 / c_ref ) * ( ∫ n_eff d ell ) 与 T_arr = ( ∫ ( n_eff / c_ref ) d ell )，并产出 delta_form。
• 跨卷引用固定写法：见《Methods.Cleaning v1.0》相应章节的 I10-*。

II. 通用类型与记录

• Image{H,W,C,dtype,space}：帧或图像；space ∈ {raw, linear, XYZ, sRGB, ...}。
• Cube{H,W,B}：多光谱数据立方。
• EventStream{(t,x,y,p)}：事件相机流。
• ToFDepth{H,W,meters}：ToF 深度帧。
• PSF, OTF, MTF：点扩散、光学传递、调制传递函数。
• NoiseModel{sigma_read,k_shot,NPS(f)}。
• GeomModel{K,R,t,dist}：内外参与畸变。
• ColorProfile{M,curve,illuminant,space}。
• SliDict：SLI.img.* 与 SLI.svc.* 的键值集合。
• Manifest{meta,contract,hash_sha256,signature,TraceID}。

III. 核心与元数据层（I20-0）*

• I20-01 register_device(device_spec) -> device_id
  pre: device_spec 完整、唯一。post: 可查询与签名。err: E.DUP_DEVICE。
• I20-02 register_mode(device_id, mode_spec) -> mode_id
  inv: mode_spec 不与已登记模式冲突。err: E.BAD_MODE。
• I20-03 standardize_metadata(meta, registry) -> meta'
  post: 统一键名、单位与别名，满足 DataSpec。err: E.META_INCOMPLETE。
• I20-04 imaging_align_timebase(meta, sync_ref) -> meta'
  wrap: 调用《Methods.Cleaning v1.0》I10-5 align_timebase。产出 offset/skew/J。
• I20-05 freeze_release(artifacts, tag) -> manifest
  wrap: 调用《Methods.Cleaning v1.0》I10-10 freeze_release。inv: 可重现性。

IV. 线性化与辐射一致化（I20-1，见第4章）*

• I20-11 linearize_and_calibrate(y_raw, RefCond, black_level, gain, response) -> {y_lin, report}
  pre: unit(y_raw) 与 dim(y_raw) 明确。post: space(y_lin)="linear"。err: E.NOT_LINEAR_DOMAIN（若失败）。
• I20-12 repair_units_img(x, policy) -> {x', report}
  post: check_dim(expr) 全通过；单位归一。err: E.DIM_MISMATCH。
• I20-13 radiometric_flatfield(y_lin, flats, darks) -> {y_corr, prnu_map, dsnu_map}
  inv: 保持辐射线性；记录 PRNU, DSNU。err: E.CAL_DRIFT。

V. 光学分辨率与 PSF/OTF/MTF（I20-2，见第5章）*

• I20-21 measure_mtf_slanted_edge(img, roi) -> {MTF(f), f50, f80, area}
  pre: space(img)="linear"。post: f50 = MTF^{-1}(0.5)。err: E.ROI_INVALID。
• I20-22 estimate_psf_from_point(img, roi) -> PSF
  inv: ∫ PSF dA = 1。err: E.POINT_SOURCE_WEAK。
• I20-23 otf_to_mtf(OTF) -> MTF
  inv: MTF(f) = | OTF(f) |。

VI. 采样、重建与插值（I20-3，见第6章）*

• I20-31 demosaic_bayer(y_lin, pattern, method) -> Image
  inv: 不跨通道泄漏测试图案；记录 artifact_score。err: E.BAD_PATTERN。
• I20-32 superres_multi(seq, psf, method, scale) -> Image
  pre: seq 已几何对齐。post: 提升分辨率与 MTF_area。err: E.REG_REQUIRED。
• I20-33 resample_multires(imgs, align, policy) -> Image
  inv: 多尺度一致；记录插值核与窗口。

VII. 噪声建模与去噪（I20-4，见第7章）*

• I20-41 estimate_noise_psd(seq, roi) -> NoiseModel
  post: 产出 NPS(f), sigma_read, k_shot。err: E.ROI_INVALID。
• I20-42 denoise(img, model, method, strength) -> {img', nps_band}
  inv: 结构保持；NPS_band 降至策略阈值。err: E.OVER_SMOOTH。

VIII. 平场/暗场与固定图样噪声（I20-5，见第8章）*

• I20-51 compute_prnu_dsnu(flats, darks) -> {PRNU, DSNU, map_prnu, map_dsnu, bad_pixel_map}
  inv: PRNU = std(flat_norm) / mean(flat_norm)。err: E.FLAT_UNSTABLE。
• I20-52 apply_fpn_correction(y_lin, map_prnu, map_dsnu, bad_pixel_map) -> y_corr
  post: PRNU,DSNU 降至策略卡阈值；记录屏蔽率。

IX. 几何标定与畸变校正/配准（I20-6，见第9章）*

• I20-61 calibrate_geometry(pattern_imgs) -> {GeomModel, err_geo}
  post: err_geo ≤ tol_geo；保存 K,R,t,dist 与置信度。err: E.GEOM_NOT_CONVERGED。
• I20-62 undistort_and_rectify(img, GeomModel) -> img'
  inv: 保角近似与采样守恒；记录插值核。
• I20-63 register_multimodal(A, B, init, cost) -> {H, err_geo}
  pre: 指定跨模态特征或互信息代价。err: E.NO_OVERLAP。

X. 色彩管理与白平衡（I20-7，见第10章）*

• I20-71 build_color_profile(charts, illuminant, target_space) -> ColorProfile
  post: 记录 M, tone_curve 与训练误差。err: E.CHART_INVALID。
• I20-72 white_balance(img, wb_gains, method) -> img'
  inv: 灰世界或参考白一致；记录 wb_error。
• I20-73 gamut_map(img, target_space, policy) -> img'
  err: E.OUT_OF_GAMUT（若无法在策略下守恒）。
• I20-74 evaluate_color(y_ref, y_test, metric="DeltaE_00") -> stats
  post: 输出 DeltaE_00.{mean,P95,P99}。

XI. HDR 与曝光融合（I20-8，见第11章）*

• I20-81 hdr_merge(frames, weights, response) -> {hdr_linear, ghosting}
  inv: 工作在线性域；记录拖影度量。err: E.GHOSTING_HIGH。
• I20-82 exposure_scheduling(SNR_model, target_sli) -> schedule
  post: 满足 SLO.* 下的 SNR 目标；输出包围参数。

XII. 计算成像（去卷积/超分/压缩感知）（I20-9，见第12章）*

• I20-91 deconvolution(img, psf, reg) -> img'
  inv: 能量守恒近似与伪影控制；记录条件数与收敛。err: E.DIVERGED。
• I20-92 compressive_reconstruction(Phi, y_meas, prior, solver) -> img'
  pre: Phi 满秩或 RIP 近似。post: 残差与稀疏度达标。
• I20-93 superres_fusion(seq, psf, motion, reg) -> img'
  inv: 运动补偿一致；MTF_area 提升。

XIII. 时间/路径门控与到达时一致化（I20-10，见第13章）*

• I20-101 gate_by_time(y(t), w(t)) -> A_path(y)
  inv: A_path(y) = ( ∫ w(t) * y(t) d t )；记录窗口形状与 Delta_t。
• I20-102 gate_by_tof(E(t), D(t), t0, Delta_t) -> A_path(E)
  post: 根据 D(t) 自适应 t0, Delta_t；记录 S_sync。
• I20-103 arrival_time_consistency(gamma(ell), n_eff(ell), c_ref) -> {T_arr_const, T_arr_general, delta_form}
  inv: 同时计算两口径并断言 delta_form ≤ tol_Tarr（策略卡）。

XIV. 质量指标、SLO 与审计（I20-11，见第14章）*

• I20-111 aggregate_sli(metrics) -> SliDict
  post: 统一键空间 SLI.img.* 与 SLI.svc.*。
• I20-112 check_slo(sli, policy) -> {pass, violations[]}
  inv: 使用高分位阈值，避免均值误判。
• I20-113 emit_qc_manifest(artifacts, sli, policy) -> manifest
  post: 落盘 hash_sha256(blob) 与 signature，对齐《Methods.Cleaning v1.0》第10章。

XV. 流式接口与背压闭环（I20-12，见第15章与《Methods.Cleaning v1.0》第11章）*

• I20-121 build_realtime_graph(topology, policy) -> G
  inv: G=(V,E) 拓扑有向无环或显式反馈边标注。
• I20-122 set_backpressure(G, policy) -> G'
  post: 配置 chan/cap/q_len、丢帧与降级策略；保证 rho < 1。
• I20-123 runtime_telemetry(G) -> {SLI.svc.*, SLI.img.*}
  post: 暴露 T_proc.P99, drop_rate, rho, W_q。

XVI. 错误码与异常语义（统一）

• E.DUP_DEVICE, E.BAD_MODE, E.META_INCOMPLETE。
• E.DIM_MISMATCH, E.NOT_LINEAR_DOMAIN, E.CAL_DRIFT。
• E.ROI_INVALID, E.POINT_SOURCE_WEAK, E.REG_REQUIRED, E.NO_OVERLAP。
• E.GEOM_NOT_CONVERGED, E.OUT_OF_GAMUT, E.GHOSTING_HIGH, E.DIVERGED。
• E.BACKPRESSURE, E.SLO_VIOLATION, E.CONTRACT_FAIL。
• 处理规范：所有接口返回 {ok, data?, error?} 或抛出异常并记录到 audit_report。

XVII. 幂等性、可重入与可审计

• 幂等：register_* 在同一 device_spec/mode_spec 下幂等；freeze_release 幂等（以 hash 为键）。
• 可重入：纯计算类（去噪、去卷积、评测）在相同输入与随机种子下确定性。
• 审计：每次调用记录 {args_digest, version, runtime, SLI.local} 并关联 TraceID。

XVIII. 版本与兼容性

• version(api)="I20.x.y"；每个接口须记录 min_device_fw, min_dataspec.
• 向后兼容策略：新增可选参数默认空，旧调用路径不变；破坏性变更以次要版本号加 1 并在《附录F》登记。

XIX. 交叉引用

• 线性化与辐射一致化：见第4章；光学分辨率：见第5章；采样重建：见第6章；噪声与 FPN：见第7章、第8章；几何：见第9章；色彩：见第10章；HDR：见第11章；计算成像：见第12章；时间/路径门控：见第13章；质量与审计：见第14章；用例：见第15章。
• 到达时两口径、时基对齐、发布冻结与背压：见《Methods.Cleaning v1.0》第5、6、10、11章。