measure op• 数据种类:depth → pairs
• 调用: import fullseye as fs; fs.ledger.surface_psd(z, dx, kind='areal', dy=None)(要直接调用实现,import roughness; roughness.surface_psd(z, dx, kind='areal', dy=None);从台账取用则 opsroughness.get("surface_psd"))
• 经台账调用的返回值: fullseye.ledger.surface_psd(...) 只返回声明的 out 类型 pairs 的值(底层函数还会返回辅助信息)。需要被丢弃的部分时,使用 fullseye.ledger.surface_psd.raw(...),或直接调用 roughness.surface_psd。
• 底层返回: (q, C) -> (N,2)
高度场的功率谱密度。返回 (q, C)。约定通过参数明确指定。
参数
z 高度场(内部减去均值。不返回 DC 区间)。
dx, dy 采样间隔。dy=None 表示正方形像素。
kind "areal" … 二维 PSD C_2D(q) 的环平均。
"radial" … 一维径向 PSD C_1D(q) = 2π q C_2D(q)。
约定(不写明这些,没有标定就无法读懂 ―― 现有的 radial_power_spectrum 的 docstring 中没有这些)
• q 的单位是 cycles / length(不是角频率 2π/λ)。q = 1/λ。
• C_2D(q) = dx dy |F|² / (ny nx)。归一化与 Parseval 一致: ∫ C_2D d²q = <h²> 且 ∫ C_1D dq = <h²>。
• 自仿射面 H 对应的斜率为 面 PSD 为 -2(H+1), 径向 PSD 为 -2H-1(恰好相差 1)。
★ 实测 —— 无论哪种约定,H 都能在无标定下恢复
用 surface_synth_psd 设定 H,在 q ∈ [2/λ_hi, 0.4/dx] 上做双对数
直线拟合恢复 H(512²,频带 2-64 µm):
设定的 H 面 PSD 斜率 恢复的 H 径向斜率 恢复的 H 斜率差
0.30 -2.600 0.300 -1.600 0.300 1.0000
0.50 -3.000 0.500 -2.000 0.500 1.0000
0.80 -3.600 0.800 -2.600 0.800 1.0000
0.95 -3.901 0.950 -2.901 0.950 1.0000
4 例误差均在 ±0.0003 以内,两种约定的斜率差对任何 H 都
严格为 1.0000。无需标定即可读懂。
★ 这里是 PoC 重新测量后结论发生改变之处。PoC 用现有的
radial_power_spectrum 发现了 一律 -0.013(H 的 1.6 %)的系统误差,
并得出“环平均离散化造成的系统误差”的结论。用本
实现做同样的验算,误差消失了。排查原因后发现,是环的代表 q 用区间编号 i·Δq 还是用环内 q 的平均值的差异
—— 用区间编号会出现 -0.0007~-0.0010 的负偏差(实测,同一面、同一
拟合频带)。方向与 PoC 的观测相同,但大小只有 1/15,因此
-0.013 的其余部分并非来自环平均的离散化,而是来自该函数的其他实现差异。
本函数返回环内 q 的平均值。
★ 陷阱 —— 超过 Nyquist 的环“只由角落”构成
正方形网格的最大 |q| 是 √2/(2 dx),但 q > 1/(2 dx) 的环
只包含频率平面的四个角。实测(512²):全部 362 个区间中排在最上的
107 个区间(29.6 %)超过 Nyquist。环内点数相对理想值 2πq/Δq
缺少多少:在 Nyquist 以下最低也会降到 0.838 倍
(网格的离散化),而超过 Nyquist 则会降到 0。
斜率拟合不要使用超过 Nyquist 的部分。
★ Parseval 验算可以信到什么程度(实测,512²,Sq²=6.400e-03)
• 在二维全网格上求 Σ C_2D Δqx Δqy 得 +0.0000 %(严格)。
• 对返回的径向 PSD 做梯形积分得 -0.55 %。按环取平均压成一维时这部分就丢失了 —— 环平均是摘要, 不可逆。 需要优于 0.5 % 精度的用途,请自行对二维的 C_2D 积分。
• 此面的频带上端就是 Nyquist,所以在 Nyquist 处截断仍为 -0.55 % 不变(角落部分没有内容)。对角落有内容的面(频带超过 Nyquist 的面),截断就会缺失。
fail-closed(失败即拒绝)
• 不是二维 / 小于 8x8 / 含 NaN 或 Inf / dx, dy 非正。
• kind 不是 "areal" 或 "radial"。
• 示例数据目录(下载 URL / 许可证) —— 2-D 用 skimage.data(BSD/公有领域)加合成图,3-D 给出真实数据源(Stanford/PDS 等)的下载 URL。
• 算子来历与参考文献 —— 该算子族所依据的研究/方法出处。
• 算法的正典(作者、年份)与用途见上面的族使用指南。
• poc_surface_roughness — py -3.11 examples/poc_surface_roughness.py
pairs 作为输入)—
measure)surface_params · profile_params
*Provenance: roughness.py — ROUGHNESS 算子登记表。本条目由 tools/opdocs.py md 自动生成(请勿手工编辑)。*
© 2026 Kazufumi Furuse — Fullseye operator documentation. Licensed under Apache-2.0.