[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-22 10:51:13 +00:00 · 2026-05-03 12:20:41 +03:00
parent 79997e39ac
commit 72a9df6b57
34 changed files with 123 additions and 114 deletions
@@ -0,0 +1,92 @@
+# VIO Adapter
+
+## 1. High-Level Overview
+
+**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.
+
+**Upstream dependencies**: Camera ingest/calibration, MAVLink telemetry stream.
+
+**Downstream consumers**: Safety/anchor wrapper, FDR, separate e2e test suite.
+
+## 2. Internal Interfaces
+
+### Interface: `VioAdapter`
+
+| Method | Input | Output | Async | Error Types |
+|--------|-------|--------|-------|-------------|
+| `initialize` | `VioInitRequest` | `VioInitResult` | No | `CalibrationInvalid`, `DatasetUnsupported` |
+| `process` | `VioInputPacket` | `VioStatePacket` | Yes | `TrackingLost`, `TimestampMismatch` |
+| `health` | none | `VioHealth` | No | none |
+
+**Input DTOs**:
+
+```yaml
+VioInputPacket:
+  frame: FramePacket
+  imu_samples: list[TelemetrySample]
+  attitude_sample: TelemetrySample optional
+```
+
+**Output DTOs**:
+
+```yaml
+VioStatePacket:
+  timestamp_ns: integer
+  relative_pose: transform
+  velocity: vector3
+  bias_estimate: object optional
+  tracking_quality: number
+  completed: boolean
+  covariance_hint: matrix optional
+```
+
+## 3. Data Access Patterns
+
+No persistent production data ownership. Reads calibration/config at startup and emits state to downstream consumers.
+
+## 4. Implementation Details
+
+**State Management**: Owns selected VIO backend runtime state and resets only through explicit wrapper command.
+
+**Key Dependencies**:
+
+| Library | Purpose |
+|---------|---------|
+| 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.
+- Timestamp/camera-IMU sync violations fail the packet and are logged.
+- The adapter never emits WGS84 coordinates; absolute semantics belong to the wrapper.
+
+## 5. Caveats & Edge Cases
+
+**Known limitations**:
+- BASALT has no special fixed-wing nadir mode; validation must prove fit under low-parallax/planar terrain.
+- 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.
+
+## 6. Dependency Graph
+
+**Must be implemented after**: Camera ingest/calibration, MAVLink telemetry DTO definitions.
+
+**Can be implemented in parallel with**: Satellite Service, Tile Manager.
+
+**Blocks**: Safety/anchor wrapper final integration.
+
+## 7. Logging Strategy
+
+| Log Level | When | Example |
+|-----------|------|---------|
+| ERROR | VIO backend initialization fails | `vio_init_failed reason=...` |
+| WARN | Tracking quality drops | `vio_tracking_degraded quality=...` |
+| INFO | VIO reset/reinitialized | `vio_reset cause=...` |
+
+**Log format**: FDR structured event.
+
+**Log storage**: FDR segment.