feat(stereo-camera): R2 — service-side rectifier (u_stereo_rectify), distorted fake, probe --rectified

[dfattal]

This PR is phase R2 of the stereo camera source (ADR-043, spec, roadmap). The service now rectifies any calibrated camera itself, in vendor-neutral C with no OpenCV dependency. Clients get RECTIFIED frames and rectified calibration. RAW frames are still refused to the browser.

Stacked on #1746 (feat/stereo-camera-r1); merge #1746 first. Rebased 2026-10-03 onto the post-lift R1 (lift #1781 is merged, v2.22.0): order is now R1 → R2 → L1 → B1; the ABI positions (camera slots after create_dp_d3d11_lift + get_platform_state, type values 1004999300–310) are in #1746's rebase comment. The Windows tester's f433d31fc (PRESENT_OWNER owner quota) survives as 0191f5481. The first real source is the Leia provider (L1): DisplayXR/displayxr-leia-plugin#273, which carries the on-hardware recipe.

What's in it

• auxiliary/util/u_stereo_rectify.{h,c} has three layers, so a GPU path can replace only the last one:
  1. Geometry. u_stereo_rectify_compute re-implements OpenCV's stereoRectify(CALIB_ZERO_DISPARITY, alpha = 0). Each camera is rotated by half the relative rotation, the baseline is put on the x axis, focal = min fy, the principal point is the corner centroid, and the image is zoomed to the valid region. The zoom is then checked on every border pixel of the real maps and increased until no output pixel samples outside its raw image. No convergence shear is applied.
  2. Float maps. u_stereo_rectify_build_map is what a GPU backend uploads as an RG32F texture.
  3. CPU backend. A fixed-point bilinear LUT over the whole SBS image (6 bytes per sample). GRAY8 and BGRA8 use one LUT; NV12 uses a full-res Y LUT plus a half-res UV LUT.
  • Supported lens models: RADTAN5, RADTAN8 and KB4. Calibration taken at a different size than the frames is rescaled.
• Service (ipc_server_stereo_camera.c):
  • A struct scam_rectifier per camera is built at create time from the plug-in's RAW calibration, whenever the camera is CALIBRATED and not NATIVELY_RECTIFIED. The WARN line reports f, principal point, baseline, zoom and build time.
  • It runs once per source frame, on the camera thread with the lock released, and only while a started stream wants RECTIFIED. RAW streams read the original frame. A RECTIFIED stream never receives unrectified pixels.
  • get_calibration(RECTIFIED) returns the same geometry: one pinhole for both eyes, model NONE, and rightFromLeft = identity plus (+B, 0, 0). horizontalFovDeg is the rectified value.
  • The browser (PRESENT_OWNER) is refused (INPUT_UNSUPPORTED) a camera the rectifier rejected. It no longer gets the RAW-flagged fallback that native clients get.
  • The INFO stats line adds rectify ms/frame.
  • It WARNs when a plug-in's calibration puts the right camera at −x (T.x > 0, i.e. the SBS halves look swapped). The pair still rectifies, but every disparity would come out negative.
• Fake: SIM_DISPLAY_FAKE_STEREO_CAMERA_DISTORT=1 produces a raw pair with exact ground truth:
  • different per-eye intrinsics and RADTAN5 barrel lenses;
  • 0.7° relative pitch and 0.9° relative roll.
  • The rotation is split symmetrically (left Sᵀ, right S), so Bouguet recovers exactly the virtual parallel pair. After rectification, disparity is exactly f·B/Z.
• CLI:
  • camera calib <id> --rectified prints P1/P2 and Z = f·B/d.
  • Every probe now reports row alignment: 2-D block matching over dx and dy on textured blocks, giving |dy| median / p90 / blocks > 1 px, and the dominant disparities converted to depths.
  • probe --rectified exits 5 if the frames come back RAW or the median |dy| is above 0.5 px.
• Docs: the spec §4/§10/§11/§13, the roadmap ("R2 as built", phase table), the ADR status and the iface reference are updated.

Test evidence (macOS, M1 Pro)

tests_stereo_rectify (716 assertions) uses golden fixtures from tests/fixtures/gen_stereo_rectify_fixtures.py (OpenCV 4.10, run offline, header committed). There are 3 calibrations: the sim fake, an SR-like pair with a non-axial T, and a RADTAN8 pair calibrated at 2× the frame size.

Check	Result
R1/R2 vs OpenCV	equal to 1e-12
Principal point vs converged reference	within 1e-4 px
Principal point vs OpenCV's own P1	within 0.75 px. OpenCV stops undistortPoints after 5 iterations; we iterate to convergence
Focal after zoom	+0.05 to +0.13 % vs OpenCV (our border check only ever zooms further; OpenCV leaves 8 black pixels on the RADTAN8 case)
Maps vs initUndistortRectifyMap	≤ 3.0e-5 px
Black output pixels	0, at full and half resolution

