gps-denied-onboard/_docs/02_tasks/done/AZ-347_c3_xfeat.md

C3 XFeat Alternate Lightweight Matcher

Task: AZ-347_c3_xfeat Name: C3 XFeat Alternate Lightweight Matcher Description: Implement XFeatMatcher, the lightweight alternate CrossDomainMatcher. XFeat combines feature extraction AND matching in a single forward pass (no separate LightGlue stage); selectable via config.matcher.strategy = "xfeat". Target use case: low-power / thermal-throttled scenarios where DISK+LightGlue's combined cost (~180 ms p95) exceeds the C4 hybrid's degraded budget. Drop-and-continue + below-threshold + best-candidate selection contracts inherited from the Protocol unchanged. RANSAC + median residual still computed via the shared RansacFilter. Complexity: 3 points Dependencies: AZ-344 (Protocol + factory + DTOs + errors + RollingHealthWindow), AZ-263_initial_structure, AZ-269_config_loader, AZ-282_ransac_filter, AZ-298_c7_tensorrt_runtime, AZ-299_c7_onnxrt_fallback, AZ-303_c6_storage_interfaces, AZ-281_engine_filename_schema (XFeat engine self-describing filename), AZ-321_c10_engine_compiler (XFeat engine compile path), AZ-266_log_module, AZ-272_fdr_record_schema Component: c3_matcher (epic AZ-257 / E-C3) Tracker: AZ-347 Epic: AZ-257 (E-C3)

Document Dependencies

• _docs/02_document/contracts/c3_matcher/cross_domain_matcher_protocol.md — Protocol contract.
• _docs/02_document/components/04_c3_matcher/description.md — § 1 XFeat alternate (lightweight); § 5 error handling; § 9 logging.
• _docs/02_document/module-layout.md — BUILD_MATCHER_XFEAT row.
• _docs/02_document/contracts/shared_helpers/ransac_filter.md — RANSAC filtering API.
• _docs/02_document/contracts/c2_5_rerank/rerank_strategy_protocol.md.
• _docs/02_document/contracts/c7_inference/inference_runtime_protocol.md.

Problem

Without this task: there is no lightweight matcher option for thermal-throttled scenarios; if the C4 hybrid switches to Jacobian (per ADR-006 / D-CROSS-LATENCY-1) but C3's per-frame budget still allows the heavy DISK+LightGlue path, the system has no mechanism to reduce C3's cost too. XFeat is also the documented mandatory simple-baseline alternative for IT-12 comparative study (AC-2.1a engine rule applied at the matcher level, with NetVLAD acting at the VPR level).

Outcome

• src/gps_denied_onboard/components/c3_matcher/xfeat.py defining:
  • XFeatMatcher class implementing the CrossDomainMatcher Protocol.
  • Constructor: __init__(self, runtime: InferenceRuntime, ransac_filter: RansacFilter, fdr_client: FdrClient, health_window: RollingHealthWindow, config: MatcherConfig). Note: NO lightglue_runtime argument — XFeat does not use LightGlue.
  • match(frame, rerank_result, calibration):
    1. Decode + preprocess the nav-camera frame ONCE.
    2. For each RerankCandidate in rerank_result.candidates: a. Decode + preprocess the candidate tile. b. Run XFeat forward (single pass: outputs combined correspondences directly — XFeat fuses extraction + matching). c. On failure: drop-and-continue (MatcherBackboneError, phase="xfeat_forward"). d. RANSAC + median residual via ransac_filter.filter(correspondences, threshold_px=...) — same helper as DISK+LightGlue. e. Append CandidateMatchSet if survivors > 0.
    3. Below-threshold / all-failed → InsufficientInliersError (same semantics as AZ-345).
    4. Sort survivors descending by inlier_count; ties broken by per_candidate_residual_px ascending.
    5. WARN on residual above threshold; INFO on ready; FDR matcher.frame_done per frame.
    6. RollingHealthWindow.update after each frame (success or failure).
    7. matcher_label = "xfeat".
  • Module-level create(config, lightglue_runtime, ransac_filter, inference_runtime, health_window) -> CrossDomainMatcher:
    1. lightglue_runtime is accepted in the signature for factory uniformity but NOT stored / used.
    2. xfeat_weights_path = config.matcher.xfeat_weights_path (TRT engine produced by AZ-321).
    3. Load XFeat engine via inference_runtime.load_engine(...).
    4. Construct XFeatMatcher(...).
• Composition-root wiring path for config.matcher.strategy == "xfeat".
• BUILD_MATCHER_XFEAT flag wiring (ON in research; ON in airborne if config selects it; OFF in operator-tooling).
• All logging + FDR records identical structure to AZ-345 with matcher_label = "xfeat".

Scope

Included

• XFeatMatcher implementation per the CrossDomainMatcher Protocol.
• XFeat forward via C7 InferenceRuntime.
• RANSAC + median residual via shared RansacFilter (NO LightGlue).
• Same drop-and-continue + below-threshold + best-candidate selection as AZ-345.
• Same RollingHealthWindow.update invocation pattern.
• Composition-root wiring path.
• XFeat-specific preprocessor inline.
• Unit tests covering Invariants 1–9 + drop-and-continue + below-threshold + deterministic ordering. Parametrised across XFeat-specific test fixtures (lightweight model output is different shape from DISK).
• BUILD_MATCHER_XFEAT flag wiring.

Excluded

