freeform op• Data kinds: image2d × image2d × image2d × bspline_surface → measurement
• Call: import fullseye as fs; fs.ledger.surface_residual(x, y, z, tck) (to call the implementation directly, import bspline_surf; bspline_surf.surface_residual(x, y, z, tck); from the registry, ops3d.get("surface_residual"))
• Return value through the ledger: fullseye.ledger.surface_residual(...) returns only the declared out type measurement (the underlying function also returns auxiliary values). When you need what was dropped, use fullseye.ledger.surface_residual.raw(...) or call bspline_surf.surface_residual directly.
• Underlying return: {"rms","max","pv"} → pv float
Return the residual statistics between scattered data and a surface tck (the form error = the deviation from the fit).
Evaluates the surface height at each sample position and measures the RMS / maximum absolute value / PV (peak-to-valley = maximum - minimum) of the difference from the observed z. In inspection this is the quantitative index of deviation from a free-form surface (dents, waviness, missing material).
dict
{"rms": float, "max": float, "pv": float}. max is the largest absolute residual,
pv is the maximum - minimum of the signed residuals (also captures one-sided bumps/dips).
Notes:
• The residual sign is resid = z - zhat (observed − surface). Positive = higher than the surface (bulge), negative = lower (missing material). max is an absolute value so the direction is lost; if you need it, get zhat with eval_bspline_surface and take the difference yourself.
• x, y, z accept any shape and go through eval_bspline_surface(tck, x, y, grid=False) internally (the tck type check also happens there; a curve tck or a polynomial dict gives ValueError). If z and x differ in element count, numpy raises a shape error (there is no dedicated check, and a 1-element z is silently broadcast).
• The unit is the same as z. rms is the root mean square over all points, so local dents are diluted by averaging. Look at local defects with max or pv.
• Typical: fit_bspline_surface → this op. Evaluated at the points used for the fit, the residual approaches 0 as smooth gets smaller (it also serves as an indicator of overfitting).
• Sample-data catalog (download URLs / licences) — 2-D uses skimage.data (BSD/public domain) plus synthetic images; 3-D lists download URLs for real data sources (Stanford, PDS, …).
• Operator provenance and references — the sources of the research/methods this op family came from.
• bspline_freeform — py -3.11 examples_3d/bspline_freeform.py
measurement as input)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 operator registry. This per-op note is generated by tools/opdocs.py md (do not hand-edit).*
© 2026 Kazufumi Furuse — Fullseye operator documentation. Licensed under Apache-2.0.