Oleksandr Bezdieniezhnykh
10 KiB
GPS-Denied Onboard Localization — Planning Report
Executive Summary
The solution planning phase decomposed the GPS-denied onboard localization service into 9 implementation components, 2 cross-cutting foundation epics, a bootstrap epic, and a blackbox-test epic. The architecture centers on a Jetson-hosted hot path using camera ingest, BASALT VIO, and a project-owned safety/anchor wrapper, with triggered satellite retrieval and ALIKED/DISK-LightGlue anchor verification against an offline PostgreSQL/PostGIS-backed cache.
Jira epics were created in project AZ from AZ-206 through AZ-218. Total estimated effort across epics is approximately 87-141 story points, with large work intentionally decomposed into child tasks of 2, 3, or 5 points where possible.
Problem Statement
The system must provide reliable onboard WGS84 localization when GPS is denied or spoofed, using a fixed nadir camera, flight-controller telemetry, and an offline satellite cache. It must emit ArduPilot-compatible position estimates, report confidence honestly, degrade safely under blackout, and preserve enough forensic evidence for post-flight analysis without retaining raw frames.
Architecture Overview
The system is a trigger-based hybrid estimator. Normal flight uses camera ingest, pre-VIO occlusion checks, BASALT VIO, and a safety/anchor wrapper. Relocalization triggers use DINOv2-VLAD, FAISS, ALIKED/DISK-LightGlue, and OpenCV RANSAC against the offline cache. The wrapper is the safety authority for covariance, source labels, degraded modes, tile-write eligibility, and MAVLink output semantics.
Technology stack: Python orchestration, C++/native vision paths where needed, OpenCV 4.x, BASALT, DINOv2-VLAD, FAISS CPU, ALIKED/DISK-LightGlue, PostgreSQL/PostGIS, COG, CBOR FDR segments, MAVSDK + pymavlink.
Deployment: Local onboard Jetson runtime with Docker/replay and Plane SITL for validation; release gates require Jetson hardware, Plane SITL, and representative synchronized replay data.
Component Summary
| # | Component | Purpose | Dependencies | Epic |
|---|---|---|---|---|
| 01 | Camera Ingest And Calibration | Ingest frames, validate calibration, detect total occlusion before VIO | Bootstrap, shared geometry/time, config/errors | AZ-209 |
| 02 | BASALT VIO Adapter | Wrap BASALT relative VIO and emit replaceable state DTOs | Camera, MAVLink telemetry, shared helpers | AZ-213 |
| 03 | Safety And Anchor Wrapper | Own localization state, covariance, anchors, blackout/failsafe, output semantics | Camera, MAVLink, VIO, anchor verification | AZ-216 |
| 04 | Satellite Retrieval | Retrieve VPR candidates from cache descriptors and FAISS | Camera, cache lifecycle, shared helpers | AZ-214 |
| 05 | Anchor Verification | Verify retrieved candidates with learned matching and RANSAC | Retrieval, camera, cache lifecycle | AZ-215 |
| 06 | Cache And Tile Lifecycle | Manage COGs, PostGIS manifests, sidecars, freshness, generated tiles | Bootstrap, shared helpers, config/errors | AZ-211 |
| 07 | MAVLink And GCS Integration | Consume FC telemetry and emit v1 GPS_INPUT/QGC status |
Bootstrap, config/errors | AZ-210 |
| 08 | FDR And Observability | Record bounded replayable evidence and status | Bootstrap, config/errors, runtime DTOs | AZ-212 |
| 09 | Validation Harness | Drive blackbox, public replay, SITL, Jetson, and release evidence tests | All runtime components | AZ-217 |
Implementation order:
- Bootstrap and cross-cutting foundations: AZ-206, AZ-207, AZ-208.
- Independent adapters/stores: AZ-209, AZ-210, AZ-211, AZ-212.
- Estimation/relocalization: AZ-213, AZ-214, AZ-215.
- Safety orchestration: AZ-216.
- Validation and blackbox test implementation: AZ-217, AZ-218.
System Flows
| Flow | Description | Key Components |
|---|---|---|
| Pre-flight cache preparation | Validate offline cache, sidecars, descriptors, and indexes | Cache lifecycle, retrieval |
| Normal frame processing | Route usable frames through BASALT; route total occlusion to IMU-only degraded path | Camera, BASALT, safety, MAVLink, FDR |
| Satellite relocalization | Retrieve and verify cache candidates, then accept/reject anchors | Safety, retrieval, anchor verification, cache |
| Visual blackout / spoofing | Propagate IMU-only from last trusted state and fail safe at thresholds | Camera, safety, MAVLink, QGC, FDR |
| Generated tile lifecycle | Write generated COG candidates only under covariance/quality gates | Safety, cache, FDR |
| Post-flight sync and audit | Package generated tiles and FDR evidence | Cache, FDR, Satellite Service |
| Validation replay | Exercise runtime through public interfaces | Validation harness, all runtime components |
See system-flows.md for full diagrams and details.
Risk Summary
| Level | Count | Key Risks |
|---|---|---|
| Critical | 0 | None |
| High | 7 | Camera spec mismatch, BASALT nadir fit, covariance under-reporting, total occlusion false-negative, IMU-only over-trust, Jetson trigger-path performance, PostgreSQL/PostGIS availability |
| Medium | 5 | Cache poisoning, dataset coverage/licensing, FDR append pressure, GPL/non-commercial leakage, generated tile promotion risk |
| Low | 0 | None |
Iterations completed: 1
All Critical/High risks mitigated: Yes. High risks have concrete gates in architecture, component specs, and tests.
See risk_mitigations.md for the full register.
Test Coverage
| Component | Integration | Performance | Security | Acceptance | AC Coverage |
|---|---|---|---|---|---|
| Camera Ingest And Calibration | 3 | 1 | 1 | 2 | 7 ACs |
| BASALT VIO Adapter | 4 | 1 | 1 | 1 | 8 ACs |
| Safety And Anchor Wrapper | 7 | 1 | 1 | 3 | 15 ACs |
| Satellite Retrieval | 4 | 2 | 1 | 1 | 10 ACs |
| Anchor Verification | 2 | 1 | 2 | 1 | 9 ACs |
| Cache And Tile Lifecycle | 4 | 1 | 3 | 1 | 10 ACs |
| MAVLink And GCS Integration | 6 | 2 | 1 | 1 | 10 ACs |
| FDR And Observability | 6 | 1 | 1 | 1 | 11 ACs |
| Validation Harness | 9 | 2 | 1 | 2 | All AC groups |
Overall acceptance criteria coverage: 39 / 39 acceptance criteria covered (100%).
Restrictions coverage: 10 / 10 restriction groups covered (100%).
Epic Roadmap
| Order | Epic | Component / Concern | Effort | Dependencies |
|---|---|---|---|---|
| 1 | AZ-206: Bootstrap & Initial Structure | Scaffold | M / 5-8 pts | none |
| 2 | AZ-207: Cross-Cutting: Shared Geometry And Time Sync | Shared helper | S-M / 3-5 pts | AZ-206 |
| 3 | AZ-208: Cross-Cutting: Runtime Configuration And Errors | Shared helper | S-M / 3-5 pts | AZ-206 |
| 4 | AZ-209: Camera Ingest And Calibration | Component 01 | M / 5-8 pts | AZ-206, AZ-207, AZ-208 |
| 5 | AZ-210: MAVLink And GCS Integration | Component 07 | M / 5-8 pts | AZ-206, AZ-208 |
| 6 | AZ-211: Cache And Tile Lifecycle | Component 06 | L / 8-13 pts | AZ-206, AZ-207, AZ-208 |
| 7 | AZ-212: FDR And Observability | Component 08 | M-L / 5-8 pts | AZ-206, AZ-208 |
| 8 | AZ-213: BASALT VIO Adapter | Component 02 | L / 8-13 pts | AZ-209, AZ-210 |
| 9 | AZ-214: Satellite Retrieval | Component 04 | L / 8-13 pts | AZ-209, AZ-211 |
| 10 | AZ-215: Anchor Verification | Component 05 | L / 8-13 pts | AZ-214, AZ-209, AZ-211 |
| 11 | AZ-216: Safety And Anchor Wrapper | Component 03 | XL / 13-21 pts | AZ-209, AZ-210, AZ-213, AZ-215 |
| 12 | AZ-217: Validation Harness | Component 09 | L / 8-13 pts | Component epics |
| 13 | AZ-218: Blackbox Tests | System tests | L / 8-13 pts | AZ-217, component epics |
Total estimated effort: 87-141 story points.
Key Decisions Made
| # | Decision | Rationale | Alternatives Rejected |
|---|---|---|---|
| 1 | Use BASALT as production VIO candidate | Permissive license and strong VIO benchmark fit | OpenVINS production dependency, custom VIO from scratch |
| 2 | Keep safety/anchor wrapper as authority | Product semantics require calibrated covariance, labels, gates, failsafe, MAVLink mapping | Letting BASALT/OpenVINS own output safety |
| 3 | Use ALIKED/DISK-LightGlue for anchor verification | Strong local correspondences for cross-domain verification | Per-frame learned matcher as primary VIO hot path |
| 4 | Add pre-VIO total-occlusion gate | Safer and cheaper than feeding fully unusable frames to VIO | Letting BASALT detect all visual failures |
| 5 | Use PostgreSQL/PostGIS for structured metadata | User confirmed PostgreSQL; PostGIS fits spatial cache/mission metadata | JSON-only or embedded single-file metadata DB |
| 6 | Use CBOR FDR payload segments with PostgreSQL index | Keeps high-volume append data bounded and queryable | Raw-frame retention, plain CSV, Parquet as runtime primary |
| 7 | v1 emits GPS_INPUT only |
Avoid ArduPilot EKF3 double-fusion risk in v1 | Parallel ODOMETRY in v1 |
Open Questions
| # | Question | Impact | Assigned To |
|---|---|---|---|
| 1 | Exact ADTi camera lens, interface, sustained FPS, and temperature spec | Blocks final camera calibration and runtime FPS assumptions | Hardware/product owner |
| 2 | Final representative synchronized target dataset collection timing | Blocks final acceptance, though public datasets can de-risk | Project/product owner |
| 3 | Dataset license approval for ALTO/Kagaru/EPFL/VPAir/UZH FPV use | Blocks commercial acceptance evidence for restricted datasets | Legal/product owner |
| 4 | Local onboard PostgreSQL/PostGIS deployment profile | Blocks implementation details for DB persistence and health checks | Backend/runtime owner |
Artifact Index
| File | Description |
|---|---|
glossary.md |
Confirmed project glossary |
architecture.md |
System architecture and ADRs |
data_model.md |
System data model and storage strategy |
system-flows.md |
Main runtime and validation flows |
deployment/containerization.md |
Container/replay strategy |
deployment/ci_cd_pipeline.md |
CI/CD and release gates |
deployment/environment_strategy.md |
Environment and dataset strategy |
deployment/observability.md |
Runtime signals, logs, and alerts |
deployment/deployment_procedures.md |
Deployment, rollback, and health checks |
components/*/description.md |
Component specifications |
components/*/tests.md |
Component test specifications |
common-helpers/*.md |
Shared helper specifications |
diagrams/component_overview.md |
Component overview Mermaid diagram |
diagrams/flows/*.md |
Flow-specific Mermaid diagrams |
risk_mitigations.md |
Risk register and mitigations |
epics.md |
Jira epic mapping and dependency roadmap |
FINAL_report.md |
This final planning report |