surface_residual — 3D `freeform` op

• 数据种类:image2d × image2d × image2d × bspline_surface → measurement

• 调用: import fullseye as fs; fs.ledger.surface_residual(x, y, z, tck)(要直接调用实现,import bspline_surf; bspline_surf.surface_residual(x, y, z, tck);从台账取用则 ops3d.get("surface_residual"))

• 经台账调用的返回值: fullseye.ledger.surface_residual(...) 只返回声明的 out 类型 measurement 的值(底层函数还会返回辅助信息)。需要被丢弃的部分时,使用 fullseye.ledger.surface_residual.raw(...),或直接调用 bspline_surf.surface_residual。

• 底层返回: {"rms","max","pv"} → pv float

用法

返回散布数据与曲面 tck 的残差统计(形状误差=相对拟合的偏离)。

在各样本位置求曲面高度,测量与观测 z 之差的 RMS / 最大绝对值 / PV (peak-to-valley = 最大 - 最小)。在检测中,这是相对自由曲面的偏差量(凹痕、波纹度、缺料)的定量指标。

Returns

dict

{"rms": float, "max": float, "pv": float}。max 为最大绝对残差,

pv 为带符号残差的最大 - 最小(也能捕捉单侧的凸起/凹陷)。

补充:

• 残差符号为 resid = z - zhat(观测 − 曲面)。正 = 高于曲面(隆起),负 = 低于曲面(缺料)。max 是绝对值,看不出方向;需要方向时用 eval_bspline_surface 取 zhat 自行求差。

• x, y, z 接受任意 shape,内部经过 eval_bspline_surface(tck, x, y, grid=False)(tck 类型检查也在那里进行,曲线 tck 或多项式 dict 为 ValueError)。z 与 x 元素数不同时会出现 numpy 的形状错误(没有专门检查,z 只有 1 个元素时会静默 broadcast)。

• 单位与 z 相同。rms 是全部点的均方根,因此局部凹痕会被平均冲淡。局部缺陷用 max 或 pv 查看。

• 典型:fit_bspline_surface → 本 op。在拟合所用的点上求值时,smooth 越小残差越接近 0(也可作为过拟合的指标)。

参考(示例数据、文献)

• 示例数据目录(下载 URL / 许可证) —— 2-D 用 skimage.data(BSD/公有领域)加合成图,3-D 给出真实数据源(Stanford/PDS 等)的下载 URL。

• 算子来历与参考文献 —— 该算子族所依据的研究/方法出处。

可运行的示例(实际调用该算子并已验证的样例)

• bspline_freeform — py -3.11 examples_3d/bspline_freeform.py

类型可衔接的下一个算子(可接受 `measurement` 作为输入)

vol_gaussian_psf · fuse_to_voxel · fresnel_reflectance · snell_angle

同类别(`freeform`)

fit_bspline_surface · eval_bspline_surface · fit_bspline_curve · eval_bspline_curve

*Provenance: bspline_surf.py — 3D 算子登记表。本条目由 tools/opdocs.py md 自动生成(请勿手工编辑)。*

surface_residual — 3D freeform op

用法