he11lib/docs/superpowers/specs/2026-07-03-camera-geometry-redesign.md

he11lib — Full Camera Geometry & Measurement Uncertainty Redesign

Date: 2026-07-03 Status: Approved for planning Supersedes: parts of docs/superpowers/specs/2026-07-02-gyrotron-mode-purity-design.md relating to MeasurementPlane.pixel_scale/viewing_angle_deg, GeometryCalibration, and the single-scalar beam pointing angle. All other decisions in the original spec (mode basis, noise, deconvolution, phase-retrieval fallback, package layout) are unchanged and still apply.

Purpose

The original design modeled camera geometry as a single, isotropic pixel scale plus one viewing-angle tilt (a uniform, affine correction across the whole frame), and treated each MeasurementPlane's z distance as exact. Real measurement setups are more demanding:

• The camera's orientation relative to the beam axis has a full 3 rotational degrees of freedom (yaw, pitch, roll), not one.
• The camera is close/wide-angle enough that true perspective projection (keystoning that varies across the frame) matters, not just a uniform compression factor.
• A physical calibration step (e.g. fiducial markers) gives nominal values for camera position, orientation, and intrinsics — but mechanical vibration means none of these can be trusted as exact; all must be refined jointly with everything else.
• The beam's pointing/tilt is two-dimensional (independent horizontal and vertical tilt), not a single scalar angle.
• Each plane's z distance (from a translation stage or tape measure) is also only known to a nominal precision and should be refined, not trusted exactly.

Scope of this change

• Replace the single pixel-scale/viewing-angle model with a full pinhole camera model shared across all planes in one reconstruction.
• Generalize beam pointing from one angle to two (horizontal, vertical).
• Model each plane's z as a nominal value with its own refinable uncertainty.
• Unify "trusted/fixed" vs. "uncertain/refined" behind a single tolerance mechanism (see below), replacing the old None-means-unknown convention for geometry.
• Out of scope: lens distortion (radial/tangential), rolling-shutter effects, and multi-camera setups. These are not part of the current measurement setup and would need a separate design if they become relevant.

Architecture

Data model changes (data.py)

• MeasurementPlane drops pixel_scale and viewing_angle_deg (per-plane geometry no longer makes sense once the camera pose is a single shared physical setup for the whole reconstruction). It gains z_tolerance: float, the ± bound (in meters) around the nominal z within which the true distance is refined. z_tolerance must be >= 0; 0 means z is trusted exactly and held fixed.
• ReconstructionResult.pointing_angle_deg: float becomes two fields: pointing_angle_horizontal_deg: float and pointing_angle_vertical_deg: float.
• ReconstructionResult.geometry gains entries for the fitted CameraModel fields (see below) alongside the existing per-plane fitted z values.

CameraModel and CameraModelTolerance (geometry.py)

@dataclass
class CameraModel:
    focal_length_px: float
    position: tuple[float, float, float]        # (x, y, z) in the beam-axis frame,
                                                  # z=0 at the output window
    orientation_deg: tuple[float, float, float]  # (yaw, pitch, roll); all-zero =
                                                  # boresight normal to the target
                                                  # plane, no in-plane rotation
    principal_point: tuple[float, float] = (0.0, 0.0)  # (px, px) offset from frame center

@dataclass
class CameraModelTolerance:
    focal_length_px: float
    position: tuple[float, float, float]
    orientation_deg: tuple[float, float, float]
    principal_point: tuple[float, float] = (0.0, 0.0)  # (px, px)

CameraModel always represents a nominal point estimate (from calibration, or an assumed default), never a value trusted as exact by itself — trust/uncertainty is expressed entirely through the paired CameraModelTolerance (see "Tolerance mechanism" below).

GeometryCalibration is rewritten around these two types. Given a CameraModel and a target plane's z, it provides:

• Forward projection — physical (X, Y) at that z to pixel (row, col), via standard pinhole projection: rotate/translate the world point into the camera frame using orientation_deg/position, then perspective-divide using focal_length_px/principal_point.
• Inverse projection — pixel (row, col) to physical (X, Y), via ray–plane intersection: cast a ray from the camera through each pixel and intersect it with the known z = const target plane. This is what produces genuine keystoning (the correction varies across the frame), replacing the old uniform x = col * scale / cos(angle) formula.
• Raises ValueError for degenerate poses where the target plane is edge-on to or behind the camera (no valid intersection).

Tolerance mechanism (applies to CameraModel/CameraModelTolerance and

MeasurementPlane.z/z_tolerance)

Every nominal geometry value is paired with a tolerance that determines how ModalFitter treats it:

• tolerance == 0: held fixed at the nominal value. Excluded entirely from the optimizer's parameter vector and substituted as a constant into the model function. This recovers the old "fully known, don't fit it" behavior.
• tolerance > 0: included in the fit, bounded to [nominal - tolerance, nominal + tolerance] via scipy.optimize.least_squares' bounds=.

There is no "fully unbounded" mode for these parameters — if a value is genuinely unconstrained, its tolerance should be set generously wide rather than infinite, since an unbounded 7-9 parameter homography fit from 3-10 planes has little chance of converging usefully without some bound.

ModalFitter changes (fitting.py)

The optimizer's parameter vector is now built dynamically per reconstruction:

