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

用法