gps-denied-onboard/_docs/02_tasks/backlog/AZ-592_AZ-332_tier2_validation.md

AZ-592 — AZ-332 Tier-2 validation: OKVIS2 ThreadedSlam wiring + CI build env + Jetson

Task: AZ-592_AZ-332_tier2_validation Name: AZ-332 Tier-2 validation bundle (OKVIS2) Description: Replace the AZ-332 _native/okvis2_binding.cpp skeleton with real okvis::ThreadedSlam wiring; add the Linux CI apt-install block + flip BUILD_OKVIS2=OFF to ON; package the DBoW2 vocabulary artifact; validate honest 6×6 covariance on real Jetson hardware against Derkachi-class fixtures. Complexity: 5 points (placeholder; likely 8+ once Tier-2 work actually starts — re-size when scheduled) Dependencies: AZ-332, AZ-276 (ImuPreintegrator), AZ-277 (SE3Utils), AZ-591 (compose_root per-binary bootstrap — must land first so the registered c1_vio:okvis2 slot is reachable) Component: c1_vio (epic AZ-254 / E-C1) Tracker: AZ-592 Epic: AZ-254 (E-C1) Status: parked in backlog/ — BLOCKED on Tier-2 prerequisites (see below)

Problem

AZ-332 shipped the Okvis2Strategy Python facade + Okvis2Backend skeleton C++ binding (which throws OkvisFatalException on first frame) and explicitly deferred the real estimator wiring to a Tier-2 follow-up. AZ-332's Implementation Notes line 82 named this follow-up AZ-332_tier2_validation and stated the gate would create it at cycle end.

The cycle-1 gate initially mis-classified AZ-332 as FAIL and created AZ-589_remediate_okvis2_threadedkfvio_wiring against the wrong OKVIS v1 API (ThreadedKFVio doesn't exist in OKVIS2). That ticket has been closed Won't Fix. This task replaces it with the correct scope and API.

Outcome

1. API-correct C++ binding rewrite: rewrite _native/okvis2_binding.cpp against the actual OKVIS2 upstream API:

   • Headers: okvis/ThreadedSlam.hpp, okvis/ViParametersReader.hpp, okvis/Parameters.hpp, okvis/ViInterface.hpp.
   • Construct okvis::ThreadedSlam(parameters, dBowDir) after reading yaml_config_ via okvis::ViParametersReader(yaml).getParameters(parameters).
   • Subscribe to setOptimisedGraphCallback(...) with a lambda whose signature is void(const State&, const TrackingState&, std::shared_ptr<const AlignedMap<StateId, State>>, std::shared_ptr<const okvis::MapPointVector>). Fill latest_output_ under output_mtx_ from State::T_WS, v_W, b_g, b_a, omega_S, timestamp, isKeyframe; derive tracked_features + mean_parallax from TrackingState.
   • Convert numpy uint8 frames to cv::Mat (re-using the existing py::array_t<uint8_t, c_style|forcecast> no-copy buffer view) and call addImages(okvis_time, {0: cv_mat}).
   • Forward IMU via addImuMeasurement(okvis_time, Eigen::Vector3d(alpha), Eigen::Vector3d(omega)).
   • Map okvis::TrackingQuality (Good/Marginal/Lost) onto the binding's HealthState enum.
   • Reset: re-construct ThreadedSlam from the same parameters and re-subscribe the callback (OKVIS2 has no in-place reset).

2. 6×6 covariance extraction: ViInterface does not expose the marginalisation block directly. Two options:

   • (a) Add a tiny upstream patch to ThreadedSlam exposing ViSlamBackend::computeCovariance(StateId); document the patch under cpp/okvis2/patches/.
   • (b) Best-effort proxy: emit a fixed-rank diagonal scaled by feature count / tracking-quality until the upstream patch lands. Mark the AC-1.4 covariance honesty test as xfail(strict=True) until option (a) is in.

3. CMake glue: extend cpp/okvis2/CMakeLists.txt to link OpenCV (cv::Mat is used in the binding). Verify Eigen pin alignment with GTSAM + VINS-Mono (AZ-593).

4. CI workflow: in .github/workflows/ci.yml, add apt install -y libceres-dev libbrisk-dev libdbow2-dev libsuitesparse-dev libgflags-dev libgoogle-glog-dev libopencv-dev libboost-filesystem-dev libatlas-base-dev libeigen3-dev to the Linux runner setup step. Flip -DBUILD_OKVIS2=OFF to -DBUILD_OKVIS2=ON for the airborne + research matrix kinds.

5. DBoW2 vocab artifact: package small_voc.yml.gz next to the .so install location. Two options:

   • (a) Vendor inside the repo (small file, ~3MB — but ROS users typically download separately).
   • (b) Fetch at CI time via a pinned URL from a OKVIS2 release artifact mirror; user decides at scheduling time.

6. Tier-1 integration test: tests/integration/c1_vio/test_az332_okvis2_real_binding.py with @pytest.mark.skipif(not _okvis2_binding_present()). Sanity-check that the binding loads and processes a 60-frame EuRoC-class fixture without throwing; does NOT validate accuracy (Tier-2).

7. Tier-2 Jetson validation (AC-9 of original AZ-332): run honest 6×6 covariance validation against Derkachi-class fixtures on real Jetson Orin. p95 ≤ 80 ms; p50 ≤ 25 ms per the original NFR-perf budget. Owned by AZ-444 (Tier-2 Jetson harness).

Prerequisites BLOCKED on

• AZ-591 landed first: compose_root per-binary bootstrap so c1_vio:okvis2 is registered + reachable.
• Linux CI runner image with apt deps: GitHub Actions ubuntu-latest has most deps but not libbrisk-dev / libdbow2-dev; may require a custom runner image or apt install of dependencies plus a self-built brisk/dbow2.
• Jetson hardware: for AC-9 honest-covariance validation against Derkachi-class fixtures.
• DBoW2 vocab decision: vendor in-repo (option 5a) vs. fetch at CI time (option 5b).
• Eigen pin alignment: confirm GTSAM + OKVIS2 use compatible Eigen versions; vendor Eigen under cpp/_third_party/eigen/ if not.

Scope notes

• This task as written exceeds the user's 5pt PBI complexity rule. It is filed as a placeholder. When Tier-2 work actually starts, split into:
  • AZ-592a — C++ binding rewrite + CMake (3pt; assumes CI dep install handled externally)
  • AZ-592b — Linux CI dep install + DBoW2 vocab artifact (2pt)
  • AZ-592c — Jetson hardware validation against Derkachi-class fixtures (5pt; runs IT-12 fixtures with covariance honesty assertions)
  • Plus the upstream-patch decision (cpp/okvis2/patches/expose_covariance.patch) as its own ADR addendum if needed.

Notes

• Coordinate with AZ-593 (VINS-Mono Tier-2 sibling) on shared Eigen / Ceres pin work.
• Upstream OKVIS2 README documents the apt deps explicitly; copy that list verbatim into the CI workflow comment.
• The skeleton binding's OkvisFatalException("OKVIS2 estimator not yet wired — this binding is the AZ-332 skeleton") is the deliberate fail-loud surface. Replace it with the real ThreadedSlam calls; do NOT keep a fallback "estimator_built_ = false" branch.
• The Implementation Notes (2026-05-12, batch 23) block in _docs/02_tasks/done/AZ-332_c1_okvis2_strategy.md documents the original deferral rationale. Keep it intact for audit; this task discharges that contract.