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, ...) —— 後ろの要素はそれぞれ独立に解く(1 画素、1 標本)。weights(同じ形か (N,))は各帯をどれだけ信じるか —— ふつうは位相を出した 2 つの振幅の積で、コントラストの無い帯は票を持たない。
方法: 標本ごとに 1 本の帯を錨(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 までの候補も入れる(同じ値が 2 回出るほど広げはしない)。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: 誤った候補は少なくとも 1 本の帯を Γ の 0 でない倍数だけ動かし、その帯のフェーザの項を厳密に下げる(重み 0 の帯でしか 2 つの候補を見分けられないときは margin が 0)。位相で言えば帯 i の許される誤差は 2 pi (Γ/4) / p_i —— 最も長い周期で最も小さい。剰余 mod Γ が Γ/2 より短い弧に収まらない標本は、その保証の外にあることが証明できる(within_bound が False。逆は保証されない —— ちょうど Γ 1 つ分の誤差は検出できない)。そのときの扱いは 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 + 周期の最小公倍数(通約できるとき)。それより広い範囲は拒否する —— その中の 2 つの値が同じ剰余を持つから。
厳密さ: 互いに素な整数の周期と整数の剰余は residue_integer_crt を正確に再現する。
• サンプルデータ カタログ(DL URL / ライセンス) — 2-D は skimage.data(BSD/public)+ 合成、3-D は実データ源(Stanford/PDS 等)の DL URL。
• 演算子の来歴・参考文献 — この op 族の元になった研究/手法の出典。
• アルゴリズムの正典(著者・年)と用途は上記ファミリ使い方ガイドに記載。
• 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 operator registry. この per-op ノートは tools/opdocs.py md が自動生成(手編集しない)。*
© 2026 Kazufumi Furuse — Fullseye operator documentation. Licensed under Apache-2.0.