# 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.