# C1 KLT/RANSAC Strategy — Mandatory Simple-Baseline VIO

**Task**: AZ-334_c1_klt_ransac_strategy
**Name**: C1 KLT/RANSAC Strategy
**Description**: Implement `KltRansacStrategy`, the mandatory simple-baseline `VioStrategy` that satisfies the ADR-002 engine rule (every component MUST ship a simple-baseline strategy alongside its production-default). The class is a pure-Python facade over OpenCV's pyramidal KLT optical-flow + RANSAC essential-matrix path. No C++/pybind11 — OpenCV's Python bindings provide everything needed, keeping the simple-baseline path camera-agnostic, dependency-light, and dead-easy to reason about. Bound by AC-2.1a (≥ 95 % tracked-frame ratio on the Derkachi normal segment) and AC-2.2 (MRE p95 < 1 px frame-to-frame; `tests.md` C1-IT-04 binds KltRansac alongside Okvis2). Build-time gated by `BUILD_KLT_RANSAC=ON` (airborne / research / replay-cli; operator-tooling does not need VIO).
**Complexity**: 5 points
**Dependencies**: AZ-331_c1_vio_strategy_protocol, AZ-263_initial_structure, AZ-269_config_loader, AZ-266_log_module, AZ-276_imu_preintegrator, AZ-277_se3_utils, AZ-282_ransac_filter, AZ-272_fdr_record_schema, AZ-273_fdr_client_ringbuf
**Component**: c1_vio (epic AZ-254 / E-C1)
**Tracker**: AZ-334
**Epic**: AZ-254 (E-C1)

### Document Dependencies

- `_docs/02_document/contracts/c1_vio/vio_strategy_protocol.md` — the Protocol this task implements; produced by AZ-331.
- `_docs/02_document/contracts/shared_helpers/imu_preintegrator.md` — IMU substrate (AZ-276); the simple-baseline still consumes the GTSAM `CombinedImuFactor` so C5 fusion sees a consistent `VioOutput` shape.
- `_docs/02_document/contracts/shared_helpers/se3_utils.md` — SE(3) ↔ pose-matrix utilities (AZ-277).
- `_docs/02_document/contracts/shared_helpers/ransac_filter.md` — generic RANSAC inlier filter (AZ-282); reused for the essential-matrix outlier rejection step.
- `_docs/02_document/components/01_c1_vio/description.md` — § 5 implementation details + § 6 helpers + § 7 caveats (sharp turns < 5 % frame overlap cause feature-track loss in all three strategies).
- `_docs/02_document/components/01_c1_vio/tests.md` — C1-IT-03 (≥ 95 % tracked-frame ratio); C1-IT-04 (MRE p95 < 1 px) — both bind this strategy.
- ADR-002 — the engine rule that mandates this baseline.

## Problem

Without `KltRansacStrategy`:

- The ADR-002 engine rule is violated; every airborne binary MUST link a simple-baseline strategy alongside the production-default.
- AC-2.1a (95 % tracked-frame ratio on normal segments — the engine rule's quantitative gate) has no producer; the Derkachi C1-IT-03 fixture cannot validate the rule.
- The deployment binary's defense-in-depth posture collapses: an OKVIS2 backend init failure leaves the runtime with no fallback path.
- The simple-baseline serves as an interpretability anchor — when the production-default OKVIS2 produces a surprising covariance, the operator's debugging step is "compare to KLT/RANSAC on the same input"; without it, the comparison has nothing to compare against.
- The dependency-light path (no OKVIS2 / VINS-Mono native libs) becomes important for Tier-0 workstation development; without `KltRansacStrategy`, every developer needs OKVIS2 native libs installed.
- IT-12 comparative-study cannot include the simple-baseline as a third data point.

This task delivers the engine-rule mandatory baseline. It is the lowest-complexity strategy in this epic by code volume but carries the highest test coverage ratio because the AC-2.1a / AC-2.2 bounds are the gate.

## Outcome

- A `KltRansacStrategy` class at `src/gps_denied_onboard/components/c1_vio/klt_ransac.py` conforming to the `VioStrategy` Protocol from AZ-331; `current_strategy_label() == "klt_ransac"`.
- No `_native/` binding — pure Python over OpenCV's `cv2.calcOpticalFlowPyrLK` + `cv2.goodFeaturesToTrack` + `cv2.findEssentialMat` + `cv2.recoverPose` path. The `helpers.ransac_filter` (AZ-282) is reused for outlier rejection of the per-frame correspondences before pose recovery.
- Constructor `__init__(self, *, calibration: CameraCalibration, preintegrator: ImuPreintegrator, ransac_filter: RansacFilter, fdr_client: FdrClient, logger: Logger, config: KltRansacConfig)` — all dependencies constructor-injected per ADR-009. `KltRansacConfig` (`@dataclass(frozen=True)`) carries the KLT-specific knobs (max corner count, KLT pyramid levels, KLT window size, RANSAC inlier ratio, essential-matrix RANSAC threshold, min-features-for-pose) loaded from `config.vio.klt_ransac.*` via AZ-269.
- `process_frame(frame, imu, calibration) -> VioOutput`:
  1. Append IMU samples to the injected `ImuPreintegrator` (the IMU contributes to bias accumulation; KLT itself is vision-only, but the `VioOutput.imu_bias` field still gets populated from the helper's current bias estimate).
  2. Convert the input `NavCameraFrame.pixels` to grayscale (OpenCV expects `uint8` single-channel for KLT).
  3. If this is the first frame, run `cv2.goodFeaturesToTrack` to seed the feature track buffer; emit `VioOutput` with `state == INIT` (zero relative pose, conservative covariance).
  4. Otherwise, call `cv2.calcOpticalFlowPyrLK` to track the prior frame's features into this frame; reject `status==0` correspondences.
  5. Run `cv2.findEssentialMat` with `cv2.RANSAC` over the surviving correspondences using `calibration.K`; reject correspondences whose RANSAC mask is 0.
  6. Recover the relative pose via `cv2.recoverPose`; convert to SE(3) via `helpers.se3_utils`.
  7. Estimate per-frame covariance from the inlier-residual scatter (sample covariance of 2D reprojection residuals back-projected to a 6×6 pose-perturbation covariance via the camera Jacobian; standard textbook approach — see Risks for the honest-covariance constraint).
  8. Compute `feature_quality.mre_px` from the inlier residuals; `tracked` / `new` / `lost` counts come from the KLT step.
  9. Build and return `VioOutput` with `frame_id` echoed; emit per-frame DEBUG log if enabled.
- `reset_to_warm_start(hint)`: clears the prior-frame feature track buffer, seeds the IMU bias from `hint.bias` via the preintegrator's `reset_with_bias`, and resets the internal "first frame seen" flag so the next `process_frame` re-seeds features. The hint's `body_T_world` is recorded as the baseline for relative-pose chaining; KLT/RANSAC's per-frame relative pose is interpreted relative to this baseline by C5 fusion.
- `health_snapshot()` returns `VioHealth(state, consecutive_lost, bias_norm)`:
  - `INIT` for the first 1–2 frames (until KLT has a prior to track from);
  - `TRACKING` when inlier count ≥ `config.vio.klt_ransac.min_features_for_pose`;
  - `DEGRADED` when inlier count drops below threshold (covariance Frobenius norm grows in proportion);
  - `LOST` after `config.vio.lost_frame_threshold` consecutive frames where pose recovery fails (e.g., RANSAC finds no consensus).
- The honest-covariance invariant is enforced behaviourally: the per-frame covariance grows monotonically as inlier count drops; no client-side floor or smoother is applied.
- Error envelope is closed: every OpenCV `cv2.error` is caught inside `process_frame` / `reset_to_warm_start` and rewrapped into the `VioError` family. `VioInitializingError` for the first frame; `VioFatalError` on sustained pose-recovery failure (RANSAC consensus < threshold for `lost_frame_threshold` frames).
- All FDR records emitted via the injected `FdrClient` use the `kind="vio.health"` schema.

## Scope

### Included

- `KltRansacStrategy` class + `KltRansacConfig` dataclass.
- The full `process_frame` / `reset_to_warm_start` / `health_snapshot` / `current_strategy_label` surface conforming to AZ-331's Protocol.
- IMU substrate via the constructor-injected `ImuPreintegrator` (AZ-276); the simple-baseline still calls into the helper for bias accumulation so `VioOutput.imu_bias` is consistent across all three strategies.
- RANSAC outlier rejection via the constructor-injected `RansacFilter` (AZ-282); KLT/RANSAC does not duplicate AZ-282's logic.
- Honest covariance estimation from the residual scatter — the formula and its limitations are documented in the spec; no smoothing on the read path.
- Per-frame DEBUG log gated by `config.vio.per_frame_debug_log` (default OFF).
- WARN / ERROR / INFO logging per description.md § 9.
- Health-state transitions emitted as FDR records.
- Composition-root wiring (entry to the AZ-331 `build_vio_strategy` factory's `klt_ransac` branch).
- KLT/RANSAC is the only strategy that builds for ALL of airborne / research / replay-cli; module-layout's Build-Time Exclusion Map shows `BUILD_KLT_RANSAC=ON` for those three binaries (operator-tooling does not need VIO).
- The KLT path MUST be camera-agnostic — no `adti20` / `adti26` specific branches; the calibration arrives via the per-call `CameraCalibration` argument.

### Excluded

- OKVIS2 strategy — separate task.
- VINS-Mono strategy — separate task.
- Warm-start hint persistence — separate task in this epic.
- C5 fusion of `VioOutput` — owned by E-C5.
- C13 FDR writer-thread — owned by E-C13.
- IMU preintegration — owned by AZ-276.
- The C1-IT-01..06 / C1-PT-01 tests themselves — deferred to Step 9 / E-BBT (KLT/RANSAC's AC-2.1a + AC-2.2 bindings will live there).
- Non-OpenCV optical-flow algorithms (Farnebäck dense flow, etc.) — out of scope; KLT pyramidal is the canonical simple baseline.
- Bundle-adjustment refinement of the recovered pose — out of scope this cycle; the engine rule's bound is per-frame relative pose, not refined keyframe pose.

## Acceptance Criteria

**AC-1: `current_strategy_label()` returns `"klt_ransac"`**
Given a `KltRansacStrategy` constructed via the AZ-331 factory with `config.vio.strategy = "klt_ransac"`
When `current_strategy_label()` is called
Then the returned string is exactly `"klt_ransac"`

**AC-2: First frame emits `VioOutput` with `state == INIT` and zero relative pose**
Given a freshly-constructed strategy and the very first `NavCameraFrame`
When `process_frame(frame, imu, calibration)` is called
Then a `VioOutput` is returned with `relative_pose_T` equal to the SE(3) identity (within numerical tolerance) and `pose_covariance_6x6` equal to the configured INIT-state conservative covariance; `health_snapshot().state == INIT`

**AC-3: Steady-state frame emits `VioOutput` with non-zero relative pose and SPD covariance**
Given a strategy with prior frames processed and a current frame with sufficient inliers
When `process_frame` is called
Then `relative_pose_T` is non-identity (the camera moved between frames in the fixture); `pose_covariance_6x6` is symmetric and positive-definite; `feature_quality.mre_px > 0`; `feature_quality.tracked > 0`

**AC-4: Pose recovery rewraps `cv2.error` into `VioError`**
Given a frame that triggers `cv2.findEssentialMat` or `cv2.recoverPose` to raise `cv2.error`
When `process_frame` is called
Then `VioFatalError` is raised; the original `cv2.error` is chained via `raise ... from`; no raw `cv2.error` leaks to the caller

**AC-5: `reset_to_warm_start` clears feature buffer and re-seeds bias**
Given a strategy with N processed frames and a non-default IMU bias
When `reset_to_warm_start(hint)` is called with a known `hint.bias`
Then the next `process_frame` call's first behaviour is `cv2.goodFeaturesToTrack` (verifiable via spy on the OpenCV call); `VioOutput.imu_bias` reflects `hint.bias` (within numerical tolerance); calling `reset_to_warm_start` again does not raise

**AC-6: Inlier loss → `DEGRADED` state with monotonically growing covariance**
Given a strategy in TRACKING state
When a frame is processed where the surviving inlier count is below `config.vio.klt_ransac.min_features_for_pose`
Then `VioOutput.pose_covariance_6x6` Frobenius norm is strictly greater than the prior frame's; `health_snapshot().state == DEGRADED`; `VioOutput` IS emitted (not raised)

**AC-7: Sustained pose-recovery failure raises `VioFatalError`**
Given a strategy in DEGRADED state
When `config.vio.lost_frame_threshold` consecutive frames fail pose recovery (e.g., RANSAC finds no consensus)
Then the next `process_frame` call raises `VioFatalError`; `health_snapshot().state == LOST`

**AC-8: `BUILD_KLT_RANSAC=OFF` does not import the strategy module**
Given the operator-tooling binary built with `BUILD_KLT_RANSAC=OFF`
When `gps_denied_onboard.components.c1_vio` is imported
Then `sys.modules` does NOT contain `gps_denied_onboard.components.c1_vio.klt_ransac`; AZ-331's factory raises `StrategyNotAvailableError("klt_ransac", missing_flag="BUILD_KLT_RANSAC")` if `klt_ransac` is requested

**AC-9: Honest covariance — no shrinkage during DEGRADED**
Given a controlled-degradation 60 s synthetic input
When `process_frame` runs through the degradation event
Then `||pose_covariance_6x6||_F` is monotonically non-decreasing from the moment `health_snapshot().state` first transitions to `DEGRADED` until `TRACKING` is restored or `LOST` is reached; the covariance estimator does NOT apply any client-side floor or smoother

**AC-10: FDR `vio.health` records emitted on every state transition**
Given the strategy is configured with a real `FdrClient` (or test double)
When `health_snapshot().state` transitions
Then exactly one FDR record with `kind="vio.health"` and the new state is emitted; no records on steady-state frames

**AC-11: Camera-agnostic path**
Given two `CameraCalibration` instances representing different deployed cameras (test fixture `adti26` and a synthetic alternate calibration)
When the same `process_frame` code path is exercised against both calibrations
Then the strategy produces sensible `VioOutput` for both without any calibration-specific branch in the source code (verifiable via static-grep CI gate: no `adti20` / `adti26` literals in `klt_ransac.py`)

## Non-Functional Requirements

**Performance**
- `process_frame` p95 ≤ 80 ms on Tier-2 (budget shared with OKVIS2 — KLT/RANSAC is typically faster but the budget is the wire boundary). Failure threshold 120 ms.
- Throughput ≥ 3 Hz sustained; failure threshold < 2.5 Hz.
- CPU ≤ 30 % of one core (OpenCV's `cv2.calcOpticalFlowPyrLK` is multi-threaded internally; bound at 30 % per ADR-002 budget partition).
- Memory ≤ 1.5 GB resident.
- AC-2.1a: ≥ 95 % tracked-frame ratio on Derkachi normal segment (C1-IT-03; deferred to Step 9 / E-BBT for the actual test, but this strategy MUST be capable of meeting it on the named fixture).
- AC-2.2: MRE p95 < 1 px frame-to-frame (C1-IT-04; this strategy IS bound by it per `tests.md`).

**Compatibility**
- OpenCV ≥ 4.12.0 (CVE-2025-53644 mitigation per architecture § 2 dependency table).
- No additional third-party dependencies — OpenCV + numpy only (numpy already pinned).

**Reliability**
- Error envelope closed at the `VioError` family; no raw OpenCV / numpy exceptions cross the API surface.
- Single-threaded by Protocol contract; one instance per camera ingest thread.
- Pure-Python — no native-lib install requirement; works on Tier-0 workstation with `pip install opencv-python` only.

**Concurrency**
- One `KltRansacStrategy` instance per camera ingest thread.

## Unit Tests

| AC Ref | What to Test | Required Outcome |
|--------|-------------|-----------------|
| AC-1 | `current_strategy_label()` after factory build with `klt_ransac` config | Returns `"klt_ransac"` |
| AC-2 | First-frame `process_frame` on a fixture | `VioOutput` returned; `relative_pose_T` ≈ identity; `state == INIT` |
| AC-3 | Process N frames; inspect `VioOutput` shape | `relative_pose_T` non-identity; `pose_covariance_6x6` SPD; `feature_quality.mre_px > 0` |
| AC-4 | Inject a frame that triggers `cv2.error` (mock OpenCV call) | `VioFatalError` raised; `__cause__` is the `cv2.error` |
| AC-5 | `reset_to_warm_start` then `process_frame` | First call to OpenCV is `goodFeaturesToTrack`; `imu_bias` reflects hint |
| AC-6 | Feed degraded fixture (low inlier count) | Covariance Frobenius norm strictly increases; `state == DEGRADED`; `VioOutput` IS emitted |
| AC-7 | `lost_frame_threshold` consecutive failed-pose frames | `VioFatalError` on next `process_frame`; `state == LOST` |
| AC-8 | `BUILD_KLT_RANSAC=OFF` import + factory call | Module not in `sys.modules`; factory raises `StrategyNotAvailableError` |
| AC-9 | 60 s controlled-degradation synthetic | Covariance monotonically non-decreasing during DEGRADED |
| AC-10 | Real / fake `FdrClient` spy through state transitions | Exactly one `vio.health` record per transition |
| AC-11 | Static-grep gate + run with two calibrations | No `adti20` / `adti26` literals in source; both calibrations produce sensible output |
| NFR-perf | C1-PT-01 microbench against Derkachi normal segment (Tier-2) | p95 ≤ 80 ms; throughput ≥ 3 Hz |
| NFR-reliability-error-envelope | Raise `cv2.error` from each OpenCV call point | All caught and rewrapped to `VioError` family |

## Constraints

- This task implements (does NOT define) the AZ-331 Protocol.
- KLT/RANSAC is pure Python — NO `_native/` binding under this strategy.
- The strategy MUST consume IMU via the AZ-276 `ImuPreintegrator` for bias propagation, even though KLT itself is vision-only (keeps `VioOutput.imu_bias` consistent across all three strategies).
- The strategy MUST consume RANSAC via the AZ-282 `RansacFilter` for the inlier-rejection step (cross-cutting helper; do not duplicate locally).
- OpenCV ≥ 4.12.0 is the only third-party dependency added by this task (already pinned at the project level).
- No covariance floor / smoother on the read path — the residual-scatter covariance estimator is the canonical formula; document its limitations in the Risks section.
- Per-frame DEBUG defaults OFF.
- Camera-agnostic — no calibration-specific branches in source. CI grep gate enforces.
- The `KltRansacConfig` schema extension to AZ-269 is owned by this task.

## Risks & Mitigation

**Risk 1: Residual-scatter covariance under-reports during high-overlap straight flight**
- *Risk*: The standard residual-scatter formula assumes residual noise is uncorrelated with pose perturbation; in long straight-flight segments the assumption holds, but in low-parallax scenarios the formula can under-report covariance — not a "honest-covariance violation" in the AC-9 sense (that test catches monotonicity), but a quantitative under-report C5 fusion will over-trust.
- *Mitigation*: D-CROSS-LATENCY-1 + AC-NEW-4 statistical headroom carry the residual risk; the C1-IT-12 comparative-study report (Step 9 / E-BBT) cross-validates KLT's covariance against OKVIS2's tightly-coupled output. The strategy spec documents the limitation; the deployed binary uses OKVIS2 by default and KLT only as a fallback / engine-rule baseline.

**Risk 2: KLT loses track on the first frame after take-off (no prior frame to track from)**
- *Risk*: AC-2 covers the INIT-state behaviour, but a misconfigured deployment that calls `process_frame` once and then crashes would leave C5 with no `VioOutput`; the AC-5.2 fallback is the right path but the diagnostic is harder.
- *Mitigation*: Per-frame DEBUG log (when enabled) records the INIT-state transition; the FDR `vio.health` record at INIT → TRACKING is emitted (AC-10) regardless of DEBUG state, so post-flight inspection always shows the warm-up.

**Risk 3: `cv2.findEssentialMat` is sensitive to RANSAC inlier-threshold tuning**
- *Risk*: The default OpenCV RANSAC threshold is in pixel units of normalised image coordinates; a misconfiguration makes the strategy either reject every correspondence or accept every outlier.
- *Mitigation*: `config.vio.klt_ransac.essential_matrix_ransac_threshold` is documented + tested with a sensitivity sweep in the deferred Step 9 test. AZ-282 (`RansacFilter`) provides a generic RANSAC entry point that this strategy uses for the AZ-282-managed correspondence-rejection step (a separate stage from `cv2.findEssentialMat`'s internal RANSAC).

**Risk 4: Sharp turns < 5 % frame overlap (RESTRICT-UAV-3) cause feature-track loss**
- *Risk*: The architecture's RESTRICT-UAV-3 calls out this constraint; KLT/RANSAC will lose tracks faster than OKVIS2 in this regime.
- *Mitigation*: The strategy reports `DEGRADED` (AC-6) immediately when inlier count drops; F6 satellite re-localisation (E-C2 / E-C3 / E-C4 path) is the recovery; no work for this strategy beyond honest reporting.

## Runtime Completeness

- **Named capability**: KLT pyramidal optical-flow + RANSAC essential-matrix simple-baseline VIO; the ADR-002 engine-rule mandatory baseline (architecture / E-C1 / `solution.md` "KltRansac mandatory simple-baseline").
- **Production code that must exist**: real `KltRansacStrategy` class implementing the AZ-331 Protocol; real OpenCV ≥ 4.12.0 calls (`cv2.calcOpticalFlowPyrLK`, `cv2.goodFeaturesToTrack`, `cv2.findEssentialMat`, `cv2.recoverPose`); real residual-scatter covariance from the inlier residuals; real bias propagation through AZ-276; real RANSAC inlier rejection through AZ-282.
- **Allowed external stubs**: tests MAY mock `cv2.error` raises at specific call points (AC-4); production wiring uses real OpenCV.
- **Unacceptable substitutes**: a deterministic-fallback `VioOutput` that bypasses OpenCV (would defeat AC-2.1a's tracked-frame ratio); a covariance floor (would break AC-9); skipping the AZ-276 `ImuPreintegrator` (would break the `VioOutput.imu_bias` consistency invariant across strategies); duplicating RANSAC logic instead of reusing AZ-282 (cross-cutting violation per `coderule.mdc` and decompose Step 2 § 9).