• The Protocol + DTOs + errors + factory + RollingHealthWindow — owned by AZ-344.
• RansacFilter (AZ-282).
• LightGlueRuntime (AZ-278) — XFeat does NOT consume this helper; the factory's signature includes it for uniformity but XFeat's create ignores the parameter.
• C7 runtime stack (AZ-297..AZ-300).
• XFeat engine compile (AZ-321).
• Component-internal acceptance tests beyond Protocol + invariants smoke.
• DISK matcher (AZ-345) and ALIKED matcher (AZ-346).

Acceptance Criteria

AC-1 through AC-10: identical contract to AZ-345 AC-1..AC-10 (Protocol conformance, best-candidate selection, drop-and-continue, below-threshold, residual WARN, health update, correspondences shape, determinism). matcher_label = "xfeat".

AC-11: Composition-root wiring Given config.matcher.strategy = "xfeat" AND BUILD_MATCHER_XFEAT = ON When compose_root(config) runs Then an XFeatMatcher instance is wired; ONE INFO log kind="c3.matcher.ready" with {strategy: "xfeat", ...} is emitted. The strategy does NOT hold a reference to LightGlueRuntime (verifiable via not hasattr(strategy, "_lightglue_runtime") OR strategy._lightglue_runtime is None).

AC-12: FDR matcher.frame_done per frame Same shape as AZ-345 AC-12 with matcher_label = "xfeat".

AC-special-1: XFeat single-pass forward — no LightGlue call Given a match(...) call where the LightGlueRuntime test double is provided to the factory When the call completes Then lightglue_runtime.match_* is NEVER invoked (verified by mock assertion lightglue_runtime.match_pair.assert_not_called()).

AC-special-2: XFeat lower latency than DISK+LightGlue (informational, not gated) Given identical hardware and identical inputs When match(...) is microbenchmarked × 100 frames Then XFeat's per-call p95 is < AZ-345's per-call p95 (informational metric; if XFeat is NOT faster, that's a backbone misconfiguration, not a contract violation. Documented in the test report; does NOT block this AC).

Non-Functional Requirements

Performance (deferred to C3-PT-01):

• match p95 ≤ 100 ms (informational target; XFeat is the lightweight option). NOT a hard gate; the hard gate is C3-PT-01's overall envelope.
• GPU memory ≤ 300 MB (XFeat single engine; smaller than DISK+LightGlue).

Compatibility

• XFeat engine file format owned by C10 + C7.

Reliability

• Same as AZ-345.

Unit Tests

AC Ref	What to Test	Required Outcome
AC-1..AC-10	Identical to AZ-345 AC-1..AC-10 with matcher_label = "xfeat"	Same outcomes
AC-11	compose_root(config="xfeat")	Wired; INFO log; no LightGlue dependency
AC-12	FDR frame_done emission	Correct fields; matcher_label = "xfeat"
AC-special-1	LightGlue NOT invoked	lightglue_runtime.match_pair.assert_not_called()
AC-special-2	Latency comparison	(Informational; not gated)

Constraints

• Same constraints as AZ-345 — drop-and-continue mandatory, median residual, constructor injection, helpers constructor-injected, engine load at create time, RollingHealthWindow.update called exactly once per match.
• LightGlueRuntime is NOT consumed — the factory's create signature accepts it for uniformity (so AZ-344's factory can call all three matchers' create with the same args) but XFeatMatcher does NOT store or use it. Test AC-special-1 enforces this.
• XFeat-specific preprocessing parameters are hard-coded (weights-coupled, same rule as DISK and ALIKED).

Risks & Mitigation

Risk 1: XFeat output schema differs from DISK+LightGlue output (correspondences format)

• Mitigation: XFeat outputs correspondences ndarray of shape (M, 4) with columns (px_query, py_query, px_tile, py_tile) — same as the post-LightGlue output of DISK+LightGlue. The shared RansacFilter consumes this format identically. If XFeat's upstream output differs, this task adapts inside the strategy.

Risk 2: XFeat's RANSAC inlier counts may be systematically lower (lighter-weight model produces noisier matches)

• Mitigation: AC-2.1a engine rule applies (XFeat is the simple baseline at the matcher level); the ≥ 80 inlier count floor (AC-1.1) may not hold for XFeat. C3-IT-01 measures this; if XFeat fails AC-1.1 on Derkachi, it remains as the "engine rule" comparison baseline NOT the production-default — same engine-rule semantics as NetVLAD at C2.

Risk 3: Linking three backbones into one binary inflates GPU memory headroom

• Mitigation: per ADR-002 / D-C7-13, only the SELECTED backbone's engine is loaded at create time. Linking does NOT load engines; loading happens lazily in each backbone's create. The factory only invokes ONE create per binary lifetime.

Runtime Completeness

• Named capability: XFeatMatcher — alternate lightweight CrossDomainMatcher (architecture / E-C3 / solution.md / AC-2.1a engine rule at matcher level).
• Production code that must exist: real XFeatMatcher calling real C7 InferenceRuntime with real TRT-compiled XFeat engine; real shared RansacFilter for inlier filtering + median residual; real RollingHealthWindow.update after each frame; real composition-root wiring.
• Allowed external stubs: FakeInferenceRuntime, FakeRansacFilter, FakeFdrClient, FakeLightGlueRuntime (passed but unused).
• Unacceptable substitutes: a Python+NumPy XFeat forward (would not satisfy the lightweight-target latency); using a different RANSAC implementation; storing/calling LightGlueRuntime (would defeat XFeat's single-pass design).