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

用法