17-EFT.WP.Methods.Imaging v1.0 | Appendix A Interface Reference (I20 Full Set)

Appendix A Interface Reference (I20 Full Set)

One-Sentence Goal
Consolidate the binding interfaces I20-* defined in this volume—their signatures, I/O, invariants, error semantics, and cross-volume dependencies—to support reuse and audit of the imaging pipeline from acquisition to publication.

I. Conventions & Numbering

• Unified numbering: Binding interfaces in this volume are denoted I20-*. Axioms P2x-*, minimal equations S2x-*, and processes M2x-* are defined in their respective chapters.
• Notation & units: Parameters and returns use English symbols; units and dimensions are specified via unit(x), dim(x). Whenever integrals, divisions, or composite operators appear, state measures and paths explicitly.
• Time base: Compute and window on tau_mono; publish on ts and record offset/skew/J (see Chapter 13 and Methods.Cleaning v1.0, Ch. 5).
• Arrival two forms: Always compute in parallel
  T_arr = ( 1 / c_ref ) * ( ∫ n_eff d ell ) and T_arr = ( ∫ ( n_eff / c_ref ) d ell ), then emit delta_form.
• Cross-volume call sites: When referring to Methods.Cleaning v1.0, use the canonical I10-* identifiers.

II. Common Types & Records

• Image{H,W,C,dtype,space} with space ∈ { raw, linear, XYZ, sRGB, ... }
• Cube{H,W,B}: multispectral cube
• EventStream{(t,x,y,p)}
• ToFDepth{H,W,meters}
• PSF, OTF, MTF
• NoiseModel{ sigma_read, k_shot, NPS(f) }
• GeomModel{ K, R, t, dist }
• ColorProfile{ M, curve, illuminant, space }
• SliDict for SLI.img.* and SLI.svc.*
• Manifest{ meta, contract, hash_sha256, signature, TraceID }

III. Core & Metadata Layer (I20-0)

• I20-01 register_device(device_spec) -> device_id
  pre: device_spec complete and unique. post: queryable & signed. err: E.DUP_DEVICE.
• I20-02 register_mode(device_id, mode_spec) -> mode_id
  inv: no conflict with existing modes. err: E.BAD_MODE.
• I20-03 standardize_metadata(meta, registry) -> meta'
  post: unified keys, units, aliases per DataSpec. err: E.META_INCOMPLETE.
• I20-04 imaging_align_timebase(meta, sync_ref) -> meta'
  wrap: calls Methods.Cleaning v1.0 I10-5 align_timebase; outputs offset/skew/J.
• I20-05 freeze_release(artifacts, tag) -> manifest
  wrap: calls Methods.Cleaning v1.0 I10-10 freeze_release. inv: reproducibility.

IV. Linearization & Radiometric Harmonization (I20-1; Ch. 4)

• I20-11 linearize_and_calibrate(y_raw, RefCond, black_level, gain, response) -> { y_lin, report }
  pre: unit(y_raw), dim(y_raw) explicit. post: space(y_lin)="linear". err: E.NOT_LINEAR_DOMAIN.
