# Requirements: GPS-Denied Onboard Navigation System

**Defined:** 2026-04-01
**Core Value:** The flight controller must receive valid MAVLink GPS_INPUT at 5-10Hz with position accuracy ≤50m for 80% of frames — without this, the UAV cannot navigate in GPS-denied airspace.

## v1 Requirements

Requirements for this milestone. The scaffold (~2800 lines) exists; all algorithmic kernels are missing or mocked. Every requirement below maps to one phase of implementation work.

### ESKF — Error-State Kalman Filter

- [ ] **ESKF-01**: 15-state ESKF implemented (δp, δv, δθ, δb_a, δb_g) with IMU prediction step (F, Q matrices, bias propagation)
- [ ] **ESKF-02**: VO measurement update implemented (relative pose ΔR/Δt from cuVSLAM, H_vo, R_vo covariance, Kalman gain)
- [ ] **ESKF-03**: Satellite measurement update implemented (absolute WGS84 position from matching, H_sat, R_sat from RANSAC inlier ratio)
- [ ] **ESKF-04**: ESKF state initializes from GLOBAL_POSITION_INT at startup and on mid-flight reboot with high-uncertainty covariance
- [ ] **ESKF-05**: Confidence tier computation outputs HIGH/MEDIUM/LOW based on covariance magnitude and last satellite correction age
- [ ] **ESKF-06**: Coordinate transform chain implemented: pixel→camera ray (K matrix), camera→body (T_cam_body), body→NED (ESKF quaternion), NED→WGS84 — replacing all FAKE Math stubs

### VO — Visual Odometry

- [ ] **VO-01**: cuVSLAM wrapper implemented for Jetson target (Inertial mode, camera + IMU inputs, relative pose output with metric scale)
- [ ] **VO-02**: OpenCV ORB stub conforms to the same `ISequentialVisualOdometry` interface as cuVSLAM wrapper, used on dev/CI (x86)
- [ ] **VO-03**: TensorRT FP16 inference engine loader implemented for SuperPoint and LightGlue on Jetson; MockInferenceEngine used on dev/CI
- [ ] **VO-04**: Scale ambiguity resolved — `scale_ambiguous` is False when ESKF provides metric scale reference; VO relative pose is metric in NED
- [ ] **VO-05**: ImageInputPipeline batch validation minimum lowered to 1 image (not 10); `get_image_by_sequence` uses exact filename matching

### SAT — Satellite Matching

- [ ] **SAT-01**: XFeat TRT FP16 inference engine implemented for satellite feature matching on Jetson; MockInferenceEngine used on dev/CI
- [ ] **SAT-02**: Satellite tile selection uses ESKF position ± 3σ_horizontal to define search area; tiles assembled into mosaic at matcher resolution
- [ ] **SAT-03**: GSD normalization implemented — camera frame downsampled to match satellite GSD (0.3–0.6 m/px) before matching
- [ ] **SAT-04**: RANSAC homography estimation produces WGS84 absolute position with confidence score from inlier ratio
- [ ] **SAT-05**: SatelliteDataManager reads from pre-loaded GeoHash-indexed local directory (read-only, no live HTTP fetches during flight)

### GPR — Global Place Recognition

- [ ] **GPR-01**: Real Faiss index loaded at runtime from file path (not synthetic random vectors); index built from DINOv2 descriptors of actual satellite tiles during offline pre-processing
- [ ] **GPR-02**: DINOv2/AnyLoc TRT FP16 inference engine implemented on Jetson; MockInferenceEngine used on dev/CI
- [ ] **GPR-03**: GPR candidate retrieval returns real tile matches ranked by descriptor similarity, used for re-localization after tracking loss

### MAV — MAVLink Output

- [ ] **MAV-01**: pymavlink added to dependencies; MAVLink output component implemented sending GPS_INPUT over UART at 5-10Hz
- [ ] **MAV-02**: ESKF state and covariance mapped to GPS_INPUT fields (lat/lon/alt from position, velocity from v-state, accuracy from covariance diagonal, fix_type from confidence tier, synthesized hdop/vdop, GPS time from system clock)
- [ ] **MAV-03**: IMU input path implemented — MAVLink listener receives ATTITUDE/RAW_IMU from flight controller at 5-10Hz and feeds ESKF prediction step
- [ ] **MAV-04**: Consecutive-failure counter detects 3 frames without any position estimate; sends MAVLink NAMED_VALUE_FLOAT re-localization request to ground station operator
- [ ] **MAV-05**: Telemetry output at 1Hz sends confidence score and drift estimate to ground station via MAVLink NAMED_VALUE_FLOAT

### PIPE — Pipeline Wiring

- [ ] **PIPE-01**: FlightProcessor.process_frame wired end-to-end: image in → cuVSLAM VO → ESKF VO update → (keyframe) satellite match → ESKF satellite update → GPS_INPUT output
- [ ] **PIPE-02**: SatelliteDataManager and CoordinateTransformer instantiated and wired into processor pipeline (currently standalone, not connected)
- [ ] **PIPE-03**: FactorGraph replaced or backed by real GTSAM ISAM2 incremental smoothing with BetweenFactorPose3 (VO) and GPSFactor (satellite anchors)
- [ ] **PIPE-04**: FailureRecoveryCoordinator connected to ESKF — on tracking loss, ESKF continues IMU-only prediction with growing uncertainty; on recovery success, ESKF is reset with satellite position
- [ ] **PIPE-05**: ImageRotationManager integrated into process_frame — heading sweep on first frame; `calculate_precise_angle` implemented with real VO-based refinement
- [ ] **PIPE-06**: Object GPS localization endpoint (POST /objects/locate) uses full pixel→ray→ground→WGS84 chain with ESKF attitude; hardcoded stub removed
- [ ] **PIPE-07**: Confidence scoring and fix_type mapping wired end-to-end: ESKF confidence tier → GPS_INPUT fix_type (3/2/0), accuracy fields
- [ ] **PIPE-08**: ImageRotationManager constructor signature fixed (accepts optional ModelManager); startup TypeError resolved

