azaion/gps-denied-onboard
1
0
Fork 0
mirror of https://github.com/azaion/gps-denied-onboard.git synced 2026-06-22 12:01:13 +00:00
Code Issues Packages Projects Releases Wiki Activity

[AZ-589] [AZ-590] [AZ-591] [AZ-592] [AZ-593] Re-classify cycle1 gate findings

Browse Source 
Cycle 1 Product Implementation Completeness Gate post-mortem.
AZ-589 + AZ-590 were the wrong abstraction:

- AZ-589 targeted `okvis::ThreadedKFVio` (OKVIS v1 API) which does
  not exist in the vendored OKVIS2 upstream; smartroboticslab/okvis2
  exposes `okvis::ThreadedSlam` instead.
- AZ-590 assumed a "de-ROSified VINS-Mono pin" submodule exists;
  `cpp/vins_mono/upstream/` has no `.gitmodules` entry.
- The actual production gap is the empty central
  `_STRATEGY_REGISTRY`: `register_strategy(...)` is never called
  outside test fixtures, so `compose_root()` raises
  `StrategyNotLinkedError` for every component slug with a
  strategy-selecting config field. Affects c1_vio + c2_vpr +
  c2_5_rerank + c3_matcher + c3_5_adhop + c4_pose + c5_state.

Re-classification:

- AZ-589 + AZ-590 closed Won't Fix (Jira); spec files removed
  from todo/ but rows retained in the dependencies table as
  audit-trail.
- AZ-591 created (todo/, 5pt) — cross-cutting compose_root
  per-binary bootstrap that populates `_STRATEGY_REGISTRY` for
  the airborne binary. Scheduled as Batch 66 sole task.
- AZ-592 created (backlog/, 5pt placeholder) — AZ-332 Tier-2
  validation bundle (real `okvis::ThreadedSlam` wiring + Linux CI
  apt-install + DBoW2 vocab + Jetson). BLOCKED on Tier-2
  prerequisites; honors AZ-332's `AZ-332_tier2_validation`
  self-deferral handle.
- AZ-593 created (backlog/, 5pt placeholder) — AZ-333 Tier-2
  validation bundle (de-ROSified VINS-Mono upstream + binding +
  CI + Jetson). BLOCKED on upstream vendoring decision plus
  Tier-2 prerequisites; honors AZ-333's parallel deferral pattern.
- AZ-332 + AZ-333 re-classified in cycle1 gate report from FAIL
  to BLOCKED-on-Tier-2.

Step 7 stays in_progress until AZ-591 lands; after that it can
advance to Step 8 with AZ-592 + AZ-593 parked in backlog/.

Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
Oleksandr Bezdieniezhnykh
2026-05-16 12:45:58 +03:00
parent be5c6d20aa
commit 6d51e06886
8 changed files with 419 additions and 237 deletions
Download Patch File Download Diff File Expand all files Collapse all files
_docs/02_tasks/backlog/AZ-592_AZ-332_tier2_validation.md
+67
View File
@@ -0,0 +1,67 @@
# 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.
_docs/02_tasks/backlog/AZ-593_AZ-333_tier2_validation.md
+71
View File
@@ -0,0 +1,71 @@
# 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.