End to end on the distorted fake:

	Result
RAW pair	median
RECTIFIED, worst block of 689	**
Background disparity	ground truth 11.330 px, measured median 11.305, worst block error 0.059 px
Bar disparity	ground truth 37.765 px, measured median 37.785, worst block error 0.063 px

NV12 and BGRA8 planes are bit-identical to GRAY8 where comparable. tests_stereo_camera (R1) and tests_ipc_proto still pass.

Live service + CLI (Debug service, SIM_DISPLAY_FAKE_STEREO_CAMERA=1 _DISTORT=1 DXR_STEREO_CAMERA_DEV_ALLOW=1):

stereo camera 1: rectifier ready (CPU) — f 453.18 px, principal point (320.43, 239.36), baseline 50.00 mm, valid-region zoom x1.1109, 614400/614400 valid taps, built in 38.1 ms
$ displayxr-cli camera calib 1 --rectified
  P1 = [453.181 0 320.426 0; 0 453.181 239.364 0; 0 0 1 0]
  P2 = [453.181 0 320.426 -22659.030; 0 453.181 239.364 0; 0 0 1 0]   (P2[0][3] = f * Tx, Tx = -50.000 mm)
$ displayxr-cli camera probe --rectified --frames 150
measured delivery rate: 29.99 Hz over 4.97 s
row alignment (RECTIFIED, 221 textured 32x32 blocks): |dy| median 0.016 px, p90 0.064 px, 9 block(s) > 1 px
  disparity mode 1: 11.30 px (165 blocks) -> Z = f*B/d = 2.004 m
  disparity mode 2: 37.81 px (48 blocks) -> Z = f*B/d = 0.599 m
--rectified: PASS — rows aligned
$ displayxr-cli camera probe --raw --format gray8
row alignment (RAW, 221 textured 32x32 blocks): |dy| median 2.589 px, p90 5.292 px, 183 block(s) > 1 px

• The 9 outlier blocks sit on the bar's occlusion edges and on the frame counter, which is burned in raw space.
• A RAW gray8 stream and a RECTIFIED bgra8 stream capped at 15 Hz ran concurrently from one source: 29.97 Hz and 15.00 Hz.
• The undistorted (NATIVELY_RECTIFIED) fake is unchanged: no rectifier is built, disparities are 12.00 / 40.00 px, and |dy| median is 0.004 px.

MinGW-w64: build-mingw-check.sh aux_util drv_sim_display passes, with no warnings from the new files. It caught a -Wpedantic array-qualifier issue, which is fixed.

Performance (CPU budget)

Measured single-threaded on an M1 Pro at -O2, per 1280×480 frame:

Format	Time
GRAY8	0.94 ms
NV12	1.36 ms
BGRA8	2.25 ms

• A Debug service measures 3.0 ms for GRAY8.
• For the Leia GRAY8 source at 30 Hz, that is about 3 % of one core.
• Budget: ≤ 2 ms per frame on the camera thread. Past that, split the rows across threads with u_stereo_rectify_lut_apply_rows, or move to the GPU backend.
• One-time setup (geometry + both LUTs) takes 9–18 ms. LUT memory is 4.6 MB per camera.
• With the distorted fake, the service stats show about 28 ms mean latency. Most of that is the fake re-rendering its warped scene in Debug, not the rectifier.

Deviations from the design

• The alpha = 0 zoom is stricter than OpenCV's (it is verified per border pixel), which costs at most +0.13 % focal on the fixtures.
• The principal point uses a converged undistortPoints (OpenCV stops at 5 iterations).
• A PRESENT_OWNER request for RECTIFIED on a camera that cannot be rectified is now refused. Before, it returned RAW-flagged frames; this tightens the "no raw frames to pages" decision.

Not tested