### TEST — Test Harness and Validation

- [ ] **TEST-01**: Docker SITL test harness implemented: ArduPilot SITL container, camera-replay service, satellite tile server mock, MAVLink capture
- [ ] **TEST-02**: CI pipeline runs on x86 using OpenCV ORB stub and MockInferenceEngine; all unit tests pass
- [ ] **TEST-03**: Accuracy validation test runs against 60-frame dataset (AD000001–AD000060.jpg) with coordinates.csv ground truth; reports 80%/50m and 60%/20m hit rates
- [ ] **TEST-04**: Performance benchmark test validates <400ms end-to-end per frame on Jetson (or reports estimated latency breakdown on dev)
- [ ] **TEST-05**: All 21 blackbox test scenarios (FT-P-01 to FT-P-14, FT-N-01 to FT-N-07) implemented as runnable pytest tests using SITL harness

## v2 Requirements

Deferred to future release. Tracked but not in current roadmap.

### Security

- **SEC-01**: JWT bearer token authentication on all API endpoints
- **SEC-02**: TLS 1.3 on all HTTPS connections
- **SEC-03**: Satellite tile manifest SHA-256 integrity verification
- **SEC-04**: Mahalanobis distance outlier rejection in ESKF measurement updates
- **SEC-05**: CORS origins locked down (remove wildcard default)

### Operational

- **OPS-01**: Uvicorn `reload` flag defaults to False in production config
- **OPS-02**: Structured logging with configurable log levels per module
- **OPS-03**: Pre-flight health check validates TRT engines loaded, tiles present, IMU receiving
- **OPS-04**: ResultManager.publish_waypoint_update implemented for waypoint SSE emission

### Performance

- **PERF-01**: Dual CUDA stream execution (Stream A: VO, Stream B: satellite matching) for pipeline parallelism
- **PERF-02**: Satellite tile RAM preload (±2km corridor) at startup for sub-millisecond tile access

## Out of Scope

Explicitly excluded. Documented to prevent scope creep.

| Feature | Reason |
|---------|--------|
| TRT engine building tooling | Engines are pre-built offline via trtexec; system only loads them |
| Google Maps tile download tooling | Tiles pre-cached before flight; no live internet during flight |
| Full ArduPilot hardware validation on Jetson | Post-v1; Jetson hardware testing is not in scope for this milestone |
| Mobile/web ground station UI | SSE stream consumed by external systems; UI is out of scope |
| Multi-UAV coordination | Single UAV instance only |
| GTSAM ARM64 source build tooling | GTSAM on Jetson requires source compilation; CI uses mock; Jetson build is ops concern |
| tech_stack.md synchronization | Documented inconsistency (3fps vs 0.7fps, etc.); separate documentation task |

## Traceability

Which phases cover which requirements. Populated from ROADMAP.md phase assignments.

| Requirement | Phase | Status |
|-------------|-------|--------|
| ESKF-01 | Phase 1 | Pending |
| ESKF-02 | Phase 1 | Pending |
| ESKF-03 | Phase 1 | Pending |
| ESKF-04 | Phase 1 | Pending |
| ESKF-05 | Phase 1 | Pending |
| ESKF-06 | Phase 1 | Pending |
| VO-01 | Phase 2 | Pending |
| VO-02 | Phase 2 | Pending |
| VO-03 | Phase 2 | Pending |
| VO-04 | Phase 2 | Pending |
| VO-05 | Phase 2 | Pending |
| SAT-01 | Phase 3 | Pending |
| SAT-02 | Phase 3 | Pending |
| SAT-03 | Phase 3 | Pending |
| SAT-04 | Phase 3 | Pending |
| SAT-05 | Phase 3 | Pending |
| GPR-01 | Phase 3 | Pending |
| GPR-02 | Phase 3 | Pending |
| GPR-03 | Phase 3 | Pending |
| MAV-01 | Phase 4 | Pending |
| MAV-02 | Phase 4 | Pending |
| MAV-03 | Phase 4 | Pending |
| MAV-04 | Phase 4 | Pending |
| MAV-05 | Phase 4 | Pending |
| PIPE-01 | Phase 5 | Pending |
| PIPE-02 | Phase 5 | Pending |
| PIPE-03 | Phase 5 | Pending |
| PIPE-04 | Phase 5 | Pending |
| PIPE-05 | Phase 5 | Pending |
| PIPE-06 | Phase 5 | Pending |
| PIPE-07 | Phase 5 | Pending |
| PIPE-08 | Phase 5 | Pending |
| TEST-01 | Phase 6 | Pending |
| TEST-02 | Phase 6 | Pending |
| TEST-03 | Phase 7 | Pending |
| TEST-04 | Phase 7 | Pending |
| TEST-05 | Phase 7 | Pending |

**Coverage:**
- v1 requirements: 36 total
- Mapped to phases: 36
- Unmapped: 0

---
*Requirements defined: 2026-04-01*
*Last updated: 2026-04-01 after initial definition*