[autodev] Step 13 partial: c1/c2/c2_5/c3 cycle-1 doc sync

Item 2 (C1) + item 3 batch 1 of ~5 (C2 VPR, C2.5 Rerank, C3 Matcher)
of the cycle-1 component-description reconciliation called out in
ripple_log_cycle1.md.

For each touched description.md:
- Add a "Cycle-1 operational reality" paragraph in section 1 that
  names the _STRATEGY_REGISTRY + register_airborne_strategies()
  runtime gate (AZ-591), the pre_constructed dict path through
  compose_root (AZ-618 umbrella), the per-component
  AIRBORNE_REQUIRED_PRE_CONSTRUCTED_KEYS row, and any cycle-1
  strategy-default vs documented-primary disambiguation
  (net_vlad as the C2 default; xfeat parked from the C3 airborne
  registry).
- Relax the OpenCV row in section 5 Key Dependencies to the
  D-CROSS-CVE-1 cycle-1 pin (>=4.11.0.86,<4.12) wherever the
  component imports cv2 (C2 preprocessors, C2.5 ORB placeholder,
  C3 RANSAC + reprojection).
- Add a "Cycle-1 Tier-2 follow-up dependencies" subsection in
  section 7 only for components with a strategy module that is
  built but parked from the airborne registry (C3 xfeat).

Refresh ripple_log_cycle1.md follow-up ordering with per-batch
progress + extracted batch pattern so the next batch session has
a self-contained recipe. Bump _autodev_state.md sub_step.detail
to reflect batch 1 completion (10 components + 8 helpers + tests/
remain).

Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
Oleksandr Bezdieniezhnykh
2026-05-19 16:49:41 +03:00
parent 4fd88655a4
commit c1f27e4681
6 changed files with 28 additions and 8 deletions
@@ -4,7 +4,9 @@
**Purpose**: produce a per-frame relative pose SE(3) + 6×6 covariance + IMU bias estimate + feature-quality summary from the nav-camera frame and the FC IMU/attitude window, fusing visual and inertial cues without any external (satellite) reference.
**Architectural Pattern**: Strategy — `VioStrategy` interface with three concrete implementations (Okvis2 production-default, VinsMono research-only, KltRansac mandatory simple-baseline), constructor-injected at the composition root (ADR-009), build-time gated by per-implementation CMake `BUILD_*` flags (ADR-002), runtime selection by config at startup (ADR-001), not hot-swappable mid-flight.
**Architectural Pattern**: Strategy — `VioStrategy` interface with three concrete implementations (Okvis2 nominal production-default, VinsMono research-only, KltRansac mandatory simple-baseline), constructor-injected at the composition root (ADR-009), build-time gated by per-implementation CMake `BUILD_*` flags (ADR-002), runtime selection by config at startup (ADR-001), not hot-swappable mid-flight.
**Cycle-1 operational reality**: the airborne binary ships with **`KltRansac` as the production-default selection** while the OKVIS2 + VINS-Mono native wirings are parked as Tier-2 follow-ups (`AZ-592` for AZ-332 OKVIS2; `AZ-593` for AZ-333 VINS-Mono — see `FINAL_report.md` § Cycle 1 Implementation Status). Both higher-fidelity strategies have their Python facade + pybind11 binding skeleton + `_STRATEGY_REGISTRY` registration in place; the first `process_frame` call into the OKVIS2/VINS-Mono native side raises until the upstream wiring (`okvis::ThreadedSlam` / VINS-Mono ROS-strip) lands. ADR-001 / ADR-002 remain correct — the seam exists, the build-flag gating works — only the operational default-selection shifts. Runtime selection of `okvis2` or `vins_mono` via config currently raises `StrategyNotAvailableError` from `runtime_root/vio_factory.py` until their `BUILD_*` flag is ON.
**Upstream dependencies**:
- Camera ingest thread → `NavCameraFrame` (3 Hz nominal, drop-oldest queue).
@@ -85,7 +87,7 @@ No database access, no cache layer beyond the in-process keyframe window.
|---------|---------|---------|
| OKVIS2 (C++) | upstream HEAD pinned per Plan-phase | Production-default tightly-coupled VIO; BSD-3-Clause |
| VINS-Mono (C++) | upstream HEAD pinned per Plan-phase | Research-only loosely-coupled VIO for IT-12 comparative study; behind `BUILD_VINS_MONO` |
| OpenCV | 4.12.0 (CVE-2025-53644 mitigation) | KLT pyramidal optical flow + RANSAC for the simple-baseline strategy |
| OpenCV | `>=4.11.0.86,<4.12` (cycle-1 relaxed pin; D-CROSS-CVE-1 deferred — see `_docs/_process_leftovers/2026-05-11_d_cross_cve_1_opencv_pin_deferred.md`) | KLT pyramidal optical flow + RANSAC for the KltRansac strategy (cycle-1 production-default) |
| Eigen | matches OKVIS2 / GTSAM pin | Lie-algebra math for SE(3) + 6×6 covariance |
| pybind11 | matches OKVIS2 / VINS-Mono build | Python bindings for the C++ strategies |
@@ -112,7 +114,11 @@ No database access, no cache layer beyond the in-process keyframe window.
- The camera ingest thread is the sole producer; C5 is the sole consumer. Concurrent calls to `process_frame` on a single strategy instance are forbidden — enforce in the composition root by binding one strategy instance to the camera ingest thread.
**Performance bottlenecks**:
- Okvis2 sliding-window optimisation can spike to 80120 ms on a thermally-throttled Jetson; D-CROSS-LATENCY-1 hybrid auto-degrades C4 covariance recovery (not C1) to free budget.
- Okvis2 sliding-window optimisation can spike to 80120 ms on a thermally-throttled Jetson; D-CROSS-LATENCY-1 hybrid auto-degrades C4 covariance recovery (not C1) to free budget. (Behaviour is documented for when AZ-592 wires the OKVIS2 native side; in cycle-1, KltRansac is the active backend and its per-frame cost is `O(F)` only.)
**Cycle-1 Tier-2 follow-up dependencies**:
- AZ-592 (parked from AZ-332): wires `okvis::ThreadedSlam` into `_native/okvis2_binding.cpp` and lands the OKVIS2 CI matrix (Ceres + vendored submodules) + Tier-2 Jetson validation against Derkachi-class fixtures. Until this lands, requesting `config.vio.strategy="okvis2"` raises `StrategyNotAvailableError` regardless of `BUILD_OKVIS2`.
- AZ-593 (parked from AZ-333): finalises the de-ROSified VINS-Mono upstream pin (HKUST + in-tree ROS-strip vs. community fork) and wires the `vins_estimator::Estimator` into `_native/vins_mono_binding.cpp`. Until this lands, requesting `config.vio.strategy="vins_mono"` raises `StrategyNotAvailableError` regardless of `BUILD_VINS_MONO`.
## 8. Dependency Graph