[AZ-219] [AZ-228] Generalize VIO component layout

Keep VIO package and native bridge paths backend-neutral so BASALT remains an implementation choice rather than a component boundary. Co-authored-by: Cursor <cursoragent@cursor.com>
2026-06-21 08:21:13 +00:00 · 2026-05-03 12:20:41 +03:00
parent 79997e39ac
commit 72a9df6b57
34 changed files with 123 additions and 114 deletions
@@ -8,7 +8,7 @@

 **Upstream dependencies**: Navigation camera, camera calibration files.

-**Downstream consumers**: BASALT VIO adapter, Satellite Service, anchor verification, Tile Manager, FDR.
+**Downstream consumers**: VIO adapter, Satellite Service, anchor verification, Tile Manager, FDR.

 ## 2. Internal Interfaces

@@ -100,7 +100,7 @@ ImageQualityReport:

 **Can be implemented in parallel with**: Tile Manager, MAVLink/GCS integration.

-**Blocks**: BASALT VIO adapter, anchor verification, generated tile lifecycle.
+**Blocks**: VIO adapter, anchor verification, generated tile lifecycle.

 ## 8. Logging Strategy

@@ -110,7 +110,7 @@
 | Step | Action | Expected Result |
 |------|--------|-----------------|
 | 1 | Feed a calibrated normal frame | Occlusion status is `clear` |
-| 2 | Process quality gate | Frame is emitted to BASALT adapter |
+| 2 | Process quality gate | Frame is emitted to VIO adapter |

 ---

@@ -1,8 +1,8 @@
-# BASALT VIO Adapter
+# VIO Adapter

 ## 1. High-Level Overview

-**Purpose**: Wrap BASALT as a replaceable relative VIO component that consumes calibrated frames and FC IMU data, then emits relative pose/velocity/bias state and tracking quality.
+**Purpose**: Wrap the selected relative VIO backend as a replaceable component that consumes calibrated frames and FC IMU data, then emits relative pose/velocity/bias state and tracking quality.

 **Architectural Pattern**: Adapter / anti-corruption layer.

@@ -48,14 +48,14 @@ No persistent production data ownership. Reads calibration/config at startup and

 ## 4. Implementation Details

-**State Management**: Owns BASALT runtime state and resets only through explicit wrapper command.
+**State Management**: Owns selected VIO backend runtime state and resets only through explicit wrapper command.

 **Key Dependencies**:

 | Library | Purpose |
 |---------|---------|
-| BASALT | Relative visual-inertial odometry |
-| Eigen/Sophus or BASALT native math stack | Pose and transform representation |
+| BASALT | Current selected relative visual-inertial odometry backend |
+| Eigen/Sophus or backend-native math stack | Pose and transform representation |

 **Error Handling Strategy**:
 - Tracking loss is surfaced to the safety/anchor wrapper, not hidden.
@@ -66,7 +66,7 @@ No persistent production data ownership. Reads calibration/config at startup and

 **Known limitations**:
 - BASALT has no special fixed-wing nadir mode; validation must prove fit under low-parallax/planar terrain.
- BASALT covariance/confidence output is not the product authority; wrapper calibration is required.
+- Backend covariance/confidence output is not the product authority; wrapper calibration is required.

 **Performance bottlenecks**:
 - Native VIO runtime and image resolution can exceed Jetson budget if not tuned.
@@ -83,7 +83,7 @@ No persistent production data ownership. Reads calibration/config at startup and

 | Log Level | When | Example |
 |-----------|------|---------|
-| ERROR | BASALT initialization fails | `basalt_init_failed reason=...` |
+| ERROR | VIO backend initialization fails | `vio_init_failed reason=...` |
 | WARN | Tracking quality drops | `vio_tracking_degraded quality=...` |
 | INFO | VIO reset/reinitialized | `vio_reset cause=...` |

@@ -1,4 +1,4 @@
-# Test Specification — BASALT VIO Adapter
+# Test Specification — VIO Adapter

 ## Acceptance Criteria Traceability

@@ -17,7 +17,7 @@

 ### IT-01: Public Dataset VIO Replay

-**Summary**: Verify BASALT adapter produces relative motion for synchronized camera/IMU replay.
+**Summary**: Verify the VIO adapter produces relative motion for synchronized camera/IMU replay.

 **Traces to**: AC-2.1a, AC-2.2

@@ -53,7 +53,7 @@

 **Traces to**: AC-3.1

-**Input data**: Replay segment with synthetic ±20° tilt and up to 350 m apparent outlier.
+**Input data**: Replay segment with synthetic +/-20 degree tilt and up to 350 m apparent outlier.

 **Expected result**: Adapter either tracks with quality metadata or emits `TrackingLost`; it never hides a failure as high-quality VIO.

@@ -67,7 +67,7 @@

 **Traces to**: AC-3.2, AC-3.4

-**Input data**: <5% overlap sequence with heading change <70°.
+**Input data**: <5% overlap sequence with heading change <70 degrees.

 **Expected result**: Adapter emits low tracking quality or `TrackingLost` within the loss window, allowing relocalization trigger.

@@ -75,7 +75,7 @@

 ## Performance Tests

-### PT-01: BASALT Adapter Runtime Budget
+### PT-01: VIO Adapter Runtime Budget

 **Summary**: Verify VIO processing does not consume the full <400 ms system p95 budget.

@@ -6,7 +6,7 @@

 **Architectural Pattern**: Stateful coordinator / safety facade.

-**Upstream dependencies**: BASALT VIO adapter, anchor verification, MAVLink telemetry, camera quality reports.
+**Upstream dependencies**: VIO adapter, anchor verification, MAVLink telemetry, camera quality reports.

 **Downstream consumers**: MAVLink/GCS integration, FDR, Tile Manager, separate e2e test suite.

@@ -76,7 +76,7 @@ AnchorDecision:

 **Must be implemented after**: Satellite Service candidate DTOs, Tile Manager tile access.

-**Can be implemented in parallel with**: BASALT VIO adapter.
+**Can be implemented in parallel with**: VIO adapter.

 **Blocks**: accepted satellite-anchor path.

@@ -8,7 +8,7 @@

 **Upstream dependencies**: ArduPilot Plane FC, safety/anchor wrapper.

-**Downstream consumers**: BASALT VIO adapter, safety/anchor wrapper, QGC, FDR.
+**Downstream consumers**: VIO adapter, safety/anchor wrapper, QGC, FDR.

 ## 2. Internal Interfaces