Oleksandr Bezdieniezhnykh
72a9df6b57
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>
2.9 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 |
VioInitRequest |
VioInitResult |
No | CalibrationInvalid, DatasetUnsupported |
process |
VioInputPacket |
VioStatePacket |
Yes | TrackingLost, TimestampMismatch |
health |
none | VioHealth |
No | none |
Input DTOs:
VioInputPacket:
frame: FramePacket
imu_samples: list[TelemetrySample]
attitude_sample: TelemetrySample optional
Output DTOs:
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.