surface_form_error — 3D surface_fit op

• Data kinds: image2d → measurement

• Call: import fullseye as fs; fs.ledger.surface_form_error(height, degree=1) (to call the implementation directly, import match3d; match3d.surface_form_error(height, degree=1); from the registry, ops3d.get("surface_form_error"))

• Return value through the ledger: fullseye.ledger.surface_form_error(...) returns only the declared out type measurement (the underlying function also returns auxiliary values). When you need what was dropped, use fullseye.ledger.surface_form_error.raw(...) or call match3d.surface_form_error directly.

• Underlying return: (residual, rms, pv) → pv float

Usage

Height-field grid → the residual from an ideal (polynomial) surface = the form error (flatness deg 1 / sphericity deg 2). → (residual, rms, pv).

Fits fit_poly_surface(degree) to the (H,W) height field with x = column index, y = row index, and returns residual = height − fit. degree=1 is the least-squares plane (flatness = pv), degree=2 is a 2nd-order surface (an approximation of a sphere, not a true sphere). Returns (residual (H,W) float64, rms, pv), in units of height (the lateral direction is in pixels, so the tilt coefficients are "height/pixel"). NaN makes lstsq fail (fill missing values first). Input that is not 2-D fails at the shape unpack.

Uses: evaluating flatness and waviness. background_flatten is the "image version" of the same computation. For the flatness of a point cloud use the resid of fit_plane_3d.

Background guides (the physics and conventions behind this op)

• blas_threads_and_memory — Why matrix decompositions are slow — BLAS threads, caches, memory layout

References (sample data, literature)

• 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.

Runnable examples (verified samples that actually call this op)

• geometry_metrology — py -3.11 examples_3d/geometry_metrology.py

Ops the type connects to (they accept measurement as input)

vol_gaussian_psf · fuse_to_voxel · fresnel_reflectance · snell_angle

Same category (surface_fit)

fit_poly_surface · eval_poly_surface · background_flatten

*Provenance: match3d.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.