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.