azaion/gps-denied-onboard
1
0
Fork 0
mirror of https://github.com/azaion/gps-denied-onboard.git synced 2026-06-22 08:41:13 +00:00
Code Issues Packages Projects Releases Wiki Activity

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.

Browse Source
This commit is contained in:
Oleksandr Bezdieniezhnykh
2026-05-01 16:24:46 +03:00
parent 3f173c1bb7
commit 7e15868d39
62 changed files with 6878 additions and 13 deletions
Download Patch File Download Diff File Expand all files Collapse all files
_docs/02_document/FINAL_report.md
+148
View File
@@ -0,0 +1,148 @@
# 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**:
1. Bootstrap and cross-cutting foundations: AZ-206, AZ-207, AZ-208.
2. Independent adapters/stores: AZ-209, AZ-210, AZ-211, AZ-212.
3. Estimation/relocalization: AZ-213, AZ-214, AZ-215.
4. Safety orchestration: AZ-216.
5. 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 |