normals_from_depth — 3D `range_image` op

• 資料種類:depth → normalmap

• 呼叫: import fullseye as fs; fs.ledger.normals_from_depth(depth, fx=None, fy=None, cx=None, cy=None, orient_to_camera=True, spacing=None)(要直接呼叫實作,import range_image; range_image.normals_from_depth(depth, fx=None, fy=None, cx=None, cy=None, orient_to_camera=True, spacing=None);從台帳取用則 ops3d.get("normals_from_depth"))

用法

organized 深度 → 帶朝向的單位法線 (H,W,3)。相鄰像素 3D 點的外積(利用格點結構,O(HW))。

指定 fx,fy 時為透視,未指定時為正交。orient_to_camera=True 時把法線符號統一為朝向相機(原點)。

★同名的另一個函式存在於 1 行 facade 中。fullseye.normals_from_depth 是 (depth, K, smooth=0) 的透視版,K 必需,而這裡(經由 fullseye.ledger = range_image)是不取 K 的正交版。記住其中一個的呼叫方式,用另一個時就會出現 TypeError(2026-09-08 實測)。

★spacing=(dy, dx) 是正交模式下像素的實際尺寸。預設 None 表示「1 像素 = 1 單位」,把各向異性的網格(例:行 0.05 mm × 列 0.5 mm)直接傳入時,傾斜會悄無聲息地偏離 —— 實測 x 分量偏了 20 倍(= 1/dx 倍),既沒有例外也沒有警告。如果知道實際尺寸,務必傳入。透視模式(指定 fx/fy)下焦距決定實際尺寸,因此會被忽略。★傳入 spacing 時請設 orient_to_camera=False。正交下的「相機」只是原點(左上、深度 0)這一權宜設定,代入實際尺寸後它相對於面的位置會改變,符號可能反轉(實測:傾斜 0.1 的平面上 orient_to_camera=False 時與真值 x=-0.0995 一致,True 時為 +0.0995)。若需要朝向,請在能定義視線的座標系中於後續步驟統一。

法線由相鄰像素的外積得出,因此兩個軸上都需要鄰域。H<2 or W<2 時沒有第 2 個切線方向, 法線無法定義(若把該軸梯度視為 0,會靜默回傳 cross(dPx,0)=[0,0,0] 的退化法線)。因此 fail-closed,明確以 ValueError 拒絕。

計算時以 depth_to_organized_points 產生 3-D 點 P,取 np.gradient 的行方向差分 dPx 與列方向差分 dPy 的外積 dPx × dPy 並單位化(邊緣為單側差分)。orient_to_camera=True 時翻轉 n·(-P) < 0 的像素,使法線朝向原點(相機) 對齊。正交模式(fx 或 fy 為 None)下 P=(u,v,d),因此原點位於影像左上深度 0 的位置,「朝向相機」的含義與透視模式不同,請注意。cx、cy 省略時為影像中心。在跨越深度階躍(遮擋邊緣)的像素上,外積會捕捉到階躍的方向而使法線損壞,因此請先以 occlusion_edges 去除邊界像素再使用。深度 0 / NaN 的像素不做驗證,法線也不確定。回傳值為 float32 的 (H,W,3)。

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

• blender_interop — 與 Blender 搭配使用 —— 在 Blender 中建形、用 fullseye 量測(座標軸、單位、真值資料的陷阱)

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

參考(範例資料、文獻)

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

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

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

• range_image — py -3.11 examples_3d/range_image.py

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

fuse_to_voxel · render_shaded · phong_shade · matcap_shade · brdf_lommel_seeliger · brdf_hapke · bump_normals_fbm · integrate_normals

同類別(`range_image`)

depth_to_organized_points · occlusion_edges · bearing_angle_image

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

normals_from_depth — 3D range_image op

用法