• Windows MSVC, Linux and Android builds and runs (CI covers the builds).
• Real hardware (that is L1's recipe).
• The GPU backend (only the seam exists).
• Runtime recalibration: calibrationGeneration stays 0, and the rectifier is built once per service lifetime.
• KB4 has round-trip tests only, with no OpenCV golden, because OpenCV's plain stereoRectify does not model fisheye lenses.

🤖 Generated with Claude Code

[dfattal]

Follow-ups from the first SR-hardware run. I rebased onto the updated R1 and force-pushed with lease; 8fce4c3c3 (M_PI) is kept.

• Probe verdict (9c2385671): row alignment now uses u_stereo_camera_match_block, a zero-mean NCC matcher with coarse-to-fine search and parabolic sub-pixel refinement. It returns its search window and flags a peak that lands on either bound. The probe uses:
  • a baseline-aware disparity window and dy ±24 px;
  • an NCC ≥ 0.90 acceptance, with low-NCC and at-bound blocks counted and excluded (it warns when more than 20% hit a bound);
  • reporting of the signed dy median;
  • --rectified now also fails on a constant offset.
  • Overrides: --max-disparity, --max-dy, --min-ncc.
• The distorted fake honours _BASELINE_MM.
• Tests:
  • A 120 mm matcher test: bar 94.9 px, signed dy +1.68 recovered as +1.74, with gain/offset and a flat block. The old 64 px window now gets rejected instead of reported.
  • An end-to-end test at 120 mm: bar ground truth 90.64 px, measured 90.66 px, signed dy −0.0001.
  • [vshift] hypothesis tests for the +1.7 px field residual:
    • a per-eye cy error gives a constant dy ≈ −Δcy (spread < 0.13);
    • a transposed R gives a large dy that follows the roll (−13 px, spread 7), so it is not a clean offset;
    • the calibration-size rescale and L1's swap (R′ = Rᵀ, T′ = −RᵀT) are exact;
    • an identity calibration is a pure scale about cy (the border nudge zooms ×1.001).

Verified: macOS build, ctest -R stereo (all pass), MinGW, and the probe on the distorted fake at 50 and 120 mm (--rectified PASS; 120 mm Z = 2.002 / 0.600 m).

[dfattal]

+1.7 px vertical residual on the SR laptop: diagnosed. The runtime rectifier is correct; the calibration doesn't match the frames.

Data: David's upload from the SR laptop (device QALA2137AL0011): the raw SBS frame, the runtime-rectified frames, the ProgramData intrinsics.yml/extrinsics.yml, the calib dumps and the service log.

I rectified the same raw frame with OpenCV stereoRectify + initUndistortRectifyMap from the same ymls (left = camera 2, R' = Rᵀ, T' = −RᵀT, the plug-in's swap) and measured SIFT matches:

	signed dy median (R−L)	std
raw	+19.09 px (≈ calib cy diff 19.65 ✓)	4.2
OpenCV rectified (alpha 0)	+1.71 px	2.2
runtime rectified (same frame)	+1.71 px	1.1
runtime rectified, face 0.6 m	+1.68 px	—

OpenCV's P1 also matches the runtime's to 0.5 px in f and 0.01 px in the principal point. So the rectifier reproduces OpenCV exactly, and OpenCV has the same residual: the ymls don't describe these frames perfectly.

The residual is not a pure offset: a fit gives dy ≈ +2.6 px at the centre with a −0.47 px / 100 px slope in y, which reads as a small pitch/vertical-scale mismatch, not a single cy error. (That kills my "one eye's cy" lead hypothesis.)

Most likely cause: the ProgramData ymls are a cache and not what SR uses at runtime. The SR Server log on the 8K box reads "Fetching Stereo Camera calibration data from FPC", i.e. the live calibration comes from the device itself.

Next:

• ask the SR SDK for the LIVE stereo-camera calibration (an API, or which file is authoritative);
• optionally, a runtime-side online vertical-alignment refinement (estimate a dy offset plus y-slope from matched features over a few seconds and fold it into the rectification). It's cheap and would also absorb drift.

Script: OpenCV 4.10, SIFT 4000, ratio 0.7.

🤖 Generated with Claude Code

[dfattal]

Online vertical-alignment refinement added (602ae1ae8..91cfc6930). It addresses the +1.7 px SR residual diagnosed above.

What it does

• Model: dy = a + b·(y − cy) (right minus left, output px). On the SR data the x/roll term was 0.04 px / 100 px (≤ 0.15 px at the edge, below match noise), so it is left out.
• A per-camera worker (off the frame path) measures rectified frames the camera thread hands it:
  • Shi-Tomasi patches on a 2× downscale, NCC over d × dy, then full-res NCC ±2 px with parabolic sub-pixel.
  • Gated on NCC ≥ 0.9, d > 0, a peak not on a window bound, and real vertical curvature.
  • Robust fit: median start, then Tukey IRLS.
• When the correction moves by more than 0.2 px, the worker rebuilds geometry + LUTs with v_offset = a/f and v_slope = b folded in.
  • The fold is a symmetric per-eye vertical affine in normalized rectified coordinates, applied before the principal point and alpha = 0 crop. So P1/P2 still describe one pinhole with a pure +x baseline, and they match the corrected frames.
  • The camera thread swaps the new maps in between frames and bumps calibration_generation.
• Duty cycle: every 250 ms for 5 s after an open or an update, then one 3-frame window every 30 s.
• Cost: 2.7 ms per measurement at -O2 (< 0.4 ms/frame amortised at 30 Hz); 8 ms per rebuild.
• Safety:
  • clamps |a| ≤ 6 px and |b| ≤ 2 px / 100 px;
  • needs ≥ 50 matches over ≥ 3 frames;
  • re-verified on every re-open;
  • kill switch DXR_STEREO_CAMERA_REFINE=0.
• Logging: one WARN on the first application, INFO after that (never per frame).
• camera probe prints the state, the applied a/b, the match count, and dy before → after.

Results (macOS)

• tests_stereo_vrefine, all 3 stereo suites green:

  • Fake with the SR model injected (SIM_DISPLAY_FAKE_STEREO_CAMERA_DY=2.6, _DY_SLOPE=-0.47): converges in one rebuild, and the fit recovers b = −0.469.

  • Real SR frame, checked against an independent judge (63 OpenCV SIFT matches; fixture stereo_vrefine_sr_raw.jpg, 62 KB):

    	signed dy median
    before	+1.715 px
    after	+0.075 px

  • Flat, noise and vertical-stripe frames never apply a correction, and the clamps hold.

• Live service + probe on the fake (+2.6 px injected):

  WARN stereo camera 1: vertical-alignment refinement APPLIED — the calibration left the rows +2.51 px off (fit +2.49 px -0.469 px/100 px about the centre row, 438 matches); correction a +2.49 px, b -0.469 px/100 px, maps rebuilt in 38.9 ms
  $ displayxr-cli camera probe --rectified --frames 90
    dy (right - left) median +0.001 px SIGNED; |dy| median 0.017 px ...  Z = 2.004 m / 0.600 m
  vertical refinement: APPLIED — correction a +2.49 px, b -0.469 px/100 px; 1 update(s), 5 window(s), 447 matches ...
  vertical refinement: signed dy BEFORE (first window, uncorrected) +2.51 px -> latest window +0.01 px; this probe's last frame +0.00 px (254 blocks)
  --rectified: PASS — rows aligned
  

  • With DXR_STEREO_CAMERA_REFINE=0: signed dy +2.54 px and --rectified: FAIL, as expected.
• MinGW aux_util drv_sim_display passes. MinGW has no ipc_server target, so the service file is covered by MSVC CI.

On-hardware check (Windows SR box)

1. Build and push the runtime. Keep DXR_STEREO_CAMERA_DEV_ALLOW=1 in the service's environment.
2. Run displayxr-cli camera probe --rectified --format gray8 --seconds 6. The service needs about 1 s to settle, and the scene needs some texture: a sparse ceiling gave ~23 matches per frame, so 3 frames are enough.
3. Expect this service-log line: vertical-alignment refinement APPLIED — the calibration left the rows +1.6..1.8 px off (… N matches); correction a ≈ +1.7 px …
4. In the probe output, expect:
   • vertical refinement: APPLIED … signed dy BEFORE (first window, uncorrected) ≈ +1.7 px -> latest window ≈ 0.0 px;
   • the probe's own dy (right - left) median within ±0.5 px;
   • --rectified: PASS.
5. A/B: restart the service with DXR_STEREO_CAMERA_REFINE=0. The probe should then read about +1.7 px again.

Not done:

• no GPU backend;
• no roll term;
• no reset path, because nothing changes the calibration at runtime yet (u_stereo_vrefine_reset is there for that);
• no merges.

🤖 Generated with Claude Code

[dfattal]

Review of f433d31 (PRESENT_OWNER quota counts distinct owner executables), from mac/holocall: approve for this branch.

• Correct: a same-exe sibling takes no slot; distinct executables still fill the quota; an unreadable exe path ("") is never a sibling and each counts separately (fails closed). The seen[] static is only touched under global_state.lock. ipc_server_peer_exe_path exists on both the Windows and POSIX paths, so macOS/Linux are unaffected.
• Semantics note: two independent instances of the SAME browser exe (e.g. different user-data-dirs) now share one owner slot. I think that's acceptable for panel arbitration (ipc: explicit client classes (CONTROLLER / APP / PRESENT_OWNER / RELAY / PROVIDER_HOST / DIAG) assigned and verified at connect; per-class quotas and priority #960), but worth one line in the ipc: explicit client classes (CONTROLLER / APP / PRESENT_OWNER / RELAY / PROVIDER_HOST / DIAG) assigned and verified at connect; per-class quotas and priority #960 doc.
• Design follow-up (not blocking): the capture utility is PRESENT_OWNER only because B1 enables XR_DXR_weave to be classed as "the browser" for the RECTIFIED-only rule. Cleaner, later (R3, consent): give camera-only clients their own class (a camera/sensor client) and key the browser rule on the registered browser identity, so a capture process never competes for panel ownership at all. Tracked for R3.

🤖 Generated with Claude Code