prepare op• 資料種類:depth → depth
• 呼叫: import fullseye as fs; fs.ledger.surface_form_remove(z, dx, order=1, method='ls', thresh=None, dy=None, iters=200, seed=0)(要直接呼叫實作,import roughness; roughness.surface_form_remove(z, dx, order=1, method='ls', thresh=None, dy=None, iters=200, seed=0);從台帳取用則 opsroughness.get("surface_form_remove"))
• 經台帳呼叫的回傳值: fullseye.ledger.surface_form_remove(...) 只回傳宣告的 out 型別 depth 的值(底層函式還會回傳輔助資訊)。需要被捨棄的部分時,請用 fullseye.ledger.surface_form_remove.raw(...),或直接呼叫 roughness.surface_form_remove。
• 底層回傳: (residual, coeffs)
直接在網格上去除平面 / 二次曲面。回傳 (residual, coeffs)。
參數
z 高度場。
dx, dy 取樣間隔。dy=None 為正方形像素。
order 1 = 平面，2 = 二次曲面。
method "ls"（最小平方）或 "ransac"（強健）。
thresh RANSAC 的內點閾值（高度單位）。為 None 時使用最小平方殘差的
強健離散度 2.5 x 1.4826 x MAD。
iters RANSAC 的試行次數。由 seed 決定。
coeffs 是以場的中心為原點的物理座標下的單項式係數。order=1 時為 [c0, gx, gy]，gx/gy 直接就是梯度； order=2 時為 [c0, gx, gy, cxx, cxy, cyy]（依 x^2, xy, y^2 的順序）。
★ 為什麼直接接收網格
現有的 fit_plane / fit_plane_ransac 只接收 (N,3) 點雲。
要傳入 512² 的高度場，每次都得用 column_stack 展開成 262144x3 = 6.3 MB
（實測）。這裡把網格當作網格直接接收，基底也
用 1 維向量的外積建構，因此不需展開。
★ 開銷（實測，1024x1024，iters=200）
method="ls" 47 ms，而 method="ransac" 為 1.8 秒（38 倍）。
RANSAC 每次都要重新統計 1024² 個點的殘差，因此與 iters 成線性關係。
若只看粗糙度，「LS + λc 高通」能以 1/40 的開銷得到相同答案
（見下方實測）—— 這就是不把 RANSAC 設為預設的原因。
★ 陷阱 —— 需要強健性的不是「深刮痕」，而是「寬的離群值」。
但當離群值成為多數時，RANSAC 也會一起失效。
在把 4 條深 3 µm 的刮痕集中在一側的 512x512 面上，只改變刮痕的寬度的
實測（注入並去除 0.050/-0.025 的傾斜。真值是含刮痕的面本身）：
刮痕半高半寬 面積比 LS 的 Sq 誤差 RANSAC 的 Sq 誤差 改善
4 µm 5.6 % -1.94 % -0.39 % 5.0 倍
12 µm 16.3 % -6.47 % -3.03 % 2.1 倍
24 µm 31.0 % -13.79 % -11.53 % 1.2 倍
40 µm 46.0 % -23.80 % -23.56 % 1.0 倍
可以讀出 3 點：
• 起作用的不是深度而是面積比。「深刮痕 = 必須強健」是草率的結論，正確的是「寬的離群值 = 必須強健」。
• 誤差必定出現在偏小一側 —— 因為最小平方連「刮痕集中在一側所造成的真實不對稱」也當作平面吸收掉了。在合格判定中會朝危險的方向失效。
• 面積比 46 % 時 RANSAC 也幫不上忙（改善 1.0 倍）。離群值占到近一半時，RANSAC 的多數決本身就會選中刮痕。強健擬合是以「離群值是少數」為前提的工具，該前提失效之處只能用表來呈現。
★ 陷阱 —— 把 λc 放在後級，LS 與 RANSAC 的差就消失了
對同一個面（半高半寬 4 µm）事後套用 λc=80 µm 的高通，
Sq 誤差為 LS +0.00 % / RANSAC -0.00 %（上表中相差 5.0 倍）。
多去除的平面是純粹的長波長，高通只是把同樣的東西再
丟一次而已。擬合的強健性起作用的是不套用 λc 的使用方式（平面度、形狀偏差）時。 若只看粗糙度，靠順序就能挽救。
另外，平面本身的恢復用 LS 也不錯：對上面那個面中注入的梯度
0.050 / -0.025，回傳 0.050006 / -0.025127（實測）。
fail-closed(失敗即拒絕)
• order 不是 1 或 2 / method 不是 "ls"、"ransac"。
• thresh 非正、非有限。
• RANSAC 收集不到規定數量的內點（退化的面）。
• 範例資料目錄(下載 URL / 授權) —— 2-D 用 skimage.data(BSD/公有領域)加合成圖,3-D 給出真實資料源(Stanford/PDS 等)的下載 URL。
• 運算子來歷與參考文獻 —— 該運算子族所依據的研究/方法出處。
• 演算法的正典(作者、年份)與用途見上面的族使用指南。
• poc_polish_wipe_measure — py -3.11 examples/poc_polish_wipe_measure.py
• poc_pv_thermal_survey — py -3.11 examples/poc_pv_thermal_survey.py
• poc_surface_roughness — py -3.11 examples/poc_surface_roughness.py
depth 作為輸入)surface_filter · surface_params · surface_psd
prepare)*Provenance: roughness.py — ROUGHNESS 運算子登記表。本條目由 tools/opdocs.py md 自動產生(請勿手動編輯)。*
© 2026 Kazufumi Furuse — Fullseye operator documentation. Licensed under Apache-2.0.