robust op• 数据种类:matrix × signal → table
• 调用: import fullseye as fs; fs.ledger.residue_crt(residues, periods, weights=None, lo=0.0, hi=None, on_outside='warn') -> 'dict'(要直接调用实现,import residue; residue.residue_crt(residues, periods, weights=None, lo=0.0, hi=None, on_outside='warn') -> 'dict';从台账取用则 opsresidue.get("residue_crt"))
针对实数周期的加权鲁棒中国剩余定理 -> dict。
在 [lo, hi) 内求解 v ≡ residues[i] (mod periods[i])。residues 的频带轴在最前，形状为 (N,) 或 (N, ...) —— 后面的每个元素独立求解(一个像素、一个样本)。weights(同形状，或 (N,))表示对各频带的信任程度 —— 通常是给出相位的两个振幅之积，没有对比度的频带没有投票权。
方法: 每个样本选一个频带作为基准(reference)(Wang & Xia 2010，第 IV-A 节: 噪声方差最小的余数。频带 i 的方差建模为 p_i^2 / w_i，即相位噪声相同、按权重缩放;在方差相同的频带中，选余数 mod Γ 最接近公共余数的那个，式 (55)/(58))。范围内的每个候选 v = r_ref + k p_ref 都用相量一致度 sum_i w_i cos(2 pi (v - r_i)/p_i)(von Mises 相位噪声的最大似然准则)打分，最佳候选再用带符号残差的逆方差加权平均精化。候选带有基准自身的误差，因此 [lo, hi) 之外 Γ/4 以内的候选也被接纳(不会宽到同一个值出现两次)。2026-10-15 之前总是以最长周期为基准: 相位噪声相同时，它在 v 的单位下是噪声最大的余数;在间接 ToF(16/80/120 MHz，σ_φ 0.33 rad)中，折叠次数的错误率为 0.556(尝试全部假设为 0.116)。现在为 0.116(公开原始数据 10 帧: 0.293 -> 0.131，与穷举解码相同)。
保证(Wang & Xia 2010，式 (47)): 把周期写成 Γ M_i(Γ 为公因子，M_i 为整数)。若所有余数误差都小于 Γ/4，无论以哪个频带为基准，折叠整数都准确且 |value - v| < Γ/4: 错误的候选至少使一个频带移动 Γ 的非零倍数，从而严格降低该频带的相量项(若只有权重为 0 的频带能区分两个候选，则 margin 为 0)。以相位表示，频带 i 允许的误差为 2 pi (Γ/4) / p_i —— 在最长周期上最小。余数 mod Γ 不能落在短于 Γ/2 的弧内的样本，可以证明位于该保证之外(within_bound 为 False;反之不保证 —— 恰好一个 Γ 的误差无法检测)。此时的处理由 on_outside 决定: "warn"(默认，ResidueBoundWarning)、"raise"(ValueError)、"nan"(这些样本的值为 NaN、margin 为 0)或 "flag"(只给 within_bound)。不可通约的周期(显式给出 hi)没有 Γ 也没有保证: 所有样本都在保证之外。
返回 {"value", "score", "margin", "residual", "n_candidates", "unambiguous_range", "gamma", "error_bound", "phase_bound_rad", "reference", "within_bound"}: score 在 [-1, 1](1 = 所有频带完全一致)，margin = 最佳与次佳得分之差(小 = 几乎平局 —— 不可信)，residual 为各频带、以 v 为单位。gamma = Γ，error_bound = Γ/4，phase_bound_rad 为各频带，reference = 每个样本所用频带的索引。hi 默认为 lo + 周期的最小公倍数(可通约时);比它更宽的范围被拒绝 —— 其中两个值会有相同的余数。
精确性: 两两互素的整数周期与整数余数能精确重现 residue_integer_crt。
• 示例数据目录(下载 URL / 许可证) —— 2-D 用 skimage.data(BSD/公有领域)加合成图,3-D 给出真实数据源(Stanford/PDS 等)的下载 URL。
• 算子来历与参考文献 —— 该算子族所依据的研究/方法出处。
• 算法的正典(作者、年份)与用途见上面的族使用指南。
• poc_itof_multifreq — py -3.11 examples/poc_itof_multifreq.py
• poc_residue_crt — py -3.11 examples/poc_residue_crt.py
table 作为输入)—
robust)*Provenance: residue.py — RESIDUE 算子登记表。本条目由 tools/opdocs.py md 自动生成(请勿手工编辑)。*
© 2026 Kazufumi Furuse — Fullseye operator documentation. Licensed under Apache-2.0.