dual op• 資料種類:signal × signal → measurement
• 呼叫: import fullseye as fs; fs.ledger.gcc_delay(a, b, rate=1.0, weight='phat', band=None, interpolate=True)(要直接呼叫實作,import acoustics; acoustics.gcc_delay(a, b, rate=1.0, weight='phat', band=None, interpolate=True);從台帳取用則 opsacoustics.get("gcc_delay"))
• 經台帳呼叫的回傳值: fullseye.ledger.gcc_delay(...) 只回傳宣告的 out 型別 measurement 的值(底層函式還會回傳輔助資訊)。需要被捨棄的部分時,請用 fullseye.ledger.gcc_delay.raw(...),或直接呼叫 acoustics.gcc_delay。
以廣義互相關(GCC)量測 2 個通道的到達時間差。→ (delay, table)。
漏水定位、聲源方向、超音波壁厚、振動傳播 —— 都取決於「同一個源何時抵達 2 處」之差。本 op 以秒(rate 為預設 1.0 時為取樣點)回傳該差。要換算成位置，乘以路徑長與傳播速度(x = (L - c·delay) / 2 的形式)。
★速度的假定會直接變成位置誤差。無論相關多麼乾淨，所乘的速度差 10 %，位置就會依離路徑中心的距離成比例偏移(poc_leak_localization 的
實測：離中心 18 m 的漏水偏 +1.798 m，幾何預測 1.800 m)。相關的品質與位置的正確性是不同的量，報告時要分開。
Args:
a, b: 長度相同的 1-D 紀錄。若 b 比 a 延遲，則 delay 為正
(b(t) ≈ a(t - delay))。
rate: 取樣頻率 [Hz]。預設 1.0 時回傳的單位是「取樣點」。
weight: 互頻譜的權重。
"none" = 原始互相關(SNR 高且無反射時最佳)，
"phat" = 相位轉換(對振幅白化。據稱對殘響穩健)，
"roth" = 1/|A|²，"scot" = 1/sqrt(|A|²|B|²)。
★PHAT 並非總是勝出：在反射不對稱的路徑上，延遲本身就會
偏，任何權重都無法去除(實測：反射 0.8 時 raw 0.134 m /
PHAT 0.114 m，只差 1 成，RMS 幾乎全是偏差)。
band: 以 (lo_hz, hi_hz) 限定頻帶(與 rate 同單位。rate=1.0 時
以 cycles / 取樣點計為 0〜0.5)。None 為全頻帶。
★weight="phat"(預設)時必填(2026-10-06，0.5.0 的破壞性變更)。
PHAT 將所有頻點白化為相同權重，因此對頻帶受限的訊號，沒有訊號的
頻點(雜訊、洩漏、捨入)會以與訊號相同的權重進入相關，峰值就會偏離
(低頻訊號不傳 band 時命中率大幅下降，傳入頻帶則恢復 ——
tests/test_acoustics.py 的迴歸測試)。若已知訊號佔滿全頻帶，
請明確寫成 band=(0.0, rate / 2)。"none" / "roth" /
"scot" 下仍為選填。
interpolate: 以峰值周圍的拋物線內插讀到次取樣點精度(預設 True)。
關閉後，量化的步長會以偏差而非離散殘留(固定位置時
每次都朝同一方向偏離。與 PIV 的峰值鎖定相同)。
★內插也消除不了偏差：相關峰呈 sinc 狀，拋物線無法
完全近似。在白雜訊、全頻帶下以 0〜1 取樣點平移的實測中，
誤差是最大 0.117 取樣點的 S 形(整數附近為 0，0.3 / 0.7 附近最大，
方向是被拉向整數)。談論次取樣精度時要將此偏差計入。
Returns:
(delay, table)：delay 是以秒(rate=1.0 時為取樣點)計的 float。
table 為 {"lags": (2N-1,) 的延遲, "r": 相關值, "peak": 峰值, "snr_peak": 峰值 / 次峰的比}。
★經由台帳(fullseye.ledger.gcc_delay)時只回傳宣告的 out 型別
delay。也需要相關曲線時用 fullseye.ledger.gcc_delay.raw(...)。
Raises:
ValueError: 長度不同 / 小於 2 / 非有限、weight 未知、band
不是 (lo, hi)、lo >= hi、對 rate 無效時，
weight="phat" 且 band 為 None 時(fail-closed(失敗即拒絕))。
侷限(honest)：(1) 反射、色散、路徑差造成的偏差無法去除 —— 能去除的只有雜訊導致的離散。(2) 因為只選 1 個相關峰，多路徑下次峰勝出時會不連續地偏離(請查看 snr_peak)。
(3) 延遲超過紀錄長度的一半時會折返。
Reference (public): C. H. Knapp, G. C. Carter, "The Generalized Correlation Method for Estimation of Time Delay", IEEE Trans. ASSP 24(4), 1976, 320-327.
• acoustic_condition_monitoring 族使用指南
• 範例資料目錄(下載 URL / 授權) —— 2-D 用 skimage.data(BSD/公有領域)加合成圖,3-D 給出真實資料源(Stanford/PDS 等)的下載 URL。
• 運算子來歷與參考文獻 —— 該運算子族所依據的研究/方法出處。
• 演算法的正典(作者、年份)與用途見上面的族使用指南。
• acoustic_condition_monitoring — py -3.11 examples/acoustic_condition_monitoring.py
measurement 作為輸入)—
dual)*Provenance: acoustics.py — ACOUSTICS 運算子登記表。本條目由 tools/opdocs.py md 自動產生(請勿手動編輯)。*
© 2026 Kazufumi Furuse — Fullseye operator documentation. Licensed under Apache-2.0.