mirror of
https://github.com/azaion/gps-denied-onboard.git
synced 2026-04-23 04:26:36 +00:00
Yuzviak
659050f20b
36 v1 requirements across 6 categories (ESKF, VO, SAT, GPR, MAV, PIPE, TEST). 7-phase roadmap ordered by dependency: ESKF → VO → Satellite → MAVLink → Pipeline → SITL → Validation. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
158 lines
9.4 KiB
Markdown
158 lines
9.4 KiB
Markdown
# 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*
|