• I20-12 repair_units_img(x, policy) -> { x', report }
  post: all check_dim(expr) pass; units normalized. err: E.DIM_MISMATCH.
• I20-13 radiometric_flatfield(y_lin, flats, darks) -> { y_corr, prnu_map, dsnu_map }
  inv: preserve linear radiometry; record PRNU, DSNU. err: E.CAL_DRIFT.

V. Optical Resolution & PSF/OTF/MTF (I20-2; Ch. 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. Sampling, Reconstruction, and Interpolation (I20-3; Ch. 6)

• I20-31 demosaic_bayer(y_lin, pattern, method) -> Image
  inv: no cross-channel pattern leakage; record artifact_score. err: E.BAD_PATTERN.
• I20-32 superres_multi(seq, psf, method, scale) -> Image
  pre: seq geometrically aligned. post: improved resolution and MTF_area. err: E.REG_REQUIRED.
• I20-33 resample_multires(imgs, align, policy) -> Image
  inv: cross-scale consistency; record interpolation kernel and window.

VII. Noise Modeling & Denoising (I20-4; Ch. 7)

• I20-41 estimate_noise_psd(seq, roi) -> NoiseModel
  post: outputs NPS(f), sigma_read, k_shot. err: E.ROI_INVALID.
• I20-42 denoise(img, model, method, strength) -> { img', nps_band }
  inv: structure preserved; NPS_band reduced to policy threshold. err: E.OVER_SMOOTH.

VIII. Flat/Dark & Fixed-Pattern Noise (I20-5; Ch. 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 meet policy thresholds; record masking rate.

IX. Geometry, Distortion, and Registration (I20-6; Ch. 9)

• I20-61 calibrate_geometry(pattern_imgs) -> { GeomModel, err_geo }
  post: err_geo ≤ tol_geo; store K,R,t,dist with confidence. err: E.GEOM_NOT_CONVERGED.
• I20-62 undistort_and_rectify(img, GeomModel) -> img'
  inv: quasi-conformal & sampling conservation; record interpolation kernel.
• I20-63 register_multimodal(A, B, init, cost) -> { H, err_geo }
  pre: specify cross-modal features or mutual-information cost. err: E.NO_OVERLAP.

X. Color Management & White Balance (I20-7; Ch. 10)

• I20-71 build_color_profile(charts, illuminant, target_space) -> ColorProfile
  post: record M, tone curve, and training error. err: E.CHART_INVALID.
• I20-72 white_balance(img, wb_gains, method) -> img'
  inv: gray-world or reference-white consistency; record wb_error.
• I20-73 gamut_map(img, target_space, policy) -> img'
  err: E.OUT_OF_GAMUT if conservation fails under policy.
• I20-74 evaluate_color(y_ref, y_test, metric="DeltaE_00") -> stats
  post: outputs DeltaE_00.{ mean, P95, P99 }.

XI. HDR & Exposure Fusion (I20-8; Ch. 11)

• I20-81 hdr_merge(frames, weights, response) -> { hdr_linear, ghosting }
  inv: operates in linear domain; record ghosting metrics. err: E.GHOSTING_HIGH.
• I20-82 exposure_scheduling(SNR_model, target_sli) -> schedule
  post: meets SNR targets under SLO.*; outputs bracket parameters.

XII. Computational Imaging (Deconvolution / SR / CS) (I20-9; Ch. 12)

• I20-91 deconvolution(img, psf, reg) -> img'
  inv: approximate energy conservation and artifact control; log condition number & convergence. err: E.DIVERGED.
• I20-92 compressive_reconstruction(Phi, y_meas, prior, solver) -> img'
  pre: Phi full rank or RIP-like; post: residual and sparsity within targets.
• I20-93 superres_fusion(seq, psf, motion, reg) -> img'
  inv: motion-compensation consistency; MTF_area improvement.

XIII. Time/Path Gating & Arrival Harmonization (I20-10; Ch. 13)

• I20-101 gate_by_time(y(t), w(t)) -> A_path(y)
  inv: A_path(y) = ( ∫ w(t) * y(t) d t ); record window shape and Δt.
• I20-102 gate_by_tof(E(t), D(t), t0, Δt) -> A_path(E)
  post: adapt t0, Δt from D(t); record S_sync.
• I20-103 arrival_time_consistency(gamma(ell), n_eff(ell), c_ref) -> { T_arr_const, T_arr_general, delta_form }
  inv: compute both forms; assert delta_form ≤ tol_Tarr (policy card).

XIV. Quality, SLO & Audit (I20-11; Ch. 14)

• I20-111 aggregate_sli(metrics) -> SliDict
  post: unify keyspace for SLI.img.* and SLI.svc.*.
• I20-112 check_slo(sli, policy) -> { pass, violations[] }
  inv: judge by high quantiles; avoid mean bias.
• I20-113 emit_qc_manifest(artifacts, sli, policy) -> manifest
  post: persist hash_sha256(blob) and signature, aligned with Methods.Cleaning v1.0, Ch. 10.

XV. Streaming Interfaces & Backpressure Loop (I20-12; Ch. 15 & Methods.Cleaning v1.0, Ch. 11)

• I20-121 build_realtime_graph(topology, policy) -> G
  inv: G=(V,E) is DAG or has labeled feedback edges.
• I20-122 set_backpressure(G, policy) -> G'
  post: configure chan/cap/q_len, drop/degrade strategies; ensure rho < 1.
• I20-123 runtime_telemetry(G) -> { SLI.svc.*, SLI.img.* }
  post: expose T_proc.P99, drop_rate, rho, W_q.

XVI. Error Codes & Semantics (Unified)
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

XVII. Idempotency, Reentrancy & Auditability

• Idempotent: register_* with identical specs; freeze_release keyed by hash.
• Reentrant: pure-compute (denoise/deconvolution/evaluation) is deterministic under identical inputs and seed.
• Audit: each call logs { args_digest, version, runtime, SLI.local } and binds to TraceID.

XVIII. Versioning & Compatibility

• version(api) = "I20.x.y"; each interface records min_device_fw, min_dataspec.
• Backward compatibility: new optional params default empty; breaking changes bump minor and register in Appendix F.

XIX. Cross-References
Linearization & radiometry (Ch. 4); optics (Ch. 5); sampling (Ch. 6); noise & FPN (Chs. 7–8); geometry (Ch. 9); color (Ch. 10); HDR (Ch. 11); computational imaging (Ch. 12); time/path gating (Ch. 13); quality & audit (Ch. 14); use cases (Ch. 15).
Arrival two forms, timebase alignment, release freeze, and backpressure: Methods.Cleaning v1.0, Chapters 5, 6, 10, 11.