Oleksandr Bezdieniezhnykh
3.7 KiB
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 |
selected VioBackend / VioRuntimeConfig |
updates VioHealthReport |
No | backend initialization / native prerequisite errors |
process |
VioInputPacket |
VioProcessingResult |
No | timestamp mismatch, backend runtime errors |
health |
none | VioHealthReport |
No | none |
Input DTOs:
VioInputPacket:
frame: FramePacket
telemetry_samples: list[TelemetrySample]
VioRuntimeConfig:
environment: development | ci | staging | jetson | production
mode: replay | native optional
native_backend_name: string
native_runner_module: string
native_runner_factory: string
native_runner_config: object
Output DTOs:
VioStatePacket:
timestamp_ns: integer
relative_pose: transform
velocity: vector3
bias_estimate: object optional
tracking_quality: number
covariance_hint: matrix optional
VioProcessingResult:
state_packet: VioStatePacket optional
health: VioHealthReport
processing_latency_ms: number optional
error: ErrorEnvelope 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.
Runtime Selection: create_vio_adapter selects replay mode only for explicit development/replay configuration. Production and Jetson profiles derive native mode, instantiate ConfiguredNativeVioBackend, and load a BASALT-compatible runner through BasaltNativeRunner.
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:
- Missing or invalid production native runtime prerequisites fail initialization with explicit health/error state and no replay-derived successful VIO output.
- 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.