mirror of
https://github.com/azaion/gps-denied-onboard.git
synced 2026-04-22 22:46: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>
9.4 KiB
9.4 KiB
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
ISequentialVisualOdometryinterface 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_ambiguousis 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_sequenceuses 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_angleimplemented 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
reloadflag 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