gps-denied-onboard/_docs/02_tasks/backlog/AZ-593_AZ-333_tier2_validation.md

AZ-593 — AZ-333 Tier-2 validation: de-ROSified VINS-Mono upstream + binding + CI + Jetson

Task: AZ-593_AZ-333_tier2_validation Name: AZ-333 Tier-2 validation bundle (VINS-Mono) Description: Vendor upstream VINS-Mono (with ROS-strip layer), rewrite _native/vins_mono_binding.cpp against the real Estimator + FeatureTracker API, add the Linux CI apt-install block for the research matrix kind, validate against IT-12 comparative-study fixtures on Jetson hardware. Complexity: 5 points (placeholder; likely 8+ if HKUST + ROS-strip path is chosen — re-size when scheduled) Dependencies: AZ-333, AZ-276 (ImuPreintegrator), AZ-277 (SE3Utils), AZ-591 (compose_root per-binary bootstrap), AZ-592 (OKVIS2 Tier-2 — shares CMake / Eigen pin work) Component: c1_vio (epic AZ-254 / E-C1) Tracker: AZ-593 Epic: AZ-254 (E-C1) Status: parked in backlog/ — BLOCKED on Tier-2 prerequisites (see below)

Problem

AZ-333 shipped the VinsMonoStrategy Python facade + VinsMonoBackend skeleton C++ binding (same defect pattern as AZ-332) and explicitly deferred the real estimator wiring. AZ-333's Implementation Notes named the follow-up AZ-333_tier2_validation.

The cycle-1 gate initially mis-classified AZ-333 as FAIL and created AZ-590_remediate_vins_mono_estimator_wiring. That ticket has been closed Won't Fix; this task replaces it with the correct scope.

Additional blocker unique to AZ-593: cpp/vins_mono/upstream/ is referenced by cpp/vins_mono/CMakeLists.txt but does not exist — .gitmodules has no entry for it. The original AZ-333 task spec assumed a "de-ROSified VINS-Mono pin" exists; the user / team must pick the vendoring path.

Outcome

1. Upstream vendoring decision: choose between

   • (a) Original HKUST HKUST-Aerial-Robotics/VINS-Mono (ROS1-locked). Requires in-tree ROS-strip configure-time hook. More work but no fork drift.
   • (b) A community de-ROSified fork (e.g., Karaca-VINS-Mono or RonaldSun/vins-fusion-no-ros). Less work but accepts external maintenance drift.

   The decision needs to be made BEFORE work starts. Document in _docs/03_implementation/refactoring/vins_mono_upstream_choice.md with the chosen pin commit hash and the rationale.

2. Add submodule: git submodule add <chosen-url> cpp/vins_mono/upstream against the pinned commit.

3. ROS-stub layer (only if option 1a): vendor minimal cpp/_third_party/vins_mono_ros_stub/ providing the symbols VINS-Mono pulls from roscpp / rosbag / std_msgs / sensor_msgs without requiring a real ROS install. Pre-process upstream sources via CMake configure_file to redirect ROS headers to the stubs.

4. C++ binding rewrite: replace _native/vins_mono_binding.cpp skeleton with real Estimator + FeatureTracker wiring. API surface:

   • Construct feature_tracker::FeatureTracker + vins_estimator::Estimator after parsing yaml_config_ via VINS-Mono's readParameters() / equivalent.
   • In add_frame(image): call feature_tracker_.readImage(image_8uc1, ts_seconds), retrieve the resulting feature observations, feed them into estimator_.processImage(image_msg, header) (mirroring the upstream feature_tracker_node.cpp / estimator_node.cpp flows but without ROS message types).
   • In add_imu(ts, accel, gyro): estimator_.processIMU(ts, alpha, omega).
   • Periodically (or per-frame) call estimator_.processMeasurements(...) and estimator_.solveOdometry() to drive the sliding-window optimisation.
   • Extract output: read estimator_.Ps[WINDOW_SIZE] (position), estimator_.Rs[WINDOW_SIZE] (rotation), estimator_.Bas[WINDOW_SIZE] / estimator_.Bgs[WINDOW_SIZE] (biases). Pose covariance from estimator_.last_marginalization_info.
   • Reset: estimator_.clearState() + estimator_.setParameter().

5. CMake glue: extend cpp/vins_mono/CMakeLists.txt to link the upstream + stub libs against pinned Ceres + OpenCV ≥ 4.2 + Eigen ≥ 3.4. Pin alignment: ensure Eigen + Ceres pins match AZ-592 (OKVIS2 Tier-2) to avoid ABI conflict in the research binary which links both.

6. CI workflow: gate BUILD_VINS_MONO=ON on the research / comparative-study CI matrix kind only (NOT the airborne kind — ci/sbom_diff.py enforces). Apt deps overlap heavily with AZ-592 (Ceres, OpenCV, Eigen, SuiteSparse).

7. Tier-1 integration test: tests/integration/c1_vio/test_az333_vins_mono_real_binding.py with @pytest.mark.skipif(not _vins_mono_binding_present()).

8. Tier-2 Jetson validation (comparative-study against AZ-332 OKVIS2): runs IT-12 fixtures, owned by AZ-444 (Tier-2 Jetson harness).

Prerequisites BLOCKED on

• Upstream choice (user decision): HKUST + ROS-strip (option 1a) vs. community de-ROSified fork (option 1b).
• AZ-591 landed first: compose_root per-binary bootstrap so c1_vio:vins_mono is registered + reachable on the research binary.
• AZ-592 landed first or in parallel: shares Linux CI dep install + Eigen / Ceres pin alignment work.
• Linux CI runner image with apt deps: see AZ-592.
• Jetson hardware: for IT-12 comparative-study validation.

Scope notes

• This task as written almost certainly exceeds 5pt. When Tier-2 work actually starts, split into:
  • AZ-593a — Upstream vendoring decision + ADR addendum + submodule add (2pt)
  • AZ-593b — ROS-stub layer (if option 1a) (5pt)
  • AZ-593c — C++ binding rewrite + CMake (5pt)
  • AZ-593d — Jetson IT-12 validation (5pt)
• The HKUST + ROS-strip path is the more conservative engineering choice (no fork drift, full upstream maintenance available), but it's also the larger effort. The fork path may be 1-2 weeks faster but introduces a maintenance dependency on a third-party fork.

Notes

• Coordinate Eigen / Ceres pin work with AZ-592. Both link against Ceres + Eigen; the research binary links both AZ-592 and AZ-593 artifacts, so version mismatch = link-time segfault.
• Upstream VINS-Mono's feature_tracker_node.cpp and estimator_node.cpp are the reference for the binding's I/O flow. Strip the ROS message types and replace with the binding's add_frame / add_imu surface.
• _docs/02_tasks/done/AZ-333_c1_vins_mono_strategy.md documents the original deferral. Keep intact for audit; this task discharges that contract.
• AZ-444 (Tier-2 Jetson harness) is the consumer of this task's binding artifact. AZ-444's IT-12 comparative-study runs require both OKVIS2 (AZ-592) and VINS-Mono (AZ-593) bindings to be working.