decode_fringe — 3D `structured_light` op

• 資料種類:images → depth

• 呼叫: import fullseye as fs; fs.ledger.decode_fringe(phase_shift_images, ref_phase=None, k=1.0, mask=None, min_modulation=None) -> 'np.ndarray'(要直接呼叫實作,import fringe; fringe.decode_fringe(phase_shift_images, ref_phase=None, k=1.0, mask=None, min_modulation=None) -> 'np.ndarray';從台帳取用則 ops3d.get("decode_fringe"))

用法

一次性解碼相移影像序列:wrapped → 解纏 →(減去參考得到)高度。

phase_shift_images:N-step 相移條紋影像序列((N,H,W) 或長度為 N 的序列)。

ref_phase: 參考平面(高度 0)已展開的相位。None 時高度 = k·(unwrapped)。

k: 相位→高度的校正常數。

mask: 可省略。True=有效像素。無效像素為 NaN。

min_modulation: 可省略。指定時把 modulation < 該值的像素作為低可信度而設為無效。

回傳值:高度圖(2D float)。ref_phase=None 時回傳乘以 k 的連續相位。無效像素為 NaN。

步驟(依實作):wrapped_phase → 組裝可信遮罩(若有 min_modulation, 則為 modulation(stack) >= min_modulation,若有 mask 則與之取 AND)→ unwrap_phase_2d(wrapped, mask=可信遮罩) → 若 ref_phase 為 None 則 k * unwrapped,否則 phase_to_height(k * (unwrapped - ref_phase))。

參數:

• phase_shift_images:(N, H, W),N >= 3,等間隔相移。

• ref_phase:純量或 (H, W)。傳入把參考面以相同步驟展開的相位(為使 unwrap_phase_2d 的全域偏移在兩者中得到相同處理,參考也以本 op 用 ref_phase=None 解碼的結果最為穩妥)。

• k:相位→高度的校正常數(單位/rad)。對應 synthesize_fringes 的 phase_gain 的倒數。

• mask:(H, W) 的 bool,True = 有效。min_modulation:調變度的下限([0, 1] 左右。剔除陰影、飽和的像素)。

驗證(ValueError):影像序列不是 3-D、N < 3、非有限 / mask 形狀不同 / ref_phase 形狀不同 / 有效像素為零。沒有 scikit-image 時拋出 RuntimeError。

回傳值:(H, W) float64。無效像素為 NaN。單位為 k 的單位。

注意:依賴空間展開,因此在因階躍、遮擋而分成孤島的場景中, 各孤島可能殘留 2πm k 的高度偏移。需要絕對高度時,走 graycode_decode → absolute_phase → triangulate_column 的路徑。

背景知識指南(該運算子背後的物理與規範)

• depth_sensors — 深度感測器知識 —— 測距原理、實機數值、缺測的表現

參考(範例資料、文獻)

• 範例資料目錄(下載 URL / 授權) —— 2-D 用 skimage.data(BSD/公有領域)加合成圖,3-D 給出真實資料源(Stanford/PDS 等)的下載 URL。

• 運算子來歷與參考文獻 —— 該運算子族所依據的研究/方法出處。

可執行的範例(實際呼叫該運算子並已驗證的樣例)

• structured_light — py -3.11 examples_3d/structured_light.py

型別可銜接的下一個運算子(可接受 `depth` 作為輸入)

depth_to_points · tsdf_from_depth · to_points · fuse_to_voxel · depth_to_organized_points · normals_from_depth · occlusion_edges · bearing_angle_image

同類別(`structured_light`)

wrapped_phase · unwrap_phase_2d · graycode_decode · synthesize_fringes · absolute_phase · triangulate_column

*Provenance: fringe.py — 3D 運算子登記表。本條目由 tools/opdocs.py md 自動產生(請勿手動編輯)。*

decode_fringe — 3D structured_light op

用法