• Always free (unchanged in kind, generalized in the pointing case): complex LG mode coefficients, per-plane beam transverse center (x, y), and the two beam pointing angles (pointing_angle_horizontal_deg, pointing_angle_vertical_deg).
• Conditionally free (new): any CameraModel field whose paired CameraModelTolerance entry is nonzero, and any plane's z whose z_tolerance is nonzero — each bounded as described above.

BeamReconstructor.__init__ gains required camera: CameraModel and camera_tolerance: CameraModelTolerance parameters (alongside existing w0, z0, wavelength), replacing the old optional per-plane pixel-scale/viewing-angle handling.

SyntheticBeamGenerator changes (synthetic.py)

Takes an exact ground-truth CameraModel (position/orientation/intrinsics) and the two beam pointing angles, and generates each plane at its own exact/ground-truth z — which may deliberately differ from the nominal z given to the resulting MeasurementPlane, so tests can verify the fit recovers the true z despite a deliberately offset nominal input.

Data flow (updated)

1. Build a list of MeasurementPlane (flux array + nominal z + z_tolerance + label), plus a nominal CameraModel + CameraModelTolerance for the whole reconstruction.
2. GeometryCalibration resolves the pixel↔physical mapping per plane from the (possibly-still-being-refined) CameraModel and that plane's (possibly-being- refined) z.
3. NoiseEstimator computes per-plane noise weights (unchanged).
4. DiffusionDeconvolver optionally deblurs each plane (unchanged; still assumes an isotropic pixel-space kernel — noted as an existing approximation, not addressed by this redesign).
5. ModalFitter runs the joint noise-weighted nonlinear least-squares fit over LG coefficients + per-plane center + 2 pointing angles + any nonzero-tolerance camera and z parameters, growing the mode set automatically as before.
6. Phase-retrieval fallback and ReconstructionResult assembly proceed as in the original design, with pointing_angle_deg replaced by the horizontal/vertical pair and geometry extended to include the fitted CameraModel fields and per-plane fitted z.

Testing strategy

In addition to the original design's synthetic-ground-truth-recovery approach:

• CameraModel projection round-trip: for several poses (on-axis, tilted, off-center) and several z values, physical→pixel→physical recovers the original point.
• Keystone regression: projecting a symmetric grid through a tilted/off-axis CameraModel produces non-uniform spacing across the frame (distinguishing it from the old uniform cosine-compression model).
• Degenerate pose: a pose placing the target plane edge-on to or behind the camera raises ValueError.
• Tolerance semantics: a tolerance=0 field stays exactly at its (deliberately wrong) nominal value rather than being corrected; a tolerance>0 field recovers a ground truth offset from nominal but within its band; a ground truth placed outside a deliberately too-tight band is clipped to the bound rather than escaping it.
• End-to-end: the full pipeline recovers mode purity, both pointing angles, the camera pose, and per-plane z, when SyntheticBeamGenerator's ground truth is offset from the nominal inputs (within their tolerances) — simulating realistic calibration/measurement error rather than assuming perfect nominal values.

Error handling

• CameraModelTolerance fields and MeasurementPlane.z_tolerance must be >= 0; ValueError otherwise. Validated at construction, consistent with the existing "validate only at boundaries" approach.
• Degenerate camera geometry (target plane edge-on to or behind the camera) raises ValueError from the projection code rather than producing NaNs.
• New documented pitfall: with only 3-10 planes, adding ~7-9 shared camera unknowns plus one z correction per plane can be practically underdetermined even though each plane contributes many pixels of data, because those unknowns are global and only weakly constrained by subtle keystone differences between planes. fit_auto/BeamReconstructor emit a UserWarning (not an error, consistent with existing warn-don't-raise style) when the free-parameter count is large relative to the number of planes, prompting the user toward tighter tolerances rather than silently returning an ill-conditioned fit.

Migration impact

This is a breaking change to the public API, acceptable pre-1.0 with no external users yet:

• MeasurementPlane(pixel_scale=..., viewing_angle_deg=...) → MeasurementPlane(z_tolerance=...) + a reconstruction-level CameraModel/ CameraModelTolerance.
• BeamReconstructor(...) requires new camera/camera_tolerance arguments.
• SyntheticBeamGenerator.generate(...) requires a CameraModel and two pointing angles instead of scalar viewing_angle_deg/pixel_scale/pointing_angle_deg.
• ReconstructionResult.pointing_angle_deg → pointing_angle_horizontal_deg + pointing_angle_vertical_deg.
• docs/api.md and examples/full_pipeline_example.py need updating to match.
• The existing pitfalls documented in CLAUDE.md (Rayleigh-range clipping, mode-growth overfitting) still apply unchanged; the new degeneracy pitfall above is additive.

Deliverables

• Updated geometry.py (CameraModel, CameraModelTolerance, rewritten GeometryCalibration), data.py, fitting.py, synthetic.py, reconstruct.py.
• Updated tests covering projection round-trip, keystone behavior, degenerate poses, tolerance semantics, and end-to-end recovery under offset nominal inputs.
• Updated docs/api.md and examples/full_pipeline_example.py reflecting the new public interface.
• Updated CLAUDE.md with the new degeneracy pitfall.