Stereo Rigs and Uncertainty
Two 0.9 changes share this page because they share a mechanism: the StereoRig became frames-native, and the statistical forms (CovMat/PrecMat) became frame-labeled — both so that a direction (or a transformation law) that used to live in a docstring is now checked by dispatch.
The frames-native StereoRig
A StereoRig is the 2-sensor case of the general Rig — a frame with posed members, whose frame is the gauge member's own. A sensor rig stores ONLY a tuple of cameras, each expressed rig-relative (reference frame = view 1, held at the identity); a rig of calibration targets is the same type with dict storage, PosedTarget members (a target model — PlanarTarget, PointTarget — and its pose) gauged on a board, and a camera rig carrying its marker constellation holds both. The pair's two cameras are the method-form accessors source and destination (no stored fields), and the relative rigid transform is derived from the stored per-camera labeled maps:
extrinsics(rig) :: EuclideanMap{3, …, ViewFrame{id₁}, ViewFrame{id₂}}(monogram X_{V₂V₁}: consumes source-view coordinates, produces destination-view coordinates, i.e. X₂ = R·X₁ + t). There is no cached inverse and no stored id tuple — the labels are the single source of truth:
pose(rig)is the on-demandinv(extrinsics(rig))(the typed algebra swaps the frames toX_{V₁V₂}).ids(rig)reads the view-identity symbols off the stored map's frame parameters — an accessor, not a field, resolved at compile time.view_frames(rig)/image_frames(rig)expose the minted per-viewViewFrame{id}/ImageFrame{id}tags, ready to attach at a lift.
rig = StereoRig(left_cam, right_cam; ids = (:left, :right))
ids(rig) # (:left, :right)
pose(rig) # ViewFrame{:right} → ViewFrame{:left}The 3-argument constructor validates a caller-supplied transform against extrinsics(destination) ∘ pose(source) computed from the given cameras (check = false for synthetic rigs whose cameras are placeholders).
Minting labeled epipolar forms
The rig mints the slot-labeled forms of the forms layer in one call:
essential_form(rig)— the calibrated formE = [t]×R, slots labeled by the per-viewGnomonicFrame{id}tags (the frame on whichEssentialMat-backed forms are honest: gnomonic coordinatesx̂ = π(K⁻¹ũ)).EpipolarForm(rig)— the pixel-frame fundamental form:essential_form(rig)'s correlation composed with the calibrated → pixel liftsHomographyMap{GnomonicFrame{id}, ImageFrame{id}}(Kᵢ), computingF = K₂⁻ᵀ E K₁⁻¹with every junction frame-checked.
Depth-driven utilities complete the two-view toolkit: depth_transfer (unit-depth point transfer — a transfer, not a correlation), transfer with depth-attributed points, and the ground-truth machinery validate_gt_metric, validate_gt_inliers that validates correspondences against a rig plus per-view depth maps with a metric (physical-length) tolerance.
Frame-labeled statistical forms
CovMat{N, T, L, F} and PrecMat{N, T, L, F} carry a trailing F <: Frame{N} parameter naming the frame their coordinates live in — defaulting to UnlabeledFrame{N}, gradual as always. The point of the labels is the law pair:
- covariance is a (2,0) tensor and pushes forward:
Σ ↦ J Σ Jᵀ - precision is a (0,2) bilinear form and pulls back:
Λ ↦ J⁻ᵀ Λ J⁻¹
Applying the covariance law to a precision matrix (or vice versa) produces a plausible-looking, silently wrong matrix — this pair is exactly the bug surface the frame labels exist to check. With the types in place, the law is dispatched, not remembered.
Checked propagation through framed maps
The raw-Jacobian layer propagate(J, Σ) = J Σ Jᵀ stays frame-free (a bare Jacobian carries no frames). The checked layer sits on top: pushing a statistical form through a framed map checks the form's frame against the map's Src (standing wildcard truth table) and stamps the result with the map's Dst:
propagate(m::EuclideanMap, Σ::CovMat) # J = R, pushforward, result labeled Dst
propagate(m::EuclideanMap, Λ::PrecMat) # J = R, pullback, result labeled Dst
propagate(m::EuclideanMap, u::Uncertain) # value and uncertainty in one call
propagate(h::HomographyMap, u::Uncertain) # point-dependent Jacobian at u.valueFor a rigid map the two conjugations coincide numerically (R is orthogonal); the code follows the honest law per type so propagate(m, inv(Σ)) == inv(propagate(m, Σ)) holds by construction. The HomographyMap overloads take the observation (Uncertain) rather than a bare form because the projective point action is nonlinear — the Jacobian must be evaluated at the point.
inv, cov, and prec preserve the frame (inversion swaps the representation, not the frame); relabel/unlabel are the escape hatches, one tag rather than two.
A batched counterpart pushes frame-labeled CovMatstacks through a stage's per-sample Jacobian stack — see Batched Maps.
See also
- Epipolar Forms — the slot-labeled forms the rig mints
- Coordinate Frames — view-identity frames
- Imaging Chain and Stereo API