mirror of
https://github.com/azaion/gps-denied-onboard.git
synced 2026-06-22 07:11:12 +00:00
Revise acceptance criteria and restrictions documentation to clarify recent updates and specifications. Key changes include enhanced definitions for position accuracy, image processing quality, and operational parameters, as well as updates to camera specifications and validation requirements. This revision aims to improve clarity and ensure alignment with project goals.
This commit is contained in:
Oleksandr Bezdieniezhnykh
@@ -0,0 +1,92 @@
|
||||
# BASALT 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.
|
||||
|
||||
**Architectural Pattern**: Adapter / anti-corruption layer.
|
||||
|
||||
**Upstream dependencies**: Camera ingest/calibration, MAVLink telemetry stream.
|
||||
|
||||
**Downstream consumers**: Safety/anchor wrapper, validation harness, FDR.
|
||||
|
||||
## 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 BASALT 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 |
|
||||
|
||||
**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.
|
||||
- BASALT 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 retrieval, cache lifecycle.
|
||||
|
||||
**Blocks**: Safety/anchor wrapper final integration.
|
||||
|
||||
## 7. Logging Strategy
|
||||
|
||||
| Log Level | When | Example |
|
||||
|-----------|------|---------|
|
||||
| ERROR | BASALT initialization fails | `basalt_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.
|
||||
@@ -0,0 +1,140 @@
|
||||
# Test Specification — BASALT VIO Adapter
|
||||
|
||||
## Acceptance Criteria Traceability
|
||||
|
||||
| AC ID | Acceptance Criterion | Test IDs | Coverage |
|
||||
|-------|---------------------|----------|----------|
|
||||
| AC-1.3 | Drift between anchors and anchor-age reporting input | IT-02, AT-01 | Covered |
|
||||
| AC-2.1a | >95% VO registration on normal segments | IT-01, AT-01 | Covered |
|
||||
| AC-2.2 | <1.0 px VO MRE | IT-01 | Covered |
|
||||
| AC-3.1 | Handles 350 m outliers/tilt | IT-03 | Covered |
|
||||
| AC-3.2 | Sharp turns trigger relocalization path | IT-04 | Covered |
|
||||
| AC-3.4 | Loss threshold feeds relocalization/dead reckoning | IT-04 | Covered |
|
||||
| AC-4.1 | Hot-path latency | PT-01 | Covered |
|
||||
| AC-4.2 | Jetson memory budget | PT-01 | Covered |
|
||||
|
||||
## Blackbox Tests
|
||||
|
||||
### IT-01: Public Dataset VIO Replay
|
||||
|
||||
**Summary**: Verify BASALT adapter produces relative motion for synchronized camera/IMU replay.
|
||||
|
||||
**Traces to**: AC-2.1a, AC-2.2
|
||||
|
||||
**Input data**: MUN-FRL preferred slice, or representative synchronized nav-camera + IMU + ground truth.
|
||||
|
||||
**Expected result**: VO registration succeeds for >95% of normal usable frames; frame-to-frame MRE <1.0 px where ground-truth/feature evaluation supports it.
|
||||
|
||||
**Max execution time**: Dataset-dependent; report per-frame latency.
|
||||
|
||||
**Dependencies**: Camera ingest, MAVLink telemetry/replay, calibration fixtures.
|
||||
|
||||
---
|
||||
|
||||
### IT-02: Relative Drift Reporting
|
||||
|
||||
**Summary**: Verify adapter emits state needed for wrapper drift and anchor-age accounting.
|
||||
|
||||
**Traces to**: AC-1.3
|
||||
|
||||
**Input data**: Segment with two known satellite anchors and IMU samples.
|
||||
|
||||
**Expected result**: Adapter emits continuous `VioStatePacket` values with timestamps and quality, enabling wrapper to compare VO extrapolation to next anchor.
|
||||
|
||||
**Max execution time**: Dataset-dependent.
|
||||
|
||||
**Dependencies**: Safety wrapper test harness.
|
||||
|
||||
---
|
||||
|
||||
### IT-03: Tilt/Outlier Robustness
|
||||
|
||||
**Summary**: Verify adapter reports degraded tracking without false success under tilt/outlier cases.
|
||||
|
||||
**Traces to**: AC-3.1
|
||||
|
||||
**Input data**: Replay segment with synthetic ±20° 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.
|
||||
|
||||
**Max execution time**: 15 minutes per fixture.
|
||||
|
||||
---
|
||||
|
||||
### IT-04: Sharp Turn / Loss Signal
|
||||
|
||||
**Summary**: Verify sharp turns and disconnected visual overlap produce wrapper-visible failure signals.
|
||||
|
||||
**Traces to**: AC-3.2, AC-3.4
|
||||
|
||||
**Input data**: <5% overlap sequence with heading change <70°.
|
||||
|
||||
**Expected result**: Adapter emits low tracking quality or `TrackingLost` within the loss window, allowing relocalization trigger.
|
||||
|
||||
**Max execution time**: 10 minutes.
|
||||
|
||||
## Performance Tests
|
||||
|
||||
### PT-01: BASALT Adapter Runtime Budget
|
||||
|
||||
**Summary**: Verify VIO processing does not consume the full <400 ms system p95 budget.
|
||||
|
||||
**Traces to**: AC-4.1, AC-4.2
|
||||
|
||||
**Load scenario**:
|
||||
- Input: synchronized public/representative replay.
|
||||
- Duration: 30 minutes plus release long-run slice.
|
||||
- Target: Jetson Orin Nano Super.
|
||||
|
||||
| Metric | Target | Failure Threshold |
|
||||
|--------|--------|-------------------|
|
||||
| Adapter p95 latency | <=250 ms | >300 ms |
|
||||
| Memory contribution | <=3 GB | >4 GB |
|
||||
| Tracking failure on normal segments | <5% | >=5% |
|
||||
|
||||
**Resource limits**: Total system memory remains below 8 GB.
|
||||
|
||||
## Security Tests
|
||||
|
||||
### ST-01: Timestamp Injection Rejection
|
||||
|
||||
**Summary**: Verify malformed or non-monotonic timestamps do not produce trusted VIO state.
|
||||
|
||||
**Traces to**: AC-NEW-4
|
||||
|
||||
**Attack vector**: Replay or telemetry timestamp manipulation.
|
||||
|
||||
**Test procedure**:
|
||||
1. Feed non-monotonic frame and IMU timestamps.
|
||||
2. Observe adapter output.
|
||||
|
||||
**Expected behavior**: Adapter returns `TimestampMismatch` or low-quality failure; wrapper does not trust the state.
|
||||
|
||||
**Pass criteria**: No high-quality VIO state is emitted from malformed timing.
|
||||
|
||||
## Acceptance Tests
|
||||
|
||||
### AT-01: Normal VIO State Contract
|
||||
|
||||
**Summary**: Confirm adapter output contract supports downstream localization.
|
||||
|
||||
**Traces to**: AC-1.3, AC-2.1a
|
||||
|
||||
| Step | Action | Expected Result |
|
||||
|------|--------|-----------------|
|
||||
| 1 | Initialize with calibrated frame/IMU config | `VioInitResult` succeeds |
|
||||
| 2 | Replay normal frames | `VioStatePacket` includes timestamp, relative pose, velocity, tracking quality |
|
||||
| 3 | End segment | State stream is continuous enough for wrapper drift accounting |
|
||||
|
||||
## Test Data Management
|
||||
|
||||
| Data Set | Description | Source | Size |
|
||||
|----------|-------------|--------|------|
|
||||
| `public_nadir_vio_candidates` | MUN-FRL/ALTO/Kagaru/EPFL slices | Public pinned fixtures | Dataset-dependent |
|
||||
| `representative_sync_replay` | Target camera + FC IMU + ground truth | Project collection | TBD |
|
||||
|
||||
**Setup procedure**: Pin calibration/extrinsics and mount read-only synchronized replay data.
|
||||
|
||||
**Teardown procedure**: Remove generated result reports and adapter temp state.
|
||||
|
||||
**Data isolation strategy**: One run directory per dataset slice and configuration hash.
|
||||
Reference in New Issue
Block a user