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.