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.