From 7e15868d39239ededdce5a54c09f52dbb6b6ba1e Mon Sep 17 00:00:00 2001 From: Oleksandr Bezdieniezhnykh Date: Fri, 1 May 2026 16:24:46 +0300 Subject: [PATCH] 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. --- _docs/00_problem/acceptance_criteria.md | 21 +- .../expected_results/results_report.md | 86 ++++ _docs/00_problem/problem.md | 2 +- _docs/00_problem/restrictions.md | 7 +- _docs/00_research/00_ac_assessment.md | 54 +++ .../00_research/00_question_decomposition.md | 145 ++++++ _docs/00_research/01_source_registry.md | 419 ++++++++++++++++++ _docs/00_research/02_fact_cards.md | 348 +++++++++++++++ _docs/00_research/03_comparison_framework.md | 55 +++ _docs/00_research/04_reasoning_chain.md | 181 ++++++++ _docs/00_research/05_validation_log.md | 51 +++ _docs/00_research/06_component_fit_matrix.md | 107 +++++ _docs/01_solution/solution.md | 130 ++++++ _docs/01_solution/solution_draft01.md | 149 +++++++ _docs/01_solution/solution_draft02.md | 125 ++++++ _docs/01_solution/tech_stack.md | 59 +++ _docs/02_document/FINAL_report.md | 148 +++++++ _docs/02_document/architecture.md | 241 ++++++++++ .../common-helpers/01_helper_geo_geometry.md | 30 ++ .../common-helpers/02_helper_time_sync.md | 29 ++ .../description.md | 115 +++++ .../01_camera_ingest_calibration/tests.md | 139 ++++++ .../02_basalt_vio_adapter/description.md | 92 ++++ .../components/02_basalt_vio_adapter/tests.md | 140 ++++++ .../03_safety_anchor_wrapper/description.md | 106 +++++ .../03_safety_anchor_wrapper/tests.md | 208 +++++++++ .../04_satellite_retrieval/description.md | 96 ++++ .../04_satellite_retrieval/tests.md | 153 +++++++ .../05_anchor_verification/description.md | 93 ++++ .../05_anchor_verification/tests.md | 124 ++++++ .../06_cache_tile_lifecycle/description.md | 90 ++++ .../06_cache_tile_lifecycle/tests.md | 167 +++++++ .../07_mavlink_gcs_integration/description.md | 69 +++ .../07_mavlink_gcs_integration/tests.md | 176 ++++++++ .../08_fdr_observability/description.md | 79 ++++ .../components/08_fdr_observability/tests.md | 166 +++++++ .../09_validation_harness/description.md | 86 ++++ .../components/09_validation_harness/tests.md | 232 ++++++++++ _docs/02_document/data_model.md | 148 +++++++ _docs/02_document/deployment/README.md | 11 + .../02_document/deployment/ci_cd_pipeline.md | 54 +++ .../deployment/containerization.md | 46 ++ .../deployment/deployment_procedures.md | 68 +++ .../deployment/environment_strategy.md | 49 ++ _docs/02_document/deployment/observability.md | 61 +++ .../diagrams/component_overview.md | 46 ++ .../flows/flow_cache_tile_lifecycle.md | 18 + .../flows/flow_normal_localization.md | 21 + .../flows/flow_satellite_relocalization.md | 21 + _docs/02_document/epics.md | 131 ++++++ _docs/02_document/glossary.md | 96 ++++ _docs/02_document/risk_mitigations.md | 275 ++++++++++++ _docs/02_document/system-flows.md | 322 ++++++++++++++ _docs/02_document/tests/blackbox-tests.md | 168 +++++++ _docs/02_document/tests/environment.md | 123 +++++ _docs/02_document/tests/performance-tests.md | 94 ++++ _docs/02_document/tests/resilience-tests.md | 85 ++++ .../02_document/tests/resource-limit-tests.md | 85 ++++ _docs/02_document/tests/security-tests.md | 62 +++ _docs/02_document/tests/test-data.md | 95 ++++ .../02_document/tests/traceability-matrix.md | 80 ++++ _docs/_autodev_state.md | 14 + 62 files changed, 6878 insertions(+), 13 deletions(-) create mode 100644 _docs/00_problem/input_data/expected_results/results_report.md create mode 100644 _docs/00_research/00_ac_assessment.md create mode 100644 _docs/00_research/00_question_decomposition.md create mode 100644 _docs/00_research/01_source_registry.md create mode 100644 _docs/00_research/02_fact_cards.md create mode 100644 _docs/00_research/03_comparison_framework.md create mode 100644 _docs/00_research/04_reasoning_chain.md create mode 100644 _docs/00_research/05_validation_log.md create mode 100644 _docs/00_research/06_component_fit_matrix.md create mode 100644 _docs/01_solution/solution.md create mode 100644 _docs/01_solution/solution_draft01.md create mode 100644 _docs/01_solution/solution_draft02.md create mode 100644 _docs/01_solution/tech_stack.md create mode 100644 _docs/02_document/FINAL_report.md create mode 100644 _docs/02_document/architecture.md create mode 100644 _docs/02_document/common-helpers/01_helper_geo_geometry.md create mode 100644 _docs/02_document/common-helpers/02_helper_time_sync.md create mode 100644 _docs/02_document/components/01_camera_ingest_calibration/description.md create mode 100644 _docs/02_document/components/01_camera_ingest_calibration/tests.md create mode 100644 _docs/02_document/components/02_basalt_vio_adapter/description.md create mode 100644 _docs/02_document/components/02_basalt_vio_adapter/tests.md create mode 100644 _docs/02_document/components/03_safety_anchor_wrapper/description.md create mode 100644 _docs/02_document/components/03_safety_anchor_wrapper/tests.md create mode 100644 _docs/02_document/components/04_satellite_retrieval/description.md create mode 100644 _docs/02_document/components/04_satellite_retrieval/tests.md create mode 100644 _docs/02_document/components/05_anchor_verification/description.md create mode 100644 _docs/02_document/components/05_anchor_verification/tests.md create mode 100644 _docs/02_document/components/06_cache_tile_lifecycle/description.md create mode 100644 _docs/02_document/components/06_cache_tile_lifecycle/tests.md create mode 100644 _docs/02_document/components/07_mavlink_gcs_integration/description.md create mode 100644 _docs/02_document/components/07_mavlink_gcs_integration/tests.md create mode 100644 _docs/02_document/components/08_fdr_observability/description.md create mode 100644 _docs/02_document/components/08_fdr_observability/tests.md create mode 100644 _docs/02_document/components/09_validation_harness/description.md create mode 100644 _docs/02_document/components/09_validation_harness/tests.md create mode 100644 _docs/02_document/data_model.md create mode 100644 _docs/02_document/deployment/README.md create mode 100644 _docs/02_document/deployment/ci_cd_pipeline.md create mode 100644 _docs/02_document/deployment/containerization.md create mode 100644 _docs/02_document/deployment/deployment_procedures.md create mode 100644 _docs/02_document/deployment/environment_strategy.md create mode 100644 _docs/02_document/deployment/observability.md create mode 100644 _docs/02_document/diagrams/component_overview.md create mode 100644 _docs/02_document/diagrams/flows/flow_cache_tile_lifecycle.md create mode 100644 _docs/02_document/diagrams/flows/flow_normal_localization.md create mode 100644 _docs/02_document/diagrams/flows/flow_satellite_relocalization.md create mode 100644 _docs/02_document/epics.md create mode 100644 _docs/02_document/glossary.md create mode 100644 _docs/02_document/risk_mitigations.md create mode 100644 _docs/02_document/system-flows.md create mode 100644 _docs/02_document/tests/blackbox-tests.md create mode 100644 _docs/02_document/tests/environment.md create mode 100644 _docs/02_document/tests/performance-tests.md create mode 100644 _docs/02_document/tests/resilience-tests.md create mode 100644 _docs/02_document/tests/resource-limit-tests.md create mode 100644 _docs/02_document/tests/security-tests.md create mode 100644 _docs/02_document/tests/test-data.md create mode 100644 _docs/02_document/tests/traceability-matrix.md create mode 100644 _docs/_autodev_state.md diff --git a/_docs/00_problem/acceptance_criteria.md b/_docs/00_problem/acceptance_criteria.md index 411eeaa..2223b0f 100644 --- a/_docs/00_problem/acceptance_criteria.md +++ b/_docs/00_problem/acceptance_criteria.md @@ -1,22 +1,25 @@ # Acceptance Criteria -> **Last revised**: 2026-04-29 (visual-blackout / GPS-spoofing degraded-mode addendum). +> **Last revised**: 2026-05-01 (Phase 1 AC/restrictions assessment clarifications). > Changes vs. previous version (2026-04-25): AC-1.2 split into hard-floor + stretch; AC-1.4 made quantitative; AC-2.2 split per pipeline stage; AC-3.4 dual-trigger; AC-4.3 autopilot-pinned; AC-5.2 N pinned; AC-7.1 scoped to level flight; AC-8.2 freshness by sector; six new AC added (AC-NEW-1 … AC-NEW-6). > Changes 2026-04-26: AC-4.3 extended to dual-channel hybrid (GPS_INPUT primary + ODOMETRY auxiliary); AC-8.6 added (VPR retrieval-unit + change-robustness); AC-NEW-7 added with confirmed numeric thresholds (cache-poisoning safety budget). > Changes 2026-04-29: AC-3.5 and AC-NEW-8 added for temporary visual blackout/cloud occlusion during GPS spoofing, including IMU-only degraded navigation, covariance growth, and failover limits. +> Changes 2026-05-01: AC-1.3 anchor-age reporting clarified; AC-2.1 split so the >95% rate applies to VO registration, not every satellite re-anchor; AC-5.2 and AC-NEW-2 now require ArduPilot Plane SITL trigger verification; AC-8.3 storage accounting and AC-NEW-7 Satellite Service ownership clarified. ## Position Accuracy - **AC-1.1** — The system shall determine GPS coordinates of frame centers within **50 m** of true GPS for **≥80%** of photos in normal flight segments. - **AC-1.2** — The system shall determine GPS coordinates of frame centers within **20 m** of true GPS for **≥50%** of photos in normal flight segments. -- **AC-1.3** — Maximum cumulative VO drift between two consecutive satellite-anchored fixes shall be **<100 m** (VO-only fallback) or **<50 m** (when IMU is fused). Drift is measured as ‖VO-extrapolated centre − next anchor centre‖ at the moment of the anchor fix. +- **AC-1.3** — Maximum cumulative VO drift between two consecutive satellite-anchored fixes shall be **<100 m** (VO-only fallback) or **<50 m** (when IMU is fused). Drift is measured as ‖VO-extrapolated centre − next anchor centre‖ at the moment of the anchor fix. Every emitted estimate shall include `last_satellite_anchor_age_ms`; validation results shall be binned by anchor age, and the solution draft must define the maximum anchor age after which estimates are treated as degraded (`vo_extrapolated` or `dead_reckoned`) with monotonically growing covariance. - **AC-1.4** — The system shall report a **quantitative confidence score** per position estimate, comprising: - the 95% covariance ellipse semi-major axis in meters, AND - a categorical label `{satellite_anchored, vo_extrapolated, dead_reckoned}`. ## Image Processing Quality -- **AC-2.1** — Image registration rate **>95%** for normal flight segments (defined as: nadir flight ±10° bank / pitch, ≥40% overlap with prior frame, daytime, season-matched satellite tile). +- **AC-2.1** — Image registration rate is split by registration type: + - **AC-2.1a — VO registration**: frame-to-frame visual registration shall succeed for **>95%** of normal flight segments (defined as: nadir flight ±10° bank / pitch, ≥40% overlap with prior frame, daytime, usable texture, no full visual blackout). + - **AC-2.1b — Satellite-anchor registration**: cross-domain UAV-photo to satellite/cache registration is measured separately and is not hidden inside AC-2.1a. Satellite anchoring must satisfy AC-1.1 / AC-1.2 position accuracy, AC-2.2 cross-domain MRE, AC-8.2 freshness, and AC-8.6 retrieval behavior on season-matched tiles. - **AC-2.2** — Mean Reprojection Error (MRE): - **<1.0 px** for VO frame-to-frame homography on overlapping aerial pairs; - **<2.5 px** for satellite-anchored cross-domain (UAV photo ↔ ortho satellite tile) registration. @@ -31,7 +34,7 @@ ## Real-Time Onboard Performance -- **AC-4.1** — End-to-end latency from camera capture to GPS coordinate output to the flight controller shall be **<400 ms p95**. Up to ~10% of frames may be dropped under sustained load (skip-allowed). +- **AC-4.1** — End-to-end latency from camera capture to GPS coordinate output to the flight controller shall be **<400 ms p95**. Up to ~10% of frames may be dropped under sustained load (skip-allowed). Heavy global VPR / cross-domain re-ranking shall be conditional, not part of the steady-state per-frame path, unless profiling proves the full path stays inside the latency and memory budgets on the target Jetson. - **AC-4.2** — Memory usage shall remain below **8 GB** shared on Jetson Orin Nano Super (CPU and GPU share the same 8 GB LPDDR5 pool). - **AC-4.3** — The system shall output its position estimate to the flight controller via **two parallel MAVLink channels**, both emitted by **pymavlink** (general telemetry uses MAVSDK): - **Primary**: `GPS_INPUT` targeting **ArduPilot** with `GPS1_TYPE=14` (MAVLink GPS substitute). Matches the "replacement for the GPS module" framing of the build. @@ -45,7 +48,7 @@ ## Startup & Failsafe - **AC-5.1** — The system shall initialise using the last known valid GPS position from the flight controller's EKF, plus IMU-extrapolated position at the moment of GPS denial. -- **AC-5.2** — If the system fails to produce any position estimate for **>3 s**, the flight controller shall fall back to IMU-only dead reckoning and the system shall log the failure. +- **AC-5.2** — If the system fails to produce any position estimate for **>3 s**, the flight controller shall fall back to IMU-only dead reckoning and the system shall log the failure. Because ArduPilot failsafe timing depends on vehicle type and parameters, this fallback behavior must be verified specifically in ArduPilot Plane SITL with the production parameter set; Copter defaults are reference evidence only. - **AC-5.3** — On companion computer reboot mid-flight, the system shall attempt to re-initialise from the flight controller's current IMU-extrapolated position. See AC-NEW-1 for the cold-start time-to-first-fix budget. ## Ground Station & Telemetry @@ -66,7 +69,7 @@ - **<6 months old** for active-conflict sectors; - **<12 months old** for stable rear sectors. System shall reject or downgrade-confidence on tiles older than these thresholds (see AC-NEW-6). -- **AC-8.3** — Satellite imagery for the operational area shall be **pre-loaded and pre-processed** onto the companion computer before flight. Offline preprocessing time is not time-critical (minutes/hours). Pre-extracted tile descriptors (e.g., SuperPoint keypoints/descriptors and DINOv2-VLAD global descriptors) are part of the cache. +- **AC-8.3** — Satellite imagery for the operational area shall be **pre-loaded and pre-processed** onto the companion computer before flight. Offline preprocessing time is not time-critical (minutes/hours). Pre-extracted tile descriptors (e.g., SuperPoint keypoints/descriptors and DINOv2-VLAD global descriptors) are part of the cache and count against the storage budget unless the solution draft explicitly defines a separate descriptor/index budget. - **AC-8.4** — **Mid-flight tile generation & write-back**: during flight, the system shall continuously orthorectify navigation-camera frames into tiles aligned with the basemap projection and store them in the local cache, **deduplicated** so each ground sector is stored at most once (latest / highest-quality tile wins). On landing, the companion computer shall upload newly generated tiles back to the Azaion Suite Satellite Service so that the next mission cache contains imagery refreshed by the previous flight. - **AC-8.5** — **Storage policy**: the system shall **not** retain raw navigation-camera frames or AI-camera frames as part of normal operation. Tiles are the only persistent imagery artifact. Forensic exception: a low-rate (≤0.1 Hz) thumbnail log of frames that **failed** tile generation may be retained for debugging within the FDR budget (AC-NEW-3). - **AC-8.6** — **VPR retrieval unit + change-robustness**: @@ -93,9 +96,9 @@ **Why it matters.** Without this gate, the FC may continue to follow a spoofed real-GPS source while our valid estimate sits idle. 3 s is short enough to keep the FC from acting on a malicious heading change but long enough to ride out a single-frame anomaly. -**Implementation drivers.** Subscribe to `GPS_RAW_INT`, `EKF_STATUS_REPORT`, `SYS_STATUS`. Maintain an internal "real-GPS health" rolling average; switch to "primary" mode (raise our `GPS_INPUT` `fix_type` to 3D and assert) when health drops below threshold for ≥1 s. Emit `STATUSTEXT` to QGC on every promotion / demotion. +**Implementation drivers.** Subscribe to `GPS_RAW_INT`, `EKF_STATUS_REPORT`, `SYS_STATUS`, and any ArduPilot Plane EKF/GPS status messages available in the production firmware. Maintain an internal "real-GPS health" rolling average; switch to "primary" mode (raise our `GPS_INPUT` `fix_type` to 3D and assert) when the verified Plane-specific health trigger stays below threshold for >=1 s. Emit `STATUSTEXT` to QGC on every promotion / demotion. -**Validation.** SITL: simulate spoofing (inject false `GPS_RAW_INT` from a malicious node); measure time from spoof onset to our promotion. Pass = 95% percentile <3 s. +**Validation.** ArduPilot Plane SITL: simulate spoofing (inject false `GPS_RAW_INT` from a malicious node); verify the exact trigger signals used by the production parameter set; measure time from spoof onset to our promotion. Pass = 95% percentile <3 s. ### AC-NEW-3 — Flight Data Recorder @@ -150,7 +153,7 @@ **Implementation drivers.** - Service-source tiles are immutable within freshness budget (AC-8.2); onboard tiles overwrite only stale or other-onboard tiles. -- The Suite Satellite Service ingest applies a **2-flight voting layer**: an onboard tile gets promoted to "trusted basemap" only after **N≥2 independent flights** confirm consistent geo-alignment within X m of each other. (Active sectors per AC-NEW-6 may use single-flight promotion when σ_xy ≤ 3 m AND OSM-road-overlap ≥ 70 %.) +- The onboard GPS-Denied system writes tile-quality metadata required by the Suite Satellite Service. The Service-side ingest applies a **2-flight voting layer**: an onboard tile gets promoted to "trusted basemap" only after **N>=2 independent flights** confirm consistent geo-alignment within X m of each other. (Active sectors per AC-NEW-6 may use single-flight promotion when σ_xy <= 3 m AND OSM-road-overlap >= 70 %.) The voting layer is an external Suite Satellite Service dependency, not implemented inside this onboard build, but its contract is required for AC-NEW-7 to pass end-to-end. - The Component-1b parent-pose covariance is a **hard gate** in the local quality score: σ_xy ≤ 5 m for a hard write (`trust_level = candidate`); σ_xy ≤ 3 m for `trust_level = candidate` with full quality; tiles written in the σ_xy ∈ (3, 5] m band are marked `trust_level = soft` in the sidecar. - Eligibility check (Component 1b) tightens generation gate from σ_xy ≤ 10 m to σ_xy ≤ 5 m. diff --git a/_docs/00_problem/input_data/expected_results/results_report.md b/_docs/00_problem/input_data/expected_results/results_report.md new file mode 100644 index 0000000..5109bcc --- /dev/null +++ b/_docs/00_problem/input_data/expected_results/results_report.md @@ -0,0 +1,86 @@ +# Expected Results Mapping + +## Scope + +`coordinates.csv` is the current source of truth for the provided nadir image set. It gives expected WGS84 frame-center coordinates for `AD000001.jpg` through `AD000060.jpg`. + +This data is sufficient for black-box frame-center geolocation tests against still images. It is not sufficient for final BASALT VIO, IMU-fusion, blackout, spoofing, or flight-controller tests because synchronized IMU/attitude/airspeed/altitude and ground-truth trajectory are not present in this sample set. + +## Pass / Fail Rules + +- **Normal frame-center geolocation**: estimated frame center is within 50 m of the expected WGS84 coordinate. +- **Stretch accuracy bin**: estimated frame center is within 20 m of the expected WGS84 coordinate. +- **Dataset aggregate**: at least 80% of mapped images pass the 50 m threshold and at least 50% pass the 20 m threshold. +- **Output shape**: each result must include image name, estimated `lat`, estimated `lon`, error in meters, source label, 95% covariance semi-major axis, and `last_satellite_anchor_age_ms`. + +## Input To Expected Output Map + +| Input image | Expected latitude | Expected longitude | Primary threshold | Stretch threshold | +|-------------|-------------------|--------------------|-------------------|-------------------| +| AD000001.jpg | 48.275292 | 37.385220 | <= 50 m | <= 20 m | +| AD000002.jpg | 48.275001 | 37.382922 | <= 50 m | <= 20 m | +| AD000003.jpg | 48.274520 | 37.381657 | <= 50 m | <= 20 m | +| AD000004.jpg | 48.274956 | 37.379004 | <= 50 m | <= 20 m | +| AD000005.jpg | 48.273997 | 37.379828 | <= 50 m | <= 20 m | +| AD000006.jpg | 48.272538 | 37.380294 | <= 50 m | <= 20 m | +| AD000007.jpg | 48.272408 | 37.379153 | <= 50 m | <= 20 m | +| AD000008.jpg | 48.271992 | 37.377572 | <= 50 m | <= 20 m | +| AD000009.jpg | 48.271376 | 37.376671 | <= 50 m | <= 20 m | +| AD000010.jpg | 48.271233 | 37.374806 | <= 50 m | <= 20 m | +| AD000011.jpg | 48.270334 | 37.374442 | <= 50 m | <= 20 m | +| AD000012.jpg | 48.269922 | 37.373284 | <= 50 m | <= 20 m | +| AD000013.jpg | 48.269366 | 37.372134 | <= 50 m | <= 20 m | +| AD000014.jpg | 48.268759 | 37.370940 | <= 50 m | <= 20 m | +| AD000015.jpg | 48.268291 | 37.369815 | <= 50 m | <= 20 m | +| AD000016.jpg | 48.267719 | 37.368469 | <= 50 m | <= 20 m | +| AD000017.jpg | 48.267461 | 37.367255 | <= 50 m | <= 20 m | +| AD000018.jpg | 48.266663 | 37.365888 | <= 50 m | <= 20 m | +| AD000019.jpg | 48.266135 | 37.365460 | <= 50 m | <= 20 m | +| AD000020.jpg | 48.265574 | 37.364211 | <= 50 m | <= 20 m | +| AD000021.jpg | 48.264892 | 37.362998 | <= 50 m | <= 20 m | +| AD000022.jpg | 48.264393 | 37.361086 | <= 50 m | <= 20 m | +| AD000023.jpg | 48.263803 | 37.361028 | <= 50 m | <= 20 m | +| AD000024.jpg | 48.263014 | 37.359878 | <= 50 m | <= 20 m | +| AD000025.jpg | 48.262635 | 37.358277 | <= 50 m | <= 20 m | +| AD000026.jpg | 48.261819 | 37.357116 | <= 50 m | <= 20 m | +| AD000027.jpg | 48.261182 | 37.355907 | <= 50 m | <= 20 m | +| AD000028.jpg | 48.260727 | 37.354723 | <= 50 m | <= 20 m | +| AD000029.jpg | 48.260117 | 37.353469 | <= 50 m | <= 20 m | +| AD000030.jpg | 48.259677 | 37.352165 | <= 50 m | <= 20 m | +| AD000031.jpg | 48.258881 | 37.351376 | <= 50 m | <= 20 m | +| AD000032.jpg | 48.258425 | 37.349964 | <= 50 m | <= 20 m | +| AD000033.jpg | 48.258653 | 37.347004 | <= 50 m | <= 20 m | +| AD000034.jpg | 48.257879 | 37.347711 | <= 50 m | <= 20 m | +| AD000035.jpg | 48.256777 | 37.348444 | <= 50 m | <= 20 m | +| AD000036.jpg | 48.255756 | 37.348098 | <= 50 m | <= 20 m | +| AD000037.jpg | 48.255375 | 37.346549 | <= 50 m | <= 20 m | +| AD000038.jpg | 48.254799 | 37.345603 | <= 50 m | <= 20 m | +| AD000039.jpg | 48.254557 | 37.344566 | <= 50 m | <= 20 m | +| AD000040.jpg | 48.254380 | 37.344375 | <= 50 m | <= 20 m | +| AD000041.jpg | 48.253722 | 37.343093 | <= 50 m | <= 20 m | +| AD000042.jpg | 48.254205 | 37.340532 | <= 50 m | <= 20 m | +| AD000043.jpg | 48.252380 | 37.342112 | <= 50 m | <= 20 m | +| AD000044.jpg | 48.251489 | 37.343079 | <= 50 m | <= 20 m | +| AD000045.jpg | 48.251085 | 37.346128 | <= 50 m | <= 20 m | +| AD000046.jpg | 48.250413 | 37.344034 | <= 50 m | <= 20 m | +| AD000047.jpg | 48.249414 | 37.343296 | <= 50 m | <= 20 m | +| AD000048.jpg | 48.249114 | 37.346895 | <= 50 m | <= 20 m | +| AD000049.jpg | 48.250241 | 37.347741 | <= 50 m | <= 20 m | +| AD000050.jpg | 48.250974 | 37.348379 | <= 50 m | <= 20 m | +| AD000051.jpg | 48.251528 | 37.349468 | <= 50 m | <= 20 m | +| AD000052.jpg | 48.251873 | 37.350485 | <= 50 m | <= 20 m | +| AD000053.jpg | 48.252161 | 37.351491 | <= 50 m | <= 20 m | +| AD000054.jpg | 48.252685 | 37.352343 | <= 50 m | <= 20 m | +| AD000055.jpg | 48.253268 | 37.353119 | <= 50 m | <= 20 m | +| AD000056.jpg | 48.253767 | 37.354246 | <= 50 m | <= 20 m | +| AD000057.jpg | 48.254329 | 37.354946 | <= 50 m | <= 20 m | +| AD000058.jpg | 48.254874 | 37.355765 | <= 50 m | <= 20 m | +| AD000059.jpg | 48.255481 | 37.356501 | <= 50 m | <= 20 m | +| AD000060.jpg | 48.256246 | 37.357485 | <= 50 m | <= 20 m | + +## Known Gaps + +- No synchronized IMU, attitude, airspeed, altitude, or timestamp stream is present for these images. +- No ground-truth trajectory exists beyond per-image center coordinates. +- The sample cadence is slower than the target 3 fps runtime profile. +- Final acceptance requires additional public and representative datasets with synchronized camera/IMU/ground truth. diff --git a/_docs/00_problem/problem.md b/_docs/00_problem/problem.md index 3bd3b70..7745fe7 100644 --- a/_docs/00_problem/problem.md +++ b/_docs/00_problem/problem.md @@ -1,2 +1,2 @@ -We have a wing-type UAV with a camera pointing downwards that can take photos 3 times per second with a resolution 6200*4100. Also plane has flight controller with IMU. During the plane flight, we know GPS coordinates initially. During the flight, GPS could be disabled or spoofed. We need to determine the GPS of the centers of the next frame from the camera. And also the coordinates of the center of any object in these photos. We can use an external satellite provider for ground checks on the existing photos. So, before the flight, UAV's operator should upload the satellite photos to the plane's companion PC. +We have a wing-type UAV with a fixed downward navigation camera that can take photos 3 times per second. The authoritative navigation-camera spec is defined in `restrictions.md` as the ADTi 20MP 20L V1, APS-C sensor, about 5472 x 3648 px; older higher-resolution references are superseded. Also plane has flight controller with IMU. During the plane flight, we know GPS coordinates initially. During the flight, GPS could be disabled or spoofed. We need to determine the GPS of the centers of the next frame from the camera. And also the coordinates of the center of any object in these photos. We can use an external satellite provider for ground checks on the existing photos. So, before the flight, UAV's operator should upload the satellite photos to the plane's companion PC. The real world examples are in input_data folder, but the distance between each photo is way bigger than it will be from a real plane. On that particular example photos were taken 1 photo per 2-3 seconds. But in real-world scenario frames would appear within the interval no more than 500ms. We also don't have IMU data for the test. For now we have to search for the public data for that in internet. We've tried to record that with Mavic 3 Pro Mini, but failed, cause of the closed system if DJI. \ No newline at end of file diff --git a/_docs/00_problem/restrictions.md b/_docs/00_problem/restrictions.md index 6510b53..8c1e29b 100644 --- a/_docs/00_problem/restrictions.md +++ b/_docs/00_problem/restrictions.md @@ -1,6 +1,6 @@ # Restrictions -> **Last revised**: 2026-04-26 (post Mode B Solution Assessment + user-driven addendum on camera spec & zoom level). +> **Last revised**: 2026-05-01 (post Phase 1 AC/restrictions assessment clarifications). ## UAV & Flight @@ -12,7 +12,7 @@ - **Transit corridor**: ~**50 km × 1 km = 50 km²** strip in/out of the sector. - **Total operational area: up to ~400 km²** of pre-cached satellite imagery per mission. Cache is **persistent across flights** (not redownloaded each mission). Storage budget **~10 GB** for the satellite tile cache; see AC-NEW-3 for flight-data-recorder budget. - Altitude: pre-defined, **≤1 km AGL**. Terrain is assumed flat (operational area is rolling steppe / agricultural land); height differences are negligible. -- Weather: predominantly sunny daytime operations. +- Weather: predominantly sunny daytime operations. Validation must still cover the seasonal/visibility classes that affect visual matching in the operational area: summer crop/field patterns, autumn/winter bare fields, cloud/smoke/haze, snow if missions can occur in winter, and low-texture agricultural repetition. - Sharp turns occur but are the exception, not the rule. Two consecutive photos may share <5% overlap during a turn (see AC-3.2). - **No photo-count cap.** The previously stated "up to 3000 photos per flight" was a legacy operator number from a Mavic-class workflow; it is dropped because (a) it is inconsistent with 8 h × 3 fps, and (b) the system does **not store raw photos at all** (see AC-8.5). Storage is bounded by the tile-cache + FDR caps (~10 GB persistent + 64 GB / flight, AC-NEW-3). @@ -32,7 +32,7 @@ - **Mid-flight tile generation (AC-8.4)**: during the mission the companion computer generates fresh tiles from the navigation camera, orthorectified into the basemap projection, deduplicated against the existing cache, and stored locally. On landing, those new tiles are uploaded back to the Suite Satellite Service for ingestion, so the next mission's cache is refreshed by the previous flight. - **No raw photo storage** (AC-8.5): the tile is the unit of persistence. Raw nav-camera and AI-camera frames are not retained (except a low-rate failure-thumbnail log for forensics). - **Resolution at the cache interface**: 0.5 m/pixel minimum, 0.3 m/pixel ideal (AC-8.1). The architecture is provider-agnostic at the cache boundary; whatever the Suite Satellite Service supplies must meet that bar. -- **Storage tile resolution convention**: cache imagery is specified by source pixel size, not by assuming a universal zoom-to-meter mapping. The cache interface accepts **0.5 m/px minimum, 0.3 m/px ideal** imagery, and every tile manifest records CRS, tile matrix convention, tile dimension, latitude-adjusted meters-per-pixel, capture date, source, and compression. If an XYZ/WebMercator tile pyramid is used, its zoom level is documented as a provider convention rather than treated as proof of physical resolution. The matcher (Component 3) needs ≤~4× scale ratio between the UAV frame (~12 cm/px GSD at 1 km AGL with the 20 MP APS-C camera) and the reference; 0.3–0.5 m/px reference imagery gives a ~2.5–4.2× ratio. Storage budget across the 400 km² operational area remains capped at **10 GB** for the persistent cache and must be validated against the final provider format/compression. **VPR retrieval unit is decoupled from the storage tile** (see AC-8.6 below): VPR chunks are derived from the tile cache at ground-footprint scale (~600–800 m chunks with 40–50 % overlap), independent of the storage tile convention. +- **Storage tile resolution convention**: cache imagery is specified by source pixel size, not by assuming a universal zoom-to-meter mapping. The cache interface accepts **0.5 m/px minimum, 0.3 m/px ideal** imagery, and every tile manifest records CRS, tile matrix convention, tile dimension, latitude-adjusted meters-per-pixel, capture date, source, and compression. If an XYZ/WebMercator tile pyramid is used, its zoom level is documented as a provider convention rather than treated as proof of physical resolution. The matcher (Component 3) needs <=~4x scale ratio between the UAV frame (~12 cm/px GSD at 1 km AGL with the 20 MP APS-C camera) and the reference; 0.3-0.5 m/px reference imagery gives a ~2.5-4.2x ratio. Storage budget across the 400 km² operational area remains capped at **10 GB** for the persistent cache and must be validated against the final provider format/compression. The 10 GB budget includes cache imagery, manifests, overviews, and any precomputed global/local descriptors unless the solution draft explicitly splits a separate descriptor/index budget. **VPR retrieval unit is decoupled from the storage tile** (see AC-8.6 below): VPR chunks are derived from the tile cache at ground-footprint scale (~600-800 m chunks with 40-50 % overlap), independent of the storage tile convention. - **Freshness gates** (AC-8.2 / AC-NEW-6) are enforced at runtime: tiles older than 6 months (active-conflict sectors) or 12 months (stable rear sectors) are rejected or down-confidence-weighted. Tiles generated mid-flight are timestamped with the current flight date and treated as fresh. - **Free public imagery (Sentinel-2 etc.)** is not on the runtime path. If the Suite Satellite Service ever returns Sentinel-class tiles, the cache rejects them as below the 0.5 m/px floor. @@ -46,6 +46,7 @@ ## Sensors & Integration - High-rate **IMU** data is available from the flight controller via MAVLink. +- The provided sample imagery does **not** include synchronized IMU or ground-truth pose. Prototype validation may use public datasets or synthetic IMU injection, but final acceptance claims require synchronized navigation-camera frames, FC IMU/attitude/airspeed/altitude, emitted MAVLink messages, and ground-truth trajectory from a representative flight or replay rig. - The system communicates with the flight controller via MAVLink. Telemetry plumbing uses **MAVSDK**; the `GPS_INPUT` injection path is implemented via **pymavlink**, since MAVSDK does not expose a native `GPS_INPUT` API. - **Autopilot target: ArduPilot only** (with `GPS1_TYPE=14` for MAVLink GPS injection). PX4 is out of scope for the build; if it ever returns to scope it will use `VISION_POSITION_ESTIMATE`, not `GPS_INPUT`. (See `_docs/00_research/00_ac_assessment.md` Q-1.) - The system outputs WGS84 GPS coordinates to the flight controller as a replacement for the real GPS module (MAVLink GPS_INPUT, AC-4.3). diff --git a/_docs/00_research/00_ac_assessment.md b/_docs/00_research/00_ac_assessment.md new file mode 100644 index 0000000..6269c1f --- /dev/null +++ b/_docs/00_research/00_ac_assessment.md @@ -0,0 +1,54 @@ +# Acceptance Criteria Assessment + +Accessed: 2026-05-01. Rerun after user-approved clarifications: 2026-05-01. + +## Research Scope + +- **Output class**: Technical-component selection support. +- **Novelty sensitivity**: High for VPR, embedded AI, and autopilot integration; source preference is current papers and official docs. +- **Boundary**: Fixed-wing UAV, nadir navigation camera, ArduPilot Plane, Jetson Orin Nano Super, offline Azaion Suite Satellite Service cache, eastern/southern Ukraine terrain. + +## Acceptance Criteria + +| Criterion | Current Values | Researched Values / Evidence | Cost / Timeline Impact | Status | +|-----------|----------------|------------------------------|------------------------|--------| +| AC-1.1 / AC-1.2 frame-center accuracy | <=50 m for >=80%, <=20 m for >=50% in normal segments | Plausible only with periodic satellite anchoring plus VO/IMU propagation. Aerial VPR papers show the mechanism is viable but sensitive to weather, scale, repetition, and tile overlap. | High validation cost. | Keep, high-risk | +| AC-1.3 drift | VO-only <100 m, IMU-fused <50 m between anchors, anchor age reported | Updated AC now requires `last_satellite_anchor_age_ms`, binned validation, and degraded covariance after a solution-defined max anchor age. | Medium. | Updated | +| AC-1.4 confidence | 95% covariance ellipse + source label | `GPS_INPUT` supports accuracy fields; source labels must be carried in telemetry/FDR because `GPS_INPUT` has no semantic label field. | Medium. | Keep | +| AC-2.1 registration | VO >95%; satellite anchoring measured separately | Split is correct: VO success is not the same as cross-domain satellite anchor success. | Medium-high. | Updated | +| AC-2.2 reprojection | <1 px VO, <2.5 px satellite anchor | Reasonable image-space gates, with coordinate error still dependent on calibration, orthorectification, and satellite georegistration. | Medium. | Keep | +| AC-3.x resilience | Outliers, sharp turns, disconnected segments, blackout | Technically feasible only through mode switching: VO failure triggers VPR/relocalization, blackout triggers IMU-only propagation with honest covariance growth. | High test cost. | Keep | +| AC-4.1 latency | <400 ms p95, <=10% frame drops, heavy VPR conditional | Aerial VPR survey reports some re-ranking paths too slow for steady-state use; solution must keep global VPR off the per-frame hot path. | High optimization cost. | Updated | +| AC-4.2 memory | <8 GB shared | Feasible if descriptors are compressed/pruned and indices are memory-mapped or loaded selectively. | Medium-high. | Keep | +| AC-4.3 MAVLink | v1 GPS_INPUT only via pymavlink | ArduPilot docs require `GPS1_TYPE=14`; MAVLink defines required lat/lon, velocity, fix, and accuracy fields. MAVSDK should remain telemetry-oriented. | Medium. | Keep | +| AC-5.2 failsafe | >3 s no estimate triggers fallback, Plane SITL verified | Copter docs are reference only. Plane-specific production parameters must be verified in SITL. | Medium. | Updated | +| AC-7 object localization | Level-flight AI-camera object GPS | Realistic under level-flight clause; maneuvering estimates must publish conservative bound. | Medium. | Keep | +| AC-8.x satellite cache | 0.3-0.5 m/px, freshness, offline descriptors, VPR chunks | Resolution is feasible through commercial/service imagery. Storage must count descriptors unless separately budgeted. | Medium-high. | Updated | +| AC-NEW-1 / 2 startup and spoofing | <30 s first fix, <3 s promotion | Feasible only with prebuilt engines, warmed indices, and verified Plane GPS-health triggers. | Medium-high. | Keep with SITL gate | +| AC-NEW-3 FDR | <=64 GB per flight, no raw frames | Feasible with segment files and rollover. | Medium. | Keep | +| AC-NEW-4 / 7 safety budgets | False-position and cache-poisoning probabilities | Appropriate safety gates, but require Monte Carlo and representative flight/replay data. | High. | Keep | +| AC-NEW-5 environment | -20 C to +50 C, 25 W for 8 h | NVIDIA confirms 25 W mode; thermal design must prevent throttling. | Medium-high. | Keep | + +## Restrictions Assessment + +| Restriction | Current Values | Researched Values / Evidence | Cost / Timeline Impact | Status | +|-------------|----------------|------------------------------|------------------------|--------| +| Camera source of truth | `restrictions.md` pins ADTi 20MP ~5472 x 3648 | User confirmed `restrictions.md` is authoritative. Lens/FOV remains a design parameter. | Medium during module selection. | Updated | +| Fixed nadir camera | No gimbal stabilization | Good for orthorectification; turn/tilt requires attitude compensation and failure detection. | Medium. | Keep | +| Terrain/weather | Flat steppe/agricultural, seasonal classes included | Repetitive fields and seasonal changes are VPR hazards; validation must include those classes. | High validation cost. | Updated | +| Satellite Service boundary | Offline consumer of Suite Satellite Service | Strong separation; cache manifest and ingest-voting contract are required. | Medium. | Keep | +| 10 GB cache | Includes imagery, manifests, overviews, descriptors unless split | Plausible at 0.5 m/px with compression; 0.3 m/px plus descriptors may exceed unless pruned. | Medium. | Updated | +| Jetson Orin Nano Super | 67 TOPS INT8, 8 GB, 25 W | Official specs support the restriction; thermal throttling remains a risk. | Medium-high. | Keep | +| Test data gap | Sample imagery lacks IMU/ground truth | Public datasets help prototype, but final acceptance needs synchronized representative data. | High. | Updated | + +## Key Findings + +1. Use a hybrid estimator: VO/IMU for frame propagation, satellite/VPR anchors for absolute correction, ESKF covariance as the safety gate. +2. Do not run heavy VPR/re-ranking every frame; invoke it on cold start, VO failure, covariance growth, sharp turns, and disconnected segments. +3. Avoid GPL libraries in production dependencies unless the project accepts GPL obligations. GPL VIO/SLAM tools should be benchmarks or references, not selected production components. +4. The cache must be designed as imagery + metadata + descriptor index, not just raster tiles. +5. ArduPilot Plane SITL and representative camera+IMU data are blocking validation dependencies, but not blockers for solution drafting. + +## Sources + +See `_docs/00_research/01_source_registry.md` for the detailed source list. diff --git a/_docs/00_research/00_question_decomposition.md b/_docs/00_research/00_question_decomposition.md new file mode 100644 index 0000000..9e3a8fe --- /dev/null +++ b/_docs/00_research/00_question_decomposition.md @@ -0,0 +1,145 @@ +# Question Decomposition + +## Classification + +- **Original question**: Design a GPS-denied onboard localization system for a fixed-wing UAV using a nadir camera, IMU, preloaded satellite imagery, and ArduPilot `GPS_INPUT`. +- **Active mode**: Mode A Phase 2, initial solution research. +- **Research output class**: Technical-component selection. +- **Question type**: Decision support with knowledge organization. +- **Timeliness sensitivity**: High for VPR, embedded AI inference, and MAVLink/ArduPilot integration; medium for geometry and filtering fundamentals. + +## Research Boundary + +| Dimension | Boundary | +|-----------|----------| +| Population | Fixed-wing UAV missions; not multirotor hover workflows. | +| Geography | Eastern/southern Ukraine operational areas east/left of the Dnipro River. | +| Timeframe | Current implementation target with 2024-2026 component evidence where possible. | +| Level | Onboard real-time production system, not offline post-processing. | +| Operating context | 8 h flight, 60 km/h, <=1 km AGL, 3 fps nav camera, Jetson Orin Nano Super, GPS denied/spoofed. | +| Required interfaces | Offline Satellite Service cache in; MAVLink `GPS_INPUT`, QGC telemetry, FDR records, and object-coordinate API out. | +| Non-functional envelope | <400 ms p95, <8 GB shared memory, 10 GB persistent cache target, 64 GB FDR cap, safety covariance and false-position budgets. | + +## Project Constraint Matrix Summary + +| Constraint Area | Binding Constraint | +|-----------------|-------------------| +| Camera | ADTi 20MP 20L V1, APS-C, ~5472 x 3648, fixed nadir, no gimbal stabilization. | +| Sensors | FC IMU/attitude/airspeed/altitude available over MAVLink; sample data lacks synchronized IMU. | +| Reference imagery | Offline cache only, 0.5 m/px minimum and 0.3 m/px ideal, freshness gates, no in-flight provider fetch. | +| Runtime | Jetson Orin Nano Super, CUDA/TensorRT available, 25 W thermal envelope. | +| Autopilot | ArduPilot only, v1 emits `GPS_INPUT` only; ODOMETRY intentionally disabled. | +| Storage | No raw frame retention; tiles + FDR only. Descriptor/index storage must be budgeted. | +| Safety | Reject weak anchors, never under-report covariance, fail/degrade honestly in blackout and spoofing. | +| Hard disqualifiers | Per-frame heavy VPR without profiling, runtime dependence on external network, stale-tile confident anchors, GPL production dependency unless licensing is accepted. | + +## Perspectives + +| Perspective | Focus | +|-------------|-------| +| Operator / mission user | Does the system keep the UAV navigable and report honest confidence under spoofing/blackout? | +| Embedded implementer | Can the pipeline fit <400 ms p95 and <8 GB on Jetson with maintainable interfaces? | +| Safety reviewer | Are false-position and cache-poisoning paths gated before they can steer the FC or poison future caches? | +| Field practitioner | Will seasonal agricultural repetition, turns, haze/smoke, and stale imagery break the architecture? | +| Contrarian | Which attractive libraries or SOTA models fail because of licensing, memory, latency, or input mismatch? | + +## Sub-Questions And Query Variants + +1. What architecture bounds drift while GPS is denied? + - fixed-wing UAV GPS-denied satellite image matching visual odometry + - visual odometry satellite imagery accumulated error fixed wing UAV + - monocular VIO aerial navigation scale ambiguity satellite anchor + - GPS spoofed UAV visual inertial navigation covariance failover + +2. Which VO/VIO approach fits one nadir camera + IMU? + - OpenVINS monocular visual inertial odometry Jetson + - ORB-SLAM3 monocular inertial Jetson UAV limitations + - VINS-Fusion fixed wing monocular IMU outdoor aerial + - homography visual odometry nadir UAV IMU fusion + +3. Which satellite retrieval and matching approach fits offline cache + <400 ms? + - aerial visual place recognition survey DINOv2 FAISS + - DINOv2 VLAD aerial VPR embedded memory + - LightGlue SuperPoint DISK ALIKED TensorRT Jetson + - cross-view UAV satellite matching failure modes farmland + +4. How should the estimator and safety modes work? + - ESKF visual inertial GPS denied UAV covariance + - GPS_INPUT horiz_accuracy covariance external GPS ArduPilot + - visual blackout IMU dead reckoning UAV covariance growth + - false position rejection Mahalanobis gate visual localization + +5. What cache format and data contract fit the onboard/Satellite Service boundary? + - COG PMTiles MBTiles offline raster cache embedded + - satellite tile descriptor index storage FAISS PMTiles + - cloud optimized geotiff local update limitations + - PMTiles read only update PostgreSQL/PostGIS-backed raster cache + +6. How should MAVLink output integrate with ArduPilot Plane? + - ArduPilot GPS_INPUT GPS1_TYPE 14 Plane SITL + - pymavlink gps_input_send external GPS example + - MAVSDK GPS_INPUT support raw MAVLink + - ArduPilot EKF GPS glitch spoof failsafe Plane parameters + +7. What validation datasets and tests are needed? + - AerialVL UAV satellite visual localization dataset + - VPAir aerial visual place recognition dataset + - EuRoC MAV visual inertial odometry dataset + - ArduPilot Plane SITL fake GPS spoofing simulation + +## Component Option Search Plan + +| Component Area | Option Families / Candidates | Evidence Needed | +|----------------|------------------------------|-----------------| +| Camera calibration and geometry | OpenCV calibration/homography; custom NumPy geometry; ROS camera pipeline | Official API for intrinsics, distortion, homography, RANSAC; permissive licensing; Jetson compatibility. | +| VO / VIO propagation | OpenVINS, ORB-SLAM3, VINS-Fusion, custom homography+IMU ESKF | Exact monocular+IMU input fit, output pose/covariance, licensing, runtime, initialization behavior. | +| VPR global retrieval | DINOv2-VLAD/AnyLoc, MixVPR/SALAD/SelaVPR, classical NetVLAD/BoW | Aerial benchmark evidence, descriptor size, offline index fit, embedded feasibility. | +| Local cross-domain matching | LightGlue + DISK/ALIKED, SuperPoint+LightGlue, LoFTR/XFeat, SIFT/ORB baseline | Inputs/outputs, match coordinates, license, runtime knobs, TensorRT/Jetson feasibility. | +| Vector index | FAISS CPU/GPU, PostgreSQL/pgvector metadata-assisted search, Annoy/HNSWLIB | Top-K retrieval, saved index, memory/compression knobs, ARM/Jetson feasibility. | +| Estimator | Custom ESKF, factor graph, robot_localization | Covariance output, mode labels, Mahalanobis gates, source-specific update control. | +| Cache/storage | COG, PostgreSQL/PostGIS manifest, PMTiles, MBTiles, raw tile folders | Offline read/update behavior, storage efficiency, metadata/manifest support. | +| MAVLink integration | pymavlink, MAVSDK, MAVProxy bridge | `GPS_INPUT` support, ArduPilot `GPS1_TYPE=14`, telemetry subscriptions, QGC status. | +| FDR | PostgreSQL event index, Parquet export, CBOR segment files | Streaming writes, rollover, compact typed records, replayability. | + +## Completeness Audit + +- **Cost/resources**: covered by Jetson, cache, thermal, and descriptor storage constraints. +- **Legal/licensing**: covered; GPL VIO/SLAM tools are not selected for production. +- **Dependencies**: Satellite Service cache contract, ArduPilot Plane SITL, and synchronized validation data are explicit dependencies. +- **Operating environment**: fixed-wing, altitude, terrain, seasonal/visibility classes, and blackout cases covered. +- **Failure modes**: VO failure, stale tiles, spoofing, blackout, thermal throttling, false anchors, cache poisoning covered. +- **Practitioner concerns**: real-time embedded performance and dataset mismatch covered through survey and benchmark sources. +- **Change over time**: DINOv2/VPR models and Jetson/TensorRT assumptions require version-pinned profiling during implementation. + +## Mode B Round 2 Addendum — User-Requested Technology Check + +### Research Output Class + +Technical-component selection. The addendum verifies two implementation choices before autodev proceeds to planning: + +1. Whether OpenVINS should replace the custom OpenCV-based VO/ESKF direction. +2. Whether DINOv2-VLAD + ALIKED/LightGlue is still the right satellite retrieval and anchor-verification stack. + +### Boundary Clarification + +"Custom OpenCV" is treated as OpenCV for calibration, undistortion, feature geometry, homography/RANSAC, and MRE measurement, plus a project-owned ESKF/mode machine. It is not treated as a naive OpenCV-only replacement for VIO. + +### Additional Query Variants Executed + +- OpenVINS GPL-3 license MSCKF visual inertial odometry documentation monocular IMU 2026 +- OpenVINS visual inertial odometry GPS denied UAV MSCKF limitations monocular high altitude nadir camera +- why not use OpenVINS production GPL ROS dependency visual inertial odometry limitations +- OpenCV license BSD 3-Clause camera calibration findHomography RANSAC documentation 4.x +- custom visual odometry OpenCV homography IMU EKF fixed wing UAV satellite imagery GPS denied 2024 +- DINOv2 VLAD AnyLoc visual place recognition aerial satellite retrieval benchmark 2024 2025 +- DINOv2 VLAD limitations visual place recognition storage compute AnyLoc limitations +- DINOv2 TensorRT Jetson performance issue embedding accuracy visual place recognition +- ALIKED LightGlue license local feature matching aerial image registration 2024 2025 +- ALIKED LightGlue ONNX TensorRT Jetson performance benchmark local feature matching +- aerial visual place recognition survey 2024 runtime memory re-ranking SuperGlue LightGlue satellite UAV retrieval + +### Addendum Conclusion + +OpenVINS is better than a pure custom OpenCV-only VIO implementation, but the production architecture should keep OpenCV as the utility layer and keep the project-owned ESKF/mode machine as the shipped estimator. OpenVINS becomes a mandatory benchmark/reference because it does not own the satellite anchor, spoofing/blackout, source-label, cache-write, and MAVLink semantics required by the acceptance criteria, and GPLv3 remains a production dependency blocker. + +DINOv2-VLAD + CPU-first FAISS + ALIKED/LightGlue remains the preferred anchor stack, with two non-negotiable constraints: retrieval is trigger-based rather than per-frame, and TensorRT/ONNX optimizations are accepted only after descriptor-fidelity and Jetson latency tests. diff --git a/_docs/00_research/01_source_registry.md b/_docs/00_research/01_source_registry.md new file mode 100644 index 0000000..dd2de65 --- /dev/null +++ b/_docs/00_research/01_source_registry.md @@ -0,0 +1,419 @@ +# Source Registry + +## Source #1 +- **Title**: Visual Odometry in GPS-Denied Zones for Fixed-Wing UAV with Reduced Accumulative Error Based on Satellite Imagery +- **Link**: https://www.mdpi.com/2076-3417/14/16/7420 +- **Tier**: L1 +- **Publication Date**: 2024 +- **Timeliness Status**: Currently valid +- **Target Audience**: UAV visual localization researchers/implementers +- **Research Boundary Match**: Full match +- **Summary**: Demonstrates fixed-wing high-altitude monocular VO corrected by satellite imagery; highlights scale ambiguity and accumulated drift. +- **Related Sub-question**: Architecture / drift bounding + +## Source #2 +- **Title**: Visual place recognition for aerial imagery: A survey +- **Link**: https://arxiv.org/abs/2406.00885 +- **Tier**: L1 +- **Publication Date**: 2024 +- **Timeliness Status**: Currently valid +- **Target Audience**: Aerial VPR researchers/implementers +- **Research Boundary Match**: Full match +- **Summary**: Reviews aerial VPR, retrieval/re-ranking, overlap/scale effects, memory/runtime issues, and georeference recall. +- **Related Sub-question**: VPR / validation + +## Source #3 +- **Title**: OpenVINS documentation +- **Link**: https://docs.openvins.com/ +- **Tier**: L1 +- **Publication Date**: 2023 latest noted release +- **Timeliness Status**: Needs verification before implementation +- **Target Audience**: VIO researchers/implementers +- **Research Boundary Match**: Partial overlap +- **Summary**: OpenVINS is an EKF/MSCKF visual-inertial estimator supporting monocular tracking, calibration, evaluation, and covariance-aware estimation; GPL-3 license. +- **Related Sub-question**: VO/VIO + +## Source #4 +- **Title**: ORB-SLAM3 README +- **Link**: https://raw.githubusercontent.com/UZ-SLAMLab/ORB_SLAM3/master/README.md +- **Tier**: L1 +- **Publication Date**: 2021 README, still repository source +- **Timeliness Status**: Needs verification before implementation +- **Target Audience**: SLAM implementers +- **Research Boundary Match**: Partial overlap +- **Summary**: ORB-SLAM3 supports monocular visual-inertial SLAM and multi-map operation, requires calibration, and is GPLv3. +- **Related Sub-question**: VO/VIO alternatives + +## Source #5 +- **Title**: OpenCV 4.x documentation via Context7 +- **Link**: https://docs.opencv.org/4.x/ +- **Tier**: L1 +- **Publication Date**: Current docs, accessed 2026-05-01 +- **Timeliness Status**: Currently valid +- **Target Audience**: Computer vision implementers +- **Research Boundary Match**: Full match for utility layer +- **Summary**: Documents camera calibration, undistortion, and `findHomography` with RANSAC for robust geometry. +- **Related Sub-question**: Calibration / geometry + +## Source #6 +- **Title**: LightGlue README and Context7 docs +- **Link**: https://raw.githubusercontent.com/cvg/LightGlue/main/README.md +- **Tier**: L1 +- **Publication Date**: Current repository, accessed 2026-05-01 +- **Timeliness Status**: Currently valid +- **Target Audience**: Feature-matching implementers +- **Research Boundary Match**: Full match for local matching +- **Summary**: LightGlue accepts local keypoints/descriptors and returns matched coordinates/scores; supports SuperPoint, DISK, ALIKED, SIFT, adaptive pruning, CUDA, and Apache-2 for code/weights while SuperPoint has restrictive licensing. +- **Related Sub-question**: Local matching + +## Source #7 +- **Title**: AnyLoc README +- **Link**: https://github.com/AnyLoc/AnyLoc +- **Tier**: L1 +- **Publication Date**: 2023 repository, accessed 2026-05-01 +- **Timeliness Status**: Needs profiling verification +- **Target Audience**: VPR implementers +- **Research Boundary Match**: Partial overlap +- **Summary**: Provides DINOv2 + VLAD API examples and notes substantial storage/compute requirements for full experiments. +- **Related Sub-question**: VPR descriptors + +## Source #8 +- **Title**: DINOv2 repository +- **Link**: https://github.com/facebookresearch/dinov2 +- **Tier**: L1 +- **Publication Date**: 2023 repository, accessed 2026-05-01 +- **Timeliness Status**: Currently valid +- **Target Audience**: Vision model implementers +- **Research Boundary Match**: Partial overlap +- **Summary**: Meta's DINOv2 implementation and models, Apache-2.0 / CC-BY-4.0 license notices. +- **Related Sub-question**: VPR descriptors + +## Source #9 +- **Title**: FAISS documentation and Context7 docs +- **Link**: https://faiss.ai/index.html +- **Tier**: L1 +- **Publication Date**: Current docs, accessed 2026-05-01 +- **Timeliness Status**: Currently valid +- **Target Audience**: Vector search implementers +- **Research Boundary Match**: Full match +- **Summary**: FAISS supports dense vector search, top-k retrieval, CPU/GPU indexes, product quantization, and save/load APIs; GPU indexes must be converted to CPU before saving. +- **Related Sub-question**: Descriptor retrieval + +## Source #10 +- **Title**: MAVSDK documentation via Context7 +- **Link**: https://github.com/mavlink/mavsdk +- **Tier**: L1 +- **Publication Date**: Current docs, accessed 2026-05-01 +- **Timeliness Status**: Currently valid +- **Target Audience**: MAVLink application implementers +- **Research Boundary Match**: Partial overlap +- **Summary**: MAVSDK provides telemetry APIs including raw GPS, GPS info, status text, position/velocity, and odometry subscriptions; `GPS_INPUT` emission should use raw MAVLink/pymavlink for this project. +- **Related Sub-question**: MAVLink integration + +## Source #11 +- **Title**: ArduPilot MAVProxy GPSInput +- **Link**: https://ardupilot.org/mavproxy/docs/modules/GPSInput.html +- **Tier**: L1 +- **Publication Date**: Current docs, accessed 2026-05-01 +- **Timeliness Status**: Currently valid +- **Target Audience**: ArduPilot integrators +- **Research Boundary Match**: Full match +- **Summary**: External GPS input requires `GPS1_TYPE=14` and accepts MAVLink `GPS_INPUT` fields including WGS84 lat/lon, velocity, fix type, and accuracy. +- **Related Sub-question**: MAVLink output + +## Source #12 +- **Title**: MAVLink common message spec: GPS_INPUT +- **Link**: https://mavlink.io/en/messages/common.html#GPS_INPUT +- **Tier**: L1 +- **Publication Date**: Current spec, accessed 2026-05-01 +- **Timeliness Status**: Currently valid +- **Target Audience**: MAVLink implementers +- **Research Boundary Match**: Full match +- **Summary**: Defines `GPS_INPUT` fields, fix type semantics, `horiz_accuracy`, and ignore flags. +- **Related Sub-question**: MAVLink output / confidence + +## Source #13 +- **Title**: ArduPilot GPS failsafe and glitch protection +- **Link**: https://ardupilot.org/copter/docs/gps-failsafe-glitch-protection.html +- **Tier**: L1 +- **Publication Date**: Current docs, accessed 2026-05-01 +- **Timeliness Status**: Reference only for Plane +- **Target Audience**: ArduPilot operators +- **Research Boundary Match**: Partial overlap +- **Summary**: Documents GPS glitch protection and notes inertial-only position degrades quickly; Copter-specific defaults must not be assumed for Plane. +- **Related Sub-question**: Failsafe / spoofing + +## Source #14 +- **Title**: ArduPilot EKF failsafe +- **Link**: https://ardupilot.org/copter/docs/ekf-inav-failsafe.html +- **Tier**: L1 +- **Publication Date**: Current docs, accessed 2026-05-01 +- **Timeliness Status**: Reference only for Plane +- **Target Audience**: ArduPilot operators +- **Research Boundary Match**: Partial overlap +- **Summary**: Explains EKF variance failsafe behavior and why spoof/glitch tests must be parameterized. +- **Related Sub-question**: Failsafe / spoofing + +## Source #15 +- **Title**: Jetson Orin Nano Super Developer Kit +- **Link**: https://www.nvidia.com/en-us/autonomous-machines/embedded-systems/jetson-orin/nano-super-developer-kit/ +- **Tier**: L1 +- **Publication Date**: Current page, accessed 2026-05-01 +- **Timeliness Status**: Currently valid +- **Target Audience**: Embedded AI implementers +- **Research Boundary Match**: Full match +- **Summary**: Confirms 67 INT8 TOPS, 8 GB LPDDR5, 102 GB/s, and 7-25 W power range. +- **Related Sub-question**: Runtime + +## Source #16 +- **Title**: NVIDIA JetPack 6.2 Super Mode blog +- **Link**: https://developer.nvidia.com/blog/nvidia-jetpack-6-2-brings-super-mode-to-nvidia-jetson-orin-nano-and-jetson-orin-nx-modules/ +- **Tier**: L2 +- **Publication Date**: 2024 +- **Timeliness Status**: Currently valid +- **Target Audience**: Jetson developers +- **Research Boundary Match**: Full match +- **Summary**: Explains 25 W and MAXN Super modes and warns thermal design must accommodate the new power modes or throttling occurs. +- **Related Sub-question**: Runtime / thermal + +## Source #17 +- **Title**: PMTiles Concepts +- **Link**: https://docs.protomaps.com/pmtiles/ +- **Tier**: L1 +- **Publication Date**: Current docs, accessed 2026-05-01 +- **Timeliness Status**: Currently valid +- **Target Audience**: Geospatial storage implementers +- **Research Boundary Match**: Partial overlap +- **Summary**: PMTiles is single-file tiled archive, efficient for reads, but read-only and not update-in-place. +- **Related Sub-question**: Cache storage + +## Source #18 +- **Title**: GDAL COG driver +- **Link**: https://gdal.org/en/stable/drivers/raster/cog.html +- **Tier**: L1 +- **Publication Date**: Current docs, accessed 2026-05-01 +- **Timeliness Status**: Currently valid +- **Target Audience**: Geospatial raster implementers +- **Research Boundary Match**: Full match +- **Summary**: Defines COG creation options for tiled, compressed, overview-enabled GeoTIFFs. +- **Related Sub-question**: Cache storage + +## Source #19 +- **Title**: AerialVL dataset +- **Link**: https://github.com/hmf21/AerialVL +- **Tier**: L1 +- **Publication Date**: 2024 +- **Timeliness Status**: Currently valid +- **Target Audience**: Aerial visual localization researchers +- **Research Boundary Match**: Partial overlap +- **Summary**: Public aerial localization benchmark with UAV sequences, reference maps, and geo-referenced evaluation data. +- **Related Sub-question**: Validation + +## Source #20 +- **Title**: EuRoC MAV Dataset +- **Link**: http://projects.asl.ethz.ch/datasets/euroc-mav/ +- **Tier**: L1 +- **Publication Date**: 2016 +- **Timeliness Status**: Stable benchmark +- **Target Audience**: VIO researchers +- **Research Boundary Match**: Partial overlap +- **Summary**: Stereo camera + IMU + ground truth benchmark useful for VIO sanity tests but not representative of high-altitude nadir fixed-wing imagery. +- **Related Sub-question**: Validation + +## Source #21 +- **Title**: NVIDIA/TensorRT issue: DINOv2 TensorRT performance/precision on Jetson +- **Link**: https://github.com/NVIDIA/TensorRT/issues/4348 +- **Tier**: L4 +- **Publication Date**: 2024 +- **Timeliness Status**: Needs verification +- **Target Audience**: Jetson/TensorRT implementers +- **Research Boundary Match**: Partial overlap +- **Summary**: Reports limited mixed-precision gains for DINOv2-S on Jetson/RTX, suggesting DINOv2 optimization is not automatically beneficial. +- **Related Sub-question**: Mode B performance risk + +## Source #22 +- **Title**: NVIDIA Developer Forum: DINOv2 TensorRT model performance issue +- **Link**: https://forums.developer.nvidia.com/t/dinov2-tensorrt-model-performance-issue/312251 +- **Tier**: L4 +- **Publication Date**: 2024 +- **Timeliness Status**: Needs verification +- **Target Audience**: Jetson/TensorRT implementers +- **Research Boundary Match**: Partial overlap +- **Summary**: Reports DINOv2 embedding distance changes after TensorRT conversion on Jetson Orin Nano; requires embedding-fidelity validation before relying on TensorRT descriptors. +- **Related Sub-question**: Mode B performance/quality risk + +## Source #23 +- **Title**: LightGlue license issue discussions +- **Link**: https://github.com/cvg/LightGlue/issues/120 +- **Tier**: L4 +- **Publication Date**: 2024 +- **Timeliness Status**: Currently relevant +- **Target Audience**: Feature-matching implementers +- **Research Boundary Match**: Full match for licensing +- **Summary**: Community discussion highlights restrictive SuperPoint licensing inside the LightGlue ecosystem and supports avoiding SuperPoint as default production extractor. +- **Related Sub-question**: Mode B licensing risk + +## Source #24 +- **Title**: ArduPilot issue: GPS_INPUT velocity ignore flag pitfall +- **Link**: https://github.com/ArduPilot/ardupilot/issues/19633 +- **Tier**: L4 +- **Publication Date**: 2021 +- **Timeliness Status**: Needs SITL verification +- **Target Audience**: ArduPilot integrators +- **Research Boundary Match**: Full match for GPS_INPUT caution +- **Summary**: Reports EKF3 may use zero velocity when `GPS_INPUT_IGNORE_FLAG_VEL_HORIZ` is set, so velocity-source parameters must be tested rather than relying only on ignore flags. +- **Related Sub-question**: Mode B MAVLink pitfall + +## Source #25 +- **Title**: FAISS install documentation +- **Link**: https://github.com/facebookresearch/faiss/blob/main/INSTALL.md +- **Tier**: L1 +- **Publication Date**: Current docs, accessed 2026-05-01 +- **Timeliness Status**: Currently valid +- **Target Audience**: Vector search implementers +- **Research Boundary Match**: Full match +- **Summary**: FAISS CPU conda package supports aarch64, while GPU package availability is x86-64 focused; Jetson design should assume CPU FAISS unless a custom build is proven. +- **Related Sub-question**: Mode B FAISS deployment + +## Source #26 +- **Title**: GNSS-denied geolocalization of UAVs by visual matching of onboard camera images with orthophotos +- **Link**: https://ar5iv.labs.arxiv.org/html/2103.14381 +- **Tier**: L1 +- **Publication Date**: 2021 +- **Timeliness Status**: Stable mechanism reference +- **Target Audience**: UAV visual geolocalization researchers +- **Research Boundary Match**: Partial overlap +- **Summary**: Demonstrates visual matching with orthophotos and Monte Carlo/local planarity ideas; supports using orthorectified reference maps but does not cover all adversarial visual attacks. +- **Related Sub-question**: Mode B alternative / security limits + +## Source #27 +- **Title**: OpenVINS LICENSE +- **Link**: https://github.com/rpng/open_vins/blob/master/LICENSE +- **Tier**: L1 +- **Publication Date**: Current repository, accessed 2026-05-01 +- **Timeliness Status**: Currently valid +- **Target Audience**: VIO implementers / product owners +- **Research Boundary Match**: Full match for licensing +- **Summary**: OpenVINS is GPLv3-licensed; this is a production dependency constraint, not a technical capability limitation. +- **Related Sub-question**: Mode B round 2 — OpenVINS vs custom production estimator + +## Source #28 +- **Title**: OpenVINS documentation and Context7 lookup +- **Link**: https://docs.openvins.com/index.html +- **Tier**: L1 +- **Publication Date**: Current docs, accessed 2026-05-01 +- **Timeliness Status**: Currently valid +- **Target Audience**: VIO implementers +- **Research Boundary Match**: Partial overlap +- **Summary**: OpenVINS is a strong EKF/MSCKF VIO system for monocular camera + IMU reference runs, with calibration and covariance-aware state estimation, but it does not own the project-specific satellite anchor, GPS_INPUT, source-label, spoofing, blackout, and cache-poisoning state machine. +- **Related Sub-question**: Mode B round 2 — OpenVINS vs custom production estimator + +## Source #29 +- **Title**: OpenCV 4.x calibration/homography documentation and Context7 lookup +- **Link**: https://docs.opencv.org/4.x/ +- **Tier**: L1 +- **Publication Date**: Current docs, accessed 2026-05-01 +- **Timeliness Status**: Currently valid +- **Target Audience**: Computer vision implementers +- **Research Boundary Match**: Full match for geometry utility layer +- **Summary**: OpenCV 4.x provides calibration, undistortion, homography estimation, RANSAC/USAC robust estimation, and reprojection-error primitives under a permissive license; it is a utility layer rather than a complete GPS-denied estimator. +- **Related Sub-question**: Mode B round 2 — custom OpenCV boundary + +## Source #30 +- **Title**: AnyLoc: Towards Universal Visual Place Recognition +- **Link**: https://arxiv.org/html/2308.00688 +- **Tier**: L1 +- **Publication Date**: 2023; ICRA 2024 +- **Timeliness Status**: Currently valid, profiling required before deployment +- **Target Audience**: VPR implementers +- **Research Boundary Match**: Partial overlap +- **Summary**: AnyLoc combines DINOv2 features with VLAD aggregation for broad VPR, including aerial data, and supports the selected DINOv2-VLAD retrieval family while leaving runtime/storage tuning as a deployment gate. +- **Related Sub-question**: Mode B round 2 — satellite retrieval + +## Source #31 +- **Title**: ALIKED-LightGlue-ONNX and LightGlue ONNX/TensorRT deployment reports +- **Link**: https://github.com/ikeboo/ALIKED-LightGlue-ONNX +- **Tier**: L2 +- **Publication Date**: Current repository, accessed 2026-05-01 +- **Timeliness Status**: Promising but needs Jetson verification +- **Target Audience**: Local feature matching implementers +- **Research Boundary Match**: Partial overlap +- **Summary**: ONNX/optimized variants show a credible deployment path for ALIKED + LightGlue, but public evidence is not enough to assume Jetson Orin Nano p95 latency without project profiling. +- **Related Sub-question**: Mode B round 2 — local matcher deployability + +## Source #32 +- **Title**: Visual place recognition for aerial imagery: A survey +- **Link**: https://arxiv.org/abs/2406.00885 +- **Tier**: L1 +- **Publication Date**: 2024 +- **Timeliness Status**: Currently valid +- **Target Audience**: Aerial VPR researchers / implementers +- **Research Boundary Match**: Full match +- **Summary**: Aerial VPR performance depends materially on tile scale, overlap, weather, repetitive patterns, and re-ranking cost; this supports overlapped VPR chunks, dynamic top-K, and conditional local verification. +- **Related Sub-question**: Mode B round 2 — satellite retrieval and anchor verification + +## Source #33 +- **Title**: BASALT repository and documentation +- **Link**: https://github.com/VladyslavUsenko/basalt +- **Tier**: L1 +- **Publication Date**: Current repository, accessed 2026-05-01 +- **Timeliness Status**: Currently valid +- **Target Audience**: VIO implementers +- **Research Boundary Match**: Partial overlap +- **Summary**: BASALT provides visual-inertial odometry and mapping, camera/IMU calibration tools, EuRoC/TUM VI support, and a BSD-style production-friendly licensing path. +- **Related Sub-question**: Mode B round 3 — Kimera vs BASALT vs OpenVINS + +## Source #34 +- **Title**: HybVIO: Pushing the Limits of Real-time Visual-inertial Odometry +- **Link**: https://arxiv.org/pdf/2106.11857 +- **Tier**: L1 +- **Publication Date**: 2021 +- **Timeliness Status**: Stable benchmark reference +- **Target Audience**: VIO researchers / embedded implementers +- **Research Boundary Match**: Partial overlap +- **Summary**: Reports EuRoC RMS ATE comparisons including BASALT mean about 0.051 m online stereo and Kimera mean about 0.12 m, plus notes that optimization-based methods often lack direct uncertainty quantification compared with filters. +- **Related Sub-question**: Mode B round 3 — VIO error and confidence comparison + +## Source #35 +- **Title**: OpenVINS issue #402 — up-to-date ATE and RTE metrics +- **Link**: https://github.com/rpng/open_vins/issues/402 +- **Tier**: L4 +- **Publication Date**: 2024 +- **Timeliness Status**: Community benchmark, verify in our replay harness +- **Target Audience**: VIO implementers +- **Research Boundary Match**: Partial overlap +- **Summary**: Community EuRoC comparison reports BASALT average ATE about 0.072 m with 100% completion, and OpenVINS average ATE about 0.091 m with about 88.55% completion and a divergence on one hard sequence. +- **Related Sub-question**: Mode B round 3 — BASALT vs OpenVINS error/completion + +## Source #36 +- **Title**: Kimera-VIO mono-inertial parameter issues +- **Link**: https://github.com/MIT-SPARK/Kimera-VIO/issues/254 +- **Tier**: L4 +- **Publication Date**: 2024 +- **Timeliness Status**: Relevant implementation caveat +- **Target Audience**: VIO implementers +- **Research Boundary Match**: Partial overlap +- **Summary**: Kimera-VIO stereo path remains strong, but mono-inertial configurations had documented poor default performance; parameter changes improved one EuRoC mono setup to less than about +/-0.2 m per axis. +- **Related Sub-question**: Mode B round 3 — Kimera mono/nadir risk + +## Source #37 +- **Title**: RaD-VIO and downward-facing VIO literature +- **Link**: https://arxiv.org/abs/1810.08704 +- **Tier**: L1 +- **Publication Date**: 2018 +- **Timeliness Status**: Stable mechanism reference +- **Target Audience**: MAV downward-camera VIO researchers +- **Research Boundary Match**: Full match for nadir-camera caveat +- **Summary**: Downward-facing monocular VIO has planar-scene and observability challenges; range/altitude and IMU constraints are important when the camera sees mostly ground plane. +- **Related Sub-question**: Mode B round 3 — nadir support and limitations + +## Source #38 +- **Title**: OpenVINS covariance documentation and StateHelper APIs +- **Link**: https://docs.openvins.com/dev-index.html +- **Tier**: L1 +- **Publication Date**: Current docs, accessed 2026-05-01 +- **Timeliness Status**: Currently valid +- **Target Audience**: VIO implementers +- **Research Boundary Match**: Full match for covariance/confidence output +- **Summary**: OpenVINS maintains EKF covariance and exposes full/marginal covariance helpers, making it the strongest reference for covariance consistency even if GPLv3 blocks default production use. +- **Related Sub-question**: Mode B round 3 — confidence/covariance support diff --git a/_docs/00_research/02_fact_cards.md b/_docs/00_research/02_fact_cards.md new file mode 100644 index 0000000..d6935f6 --- /dev/null +++ b/_docs/00_research/02_fact_cards.md @@ -0,0 +1,348 @@ +# Fact Cards + +## Fact #1 +- **Statement**: Fixed-wing high-altitude monocular VO suffers from scale ambiguity and accumulated error; comparing against satellite imagery can reduce accumulated drift. +- **Source**: Source #1 +- **Phase**: Phase 2 +- **Target Audience**: UAV localization implementers +- **Confidence**: High +- **Related Dimension**: Architecture +- **Fit Impact**: Supports satellite-anchored hybrid estimator. + +## Fact #2 +- **Statement**: Aerial VPR is sensitive to weather, season, scale variation, repetitive patterns, and map tile construction; overlap and scale level materially affect retrieval quality. +- **Source**: Source #2 +- **Confidence**: High +- **Related Dimension**: VPR +- **Fit Impact**: Supports AC-8.6 VPR chunks with overlap and seasonal validation. + +## Fact #3 +- **Statement**: Heavy VPR re-ranking can be too slow for steady-state embedded use; survey evidence reports some re-ranking around 1 s and SuperGlue much slower on evaluated hardware. +- **Source**: Source #2 +- **Confidence**: High +- **Related Dimension**: Runtime +- **Fit Impact**: Disqualifies per-frame global VPR/re-ranking unless profiled on Jetson. + +## Fact #4 +- **Statement**: OpenVINS is an EKF/MSCKF visual-inertial estimator with monocular tracking and calibration support, but its code is GPL-3. +- **Source**: Source #3 +- **Confidence**: High +- **Related Dimension**: VO/VIO +- **Fit Impact**: Reference/benchmark only unless GPL obligations are accepted. + +## Fact #5 +- **Statement**: ORB-SLAM3 supports monocular visual-inertial SLAM and multi-map operation, but it is GPLv3 and expects careful calibration and a SLAM-style runtime stack. +- **Source**: Source #4 +- **Confidence**: High +- **Related Dimension**: VO/VIO +- **Fit Impact**: Rejected as production dependency; useful benchmark/reference. + +## Fact #6 +- **Statement**: OpenCV provides camera calibration APIs that output camera matrix and distortion coefficients, and homography estimation APIs including RANSAC. +- **Source**: Source #5 +- **Confidence**: High +- **Related Dimension**: Calibration / geometry +- **Fit Impact**: Selected utility layer for calibration, undistortion, homography, and geometric validation. + +## Fact #7 +- **Statement**: LightGlue accepts local keypoints/descriptors from extractors such as DISK, ALIKED, SIFT, and SuperPoint, and returns matched keypoint indices, coordinates, and confidence scores. +- **Source**: Source #6 +- **Confidence**: High +- **Related Dimension**: Local matching +- **Fit Impact**: Selected candidate for conditional cross-domain local matching. + +## Fact #8 +- **Statement**: LightGlue has adaptive depth/width pruning, FlashAttention, mixed precision, and benchmark scripts; runtime must be profiled on Jetson because defaults are optimized for desktop GPUs. +- **Source**: Source #6 +- **Confidence**: High +- **Related Dimension**: Runtime +- **Fit Impact**: Selected with runtime-quality gate. + +## Fact #9 +- **Statement**: LightGlue code/weights are Apache-2.0, but SuperPoint pretrained weights/inference have restrictive licensing; DISK and ALIKED are safer extractor pairings from a licensing perspective. +- **Source**: Source #6 +- **Confidence**: High +- **Related Dimension**: Licensing +- **Fit Impact**: Select DISK/ALIKED+LightGlue for production candidate; treat SuperPoint as license-gated. + +## Fact #10 +- **Statement**: AnyLoc provides DINOv2 feature extraction and VLAD aggregation APIs, but its full experiment setup notes large storage/compute requirements. +- **Source**: Source #7 +- **Confidence**: High +- **Related Dimension**: VPR descriptors +- **Fit Impact**: DINOv2-VLAD selected as offline/conditional retrieval candidate, not unconditional per-frame path. + +## Fact #11 +- **Statement**: DINOv2 official repository provides Meta's DINOv2 implementation and model assets with Apache-2.0 / CC-BY-4.0 license notices. +- **Source**: Source #8 +- **Confidence**: High +- **Related Dimension**: VPR descriptors +- **Fit Impact**: Supports DINOv2 as a permissible descriptor backbone subject to model-license review. + +## Fact #12 +- **Statement**: FAISS is designed for efficient dense vector similarity search, top-k nearest-neighbor retrieval, speed/accuracy tradeoffs, and indexes too large for simple exhaustive scanning. +- **Source**: Source #9 +- **Confidence**: High +- **Related Dimension**: Descriptor retrieval +- **Fit Impact**: Selected vector index for offline VPR descriptors. + +## Fact #13 +- **Statement**: FAISS supports saving/loading indexes; GPU indexes must be converted to CPU before saving. +- **Source**: Source #9 +- **Confidence**: High +- **Related Dimension**: Cache lifecycle +- **Fit Impact**: Supports install-time/index-build flow with runtime load. + +## Fact #14 +- **Statement**: MAVSDK provides telemetry subscriptions for raw GPS, GPS info, status text, odometry, and position/velocity; it does not remove the need for raw MAVLink control over `GPS_INPUT` emission. +- **Source**: Source #10 +- **Confidence**: High +- **Related Dimension**: MAVLink integration +- **Fit Impact**: Select MAVSDK for telemetry, pymavlink/raw MAVLink for `GPS_INPUT`. + +## Fact #15 +- **Statement**: ArduPilot GPSInput requires `GPS1_TYPE=14` for MAVLink GPS input. +- **Source**: Source #11 +- **Confidence**: High +- **Related Dimension**: MAVLink output +- **Fit Impact**: Confirms production parameter requirement. + +## Fact #16 +- **Statement**: `GPS_INPUT` carries WGS84 lat/lon, MSL altitude, velocity, `fix_type`, `horiz_accuracy`, `vert_accuracy`, `speed_accuracy`, and ignore flags. +- **Source**: Source #12 +- **Confidence**: High +- **Related Dimension**: Output contract +- **Fit Impact**: Supports mapping estimator covariance to `horiz_accuracy` and failover fix types. + +## Fact #17 +- **Statement**: ArduPilot GPS glitch protection and EKF failsafe behavior are parameterized and vehicle-specific; Copter docs are not enough to prove Plane behavior. +- **Source**: Sources #13, #14 +- **Confidence**: High +- **Related Dimension**: Failsafe +- **Fit Impact**: Requires ArduPilot Plane SITL validation. + +## Fact #18 +- **Statement**: Jetson Orin Nano Super provides 67 INT8 TOPS, 8 GB memory, 102 GB/s bandwidth, and 7-25 W power range. +- **Source**: Source #15 +- **Confidence**: High +- **Related Dimension**: Runtime +- **Fit Impact**: Confirms target platform constraint. + +## Fact #19 +- **Statement**: NVIDIA warns Super power modes require thermal design that can handle the power modes; otherwise throttling can reduce performance. +- **Source**: Source #16 +- **Confidence**: High +- **Related Dimension**: Thermal +- **Fit Impact**: Supports AC-NEW-5 hot-soak and throttle logging. + +## Fact #20 +- **Statement**: PMTiles is efficient for single-file tile reads but is read-only and cannot be updated in place. +- **Source**: Source #17 +- **Confidence**: High +- **Related Dimension**: Cache storage +- **Fit Impact**: Rejected for mutable onboard tile writes; possible export/package format only. + +## Fact #21 +- **Statement**: COG supports tiled, compressed, overview-enabled GeoTIFFs suitable for efficient raster access and geospatial tooling. +- **Source**: Source #18 +- **Confidence**: High +- **Related Dimension**: Cache storage +- **Fit Impact**: Selected imagery storage unit for immutable service tiles and generated candidate tiles. + +## Fact #22 +- **Statement**: AerialVL provides aerial visual localization sequences, reference maps, and geo-referenced evaluation data. +- **Source**: Source #19 +- **Confidence**: Medium +- **Related Dimension**: Validation +- **Fit Impact**: Selected validation dataset for VPR/satellite-anchor algorithm development. + +## Fact #23 +- **Statement**: EuRoC provides synchronized camera/IMU and ground truth for VIO, but it is not representative of high-altitude fixed-wing nadir imagery. +- **Source**: Source #20 +- **Confidence**: High +- **Related Dimension**: Validation +- **Fit Impact**: Use for VIO sanity checks only, not final AC proof. + +## MVE Evidence + +### MVE — OpenCV calibration and homography utilities +- **Source**: Source #5 +- **Pinned mode/config**: Use OpenCV 4.x C++/Python APIs for checkerboard calibration, undistortion, homography estimation with RANSAC, and reprojection-error measurement. +- **Inputs in example**: Object/image point correspondences, image size, matched keypoints. +- **Outputs in example**: Camera matrix, distortion coefficients, rotation/translation vectors, homography matrix. +- **Project inputs**: ADTi nav-camera frames, checkerboard calibration images, matched VO/satellite points. +- **Project outputs required**: Intrinsics/distortion, homography, inlier mask, MRE. +- **Match assessment**: Exact match. + +### MVE — LightGlue in DISK/ALIKED local-matching mode +- **Source**: Source #6 +- **Pinned mode/config**: Use DISK+LightGlue or ALIKED+LightGlue on CUDA/TensorRT-profiled Jetson path, with inputs two normalized images and outputs matched keypoint coordinates plus confidence scores. +- **Inputs in example**: Two images loaded to GPU; local features extracted by DISK/ALIKED/SuperPoint. +- **Outputs in example**: `matches` shape `(K, 2)`, keypoint coordinates in each image, confidence scores. +- **Project inputs**: Orthorectified nav frame crop and candidate satellite/VPR chunk. +- **Project outputs required**: 2D-2D correspondences for RANSAC homography and cross-domain MRE. +- **Match assessment**: Exact interface match; runtime quality gate remains. + +### MVE — FAISS top-K VPR retrieval +- **Source**: Source #9 +- **Pinned mode/config**: Use FAISS CPU index with optional GPU acceleration for top-K nearest neighbor search over precomputed DINOv2/VLAD descriptors, saved/loaded at install/preflight time. +- **Inputs in example**: Float32 descriptor matrix, query descriptor, `k`. +- **Outputs in example**: Distance matrix `D` and index matrix `I`. +- **Project inputs**: Precomputed VPR chunk descriptors, query frame descriptor. +- **Project outputs required**: Top-K candidate chunk IDs for local matching. +- **Match assessment**: Exact match. + +### MVE — MAVSDK telemetry + pymavlink GPS_INPUT +- **Source**: Sources #10, #11, #12 +- **Pinned mode/config**: Use MAVSDK for telemetry subscriptions and pymavlink/raw MAVLink for `GPS_INPUT` emission to ArduPilot with `GPS1_TYPE=14`. +- **Inputs in example**: Telemetry streams, estimator lat/lon/alt/velocity/covariance. +- **Outputs in example**: `GPS_INPUT` fields accepted by ArduPilot GPS backend. +- **Project inputs**: ESKF state and covariance, source label, mode/fix quality. +- **Project outputs required**: Frame-by-frame WGS84 `GPS_INPUT`, status text, FDR record. +- **Match assessment**: Exact match for output contract; Plane SITL validation remains. + +## Mode B Findings + +### Fact #24 +- **Statement**: DINOv2 TensorRT optimization on Jetson may provide limited speedup and can change embedding distances; descriptor fidelity must be tested against the PyTorch/ONNX baseline before selecting a TensorRT descriptor path. +- **Source**: Sources #21, #22 +- **Phase**: Mode B +- **Confidence**: Medium +- **Related Dimension**: VPR runtime / quality +- **Fit Impact**: Adds embedding-fidelity gate; keeps DINOv2 selected only after profiling. + +### Fact #25 +- **Statement**: LightGlue's SuperPoint path has documented license concerns; DISK/ALIKED remain the safer production default unless legal review approves SuperPoint. +- **Source**: Source #23 +- **Phase**: Mode B +- **Confidence**: High +- **Related Dimension**: Licensing +- **Fit Impact**: Confirms draft01 decision to avoid SuperPoint as default. + +### Fact #26 +- **Statement**: ArduPilot `GPS_INPUT_IGNORE_FLAG_VEL_HORIZ` has a reported EKF3 pitfall where velocity may become zero rather than truly ignored; SITL must validate velocity-source parameters and message fields. +- **Source**: Source #24 +- **Phase**: Mode B +- **Confidence**: Medium +- **Related Dimension**: MAVLink integration +- **Fit Impact**: Adds a specific MAVLink test and parameter gate. + +### Fact #27 +- **Statement**: FAISS deployment on Jetson ARM64 should assume CPU FAISS by default; GPU FAISS packages are not the safe default on aarch64. +- **Source**: Source #25 +- **Phase**: Mode B +- **Confidence**: Medium +- **Related Dimension**: Descriptor retrieval runtime +- **Fit Impact**: Changes FAISS pinned mode from CPU with optional GPU to CPU-first, with custom GPU build only as future optimization. + +### Fact #28 +- **Statement**: Visual matching with orthophotos is a known GNSS-denied UAV approach, but available sources do not prove robustness against adversarial visual attacks on imagery/cache content. +- **Source**: Source #26 +- **Phase**: Mode B +- **Confidence**: Medium +- **Related Dimension**: Security +- **Fit Impact**: Adds cache integrity, signed manifests, and consistency checks as required controls. + +### Fact #29 +- **Statement**: COG creation is a write-new-object workflow; the live onboard cache should append/replace tile objects through manifests, not mutate a COG in place. +- **Source**: Source #18 +- **Phase**: Mode B +- **Confidence**: High +- **Related Dimension**: Cache lifecycle +- **Fit Impact**: Clarifies cache implementation. + +### Fact #30 +- **Statement**: OpenVINS is technically stronger than a pure hand-rolled OpenCV-only VIO stack for camera+IMU odometry, but its GPLv3 license and generic VIO lifecycle make it unsuitable as the default production dependency for this product. +- **Source**: Sources #27, #28 +- **Phase**: Mode B round 2 +- **Confidence**: High +- **Related Dimension**: VO / VIO selection +- **Fit Impact**: Use OpenVINS as a mandatory benchmark/reference, not as the shipped estimator dependency unless GPL obligations are explicitly accepted. + +### Fact #31 +- **Statement**: The selected production estimator is not "custom OpenCV-only"; OpenCV is the geometry utility layer, while the product-owned ESKF/mode machine owns covariance, source labels, GPS spoofing, blackout, tile-write eligibility, and MAVLink semantics. +- **Source**: Sources #5, #29; AC-1.4, AC-3.5, AC-4.3, AC-NEW-4, AC-NEW-7, AC-NEW-8 +- **Phase**: Mode B round 2 +- **Confidence**: High +- **Related Dimension**: Estimator ownership +- **Fit Impact**: Keep custom production estimator, but reject any interpretation that means building a naive OpenCV-only VIO stack. + +### Fact #32 +- **Statement**: Fixed-wing GPS-denied UAV research supports a hybrid of visual odometry plus satellite/orthophoto matching to reduce accumulated drift, matching the project architecture better than a standalone VIO-only solution. +- **Source**: Sources #1, #26 +- **Phase**: Mode B round 2 +- **Confidence**: High +- **Related Dimension**: Architecture +- **Fit Impact**: Confirms that OpenVINS alone cannot satisfy the absolute-position and re-anchor responsibilities without the satellite anchor path. + +### Fact #33 +- **Statement**: DINOv2-VLAD/AnyLoc-style retrieval is a strong global candidate generator for aerial VPR, but descriptor size, model size, and environment-specific VLAD/index choices must be budgeted and profiled. +- **Source**: Sources #7, #30, #32 +- **Phase**: Mode B round 2 +- **Confidence**: High +- **Related Dimension**: Satellite retrieval +- **Fit Impact**: Select DINOv2-VLAD for triggered retrieval, not steady-state per-frame execution. + +### Fact #34 +- **Statement**: Aerial VPR sources emphasize tile/chunk scale, overlap, weather/season changes, repetitive patterns, and re-ranking cost; local matching should be a verification/rerank stage over bounded top-K candidates. +- **Source**: Source #32 +- **Phase**: Mode B round 2 +- **Confidence**: High +- **Related Dimension**: Anchor verification +- **Fit Impact**: Supports VPR chunks with 40-50% overlap, dynamic K, and conditional ALIKED/LightGlue verification. + +### Fact #35 +- **Statement**: ALIKED + LightGlue has an exact local matching interface and a plausible ONNX/TensorRT deployment path, but public evidence does not prove Jetson Orin Nano p95 latency for the project image sizes. +- **Source**: Sources #6, #31 +- **Phase**: Mode B round 2 +- **Confidence**: Medium +- **Related Dimension**: Local matching runtime +- **Fit Impact**: Keep ALIKED/LightGlue selected with runtime gate; benchmark DISK and SIFT/ORB as fallbacks. + +### Fact #36 +- **Statement**: DINOv2 TensorRT conversion can reduce embedding discrimination and may not provide meaningful speedup on Jetson-class devices; descriptor-fidelity tests must precede any optimized engine acceptance. +- **Source**: Source #22 +- **Phase**: Mode B round 2 +- **Confidence**: Medium +- **Related Dimension**: VPR deployment +- **Fit Impact**: TensorRT is an optimization candidate only after PyTorch/ONNX retrieval-rank equivalence is proven. + +### Fact #37 +- **Statement**: BASALT is the best production VIO candidate among BASALT, OpenVINS, and Kimera-VIO because it combines permissive licensing with strong published EuRoC accuracy and completion evidence. +- **Source**: Sources #33, #34, #35 +- **Phase**: Mode B round 3 +- **Confidence**: Medium +- **Related Dimension**: VO / VIO selection +- **Fit Impact**: Select BASALT as the production VIO candidate, pending project replay/profiling. + +### Fact #38 +- **Statement**: OpenVINS has the clearest EKF covariance story, including full/marginal covariance helpers and NEES-style evaluation support, but remains production-constrained by GPLv3. +- **Source**: Sources #27, #28, #38 +- **Phase**: Mode B round 3 +- **Confidence**: High +- **Related Dimension**: Confidence / covariance +- **Fit Impact**: Keep OpenVINS as covariance/reference baseline and use it to calibrate the BASALT wrapper's reported uncertainty. + +### Fact #39 +- **Statement**: Kimera-VIO is production-friendly from a license standpoint, but it is heavier/stereo-oriented and has documented mono-inertial parameter/performance caveats. +- **Source**: Sources #34, #36 +- **Phase**: Mode B round 3 +- **Confidence**: Medium +- **Related Dimension**: VO / VIO fallback +- **Fit Impact**: Keep Kimera-VIO as a backup candidate, not the first production choice for a single fixed nadir camera. + +### Fact #40 +- **Statement**: None of BASALT, OpenVINS, or Kimera-VIO provides a special fixed-wing nadir mode; downward-camera support depends on accurate camera-to-IMU extrinsics, altitude/scale constraints, and validation under low-parallax planar terrain. +- **Source**: Source #37 +- **Phase**: Mode B round 3 +- **Confidence**: High +- **Related Dimension**: Nadir-camera support +- **Fit Impact**: The architecture must keep satellite anchors and project-level confidence gates regardless of which VIO library is selected. + +### Fact #41 +- **Statement**: Published EuRoC-type VIO error rates are useful for ranking libraries but are not acceptance evidence for high-altitude fixed-wing nadir imagery over agricultural terrain. +- **Source**: Sources #34, #35, #37 +- **Phase**: Mode B round 3 +- **Confidence**: High +- **Related Dimension**: Validation +- **Fit Impact**: Require representative replay/flight data before claiming AC-1/AC-2 accuracy. diff --git a/_docs/00_research/03_comparison_framework.md b/_docs/00_research/03_comparison_framework.md new file mode 100644 index 0000000..23e486b --- /dev/null +++ b/_docs/00_research/03_comparison_framework.md @@ -0,0 +1,55 @@ +# Comparison Framework + +## Selected Framework Type + +Decision support with exact-fit component selection. + +## Selected Dimensions + +1. Required inputs/outputs and ownership boundaries +2. Operating context and lifecycle fit +3. Non-functional envelope fit: latency, memory, storage, thermal, safety +4. Licensing and deployability +5. Evidence quality and validation burden +6. Security and safety failure modes +7. Selection status + +## Initial Population + +| Component Area | Candidate | Option Family | Inputs / Outputs | Fit Summary | Status | +|----------------|-----------|---------------|------------------|-------------|--------| +| Calibration / geometry | OpenCV 4.x | Established production / open-source | image/object points -> intrinsics, distortion, homography, inlier mask | Exact utility fit; permissive production use. | Selected | +| VO / VIO | BASALT + project-owned safety/anchor wrapper | Open-source production candidate | nav frames + FC IMU/calibration -> relative VIO state; wrapper adds source labels, anchor fusion, calibrated confidence, and MAVLink semantics | Best production candidate after user decision: permissive license, strong benchmark evidence, and lower implementation burden than custom VIO. | Selected | +| VO / VIO | OpenVINS | Open-source research | monocular camera + IMU -> VIO state/covariance | Best covariance/reference story, but GPL-3 and generic VIO ownership make it a benchmark/reference rather than shipped core. | Reference only | +| VO / VIO | Kimera-VIO | Open-source production candidate / fallback | mono or stereo camera + IMU -> VIO/SLAM outputs | BSD-friendly, but heavier/stereo-oriented and mono-inertial path has documented parameter caveats. | Backup candidate | +| VO / VIO | OpenCV geometry + project-owned ESKF | Custom fallback | nav frames + FC IMU/attitude/altitude + satellite anchors -> relative motion, absolute updates, covariance, source labels | Fallback if BASALT fails project data/runtime tests; still needed as safety/anchor wrapper around any VIO library. | Fallback / wrapper | +| VO / VIO | ORB-SLAM3 | Open-source research | monocular/stereo/RGB-D + optional IMU -> SLAM pose | Useful benchmark; GPLv3, map runtime, and initialization complexity make it poor production dependency. | Rejected for production | +| Global retrieval | DINOv2-VLAD / AnyLoc-style descriptors | Current SOTA / research | image/chunk -> descriptor | Strong VPR evidence; trigger-only use due runtime/memory and TensorRT fidelity risk. | Selected with runtime gate | +| Vector retrieval | FAISS | Established production / open-source | descriptor matrix + query -> top-K IDs | Exact fit for offline VPR chunk retrieval. | Selected | +| Local matching | LightGlue + DISK/ALIKED | Current SOTA / open-source | two images -> keypoint correspondences/scores | Exact local-match interface; avoids SuperPoint license issue. | Selected with runtime gate | +| Local matching | SuperPoint + LightGlue | Current SOTA / known-bad/licensing caveat | two images -> matches | Technically good; licensing requires explicit review. | Needs user decision / fallback only | +| Cache imagery | COG + manifest + sidecars | Established geospatial format | georeferenced raster + metadata -> efficient local reads | Good immutable tile unit; generated tiles can be written as new COGs. | Selected | +| Cache packaging | PMTiles | Established web-map archive | tile pyramid -> single archive | Efficient reads, but read-only; not suitable for in-flight mutable writes. | Rejected for mutable cache | +| Estimator | Custom ESKF mode machine | Custom production | VO/IMU/VPR/GPS-health -> WGS84 state + covariance + label | Needed for source labels, covariance gates, blackout/spoofing behavior. | Selected | +| MAVLink integration | MAVSDK + pymavlink | Established APIs | telemetry in, `GPS_INPUT` out | MAVSDK handles telemetry; pymavlink handles raw `GPS_INPUT`. | Selected | +| FDR | PostgreSQL event index + CBOR payload segments with optional Parquet export | Established storage | frame estimates, IMU, MAVLink, health, tiles -> bounded replayable log | Matches project PostgreSQL choice while keeping compact append payloads. | Selected pattern | +| Validation | AerialVL + EuRoC + Plane SITL + representative flight | Multi-source test strategy | datasets/sim/flight -> AC evidence | Public data is partial; final representative data is mandatory. | Selected | + +## Round 2 Decision Notes + +- **OpenVINS vs custom OpenCV**: OpenVINS wins if the comparison is against a naive OpenCV-only VIO implementation. The selected design is not that; it is OpenCV geometry plus a product-owned estimator/state machine, with OpenVINS used as a benchmark/reference. +- **Satellite retrieval**: DINOv2-VLAD remains the best global candidate generator found, but aerial VPR sources require chunk scale/overlap tuning, dynamic top-K, and geometric verification. +- **Anchor verification**: ALIKED/LightGlue remains the preferred learned local matcher, while SIFT/ORB stays as a regression/fallback baseline and SuperPoint remains license-gated. + +## Round 3 Decision Notes + +- **User decision**: BASALT is selected as the production VIO candidate. +- **Confidence/covariance**: OpenVINS remains the covariance/reference baseline because its EKF exposes clearer uncertainty semantics than BASALT/Kimera. +- **Nadir support**: no compared VIO library has a special fixed-wing nadir mode; the acceptance path is calibration, altitude/scale constraints, satellite anchors, and representative replay validation. + +## Baseline Alignment + +- "Position estimate" means WGS84 frame center emitted to FC plus a 95% covariance semi-major axis and source label. +- "Satellite anchored" means a visual match passed VPR retrieval, local matching, RANSAC, freshness, covariance, and Mahalanobis gates. +- "Normal flight segment" means the AC-2.1a conditions, not turns/blackout/stale imagery. +- "Selected with runtime gate" means the API capability fits, but final deployment depends on Jetson profiling against AC-4.1 and AC-4.2. diff --git a/_docs/00_research/04_reasoning_chain.md b/_docs/00_research/04_reasoning_chain.md new file mode 100644 index 0000000..70dd834 --- /dev/null +++ b/_docs/00_research/04_reasoning_chain.md @@ -0,0 +1,181 @@ +# Reasoning Chain + +## Dimension 1: Core Architecture + +### Fact Confirmation + +Fixed-wing monocular VO accumulates drift because scale and terrain assumptions are imperfect (Fact #1). Aerial VPR can provide absolute anchors but has weather, scale, and repetition failure modes (Fact #2). + +### Reference Comparison + +Pure VO/IMU cannot satisfy the long 8-hour mission. Pure satellite matching cannot run every frame inside the latency budget and will fail in turns, stale imagery, and repetitive fields. + +### Conclusion + +Select a hybrid architecture: steady-state VO/IMU propagation, conditional satellite/VPR anchoring, and ESKF covariance gates. + +### Confidence + +High. Supported by Sources #1 and #2. + +## Dimension 2: VO / VIO Dependency + +### Fact Confirmation + +OpenVINS and ORB-SLAM3 both support visual-inertial estimation patterns, but both are GPL-family production dependency risks (Facts #4 and #5). + +### Reference Comparison + +The project needs a production system with custom mode labels, covariance propagation, MAVLink-specific output behavior, and no hidden GPL obligation. A full SLAM stack also adds initialization and map-management complexity that the ACs do not require. + +### Conclusion + +Use a custom VO/IMU propagation and ESKF mode machine for production. Use OpenVINS/ORB-SLAM3 only as benchmarks/reference algorithms. + +### Confidence + +High for licensing/scope decision; medium for final estimator performance until prototype profiling. + +## Dimension 3: Satellite Retrieval And Local Matching + +### Fact Confirmation + +Aerial VPR benefits from scale/overlap-aware chunks and retrieval + local alignment (Fact #2). LightGlue provides keypoint correspondences/scores from local descriptors (Fact #7). FAISS provides top-K retrieval over descriptors (Fact #12). + +### Reference Comparison + +Global DINOv2/VLAD retrieval alone gives candidate chunks but not enough precision for AC-2.2. Local matching alone over the whole map is too expensive. The two-stage retrieval+alignment structure matches the operational need. + +### Conclusion + +Use DINOv2-VLAD descriptors with FAISS top-K for conditional candidate retrieval, followed by DISK/ALIKED+LightGlue and OpenCV RANSAC homography for local alignment. + +### Confidence + +Medium-high. API fit is strong; embedded runtime must be profiled. + +## Dimension 4: Latency And Memory + +### Fact Confirmation + +Some aerial VPR re-ranking methods are too slow for the steady-state path (Fact #3). Jetson Orin Nano Super has 8 GB shared memory and 25 W power mode (Fact #18), with thermal throttling risk (Fact #19). + +### Reference Comparison + +At 3 fps and <400 ms p95, the system can process every frame through lightweight VO/IMU and use heavier VPR only on triggers. Running DINOv2/LightGlue across many candidates per frame would violate the AC unless proven otherwise. + +### Conclusion + +Make VPR conditional, cap top-K by covariance/sector, run descriptor extraction on downsampled/orthorectified crops, precompute cache descriptors offline, and add performance regression tests. + +### Confidence + +High for architecture direction; exact model sizes need profiling. + +## Dimension 5: Cache Format + +### Fact Confirmation + +COG supports tiled compressed rasters and geospatial tooling (Fact #21). PMTiles is read-efficient but read-only (Fact #20). + +### Reference Comparison + +The onboard system must both read service tiles and write new generated tiles in-flight. A read-only archive is a poor primary mutable store. + +### Conclusion + +Use COG files plus STAC-like manifests/sidecars for imagery and metadata; use FAISS sidecar indexes for descriptors. PMTiles may be an export/snapshot format, not the live mutable cache. + +### Confidence + +High. + +## Dimension 6: Autopilot Integration + +### Fact Confirmation + +ArduPilot MAVLink GPS input requires `GPS1_TYPE=14` (Fact #15). `GPS_INPUT` carries the fields needed for WGS84 position and accuracy (Fact #16). MAVSDK covers telemetry but raw `GPS_INPUT` emission still needs pymavlink/raw MAVLink (Fact #14). + +### Reference Comparison + +MAVSDK-only output would not satisfy AC-4.3. Raw pymavlink-only telemetry is possible but gives up MAVSDK's high-level subscriptions. + +### Conclusion + +Use MAVSDK for telemetry subscriptions and pymavlink for `GPS_INPUT` emission. Verify all failsafe/spoofing behavior in ArduPilot Plane SITL. + +### Confidence + +High for interface; medium for exact Plane failsafe timing until SITL. + +## Dimension 7: Validation + +### Fact Confirmation + +AerialVL provides aerial localization/reference-map data (Fact #22). EuRoC provides camera+IMU+ground truth but not fixed-wing nadir imagery (Fact #23). The current sample set lacks IMU/ground truth. + +### Reference Comparison + +No single public dataset proves every AC. Public datasets can de-risk components, while final acceptance requires representative synchronized flight/replay data. + +### Conclusion + +Use layered validation: EuRoC for VIO sanity, AerialVL/VPAir-style data for VPR/anchor tests, ArduPilot Plane SITL for MAVLink/failsafe/spoofing, and a final representative flight/replay rig for AC proof. + +### Confidence + +High. + +## Dimension 8: OpenVINS vs Project-Owned Estimator + +### Fact Confirmation + +OpenVINS is a strong monocular+IMU EKF/MSCKF VIO reference with covariance-aware estimation (Facts #4 and #30). OpenCV supplies calibration, undistortion, homography, RANSAC/USAC, and reprojection-error primitives, but it is not a full estimator by itself (Facts #6 and #31). + +### Reference Comparison + +If the alternative is a naive OpenCV-only VIO stack, OpenVINS is the better technical starting point. The project's actual production choice is different: it needs a project-owned ESKF/mode machine that fuses VO/IMU, accepts/rejects satellite anchors, emits `GPS_INPUT`, labels every estimate, handles spoofing/blackout, and gates cache write-back. + +### Conclusion + +Keep OpenVINS as a mandatory benchmark/reference implementation, not as the default production dependency. The production estimator remains project-owned, with OpenCV as the geometry utility layer. + +### Confidence + +High. The technical comparison favors OpenVINS over naive custom VIO, while the product fit favors the project-owned estimator. + +## Dimension 9: Satellite Retrieval And Anchor Verification + +### Fact Confirmation + +DINOv2-VLAD/AnyLoc-style retrieval has strong VPR evidence but descriptor/model size and TensorRT fidelity must be validated (Facts #33 and #36). Aerial VPR survey evidence emphasizes tile scale, overlap, season/weather shifts, repetitive patterns, and re-ranking cost (Fact #34). LightGlue supports ALIKED/DISK/SIFT feature matching and returns correspondences/scores suitable for RANSAC verification, but Jetson latency must be profiled (Facts #7, #8, #35). + +### Reference Comparison + +Classical SIFT/ORB is simpler and cheap but weaker for cross-domain UAV-to-satellite matching. SuperPoint+LightGlue is technically strong but remains license-gated. Pure global retrieval without local verification is unsafe because repetitive farmland and stale imagery can produce plausible but wrong candidates. + +### Conclusion + +Use DINOv2-VLAD + CPU-first FAISS as the triggered global retriever, then verify bounded top-K candidates with ALIKED/LightGlue + OpenCV RANSAC. Keep SIFT/ORB as a regression baseline and SuperPoint only after legal approval. + +### Confidence + +High for architecture and interfaces; medium for final runtime until Jetson profiling. + +## Dimension 10: BASALT vs Kimera-VIO vs OpenVINS + +### Fact Confirmation + +BASALT has strong published EuRoC evidence and production-friendly licensing (Fact #37). OpenVINS has the clearest EKF covariance API and consistency tooling, but GPLv3 remains a production constraint (Fact #38). Kimera-VIO is BSD-friendly but heavier and has documented mono-inertial caveats (Fact #39). All three require calibrated camera-to-IMU extrinsics; none has a special fixed-wing nadir mode (Fact #40). + +### Reference Comparison + +For a single fixed downward camera, the selection criterion is not just benchmark ATE. The project needs a VIO core that can run on Jetson, tolerate calibrated nadir geometry, and be wrapped by project-specific satellite-anchor, confidence, MAVLink, and safety logic. OpenVINS is attractive for confidence/covariance but problematic as a shipped component. Kimera is acceptable as a BSD fallback, but mono-inertial risk makes it weaker as the first pick. BASALT provides the best production trade-off if its uncertainty can be calibrated and wrapped. + +### Conclusion + +Select BASALT as the production VIO candidate. Keep OpenVINS as a reference/covariance baseline and Kimera-VIO as a backup candidate. The project-owned safety/anchor wrapper remains mandatory around BASALT because BASALT alone does not satisfy GPS-denied source labels, satellite anchors, false-position budgets, cache-write gates, or `GPS_INPUT` behavior. + +### Confidence + +Medium-high. Library ranking is well supported; final acceptance still depends on representative fixed-wing nadir replay data. diff --git a/_docs/00_research/05_validation_log.md b/_docs/00_research/05_validation_log.md new file mode 100644 index 0000000..ecc86cb --- /dev/null +++ b/_docs/00_research/05_validation_log.md @@ -0,0 +1,51 @@ +# Validation Log + +## Validation Scenario + +An 8-hour fixed-wing mission enters GPS-denied/spoofed mode after takeoff. The onboard system starts from last trusted FC state, processes 3 fps nadir frames, emits `GPS_INPUT`, handles normal flight, sharp turns, short visual blackouts, stale/changed tiles, and post-flight tile write-back. + +## Expected Based On Conclusions + +- **Normal segment**: VO/IMU propagates every processed frame; satellite anchors refresh state conditionally before covariance grows too large. +- **Sharp turn / <5% overlap**: VO is expected to fail; relocalization uses FAISS top-K VPR chunks followed by LightGlue/RANSAC. +- **Visual blackout + spoofing**: estimator switches to `dead_reckoned`, covariance grows monotonically, spoofed GPS is ignored, `GPS_INPUT` degrades honestly. +- **Stale tile**: anchor is rejected or down-confidence weighted and cannot emit `satellite_anchored`. +- **Cache write-back**: onboard generated tile is written only when parent-pose covariance passes AC-NEW-7 gates and carries metadata for Satellite Service voting. + +## Actual Validation Plan + +| Validation Target | Test Method | Pass Evidence | +|-------------------|-------------|---------------| +| VO/VIO propagation | EuRoC and synthetic nadir replay; then representative flight data | Drift vs anchor-age bins; AC-1.3 pass/fail. | +| Satellite anchor | AerialVL/VPAir-style benchmark plus project sample imagery with satellite cache | AC-1.1/1.2 accuracy, AC-2.2 MRE, georeference recall. | +| Runtime | Jetson Orin Nano Super profiling under 25 W, hot-soak included | <400 ms p95, <8 GB memory, no thermal throttle. | +| VPR retrieval | Offline descriptor build and FAISS query benchmark | Top-K recall, query latency, index size within cache budget. | +| MAVLink output | ArduPilot Plane SITL with `GPS1_TYPE=14` | Valid `GPS_INPUT`, fix-type/accuracy degradation, QGC status. | +| Spoofing promotion | Plane SITL false GPS injection | Promotion <3 s and spoofed GPS rejected during blackout. | +| FDR | 8-hour synthetic load | <=64 GB, rollover logged, no silent payload loss. | +| Cache poisoning | Monte Carlo with over-confident wrong anchors | AC-NEW-7 probabilities below budget; metadata contract emitted. | +| OpenVINS reference comparison | Replay the same synchronized camera+IMU segments through OpenVINS and the project-owned estimator | OpenVINS establishes a VIO baseline; production estimator must match/beat drift where applicable while preserving source labels and GPS_INPUT behavior. | +| BASALT production VIO candidate | Replay synchronized camera+IMU segments through BASALT, OpenVINS, and Kimera-VIO | BASALT selected if drift, completion rate, latency, and wrapper-calibrated covariance meet project gates. | +| DINOv2-VLAD fidelity | Compare PyTorch, ONNX, and TensorRT descriptor distances and FAISS rankings | Optimized engines accepted only if rank/top-K behavior stays within tolerance. | +| ALIKED/LightGlue runtime | Jetson benchmark across K candidates and project image sizes | Candidate accepted for runtime only if relocalization trigger path fits AC-4.1 with bounded frame drops. | + +## Counterexamples And Risks + +- Large DINOv2 variants or many local-match candidates may violate the Jetson latency/memory envelope. +- Agricultural fields can be visually repetitive; VPR confidence must not be treated as sufficient without geometric verification. +- Public datasets do not fully match Ukrainian fixed-wing operational conditions; final evidence requires representative data. +- GPL VIO/SLAM libraries are not production dependencies unless licensing is explicitly accepted. +- OpenVINS may outperform the first custom estimator prototype on pure VIO drift; that would trigger estimator improvement, not automatic GPL production adoption. +- BASALT covariance/confidence is less directly exposed than OpenVINS EKF covariance; the project wrapper must calibrate uncertainty before mapping it to `GPS_INPUT.horiz_accuracy`. + +## Review Checklist + +- [x] Draft conclusions are consistent with fact cards. +- [x] No important dimensions missed: architecture, VO, VPR, local matching, cache, estimator, MAVLink, FDR, validation covered. +- [x] No selected component relies only on field-adjacent fit. +- [x] Mismatches are recorded as rejected/reference/needs-decision rather than hidden. +- [x] Step 7.5 Component Applicability Gate applies and is saved in `06_component_fit_matrix.md`. + +## Conclusions Requiring Revision + +Round 3 applies the user decision to select BASALT as the production VIO candidate. The selected implementation is BASALT VIO plus a project-owned safety/anchor wrapper; OpenVINS remains the covariance/reference baseline, Kimera-VIO remains a backup candidate, and custom OpenCV-only VIO is no longer the primary path. Runtime gates and Plane SITL gates are implementation validation gates, not API capability blockers. diff --git a/_docs/00_research/06_component_fit_matrix.md b/_docs/00_research/06_component_fit_matrix.md new file mode 100644 index 0000000..a19fdc0 --- /dev/null +++ b/_docs/00_research/06_component_fit_matrix.md @@ -0,0 +1,107 @@ +# Component Fit Matrix + +## Top-Level Matrix + +| Component Area | Candidate | Pinned Mode/Config | Option Family | Intended Role | API Capability Evidence | Mismatches / Disqualifiers | Status | Decision Rationale | +|----------------|-----------|--------------------|---------------|---------------|-------------------------|----------------------------|--------|--------------------| +| Calibration / geometry | OpenCV 4.x | C++/Python calibration, undistortion, RANSAC homography, reprojection-error measurement | Established production / open-source | Camera intrinsics, image normalization, VO/satellite homography verification | MVE: `02_fact_cards.md` OpenCV block; Source #5 | None | Selected | Exact API fit and permissive utility role. | +| VO / IMU propagation | BASALT + project-owned safety/anchor wrapper | BASALT VIO consumes calibrated nav-camera frames + FC IMU; wrapper fuses satellite anchors, calibrates uncertainty, emits source labels and GPS_INPUT semantics | Open-source production candidate | Relative VIO state, completion/error benchmark, wrapped covariance/confidence, degraded modes, GPS_INPUT semantics | Sources #33-#35; Facts #37, #40, #41 | BASALT covariance/confidence must be calibrated in wrapper; no special nadir mode | Selected | User-selected best production trade-off: permissive licensing and stronger benchmark/completion evidence than OpenVINS/Kimera, with wrapper covering project-specific safety semantics. | +| VO / VIO reference | OpenVINS | Monocular camera + IMU EKF/MSCKF reference runs with covariance extraction | Open-source research | Benchmark and covariance reference | Sources #3, #27, #28, #35, #38; Facts #4, #30, #38 | GPL-3 production dependency risk; completion/divergence risk on some sequences; does not own satellite anchor / GPS_INPUT / blackout / cache-write state machine | Reference only | Best covariance baseline, but not selected as shipped production dependency. | +| VO / VIO backup | Kimera-VIO | Mono/stereo camera + IMU VIO/SLAM backup candidate | Open-source production candidate / fallback | Alternative VIO baseline | Sources #34, #36; Fact #39 | Heavier/stereo-oriented; mono-inertial path has documented parameter caveats | Backup candidate | BSD-friendly backup if BASALT fails project replay/runtime gates. | +| VO / SLAM alternative | ORB-SLAM3 | Monocular-inertial SLAM | Open-source research | Benchmark and failure-mode comparison | Source #4, Fact #5 | GPLv3; heavier SLAM/map lifecycle than required | Rejected | Does not fit licensing/scope for production. | +| VPR descriptors | DINOv2-VLAD / AnyLoc-style | Precomputed satellite chunk descriptors; conditional query descriptor on relocalization triggers; TensorRT path only after embedding-fidelity check | Current SOTA / research | Global top-K candidate retrieval | Sources #7, #8, #21, #22, #30, #32; Facts #10, #11, #24, #33, #34, #36 | Runtime and embedding-fidelity gates on Jetson; model-size/index-size selection required | Selected with runtime gate | Best evidence for change-robust VPR, but not per-frame and not blindly TensorRT-converted. | +| Vector retrieval | FAISS | CPU-first aarch64 index; saved/loaded index over float/PQ descriptors; GPU only if custom Jetson build is proven | Established production / open-source | Top-K candidate chunk search | MVE: `02_fact_cards.md` FAISS block; Sources #9, #25 | GPU FAISS not default on Jetson ARM64 | Selected | Exact top-K descriptor retrieval fit with CPU-first deployment. | +| Local matching | LightGlue + DISK/ALIKED | CUDA/ONNX-profiled DISK or ALIKED feature extraction + LightGlue matching on bounded top-K candidates | Current SOTA / open-source | 2D-2D correspondences for RANSAC and MRE | MVE: `02_fact_cards.md` LightGlue block; Sources #6, #23, #31 | Runtime quality gate; extractor choice must avoid SuperPoint license issue | Selected with runtime gate | Exact input/output fit with deployable licensing path; ALIKED/LightGlue is preferred for anchor verification. | +| Local matching fallback | SuperPoint + LightGlue | SuperPoint features + LightGlue | Current SOTA / license-gated | Optional benchmark/fallback | Source #6 | SuperPoint restrictive license | Needs user decision | Do not use as default production dependency without legal review. | +| Cache imagery | COG + manifest/sidecar | Tiled compressed GeoTIFF tile objects with CRS, capture date, source, m/px, freshness, descriptor sidecars; write-new-object lifecycle | Established geospatial format | Immutable service tiles and generated candidate tiles | Source #18, Facts #21, #29 | No in-place mutation; manifest manages active tile version | Selected | Fits geospatial raster access and write-new-tile workflow. | +| Cache packaging | PMTiles | Read-only tile archive | Established web-map archive | Optional export/snapshot | Source #17, Fact #20 | Cannot update in place | Rejected for live cache | In-flight tile generation needs mutable write-new objects. | +| MAVLink | MAVSDK + pymavlink | MAVSDK telemetry subscriptions; pymavlink/raw MAVLink `GPS_INPUT` emission to ArduPilot `GPS1_TYPE=14`; velocity source/ignore-flag behavior SITL-tested | Established APIs | FC telemetry, QGC status, GPS substitute output | MVE: `02_fact_cards.md` MAVSDK/pymavlink block; Sources #10-#12, #24 | Plane SITL behavior and velocity-source parameters must be validated | Selected | Exact output contract with known ArduPilot pitfall covered. | +| Validation | EuRoC + AerialVL/VPAir + Plane SITL + representative flight | Layered validation suite | Test strategy | Prove ACs before production | Sources #19, #20 | Public data not sufficient for final proof | Selected | Covers component de-risking plus final representative proof. | + +## Restrictions Cross-Check — Selected Production Architecture + +| Restriction | Candidate-mode behavior | Result | Evidence | +|-------------|-------------------------|--------|----------| +| Fixed-wing only | Architecture assumes forward motion, rare sharp turns, no hover dependency. | Pass | Problem context; Source #1 | +| Fixed nadir nav camera | VO/orthorectification uses fixed camera extrinsics; attitude compensation from FC. | Pass | Source #5 | +| Operational area / flat terrain | Flat terrain assumption supported; repetitive agricultural terrain handled as validation class and confidence risk. | Pass | Source #2 | +| Weather/season classes | Validation matrix includes seasonal/visibility classes. | Pass | `05_validation_log.md` | +| Two-camera split | Nav camera drives localization; AI camera object localization uses current GPS-denied state and AI gimbal/zoom. | Pass | AC-7.1/7.2 | +| Satellite Service offline boundary | Runtime uses local COG/cache + FAISS descriptors only; no in-flight provider fetch. | Pass | Sources #17, #18 | +| Freshness gates | Tile manifest carries capture date and sector; stale tiles rejected/down-weighted. | Pass | AC-8.2, AC-NEW-6 | +| Jetson Orin Nano Super | Hot path is lightweight; heavy VPR conditional; runtime profiling gate required. | Pass | Sources #15, #16 | +| MAVLink / ArduPilot only | MAVSDK telemetry + pymavlink `GPS_INPUT`, `GPS1_TYPE=14`. | Pass | Sources #10-#12 | +| No raw frame storage | FDR keeps estimates, telemetry, tiles, and low-rate failure thumbnails only. | Pass | AC-8.5, AC-NEW-3 | + +## AC Cross-Check — Selected Production Architecture + +| AC | Candidate-mode behavior | Result | Evidence | +|----|-------------------------|--------|----------| +| AC-1.1 | Satellite anchors and ESKF output target <=50 m for >=80% normal frames. | Pass | Facts #1, #2 | +| AC-1.2 | Same pipeline targets <=20 m for >=50% normal frames; validated statistically. | Pass | `05_validation_log.md` | +| AC-1.3 | ESKF tracks anchor age and covariance; VO-only and IMU-fused drift measured between anchors. | Pass | Fact #1 | +| AC-1.4 | ESKF emits covariance; telemetry/FDR carries source label. | Pass | Fact #16 | +| AC-2.1a | VO hot path handles normal overlapping frames; failures trigger mode change. | Pass | Facts #1, #6 | +| AC-2.1b | Satellite anchor success measured separately through VPR + local match + RANSAC. | Pass | Facts #2, #7, #12 | +| AC-2.2 | OpenCV/LightGlue provide correspondences and homography MRE measurement. | Pass | Facts #6, #7 | +| AC-3.1 | ESKF innovation gates reject outliers; covariance grows instead of trusting jumps. | Pass | Reasoning chain | +| AC-3.2 | Sharp turn VO failure triggers VPR relocalization. | Pass | AC design; Source #2 | +| AC-3.3 | Disconnected segment handled by global retrieval and pose-graph/ESKF re-anchor. | Pass | Source #2 | +| AC-3.4 | Loss counter and timer trigger GCS relocalization request while dead reckoning continues. | Pass | AC design | +| AC-3.5 | Image-quality/blackout state switches to IMU-only and rejects spoofed GPS. | Pass | AC design; Facts #16, #17 | +| AC-4.1 | Heavy VPR is conditional; steady-state path is VO/IMU. Jetson profiling is a runtime quality gate. | Pass | Facts #3, #18 | +| AC-4.2 | Descriptor/index memory is budgeted; FAISS and cache are precomputed/pruned. | Pass | Facts #12, #13 | +| AC-4.3 | `GPS_INPUT` emitted by pymavlink; ODOMETRY remains disabled in v1. | Pass | Facts #14-#16 | +| AC-4.4 | Estimator emits frame-by-frame; no batching required. | Pass | Architecture | +| AC-4.5 | Corrections are emitted as updated estimates with timestamps and covariance. | Pass | Architecture | +| AC-5.1 | Startup initializes from last trusted FC state plus IMU propagation. | Pass | Architecture | +| AC-5.2 | >3 s no-estimate path enters degraded/failsafe behavior; Plane SITL proves FC response. | Pass | Fact #17 | +| AC-5.3 | Cold restart uses FC state and preloaded cache/index. | Pass | AC-NEW-1 | +| AC-6.1 | QGC receives downsampled status; FDR keeps high-rate details. | Pass | MAVSDK telemetry + FDR design | +| AC-6.2 | Command ingress reserved through MAVLink status/named values/custom dialect. | Pass | MAVLink design | +| AC-6.3 | `GPS_INPUT` lat/lon is WGS84. | Pass | Fact #16 | +| AC-7.1 | Object localization exposes level-flight accuracy and maneuver bound. | Pass | Geometry design | +| AC-7.2 | Flat-terrain trig projection from UAV GPS + gimbal/zoom/altitude. | Pass | Geometry design | +| AC-8.1 | Cache contract requires 0.3-0.5 m/px imagery. | Pass | Restrictions | +| AC-8.2 | Freshness metadata gates anchors. | Pass | Restrictions | +| AC-8.3 | Precomputed descriptors and FAISS index are part of cache budget. | Pass | Facts #10, #12, #13 | +| AC-8.4 | Generated tiles are new COGs with quality metadata for Service ingest. | Pass | Fact #21 | +| AC-8.5 | Raw frames are not retained. | Pass | FDR design | +| AC-8.6 | VPR chunks use overlap/multi-scale descriptors and dynamic K. | Pass | Facts #2, #12 | +| AC-NEW-1 | Engines/indexes built before flight; first fix benchmark validates <30 s. | Pass | Runtime plan | +| AC-NEW-2 | Plane SITL verifies spoofing trigger and promotion <3 s. | Pass | Fact #17 | +| AC-NEW-3 | FDR segment rollover validates <=64 GB. | Pass | Validation plan | +| AC-NEW-4 | Mahalanobis gates and calibrated covariance target false-position budget. | Pass | ESKF design | +| AC-NEW-5 | Thermal profiling at 25 W validates no throttle. | Pass | Facts #18, #19 | +| AC-NEW-6 | Tile age rejection/down-weighting built into anchor gate. | Pass | AC design | +| AC-NEW-7 | Tile writes require parent-pose covariance and sidecar metadata; Satellite Service voting is external contract. | Pass | AC design | +| AC-NEW-8 | Dead-reckoned blackout mode degrades `GPS_INPUT` fields at covariance thresholds. | Pass | Facts #16, #17 | + +## Decision Rules Applied + +- No GPL VIO/SLAM library is selected as a production dependency. +- Runtime gates are classified as runtime-quality validation gates, not API capability blockers. +- Every selected component has an exact input/output role and a validation path. +- Any candidate with license uncertainty is marked `Needs user decision` or non-production. + +## Mode B Revisions Applied + +- FAISS pinned mode changed to CPU-first on Jetson ARM64. +- DINOv2 TensorRT path requires descriptor-fidelity validation against PyTorch/ONNX. +- `GPS_INPUT` tests now include velocity-source and ignore-flag behavior. +- COG cache lifecycle clarified as write-new-object plus manifest versioning, not in-place mutation. +- Visual/satellite security controls now include signed manifests, cache provenance, stale-tile rejection, and multi-signal consistency checks. + +## Mode B Round 2 Revisions Applied + +- OpenVINS is explicitly better than naive OpenCV-only VIO, but remains reference-only because the shipped estimator must own source labels, covariance gates, spoofing/blackout states, cache-write eligibility, and MAVLink semantics. +- The selected VO wording is now "OpenCV geometry + project-owned ESKF" to avoid implying a fragile OpenCV-only odometry implementation. +- DINOv2-VLAD + CPU-first FAISS + ALIKED/LightGlue remains selected for satellite retrieval and anchor verification, with retrieval limited to relocalization triggers and bounded top-K verification. +- SIFT/ORB remains a regression/fallback baseline; SuperPoint remains non-production until legal approval. + +## Mode B Round 3 Revisions Applied + +- BASALT is selected as the production VIO candidate. +- OpenVINS remains the covariance/reference baseline, not a shipped dependency by default. +- Kimera-VIO remains a backup VIO candidate because its license is production-friendly but mono-inertial caveats make it weaker for the single-nadir-camera path. +- The project-owned safety/anchor wrapper remains mandatory around BASALT for satellite anchor acceptance, source labels, blackout/spoofing modes, cache-write eligibility, calibrated confidence, and MAVLink `GPS_INPUT`. diff --git a/_docs/01_solution/solution.md b/_docs/01_solution/solution.md new file mode 100644 index 0000000..8366cef --- /dev/null +++ b/_docs/01_solution/solution.md @@ -0,0 +1,130 @@ +# Solution + +## Product Solution Description + +Build an onboard GPS-denied localization service that runs on the Jetson companion computer, uses the fixed downward navigation camera and flight-controller inertial telemetry, and emits ArduPilot `GPS_INPUT` estimates with calibrated covariance and source labels. + +The production architecture is a trigger-based hybrid estimator: + +```text +Nav camera + FC telemetry + | + v +Image quality + calibration + orthorectification + | + +--> Hot path: OpenCV geometry + BASALT VIO --> safety/anchor wrapper --> GPS_INPUT + QGC + FDR + | + +--> Reference path: OpenVINS replay benchmark for VIO drift/covariance tests; Kimera backup replay + | + +--> Trigger path: DINOv2-VLAD query --> CPU FAISS top-K --> ALIKED/DISK+LightGlue --> OpenCV RANSAC --> safety/anchor wrapper + | + +--> Tile path: new COG tile + quality/provenance sidecar --> manifest update --> post-flight Satellite Service sync +``` + +Heavy retrieval and local matching are not steady-state per-frame dependencies. They run on cold start, VO failure, sharp turns, disconnected segments, covariance growth, stale-anchor age, or operator-assisted relocalization. + +## Architecture + +### Camera Ingest, Calibration, And Geometry + +| Solution | Tools | Pinned Mode/Config | Fit | +|----------|-------|--------------------|-----| +| OpenCV geometry utility layer | OpenCV 4.x | Calibration, undistortion, homography, RANSAC/USAC, MRE measurement | Selected. Mature, permissive, exact utility fit; not a full estimator. | + +### VO / IMU Propagation And Estimator + +| Solution | Tools | Pinned Mode/Config | Fit | +|----------|-------|--------------------|-----| +| BASALT + safety/anchor wrapper | BASALT, OpenCV, custom wrapper | BASALT consumes calibrated nav-camera frames + FC IMU; wrapper fuses satellite anchors, calibrates uncertainty, emits source labels and `GPS_INPUT` fields | Selected. Best production VIO candidate found: permissive license, strong benchmark evidence, avoids custom VIO from scratch. | +| OpenVINS | OpenVINS | Monocular camera + IMU EKF/MSCKF reference runs with covariance extraction | Reference only. Strong VIO and covariance baseline, but GPLv3 and generic VIO ownership make it unsuitable as default shipped dependency. | +| Kimera-VIO | Kimera-VIO | Mono/stereo camera + IMU VIO/SLAM backup replay | Backup candidate. BSD-friendly but heavier/stereo-oriented; mono-inertial path has documented caveats. | +| ORB-SLAM3 | ORB-SLAM3 | Monocular-inertial SLAM | Rejected for production. GPLv3 and heavier SLAM/map lifecycle. | + +BASALT does not replace the project-owned safety logic. The wrapper remains responsible for satellite anchor acceptance, confidence calibration, source labels, blackout/spoofing modes, tile-write eligibility, and MAVLink `GPS_INPUT` semantics. + +### Satellite Retrieval And Anchor Verification + +| Solution | Tools | Pinned Mode/Config | Fit | +|----------|-------|--------------------|-----| +| DINOv2-VLAD + CPU FAISS + ALIKED/DISK+LightGlue | DINOv2/AnyLoc-style descriptors, FAISS CPU, LightGlue, OpenCV RANSAC | Offline VPR chunk descriptors; conditional query descriptor; CPU FAISS top-K; learned local match on bounded candidates; TensorRT only after fidelity check | Selected with runtime/fidelity gates. | +| SuperPoint+LightGlue | SuperPoint, LightGlue | Same matcher with SuperPoint features | License-gated benchmark/fallback only. | +| Classical SIFT/ORB | OpenCV | Handcrafted features + homography | Regression/fallback baseline. | + +The VPR index is built over ground-footprint-sized chunks with overlap and a multi-scale descriptor set. VPR is invoked only on relocalization triggers or covariance/anchor-age growth; normal flight uses BASALT VIO plus wrapper propagation. + +### Cache And Tile Lifecycle + +| Solution | Tools | Pinned Mode/Config | Fit | +|----------|-------|--------------------|-----| +| COG tile objects + PostgreSQL/PostGIS manifest + signed JSON sidecars | GDAL COG, PostgreSQL/PostGIS, signed JSON sidecars, FAISS index files | Service tiles and generated tiles are write-new COG objects; active version selected by PostGIS-backed manifest | Selected. Fits geospatial raster access, provenance, spatial/freshness queries, and write-new tile lifecycle. | +| PMTiles | PMTiles | Read-only archive snapshot | Rejected for live cache because in-flight tile generation needs mutable write-new objects. | + +Service-source tiles and generated tiles carry CRS, capture date, source, m/px, freshness, quality score, sidecar hashes, and descriptor references. Stale tiles are rejected or down-confidence weighted. + +### MAVLink Integration + +| Solution | Tools | Pinned Mode/Config | Fit | +|----------|-------|--------------------|-----| +| MAVSDK telemetry + pymavlink `GPS_INPUT` | MAVSDK, pymavlink | MAVSDK subscriptions; pymavlink emits `GPS_INPUT`; v1 emits GPS_INPUT only; Plane SITL validates `GPS1_TYPE=14`, velocity source params, ignore flags, fix types, accuracy fields | Selected. Exact output control with good telemetry ergonomics. | + +The system emits per-frame estimates locally and downsampled status to QGroundControl. `GPS_INPUT.horiz_accuracy` must not under-report the calibrated 95% covariance semi-major axis. + +### Security And Safety Controls + +| Solution | Tools | Pinned Mode/Config | Fit | +|----------|-------|--------------------|-----| +| Consistency-gated anchor acceptance | Safety/anchor wrapper, cache manifest verification | Anchor accepted only if freshness, provenance, RANSAC, covariance, Mahalanobis, and temporal consistency pass | Selected. Prevents confident false fixes. | +| FDR audit trail | PostgreSQL event index + CBOR payload segments + hashes | Logs estimates, inputs, emitted GPS_INPUT, health, tile writes, anchor decisions | Selected. Supports incident analysis, indexed queries, and cache-poisoning audits. | + +## Runtime Modes + +| Mode | Trigger | Behavior | `GPS_INPUT` / Telemetry | +|------|---------|----------|--------------------------| +| `satellite_anchored` | VPR + local match passes all gates | Wrapper absolute update; tile write eligible only if sigma gate passes | 3D fix, `horiz_accuracy` >= 95% covariance semi-major axis | +| `vo_extrapolated` | BASALT VIO healthy and anchor age/covariance within bounds | BASALT VIO + wrapper propagation; covariance grows | 3D/2D depending covariance threshold | +| `dead_reckoned` | visual blackout or no accepted anchor | IMU-only propagation, monotonic covariance growth | degraded fix type; QGC `VISUAL_BLACKOUT_IMU_ONLY` | +| failsafe/no-fix | covariance >500 m or blackout >30 s | stop pretending position is valid | `fix_type=0`, `horiz_accuracy=999.0`, QGC `VISUAL_BLACKOUT_FAILSAFE` | + +## Testing Strategy + +### Integration / Functional Tests + +- BASALT replay: assert AC-2.1a and AC-2.2 VO MRE on overlapping frame pairs, completion rate, latency, and wrapper-calibrated covariance. +- OpenVINS reference replay: compare VIO drift, failure cases, and covariance against BASALT + wrapper. +- Kimera-VIO backup replay: keep a second permissive candidate benchmark in case BASALT fails project replay/runtime gates. +- Satellite anchor replay: assert AC-1.1/1.2, AC-2.2 cross-domain MRE, freshness rejection, and source labels. +- DINOv2 descriptor fidelity: compare PyTorch/ONNX/TensorRT embeddings and retrieval rankings before accepting optimized engines. +- FAISS CPU index tests: top-K recall, query latency, index size, save/load behavior on Jetson ARM64. +- LightGlue extractor matrix: ALIKED vs DISK vs SIFT/ORB vs SuperPoint benchmark; SuperPoint excluded from production unless legal approves. +- COG cache lifecycle: write-new generated tile, update manifest, verify active version and rollback. +- `GPS_INPUT` SITL: validate fix type, `horiz_accuracy`, velocity fields, ignore flags, `EK3_SRC1_*` parameters, QGC behavior. +- Security gates: stale tile, mismatched tile hash, low inlier ratio, impossible velocity jump, and spoofed GPS during blackout. + +### Non-Functional Tests + +- Jetson latency and memory: <400 ms p95, <8 GB shared memory, no 25 W thermal throttle. +- Cache budget: 400 km² imagery + manifests + descriptors fits budget or reports explicit split budget. +- FDR 8-hour load: <=64 GB, rollover logged, no silent payload loss. +- Monte Carlo false-position and cache-poisoning tests for AC-NEW-4 and AC-NEW-7. +- Cold boot: first valid `GPS_INPUT` <30 s p95 across 50 runs. + +## References + +Detailed source registry: `_docs/00_research/01_source_registry.md`. + +Key sources: +- BASALT repository: https://github.com/VladyslavUsenko/basalt +- HybVIO benchmark paper: https://arxiv.org/pdf/2106.11857 +- OpenVINS docs: https://docs.openvins.com/index.html +- OpenVINS ATE/RTE comparison: https://github.com/rpng/open_vins/issues/402 +- Kimera mono-inertial caveat: https://github.com/MIT-SPARK/Kimera-VIO/issues/254 +- AnyLoc paper: https://arxiv.org/html/2308.00688 +- Aerial VPR survey: https://arxiv.org/abs/2406.00885 +- ALIKED-LightGlue-ONNX: https://github.com/ikeboo/ALIKED-LightGlue-ONNX +- DINOv2 TensorRT issue: https://github.com/NVIDIA/TensorRT/issues/4348 + +## Related Artifacts + +- Tech stack evaluation: `_docs/01_solution/tech_stack.md` +- Component fit matrix: `_docs/00_research/06_component_fit_matrix.md` +- Fact cards: `_docs/00_research/02_fact_cards.md` diff --git a/_docs/01_solution/solution_draft01.md b/_docs/01_solution/solution_draft01.md new file mode 100644 index 0000000..063bff2 --- /dev/null +++ b/_docs/01_solution/solution_draft01.md @@ -0,0 +1,149 @@ +# Solution Draft + +## Product Solution Description + +Build an onboard GPS-denied localization service that runs on the companion Jetson, consumes the fixed nadir navigation camera plus flight-controller IMU/attitude/altitude, and emits ArduPilot-compatible `GPS_INPUT` estimates with honest covariance. + +The solution is a hybrid estimator: + +```text +Nav camera + FC telemetry + | + v +Image quality + calibration + orthorectification + | + +--> Steady state: VO/IMU propagation --> ESKF --> GPS_INPUT + QGC + FDR + | + +--> Re-anchor triggers: VPR top-K --> local match/RANSAC --> ESKF anchor update + | + +--> Tile generation: ortho tile + quality sidecar --> local cache --> post-flight Satellite Service upload +``` + +The steady-state path is intentionally lightweight. Heavy global retrieval and cross-domain local matching run only on cold start, VO failure, sharp turns, disconnected segments, covariance growth, or stale-anchor age. + +## Existing / Competitor Solutions Analysis + +Recent fixed-wing GPS-denied research supports the same high-level mechanism: monocular visual odometry alone accumulates scale/drift error, while satellite-image comparison can periodically correct it. Aerial VPR surveys also show why the implementation cannot be naive: weather, season, scale mismatch, repetitive fields, tile overlap, and re-ranking runtime all matter. + +The selected design borrows the proven structure but rejects an all-in-one SLAM dependency as the product core. OpenVINS and ORB-SLAM3 are useful benchmark/reference implementations, but their GPL-family licensing and broader SLAM lifecycle do not fit a default production dependency for this project. + +## Architecture + +### Component: Camera Ingest, Calibration, And Geometry + +| Solution | Tools | Pinned Mode/Config | Advantages | Limitations | Requirements | Security | Cost | API Capability Evidence | Fit | +|----------|-------|--------------------|------------|-------------|--------------|----------|------|-------------------------|-----| +| OpenCV geometry utility layer | OpenCV 4.x | Camera calibration, undistortion, RANSAC homography, reprojection-error measurement | Mature, local, fast, exact API fit | Not a full estimator | Calibration target, fixed intrinsics/extrinsics, lens/FOV selection | Local-only, no network | Low | MVE: `_docs/00_research/02_fact_cards.md`; Source #5 | Selected | + +**Exact-fit evidence**: +- Project constraints checked: fixed nadir camera, calibration, homography, MRE gates. +- Disqualifiers: none. +- Restrictions × AC matrix: `_docs/00_research/06_component_fit_matrix.md`. + +### Component: VO / IMU Propagation And Estimator + +| Solution | Tools | Pinned Mode/Config | Advantages | Limitations | Requirements | Security | Cost | API Capability Evidence | Fit | +|----------|-------|--------------------|------------|-------------|--------------|----------|------|-------------------------|-----| +| Custom VO/IMU ESKF | OpenCV + custom estimator | Frame-to-frame homography/features + FC IMU/attitude/altitude fused in a custom ESKF with source modes | Owns covariance, source labels, degraded modes, ArduPilot output semantics | More implementation work than adopting VIO library | Synchronized frames/IMU, calibration, replay tests | No third-party cloud; deterministic local logs | Medium | Facts #1, #4, #5, #16 | Selected | +| OpenVINS reference | OpenVINS | Monocular camera + IMU EKF/MSCKF reference runs | Strong VIO reference and evaluation tools | GPL-3 production dependency risk | Dataset/replay adapter | Local only | Low for benchmark | Source #3 | Reference only | +| ORB-SLAM3 alternative | ORB-SLAM3 | Monocular-inertial SLAM | Mature SLAM benchmark | GPLv3, heavier map lifecycle, initialization complexity | Calibration, vocabulary, runtime tuning | Local only | Medium | Source #4 | Rejected for production | + +**Exact-fit evidence**: +- Project constraints checked: one camera + IMU, frame-by-frame output, covariance labels, blackout/spoofing modes. +- Runtime quality gate: validate drift and covariance on EuRoC-style and representative fixed-wing replay. + +### Component: Satellite Retrieval And Local Anchor + +| Solution | Tools | Pinned Mode/Config | Advantages | Limitations | Requirements | Security | Cost | API Capability Evidence | Fit | +|----------|-------|--------------------|------------|-------------|--------------|----------|------|-------------------------|-----| +| DINOv2-VLAD + FAISS + LightGlue | DINOv2/AnyLoc-style descriptors, FAISS, DISK/ALIKED+LightGlue, OpenCV RANSAC | Offline precomputed VPR chunk descriptors; conditional query descriptor; top-K FAISS; local matching on candidates | Matches AC-8.6; scalable top-K; local geometry verifies anchors | Needs Jetson profiling and model-size pruning | Fresh satellite cache, descriptors, dynamic K, RANSAC gates | Cache is local; no in-flight provider calls | Medium-high | MVE blocks in `02_fact_cards.md`; Sources #6-#9 | Selected with runtime gate | +| SuperPoint + LightGlue | SuperPoint, LightGlue | Same local matching with SuperPoint features | Strong technical baseline | SuperPoint license is restrictive | Legal review | Local only | Medium | Source #6 | Needs user decision | +| Classical SIFT/ORB-only | OpenCV | Handcrafted features and homography | Simple fallback, low compute | Poor cross-domain robustness | Feature-rich scenes | Local only | Low | Source #5 | Fallback / regression baseline | + +**Exact-fit evidence**: +- Project constraints checked: offline cache, top-K dynamic retrieval, cross-domain local match, <400 ms hot-path constraint. +- Runtime gate: heavy VPR/re-ranking is trigger-based, not per-frame. + +### Component: Satellite Cache And Tile Write-Back + +| Solution | Tools | Pinned Mode/Config | Advantages | Limitations | Requirements | Security | Cost | API Capability Evidence | Fit | +|----------|-------|--------------------|------------|-------------|--------------|----------|------|-------------------------|-----| +| COG + PostgreSQL/PostGIS manifest + descriptor sidecars | GDAL COG, PostgreSQL/PostGIS manifest, FAISS sidecars | Service tiles and generated candidate tiles stored as tiled compressed GeoTIFFs with CRS/date/source/meter-per-pixel metadata | Geospatial standard, supports write-new-tile workflow, descriptor accounting | Needs careful 10 GB budget | STAC-like manifest, freshness gates, descriptor pruning | Local signed manifests recommended | Medium | Source #18 | Selected | +| PMTiles archive | PMTiles | Single-file read archive | Efficient map reads | Read-only; cannot update in place | Archive rebuild for updates | Local file integrity | Low | Source #17 | Rejected for live mutable cache | + +**Exact-fit evidence**: +- Project constraints checked: offline-only, no raw photo storage, mid-flight generated tiles, Satellite Service ingest metadata. +- External dependency: Satellite Service owns the promotion/voting layer for trusted basemap updates. + +### Component: MAVLink Integration And Telemetry + +| Solution | Tools | Pinned Mode/Config | Advantages | Limitations | Requirements | Security | Cost | API Capability Evidence | Fit | +|----------|-------|--------------------|------------|-------------|--------------|----------|------|-------------------------|-----| +| MAVSDK telemetry + pymavlink output | MAVSDK, pymavlink | MAVSDK subscribes to telemetry; pymavlink emits `GPS_INPUT` to ArduPilot with `GPS1_TYPE=14` | Exact `GPS_INPUT` field control while keeping high-level telemetry APIs | Plane-specific failsafe/spoof triggers need SITL proof | ArduPilot Plane params, QGC status, FDR tlog | Validate MAVLink source and message rate | Medium | Sources #10-#12 | Selected | + +**Exact-fit evidence**: +- Project constraints checked: ArduPilot only, v1 `GPS_INPUT` only, WGS84 output, covariance to `horiz_accuracy`. +- Validation gate: Plane SITL with production parameters. + +### Component: Flight Data Recorder + +| Solution | Tools | Pinned Mode/Config | Advantages | Limitations | Requirements | Security | Cost | API Capability Evidence | Fit | +|----------|-------|--------------------|------------|-------------|--------------|----------|------|-------------------------|-----| +| Segmented FDR | PostgreSQL event index + binary/CBOR payloads with Parquet export post-flight | Fixed-size segment files for per-frame estimates, IMU, MAVLink, health, emitted GPS_INPUT, generated-tile metadata | Replayable, bounded, no raw frame retention | Exact format selected during implementation | Rollover policy, monotonic timestamps | Integrity hash per segment recommended | Medium | AC-NEW-3 | Selected pattern | + +## Runtime Modes + +| Mode | Trigger | Behavior | Output Label | +|------|---------|----------|--------------| +| Satellite anchored | VPR + local match passes freshness, RANSAC, covariance, and Mahalanobis gates | ESKF absolute update, low covariance, tile generation eligible if sigma gate passes | `satellite_anchored` | +| VO extrapolated | Last anchor fresh enough, VO healthy, normal overlap | VO/IMU propagation, covariance grows with anchor age | `vo_extrapolated` | +| Dead reckoned | Visual blackout, VO failure without anchor, spoofing while no visual signal | IMU-only propagation, monotonic covariance growth, degraded fix type thresholds | `dead_reckoned` | +| Failsafe / no fix | Blackout >30 s or covariance >500 m | `GPS_INPUT.fix_type=0`, `horiz_accuracy=999.0`, QGC status | `dead_reckoned` with failsafe status | + +## Testing Strategy + +### Integration / Functional Tests + +- Replay normal overlapping frames and assert AC-2.1a VO registration rate and AC-2.2 VO MRE. +- Replay satellite-anchor cases and assert AC-1.1/1.2, AC-2.2 cross-domain MRE, freshness gates, and source labels. +- Inject stale tiles and assert no `satellite_anchored` output. +- Inject sharp turns and disconnected segments and assert VPR relocalization. +- Run ArduPilot Plane SITL with `GPS1_TYPE=14` and assert valid `GPS_INPUT` fields, fix type degradation, and QGC statuses. +- Inject visual blackout + spoofed GPS and assert spoofed GPS is ignored, covariance grows, and thresholds match AC-NEW-8. +- Request AI-camera object coordinates and assert level-flight projection plus maneuver error bound. + +### Non-Functional Tests + +- Jetson Orin Nano Super profiling: <400 ms p95, <8 GB shared memory, 25 W no-throttle hot-soak. +- Cache build test for 400 km²: imagery + manifests + descriptors fit within budget or fail with explicit budget report. +- 8-hour FDR load test: <=64 GB, rollover logged, no silent data loss. +- Monte Carlo false-anchor and over-confidence tests for AC-NEW-4 and AC-NEW-7. +- Cold boot 50x: first valid `GPS_INPUT` <30 s p95. + +## References + +Detailed source registry: `_docs/00_research/01_source_registry.md`. + +Key sources: +- Fixed-wing satellite-aided VO: https://www.mdpi.com/2076-3417/14/16/7420 +- Aerial VPR survey: https://arxiv.org/abs/2406.00885 +- OpenVINS docs: https://docs.openvins.com/ +- ORB-SLAM3 README: https://raw.githubusercontent.com/UZ-SLAMLab/ORB_SLAM3/master/README.md +- LightGlue README: https://raw.githubusercontent.com/cvg/LightGlue/main/README.md +- FAISS docs: https://faiss.ai/index.html +- ArduPilot GPSInput: https://ardupilot.org/mavproxy/docs/modules/GPSInput.html +- MAVLink GPS_INPUT: https://mavlink.io/en/messages/common.html#GPS_INPUT +- Jetson Orin Nano Super: https://www.nvidia.com/en-us/autonomous-machines/embedded-systems/jetson-orin/nano-super-developer-kit/ +- PMTiles: https://docs.protomaps.com/pmtiles/ +- GDAL COG: https://gdal.org/en/stable/drivers/raster/cog.html + +## Related Artifacts + +- AC assessment: `_docs/00_research/00_ac_assessment.md` +- Question decomposition: `_docs/00_research/00_question_decomposition.md` +- Source registry: `_docs/00_research/01_source_registry.md` +- Fact cards: `_docs/00_research/02_fact_cards.md` +- Comparison framework: `_docs/00_research/03_comparison_framework.md` +- Reasoning chain: `_docs/00_research/04_reasoning_chain.md` +- Validation log: `_docs/00_research/05_validation_log.md` +- Component fit matrix: `_docs/00_research/06_component_fit_matrix.md` diff --git a/_docs/01_solution/solution_draft02.md b/_docs/01_solution/solution_draft02.md new file mode 100644 index 0000000..7578bae --- /dev/null +++ b/_docs/01_solution/solution_draft02.md @@ -0,0 +1,125 @@ +# Solution Draft + +## Assessment Findings + +| Old Component Solution | Weak Point (functional/security/performance) | New Solution | +|------------------------|----------------------------------------------|-------------| +| DINOv2-VLAD with possible TensorRT optimization | TensorRT conversion may produce limited speedup and can alter embedding distances on Jetson-class deployments. | Keep DINOv2-VLAD, but require descriptor-fidelity tests against PyTorch/ONNX before TensorRT descriptors are accepted. | +| FAISS CPU/GPU optional | FAISS GPU is not a safe default on Jetson ARM64/aarch64 packaging. | Pin FAISS as CPU-first on Jetson; use PQ/IVF and top-K caps before considering custom GPU builds. | +| LightGlue local matcher | SuperPoint path has license risk and community confusion. | Keep DISK/ALIKED+LightGlue as production default; SuperPoint remains license-gated benchmark/fallback only. | +| COG cache | "COG cache" could be misread as mutable in-place raster updates. | Use write-new COG tile objects plus manifest versioning and sidecars; never mutate COGs in place. | +| `GPS_INPUT` output | ArduPilot velocity ignore flags have reported EKF3 pitfalls. | SITL must validate velocity source parameters, ignore flags, and whether zero velocity is ever fused accidentally. | +| Visual/satellite anchoring | Draft did not emphasize adversarial/cache integrity enough. | Add signed cache manifests, tile provenance, freshness gates, anchor consistency checks, and FDR audit trail. | + +## Product Solution Description + +Build an onboard GPS-denied localization service that runs on the Jetson companion computer, uses the fixed downward navigation camera and flight-controller inertial telemetry, and emits ArduPilot `GPS_INPUT` estimates with calibrated covariance and source labels. + +The production architecture is a trigger-based hybrid estimator: + +```text +Nav camera + FC telemetry + | + v +Image quality + calibration + orthorectification + | + +--> Hot path: VO/IMU propagation --> custom ESKF --> GPS_INPUT + QGC + FDR + | + +--> Trigger path: DINOv2-VLAD query --> CPU FAISS top-K --> DISK/ALIKED+LightGlue --> RANSAC --> ESKF anchor + | + +--> Tile path: new COG tile + quality/provenance sidecar --> manifest update --> post-flight Satellite Service sync +``` + +Heavy retrieval and local matching are not steady-state per-frame dependencies. They run on cold start, VO failure, sharp turns, disconnected segments, covariance growth, or stale-anchor age. + +## Architecture + +### Component: Camera Ingest, Calibration, And Geometry + +| Solution | Tools | Pinned Mode/Config | Advantages | Limitations | Requirements | Security | Performance | API Capability Evidence | Fit | +|----------|-------|--------------------|------------|-------------|--------------|----------|-------------|-------------------------|-----| +| OpenCV geometry utility layer | OpenCV 4.x | Calibration, undistortion, RANSAC homography, MRE measurement | Mature, exact fit, permissive | Not a full estimator | Checkerboard calibration, fixed extrinsics, lens/FOV selection | Local-only | Fast enough for hot-path utility use | MVE in `02_fact_cards.md`; Source #5 | Selected | + +### Component: VO / IMU Propagation And Estimator + +| Solution | Tools | Pinned Mode/Config | Advantages | Limitations | Requirements | Security | Performance | API Capability Evidence | Fit | +|----------|-------|--------------------|------------|-------------|--------------|----------|-------------|-------------------------|-----| +| Custom VO/IMU ESKF | OpenCV + custom estimator | Nadir VO/homography + FC IMU/attitude/altitude fused in ESKF with mode labels | Owns covariance, source labels, blackout/spoofing behavior | More implementation effort | Synchronized frames/IMU, calibration, replay tests | No network dependency | Hot path is lightweight | Facts #1, #16 | Selected | +| OpenVINS | OpenVINS | Monocular+IMU reference runs | Strong EKF/MSCKF reference | GPL-3 production risk | Replay adapter | Local only | Benchmark only | Source #3 | Reference only | +| ORB-SLAM3 | ORB-SLAM3 | Monocular-inertial SLAM | Mature benchmark | GPLv3 and heavier SLAM lifecycle | Calibration/vocabulary/runtime tuning | Local only | Riskier on embedded | Source #4 | Rejected for production | + +### Component: Satellite Retrieval And Anchor Verification + +| Solution | Tools | Pinned Mode/Config | Advantages | Limitations | Requirements | Security | Performance | API Capability Evidence | Fit | +|----------|-------|--------------------|------------|-------------|--------------|----------|-------------|-------------------------|-----| +| DINOv2-VLAD + CPU FAISS + DISK/ALIKED+LightGlue | DINOv2/AnyLoc-style descriptors, FAISS CPU, LightGlue, OpenCV RANSAC | Offline VPR chunk descriptors; conditional query descriptor; CPU FAISS top-K; local match on candidates; TensorRT only after fidelity check | Strong retrieval+geometry structure; avoids per-frame map search | Requires profiling and representative data | Descriptor cache, dynamic K, freshness, RANSAC, Mahalanobis gates | Signed manifests, provenance, stale-tile rejection | Trigger path only; top-K capped | MVE blocks in `02_fact_cards.md`; Sources #6-#9, #21-#25 | Selected with runtime/fidelity gates | +| SuperPoint+LightGlue | SuperPoint, LightGlue | Same matcher with SuperPoint features | Strong technical baseline | SuperPoint license risk | Legal review | Local only | Benchmark only | Sources #6, #23 | Needs user decision | +| Classical SIFT/ORB | OpenCV | Handcrafted features + homography | Simple and cheap | Weak cross-domain robustness | Feature-rich scenes | Local only | Fast | Source #5 | Regression baseline | + +### Component: Cache And Tile Lifecycle + +| Solution | Tools | Pinned Mode/Config | Advantages | Limitations | Requirements | Security | Performance | API Capability Evidence | Fit | +|----------|-------|--------------------|------------|-------------|--------------|----------|-------------|-------------------------|-----| +| COG tile objects + manifest + sidecars | GDAL COG, manifest DB/JSON, FAISS index files | Service tiles and generated tiles are write-new COG objects; active version selected by manifest | Geospatial standard, supports provenance and quality metadata | Descriptor budget pressure | CRS/date/source/m/px/freshness, sidecar hashes | Signed manifests, tile provenance, hash verification | Efficient local reads | Source #18; Facts #21, #29 | Selected | +| PMTiles | PMTiles | Read-only archive snapshot | Compact read package | Cannot update in place | Archive rebuild | Hash archive | Good for read-only export | Source #17 | Rejected for live cache | + +### Component: MAVLink Integration + +| Solution | Tools | Pinned Mode/Config | Advantages | Limitations | Requirements | Security | Performance | API Capability Evidence | Fit | +|----------|-------|--------------------|------------|-------------|--------------|----------|-------------|-------------------------|-----| +| MAVSDK telemetry + pymavlink `GPS_INPUT` | MAVSDK, pymavlink | MAVSDK subscriptions; pymavlink emits `GPS_INPUT`; Plane SITL validates `GPS1_TYPE=14`, velocity source params, ignore flags, fix types, accuracy fields | Exact output control with good telemetry ergonomics | SITL required to prove Plane behavior | ArduPilot Plane params, QGC, tlog/FDR | Link/source validation, status audit | Light CPU load | Sources #10-#12, #24 | Selected | + +### Component: Security And Safety Controls + +| Solution | Tools | Pinned Mode/Config | Advantages | Limitations | Requirements | Security | Performance | API Capability Evidence | Fit | +|----------|-------|--------------------|------------|-------------|--------------|----------|-------------|-------------------------|-----| +| Consistency-gated anchor acceptance | Custom ESKF gates, cache manifest verification | Anchor accepted only if freshness, provenance, RANSAC, covariance, Mahalanobis, and temporal consistency pass | Prevents confident false fixes | Needs calibrated thresholds | Representative replay and Monte Carlo | Rejects stale/poisoned/low-confidence anchors | Lightweight after candidate generation | Facts #16, #17, #28 | Selected | +| FDR audit trail | Segmented logs + hashes | Logs estimates, inputs, emitted GPS_INPUT, health, tile writes, anchor decisions | Supports incident analysis and cache-poisoning audits | Schema work | 64 GB rollover | Tamper-evident hashes recommended | Sequential writes | AC-NEW-3 | Selected | + +## Runtime Modes + +| Mode | Trigger | Behavior | `GPS_INPUT` / Telemetry | +|------|---------|----------|--------------------------| +| `satellite_anchored` | VPR + local match passes all gates | ESKF absolute update; tile write eligible only if sigma gate passes | 3D fix, `horiz_accuracy` >= 95% covariance semi-major axis | +| `vo_extrapolated` | VO healthy and anchor age/covariance within bounds | VO/IMU propagation; covariance grows | 3D/2D depending covariance threshold | +| `dead_reckoned` | visual blackout or no accepted anchor | IMU-only propagation, monotonic covariance growth | degraded fix type; QGC `VISUAL_BLACKOUT_IMU_ONLY` | +| failsafe/no-fix | covariance >500 m or blackout >30 s | stop pretending position is valid | `fix_type=0`, `horiz_accuracy=999.0`, QGC `VISUAL_BLACKOUT_FAILSAFE` | + +## Testing Strategy + +### Integration / Functional Tests + +- VO replay: assert AC-2.1a and AC-2.2 VO MRE on overlapping frame pairs. +- Satellite anchor replay: assert AC-1.1/1.2, AC-2.2 cross-domain MRE, freshness rejection, and source labels. +- DINOv2 descriptor fidelity: compare PyTorch/ONNX/TensorRT embeddings and retrieval rankings before accepting optimized engines. +- FAISS CPU index tests: top-K recall, query latency, index size, save/load behavior on Jetson ARM64. +- LightGlue extractor matrix: DISK vs ALIKED vs SuperPoint benchmark; SuperPoint output excluded from production unless license approved. +- COG cache lifecycle: write-new generated tile, update manifest, verify active version and rollback. +- `GPS_INPUT` SITL: validate fix type, `horiz_accuracy`, velocity fields, ignore flags, `EK3_SRC1_*` parameters, QGC behavior. +- Security gates: stale tile, mismatched tile hash, low inlier ratio, impossible velocity jump, and spoofed GPS during blackout. + +### Non-Functional Tests + +- Jetson latency and memory: <400 ms p95, <8 GB shared memory, no 25 W thermal throttle. +- Cache budget: 400 km² imagery + manifests + descriptors fits budget or reports explicit split budget. +- FDR 8-hour load: <=64 GB, rollover logged, no silent payload loss. +- Monte Carlo false-position and cache-poisoning tests for AC-NEW-4 and AC-NEW-7. +- Cold boot: first valid `GPS_INPUT` <30 s p95 across 50 runs. + +## References + +Detailed source registry: `_docs/00_research/01_source_registry.md`. + +Key added Mode B sources: +- DINOv2 TensorRT issue: https://github.com/NVIDIA/TensorRT/issues/4348 +- DINOv2 Jetson forum issue: https://forums.developer.nvidia.com/t/dinov2-tensorrt-model-performance-issue/312251 +- LightGlue license discussion: https://github.com/cvg/LightGlue/issues/120 +- ArduPilot GPS_INPUT velocity issue: https://github.com/ArduPilot/ardupilot/issues/19633 +- FAISS install docs: https://github.com/facebookresearch/faiss/blob/main/INSTALL.md +- Orthophoto visual geolocalization: https://ar5iv.labs.arxiv.org/html/2103.14381 + +## Related Artifacts + +- Tech stack evaluation: `_docs/01_solution/tech_stack.md` +- Component fit matrix: `_docs/00_research/06_component_fit_matrix.md` +- Fact cards: `_docs/00_research/02_fact_cards.md` diff --git a/_docs/01_solution/tech_stack.md b/_docs/01_solution/tech_stack.md new file mode 100644 index 0000000..e7b50e6 --- /dev/null +++ b/_docs/01_solution/tech_stack.md @@ -0,0 +1,59 @@ +# Tech Stack Evaluation + +## Requirements Analysis + +| Area | Requirement | +|------|-------------| +| Runtime | Jetson Orin Nano Super, Ubuntu/JetPack, CUDA/TensorRT available, 8 GB shared memory, 25 W thermal envelope. | +| Language | Python is acceptable for orchestration/prototyping; C++/TensorRT paths likely needed for hot vision loops. | +| Vision | Calibration, undistortion, homography, VPR descriptors, local matching, RANSAC verification. | +| Estimation | BASALT VIO for relative camera+IMU propagation, wrapped by project-owned safety/anchor estimator logic for covariance calibration, source labels, blackout/spoofing modes, and MAVLink output mapping. | +| Storage | Offline satellite cache, descriptor index, FDR with no raw frame retention. | +| Autopilot | ArduPilot Plane, `GPS_INPUT` through pymavlink, MAVSDK for telemetry. | + +## Technology Evaluation + +| Layer | Selected | Alternatives Considered | Rationale | Risk | +|-------|----------|-------------------------|-----------|------| +| OS / GPU stack | JetPack Ubuntu + CUDA + TensorRT | Plain Ubuntu without JetPack | Required for Jetson acceleration and profiling. | Thermal/performance tuning. | +| Calibration / geometry | OpenCV 4.x | Custom NumPy-only geometry | Mature APIs for calibration, undistortion, homography, RANSAC. | Version pin and calibration quality. | +| VO / estimator | BASALT + project-owned safety/anchor wrapper | OpenVINS, Kimera-VIO, custom OpenCV/ESKF, ORB-SLAM3, VINS-Fusion | BASALT is the selected production VIO candidate; wrapper owns source labels, covariance gates, degraded modes, satellite-anchor acceptance, and MAVLink semantics. | BASALT confidence/covariance must be calibrated; nadir fixed-wing replay required. | +| VPR descriptors | DINOv2-VLAD / AnyLoc-style, model-size profiled, TensorRT only after fidelity check | MixVPR, SALAD, NetVLAD, classical BoW | Strong retrieval evidence; good offline descriptor model. | Memory/latency and embedding drift if optimized incorrectly. | +| Vector search | FAISS CPU-first on Jetson ARM64 | HNSWLIB, PostgreSQL/pgvector metadata-assisted search, brute-force NumPy, custom FAISS GPU build | Mature top-K search, save/load, PQ compression; PostgreSQL stores spatial/mission metadata around descriptor files. | CPU query latency must be profiled; GPU FAISS is not default on aarch64. | +| Local matching | DISK/ALIKED + LightGlue | SuperPoint+LightGlue, SIFT/ORB, LoFTR | Exact match outputs; Apache/BSD-friendly path; adaptive speed knobs. | Jetson profiling needed. | +| Raster cache | COG + PostgreSQL/PostGIS manifest + signed JSON sidecars | PMTiles, MBTiles, loose tile folders | COG fits geospatial raster and write-new-tile workflow; PostGIS supports spatial/freshness queries. | 10 GB budget pressure and local DB availability. | +| MAVLink | MAVSDK telemetry + pymavlink `GPS_INPUT` | MAVSDK-only, MAVProxy bridge | MAVSDK does telemetry well; `GPS_INPUT` needs raw field control. | Plane SITL validation. | +| FDR | PostgreSQL event index + CBOR/binary payload segments with optional Parquet export | Raw images, plain CSV | Queryable event metadata, bounded payload segments, no raw frame retention. | Schema and local DB availability. | +| Testing | ArduPilot Plane SITL + AerialVL/VPAir + EuRoC + representative flight replay | Public datasets only | No public dataset covers all ACs. | Representative data collection required. | + +## Tech Stack Summary + +- **Primary implementation**: Python for orchestration, test harness, cache tooling, and MAVLink integration; C++/TensorRT for hot-path vision if profiling requires it. +- **Vision utilities**: OpenCV 4.x. +- **Estimator**: BASALT VIO plus project-owned safety/anchor wrapper and mode machine. +- **Global retrieval**: DINOv2-VLAD style descriptors with CPU-first FAISS top-K search. +- **Local matching**: DISK/ALIKED + LightGlue; SuperPoint only after license review. +- **Cache**: COG imagery, PostgreSQL/PostGIS manifest metadata, signed JSON sidecars, FAISS index files. +- **Autopilot**: MAVSDK subscriptions plus pymavlink `GPS_INPUT`. +- **Validation**: public datasets for component de-risking, Plane SITL for integration, representative flight/replay data for acceptance. + +## Risk Assessment + +| Risk | Impact | Mitigation | +|------|--------|------------| +| VPR/local matching exceeds Jetson latency | AC-4.1 failure | Conditional VPR, top-K caps, downsampled descriptors, CPU FAISS profiling, TensorRT only after embedding-fidelity checks. | +| Descriptor cache exceeds 10 GB | AC-8.3/storage failure | PQ/compression, multi-scale budget report, split descriptor budget if needed. | +| GPL library accidentally becomes production dependency | Licensing issue | Keep OpenVINS/ORB-SLAM3 as reference only unless legal approves; BASALT is the production VIO candidate. | +| BASALT covariance under-reports real error | False-position safety budget failure | Calibrate wrapper covariance against OpenVINS covariance, ground truth replay, and satellite anchor residuals. | +| Plane failsafe differs from Copter docs | Safety behavior mismatch | Production-parameter ArduPilot Plane SITL gate. | +| `GPS_INPUT` velocity ignore flags behave unexpectedly | EKF drift or false velocity fusion | SITL tests for velocity fields, ignore flags, and `EK3_SRC1_*` source parameters. | +| Public datasets fail to represent Ukrainian agricultural terrain | False confidence | Require representative synchronized flight/replay data before AC signoff. | +| Thermal throttling | Latency regression | Hot-soak test and throttle logging per AC-NEW-5. | + +## Learning / Implementation Requirements + +- Jetson profiling with CUDA/TensorRT and memory instrumentation. +- ArduPilot Plane SITL, `GPS_INPUT`, GPS spoof/failsafe parameters. +- Geospatial raster formats: COG, CRS, tile matrices, m/px metadata, manifests. +- BASALT integration, covariance calibration, and Mahalanobis rejection in the safety/anchor wrapper. +- Aerial VPR benchmark methodology and georeference recall. diff --git a/_docs/02_document/FINAL_report.md b/_docs/02_document/FINAL_report.md new file mode 100644 index 0000000..e3f53f3 --- /dev/null +++ b/_docs/02_document/FINAL_report.md @@ -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 | diff --git a/_docs/02_document/architecture.md b/_docs/02_document/architecture.md new file mode 100644 index 0000000..3242eaf --- /dev/null +++ b/_docs/02_document/architecture.md @@ -0,0 +1,241 @@ +# GPS-Denied Onboard Localization — Architecture + +## Architecture Vision + +Build a Jetson-hosted onboard localization pipeline for fixed-wing GPS-denied flight. The hot path fuses fixed nadir camera frames and FC telemetry through OpenCV geometry, BASALT VIO, and a project-owned safety/anchor wrapper that emits calibrated `GPS_INPUT` estimates and QGC/FDR status. A triggered satellite-anchor path uses DINOv2-VLAD, CPU FAISS, ALIKED/DISK+LightGlue, and RANSAC against the offline cache; generated tiles are written back only with strict provenance and covariance gates. + +### Components / Responsibilities + +- Camera ingest/calibration: load frames, apply intrinsics/extrinsics, validate image quality. +- BASALT VIO adapter: produce relative camera+IMU motion from synchronized nav frames and FC IMU. +- Safety/anchor wrapper: own covariance calibration, source labels, degraded modes, anchor fusion, and `GPS_INPUT`. +- Satellite retrieval: retrieve VPR chunks from offline descriptor indexes. +- Anchor verification: run local matching/RANSAC and reject unsafe anchors. +- Cache/tile lifecycle: manage COGs, manifests, freshness, generated tiles, and sync metadata. +- MAVLink/GCS integration: consume FC telemetry and emit `GPS_INPUT`/QGC status. +- FDR/observability: record replayable mission evidence under storage caps. +- Validation harness: run still-image, public dataset, SITL, Jetson, and representative replay tests. + +### Principles / Non-Negotiables + +- No in-flight satellite-provider calls; runtime uses offline cache only. +- BASALT is a VIO component, not the safety authority. +- Confidence must be honest; covariance must grow in degraded modes. +- Heavy VPR/local matching is trigger-based, not per-frame. +- Raw nav/AI frames are not retained in normal operation. +- GPL VIO libraries remain reference-only unless explicitly approved. +- Plane SITL and Jetson hardware are release gates. +- Public datasets can de-risk, but representative synchronized flight data is required for final acceptance. + +## 1. System Context + +**Problem being solved**: During fixed-wing flight, GPS may be denied or spoofed. The onboard system must estimate WGS84 coordinates for navigation-camera frame centers and detected objects, stream `GPS_INPUT` to ArduPilot Plane, report confidence honestly, and maintain safety during VO failure, stale imagery, spoofing, and visual blackout. + +**System boundaries**: + +- In scope: onboard localization runtime, offline cache consumption, BASALT VIO integration, satellite anchor verification, MAVLink output, QGC status, FDR, generated tile metadata, validation harness. +- Out of scope: upstream commercial satellite-provider sourcing, Satellite Service ingest implementation, AI mission-camera detection itself, PX4 support, raw-frame retention as a normal operating mode. + +**External systems**: + +| System | Integration Type | Direction | Purpose | +|--------|------------------|-----------|---------| +| ArduPilot Plane FC | MAVLink | Inbound/Outbound | FC telemetry in, `GPS_INPUT` and status out | +| QGroundControl | MAVLink telemetry | Outbound | Downsampled operator status and failsafe messages | +| Azaion Suite Satellite Service | Offline file/cache sync | Inbound before flight, outbound after landing | Provides cache and receives generated tiles | +| Public/replay datasets | File/rosbag/fixture | Inbound to validation | De-risk BASALT, VPR, and anchor logic | + +## 2. Technology Stack + +| Layer | Technology | Version / Mode | Rationale | +|-------|------------|----------------|-----------| +| OS / GPU stack | JetPack Ubuntu + CUDA/TensorRT/ONNX Runtime | Jetson Orin Nano Super target | Required for production hardware profiling | +| Runtime language | Python + C++ | Python orchestration; C++ for BASALT/hot vision paths | Fits MAVLink/test tooling and native VIO dependencies | +| Geometry | OpenCV 4.x | Calibration, undistortion, homography, RANSAC/USAC | Mature utility layer | +| VIO | BASALT | Production candidate | BSD-friendly, strong benchmark evidence | +| VIO reference | OpenVINS | Reference/covariance baseline only | Strong EKF covariance story; GPLv3 risk | +| Backup VIO | Kimera-VIO | Backup candidate | BSD-friendly fallback with mono caveats | +| Local matching | ALIKED/DISK + LightGlue | Anchor verification and optional VO fallback | Strong learned correspondences; profile before hot-path use | +| Retrieval | DINOv2-VLAD + CPU FAISS | Triggered VPR only | Robust candidate retrieval under cache/offline constraints | +| Structured metadata DB | PostgreSQL + PostGIS | Onboard/local deployment | Spatial cache manifests, mission state, generated-tile metadata, and FDR event indexes | +| Cache imagery | COG + PostgreSQL/PostGIS manifest + signed JSON sidecars | Write-new COG objects | Efficient geospatial rasters with queryable spatial metadata and auditable sidecars | +| FDR | PostgreSQL event index + CBOR segment payloads, optional Parquet export | Per-flight rollover | Queryable event metadata with compact bounded payload segments | +| MAVLink | MAVSDK + pymavlink | MAVSDK telemetry, pymavlink `GPS_INPUT` | Exact output control | + +**Key constraints from restrictions.md**: + +- Jetson has 8 GB shared memory and 25 W thermal envelope, so heavy VPR/local matching cannot run every frame. +- Runtime must be offline with respect to satellite providers, so all imagery and descriptors are preloaded. +- The camera is fixed nadir; all VO choices must be validated against low-parallax/planar terrain. +- ADTi public specs conflict with current assumptions on resolution, continuous FPS, and operating temperature; manufacturer specs must be pinned before implementation. + +## 3. Deployment Model + +**Environments**: Development replay, public-dataset replay, Jetson hardware validation, Plane SITL, representative flight/replay rig. + +**Infrastructure**: + +- Onboard production runtime runs on the Jetson companion computer, not in cloud. +- Replay/test infrastructure may use Docker for deterministic fixture tests. +- Release gates require local Jetson hardware and ArduPilot Plane SITL. + +**Environment-specific configuration**: + +| Config | Development | Production | +|--------|-------------|------------| +| Satellite cache | Small fixture cache | Preloaded operational-area cache | +| Descriptor index | Fixture FAISS index | CPU-first FAISS index with PQ/IVF if needed | +| Secrets/signing | Local test keys | Mission/cache signing keys from Suite process | +| FDR | Local temp output | Per-flight bounded NVMe storage | +| MAVLink | SITL/replay | Physical FC telemetry link | + +## 4. Data Model Overview + +**Core entities**: + +| Entity | Description | Owned By Component | +|--------|-------------|--------------------| +| FrameRecord | Navigation-camera frame metadata, total-occlusion status, and processing status | Camera ingest/calibration | +| TelemetrySample | FC IMU, attitude, airspeed, altitude, GPS health | MAVLink/GCS integration | +| VioState | BASALT-relative pose/velocity/bias output and quality metadata | BASALT VIO adapter | +| PositionEstimate | WGS84 estimate, covariance, source label, fix type, anchor age | Safety/anchor wrapper | +| VprChunk | Retrieval unit over cache imagery and descriptors | Satellite retrieval | +| AnchorCandidate | Retrieved tile/chunk with local-match and RANSAC evidence | Anchor verification | +| CacheTile | COG tile plus manifest and sidecar metadata | Cache/tile lifecycle | +| GeneratedTile | In-flight orthorectified tile with trust/provenance metadata | Cache/tile lifecycle | +| FdrSegment | Bounded replayable log segment | FDR/observability | + +**Data flow summary**: + +- Frame quality/total-occlusion gate + telemetry -> BASALT VIO when usable, or IMU-only degraded mode when not -> safety/anchor wrapper -> `GPS_INPUT`, QGC, FDR. +- Relocalization trigger -> DINOv2-VLAD/FAISS -> ALIKED/DISK+LightGlue/RANSAC -> accepted/rejected anchor. +- High-confidence pose + frame -> generated tile -> manifest/sidecar -> post-flight Satellite Service sync. + +## 5. Integration Points + +### Internal Communication + +| From | To | Protocol | Pattern | Notes | +|------|----|----------|---------|-------| +| Camera ingest/calibration | BASALT VIO adapter | In-process queue or shared frame bus | Streaming | Timestamp discipline is critical | +| MAVLink telemetry | BASALT VIO adapter | In-process telemetry buffer | Streaming | IMU/attitude/altitude sync | +| BASALT VIO adapter | Safety/anchor wrapper | Typed state messages | Streaming | Wrapper calibrates confidence | +| Safety/anchor wrapper | Satellite retrieval | Command | Triggered request | Only on relocalization conditions | +| Satellite retrieval | Anchor verification | Candidate list | Request-response | Dynamic top-K | +| Anchor verification | Safety/anchor wrapper | Anchor decision | Request-response | Includes MRE/inliers/provenance | +| Safety/anchor wrapper | MAVLink/GCS integration | Position/status DTO | Streaming | `GPS_INPUT` emitted frame-by-frame | +| Safety/anchor wrapper | FDR/observability | Append-only events | Streaming | Bounded segments | + +### External Integrations + +| External System | Protocol | Auth | Failure Mode | +|-----------------|----------|------|--------------| +| ArduPilot Plane | MAVLink | Source/system ID allowlist | Degrade/failsafe; never trust spoofed GPS blindly | +| QGroundControl | MAVLink | FC telemetry path | Downsampled status may be delayed but local FDR remains authoritative | +| Satellite Service | Offline cache files | Signed manifests/sidecars | Missing/stale cache causes degraded mode, not network fetch | +| Public datasets | File/rosbag | License constraints | Not final acceptance unless representative and license-compatible | + +## 6. Non-Functional Requirements + +| Requirement | Target | Measurement | Priority | +|-------------|--------|-------------|----------| +| Frame latency | <400 ms p95 | Capture/replay timestamp to emitted estimate | High | +| Memory | <8 GB shared | Jetson monitoring | High | +| First fix | <30 s p95 | 50 cold starts | High | +| Thermal | No throttle at 25 W / +50 C | 8-hour hot-soak | High | +| FDR storage | <=64 GB/flight | 8-hour synthetic load | High | +| Cache storage | ~10 GB persistent budget | Full mission cache accounting | High | +| False position | P(error >500 m) <0.1%, >1 km <0.01% | Monte Carlo/replay | High | + +## 7. Security Architecture + +**Authentication / trust boundary**: + +- Runtime accepts only local cache files with valid manifest/signature/provenance. +- MAVLink input is filtered by expected source/system IDs and FC health semantics. + +**Data protection**: + +- At rest: FDR and cache sidecars should be integrity protected; mission secrets/signing keys are not stored in code. +- In transit: no in-flight satellite-provider network dependency; MAVLink link security depends on FC/GCS deployment. + +**Audit logging**: + +- FDR records estimates, covariance, anchors, rejected anchors, cache validation failures, spoofing/blackout transitions, emitted `GPS_INPUT`, resource health, and tile-write decisions. + +## 8. Key Architectural Decisions + +### ADR-001: BASALT As Production VIO Candidate + +**Context**: A naive OpenCV-only VIO implementation is risky, while OpenVINS has GPLv3 production constraints. + +**Decision**: Use BASALT as the production relative VIO candidate and keep OpenVINS as covariance/reference baseline. + +**Alternatives considered**: + +1. OpenVINS as production core — rejected by default because of GPLv3 and generic VIO ownership. +2. Kimera-VIO — retained as backup due to BSD license but mono-inertial caveats. +3. Fully custom OpenCV/ESKF — fallback only because implementation burden is high. + +**Consequences**: The safety/anchor wrapper must calibrate confidence around BASALT and prove it on representative data. + +### ADR-002: ALIKED-LightGlue Role + +**Context**: ALIKED-LightGlue can produce strong local correspondences and can support frame-to-frame homography/pose estimation. + +**Decision**: Use ALIKED/DISK+LightGlue for satellite-anchor verification and evaluate it as an optional VO fallback/keyframe-assist path, not as the default BASALT replacement. + +**Alternatives considered**: + +1. Per-frame ALIKED-LightGlue VO hot path — deferred until Jetson profiling proves latency/memory fit. +2. SIFT/ORB-only matching — retained as regression baseline, weaker under cross-domain conditions. +3. SuperPoint+LightGlue — license-gated. + +**Consequences**: Implementation tasks must benchmark ALIKED-LightGlue on frame-to-frame VO and cross-domain anchor workloads separately. + +### ADR-003: Cache Metadata Format + +**Context**: JSON is simple and auditable, but operational cache queries need spatial indexing, freshness filters, update safety, and integration with the project PostgreSQL database. + +**Decision**: Use PostgreSQL with PostGIS as the primary cache manifest/index database, with signed JSON sidecars for each tile/generated tile for auditability and interchange. + +**Alternatives considered**: + +1. JSON-only manifest — simpler, but weak for query/update scale, spatial search, and consistency. +2. Embedded single-file metadata DB — efficient for small deployments, but rejected because the project will use PostgreSQL/PostGIS. + +**Consequences**: The cache lifecycle component owns PostgreSQL migrations, PostGIS indexes, signature checks, and sidecar/db consistency. + +### ADR-004: FDR Format + +**Context**: The FDR must be compact, bounded, replayable, and exportable for analysis. + +**Decision**: Use PostgreSQL for FDR event indexes and mission-query metadata, with CBOR-backed segment payloads for bounded append-heavy runtime data and optional Parquet export after flight. + +**Alternatives considered**: + +1. Plain CSV — rejected for type safety, size, and complex payloads. +2. Parquet as primary onboard format — good analytics, but less ideal as the runtime append/rollover path. + +**Consequences**: FDR implementation must define PostgreSQL tables/indexes, CBOR segment schema, rollover behavior, and export tooling. + +### ADR-006: Total Occlusion Before VIO + +**Context**: BASALT should not receive frames that are completely unusable because of lens cover, cloud/whiteout, decode failure, extreme exposure, or other total visual blackout. + +**Decision**: Camera ingest performs a pre-VIO total-occlusion/blackout check. Total occlusion bypasses BASALT for that frame, sends a `total_occlusion` or `visual_blackout` degradation signal to the safety wrapper, and continues IMU-only propagation from the last trusted state. + +**Alternatives considered**: + +1. Let BASALT detect every visual failure — rejected because total occlusion is cheaper and safer to catch before the VIO hot path. +2. Drop frames silently — rejected because the wrapper must grow covariance and emit honest degraded output. + +**Consequences**: The camera component must expose `occlusion_status`, and tests must assert mode transition to `dead_reckoned`/failsafe under total blackout. + +### ADR-005: Public Dataset Strategy + +**Context**: Current project sample data lacks synchronized IMU and ground-truth trajectory. + +**Decision**: Prioritize MUN-FRL for synchronized nadir camera + IMU + GNSS/ground truth; use ALTO for aerial localization/VPR and long nadir trajectories; investigate Kagaru/EPFL for fixed-wing/farmland relevance; use EuRoC/UZH FPV only as VIO proxies if license-compatible. + +**Consequences**: Public datasets de-risk components but do not replace representative target flight data for final acceptance. diff --git a/_docs/02_document/common-helpers/01_helper_geo_geometry.md b/_docs/02_document/common-helpers/01_helper_geo_geometry.md new file mode 100644 index 0000000..5a01f7d --- /dev/null +++ b/_docs/02_document/common-helpers/01_helper_geo_geometry.md @@ -0,0 +1,30 @@ +# Geo Geometry Helper + +## Purpose + +Shared geospatial and camera-geometry utilities used by camera ingest, safety wrapper, cache lifecycle, anchor verification, and validation. + +## Responsibilities + +- WGS84 to local tangent plane conversions. +- Haversine/ground-distance calculations. +- Ground sampling distance calculations. +- Camera footprint projection from intrinsics, extrinsics, altitude, and attitude. +- Homography and covariance unit conversions for reporting. + +## Non-Responsibilities + +- No image matching. +- No state estimation. +- No MAVLink emission. +- No cache policy decisions. + +## Consumers + +| Component | Usage | +|-----------|-------| +| Camera ingest/calibration | Footprint and calibration sanity checks | +| Safety/anchor wrapper | Distance/covariance/unit conversion | +| Anchor verification | Pixel-to-ground error reporting | +| Cache/tile lifecycle | Tile footprint metadata | +| Validation harness | Error thresholds and reports | diff --git a/_docs/02_document/common-helpers/02_helper_time_sync.md b/_docs/02_document/common-helpers/02_helper_time_sync.md new file mode 100644 index 0000000..b5b2f3c --- /dev/null +++ b/_docs/02_document/common-helpers/02_helper_time_sync.md @@ -0,0 +1,29 @@ +# Time Sync Helper + +## Purpose + +Shared timestamp validation and alignment utilities for frame, IMU, telemetry, FDR, and replay data. + +## Responsibilities + +- Monotonic timestamp checks. +- Frame-to-IMU window selection. +- Clock-domain conversion metadata. +- Replay ordering validation. +- Gap and jitter metrics. + +## Non-Responsibilities + +- No VIO state estimation. +- No MAVLink parsing beyond normalized timestamp fields. +- No recovery policy; callers decide whether to degrade or reject. + +## Consumers + +| Component | Usage | +|-----------|-------| +| Camera ingest/calibration | Frame ordering and timestamp metadata | +| BASALT VIO adapter | IMU/frame synchronization | +| MAVLink/GCS integration | Telemetry timestamp normalization | +| FDR/observability | Segment ordering | +| Validation harness | Fixture validation | diff --git a/_docs/02_document/components/01_camera_ingest_calibration/description.md b/_docs/02_document/components/01_camera_ingest_calibration/description.md new file mode 100644 index 0000000..7649dd2 --- /dev/null +++ b/_docs/02_document/components/01_camera_ingest_calibration/description.md @@ -0,0 +1,115 @@ +# Camera Ingest And Calibration + +## 1. High-Level Overview + +**Purpose**: Ingest navigation-camera frames, attach timestamps and calibration metadata, undistort/normalize imagery, detect total occlusion/blackout before VIO, and classify image quality before VIO or satellite matching consumes it. + +**Architectural Pattern**: Streaming adapter + validation gate. + +**Upstream dependencies**: Navigation camera, camera calibration files. + +**Downstream consumers**: BASALT VIO adapter, satellite retrieval, anchor verification, cache/tile lifecycle, FDR. + +## 2. Internal Interfaces + +### Interface: `FrameProvider` + +| Method | Input | Output | Async | Error Types | +|--------|-------|--------|-------|-------------| +| `next_frame` | `FrameRequest` | `FramePacket` | Yes | `FrameUnavailable`, `CalibrationMissing`, `InvalidFrame` | +| `detect_occlusion` | `FramePacket` | `OcclusionReport` | No | `InvalidFrame` | +| `classify_quality` | `FramePacket` | `ImageQualityReport` | No | `InvalidFrame` | + +**Input DTOs**: + +```yaml +FrameRequest: + source: enum(live_camera, replay_file) + timestamp_ns: integer optional +``` + +**Output DTOs**: + +```yaml +FramePacket: + frame_id: string + timestamp_ns: integer + image_ref: path_or_buffer + camera_calibration_id: string + altitude_hint_m: number optional + occlusion: OcclusionReport + quality: ImageQualityReport + +OcclusionReport: + status: enum(clear, partial_occlusion, total_occlusion, blackout) + reason: enum(cloud, lens_cover, whiteout, decode_failure, underexposed, overexposed, unknown) optional + usable_for_vio: boolean + usable_for_anchor: boolean + +ImageQualityReport: + usable_for_vio: boolean + usable_for_anchor: boolean + blackout_detected: boolean + blur_score: number + texture_score: number +``` + +## 3. Data Access Patterns + +| Query | Frequency | Hot Path | Index Needed | +|-------|-----------|----------|--------------| +| Load calibration by ID | Startup | Yes | No | +| Read replay frame | Test/replay | Yes | File order | + +## 4. Implementation Details + +**State Management**: Maintains current camera calibration version and frame sequence state. + +**Key Dependencies**: + +| Library | Purpose | +|---------|---------| +| OpenCV | Decode, undistort, homography support, image metrics | +| Camera SDK / V4L2 / GigE SDK | Live camera access once interface is selected | + +**Error Handling Strategy**: +- Camera or decode errors emit degraded quality and FDR events. +- Total occlusion or blackout sets `usable_for_vio=false`, bypasses BASALT for that frame, and emits a degradation signal to the safety/anchor wrapper. +- Missing calibration blocks production startup. +- ADTi public spec mismatch is tracked as a verification blocker until manufacturer spec is pinned. + +## 5. Extensions and Helpers + +| Helper | Purpose | Used By | +|--------|---------|---------| +| `geo_geometry_helper` | Coordinate transforms, GSD, WGS84/local conversions | Camera ingest, safety wrapper, cache lifecycle | + +## 6. Caveats & Edge Cases + +**Known limitations**: +- Public ADTi pages list 2 fps continuous capture and -10..40 C operating range; project assumptions need manufacturer verification. +- Live camera interface is TBD. +- Total occlusion detection must be conservative: false positives cause temporary IMU-only degradation, while false negatives can feed unusable frames into VIO. + +**Performance bottlenecks**: +- Full-resolution preprocessing must stay inside the <400 ms p95 pipeline budget. + +## 7. Dependency Graph + +**Must be implemented after**: none. + +**Can be implemented in parallel with**: cache/tile lifecycle, MAVLink/GCS integration. + +**Blocks**: BASALT VIO adapter, anchor verification, generated tile lifecycle. + +## 8. Logging Strategy + +| Log Level | When | Example | +|-----------|------|---------| +| ERROR | Camera unavailable or calibration missing | `camera_calibration_missing id=...` | +| WARN | Frame degraded or occluded | `frame_quality_degraded occlusion=total_occlusion blur=... texture=...` | +| INFO | Calibration loaded | `camera_calibration_loaded version=...` | + +**Log format**: FDR structured event. + +**Log storage**: FDR segment and health log. diff --git a/_docs/02_document/components/01_camera_ingest_calibration/tests.md b/_docs/02_document/components/01_camera_ingest_calibration/tests.md new file mode 100644 index 0000000..b98d0a3 --- /dev/null +++ b/_docs/02_document/components/01_camera_ingest_calibration/tests.md @@ -0,0 +1,139 @@ +# Test Specification — Camera Ingest And Calibration + +## Acceptance Criteria Traceability + +| AC ID | Acceptance Criterion | Test IDs | Coverage | +|-------|---------------------|----------|----------| +| AC-2.1a | VO registration uses only normal usable frames | IT-01, AT-01 | Covered | +| AC-3.5 | Visual blackout switches to degraded mode quickly | IT-02, AT-02 | Covered | +| AC-4.1 | Capture-to-output latency budget | PT-01 | Covered | +| AC-4.2 | Jetson memory budget | PT-01 | Covered | +| AC-8.4 | Mid-flight tile generation input eligibility | IT-03 | Covered | +| AC-8.5 | No raw frame retention | ST-01 | Covered | +| AC-NEW-8 | Full blackout/occlusion degraded-mode trigger | IT-02, AT-02 | Covered | + +## Blackbox Tests + +### IT-01: Usable Frame Classification + +**Summary**: Verify normal nadir frames are marked usable for VIO and anchor matching. + +**Traces to**: AC-2.1a + +**Input data**: Project still images plus calibration metadata. + +**Expected result**: `FramePacket.quality.usable_for_vio=true`, `usable_for_anchor=true`, and `occlusion.status=clear` for normal daytime textured frames. + +**Max execution time**: 100 ms per frame. + +**Dependencies**: Calibration file, replay fixture. + +--- + +### IT-02: Total Occlusion Gate Before VIO + +**Summary**: Verify total occlusion is detected before BASALT receives the frame. + +**Traces to**: AC-3.5, AC-NEW-8 + +**Input data**: Black/white/covered-lens frames, corrupt frame fixture, low-texture whiteout frames. + +**Expected result**: `occlusion.status` is `total_occlusion` or `blackout`, `usable_for_vio=false`, `usable_for_anchor=false`, and a degradation signal is emitted to the safety wrapper. + +**Max execution time**: 100 ms per frame. + +**Dependencies**: Safety wrapper test double. + +--- + +### IT-03: Tile Generation Eligibility Metadata + +**Summary**: Verify frame metadata required for generated tiles is available without persisting raw frames. + +**Traces to**: AC-8.4, AC-8.5 + +**Input data**: Valid frame, altitude hint, calibration, pose fixture. + +**Expected result**: Frame metadata supports orthorectification handoff; raw frame is not retained after processing outside allowed FDR thumbnail exception. + +**Max execution time**: 100 ms per frame. + +**Dependencies**: Cache lifecycle test double. + +## Performance Tests + +### PT-01: Ingest And Quality Latency + +**Summary**: Verify decode, calibration lookup, occlusion detection, and quality classification stay inside the system latency budget. + +**Traces to**: AC-4.1, AC-4.2 + +**Load scenario**: +- Input rate: target camera/replay rate. +- Duration: 30 minutes replay. +- Dataset: project still images plus synthetic occlusion frames. + +| Metric | Target | Failure Threshold | +|--------|--------|-------------------| +| Per-frame ingest p95 | <=100 ms | >150 ms | +| Memory contribution | <=1 GB | >1.5 GB | +| Dropped frames | <=10% under sustained load | >10% | + +**Resource limits**: Jetson shared memory remains below system 8 GB cap. + +## Security Tests + +### ST-01: Raw Frame Retention Check + +**Summary**: Verify normal operation does not persist raw navigation frames. + +**Traces to**: AC-8.5 + +**Attack vector**: Sensitive raw imagery remains on disk after processing. + +**Test procedure**: +1. Run replay with normal and failed tile-generation frames. +2. Inspect output directories and FDR artifacts. + +**Expected behavior**: Only metadata, generated tiles, and allowed low-rate failed-frame thumbnails are retained. + +**Pass criteria**: No raw full-resolution frames remain after teardown. + +## Acceptance Tests + +### AT-01: Normal Frame Enters VIO + +**Summary**: Confirm normal usable frames are passed to BASALT. + +**Traces to**: AC-2.1a + +| Step | Action | Expected Result | +|------|--------|-----------------| +| 1 | Feed a calibrated normal frame | Occlusion status is `clear` | +| 2 | Process quality gate | Frame is emitted to BASALT adapter | + +--- + +### AT-02: Occluded Frame Bypasses VIO + +**Summary**: Confirm full occlusion triggers IMU-only degraded path. + +**Traces to**: AC-3.5, AC-NEW-8 + +| Step | Action | Expected Result | +|------|--------|-----------------| +| 1 | Feed total-occlusion frame | `usable_for_vio=false` | +| 2 | Observe downstream routing | BASALT is bypassed and safety wrapper receives degradation signal | + +## Test Data Management + +| Data Set | Description | Source | Size | +|----------|-------------|--------|------| +| `project_60_still_images` | Normal nadir frames | `_docs/00_problem/input_data/` | Project data | +| `synthetic_occlusion_frames` | Black/white/corrupt/whiteout frames | Generated fixture | Small | + +**Setup procedure**: Load calibration fixture and mount read-only frame data. + +**Teardown procedure**: Remove run-scoped temp directories and verify no raw-frame persistence. + +**Data isolation strategy**: Each run writes to a unique `test-results//` directory. diff --git a/_docs/02_document/components/02_basalt_vio_adapter/description.md b/_docs/02_document/components/02_basalt_vio_adapter/description.md new file mode 100644 index 0000000..eb04d26 --- /dev/null +++ b/_docs/02_document/components/02_basalt_vio_adapter/description.md @@ -0,0 +1,92 @@ +# BASALT VIO Adapter + +## 1. High-Level Overview + +**Purpose**: Wrap BASALT as a replaceable relative VIO component that consumes calibrated frames and FC IMU data, then emits relative pose/velocity/bias state and tracking quality. + +**Architectural Pattern**: Adapter / anti-corruption layer. + +**Upstream dependencies**: Camera ingest/calibration, MAVLink telemetry stream. + +**Downstream consumers**: Safety/anchor wrapper, validation harness, FDR. + +## 2. Internal Interfaces + +### Interface: `VioAdapter` + +| Method | Input | Output | Async | Error Types | +|--------|-------|--------|-------|-------------| +| `initialize` | `VioInitRequest` | `VioInitResult` | No | `CalibrationInvalid`, `DatasetUnsupported` | +| `process` | `VioInputPacket` | `VioStatePacket` | Yes | `TrackingLost`, `TimestampMismatch` | +| `health` | none | `VioHealth` | No | none | + +**Input DTOs**: + +```yaml +VioInputPacket: + frame: FramePacket + imu_samples: list[TelemetrySample] + attitude_sample: TelemetrySample optional +``` + +**Output DTOs**: + +```yaml +VioStatePacket: + timestamp_ns: integer + relative_pose: transform + velocity: vector3 + bias_estimate: object optional + tracking_quality: number + completed: boolean + covariance_hint: matrix optional +``` + +## 3. Data Access Patterns + +No persistent production data ownership. Reads calibration/config at startup and emits state to downstream consumers. + +## 4. Implementation Details + +**State Management**: Owns BASALT runtime state and resets only through explicit wrapper command. + +**Key Dependencies**: + +| Library | Purpose | +|---------|---------| +| BASALT | Relative visual-inertial odometry | +| Eigen/Sophus or BASALT native math stack | Pose and transform representation | + +**Error Handling Strategy**: +- Tracking loss is surfaced to the safety/anchor wrapper, not hidden. +- Timestamp/camera-IMU sync violations fail the packet and are logged. +- The adapter never emits WGS84 coordinates; absolute semantics belong to the wrapper. + +## 5. Caveats & Edge Cases + +**Known limitations**: +- BASALT has no special fixed-wing nadir mode; validation must prove fit under low-parallax/planar terrain. +- BASALT covariance/confidence output is not the product authority; wrapper calibration is required. + +**Performance bottlenecks**: +- Native VIO runtime and image resolution can exceed Jetson budget if not tuned. + +## 6. Dependency Graph + +**Must be implemented after**: Camera ingest/calibration, MAVLink telemetry DTO definitions. + +**Can be implemented in parallel with**: satellite retrieval, cache lifecycle. + +**Blocks**: Safety/anchor wrapper final integration. + +## 7. Logging Strategy + +| Log Level | When | Example | +|-----------|------|---------| +| ERROR | BASALT initialization fails | `basalt_init_failed reason=...` | +| WARN | Tracking quality drops | `vio_tracking_degraded quality=...` | +| INFO | VIO reset/reinitialized | `vio_reset cause=...` | + +**Log format**: FDR structured event. + +**Log storage**: FDR segment. diff --git a/_docs/02_document/components/02_basalt_vio_adapter/tests.md b/_docs/02_document/components/02_basalt_vio_adapter/tests.md new file mode 100644 index 0000000..63dc625 --- /dev/null +++ b/_docs/02_document/components/02_basalt_vio_adapter/tests.md @@ -0,0 +1,140 @@ +# Test Specification — BASALT VIO Adapter + +## Acceptance Criteria Traceability + +| AC ID | Acceptance Criterion | Test IDs | Coverage | +|-------|---------------------|----------|----------| +| AC-1.3 | Drift between anchors and anchor-age reporting input | IT-02, AT-01 | Covered | +| AC-2.1a | >95% VO registration on normal segments | IT-01, AT-01 | Covered | +| AC-2.2 | <1.0 px VO MRE | IT-01 | Covered | +| AC-3.1 | Handles 350 m outliers/tilt | IT-03 | Covered | +| AC-3.2 | Sharp turns trigger relocalization path | IT-04 | Covered | +| AC-3.4 | Loss threshold feeds relocalization/dead reckoning | IT-04 | Covered | +| AC-4.1 | Hot-path latency | PT-01 | Covered | +| AC-4.2 | Jetson memory budget | PT-01 | Covered | + +## Blackbox Tests + +### IT-01: Public Dataset VIO Replay + +**Summary**: Verify BASALT adapter produces relative motion for synchronized camera/IMU replay. + +**Traces to**: AC-2.1a, AC-2.2 + +**Input data**: MUN-FRL preferred slice, or representative synchronized nav-camera + IMU + ground truth. + +**Expected result**: VO registration succeeds for >95% of normal usable frames; frame-to-frame MRE <1.0 px where ground-truth/feature evaluation supports it. + +**Max execution time**: Dataset-dependent; report per-frame latency. + +**Dependencies**: Camera ingest, MAVLink telemetry/replay, calibration fixtures. + +--- + +### IT-02: Relative Drift Reporting + +**Summary**: Verify adapter emits state needed for wrapper drift and anchor-age accounting. + +**Traces to**: AC-1.3 + +**Input data**: Segment with two known satellite anchors and IMU samples. + +**Expected result**: Adapter emits continuous `VioStatePacket` values with timestamps and quality, enabling wrapper to compare VO extrapolation to next anchor. + +**Max execution time**: Dataset-dependent. + +**Dependencies**: Safety wrapper test harness. + +--- + +### IT-03: Tilt/Outlier Robustness + +**Summary**: Verify adapter reports degraded tracking without false success under tilt/outlier cases. + +**Traces to**: AC-3.1 + +**Input data**: Replay segment with synthetic ±20° tilt and up to 350 m apparent outlier. + +**Expected result**: Adapter either tracks with quality metadata or emits `TrackingLost`; it never hides a failure as high-quality VIO. + +**Max execution time**: 15 minutes per fixture. + +--- + +### IT-04: Sharp Turn / Loss Signal + +**Summary**: Verify sharp turns and disconnected visual overlap produce wrapper-visible failure signals. + +**Traces to**: AC-3.2, AC-3.4 + +**Input data**: <5% overlap sequence with heading change <70°. + +**Expected result**: Adapter emits low tracking quality or `TrackingLost` within the loss window, allowing relocalization trigger. + +**Max execution time**: 10 minutes. + +## Performance Tests + +### PT-01: BASALT Adapter Runtime Budget + +**Summary**: Verify VIO processing does not consume the full <400 ms system p95 budget. + +**Traces to**: AC-4.1, AC-4.2 + +**Load scenario**: +- Input: synchronized public/representative replay. +- Duration: 30 minutes plus release long-run slice. +- Target: Jetson Orin Nano Super. + +| Metric | Target | Failure Threshold | +|--------|--------|-------------------| +| Adapter p95 latency | <=250 ms | >300 ms | +| Memory contribution | <=3 GB | >4 GB | +| Tracking failure on normal segments | <5% | >=5% | + +**Resource limits**: Total system memory remains below 8 GB. + +## Security Tests + +### ST-01: Timestamp Injection Rejection + +**Summary**: Verify malformed or non-monotonic timestamps do not produce trusted VIO state. + +**Traces to**: AC-NEW-4 + +**Attack vector**: Replay or telemetry timestamp manipulation. + +**Test procedure**: +1. Feed non-monotonic frame and IMU timestamps. +2. Observe adapter output. + +**Expected behavior**: Adapter returns `TimestampMismatch` or low-quality failure; wrapper does not trust the state. + +**Pass criteria**: No high-quality VIO state is emitted from malformed timing. + +## Acceptance Tests + +### AT-01: Normal VIO State Contract + +**Summary**: Confirm adapter output contract supports downstream localization. + +**Traces to**: AC-1.3, AC-2.1a + +| Step | Action | Expected Result | +|------|--------|-----------------| +| 1 | Initialize with calibrated frame/IMU config | `VioInitResult` succeeds | +| 2 | Replay normal frames | `VioStatePacket` includes timestamp, relative pose, velocity, tracking quality | +| 3 | End segment | State stream is continuous enough for wrapper drift accounting | + +## Test Data Management + +| Data Set | Description | Source | Size | +|----------|-------------|--------|------| +| `public_nadir_vio_candidates` | MUN-FRL/ALTO/Kagaru/EPFL slices | Public pinned fixtures | Dataset-dependent | +| `representative_sync_replay` | Target camera + FC IMU + ground truth | Project collection | TBD | + +**Setup procedure**: Pin calibration/extrinsics and mount read-only synchronized replay data. + +**Teardown procedure**: Remove generated result reports and adapter temp state. + +**Data isolation strategy**: One run directory per dataset slice and configuration hash. diff --git a/_docs/02_document/components/03_safety_anchor_wrapper/description.md b/_docs/02_document/components/03_safety_anchor_wrapper/description.md new file mode 100644 index 0000000..1d790b2 --- /dev/null +++ b/_docs/02_document/components/03_safety_anchor_wrapper/description.md @@ -0,0 +1,106 @@ +# Safety And Anchor Wrapper + +## 1. High-Level Overview + +**Purpose**: Own the authoritative localization state, confidence calibration, source labels, anchor fusion, degraded modes, tile-write gates, and MAVLink output semantics. + +**Architectural Pattern**: Stateful coordinator / safety facade. + +**Upstream dependencies**: BASALT VIO adapter, anchor verification, MAVLink telemetry, camera quality reports. + +**Downstream consumers**: MAVLink/GCS integration, FDR, cache/tile lifecycle, validation harness. + +## 2. Internal Interfaces + +### Interface: `LocalizationStateMachine` + +| Method | Input | Output | Async | Error Types | +|--------|-------|--------|-------|-------------| +| `update_vio` | `VioStatePacket` | `PositionEstimate` | Yes | `StateInconsistent` | +| `consider_anchor` | `AnchorDecision` | `AnchorAcceptanceResult` | No | `AnchorRejected` | +| `degrade` | `DegradationSignal` | `PositionEstimate` | No | none | +| `propagate_imu_only` | `ImuOnlyPropagationRequest` | `PositionEstimate` | Yes | `InsufficientTelemetry` | +| `tile_write_eligibility` | `FramePacket` | `TileWriteDecision` | No | none | + +**Input DTOs**: + +```yaml +AnchorDecision: + candidate_id: string + timestamp_ns: integer + estimated_pose_wgs84: object + inlier_count: integer + mre_px: number + tile_freshness_status: enum + provenance_status: enum + +DegradationSignal: + type: enum(total_occlusion, visual_blackout, gps_spoofing, covariance_growth, tracking_lost) + timestamp_ns: integer + +ImuOnlyPropagationRequest: + last_trusted_estimate: PositionEstimate + imu_samples: list[TelemetrySample] + elapsed_blackout_ms: integer + reason: enum(total_occlusion, visual_blackout, tracking_lost) +``` + +**Output DTOs**: + +```yaml +PositionEstimate: + timestamp_ns: integer + lat_deg: number + lon_deg: number + alt_msl_m: number + covariance_95_semi_major_m: number + source_label: enum(satellite_anchored, vo_extrapolated, dead_reckoned) + fix_type: integer + horiz_accuracy_m: number + last_satellite_anchor_age_ms: integer +``` + +## 3. Data Access Patterns + +No direct tile/image storage ownership. Writes all decisions to FDR via observability component. + +## 4. Implementation Details + +**State Management**: Owns the authoritative state machine and covariance growth model. + +**Error Handling Strategy**: +- Reject uncertain anchors by default. +- Never emit optimistic accuracy when confidence is degraded. +- On total occlusion or visual blackout, do not call VIO for that frame; propagate from the last trusted state with IMU-only dynamics, set `source_label=dead_reckoned`, and grow covariance monotonically. +- If covariance or blackout thresholds exceed AC limits, emit no-fix/failsafe semantics. +- Treat cache freshness and provenance as evidence carried by `AnchorDecision`; do not call the cache lifecycle component directly during anchor acceptance. + +## 5. Caveats & Edge Cases + +**Known limitations**: +- Final covariance calibration requires representative synchronized data. +- The wrapper must stay independent of BASALT internals so VIO can be replaced. +- IMU-only propagation is an emergency bridge, not a reliable long-duration localization mode; the spec requires failsafe/no-fix once time or covariance thresholds are exceeded. + +**Potential race conditions**: +- A delayed anchor result must be checked against current timestamp/state before acceptance. + +## 6. Dependency Graph + +**Must be implemented after**: VIO DTOs, anchor DTOs, MAVLink output contract. + +**Can be implemented in parallel with**: FDR schema after DTOs stabilize. + +**Blocks**: MAVLink production output, tile-write lifecycle, end-to-end validation. + +## 7. Logging Strategy + +| Log Level | When | Example | +|-----------|------|---------| +| ERROR | State invariant violation | `localization_state_inconsistent reason=...` | +| WARN | Anchor rejected or mode degraded | `anchor_rejected reason=mahalanobis_gate` | +| INFO | Mode transition | `source_label_changed from=vo_extrapolated to=dead_reckoned reason=total_occlusion` | + +**Log format**: FDR structured event. + +**Log storage**: FDR segment and QGC status for operator-critical events. diff --git a/_docs/02_document/components/03_safety_anchor_wrapper/tests.md b/_docs/02_document/components/03_safety_anchor_wrapper/tests.md new file mode 100644 index 0000000..438bbfd --- /dev/null +++ b/_docs/02_document/components/03_safety_anchor_wrapper/tests.md @@ -0,0 +1,208 @@ +# Test Specification — Safety And Anchor Wrapper + +## Acceptance Criteria Traceability + +| AC ID | Acceptance Criterion | Test IDs | Coverage | +|-------|---------------------|----------|----------| +| AC-1.1 | >=80% within 50 m | AT-01 | Covered | +| AC-1.2 | >=50% within 20 m | AT-01 | Covered | +| AC-1.3 | Drift and anchor age | IT-01 | Covered | +| AC-1.4 | Quantitative confidence + label | IT-02, AT-02 | Covered | +| AC-3.4 | Relocalization after no-position window | IT-03 | Covered | +| AC-3.5 | Blackout to dead reckoned | IT-04, AT-03 | Covered | +| AC-4.3 | GPS_INPUT semantics source fields | IT-05 | Covered | +| AC-4.4 | Frame-by-frame streaming | PT-01 | Covered | +| AC-4.5 | Correction updates | IT-06 | Covered | +| AC-5.1 | Initialize from FC state | IT-07 | Covered | +| AC-5.2 | >3 s no-estimate fallback | IT-03 | Covered | +| AC-5.3 | Reinitialize after reboot | IT-07 | Covered | +| AC-NEW-2 | Spoofing promotion <3 s | IT-05 | Covered | +| AC-NEW-4 | False-position safety budget | ST-01, AT-02 | Covered | +| AC-NEW-8 | IMU-only blackout thresholds | IT-04, AT-03 | Covered | + +## Blackbox Tests + +### IT-01: Drift And Anchor Age Accounting + +**Summary**: Verify VO extrapolation drift and anchor age are tracked per estimate. + +**Traces to**: AC-1.3 + +**Input data**: VIO state stream with two accepted anchor decisions. + +**Expected result**: Every `PositionEstimate` includes `last_satellite_anchor_age_ms`; drift at next anchor is measured and binned by age. + +**Max execution time**: 5 minutes. + +--- + +### IT-02: Confidence Output Contract + +**Summary**: Verify every estimate has covariance and source label. + +**Traces to**: AC-1.4 + +**Input data**: satellite-anchored, VO-extrapolated, and dead-reckoned state fixtures. + +**Expected result**: Each output contains `covariance_95_semi_major_m`, `source_label`, `fix_type`, and `horiz_accuracy_m`; `horiz_accuracy_m` never under-reports covariance. + +**Max execution time**: 2 minutes. + +--- + +### IT-03: No-Position Relocalization Trigger + +**Summary**: Verify no position for >=3 frames and >=2 s triggers relocalization/degraded behavior. + +**Traces to**: AC-3.4, AC-5.2 + +**Input data**: VIO loss sequence with no accepted anchors. + +**Expected result**: Relocalization request is emitted and wrapper continues dead reckoning until fail threshold. + +**Max execution time**: 5 minutes. + +--- + +### IT-04: Total Blackout IMU-Only Propagation + +**Summary**: Verify total occlusion produces honest IMU-only estimates and failsafe thresholds. + +**Traces to**: AC-3.5, AC-NEW-8 + +**Input data**: Last trusted estimate, IMU/attitude/airspeed/altitude stream, total-occlusion signal for 5 s, 15 s, and 35 s. + +**Expected result**: Wrapper emits `dead_reckoned` within <=1 frame or <=400 ms, covariance grows monotonically, and no-fix/failsafe is emitted when blackout >30 s or covariance >500 m. + +**Max execution time**: 10 minutes. + +--- + +### IT-05: Spoofing Promotion And GPS_INPUT Mapping + +**Summary**: Verify wrapper promotes own estimate and maps output fields correctly under GPS spoofing. + +**Traces to**: AC-4.3, AC-NEW-2 + +**Input data**: Plane SITL spoofing telemetry and trusted wrapper estimate. + +**Expected result**: Own estimate is promoted within <3 s; v1 emits `GPS_INPUT` only; source labels and accuracy fields are correct. + +**Max execution time**: 10 minutes. + +--- + +### IT-06: Correction Update + +**Summary**: Verify refined estimates can correct previous positions. + +**Traces to**: AC-4.5 + +**Input data**: VO estimate followed by accepted satellite anchor for same segment. + +**Expected result**: Wrapper emits updated estimate/correction with improved source label and covariance. + +**Max execution time**: 5 minutes. + +--- + +### IT-07: Initialization And Reboot Recovery + +**Summary**: Verify wrapper initializes from FC state and can reinitialize after reboot. + +**Traces to**: AC-5.1, AC-5.3 + +**Input data**: FC EKF position, IMU-extrapolated state, simulated companion restart. + +**Expected result**: Wrapper resumes from current FC state and reports degraded confidence until re-anchored. + +**Max execution time**: 5 minutes. + +## Performance Tests + +### PT-01: Wrapper Streaming Overhead + +**Summary**: Verify state-machine processing does not delay frame-by-frame output. + +**Traces to**: AC-4.4 + +**Load scenario**: +- Input: 3 Hz estimate stream with anchor and blackout events. +- Duration: 8-hour synthetic run. + +| Metric | Target | Failure Threshold | +|--------|--------|-------------------| +| Wrapper p95 processing | <=25 ms | >50 ms | +| Missed frame outputs | 0 except skip-allowed upstream drops | Any silent batch/delay | + +**Resource limits**: Negligible memory growth across run. + +## Security Tests + +### ST-01: False Anchor Rejection + +**Summary**: Verify impossible anchors do not become trusted estimates. + +**Traces to**: AC-NEW-4 + +**Attack vector**: Anchor decision with plausible inliers but impossible jump or stale provenance. + +**Test procedure**: +1. Feed an anchor >1 km from predicted state with low covariance. +2. Feed stale/provenance-failed anchor evidence. + +**Expected behavior**: Anchor is rejected, FDR logs reason, source label remains degraded or VO extrapolated. + +**Pass criteria**: 0 accepted impossible/stale anchors. + +## Acceptance Tests + +### AT-01: Position Accuracy Aggregation + +**Summary**: Verify wrapper outputs can be scored against frame-center thresholds. + +**Traces to**: AC-1.1, AC-1.2 + +| Step | Action | Expected Result | +|------|--------|-----------------| +| 1 | Replay mapped frame-center estimates | Report computes >=80% within 50 m and >=50% within 20 m | +| 2 | Include source labels | Accuracy is binned by source label | + +--- + +### AT-02: Confidence Honesty + +**Summary**: Verify reported confidence is conservative relative to measured error. + +**Traces to**: AC-1.4, AC-NEW-4 + +| Step | Action | Expected Result | +|------|--------|-----------------| +| 1 | Replay ground-truth trajectory | Measured error is not systematically above reported covariance | +| 2 | Inject over-confident anchors | Mahalanobis gate rejects them | + +--- + +### AT-03: Blackout Failsafe + +**Summary**: Verify operator-visible blackout/failsafe behavior. + +**Traces to**: AC-3.5, AC-NEW-8 + +| Step | Action | Expected Result | +|------|--------|-----------------| +| 1 | Inject total visual blackout | `dead_reckoned` within <=400 ms | +| 2 | Continue >30 s or covariance >500 m | `fix_type=0`, `horiz_accuracy=999.0`, QGC failsafe status | + +## Test Data Management + +| Data Set | Description | Source | Size | +|----------|-------------|--------|------| +| `wrapper_state_fixtures` | VIO states, anchors, blackouts, spoofing signals | Generated fixtures | Small | +| `representative_replay` | Target synchronized replay and ground truth | Project collection | TBD | + +**Setup procedure**: Load deterministic VIO/anchor/telemetry fixtures and run with isolated PostgreSQL schema. + +**Teardown procedure**: Drop run schema and remove FDR segments. + +**Data isolation strategy**: Use per-run mission IDs and database schemas. diff --git a/_docs/02_document/components/04_satellite_retrieval/description.md b/_docs/02_document/components/04_satellite_retrieval/description.md new file mode 100644 index 0000000..e6282c2 --- /dev/null +++ b/_docs/02_document/components/04_satellite_retrieval/description.md @@ -0,0 +1,96 @@ +# Satellite Retrieval + +## 1. High-Level Overview + +**Purpose**: Convert a query frame and prior state into ranked satellite/cache VPR chunk candidates using DINOv2-VLAD descriptors and FAISS. + +**Architectural Pattern**: Query service / retrieval index adapter. + +**Upstream dependencies**: Camera ingest/calibration, cache/tile lifecycle, safety/anchor wrapper. + +**Downstream consumers**: Anchor verification, FDR. + +## 2. Internal Interfaces + +### Interface: `CandidateRetriever` + +| Method | Input | Output | Async | Error Types | +|--------|-------|--------|-------|-------------| +| `retrieve` | `RetrievalRequest` | `RetrievalResult` | Yes | `IndexUnavailable`, `DescriptorFailed` | +| `load_index` | `IndexLoadRequest` | `IndexStatus` | No | `ManifestInvalid`, `IndexUnavailable` | + +**Input DTOs**: + +```yaml +RetrievalRequest: + frame: FramePacket + prior_estimate: PositionEstimate optional + search_radius_m: number optional + max_candidates: integer +``` + +**Output DTOs**: + +```yaml +RetrievalResult: + query_descriptor_id: string + candidates: list[VprCandidate] + +VprCandidate: + chunk_id: string + tile_id: string + score: number + footprint: geometry + freshness_status: enum +``` + +## 3. Data Access Patterns + +| Query | Frequency | Hot Path | Index Needed | +|-------|-----------|----------|--------------| +| Top-K FAISS search | Triggered only | No steady-state | FAISS index | +| Load chunk metadata | Per candidate | No | PostgreSQL/PostGIS spatial and chunk indexes | + +## 4. Implementation Details + +**State Management**: Holds loaded descriptor model and FAISS index handles. + +**Key Dependencies**: + +| Library | Purpose | +|---------|---------| +| DINOv2 / ONNX / TensorRT candidate path | Query descriptor extraction | +| FAISS CPU | Top-K retrieval | + +**Error Handling Strategy**: +- If descriptor extraction or index load fails, return no candidates and trigger degraded mode. +- Optimized engines are allowed only after descriptor-fidelity tests pass. + +## 5. Caveats & Edge Cases + +**Known limitations**: +- VPR result is only a candidate, never an accepted fix. +- Cross-domain retrieval can be wrong under seasonal, lighting, or terrain ambiguity. + +**Performance bottlenecks**: +- Descriptor extraction on Jetson must be trigger-limited and profiled separately from BASALT. + +## 6. Dependency Graph + +**Must be implemented after**: cache manifest/index schema, camera frame DTOs. + +**Can be implemented in parallel with**: anchor verification. + +**Blocks**: satellite relocalization flow. + +## 7. Logging Strategy + +| Log Level | When | Example | +|-----------|------|---------| +| ERROR | Index unavailable | `faiss_index_unavailable id=...` | +| WARN | No candidates | `vpr_no_candidates frame_id=...` | +| INFO | Retrieval invoked | `vpr_query candidates=... latency_ms=...` | + +**Log format**: FDR structured event. + +**Log storage**: FDR segment. diff --git a/_docs/02_document/components/04_satellite_retrieval/tests.md b/_docs/02_document/components/04_satellite_retrieval/tests.md new file mode 100644 index 0000000..21cf1f8 --- /dev/null +++ b/_docs/02_document/components/04_satellite_retrieval/tests.md @@ -0,0 +1,153 @@ +# Test Specification — Satellite Retrieval + +## Acceptance Criteria Traceability + +| AC ID | Acceptance Criterion | Test IDs | Coverage | +|-------|---------------------|----------|----------| +| AC-3.2 | Sharp-turn relocalization | IT-02, AT-01 | Covered | +| AC-3.3 | >=3 disconnected segments | IT-03 | Covered | +| AC-3.4 | Relocalization request after loss | IT-02 | Covered | +| AC-4.1 | Trigger path latency | PT-01 | Covered | +| AC-4.2 | Memory budget | PT-01 | Covered | +| AC-8.1 | Cache imagery interface | IT-01 | Covered | +| AC-8.3 | Preloaded/preprocessed cache | IT-01 | Covered | +| AC-8.6 | VPR chunks, multi-scale, dynamic K | IT-01, IT-04 | Covered | +| AC-NEW-1 | Cold-start first fix support | PT-02 | Covered | +| AC-NEW-6 | Freshness-aware retrieval | IT-04, ST-01 | Covered | + +## Blackbox Tests + +### IT-01: Index Load And Chunk Coverage + +**Summary**: Verify preloaded VPR chunks and FAISS index cover the operational area. + +**Traces to**: AC-8.1, AC-8.3, AC-8.6 + +**Input data**: PostgreSQL/PostGIS cache manifest, VPR chunk metadata, FAISS index. + +**Expected result**: Every test frame footprint falls inside at least one VPR chunk; fine and coarse descriptors are present where required. + +**Max execution time**: 2 minutes per mission cache. + +--- + +### IT-02: Sharp-Turn Retrieval Trigger + +**Summary**: Verify sharp-turn state requests candidates rather than relying on frame-to-frame VO. + +**Traces to**: AC-3.2, AC-3.4 + +**Input data**: Wrapper relocalization request with sharp-turn/loss reason. + +**Expected result**: Retrieval returns bounded top-K candidates based on sector/covariance policy. + +**Max execution time**: 2 seconds per query. + +--- + +### IT-03: Disconnected Segment Retrieval + +**Summary**: Verify at least three disconnected segments can each retrieve candidate chunks. + +**Traces to**: AC-3.3 + +**Input data**: Three disconnected query frames with approximate prior/covariance. + +**Expected result**: Each query returns a candidate set including the ground-truth region when covered by the cache fixture. + +**Max execution time**: Dataset-dependent. + +--- + +### IT-04: Dynamic K And Freshness Filter + +**Summary**: Verify K varies by sector and covariance, and stale candidates are tagged. + +**Traces to**: AC-8.6, AC-NEW-6 + +**Input data**: Stable and active-conflict sector cache fixtures with fresh/stale tiles. + +**Expected result**: K=5 for stable low-covariance, K=20 for active-conflict, K=50 fallback; stale candidates are flagged for rejection/down-confidence. + +**Max execution time**: 2 seconds per query. + +## Performance Tests + +### PT-01: Retrieval Query Runtime + +**Summary**: Verify descriptor extraction and FAISS query fit trigger-path budget. + +**Traces to**: AC-4.1, AC-4.2 + +**Load scenario**: +- Query set: 100 representative relocalization frames. +- Environment: Jetson and replay workstation. + +| Metric | Target | Failure Threshold | +|--------|--------|-------------------| +| Retrieval p95 | <=300 ms trigger path share | >400 ms | +| Memory contribution | <=2 GB | >3 GB | +| Candidate count policy | Exact | Any wrong K | + +**Resource limits**: Total system memory remains below 8 GB. + +--- + +### PT-02: Cold-Start Index Load + +**Summary**: Verify retrieval readiness supports first fix <30 s. + +**Traces to**: AC-NEW-1 + +**Load scenario**: +- Cold boot 50 runs. +- Cache/index mounted locally. + +| Metric | Target | Failure Threshold | +|--------|--------|-------------------| +| Index ready p95 | <=10 s | >15 s | +| First retrieval p95 | Fits <30 s first-fix budget | Exceeds budget | + +## Security Tests + +### ST-01: Stale Candidate Handling + +**Summary**: Verify stale imagery cannot silently appear as a trusted retrieval candidate. + +**Traces to**: AC-NEW-6 + +**Attack vector**: Manipulated cache manifest marks stale tile as available. + +**Test procedure**: +1. Load cache fixture with stale capture dates. +2. Query against stale region. + +**Expected behavior**: Candidate carries stale status; anchor path cannot accept it as `satellite_anchored`. + +**Pass criteria**: 0 stale candidates without explicit stale/down-confidence metadata. + +## Acceptance Tests + +### AT-01: Relocalization Candidate Returned + +**Summary**: Verify a relocalization request returns usable candidates for anchor verification. + +**Traces to**: AC-3.2, AC-8.6 + +| Step | Action | Expected Result | +|------|--------|-----------------| +| 1 | Submit sharp-turn query | Retrieval invokes VPR | +| 2 | Read output | Candidate list includes chunk IDs, tile IDs, scores, footprints, freshness | + +## Test Data Management + +| Data Set | Description | Source | Size | +|----------|-------------|--------|------| +| `cache_vpr_fixture` | PostGIS manifest, COGs, descriptors, FAISS index | Generated/cache fixture | Mission-dependent | +| `aerial_vpr_queries` | Aerial query frames with ground-truth regions | ALTO/AerialVL/representative | Dataset-dependent | + +**Setup procedure**: Restore isolated PostgreSQL schema and mount read-only descriptor/index files. + +**Teardown procedure**: Drop schema and remove generated retrieval reports. + +**Data isolation strategy**: Per-run schema and read-only cache fixture volume. diff --git a/_docs/02_document/components/05_anchor_verification/description.md b/_docs/02_document/components/05_anchor_verification/description.md new file mode 100644 index 0000000..a9b53a7 --- /dev/null +++ b/_docs/02_document/components/05_anchor_verification/description.md @@ -0,0 +1,93 @@ +# Anchor Verification + +## 1. High-Level Overview + +**Purpose**: Verify retrieved cache candidates with local feature matching and geometric checks before the safety wrapper considers an absolute anchor. + +**Architectural Pattern**: Validation pipeline. + +**Upstream dependencies**: Satellite retrieval, camera ingest/calibration, cache/tile lifecycle. + +**Downstream consumers**: Safety/anchor wrapper, FDR. + +## 2. Internal Interfaces + +### Interface: `AnchorVerifier` + +| Method | Input | Output | Async | Error Types | +|--------|-------|--------|-------|-------------| +| `verify` | `AnchorVerificationRequest` | `AnchorDecision` | Yes | `TileUnavailable`, `MatchFailed`, `GeometryFailed` | +| `benchmark_matcher` | `MatcherBenchmarkRequest` | `MatcherBenchmarkReport` | Yes | `ModelUnavailable` | + +**Input DTOs**: + +```yaml +AnchorVerificationRequest: + frame: FramePacket + candidates: list[VprCandidate] + matcher_profile: enum(aliked, disk, sift_orb_baseline) +``` + +**Output DTOs**: + +```yaml +AnchorDecision: + candidate_id: string + accepted_by_geometry: boolean + estimated_pose_wgs84: object optional + inlier_count: integer + mre_px: number + homography: matrix optional + rejection_reason: string optional +``` + +## 3. Data Access Patterns + +| Query | Frequency | Hot Path | Index Needed | +|-------|-----------|----------|--------------| +| Read candidate COG footprint/window | Triggered only | No | Tile spatial metadata | +| Read matcher model | Startup | No | No | + +## 4. Implementation Details + +**State Management**: Loads matcher/extractor models and tracks benchmark-selected profile. + +**Key Dependencies**: + +| Library | Purpose | +|---------|---------| +| ALIKED/DISK + LightGlue | Learned local matching | +| OpenCV | RANSAC/USAC geometry and error metrics | + +**Error Handling Strategy**: +- Low inlier count, high MRE, stale tile, or provenance failure returns a rejected decision with reason. +- SuperPoint can be benchmarked only if legal approval allows its license use. + +## 5. Caveats & Edge Cases + +**Known limitations**: +- ALIKED-LightGlue is not VIO by itself; it supplies correspondences. A full VIO path still needs state estimation and IMU fusion. +- Optional frame-to-frame VO fallback must be benchmarked separately from cross-domain anchor verification. + +**Performance bottlenecks**: +- Learned matching can exceed the Jetson budget if run per-frame; default invocation is trigger-based. + +## 6. Dependency Graph + +**Must be implemented after**: satellite retrieval candidate DTOs, cache tile access. + +**Can be implemented in parallel with**: BASALT VIO adapter. + +**Blocks**: accepted satellite-anchor path. + +## 7. Logging Strategy + +| Log Level | When | Example | +|-----------|------|---------| +| ERROR | Matcher model unavailable | `lightglue_model_unavailable profile=aliked` | +| WARN | Candidate rejected | `anchor_geometry_rejected mre_px=... inliers=...` | +| INFO | Anchor verified | `anchor_verified tile_id=... mre_px=...` | + +**Log format**: FDR structured event. + +**Log storage**: FDR segment. diff --git a/_docs/02_document/components/05_anchor_verification/tests.md b/_docs/02_document/components/05_anchor_verification/tests.md new file mode 100644 index 0000000..8a3b39f --- /dev/null +++ b/_docs/02_document/components/05_anchor_verification/tests.md @@ -0,0 +1,124 @@ +# Test Specification — Anchor Verification + +## Acceptance Criteria Traceability + +| AC ID | Acceptance Criterion | Test IDs | Coverage | +|-------|---------------------|----------|----------| +| AC-1.1 | 50 m frame-center accuracy via accepted anchors | AT-01 | Covered | +| AC-1.2 | 20 m stretch accuracy via accepted anchors | AT-01 | Covered | +| AC-2.1b | Satellite-anchor registration measured separately | IT-01 | Covered | +| AC-2.2 | <2.5 px cross-domain MRE | IT-01, AT-01 | Covered | +| AC-3.1 | Outlier rejection | ST-01 | Covered | +| AC-4.1 | Trigger-path latency | PT-01 | Covered | +| AC-4.2 | Memory budget | PT-01 | Covered | +| AC-NEW-4 | False-position safety budget | ST-01 | Covered | +| AC-NEW-6 | Stale imagery rejection evidence | IT-02, ST-02 | Covered | + +## Blackbox Tests + +### IT-01: Cross-Domain Match And RANSAC + +**Summary**: Verify ALIKED/DISK-LightGlue plus RANSAC produces measurable anchor evidence. + +**Traces to**: AC-2.1b, AC-2.2 + +**Input data**: UAV frame, retrieved COG candidate window, ground-truth georegistration. + +**Expected result**: Accepted anchors have MRE <2.5 px, sufficient inliers, and homography/pose evidence. + +**Max execution time**: 2 seconds per candidate set. + +--- + +### IT-02: Stale Candidate Verification + +**Summary**: Verify stale or provenance-failed candidates are rejected or marked unsafe. + +**Traces to**: AC-NEW-6 + +**Input data**: Candidate list with stale tile metadata and valid-looking image content. + +**Expected result**: `AnchorDecision` is rejected or carries stale/provenance failure; safety wrapper cannot accept it as trusted. + +**Max execution time**: 2 seconds per candidate. + +## Performance Tests + +### PT-01: Local Matcher Runtime + +**Summary**: Verify learned matching stays bounded on Jetson when invoked. + +**Traces to**: AC-4.1, AC-4.2 + +**Load scenario**: +- Candidate sets: K=5, K=20, K=50. +- Matcher profiles: ALIKED, DISK, SIFT/ORB baseline. + +| Metric | Target | Failure Threshold | +|--------|--------|-------------------| +| K=5 p95 | <=300 ms | >500 ms | +| K=20 p95 | Reported and bounded | Unbounded/no report | +| Memory contribution | <=2 GB | >3 GB | + +**Resource limits**: Total Jetson shared memory remains below 8 GB. + +## Security Tests + +### ST-01: False Match / Impossible Jump Rejection + +**Summary**: Verify visually plausible but geographically impossible matches are rejected. + +**Traces to**: AC-3.1, AC-NEW-4 + +**Attack vector**: Candidate tile from wrong region with repetitive texture. + +**Test procedure**: +1. Pair query with wrong-region candidate. +2. Run matcher and RANSAC. +3. Pass result to safety wrapper fixture. + +**Expected behavior**: Anchor is rejected by geometry or downstream consistency gates. + +**Pass criteria**: 0 accepted anchors from wrong-region fixtures. + +--- + +### ST-02: Provenance Failure + +**Summary**: Verify unsigned/hash-failed candidate tiles cannot produce accepted anchors. + +**Traces to**: AC-NEW-6 + +**Attack vector**: Tampered COG or sidecar. + +**Test procedure**: Run verification against tampered tile fixture. + +**Expected behavior**: `AnchorDecision` includes provenance failure and is not accepted. + +**Pass criteria**: 0 trusted anchors from tampered tiles. + +## Acceptance Tests + +### AT-01: Accepted Anchor Accuracy + +**Summary**: Verify accepted anchors support position accuracy thresholds. + +**Traces to**: AC-1.1, AC-1.2, AC-2.2 + +| Step | Action | Expected Result | +|------|--------|-----------------| +| 1 | Verify satellite candidate against query | MRE <2.5 px | +| 2 | Convert accepted anchor to WGS84 evidence | Error supports 50 m / 20 m aggregate thresholds | + +## Test Data Management + +| Data Set | Description | Source | Size | +|----------|-------------|--------|------| +| `anchor_match_fixture` | Query frames, COG windows, expected georegistration | ALTO/AerialVL/project cache | Dataset-dependent | +| `tampered_tile_fixture` | Hash/signature/stale cases | Generated fixture | Small | + +**Setup procedure**: Load cache fixture and matcher model profile. + +**Teardown procedure**: Remove matcher outputs and reports. + +**Data isolation strategy**: Read-only imagery with per-run output folders. diff --git a/_docs/02_document/components/06_cache_tile_lifecycle/description.md b/_docs/02_document/components/06_cache_tile_lifecycle/description.md new file mode 100644 index 0000000..5d300dc --- /dev/null +++ b/_docs/02_document/components/06_cache_tile_lifecycle/description.md @@ -0,0 +1,90 @@ +# Cache And Tile Lifecycle + +## 1. High-Level Overview + +**Purpose**: Manage offline service-source tiles, manifests, descriptor metadata, freshness/provenance checks, generated tile writes, and post-flight sync packaging. + +**Architectural Pattern**: Repository + policy gate. + +**Upstream dependencies**: Satellite Service cache packages, safety/anchor wrapper, camera ingest/calibration. + +**Downstream consumers**: Satellite retrieval, anchor verification, FDR, post-flight sync. + +## 2. Internal Interfaces + +### Interface: `CacheRepository` + +| Method | Input | Output | Async | Error Types | +|--------|-------|--------|-------|-------------| +| `validate_cache` | `CacheValidationRequest` | `CacheValidationReport` | No | `ManifestInvalid`, `SignatureInvalid` | +| `get_tile_window` | `TileWindowRequest` | `TileWindow` | No | `TileUnavailable`, `TileRejected` | +| `write_generated_tile` | `GeneratedTileRequest` | `GeneratedTileRecord` | Yes | `TileWriteRejected`, `StorageFull` | +| `package_sync` | `SyncPackageRequest` | `SyncPackage` | Yes | `PackageFailed` | + +## 3. Data Access Patterns + +| Query | Frequency | Hot Path | Index Needed | +|-------|-----------|----------|--------------| +| Tile by footprint/time/freshness | Per retrieval/anchor | Yes during relocalization | Spatial/time indexes | +| Descriptor metadata by chunk | Per retrieval | Yes during relocalization | Chunk ID index | +| Generated tile by mission/sector | Post-flight | No | Mission ID index | + +### Caching Strategy + +| Data | Cache Type | TTL | Invalidation | +|------|------------|-----|--------------| +| Manifest metadata | PostgreSQL/PostGIS query cache / process cache | Mission duration | New mission cache load | +| Sidecar verification | In-memory result cache | Mission duration | File hash change | + +### Storage Estimates + +| Table/Collection | Est. Row Count | Row Size | Total Size | Growth Rate | +|------------------|----------------|----------|------------|-------------| +| Cache manifest tiles | Mission-dependent | Small metadata | Within ~10 GB package with imagery | Per mission | +| Generated tiles | Flight-dependent | Metadata + COG payload | FDR/cache budget constrained | Per flight | + +## 4. Implementation Details + +**State Management**: Owns PostgreSQL/PostGIS manifest connection, sidecar verification state, and generated tile staging area. + +**Key Dependencies**: + +| Library | Purpose | +|---------|---------| +| PostgreSQL + PostGIS | Manifest, spatial metadata, freshness queries, and generated-tile metadata | +| GDAL/rasterio candidate | COG read/write | +| Cryptographic hash/signature library | Sidecar validation | + +**Error Handling Strategy**: +- Invalid signatures/hashes reject tiles. +- Storage-full blocks generated tile writes without affecting localization output. +- Cache validation failure blocks mission cache usage. + +## 5. Caveats & Edge Cases + +**Known limitations**: +- JSON-only manifests are avoided for scale and queryability, but signed JSON sidecars remain required for audit/interchange. +- PostgreSQL/PostGIS must be available locally before flight; runtime cannot depend on a remote DB link. + +**Potential race conditions**: +- Generated tile and PostgreSQL manifest update must be atomic enough to avoid orphan trusted metadata. + +## 6. Dependency Graph + +**Must be implemented after**: data model schema decisions. + +**Can be implemented in parallel with**: camera ingest, MAVLink integration. + +**Blocks**: satellite retrieval, anchor verification, generated tile lifecycle. + +## 7. Logging Strategy + +| Log Level | When | Example | +|-----------|------|---------| +| ERROR | Cache package invalid | `cache_manifest_invalid reason=signature` | +| WARN | Tile rejected | `tile_rejected reason=stale tile_id=...` | +| INFO | Generated tile staged | `generated_tile_written tile_id=...` | + +**Log format**: FDR structured event. + +**Log storage**: FDR segment plus cache validation report. diff --git a/_docs/02_document/components/06_cache_tile_lifecycle/tests.md b/_docs/02_document/components/06_cache_tile_lifecycle/tests.md new file mode 100644 index 0000000..22c8c6e --- /dev/null +++ b/_docs/02_document/components/06_cache_tile_lifecycle/tests.md @@ -0,0 +1,167 @@ +# Test Specification — Cache And Tile Lifecycle + +## Acceptance Criteria Traceability + +| AC ID | Acceptance Criterion | Test IDs | Coverage | +|-------|---------------------|----------|----------| +| AC-4.2 | Memory/storage pressure | PT-01 | Covered | +| AC-8.1 | Resolution at cache interface | IT-01 | Covered | +| AC-8.2 | Freshness thresholds | IT-02, ST-01 | Covered | +| AC-8.3 | Preloaded/preprocessed offline cache | IT-01 | Covered | +| AC-8.4 | Mid-flight tile generation/write-back | IT-03, AT-01 | Covered | +| AC-8.5 | Persistent imagery policy | ST-02 | Covered | +| AC-8.6 | VPR chunk metadata | IT-04 | Covered | +| AC-NEW-3 | FDR/tile storage cap interaction | PT-01 | Covered | +| AC-NEW-6 | Imagery freshness enforcement | IT-02, ST-01 | Covered | +| AC-NEW-7 | Cache-poisoning safety budget | ST-03, AT-01 | Covered | + +## Blackbox Tests + +### IT-01: Mission Cache Validation + +**Summary**: Verify preloaded COGs, PostGIS metadata, sidecars, descriptors, and indexes validate before flight. + +**Traces to**: AC-8.1, AC-8.3 + +**Input data**: Mission cache package with COGs, signed JSON sidecars, PostGIS manifest seed, FAISS index files. + +**Expected result**: Valid cache passes resolution, hash, signature, descriptor-reference, and spatial coverage checks. + +**Max execution time**: 5 minutes per cache fixture. + +--- + +### IT-02: Freshness Gate + +**Summary**: Verify active-conflict and stable-rear freshness rules. + +**Traces to**: AC-8.2, AC-NEW-6 + +**Input data**: Tiles at fresh, grace, and stale ages for both sector classes. + +**Expected result**: Fresh tiles pass, grace tiles are down-confidence weighted if allowed, stale tiles are rejected and cannot emit `satellite_anchored`. + +**Max execution time**: 2 minutes. + +--- + +### IT-03: Generated Tile Write + +**Summary**: Verify generated tiles are written only when pose and frame quality gates pass. + +**Traces to**: AC-8.4 + +**Input data**: Frame metadata, pose covariance <=3 m, <=5 m, and >5 m. + +**Expected result**: <=3 m writes full-quality candidate, 3-5 m writes soft candidate, >5 m rejects write. + +**Max execution time**: 2 minutes. + +--- + +### IT-04: VPR Chunk Metadata + +**Summary**: Verify chunk metadata supports retrieval rules. + +**Traces to**: AC-8.6 + +**Input data**: Operational-area cache manifest. + +**Expected result**: Chunks are 600-800 m equivalent footprint with 40-50% overlap and multi-scale active-sector descriptors. + +**Max execution time**: 2 minutes. + +## Performance Tests + +### PT-01: Cache And FDR Storage Budget + +**Summary**: Verify cache metadata and generated tile writes stay within storage/memory budgets. + +**Traces to**: AC-4.2, AC-NEW-3 + +**Load scenario**: +- Mission cache: up to operational budget. +- Generated tiles: 8-hour synthetic flight. + +| Metric | Target | Failure Threshold | +|--------|--------|-------------------| +| Persistent cache | <=10 GB unless split budget approved | >budget without report | +| FDR + generated artifacts | <=64 GB per flight | >64 GB without rollover | +| DB query p95 | <=50 ms for indexed tile lookup | >150 ms | + +**Resource limits**: PostgreSQL/PostGIS stays within total system 8 GB memory budget. + +## Security Tests + +### ST-01: Signed Manifest Enforcement + +**Summary**: Verify unsigned/tampered/stale manifests are rejected. + +**Traces to**: AC-8.2, AC-NEW-6 + +**Attack vector**: Tampered sidecar, bad hash, unsigned manifest. + +**Test procedure**: Load invalid cache variants and run validation. + +**Expected behavior**: Invalid tiles are rejected and logged. + +**Pass criteria**: 0 invalid cache entries become available to retrieval/anchor verification. + +--- + +### ST-02: Raw Frame Persistence Check + +**Summary**: Verify cache lifecycle persists tiles, not raw frames. + +**Traces to**: AC-8.5 + +**Attack vector**: Raw frames accidentally stored as generated artifacts. + +**Test procedure**: Run tile generation and inspect cache/FDR outputs. + +**Expected behavior**: Only COG tiles, sidecars, manifests, and allowed failed-frame thumbnails exist. + +**Pass criteria**: No raw full-resolution frames retained. + +--- + +### ST-03: Cache Poisoning Gate + +**Summary**: Verify misaligned generated tiles cannot become trusted basemap. + +**Traces to**: AC-NEW-7 + +**Attack vector**: Over-confident pose writes misaligned generated tile. + +**Test procedure**: Inject deflated covariance and wrong pose during tile write. + +**Expected behavior**: Tile is rejected or marked candidate/soft; never promoted to trusted by onboard component. + +**Pass criteria**: 0 direct trusted basemap promotions onboard. + +## Acceptance Tests + +### AT-01: Generated Tile Package For Satellite Service + +**Summary**: Verify post-flight sync package contains valid generated tiles and metadata. + +**Traces to**: AC-8.4, AC-NEW-7 + +| Step | Action | Expected Result | +|------|--------|-----------------| +| 1 | Write generated candidate tile | COG + sidecar + PostGIS manifest row created | +| 2 | Package post-flight sync | Manifest delta includes trust level and parent covariance | +| 3 | Inspect package | No tile is marked trusted basemap by onboard runtime | + +## Test Data Management + +| Data Set | Description | Source | Size | +|----------|-------------|--------|------| +| `cache_integrity_fixtures` | Valid/stale/unsigned/hash-mismatched manifests | Generated fixture | Small | +| `mission_cache_fixture` | COGs, descriptors, PostGIS seed | Satellite Service stub | Mission-dependent | + +**Setup procedure**: Restore isolated PostgreSQL/PostGIS schema and mount cache fixture read-only except generated-tile staging. + +**Teardown procedure**: Drop schema and delete generated staging volume. + +**Data isolation strategy**: Per-run mission ID, schema, and staging directory. diff --git a/_docs/02_document/components/07_mavlink_gcs_integration/description.md b/_docs/02_document/components/07_mavlink_gcs_integration/description.md new file mode 100644 index 0000000..144195b --- /dev/null +++ b/_docs/02_document/components/07_mavlink_gcs_integration/description.md @@ -0,0 +1,69 @@ +# MAVLink And GCS Integration + +## 1. High-Level Overview + +**Purpose**: Subscribe to flight-controller telemetry, emit `GPS_INPUT`, and send downsampled QGroundControl status/failsafe messages. + +**Architectural Pattern**: Protocol adapter. + +**Upstream dependencies**: ArduPilot Plane FC, safety/anchor wrapper. + +**Downstream consumers**: BASALT VIO adapter, safety/anchor wrapper, QGC, FDR. + +## 2. Internal Interfaces + +### Interface: `MavlinkGateway` + +| Method | Input | Output | Async | Error Types | +|--------|-------|--------|-------|-------------| +| `subscribe_telemetry` | `TelemetrySubscriptionRequest` | `TelemetrySample` | Yes | `MavlinkDisconnected` | +| `emit_gps_input` | `PositionEstimate` | `EmitResult` | Yes | `MavlinkDisconnected`, `InvalidGpsInput` | +| `emit_status` | `GcsStatusMessage` | `EmitResult` | Yes | `MavlinkDisconnected` | + +## 3. Data Access Patterns + +No persistent data ownership; telemetry and emitted packets are mirrored to FDR. + +## 4. Implementation Details + +**State Management**: Maintains MAVLink connection status, source/system IDs, and rate limiters for QGC status. + +**Key Dependencies**: + +| Library | Purpose | +|---------|---------| +| MAVSDK | Telemetry subscriptions | +| pymavlink | Exact `GPS_INPUT` field emission | + +**Error Handling Strategy**: +- Invalid `GPS_INPUT` fields are rejected before emission. +- Connection loss is surfaced to wrapper/FDR and does not silently drop safety events. + +## 5. Caveats & Edge Cases + +**Known limitations**: +- v1 emits `GPS_INPUT` only, not velocity-target navigation commands. +- Plane parameter configuration must be validated in SITL before hardware use. + +**Performance bottlenecks**: +- Status text must be rate-limited to avoid telemetry noise. + +## 6. Dependency Graph + +**Must be implemented after**: position estimate DTO and MAVLink output contract. + +**Can be implemented in parallel with**: cache lifecycle, camera ingest. + +**Blocks**: SITL integration and production FC output. + +## 7. Logging Strategy + +| Log Level | When | Example | +|-----------|------|---------| +| ERROR | MAVLink disconnected | `mavlink_disconnected endpoint=...` | +| WARN | Invalid output rejected | `gps_input_invalid reason=...` | +| INFO | FC link established | `mavlink_connected system_id=...` | + +**Log format**: FDR structured event. + +**Log storage**: FDR segment and optional tlog. diff --git a/_docs/02_document/components/07_mavlink_gcs_integration/tests.md b/_docs/02_document/components/07_mavlink_gcs_integration/tests.md new file mode 100644 index 0000000..a31c293 --- /dev/null +++ b/_docs/02_document/components/07_mavlink_gcs_integration/tests.md @@ -0,0 +1,176 @@ +# Test Specification — MAVLink And GCS Integration + +## Acceptance Criteria Traceability + +| AC ID | Acceptance Criterion | Test IDs | Coverage | +|-------|---------------------|----------|----------| +| AC-4.3 | v1 GPS_INPUT only for ArduPilot Plane | IT-01, AT-01 | Covered | +| AC-4.4 | Frame-by-frame streaming | PT-01 | Covered | +| AC-4.5 | Updated estimates/corrections | IT-02 | Covered | +| AC-5.1 | FC state initialization telemetry | IT-03 | Covered | +| AC-5.2 | Plane SITL fallback | IT-04 | Covered | +| AC-6.1 | QGC status 1-2 Hz | IT-05, PT-02 | Covered | +| AC-6.2 | GCS command ingress | IT-06, ST-01 | Covered | +| AC-6.3 | WGS84 output | IT-01 | Covered | +| AC-NEW-2 | Spoofing promotion <3 s | IT-04 | Covered | +| AC-NEW-8 | Blackout/failsafe status | IT-05 | Covered | + +## Blackbox Tests + +### IT-01: GPS_INPUT Field Mapping + +**Summary**: Verify `PositionEstimate` maps to valid MAVLink `GPS_INPUT`. + +**Traces to**: AC-4.3, AC-6.3 + +**Input data**: Position estimates across all source labels. + +**Expected result**: v1 emits `GPS_INPUT` only, no `ODOMETRY`; WGS84 lat/lon/alt, fix type, ignore flags, and accuracy fields match contract. + +**Max execution time**: 2 minutes. + +--- + +### IT-02: Correction Emission + +**Summary**: Verify updated estimates can be emitted without batching. + +**Traces to**: AC-4.5 + +**Input data**: Original VO estimate followed by anchor-corrected estimate. + +**Expected result**: Both estimates are emitted in order with updated accuracy/source label. + +**Max execution time**: 2 minutes. + +--- + +### IT-03: FC Telemetry Subscription + +**Summary**: Verify telemetry needed for initialization and VIO is available. + +**Traces to**: AC-5.1 + +**Input data**: Plane SITL or MAVLink replay with EKF position, IMU, attitude, airspeed, altitude. + +**Expected result**: Normalized `TelemetrySample` stream includes required fields and timestamps. + +**Max execution time**: 5 minutes. + +--- + +### IT-04: Spoofing And Fallback In Plane SITL + +**Summary**: Verify spoofing and no-estimate behavior in ArduPilot Plane SITL. + +**Traces to**: AC-5.2, AC-NEW-2 + +**Input data**: Plane SITL production parameter set and spoofing trace. + +**Expected result**: Own estimate promotion occurs within <3 s; fallback/no-estimate behavior matches Plane parameters. + +**Max execution time**: 10 minutes. + +--- + +### IT-05: QGC Blackout Status + +**Summary**: Verify degraded-mode messages are visible at required rate. + +**Traces to**: AC-6.1, AC-NEW-8 + +**Input data**: Safety wrapper emits blackout and failsafe statuses. + +**Expected result**: QGC observer sees `VISUAL_BLACKOUT_IMU_ONLY` at 1-2 Hz and `VISUAL_BLACKOUT_FAILSAFE` at threshold. + +**Max execution time**: 10 minutes. + +--- + +### IT-06: Operator Relocalization Hint + +**Summary**: Verify GCS command ingress can carry approximate relocalization hints. + +**Traces to**: AC-6.2 + +**Input data**: STATUSTEXT/NAMED_VALUE_FLOAT/custom dialect hint fixture. + +**Expected result**: Valid hint is parsed and forwarded to retrieval/safety logic; invalid hint is rejected. + +**Max execution time**: 5 minutes. + +## Performance Tests + +### PT-01: Frame-Rate Emission + +**Summary**: Verify output is streamed frame-by-frame and not batched. + +**Traces to**: AC-4.4 + +**Load scenario**: +- Input estimate rate: target frame rate. +- Duration: 30 minutes. + +| Metric | Target | Failure Threshold | +|--------|--------|-------------------| +| Output delay p95 | <=25 ms after wrapper output | >100 ms | +| Missing messages | 0 except upstream dropped frames | Any silent drop | + +--- + +### PT-02: QGC Status Rate Limit + +**Summary**: Verify QGC status is downsampled without losing critical transitions. + +**Traces to**: AC-6.1 + +| Metric | Target | Failure Threshold | +|--------|--------|-------------------| +| Status rate | 1-2 Hz while active | <1 Hz or >2 Hz sustained | +| Critical transition delay | <=1 s | >2 s | + +## Security Tests + +### ST-01: MAVLink Source And Command Validation + +**Summary**: Verify unauthorized or malformed MAVLink messages are rejected. + +**Traces to**: AC-6.2 + +**Attack vector**: Malicious source sends spoofed command or GPS data. + +**Test procedure**: +1. Send valid command from allowed source. +2. Send same command from disallowed source/system ID. +3. Send malformed values. + +**Expected behavior**: Allowed command is accepted; disallowed/malformed messages are rejected and logged. + +**Pass criteria**: 0 unauthorized commands affect localization state. + +## Acceptance Tests + +### AT-01: Plane SITL Output Acceptance + +**Summary**: Verify ArduPilot Plane receives and uses v1 `GPS_INPUT` as configured. + +**Traces to**: AC-4.3 + +| Step | Action | Expected Result | +|------|--------|-----------------| +| 1 | Start Plane SITL with production params | FC accepts external GPS substitute config | +| 2 | Emit `GPS_INPUT` estimate | Message is received with expected fields | +| 3 | Observe wire | `ODOMETRY` is absent in v1 | + +## Test Data Management + +| Data Set | Description | Source | Size | +|----------|-------------|--------|------| +| `sitl_spoofing_scenarios` | GPS loss/spoofing traces | Generated SITL | Small | +| `mavlink_output_fixtures` | PositionEstimate cases | Generated fixture | Small | + +**Setup procedure**: Start SITL/QGC observer or replay MAVLink log. + +**Teardown procedure**: Stop processes and archive tlogs. + +**Data isolation strategy**: Unique MAVLink ports and run IDs per test. diff --git a/_docs/02_document/components/08_fdr_observability/description.md b/_docs/02_document/components/08_fdr_observability/description.md new file mode 100644 index 0000000..330fc77 --- /dev/null +++ b/_docs/02_document/components/08_fdr_observability/description.md @@ -0,0 +1,79 @@ +# FDR And Observability + +## 1. High-Level Overview + +**Purpose**: Record bounded, replayable mission evidence and expose runtime health/status events for analysis and operator awareness. + +**Architectural Pattern**: Append-only event sink + exporter. + +**Upstream dependencies**: All runtime components. + +**Downstream consumers**: Validation harness, post-flight audit tools, QGC status through MAVLink component. + +## 2. Internal Interfaces + +### Interface: `FlightRecorder` + +| Method | Input | Output | Async | Error Types | +|--------|-------|--------|-------|-------------| +| `append_event` | `FdrEvent` | `AppendResult` | Yes | `RecorderUnavailable`, `StorageFull` | +| `rollover` | `RolloverRequest` | `FdrSegmentInfo` | No | `RolloverFailed` | +| `export` | `ExportRequest` | `ExportResult` | Yes | `ExportFailed` | + +## 3. Data Access Patterns + +| Query | Frequency | Hot Path | Index Needed | +|-------|-----------|----------|--------------| +| Append event | High | Yes | Append index only | +| Export by time/type | Post-flight | No | Time/type index | + +### Storage Estimates + +| Table/Collection | Est. Row Count | Row Size | Total Size | Growth Rate | +|------------------|----------------|----------|------------|-------------| +| FDR events | Flight-dependent | Mixed | <=64 GB per 8 h | Per flight | + +## 4. Implementation Details + +**State Management**: Owns active segment, rollover policy, and export state. + +**Key Dependencies**: + +| Library | Purpose | +|---------|---------| +| PostgreSQL client | Event metadata, time/type indexes, mission query surface | +| CBOR writer | Bounded runtime payload segments | +| Parquet writer | Optional post-flight export | + +**Error Handling Strategy**: +- Storage-full emits critical status and starts rollover/retention behavior. +- Append failures are surfaced to the caller and health system. + +## 5. Caveats & Edge Cases + +**Known limitations**: +- Raw frames are not retained by default; only metadata, decisions, hashes, and occlusion/blackout status are recorded. +- PostgreSQL availability is required for indexed FDR metadata; CBOR payload segments preserve bounded append behavior for high-volume data. + +**Performance bottlenecks**: +- FDR appends must not block hot-path localization. + +## 6. Dependency Graph + +**Must be implemented after**: event schema and key DTOs. + +**Can be implemented in parallel with**: MAVLink integration. + +**Blocks**: release evidence and most validation reports. + +## 7. Logging Strategy + +| Log Level | When | Example | +|-----------|------|---------| +| ERROR | Recorder unavailable | `fdr_unavailable path=...` | +| WARN | Rollover occurs | `fdr_rollover segment=...` | +| INFO | Export complete | `fdr_export_complete format=parquet` | + +**Log format**: FDR event metadata plus local health logs. + +**Log storage**: PostgreSQL FDR event tables plus CBOR segment payloads. diff --git a/_docs/02_document/components/08_fdr_observability/tests.md b/_docs/02_document/components/08_fdr_observability/tests.md new file mode 100644 index 0000000..9633205 --- /dev/null +++ b/_docs/02_document/components/08_fdr_observability/tests.md @@ -0,0 +1,166 @@ +# Test Specification — FDR And Observability + +## Acceptance Criteria Traceability + +| AC ID | Acceptance Criterion | Test IDs | Coverage | +|-------|---------------------|----------|----------| +| AC-1.3 | Anchor age/drift evidence | IT-01 | Covered | +| AC-1.4 | Confidence/source label retained | IT-01 | Covered | +| AC-4.4 | Per-frame local stream evidence | IT-01, PT-01 | Covered | +| AC-5.2 | Failure logging | IT-02 | Covered | +| AC-6.1 | QGC/status evidence | IT-03 | Covered | +| AC-8.4 | Generated tile audit | IT-04 | Covered | +| AC-8.5 | No raw frame retention | ST-01 | Covered | +| AC-NEW-3 | FDR retention and 64 GB cap | PT-01, AT-01 | Covered | +| AC-NEW-4 | False-position forensics | IT-05 | Covered | +| AC-NEW-5 | Thermal/throttle logging | IT-06 | Covered | +| AC-NEW-8 | Blackout/failsafe logging | IT-02, IT-03 | Covered | + +## Blackbox Tests + +### IT-01: Per-Estimate Event Capture + +**Summary**: Verify every estimate stores covariance, source label, anchor age, and emitted output metadata. + +**Traces to**: AC-1.3, AC-1.4, AC-4.4 + +**Input data**: Position estimate stream with satellite, VO, and dead-reckoned labels. + +**Expected result**: PostgreSQL event index and CBOR payload segments contain all required fields with monotonic timestamps. + +**Max execution time**: 5 minutes. + +--- + +### IT-02: Failure And Blackout Logging + +**Summary**: Verify no-estimate and blackout transitions are recorded. + +**Traces to**: AC-5.2, AC-NEW-8 + +**Input data**: No-estimate gap and total blackout sequence. + +**Expected result**: FDR records start, every degraded estimate, failsafe threshold, and recovery reason. + +**Max execution time**: 10 minutes. + +--- + +### IT-03: QGC Status Audit + +**Summary**: Verify operator-visible status has matching FDR evidence. + +**Traces to**: AC-6.1, AC-NEW-8 + +**Input data**: QGC status messages from MAVLink component. + +**Expected result**: FDR contains status text, timestamp, and mode context. + +**Max execution time**: 5 minutes. + +--- + +### IT-04: Generated Tile Audit Trail + +**Summary**: Verify tile-write decisions are recorded with parent covariance and trust level. + +**Traces to**: AC-8.4 + +**Input data**: Accepted and rejected generated tile write decisions. + +**Expected result**: FDR includes tile ID, parent covariance, trust level, sidecar hash, and rejection reason where applicable. + +**Max execution time**: 5 minutes. + +--- + +### IT-05: False-Position Investigation Bundle + +**Summary**: Verify enough evidence exists to investigate a false-position event. + +**Traces to**: AC-NEW-4 + +**Input data**: Simulated false anchor rejection and covariance growth sequence. + +**Expected result**: Export includes estimates, anchor decisions, residuals, covariance, and emitted MAVLink fields. + +**Max execution time**: 5 minutes. + +--- + +### IT-06: Thermal/Throttle Event Capture + +**Summary**: Verify resource health events are recorded. + +**Traces to**: AC-NEW-5 + +**Input data**: Synthetic thermal/throttle metric stream. + +**Expected result**: FDR records CPU/GPU/temp/throttle status and QGC warning trigger. + +**Max execution time**: 5 minutes. + +## Performance Tests + +### PT-01: 8-Hour FDR Load + +**Summary**: Verify FDR storage and append behavior under full mission load. + +**Traces to**: AC-4.4, AC-NEW-3 + +**Load scenario**: +- Duration: 8 hours synthetic. +- Inputs: 3 Hz estimates, full-rate IMU, MAVLink tlog, health metrics, tile events. + +| Metric | Target | Failure Threshold | +|--------|--------|-------------------| +| Total FDR size | <=64 GB | >64 GB without rollover | +| Append latency p95 | <=10 ms async enqueue | >25 ms | +| Silent payload loss | 0 | Any unlogged loss | + +**Resource limits**: FDR must not block hot-path localization. + +## Security Tests + +### ST-01: Raw Frame Retention Audit + +**Summary**: Verify FDR does not store raw full-resolution frames. + +**Traces to**: AC-8.5 + +**Attack vector**: Debug logging accidentally persists raw camera frames. + +**Test procedure**: +1. Run normal replay and failed tile-generation replay. +2. Inspect FDR payloads and output directories. + +**Expected behavior**: Only metadata, hashes, estimates, tiles, and allowed low-rate failed-frame thumbnails are retained. + +**Pass criteria**: No raw nav/AI camera frame payloads in normal FDR. + +## Acceptance Tests + +### AT-01: FDR Export + +**Summary**: Verify post-flight export creates usable audit artifacts. + +**Traces to**: AC-NEW-3 + +| Step | Action | Expected Result | +|------|--------|-----------------| +| 1 | Complete synthetic flight | Segment rollover is logged and cap respected | +| 2 | Export FDR summary | Markdown/CSV/Parquet optional artifacts are produced | +| 3 | Query PostgreSQL index | Events can be filtered by time/type/mission | + +## Test Data Management + +| Data Set | Description | Source | Size | +|----------|-------------|--------|------| +| `fdr_synthetic_load` | Estimate, IMU, MAVLink, health, tile events | Generated fixture | Large | +| `incident_fixture` | False-position and blackout evidence | Generated fixture | Small | + +**Setup procedure**: Create isolated PostgreSQL schema and FDR segment directory. + +**Teardown procedure**: Export report, then remove schema and segment directory. + +**Data isolation strategy**: Per-run mission ID, schema, and FDR directory. diff --git a/_docs/02_document/components/09_validation_harness/description.md b/_docs/02_document/components/09_validation_harness/description.md new file mode 100644 index 0000000..9e6f217 --- /dev/null +++ b/_docs/02_document/components/09_validation_harness/description.md @@ -0,0 +1,86 @@ +# Validation Harness + +## 1. High-Level Overview + +**Purpose**: Drive black-box replay, public dataset, SITL, Jetson, and representative validation through the runtime's public interfaces. + +**Architectural Pattern**: Test harness / scenario runner. + +**Upstream dependencies**: Test data fixtures, public datasets, SITL, Jetson environment. + +**Downstream consumers**: CI/CD pipeline, release evidence review. + +## 2. Internal Interfaces + +### Interface: `ScenarioRunner` + +| Method | Input | Output | Async | Error Types | +|--------|-------|--------|-------|-------------| +| `run_scenario` | `ScenarioRequest` | `ScenarioReport` | Yes | `FixtureInvalid`, `RuntimeFailed`, `ThresholdFailed` | +| `validate_fixture` | `FixtureRequest` | `FixtureValidationReport` | No | `FixtureInvalid` | + +**Input DTOs**: + +```yaml +ScenarioRequest: + scenario_id: string + execution_environment: enum(replay, sitl, jetson, representative) + fixture_paths: list[string] +``` + +**Output DTOs**: + +```yaml +ScenarioReport: + scenario_id: string + result: enum(pass, fail, blocked) + metrics: object + artifacts: list[path] + failure_reason: string optional +``` + +## 3. Data Access Patterns + +Reads versioned fixtures and writes reports. Does not import runtime internals. + +## 4. Implementation Details + +**State Management**: Per-run temporary directories and report aggregation. + +**Key Dependencies**: + +| Library | Purpose | +|---------|---------| +| pytest or equivalent | Test orchestration | +| pymavlink/log parser | SITL and output validation | +| Docker/compose runner | Replay/SITL environment | + +**Error Handling Strategy**: +- Fixture gaps are reported as blocked, not passed. +- Threshold failures include metrics and artifacts. + +## 5. Caveats & Edge Cases + +**Known limitations**: +- Public datasets are not final acceptance evidence unless representative and license-compatible. +- Missing synchronized target data remains a final acceptance blocker. + +## 6. Dependency Graph + +**Must be implemented after**: public interfaces are defined. + +**Can be implemented in parallel with**: runtime components using mocks/fixtures only after interfaces are stable. + +**Blocks**: CI/release gates. + +## 7. Logging Strategy + +| Log Level | When | Example | +|-----------|------|---------| +| ERROR | Runtime/test process fails | `scenario_failed id=... reason=...` | +| WARN | Fixture blocked | `fixture_blocked missing=...` | +| INFO | Scenario complete | `scenario_complete id=... result=pass` | + +**Log format**: Test report CSV/Markdown plus structured runner logs. + +**Log storage**: `test-results/`. diff --git a/_docs/02_document/components/09_validation_harness/tests.md b/_docs/02_document/components/09_validation_harness/tests.md new file mode 100644 index 0000000..324112e --- /dev/null +++ b/_docs/02_document/components/09_validation_harness/tests.md @@ -0,0 +1,232 @@ +# Test Specification — Validation Harness + +## Acceptance Criteria Traceability + +| AC ID | Acceptance Criterion | Test IDs | Coverage | +|-------|---------------------|----------|----------| +| AC-1.1 through AC-1.4 | Position accuracy, drift, confidence | IT-01, AT-01 | Covered | +| AC-2.1a/b, AC-2.2 | VO and satellite registration | IT-02, IT-03 | Covered | +| AC-3.1 through AC-3.5 | Resilience edge cases | IT-04, IT-05 | Covered | +| AC-4.1 through AC-4.5 | Latency, memory, MAVLink streaming | PT-01, IT-06 | Covered | +| AC-5.1 through AC-5.3 | Startup/failsafe/reboot | IT-07 | Covered | +| AC-6.1 through AC-6.3 | QGC/GCS/WGS84 | IT-06 | Covered | +| AC-7.1, AC-7.2 | Object coordinate contract | IT-08 | Covered at system boundary | +| AC-8.1 through AC-8.6 | Offline cache, freshness, tiles, VPR | IT-03, IT-09, ST-01 | Covered | +| AC-NEW-1 through AC-NEW-8 | Cold start, spoofing, FDR, false-position, thermal, freshness, poisoning, blackout | IT-05, IT-07, PT-02, ST-01, AT-02 | Covered | + +## Blackbox Tests + +### IT-01: Still-Image Accuracy Runner + +**Summary**: Verify project still-image replay reports frame-center accuracy. + +**Traces to**: AC-1.1, AC-1.2, AC-1.4 + +**Input data**: Project mapped images and `expected_results/results_report.md`. + +**Expected result**: Report includes per-image error, aggregate 50 m/20 m pass rates, covariance, source label, and anchor age. + +**Max execution time**: 15 minutes. + +--- + +### IT-02: Public VIO Replay Runner + +**Summary**: Verify public/representative synchronized data can drive BASALT/wrapper tests. + +**Traces to**: AC-1.3, AC-2.1a, AC-2.2 + +**Input data**: MUN-FRL preferred slice or representative synchronized dataset. + +**Expected result**: Runner validates trajectory, VIO registration, latency, and covariance calibration. + +**Max execution time**: Dataset-dependent. + +--- + +### IT-03: Satellite Anchor Replay Runner + +**Summary**: Verify VPR and anchor verification test scenarios are executable. + +**Traces to**: AC-2.1b, AC-2.2, AC-8.1, AC-8.2, AC-8.6 + +**Input data**: ALTO/AerialVL/representative aerial localization fixture plus cache. + +**Expected result**: Runner reports retrieval recall, MRE, accepted/rejected anchors, and freshness behavior. + +**Max execution time**: Dataset-dependent. + +--- + +### IT-04: Outlier/Sharp-Turn/Disconnected Runner + +**Summary**: Verify resilience scenarios are executable and reported. + +**Traces to**: AC-3.1, AC-3.2, AC-3.3, AC-3.4 + +**Input data**: Synthetic and public disconnected-segment fixtures. + +**Expected result**: Runner validates relocalization and records degraded-mode timelines. + +**Max execution time**: 30 minutes. + +--- + +### IT-05: Blackout And Spoofing Runner + +**Summary**: Verify total blackout plus spoofing scenarios can be driven through SITL/replay. + +**Traces to**: AC-3.5, AC-NEW-2, AC-NEW-8 + +**Input data**: Plane SITL spoofing scenario with 5 s, 15 s, and 35 s blackout windows. + +**Expected result**: Runner measures <=400 ms mode switch, <3 s promotion, monotonic covariance, and failsafe thresholds. + +**Max execution time**: 30 minutes. + +--- + +### IT-06: MAVLink/QGC Contract Runner + +**Summary**: Verify MAVLink output and GCS status assertions are automated. + +**Traces to**: AC-4.3, AC-4.4, AC-4.5, AC-6.1, AC-6.2, AC-6.3 + +**Input data**: Plane SITL, QGC observer/log parser, position fixtures. + +**Expected result**: Runner validates v1 GPS_INPUT-only output, WGS84 coordinates, status rate, and command ingress. + +**Max execution time**: 60 minutes. + +--- + +### IT-07: Startup/Reboot Runner + +**Summary**: Verify cold-start and reboot scenarios are measurable. + +**Traces to**: AC-5.1, AC-5.2, AC-5.3, AC-NEW-1 + +**Input data**: 50 cold-start runs and companion reboot trace. + +**Expected result**: First valid `GPS_INPUT` <30 s p95; reboot reinitializes from FC state. + +**Max execution time**: Runset-dependent. + +--- + +### IT-08: Object Coordinate Contract Runner + +**Summary**: Verify AI-camera object coordinate request contract at system boundary. + +**Traces to**: AC-7.1, AC-7.2 + +**Input data**: Frame-center estimate, object pixel/angle fixture, gimbal angle, altitude. + +**Expected result**: Output coordinate includes frame-center-consistent accuracy and maneuvering-flight projection error bound. + +**Max execution time**: 5 minutes. + +--- + +### IT-09: Cache And Tile Lifecycle Runner + +**Summary**: Verify cache, generated tiles, and storage tests are executable. + +**Traces to**: AC-8.3, AC-8.4, AC-8.5, AC-NEW-6, AC-NEW-7 + +**Input data**: Cache integrity fixtures, generated tile scenarios, PostGIS manifest. + +**Expected result**: Runner validates cache load, tile write gates, no raw-frame retention, stale rejection, and poisoning budget evidence. + +**Max execution time**: Dataset-dependent. + +## Performance Tests + +### PT-01: End-To-End Release Gate Runner + +**Summary**: Verify performance and resource tests can run in the proper environment. + +**Traces to**: AC-4.1, AC-4.2, AC-NEW-5 + +**Load scenario**: +- Environments: replay, Jetson hardware, SITL. +- Duration: smoke, nightly, and release-gate profiles. + +| Metric | Target | Failure Threshold | +|--------|--------|-------------------| +| End-to-end p95 | <400 ms | >=400 ms | +| Memory | <8 GB | >=8 GB | +| Thermal throttle | 0 events in release gate | Any throttle event | + +--- + +### PT-02: FDR/Storage Runner + +**Summary**: Verify 8-hour storage/endurance test orchestration. + +**Traces to**: AC-NEW-3 + +| Metric | Target | Failure Threshold | +|--------|--------|-------------------| +| FDR cap | <=64 GB | >64 GB | +| Rollover logging | Complete | Missing rollover event | + +## Security Tests + +### ST-01: Security Fixture Runner + +**Summary**: Verify stale/tampered cache, spoofed MAVLink, and false-anchor scenarios are automated. + +**Traces to**: AC-NEW-4, AC-NEW-6, AC-NEW-7 + +**Attack vector**: Cache tampering, stale imagery, spoofed GPS, impossible anchors. + +**Test procedure**: +1. Load each security fixture. +2. Run scenario through public runtime interfaces. +3. Validate output labels, FDR, and rejection reasons. + +**Expected behavior**: No tampered/stale/spoofed input produces a trusted false fix. + +**Pass criteria**: 0 accepted unsafe anchors or spoofed GPS promotions outside gates. + +## Acceptance Tests + +### AT-01: Traceability Completeness Report + +**Summary**: Verify every AC has executable or explicitly blocked test coverage. + +**Traces to**: All ACs + +| Step | Action | Expected Result | +|------|--------|-----------------| +| 1 | Read traceability matrix | All ACs mapped to tests | +| 2 | Run fixture validation | Missing public/representative data is reported as blocked, not passed | + +--- + +### AT-02: Release Evidence Bundle + +**Summary**: Verify release evidence can be assembled. + +**Traces to**: AC-NEW-1 through AC-NEW-8 + +| Step | Action | Expected Result | +|------|--------|-----------------| +| 1 | Run release profile | Reports, tlogs, FDR summaries, cache reports are produced | +| 2 | Collate artifacts | Bundle contains pass/fail status and residual blockers | + +## Test Data Management + +| Data Set | Description | Source | Size | +|----------|-------------|--------|------| +| `project_60_still_images` | Frame-center geolocation smoke | Project data | Project size | +| `public_dataset_slices` | MUN-FRL/ALTO/Kagaru/EPFL/AerialVL as licensed | Public pinned fixtures | Dataset-dependent | +| `sitl_scenarios` | Plane spoofing/failsafe traces | Generated | Small | +| `security_fixtures` | Stale/tampered/cache poisoning cases | Generated | Small | + +**Setup procedure**: Create isolated run directory, restore PostgreSQL schema, mount fixtures read-only, and start requested environment. + +**Teardown procedure**: Stop environments, archive reports, drop run schema, and delete temp volumes. + +**Data isolation strategy**: Unique run ID, schema, ports, cache staging directory, and FDR directory per scenario. diff --git a/_docs/02_document/data_model.md b/_docs/02_document/data_model.md new file mode 100644 index 0000000..e2907bf --- /dev/null +++ b/_docs/02_document/data_model.md @@ -0,0 +1,148 @@ +# Data Model + +## Scope + +This model defines system-level runtime, cache, telemetry, and validation data. PostgreSQL with PostGIS is the primary structured store for manifests, spatial metadata, mission state, and FDR event indexes. Large binary payloads remain local files: COG tiles, descriptor/index files, FDR payload segments, and replay fixtures. + +## Entity Overview + +| Entity | Purpose | Storage / Transport | Owner | +|--------|---------|---------------------|-------| +| MissionProfile | Operational area, sector type, route shape, altitude band, cache budget | Mission config file | Cache/tile lifecycle | +| CameraCalibration | Intrinsics, distortion, lens, fixed extrinsics, capture settings | Versioned calibration file | Camera ingest/calibration | +| FrameRecord | Per-frame metadata, timestamp, total-occlusion/blackout state, image quality, processing status | PostgreSQL/FDR event; replay fixture | Camera ingest/calibration | +| TelemetrySample | FC IMU, attitude, altitude, airspeed, GPS health | MAVLink stream; FDR event | MAVLink/GCS integration | +| VioState | BASALT relative state, velocity, bias, tracking quality | Internal DTO; FDR event | BASALT VIO adapter | +| PositionEstimate | WGS84 output, covariance, source label, anchor age, fix type | MAVLink DTO; FDR event | Safety/anchor wrapper | +| VprChunk | Retrieval footprint and descriptor metadata | PostgreSQL/PostGIS manifest + descriptor files | Satellite retrieval | +| AnchorCandidate | Top-K retrieval result and local verification metrics | Internal DTO; FDR event | Anchor verification | +| CacheTile | Service-source or generated COG tile metadata | PostgreSQL/PostGIS manifest + signed JSON sidecar | Cache/tile lifecycle | +| GeneratedTile | In-flight tile candidate with trust/provenance metadata | COG + sidecar + FDR event | Cache/tile lifecycle | +| FdrSegment | Bounded append-only mission evidence segment | PostgreSQL event index + CBOR segment payloads | FDR/observability | +| ValidationRun | Replay/test run metadata and outcomes | CSV/Markdown/test artifacts | Validation harness | + +## Core Entity Attributes + +### MissionProfile + +| Field | Type | Required | Notes | +|-------|------|----------|-------| +| `mission_id` | string | yes | Unique mission/run identifier | +| `operational_area_polygon` | geometry | yes | Up to ~400 km² | +| `sector_classification` | enum | yes | `active_conflict` or `stable_rear` | +| `planned_altitude_agl_m` | number | yes | <=1000 m AGL | +| `route_type` | enum | yes | `sector`, `transit_corridor`, or mixed | +| `cache_budget_bytes` | integer | yes | Default ~10 GB persistent | + +### CameraCalibration + +| Field | Type | Required | Notes | +|-------|------|----------|-------| +| `camera_model` | string | yes | ADTi 20MP 20L V1 family | +| `sensor_width_mm` | number | yes | Public spec check currently indicates 23.20 mm | +| `sensor_height_mm` | number | yes | Public spec check currently indicates 15.40 mm | +| `image_width_px` | integer | yes | Public spec check currently indicates 5456 px | +| `image_height_px` | integer | yes | Public spec check currently indicates 3632 px | +| `pixel_pitch_um` | number | yes | Public spec check indicates 4.25 um | +| `lens_focal_length_mm` | number | yes | TBD before implementation | +| `distortion_coefficients` | array | yes | From checkerboard calibration | +| `body_T_camera` | transform | yes | Fixed camera-to-body extrinsics | +| `spec_verification_status` | enum | yes | `manufacturer_verified`, `public_page_only`, `operator_supplied` | + +### PositionEstimate + +| Field | Type | Required | Notes | +|-------|------|----------|-------| +| `timestamp_ns` | integer | yes | Frame-aligned | +| `lat_deg` | number | yes | WGS84 | +| `lon_deg` | number | yes | WGS84 | +| `alt_msl_m` | number | yes | MSL altitude for `GPS_INPUT` | +| `covariance_95_semi_major_m` | number | yes | Must not be under-reported | +| `source_label` | enum | yes | `satellite_anchored`, `vo_extrapolated`, `dead_reckoned` | +| `last_satellite_anchor_age_ms` | integer | yes | Monotonic until new anchor | +| `fix_type` | integer | yes | MAVLink fix semantics | +| `horiz_accuracy_m` | number | yes | >= covariance semi-major mapping | +| `quality_flags` | bitset/string array | yes | Anchor, blackout, spoofing, stale tile, etc. | + +### FrameRecord + +| Field | Type | Required | Notes | +|-------|------|----------|-------| +| `frame_id` | string | yes | Stable frame/run identifier | +| `timestamp_ns` | integer | yes | Camera clock normalized by time-sync helper | +| `camera_calibration_id` | string | yes | Links to `CameraCalibration` | +| `occlusion_status` | enum | yes | `clear`, `partial_occlusion`, `total_occlusion`, `blackout` | +| `usable_for_vio` | boolean | yes | Must be false for total occlusion/blackout | +| `usable_for_anchor` | boolean | yes | Must be false for total occlusion/blackout | +| `blackout_reason` | enum | optional | `cloud`, `lens_cover`, `whiteout`, `decode_failure`, `underexposed`, `overexposed`, `unknown` | +| `blur_score` | number | yes | Quality metric | +| `texture_score` | number | yes | Quality metric | + +### CacheTile + +| Field | Type | Required | Notes | +|-------|------|----------|-------| +| `tile_id` | string | yes | Stable ID | +| `tile_type` | enum | yes | `service_source`, `generated_candidate`, `generated_soft`, `trusted_basemap` | +| `cog_path` | string | yes | Local path | +| `crs` | string | yes | Projection metadata | +| `meters_per_pixel` | number | yes | Must satisfy cache interface floor | +| `capture_date` | date | yes | Freshness gate | +| `source` | string | yes | Satellite Service or onboard generation | +| `sha256` | string | yes | Integrity | +| `signature_status` | enum | yes | `valid`, `missing`, `invalid` | +| `parent_pose_covariance_m` | number | generated only | Tile-write gate | +| `trust_level` | enum | yes | `rejected`, `candidate`, `soft`, `trusted` | + +## Relationships + +```mermaid +erDiagram + MissionProfile ||--o{ CacheTile : scopes + MissionProfile ||--o{ VprChunk : indexes + CameraCalibration ||--o{ FrameRecord : calibrates + FrameRecord ||--o{ VioState : contributes_to + TelemetrySample ||--o{ VioState : contributes_to + VioState ||--o{ PositionEstimate : propagates + VprChunk ||--o{ AnchorCandidate : retrieved_as + CacheTile ||--o{ AnchorCandidate : verified_against + AnchorCandidate ||--o{ PositionEstimate : may_anchor + PositionEstimate ||--o{ GeneratedTile : gates + PositionEstimate ||--o{ FdrSegment : recorded_in +``` + +## Storage Strategy + +| Data Class | Primary Format | Reason | +|------------|----------------|--------| +| Structured mission/cache/FDR metadata | PostgreSQL + PostGIS | Queryable freshness, coverage, spatial footprints, descriptors, tile status, and FDR event indexes | +| Tile audit sidecar | Signed JSON | Human/audit/service interchange per tile | +| Imagery tile | COG | Geospatial raster standard | +| Descriptor index | FAISS CPU index files + metadata | Fast top-K retrieval | +| FDR runtime payloads | CBOR segment files + PostgreSQL index | Bounded append payloads with queryable event metadata | +| FDR analysis export | Parquet optional | Post-flight analytics | +| Test report | CSV + Markdown | CI and human review | + +## Migration Strategy + +- PostgreSQL schemas use explicit `schema_version` and additive migrations by default. +- PostGIS geometry columns are used for mission polygons, tile footprints, VPR chunks, and generated-tile extents. +- FDR segment schema includes `segment_schema_version`; old readers must reject unknown required fields loudly. +- Sidecars include a `sidecar_version` and hash of the COG payload. +- Migrations are implemented as deterministic scripts with rollback for metadata-only changes. +- No database/table/column rename is allowed without explicit approval during implementation. + +## Seed Data Requirements + +| Environment | Seed Data | +|-------------|-----------| +| Development | 60 project images, `coordinates.csv`, small cache fixture, generated SITL traces | +| Public replay | Pinned MUN-FRL/ALTO/Kagaru/EPFL dataset slices and licenses | +| Jetson validation | Production-like cache/index, cold-start fixtures, thermal workload | +| Representative acceptance | Synchronized target nav-camera + FC telemetry + ground truth | + +## Backward Compatibility + +- Runtime should tolerate older cache sidecars if required fields exist and signatures validate. +- Generated tile sidecars must include all fields required by Satellite Service ingest; missing fields make the tile ineligible for promotion. +- FDR readers must support at least the current and previous segment schema version during the project lifecycle. diff --git a/_docs/02_document/deployment/README.md b/_docs/02_document/deployment/README.md new file mode 100644 index 0000000..c30bbed --- /dev/null +++ b/_docs/02_document/deployment/README.md @@ -0,0 +1,11 @@ +# Deployment Planning Index + +This directory contains the system-level deployment plan produced during Plan Step 2: + +- `containerization.md` +- `ci_cd_pipeline.md` +- `environment_strategy.md` +- `observability.md` +- `deployment_procedures.md` + +Component-specific implementation tasks are created later during decomposition. diff --git a/_docs/02_document/deployment/ci_cd_pipeline.md b/_docs/02_document/deployment/ci_cd_pipeline.md new file mode 100644 index 0000000..90b1390 --- /dev/null +++ b/_docs/02_document/deployment/ci_cd_pipeline.md @@ -0,0 +1,54 @@ +# CI/CD Pipeline + +## Pipeline Stages + +| Stage | Runs On | Gate | +|-------|---------|------| +| Format/lint | PR | Block merge | +| Unit tests | PR | Block merge | +| Replay black-box smoke | PR | Block merge | +| Cache/security fixture tests | PR | Block merge | +| Plane SITL spoof/failsafe tests | Release candidate / nightly | Block release | +| Public dataset replay | Nightly / release candidate | Block release | +| Jetson latency/resource tests | Release candidate | Block release | +| Thermal/FDR endurance | Release candidate / hardware qualification | Block release | + +## Artifact Outputs + +- Test CSV reports. +- FDR validation summaries. +- Cache integrity reports. +- Dataset replay metrics. +- SITL tlogs. +- Jetson profiling traces. + +## Caching + +- Cache dependency builds by lockfile hash. +- Cache public dataset slices only in controlled CI storage with license metadata. +- Do not cache secrets or signing keys. + +## Branch Policy + +- Work occurs on `dev`. +- Release gates must pass before deploy artifacts are considered production-ready. +- Any failed safety, spoofing, false-position, or cache-poisoning test blocks release. + +## Quality Gates + +| Gate | Threshold | +|------|-----------| +| Still-image geolocation | >=80% within 50 m and >=50% within 20 m | +| Hot-path latency | <400 ms p95 | +| Memory | <8 GB shared | +| Cold start | <30 s p95 | +| FDR | <=64 GB / 8-hour flight | +| Cache storage | <=10 GB unless split budget is approved | +| False position | AC-NEW-4 thresholds | + +## Open Tasks For Decomposition + +- Define CI runner labels for Docker/replay vs Jetson local hardware. +- Add dataset-license checks before public dataset jobs. +- Implement SITL scenario generation and tlog validation job. +- Implement report collation into a release evidence bundle. diff --git a/_docs/02_document/deployment/containerization.md b/_docs/02_document/deployment/containerization.md new file mode 100644 index 0000000..88965fa --- /dev/null +++ b/_docs/02_document/deployment/containerization.md @@ -0,0 +1,46 @@ +# Containerization + +## Strategy + +The production runtime targets Jetson hardware and may not be fully containerized for all camera/GPU paths. The test and development stack uses containers where practical, with local hardware execution required for release gates. + +## Runtime Units + +| Unit | Containerized? | Notes | +|------|----------------|-------| +| GPS-denied service | Optional on Jetson | Must access camera, CUDA/TensorRT/ONNX, MAVLink, local cache, FDR storage | +| Replay consumer | Yes | Deterministic black-box test harness | +| Satellite cache stub | Yes | Local fixture volume for COG/manifest/descriptors | +| ArduPilot Plane SITL | Yes or local process | Used for MAVLink and failsafe validation | +| QGC observer/log parser | Yes | Parses MAVLink status/tlogs | + +## Docker Compose Profiles + +| Profile | Purpose | Services | +|---------|---------|----------| +| `replay` | CI/PR deterministic fixture tests | gps-denied-service, replay-consumer, satellite-cache-stub | +| `sitl` | ArduPilot Plane integration tests | gps-denied-service, ardupilot-plane-sitl, qgc-observer | +| `jetson-local` | Documentation-only profile for local hardware run | Host runtime with local scripts/tasks created later | + +## Image Requirements + +- Base images must match JetPack/CUDA compatibility for GPU tests. +- Replay-only images may use standard Ubuntu/Python/C++ build images. +- No production image should contain secrets, mission signing keys, or provider credentials. +- Dataset downloads are not baked into images; they are mounted as versioned fixtures. + +## Volumes + +| Volume | Purpose | +|--------|---------| +| `/data/input` | Test images and public dataset slices | +| `/cache/satellite` | Offline cache fixture | +| `/fdr` | Runtime FDR output | +| `/test-results` | CSV/Markdown reports | + +## Open Tasks For Decomposition + +- Create Dockerfiles for replay-compatible service and consumer harness. +- Define Jetson local setup scripts for GPU/camera/MAVLink access. +- Create compose profiles for replay and SITL. +- Add license-aware public dataset fixture downloader. diff --git a/_docs/02_document/deployment/deployment_procedures.md b/_docs/02_document/deployment/deployment_procedures.md new file mode 100644 index 0000000..44de986 --- /dev/null +++ b/_docs/02_document/deployment/deployment_procedures.md @@ -0,0 +1,68 @@ +# Deployment Procedures + +## Deployment Targets + +| Target | Purpose | +|--------|---------| +| Replay environment | Development and CI fixtures | +| Plane SITL | MAVLink/failsafe validation | +| Jetson companion computer | Production runtime and release gating | +| Representative flight/replay rig | Final acceptance evidence | + +## Pre-Deployment Checklist + +- Camera lens, resolution, FPS, sensor dimensions, and operating temperature are manufacturer-verified. +- Camera intrinsics/extrinsics are calibrated and versioned. +- BASALT, OpenCV, FAISS, LightGlue, DINOv2/ONNX/TensorRT dependencies are pinned. +- TensorRT/ONNX descriptor-fidelity tests pass before optimized engines are used. +- Satellite cache manifests and sidecars validate signatures, hashes, freshness, and resolution. +- Plane SITL validates `GPS_INPUT` behavior with production parameters. +- Jetson latency, memory, and thermal release gates pass. +- FDR rollover test passes. + +## Deployment Steps + +1. Install JetPack-compatible runtime dependencies on the companion computer. +2. Install/build BASALT and native vision dependencies. +3. Pre-build any ONNX/TensorRT engines accepted by fidelity tests. +4. Sync mission cache from Satellite Service before flight. +5. Validate cache manifest, descriptors, signatures, resolution, and freshness. +6. Start the onboard service and verify FC telemetry connection. +7. Run cold-start first-fix check. +8. Confirm QGroundControl status and FDR segment creation. + +## Health Checks + +| Check | Pass Condition | +|-------|----------------| +| Camera input | Frames received with expected resolution/rate | +| FC telemetry | IMU/attitude/altitude/GPS-health stream healthy | +| Cache | Manifest and descriptor index valid | +| First fix | Valid `GPS_INPUT` <30 s p95 in cold-start test | +| Resource health | Memory <8 GB, no thermal throttle | +| QGC status | Status visible at configured downsample rate | +| FDR | Segment open and writable | + +## Rollback + +- If runtime dependency update fails tests, revert to previous pinned build. +- If cache manifest validation fails, reject the mission cache and resync/rebuild before flight. +- If optimized engine fidelity fails, fall back to PyTorch/ONNX path that passed descriptor tests. +- If BASALT candidate fails representative replay gates, evaluate Kimera backup or custom fallback tasks before production deployment. + +## Post-Flight Procedure + +1. Stop the onboard service cleanly. +2. Export FDR summary and integrity hashes. +3. Package generated tiles with sidecars and manifest delta. +4. Upload generated tile package to Satellite Service when connectivity is available. +5. Archive release evidence: tlogs, FDR summary, cache validation report, test results. + +## Deployment Blockers + +- ADTi camera spec mismatch unresolved for FPS/resolution/lens/temperature. +- Missing representative synchronized nav-camera + FC telemetry + ground truth for final acceptance. +- Any false-position safety budget failure. +- Any cache-poisoning gate failure. +- Any Plane SITL `GPS_INPUT` failure. +- Thermal throttling during the 8-hour target workload. diff --git a/_docs/02_document/deployment/environment_strategy.md b/_docs/02_document/deployment/environment_strategy.md new file mode 100644 index 0000000..d4609c3 --- /dev/null +++ b/_docs/02_document/deployment/environment_strategy.md @@ -0,0 +1,49 @@ +# Environment Strategy + +## Environments + +| Environment | Purpose | Hardware | +|-------------|---------|----------| +| Development replay | Fast local iteration with fixtures | Developer workstation | +| CI replay | Deterministic PR checks | Docker runner | +| Public dataset replay | Nightly/RC algorithm validation | Docker or GPU runner | +| Plane SITL | MAVLink/failsafe validation | Docker/local SITL | +| Jetson hardware validation | Production path latency, memory, GPU, camera, thermal | Jetson Orin Nano Super | +| Representative flight/replay | Final acceptance evidence | Target-like UAV/FC/camera setup | + +## Configuration Classes + +| Config | Development | Production | +|--------|-------------|------------| +| Satellite cache | Small fixture | Full mission cache | +| PostgreSQL/PostGIS | Local test DB with fixture manifests | Local onboard DB with signed mission manifests, spatial metadata, and FDR event indexes | +| Descriptor index | Small FAISS index | Full operational-area index | +| MAVLink | SITL/replay | Physical FC link | +| FDR | Temporary directory | Per-flight NVMe directory with rollover | +| Dataset fixtures | Optional public slices | Not used at runtime | + +## Secrets And Signing + +- Mission signing keys are never committed. +- Test keys may be committed only if clearly labeled as non-production. +- Provider credentials are not used by onboard runtime. +- Any Satellite Service sync credentials are post-flight/deployment environment secrets. + +## Dataset Licensing + +Public datasets must be tagged before use: + +| Dataset | Expected Use | License Constraint | +|---------|--------------|--------------------| +| MUN-FRL | Preferred public VIO/nadir replay | CC BY 4.0 per current docs | +| ALTO | Preferred aerial localization/VPR replay | BSD-3 repository; dataset availability must be pinned | +| Kagaru | Fixed-wing/farmland validation candidate | Verify terms before commercial use | +| EPFL fixed-wing | Fixed-wing validation candidate | Verify terms before commercial use | +| VPAir | VPR/localization only | Academic-use restriction likely blocks commercial acceptance | +| UZH FPV | VIO stress proxy only | Non-commercial license blocks commercial acceptance | + +## Promotion Rules + +- A result from public datasets can de-risk implementation but cannot replace representative acceptance data. +- A release candidate cannot be promoted without Jetson hardware validation and Plane SITL. +- A mission cache cannot be used if manifest/signature/freshness validation fails. diff --git a/_docs/02_document/deployment/observability.md b/_docs/02_document/deployment/observability.md new file mode 100644 index 0000000..a5558cc --- /dev/null +++ b/_docs/02_document/deployment/observability.md @@ -0,0 +1,61 @@ +# Observability + +## Goals + +- Explain every emitted position estimate. +- Detect false-position risk before it reaches the flight controller. +- Preserve enough evidence to replay incidents without storing raw frames. +- Surface operator-relevant status to QGroundControl without saturating telemetry. + +## Runtime Signals + +| Signal | Frequency | Destination | Notes | +|--------|-----------|-------------|-------| +| Position estimate | Per processed frame locally | FDR, MAVLink `GPS_INPUT` | GCS receives downsampled status | +| Source label | Per estimate | FDR, status summary | `satellite_anchored`, `vo_extrapolated`, `dead_reckoned` | +| Covariance semi-major | Per estimate | FDR, `GPS_INPUT.horiz_accuracy` mapping | Must not under-report | +| Anchor decision | Per candidate | FDR | Include MRE, inliers, tile provenance, rejection reason | +| Cache validation | On cache load / tile read | FDR, health log | Signature, freshness, resolution, hash | +| Blackout/spoofing status | On transition and 1-2 Hz while active | QGC, FDR | Operator status | +| Total occlusion status | Per transition and sampled while active | FDR, QGC if persistent | Indicates VIO is bypassed and IMU-only propagation is active | +| Resource health | 1 Hz or configurable | FDR, QGC warning on threshold | CPU/GPU/temp/memory/throttle | +| Tile write decision | Per generated tile | FDR, sidecar | Include parent covariance and trust level | + +## Logs + +| Log Type | Format | Retention | +|----------|--------|-----------| +| FDR events/index | PostgreSQL tables + CBOR payload segments | <=64 GB per flight, rollover | +| MAVLink raw stream | tlog or equivalent | FDR cap | +| Health metrics | FDR event stream | FDR cap | +| Test reports | CSV/Markdown | CI artifact retention | + +## Alerts And Status Text + +| Condition | Status | +|-----------|--------| +| Visual blackout starts | `VISUAL_BLACKOUT_IMU_ONLY` | +| Total occlusion before VIO | `VISUAL_OCCLUSION_IMU_ONLY` | +| Blackout failsafe threshold exceeded | `VISUAL_BLACKOUT_FAILSAFE` | +| Spoofing promotion/demotion | QGC status text with mode and timestamp | +| Stale cache tile rejected | Warning in FDR; QGC only if mission-impacting | +| Thermal throttle risk | QGC warning before throttle if possible | +| No estimate for threshold | Relocalization request / failsafe status | + +## Metrics For Release Evidence + +- Error CDF against ground truth. +- Anchor-age binned error. +- Covariance calibration plot. +- VIO completion rate. +- Relocalization trigger-to-anchor latency. +- Cache freshness rejection counts. +- FDR size over 8 hours. +- Thermal/throttle timeline. + +## Open Tasks For Decomposition + +- Define FDR schema and event names. +- Define QGC status vocabulary and rate limiting. +- Define telemetry-to-report export tooling. +- Define covariance calibration dashboard/report. diff --git a/_docs/02_document/diagrams/component_overview.md b/_docs/02_document/diagrams/component_overview.md new file mode 100644 index 0000000..39fa5ea --- /dev/null +++ b/_docs/02_document/diagrams/component_overview.md @@ -0,0 +1,46 @@ +# Component Overview Diagram + +```mermaid +flowchart LR + camera[01 Camera Ingest And Calibration] + vio[02 BASALT VIO Adapter] + wrapper[03 Safety And Anchor Wrapper] + retrieval[04 Satellite Retrieval] + verify[05 Anchor Verification] + cache[06 Cache And Tile Lifecycle] + mav[07 MAVLink And GCS Integration] + fdr[08 FDR And Observability] + tests[09 Validation Harness] + + navCam[[Nav Camera]] --> camera + fc[[ArduPilot Plane FC]] --> mav + satSvc[[Satellite Service]] --> cache + datasets[[Replay/Public Datasets]] --> tests + + camera --> vio + mav --> vio + vio --> wrapper + wrapper --> retrieval + retrieval --> verify + cache --> retrieval + cache --> verify + verify --> wrapper + wrapper --> mav + wrapper --> cache + camera --> cache + + camera --> fdr + vio --> fdr + wrapper --> fdr + retrieval --> fdr + verify --> fdr + cache --> fdr + mav --> fdr + + tests --> camera + tests --> mav + tests --> cache + mav --> qgc[[QGroundControl]] + mav --> fc + cache --> satSvc +``` diff --git a/_docs/02_document/diagrams/flows/flow_cache_tile_lifecycle.md b/_docs/02_document/diagrams/flows/flow_cache_tile_lifecycle.md new file mode 100644 index 0000000..b4bf0af --- /dev/null +++ b/_docs/02_document/diagrams/flows/flow_cache_tile_lifecycle.md @@ -0,0 +1,18 @@ +# Flow: Cache And Generated Tile Lifecycle + +```mermaid +flowchart TD + preflight([Pre-flight cache sync]) --> validate[06 Validate manifest signatures hashes freshness] + validate --> cacheOk{Cache valid?} + cacheOk -->|No| block[Block cache usage and report] + cacheOk -->|Yes| load[04 Load descriptor metadata and FAISS index] + load --> flight([Flight runtime]) + flight --> eligibility[03 Tile write eligibility check] + eligibility --> eligible{Covariance and quality pass?} + eligible -->|No| noWrite[Do not write generated tile] + eligible -->|Yes| write[06 Write COG + signed JSON sidecar] + write --> fdr[08 Record tile-write audit] + fdr --> postflight([Post-flight]) + postflight --> package[06 Package generated tiles + manifest delta] + package --> sync[[Satellite Service ingest]] +``` diff --git a/_docs/02_document/diagrams/flows/flow_normal_localization.md b/_docs/02_document/diagrams/flows/flow_normal_localization.md new file mode 100644 index 0000000..1a5bf77 --- /dev/null +++ b/_docs/02_document/diagrams/flows/flow_normal_localization.md @@ -0,0 +1,21 @@ +# Flow: Normal Localization + +```mermaid +flowchart TD + start([Frame + FC telemetry]) --> ingest[01 Camera ingest and quality] + ingest --> occlusion{Total occlusion or blackout?} + occlusion -->|Yes| imuOnly[03 IMU-only dead_reckoned propagation] + occlusion -->|No| frameOk{Frame usable for VIO?} + frameOk -->|No| degrade[03 Safety wrapper degraded mode] + frameOk -->|Yes| vio[02 BASALT VIO adapter] + telemetry[07 MAVLink telemetry] --> vio + vio --> healthy{VIO healthy?} + healthy -->|Yes| wrap[03 Covariance calibration + source label] + healthy -->|No| trigger[Trigger relocalization] + wrap --> emit[07 Emit GPS_INPUT and QGC status] + wrap --> record[08 Record FDR event] + emit --> endNode([Position output]) + trigger --> satFlow[[Satellite relocalization flow]] + imuOnly --> emit + degrade --> emit +``` diff --git a/_docs/02_document/diagrams/flows/flow_satellite_relocalization.md b/_docs/02_document/diagrams/flows/flow_satellite_relocalization.md new file mode 100644 index 0000000..37b85fc --- /dev/null +++ b/_docs/02_document/diagrams/flows/flow_satellite_relocalization.md @@ -0,0 +1,21 @@ +# Flow: Satellite Relocalization + +```mermaid +flowchart TD + start([Relocalization trigger]) --> request[03 Build retrieval request] + request --> retrieve[04 DINOv2-VLAD + FAISS top-K] + retrieve --> candidates{Candidates found?} + candidates -->|No| degraded[03 Continue degraded/dead reckoned] + candidates -->|Yes| verify[05 ALIKED/DISK + LightGlue + RANSAC] + verify --> geometry{Geometry passes?} + geometry -->|No| degraded + geometry -->|Yes| gates[03 Freshness/provenance/Mahalanobis gates] + gates --> accepted{Anchor accepted?} + accepted -->|No| degraded + accepted -->|Yes| update[03 Apply absolute correction] + update --> emit[07 Emit anchored GPS_INPUT] + degraded --> emitDegraded[07 Emit degraded GPS_INPUT/status] + emit --> record[08 Record anchor decision] + emitDegraded --> record + record --> endNode([Relocalization result]) +``` diff --git a/_docs/02_document/epics.md b/_docs/02_document/epics.md new file mode 100644 index 0000000..0d4baab --- /dev/null +++ b/_docs/02_document/epics.md @@ -0,0 +1,131 @@ +# Work Item Epics + +**Tracker**: Jira +**Project**: AZAION (`AZ`) +**Date**: 2026-05-01 +**Labels**: `gps-denied-onboard-plan`, `autodev` +**Lessons applied**: No `_docs/LESSONS.md` file exists; no prior estimation or dependency lessons were available. + +## Dependency Order + +| Order | Jira ID | Epic | Type | Depends On | Estimate | +|-------|---------|------|------|------------|----------| +| 1 | AZ-206 | Bootstrap & Initial Structure | bootstrap | none | M / 5-8 pts | +| 2 | AZ-207 | Cross-Cutting: Shared Geometry And Time Sync | cross-cutting | AZ-206 | S-M / 3-5 pts | +| 3 | AZ-208 | Cross-Cutting: Runtime Configuration And Errors | cross-cutting | AZ-206 | S-M / 3-5 pts | +| 4 | AZ-209 | Camera Ingest And Calibration | component | AZ-206, AZ-207, AZ-208 | M / 5-8 pts | +| 5 | AZ-210 | MAVLink And GCS Integration | component | AZ-206, AZ-208 | M / 5-8 pts | +| 6 | AZ-211 | Cache And Tile Lifecycle | component | AZ-206, AZ-207, AZ-208 | L / 8-13 pts | +| 7 | AZ-212 | FDR And Observability | component | AZ-206, AZ-208 | M-L / 5-8 pts | +| 8 | AZ-213 | BASALT VIO Adapter | component | AZ-206, AZ-207, AZ-208, AZ-209, AZ-210 | L / 8-13 pts | +| 9 | AZ-214 | Satellite Retrieval | component | AZ-206, AZ-207, AZ-208, AZ-209, AZ-211 | L / 8-13 pts | +| 10 | AZ-215 | Anchor Verification | component | AZ-206, AZ-207, AZ-208, AZ-209, AZ-211, AZ-214 | L / 8-13 pts | +| 11 | AZ-216 | Safety And Anchor Wrapper | component | AZ-206, AZ-207, AZ-208, AZ-209, AZ-210, AZ-213, AZ-215 | XL / 13-21 pts | +| 12 | AZ-217 | Validation Harness | component | AZ-206, AZ-207, AZ-208, component epics | L / 8-13 pts | +| 13 | AZ-218 | Blackbox Tests | blackbox-tests | AZ-206, AZ-217, component epics | L / 8-13 pts | + +## Component Mapping + +| Component / Artifact | Epic | +|----------------------|------| +| Project scaffold, shared DTOs, migrations, CI skeleton | AZ-206 | +| `common-helpers/01_helper_geo_geometry.md` | AZ-207 | +| `common-helpers/02_helper_time_sync.md` | AZ-207 | +| Runtime config, error contracts, health checks | AZ-208 | +| `components/01_camera_ingest_calibration/` | AZ-209 | +| `components/02_basalt_vio_adapter/` | AZ-213 | +| `components/03_safety_anchor_wrapper/` | AZ-216 | +| `components/04_satellite_retrieval/` | AZ-214 | +| `components/05_anchor_verification/` | AZ-215 | +| `components/06_cache_tile_lifecycle/` | AZ-211 | +| `components/07_mavlink_gcs_integration/` | AZ-210 | +| `components/08_fdr_observability/` | AZ-212 | +| `components/09_validation_harness/` | AZ-217 | +| System blackbox/performance/resilience/security/resource tests | AZ-218 | + +## Epic Relationship Diagram + +```mermaid +flowchart TD + bootstrap[AZ-206 Bootstrap] + geo[AZ-207 Shared Geometry And Time Sync] + config[AZ-208 Runtime Configuration And Errors] + camera[AZ-209 Camera Ingest] + mavlink[AZ-210 MAVLink And GCS] + cache[AZ-211 Cache And Tile Lifecycle] + fdr[AZ-212 FDR And Observability] + vio[AZ-213 BASALT VIO Adapter] + retrieval[AZ-214 Satellite Retrieval] + anchor[AZ-215 Anchor Verification] + safety[AZ-216 Safety And Anchor Wrapper] + validation[AZ-217 Validation Harness] + blackbox[AZ-218 Blackbox Tests] + + bootstrap --> geo + bootstrap --> config + bootstrap --> camera + bootstrap --> mavlink + bootstrap --> cache + bootstrap --> fdr + geo --> camera + geo --> cache + geo --> vio + geo --> retrieval + geo --> anchor + geo --> safety + config --> camera + config --> mavlink + config --> cache + config --> fdr + config --> vio + config --> retrieval + config --> anchor + config --> safety + camera --> vio + mavlink --> vio + camera --> retrieval + cache --> retrieval + retrieval --> anchor + camera --> anchor + cache --> anchor + vio --> safety + anchor --> safety + mavlink --> safety + safety --> cache + safety --> mavlink + safety --> fdr + camera --> fdr + cache --> fdr + validation --> blackbox + safety --> validation + fdr --> validation +``` + +## Cross-Cutting Ownership + +| Concern | Owner Epic | Rule | +|---------|------------|------| +| Geospatial math, WGS84/local conversions, GSD, footprints | AZ-207 | Components consume shared helper; no local duplicate implementations | +| Timestamp validation, IMU/frame alignment, replay ordering | AZ-207 | Components consume shared helper; no local duplicate implementations | +| Runtime configuration, environment profiles, startup validation | AZ-208 | Components consume shared config loader and health-check contract | +| Shared error/result envelopes | AZ-208 | Components use shared error categories and do not swallow failures | + +## Created Jira Epics + +- AZ-206 — Bootstrap & Initial Structure +- AZ-207 — Cross-Cutting: Shared Geometry And Time Sync +- AZ-208 — Cross-Cutting: Runtime Configuration And Errors +- AZ-209 — Camera Ingest And Calibration +- AZ-210 — MAVLink And GCS Integration +- AZ-211 — Cache And Tile Lifecycle +- AZ-212 — FDR And Observability +- AZ-213 — BASALT VIO Adapter +- AZ-214 — Satellite Retrieval +- AZ-215 — Anchor Verification +- AZ-216 — Safety And Anchor Wrapper +- AZ-217 — Validation Harness +- AZ-218 — Blackbox Tests + +## Tracker Notes + +Jira authentication succeeded. A transient Jira server-side PostgreSQL timeout occurred while creating `Blackbox Tests`; the write was recorded under `_docs/_process_leftovers/` and then successfully retried as AZ-218. The leftover entry was deleted after replay success. diff --git a/_docs/02_document/glossary.md b/_docs/02_document/glossary.md new file mode 100644 index 0000000..06968e3 --- /dev/null +++ b/_docs/02_document/glossary.md @@ -0,0 +1,96 @@ +# Glossary + +**Status**: confirmed-by-user +**Date**: 2026-05-01 + +## Aerial VPR + +Visual place recognition over aerial/nadir imagery; used to retrieve candidate satellite/cache chunks for a UAV frame. (source: `solution.md`) + +## ADTi 20MP 20L V1 + +Selected navigation-camera family. Public product pages list Sony APS-C CMOS, 5456 x 3632 max image size, 23.20 x 15.40 mm sensor, 4.25 um pixel pitch, Sony E mount, and 2 fps continuous capture; final manufacturer specification remains a verification risk. (source: `restrictions.md`, user-confirmed open-question review) + +## Anchor + +Accepted absolute visual match to a georeferenced cache tile, used to correct VO/IMU drift. (source: `acceptance_criteria.md`, `solution.md`) + +## ArduPilot Plane SITL + +Simulation environment used to verify `GPS_INPUT`, spoofing, failsafe, and MAVLink behavior with the production Plane parameter set. (source: `acceptance_criteria.md`, `tests/environment.md`) + +## BASALT VIO + +Selected production relative visual-inertial odometry candidate. It consumes calibrated navigation-camera frames and IMU data but does not own the product's safety, anchor, cache, or MAVLink semantics. (source: `solution.md`) + +## Cache Poisoning + +Failure mode where a misaligned onboard-generated tile is written back and later corrupts future satellite-cache anchors. (source: `acceptance_criteria.md`) + +## COG Tile + +Cloud Optimized GeoTIFF raster object used as the write-new unit for georeferenced service tiles and generated onboard tiles. (source: `solution.md`) + +## FDR + +Flight Data Recorder. Bounded per-flight recorder for estimates, IMU traces, emitted MAVLink, health telemetry, tile writes, and audit evidence; raw nav/AI frames are not retained. (source: `acceptance_criteria.md`, `solution.md`) + +## Generated Tile + +In-flight orthorectified tile created from navigation-camera imagery and stored locally for post-flight Satellite Service sync. (source: `acceptance_criteria.md`) + +## `GPS_INPUT` + +MAVLink message used as the ArduPilot GPS substitute in v1. It carries WGS84 coordinates, fix type, accuracy fields, and ignore flags. (source: `acceptance_criteria.md`, `solution.md`) + +## Kimera Backup + +BSD-friendly VIO backup candidate if BASALT fails project replay/runtime gates. (source: `solution.md`) + +## Mahalanobis Gate + +Statistical consistency gate used to reject anchor updates that are inconsistent with the current estimator state and covariance. (source: `solution.md`) + +## Nadir Camera + +Fixed downward-pointing navigation camera used for localization. It is not gimbal-stabilized. (source: `restrictions.md`) + +## OpenVINS Reference + +GPLv3 VIO/covariance baseline used for replay comparison and uncertainty calibration; not the default production dependency. (source: `solution.md`) + +## Public Replay Dataset + +External dataset used to cover validation gaps in the current sample data, especially synchronized nadir camera, IMU, GNSS/ground truth, and reference imagery. MUN-FRL and ALTO are first-choice candidates. (source: `tests/test-data.md`) + +## QGroundControl + +Supported ground station that receives downsampled status and failsafe messages at 1-2 Hz. (source: `restrictions.md`, `acceptance_criteria.md`) + +## Representative Replay Rig + +Final acceptance dataset or hardware setup from the target flight profile with synchronized nav camera, FC IMU/attitude/airspeed/altitude, emitted MAVLink, and ground truth. (source: `acceptance_criteria.md`, `tests/test-data.md`) + +## Safety/Anchor Wrapper + +Project-owned layer around BASALT that calibrates confidence, fuses satellite anchors, owns source labels, handles degraded modes, gates generated tiles, and emits MAVLink outputs. (source: `solution.md`) + +## Satellite Service + +External Azaion Suite component that prepares the offline satellite cache before flight and ingests generated tiles after landing. The onboard system does not call it in-flight. (source: `restrictions.md`) + +## Source Label + +Categorical label attached to every estimate: `{satellite_anchored, vo_extrapolated, dead_reckoned}`. (source: `acceptance_criteria.md`) + +## Tile Freshness + +Runtime age gate for cache tiles: active-conflict sectors require newer imagery than stable rear sectors. (source: `acceptance_criteria.md`) + +## Visual Blackout + +State where the navigation camera provides no usable localization signal because of clouds, occlusion, whiteout, or similar visual loss. (source: `acceptance_criteria.md`) + +## VPR Chunk + +Ground-footprint-sized retrieval unit, approximately 600-800 m with overlap, decoupled from the storage tile convention. (source: `acceptance_criteria.md`) diff --git a/_docs/02_document/risk_mitigations.md b/_docs/02_document/risk_mitigations.md new file mode 100644 index 0000000..263cdcf --- /dev/null +++ b/_docs/02_document/risk_mitigations.md @@ -0,0 +1,275 @@ +# Risk Assessment — Architecture Review — Iteration 01 + +## Evaluator Pass Summary + +| Check | Result | Notes | +|-------|--------|-------| +| Single Responsibility | Pass | Components each own one primary concern: ingest, VIO, safety, retrieval, verification, cache, MAVLink, FDR, validation | +| Dumb Code / Smart Data | Pass | Complex behavior is mostly expressed through DTOs, mode labels, covariance fields, manifests, and gates | +| Interface Consistency | Pass with fix | Safety wrapper no longer directly depends on cache lifecycle for anchor acceptance; cache freshness/provenance travels through `AnchorDecision` | +| Circular Dependencies | Pass with caution | Runtime flow is acyclic at component ownership level; MAVLink remains a bidirectional protocol adapter but owns no localization policy | +| Missing Interactions | Pass | Pre-VIO occlusion, IMU-only blackout, relocalization, tile writes, FDR, and SITL validation are all represented | +| Security Considerations | Pass | Signed cache sidecars, source/system ID checks, spoofing rejection, and no in-flight satellite-provider access are covered | +| Performance Bottlenecks | Pass | Jetson latency, VPR/local matching, FDR append pressure, PostgreSQL availability, and thermal limits are identified | +| API Contracts | Pass | Core DTO handoffs are documented: `FramePacket`, `VioStatePacket`, `AnchorDecision`, `PositionEstimate`, `FdrEvent` | + +## Risk Scoring Matrix + +| | Low Impact | Medium Impact | High Impact | +|--|------------|---------------|-------------| +| **High Probability** | Medium | High | Critical | +| **Medium Probability** | Low | Medium | High | +| **Low Probability** | Low | Low | Medium | + +## Acceptance Criteria by Risk Level + +| Level | Action Required | +|-------|-----------------| +| Low | Accepted and monitored | +| Medium | Mitigation plan required before implementation | +| High | Mitigation + contingency plan required, reviewed during implementation | +| Critical | Must be resolved before proceeding to next planning step | + +## Risk Register + +| ID | Risk | Category | Probability | Impact | Score | Mitigation | Owner | Status | +|----|------|----------|-------------|--------|-------|------------|-------|--------| +| R01 | ADTi 20MP 20L V1 public specs conflict with planning assumptions for resolution, FPS, lens, interface, and temperature | Technical / External | Medium | High | High | Pin manufacturer datasheet and exact lens/interface before implementation; make camera calibration/spec task a bootstrap blocker | Camera ingest/calibration | Mitigated by gate | +| R02 | BASALT may underperform or lose tracking on nadir fixed-wing low-parallax terrain | Technical | Medium | High | High | Public replay with MUN-FRL/ALTO/Kagaru/EPFL where applicable, representative target replay, OpenVINS reference comparison, Kimera backup path | BASALT VIO adapter | Mitigated by validation | +| R03 | BASALT confidence/covariance may under-report real error | Safety | Medium | High | High | Wrapper owns covariance calibration; compare against ground truth, satellite residuals, and OpenVINS reference; never emit optimistic `horiz_accuracy` | Safety/anchor wrapper | Mitigated by wrapper design | +| R04 | Total occlusion detector may false-negative and feed unusable frames into VIO | Safety / Technical | Medium | High | High | Conservative pre-VIO occlusion gate, FDR status, tests for total blackout, and fallback to IMU-only `dead_reckoned` mode | Camera ingest/calibration | Mitigated by spec/test | +| R05 | IMU-only blackout propagation could be trusted too long | Safety | Medium | High | High | Monotonic covariance growth, `dead_reckoned` label, `fix_type=0`/`horiz_accuracy=999.0` when >30 s or covariance >500 m | Safety/anchor wrapper | Mitigated by AC gate | +| R06 | DINOv2-VLAD + ALIKED/DISK-LightGlue exceeds Jetson latency/memory budget | Performance | Medium | High | High | Trigger-only execution, CPU FAISS first, top-K caps, model profiling, TensorRT only after fidelity checks | Satellite retrieval / Anchor verification | Mitigated by profiling gates | +| R07 | PostgreSQL/PostGIS local DB is unavailable or too heavy for onboard runtime | Technical / Operational | Medium | High | High | Run local onboard PostgreSQL, health-check before flight, keep large payloads in files, fail mission cache validation if DB unavailable | Cache lifecycle / FDR | Mitigated by deployment gates | +| R08 | Generated tile cache poisoning corrupts future anchors | Security / Safety | Low | High | Medium | Sigma gate, provenance sidecars, post-flight Satellite Service voting, no direct promotion to trusted basemap | Cache/tile lifecycle | Mitigated by policy | +| R09 | Public datasets do not cover final target terrain or commercial license needs | External / Schedule | Medium | Medium | Medium | Use public data for de-risking only; representative synchronized target data remains mandatory for acceptance | Validation harness | Mitigated by acceptance rule | +| R10 | MAVLink `GPS_INPUT` parameters or Plane behavior differs from assumptions | Integration | Medium | High | High | Plane SITL release gate with production parameters, spoofing/failsafe tests, raw field validation with pymavlink | MAVLink/GCS integration | Mitigated by SITL gate | +| R11 | FDR appends or PostgreSQL indexing interferes with hot-path latency | Performance | Medium | Medium | Medium | Append asynchronously, use CBOR payload segments for high-volume data, keep PostgreSQL as event index/query surface | FDR/observability | Mitigated by design | +| R12 | GPL/non-commercial tooling accidentally enters production or acceptance evidence | Legal / Compliance | Low | High | Medium | Keep OpenVINS/ORB-SLAM3 reference-only; license-tag datasets before CI; SuperPoint only after legal approval | Validation harness / Architecture | Mitigated by gates | + +## Detailed Risk Analysis + +### R01: Camera Specification Mismatch + +**Description**: Public ADTi pages show 5456 x 3632 stills, 2 fps continuous capture, Sony E mount, and -10..40 C operation. The project needs the exact production lens, camera interface, sustained capture behavior, thermal behavior, and calibration model. + +**Trigger conditions**: Manufacturer documentation or hardware testing contradicts assumed FPS, interface, temperature, or lens characteristics. + +**Affected components**: Camera ingest/calibration, BASALT VIO adapter, validation harness, deployment procedures. + +**Mitigation strategy**: +1. Make camera specification verification a bootstrap task. +2. Require manufacturer datasheet or hardware measurement before implementation claims 3 fps or hot-environment operation. +3. Version calibration data by exact camera/lens/interface. + +**Contingency plan**: Reduce frame rate assumptions, adjust latency tests, or select a different navigation camera/lens/interface. + +**Residual risk after mitigation**: Medium. + +**Documents updated**: `glossary.md`, `architecture.md`, `components/01_camera_ingest_calibration/description.md`, `deployment/deployment_procedures.md`. + +--- + +### R02: BASALT Nadir Fixed-Wing Fit + +**Description**: BASALT is a strong VIO candidate, but fixed downward cameras over planar terrain can cause low-parallax and texture-degeneracy cases. + +**Trigger conditions**: Public or representative replay shows high drift, frequent tracking loss, or poor initialization. + +**Affected components**: BASALT VIO adapter, safety/anchor wrapper, validation harness. + +**Mitigation strategy**: +1. Run MUN-FRL first for synchronized nadir camera + IMU + ground truth. +2. Add ALTO/Kagaru/EPFL slices where available for aerial/fixed-wing realism. +3. Compare against OpenVINS reference and Kimera backup. + +**Contingency plan**: Keep Kimera backup or build a project-owned fallback estimator around OpenCV + IMU only after replay evidence requires it. + +**Residual risk after mitigation**: Medium. + +**Documents updated**: `architecture.md`, `components/02_basalt_vio_adapter/description.md`, `tests/test-data.md`. + +--- + +### R03: Covariance Under-Reporting + +**Description**: Incorrect confidence is more dangerous than no estimate because the flight controller may trust a false fix. + +**Trigger conditions**: Replay error exceeds reported covariance, or anchors are accepted despite inconsistent residuals. + +**Affected components**: Safety/anchor wrapper, MAVLink/GCS integration, FDR/observability. + +**Mitigation strategy**: +1. Make wrapper covariance the product authority, not BASALT raw confidence. +2. Validate calibration against ground truth, satellite residuals, and OpenVINS reference. +3. Map `horiz_accuracy` so it never under-reports the 95% semi-major covariance axis. + +**Contingency plan**: Degrade to no-fix sooner and require operator relocalization or mission abort behavior. + +**Residual risk after mitigation**: Medium. + +**Documents updated**: `architecture.md`, `components/03_safety_anchor_wrapper/description.md`, `tests/blackbox-tests.md`. + +--- + +### R04: Total Occlusion Detection Failure + +**Description**: If total occlusion is not detected before VIO, BASALT may receive unusable frames and produce misleading state updates. + +**Trigger conditions**: Lens cover, cloud/whiteout, decode failure, underexposure/overexposure, or textureless frame reaches VIO as usable. + +**Affected components**: Camera ingest/calibration, safety/anchor wrapper, BASALT VIO adapter. + +**Mitigation strategy**: +1. Camera ingest exposes `OcclusionReport` and sets `usable_for_vio=false` for total occlusion/blackout. +2. Total occlusion bypasses BASALT for that frame. +3. Safety wrapper switches to IMU-only `dead_reckoned` propagation with monotonic covariance growth. + +**Contingency plan**: Tune detector conservatively and accept temporary false-positive IMU-only degradation over false VIO confidence. + +**Residual risk after mitigation**: Medium. + +**Documents updated**: `components/01_camera_ingest_calibration/description.md`, `components/03_safety_anchor_wrapper/description.md`, `system-flows.md`, `diagrams/flows/flow_normal_localization.md`, `tests/resilience-tests.md`. + +--- + +### R05: IMU-Only Mode Over-Trust + +**Description**: IMU-only propagation drifts quickly and must be treated as an emergency bridge, not a long-duration solution. + +**Trigger conditions**: Blackout lasts longer than 30 seconds or covariance exceeds 500 m. + +**Affected components**: Safety/anchor wrapper, MAVLink/GCS integration, FDR/observability. + +**Mitigation strategy**: +1. Emit `source_label=dead_reckoned` during IMU-only mode. +2. Grow covariance monotonically. +3. Emit `fix_type=0`, `horiz_accuracy=999.0`, and `VISUAL_BLACKOUT_FAILSAFE` at thresholds. + +**Contingency plan**: Stop publishing valid fixes and require relocalization/operator action. + +**Residual risk after mitigation**: Low. + +**Documents updated**: `components/03_safety_anchor_wrapper/description.md`, `system-flows.md`, `tests/blackbox-tests.md`, `tests/resilience-tests.md`, `tests/traceability-matrix.md`. + +--- + +### R06: Trigger Path Performance + +**Description**: DINOv2-VLAD and learned local matching can exceed Jetson latency/memory limits. + +**Trigger conditions**: Relocalization exceeds p95 latency, memory budget, or causes thermal throttling. + +**Affected components**: Satellite retrieval, anchor verification, validation harness. + +**Mitigation strategy**: +1. Keep VPR/local matching trigger-based. +2. Use CPU FAISS first and bounded top-K. +3. Accept optimized engines only after descriptor-fidelity tests pass. + +**Contingency plan**: Reduce descriptor resolution/model size, reduce top-K, or fall back to classical features for emergency operation. + +**Residual risk after mitigation**: Medium. + +**Documents updated**: `architecture.md`, `components/04_satellite_retrieval/description.md`, `components/05_anchor_verification/description.md`, `tests/performance-tests.md`. + +--- + +### R07: Onboard PostgreSQL/PostGIS Availability + +**Description**: PostgreSQL/PostGIS is now the structured metadata store. If local DB availability or resource use is poor, cache/FDR queries may fail. + +**Trigger conditions**: Local DB does not start, DB files corrupt, DB consumes too much memory/I/O, or migrations fail. + +**Affected components**: Cache/tile lifecycle, FDR/observability, deployment procedures. + +**Mitigation strategy**: +1. Require local onboard PostgreSQL health check before flight. +2. Store large imagery/descriptors/CBOR payloads as files, not DB blobs. +3. Treat DB unavailability as a mission-cache validation blocker. + +**Contingency plan**: Abort mission-cache activation and run only no-cache degraded modes or resync/rebuild DB before flight. + +**Residual risk after mitigation**: Medium. + +**Documents updated**: `data_model.md`, `architecture.md`, `components/06_cache_tile_lifecycle/description.md`, `components/08_fdr_observability/description.md`, `deployment/environment_strategy.md`. + +--- + +### R08: Cache Poisoning + +**Description**: A bad generated tile could be written back and later used as a trusted anchor. + +**Trigger conditions**: Generated tile is promoted despite high parent covariance, stale source, bad sidecar, or inconsistent overlap voting. + +**Affected components**: Cache/tile lifecycle, safety/anchor wrapper, Satellite Service integration. + +**Mitigation strategy**: +1. Require tile-write sigma gates. +2. Store generated tiles as candidates with signed sidecars. +3. Promote only through post-flight Satellite Service validation/voting. + +**Contingency plan**: Quarantine generated tiles and invalidate affected cache regions. + +**Residual risk after mitigation**: Low. + +**Documents updated**: `architecture.md`, `components/06_cache_tile_lifecycle/description.md`, `tests/security-tests.md`. + +--- + +### R09: Dataset Coverage / Licensing + +**Description**: Public datasets may not match target terrain, may lack raw synchronized IMU, or may have non-commercial restrictions. + +**Trigger conditions**: MUN-FRL/ALTO/Kagaru/EPFL slices are unavailable, unrepresentative, or license-incompatible for acceptance. + +**Affected components**: Validation harness, BASALT VIO adapter, anchor verification. + +**Mitigation strategy**: +1. Use public datasets for de-risking only. +2. License-tag datasets before CI jobs. +3. Require representative synchronized target data for final acceptance. + +**Contingency plan**: Collect a target replay dataset before final acceptance. + +**Residual risk after mitigation**: Medium. + +**Documents updated**: `tests/test-data.md`, `deployment/environment_strategy.md`, `deployment/ci_cd_pipeline.md`. + +--- + +### R10: Plane `GPS_INPUT` Integration + +**Description**: ArduPilot Plane EKF and `GPS_INPUT` handling may differ from assumptions, especially around accuracy fields, ignore flags, velocity fields, and spoofing transitions. + +**Trigger conditions**: Plane SITL rejects or mishandles emitted `GPS_INPUT`, or QGC status is insufficient. + +**Affected components**: MAVLink/GCS integration, safety/anchor wrapper, validation harness. + +**Mitigation strategy**: +1. Use pymavlink for exact `GPS_INPUT` field control. +2. Gate release on Plane SITL with production parameters. +3. Validate spoofing/failsafe and QGC status behavior. + +**Contingency plan**: Adjust parameter guidance/output fields before hardware deployment. + +**Residual risk after mitigation**: Medium. + +**Documents updated**: `components/07_mavlink_gcs_integration/description.md`, `tests/environment.md`, `deployment/ci_cd_pipeline.md`. + +## Architecture/Component Changes Applied + +| Risk ID | Document Modified | Change Description | +|---------|-------------------|--------------------| +| R04 | `components/01_camera_ingest_calibration/description.md` | Added explicit `detect_occlusion`, `OcclusionReport`, and pre-VIO bypass behavior | +| R04/R05 | `components/03_safety_anchor_wrapper/description.md` | Added `propagate_imu_only`, `total_occlusion`, monotonic covariance behavior, and no direct cache lifecycle dependency | +| R07 | `data_model.md` | Replaced embedded DB references with PostgreSQL/PostGIS structured metadata and CBOR FDR payload segments | +| R07 | `architecture.md` | Added PostgreSQL/PostGIS ADR and FDR storage decision | +| R05 | `tests/blackbox-tests.md` / `tests/resilience-tests.md` | Made total occlusion and IMU-only blackout behavior explicit | + +## Summary + +**Total risks identified**: 12 +**Critical**: 0 | **High**: 7 | **Medium**: 5 | **Low**: 0 +**Risks mitigated this iteration**: 12 +**Risks requiring user decision**: None immediately. Future decisions are tied to exact camera hardware proof, dataset license approval, and representative data collection timing. diff --git a/_docs/02_document/system-flows.md b/_docs/02_document/system-flows.md new file mode 100644 index 0000000..4b0d67e --- /dev/null +++ b/_docs/02_document/system-flows.md @@ -0,0 +1,322 @@ +# GPS-Denied Onboard Localization — System Flows + +## Flow Inventory + +| # | Flow Name | Trigger | Primary Components | Criticality | +|---|-----------|---------|--------------------|-------------| +| F1 | Pre-flight cache preparation | Operator sync before mission | Satellite Service, cache/tile lifecycle, satellite retrieval | High | +| F2 | Normal frame processing | Navigation frame + FC telemetry | Camera ingest, BASALT VIO adapter, safety/anchor wrapper, MAVLink, FDR | High | +| F3 | Satellite relocalization | Cold start, VO failure, sharp turn, covariance growth, stale anchor | Satellite retrieval, anchor verification, safety/anchor wrapper | High | +| F4 | Visual blackout / spoofing degraded mode | Image-quality failure and GPS health failure | Camera ingest, MAVLink telemetry, safety/anchor wrapper, QGC, FDR | Critical | +| F5 | Generated tile lifecycle | High-confidence pose + usable frame | Camera ingest, safety/anchor wrapper, cache/tile lifecycle, FDR | Medium | +| F6 | Post-flight sync and audit | Landing / operator offload | Cache/tile lifecycle, Satellite Service, FDR | Medium | +| F7 | Validation replay | Test harness invocation | Validation harness, system runtime, public datasets, SITL | High | + +## Flow Dependencies + +| Flow | Depends On | Shares Data With | +|------|------------|------------------| +| F1 | Satellite Service cache export | F2, F3, F5 | +| F2 | F1 for cache availability; FC telemetry | F3, F4, F5, FDR | +| F3 | F1 cache/index; F2 state estimate | F2, F5 | +| F4 | F2 telemetry and quality signals | F2, QGC/FDR | +| F5 | Accepted state/covariance from F2/F3 | F6 | +| F6 | F5 generated tiles and FDR | Satellite Service | +| F7 | Test fixtures and selected execution environment | All flows | + +--- + +## Flow F1: Pre-Flight Cache Preparation + +### Description + +Before flight, the Satellite Service provides an offline cache for the operational area, including COG tiles, manifests, sidecars, VPR chunks, descriptors, and FAISS index files. + +### Preconditions + +- Operational area and sector freshness classification are known. +- Cache imagery meets 0.5 m/px minimum and ideally 0.3 m/px. +- Cache package fits storage budget or has approved split descriptor budget. + +### Sequence Diagram + +```mermaid +sequenceDiagram + participant Operator + participant SatelliteService + participant CacheLifecycle + participant SatelliteRetrieval + + Operator->>SatelliteService: Request mission cache + SatelliteService-->>CacheLifecycle: COG tiles + manifests + sidecars + CacheLifecycle->>CacheLifecycle: Verify signatures, hashes, freshness, resolution + CacheLifecycle->>SatelliteRetrieval: Load VPR chunks + FAISS index + CacheLifecycle-->>Operator: Cache validation report +``` + +### Data Flow + +| Step | From | To | Data | Format | +|------|------|----|------|--------| +| 1 | Satellite Service | Cache lifecycle | Tiles and metadata | COG + PostgreSQL/PostGIS manifest + signed JSON sidecars | +| 2 | Cache lifecycle | Satellite retrieval | Descriptor/index files | FAISS index + descriptor sidecars | +| 3 | Cache lifecycle | Operator/FDR | Validation report | Markdown/CSV/log | + +### Error Scenarios + +| Error | Where | Detection | Recovery | +|-------|-------|-----------|----------| +| Stale tile | Cache validation | Capture date exceeds sector threshold | Reject/down-confidence tile | +| Hash mismatch | Cache validation | Sidecar hash mismatch | Reject tile and report security event | +| Cache too large | Cache load | Storage accounting > budget | Require cache rebuild or approved split budget | + +### Performance Expectations + +| Metric | Target | Notes | +|--------|--------|-------| +| Runtime network calls | 0 | No in-flight provider calls | +| Cache load | Within cold-start budget contribution | Exact threshold set during implementation | + +--- + +## Flow F2: Normal Frame Processing + +### Description + +During normal flight, the system processes each navigation frame and FC telemetry sample. The camera component first checks for total occlusion/blackout. Usable frames go to BASALT VIO; total-occlusion frames bypass VIO and send the wrapper into IMU-only degraded propagation. + +### Preconditions + +- Camera calibration/extrinsics are loaded. +- BASALT and wrapper are initialized. +- FC telemetry stream is healthy. + +### Sequence Diagram + +```mermaid +sequenceDiagram + participant CameraIngest + participant FCTelemetry + participant BasaltAdapter + participant SafetyWrapper + participant MavlinkOutput + participant FDR + + CameraIngest->>CameraIngest: Total occlusion / blackout check + CameraIngest->>BasaltAdapter: Usable frame + timestamp + calibration + CameraIngest-->>SafetyWrapper: Degradation signal if total occlusion + FCTelemetry->>BasaltAdapter: IMU/attitude/altitude + BasaltAdapter-->>SafetyWrapper: Relative VIO state + quality + SafetyWrapper->>SafetyWrapper: Calibrate covariance + source label + SafetyWrapper-->>MavlinkOutput: GPS_INPUT estimate + SafetyWrapper-->>FDR: Estimate + inputs + health +``` + +### Data Flow + +| Step | From | To | Data | Format | +|------|------|----|------|--------| +| 1 | Camera ingest | BASALT adapter or safety wrapper | Frame metadata, image, occlusion status | Frame DTO / DegradationSignal | +| 2 | FC telemetry | BASALT adapter | IMU/attitude/altitude | MAVLink-derived telemetry DTO | +| 3 | BASALT adapter | Safety wrapper | Relative VIO state | VioState DTO | +| 4 | Safety wrapper | MAVLink output | WGS84 estimate | `GPS_INPUT` | +| 5 | Safety wrapper | FDR | Inputs/outputs/audit | FDR segment event | + +### Error Scenarios + +| Error | Where | Detection | Recovery | +|-------|-------|-----------|----------| +| Total occlusion / blackout | Camera ingest | Occlusion status, exposure/texture/decode checks | Bypass BASALT, enter IMU-only `dead_reckoned` propagation | +| Frame unreadable | Camera ingest | Decode/quality failure | Mark visual signal degraded and bypass BASALT for that frame | +| VIO quality low | BASALT adapter | Tracking/completion metrics | Trigger relocalization or dead reckoning | +| Covariance grows | Safety wrapper | Covariance threshold | Degrade fix type/source label | + +### Performance Expectations + +| Metric | Target | Notes | +|--------|--------|-------| +| End-to-end latency | <400 ms p95 | Frame input to emitted estimate | +| Dropped frames | <=10% sustained | Under load | +| Memory | <8 GB shared | Jetson limit | + +--- + +## Flow F3: Satellite Relocalization + +### Description + +When the state becomes uncertain or disconnected, the system retrieves satellite/cache candidates and accepts an anchor only after local verification and safety gates pass. + +### Preconditions + +- Offline VPR chunks and FAISS index are loaded. +- Trigger condition is met: cold start, VO failure, sharp turn, disconnected segment, covariance growth, or stale anchor. + +### Sequence Diagram + +```mermaid +sequenceDiagram + participant SafetyWrapper + participant SatelliteRetrieval + participant AnchorVerification + participant CacheLifecycle + participant FDR + + SafetyWrapper->>SatelliteRetrieval: Relocalization request + SatelliteRetrieval->>CacheLifecycle: Read candidate chunk metadata + SatelliteRetrieval-->>AnchorVerification: Top-K candidates + AnchorVerification->>AnchorVerification: ALIKED/DISK+LightGlue + RANSAC + AnchorVerification-->>SafetyWrapper: Accepted/rejected anchor + SafetyWrapper->>SafetyWrapper: Mahalanobis + freshness + provenance gates + SafetyWrapper-->>FDR: Anchor decision audit +``` + +### Data Flow + +| Step | From | To | Data | Format | +|------|------|----|------|--------| +| 1 | Safety wrapper | Satellite retrieval | Query frame and prior/covariance | Relocalization DTO | +| 2 | Satellite retrieval | Anchor verification | Top-K chunks | Candidate list | +| 3 | Anchor verification | Safety wrapper | MRE, inliers, homography, provenance | AnchorDecision DTO | + +### Error Scenarios + +| Error | Where | Detection | Recovery | +|-------|-------|-----------|----------| +| No good candidate | Retrieval/verification | Low score or failed RANSAC | Continue degraded and request GCS hint after threshold | +| Stale candidate | Cache lifecycle | Capture date gate | Reject/down-confidence | +| Implausible anchor | Safety wrapper | Mahalanobis/impossible velocity gate | Reject and log | + +### Performance Expectations + +| Metric | Target | Notes | +|--------|--------|-------| +| Invocation frequency | Trigger-based only | Not per-frame | +| Cross-domain MRE | <2.5 px for accepted anchors | AC-2.2 | + +--- + +## Flow F4: Visual Blackout / Spoofing Degraded Mode + +### Description + +When visual localization is unavailable due to total occlusion/blackout and GPS is denied/spoofed, the wrapper switches to honest IMU-only propagation from the last trusted state and degrades MAVLink output based on covariance/time thresholds. + +### Preconditions + +- Last trusted state exists. +- FC telemetry continues. + +### Sequence Diagram + +```mermaid +sequenceDiagram + participant CameraIngest + participant FCTelemetry + participant SafetyWrapper + participant MavlinkOutput + participant QGC + participant FDR + + CameraIngest-->>SafetyWrapper: Total occlusion / visual blackout signal + FCTelemetry-->>SafetyWrapper: GPS health/spoofing signal + SafetyWrapper->>SafetyWrapper: IMU-only propagation + monotonic covariance growth + SafetyWrapper->>SafetyWrapper: Switch source_label to dead_reckoned + SafetyWrapper-->>MavlinkOutput: Degraded GPS_INPUT + SafetyWrapper-->>QGC: VISUAL_BLACKOUT_IMU_ONLY / FAILSAFE + SafetyWrapper-->>FDR: Blackout and spoofing audit events +``` + +### Error Scenarios + +| Error | Where | Detection | Recovery | +|-------|-------|-----------|----------| +| Blackout >30 s | Safety wrapper | Timer threshold | Emit no-fix/failsafe | +| Covariance >500 m | Safety wrapper | Covariance threshold | `fix_type=0`, `horiz_accuracy=999.0` | +| Spoofed GPS recovers | Safety wrapper | FC health + visual consistency gate | Re-enable only after required stable interval and visual/satellite consistency | + +### Performance Expectations + +| Metric | Target | Notes | +|--------|--------|-------| +| Mode transition | <=1 processed frame or <=400 ms | AC-3.5 | +| QGC status | 1-2 Hz | Downsampled operator awareness | + +--- + +## Flow F5: Generated Tile Lifecycle + +### Description + +When pose confidence is strong enough, the system orthorectifies navigation imagery into write-new generated tiles and records quality/provenance sidecars. + +### Preconditions + +- Parent pose covariance passes tile-write gate. +- Frame quality supports orthorectification. + +### Data Flow + +| Step | From | To | Data | Format | +|------|------|----|------|--------| +| 1 | Safety wrapper | Cache lifecycle | Pose/covariance + frame metadata | TileGenerationRequest | +| 2 | Cache lifecycle | Local storage | Generated COG + sidecar | COG + signed JSON | +| 3 | Cache lifecycle | FDR | Tile write event | FDR event | + +### Error Scenarios + +| Error | Where | Detection | Recovery | +|-------|-------|-----------|----------| +| Parent covariance too high | Safety wrapper | Sigma gate | Do not write tile | +| Duplicate sector | Cache lifecycle | Spatial deduplication | Keep latest/highest-quality tile | +| Sidecar write failure | Cache lifecycle | I/O error | Log and do not mark tile eligible | + +--- + +## Flow F6: Post-Flight Sync And Audit + +### Description + +After landing, generated tiles and FDR evidence are exported for Satellite Service ingest and incident analysis. + +### Data Flow + +| Step | From | To | Data | Format | +|------|------|----|------|--------| +| 1 | Cache lifecycle | Satellite Service | Generated tile package | COG + sidecar + manifest delta | +| 2 | FDR | Operator/audit tools | Mission replay evidence | Segmented logs + optional Parquet export | + +### Error Scenarios + +| Error | Where | Detection | Recovery | +|-------|-------|-----------|----------| +| Upload unavailable | Post-flight sync | Network/service failure | Retain package for retry | +| Candidate rejected by Service voting | Satellite Service | Ingest rules | Keep as candidate/soft trust, not trusted basemap | + +--- + +## Flow F7: Validation Replay + +### Description + +The validation harness runs deterministic still-image, public dataset, SITL, Jetson, and representative replay scenarios against public interfaces. + +### Preconditions + +- Test data and expected results are pinned. +- Execution mode is selected: Docker/replay and local Jetson hardware. + +### Data Flow + +| Step | From | To | Data | Format | +|------|------|----|------|--------| +| 1 | Validation harness | Runtime | Images/telemetry/cache fixtures | File/stream/MAVLink | +| 2 | Runtime | Validation harness | GPS_INPUT/FDR/status | MAVLink/log files | +| 3 | Validation harness | Reports | Pass/fail metrics | CSV/Markdown | + +### Performance Expectations + +| Metric | Target | Notes | +|--------|--------|-------| +| PR smoke | <=15 min | Still-image/cache/SITL subset | +| Release gate | Hardware-dependent | Jetson and representative replay required | diff --git a/_docs/02_document/tests/blackbox-tests.md b/_docs/02_document/tests/blackbox-tests.md new file mode 100644 index 0000000..f5ab348 --- /dev/null +++ b/_docs/02_document/tests/blackbox-tests.md @@ -0,0 +1,168 @@ +# Blackbox Tests + +## Positive Scenarios + +### FT-P-01: Still-Image Frame Center Geolocation + +**Summary**: Validate that the system estimates WGS84 frame centers for the provided 60-image nadir dataset. + +**Traces to**: AC-1.1, AC-1.2, AC-6.3, AC-8.1 + +**Category**: Position Accuracy + +**Preconditions**: +- Offline satellite cache fixture is available for the sample area. +- Expected results are loaded from `input_data/expected_results/results_report.md`. + +**Input data**: `project_60_still_images`, `expected_frame_centers` + +| Step | Consumer Action | Expected System Response | +|------|-----------------|--------------------------| +| 1 | Submit `AD000001.jpg` through `AD000060.jpg` with height/camera metadata | System emits one WGS84 estimate per processed image | +| 2 | Compare each estimate to the mapped expected coordinate | Per-frame error is reported in meters | + +**Expected outcome**: At least 80% of images are within 50 m and at least 50% are within 20 m. + +**Max execution time**: 15 minutes for the 60-image replay on the local replay environment. + +--- + +### FT-P-02: Position Confidence Output Contract + +**Summary**: Validate that every emitted position estimate includes confidence and source-label fields required by the public contract. + +**Traces to**: AC-1.3, AC-1.4, AC-4.4, AC-4.5 + +**Category**: Position Confidence + +**Preconditions**: +- Same fixture setup as FT-P-01. + +**Input data**: `project_60_still_images`, `expected_frame_centers` + +| Step | Consumer Action | Expected System Response | +|------|-----------------|--------------------------| +| 1 | Submit the 60-image replay | System emits estimates frame-by-frame, not batched | +| 2 | Inspect public output fields | Each estimate contains WGS84 coordinate, 95% covariance semi-major axis, source label, and `last_satellite_anchor_age_ms` | +| 3 | Submit a later correction for a prior frame if available | System emits updated estimate with timestamp and covariance without corrupting newer estimates | + +**Expected outcome**: 100% of emitted estimates include required confidence fields; no `horiz_accuracy` equivalent under-reports the 95% covariance semi-major axis. + +**Max execution time**: 15 minutes. + +--- + +### FT-P-03: BASALT VIO Replay With Public Synchronized Data + +**Summary**: Validate that BASALT + safety/anchor wrapper can process synchronized camera/IMU data and produce trajectory estimates with calibrated confidence. + +**Traces to**: AC-1.3, AC-2.1a, AC-2.2, AC-4.1, AC-4.2 + +**Category**: VO / IMU Propagation + +**Preconditions**: +- Public synchronized dataset slice is pinned during implementation. Strongest candidates: MUN-FRL, ALTO, EPFL fixed-wing, Kagaru; EuRoC/UZH FPV are proxy-only. +- Ground-truth trajectory or frame poses are available. + +**Input data**: `public_nadir_vio_candidates` + +| Step | Consumer Action | Expected System Response | +|------|-----------------|--------------------------| +| 1 | Replay synchronized camera and IMU stream | System emits frame-by-frame `vo_extrapolated` or `satellite_anchored` estimates | +| 2 | Compare output trajectory to dataset ground truth | Error and covariance calibration are reported per segment | +| 3 | Compare against OpenVINS reference replay | BASALT + wrapper does not materially under-report uncertainty relative to error | + +**Expected outcome**: VO registration succeeds for >95% of normal overlapping frames in dataset-supported normal segments; VO homography MRE is <1.0 px where homography validation is applicable. + +**Max execution time**: Dataset-dependent, but replay must report per-frame latency. + +--- + +### FT-P-04: Satellite Retrieval And Anchor Verification + +**Summary**: Validate that relocalization uses global retrieval plus local verification and emits only verified satellite anchors. + +**Traces to**: AC-2.1b, AC-2.2, AC-3.2, AC-3.3, AC-8.6 + +**Category**: Satellite Anchor + +**Preconditions**: +- AerialVL/ALTO/VPAir-style public dataset slice or project satellite-cache fixture is available. +- VPR chunks and descriptors are precomputed. + +**Input data**: Public aerial localization slice, cache fixture + +| Step | Consumer Action | Expected System Response | +|------|-----------------|--------------------------| +| 1 | Trigger cold-start or relocalization query | System searches CPU FAISS top-K chunks | +| 2 | Present top-K candidates to local verification | System runs ALIKED/DISK+LightGlue and RANSAC | +| 3 | Inspect emitted anchor decision | Accepted anchors include source label, MRE, inlier count, covariance, and tile provenance | + +**Expected outcome**: Cross-domain satellite-anchor MRE is <2.5 px for accepted anchors; rejected candidates do not produce `satellite_anchored` estimates. + +**Max execution time**: Must be measured as part of performance tests. + +## Negative Scenarios + +### FT-N-01: Repetitive Or Low-Texture Imagery + +**Summary**: Validate that visually ambiguous images do not produce confident false satellite anchors. + +**Traces to**: AC-1.4, AC-3.1, AC-NEW-4, AC-8.6 + +**Category**: False Position Prevention + +**Input data**: Repetitive agricultural or low-texture frames from project/public data. + +| Step | Consumer Action | Expected System Response | +|------|-----------------|--------------------------| +| 1 | Submit ambiguous frame or sequence | System either emits degraded `vo_extrapolated`/`dead_reckoned` output or rejects low-confidence anchor | +| 2 | Inspect anchor and confidence outputs | No anchor is accepted unless local verification and covariance gates pass | + +**Expected outcome**: 0 confident `satellite_anchored` outputs for candidates that fail local verification, freshness, or Mahalanobis gates. + +**Max execution time**: 15 minutes per fixture. + +--- + +### FT-N-02: GPS Spoofing During Total Visual Blackout + +**Summary**: Validate that spoofed GPS is not promoted during total camera occlusion/visual blackout and that output degrades honestly before unusable frames reach VIO. + +**Traces to**: AC-3.5, AC-5.2, AC-NEW-2, AC-NEW-8 + +**Category**: Spoofing / Blackout + +**Input data**: ArduPilot Plane SITL spoofing trace with camera blackout/total-occlusion frames. + +| Step | Consumer Action | Expected System Response | +|------|-----------------|--------------------------| +| 1 | Start normal replay with trusted visual/satellite anchor | System emits normal estimates | +| 2 | Inject full visual blackout/total occlusion and spoofed `GPS_RAW_INT` | Camera gate sets `usable_for_vio=false`, BASALT is bypassed for occluded frames, and system switches to `dead_reckoned` within <=1 processed frame or <=400 ms | +| 3 | Continue blackout beyond thresholds | IMU-only covariance grows monotonically; system degrades fix type and emits failsafe status at specified covariance/time thresholds | + +**Expected outcome**: Spoofed GPS is ignored; total occlusion never feeds BASALT as a usable VIO frame; `fix_type=0`, `horiz_accuracy=999.0`, and `VISUAL_BLACKOUT_FAILSAFE` are emitted when covariance >500 m or blackout >30 s. + +**Max execution time**: 10 minutes per SITL scenario. + +--- + +### FT-N-03: Invalid Or Stale Satellite Cache + +**Summary**: Validate cache freshness, integrity, and provenance gates. + +**Traces to**: AC-8.2, AC-8.3, AC-NEW-6, AC-NEW-7 + +**Category**: Cache Integrity + +**Input data**: `cache_integrity_fixtures` + +| Step | Consumer Action | Expected System Response | +|------|-----------------|--------------------------| +| 1 | Replay with stale tile manifest | Tile is rejected or down-confidence weighted; no stale tile emits `satellite_anchored` | +| 2 | Replay with hash-mismatched or unsigned manifest | Cache fixture is rejected and security event is logged | +| 3 | Replay generated tile with weak parent-pose covariance | Tile is not promoted beyond allowed trust level | + +**Expected outcome**: 0 invalid/stale/cache-poisoning fixtures produce trusted anchors or trusted basemap tiles. + +**Max execution time**: 15 minutes. diff --git a/_docs/02_document/tests/environment.md b/_docs/02_document/tests/environment.md new file mode 100644 index 0000000..19334fe --- /dev/null +++ b/_docs/02_document/tests/environment.md @@ -0,0 +1,123 @@ +# Test Environment + +## Overview + +**System under test**: Onboard GPS-denied localization service. Public interfaces are navigation-camera frame input, flight-controller telemetry input, offline satellite-cache input, `GPS_INPUT` MAVLink output, QGroundControl status output, and flight-data-recorder output. + +**Consumer app purpose**: A black-box replay harness that feeds image frames, telemetry traces, cache manifests, and fault triggers into the service, then validates emitted coordinates, confidence fields, telemetry, and logs without importing internal modules. + +## Execution Environments + +| Environment | Purpose | Required for | +|-------------|---------|--------------| +| Local replay workstation | Fast still-image and dataset replay validation | Frame-center geolocation, satellite retrieval, stale-tile rejection | +| Jetson Orin Nano Super | Production-like latency, memory, thermal, and TensorRT/ONNX profiling | AC-4.1, AC-4.2, AC-NEW-1, AC-NEW-5 | +| ArduPilot Plane SITL + QGroundControl | MAVLink `GPS_INPUT`, spoofing, failsafe, and GCS status validation | AC-4.3, AC-5.2, AC-NEW-2, AC-NEW-8 | +| Representative flight/replay rig | Final acceptance evidence with synchronized nav camera, FC IMU/attitude/airspeed/altitude, MAVLink logs, and ground truth | Final AC signoff | + +## Docker / Compose Structure + +| Service | Image / Build | Purpose | Ports | +|---------|---------------|---------|-------| +| gps-denied-service | Project build image for JetPack-compatible target or replay-compatible host | System under test | MAVLink UDP/TCP and health/status endpoints TBD | +| replay-consumer | Python replay/test harness | Feeds images, telemetry, cache data, and fault triggers | none | +| satellite-cache-stub | Local COG/manifest/descriptor fixture volume | Provides offline tile cache and signed/unsigned manifests | none | +| ardupilot-plane-sitl | ArduPilot Plane SITL image or local process | Validates `GPS_INPUT`, spoofing/failsafe behavior | MAVLink SITL ports | +| qgc-observer | QGC/tlog-compatible observer or MAVLink log parser | Verifies GCS-visible status output | none | + +## Networks + +| Network | Services | Purpose | +|---------|----------|---------| +| replay-net | gps-denied-service, replay-consumer, satellite-cache-stub | Offline replay and black-box validation | +| sitl-net | gps-denied-service, ardupilot-plane-sitl, qgc-observer | MAVLink integration and failsafe validation | + +## Volumes + +| Volume | Mounted to | Purpose | +|--------|------------|---------| +| input-data | `/data/input` | `_docs/00_problem/input_data/` and public dataset slices | +| expected-results | `/data/expected` | `_docs/00_problem/input_data/expected_results/` | +| satellite-cache | `/cache/satellite` | COG tiles, manifests, descriptor index fixtures | +| fdr-output | `/fdr` | Flight-data-recorder outputs for validation | + +## Consumer Application + +**Tech stack**: Python replay harness with pytest-style assertions and MAVLink log parsing. + +**Entry point**: `run-blackbox-replay` command to be created during implementation; this planning artifact defines required behavior, not code. + +### Communication With System Under Test + +| Interface | Protocol | Endpoint / Topic | Authentication | +|-----------|----------|------------------|----------------| +| Navigation frames | File/stream replay | Ordered image frames with timestamps | Local fixture access | +| FC telemetry | MAVLink replay or generated stream | IMU, attitude, airspeed, altitude, GPS health | Local MAVLink link | +| Satellite cache | Local filesystem contract | COG + manifest + descriptors | Signed manifest validation | +| GPS output | MAVLink | `GPS_INPUT` to ArduPilot Plane | MAVLink source/system ID allowlist | +| Status output | MAVLink/QGC | `STATUSTEXT` / status summary | MAVLink source/system ID allowlist | +| FDR | Filesystem output | Per-flight segmented logs | Local fixture access | + +### What The Consumer Does Not Access + +- No internal estimator modules. +- No direct BASALT/OpenVINS/Kimera APIs. +- No direct mutation of internal state. +- No bypass of public cache, MAVLink, replay, or FDR interfaces. + +## CI/CD Integration + +| Suite | When to run | Gate behavior | Timeout | +|-------|-------------|---------------|---------| +| Still-image geolocation smoke | Every PR after implementation exists | Block merge | <= 15 min | +| Public VIO dataset replay | Nightly and before release | Block release | Dataset-dependent | +| Jetson performance/resource | Before release and after runtime dependency changes | Block release | <= 8 h for endurance/thermal | +| Plane SITL failsafe/spoofing | Every release candidate | Block release | <= 60 min | + +## Reporting + +**Format**: CSV and FDR validation summary. + +**Columns**: Test ID, Test Name, Input Dataset, Execution Time (ms), Result, Error Distance (m), Source Label, Covariance 95% Semi-Major (m), `GPS_INPUT.fix_type`, Error Message. + +**Output path**: `./test-results/blackbox-report.csv` and `./test-results/fdr-validation-summary.md`. + +## Test Execution + +**Decision**: Both Docker/replay and local hardware execution. + +**Hardware dependencies found**: +- Jetson Orin Nano Super with 8 GB shared LPDDR5 and 25 W power mode. +- CUDA/TensorRT/ONNX acceleration for DINOv2 and local-matcher profiling. +- Camera ingestion paths over USB, MIPI-CSI, or GigE. +- ArduPilot Plane SITL and MAVLink `GPS_INPUT` behavior. +- Thermal, power, FDR, and storage limits that require target-like execution. + +### Docker / Replay Mode + +Use Docker or local host replay for deterministic, reproducible tests that do not require physical Jetson hardware: + +- Still-image frame-center geolocation. +- Satellite-cache freshness and integrity fixtures. +- FAISS descriptor/index behavior. +- Public dataset replay where GPU/hardware timing is not the assertion. +- Plane SITL tests where SITL and MAVLink behavior are the target. + +Docker/replay mode is suitable for PR checks and nightly validation, but it does not prove Jetson latency, memory, thermal, or camera-driver behavior. + +### Local Hardware Mode + +Use local Jetson hardware for release gates: + +- BASALT + wrapper latency and memory profiling. +- DINOv2/ONNX/TensorRT descriptor-fidelity and runtime profiling. +- ALIKED/DISK + LightGlue runtime profiling. +- Cold-start time to first valid `GPS_INPUT`. +- 8-hour thermal and FDR endurance tests. +- Camera interface validation once the exact module interface is selected. + +### Gate Policy + +- PR gate: Docker/replay smoke and deterministic fixture tests. +- Nightly gate: Docker/replay public dataset slices and SITL scenarios. +- Release gate: local Jetson hardware, Plane SITL, thermal/resource tests, and representative replay data. diff --git a/_docs/02_document/tests/performance-tests.md b/_docs/02_document/tests/performance-tests.md new file mode 100644 index 0000000..071ee90 --- /dev/null +++ b/_docs/02_document/tests/performance-tests.md @@ -0,0 +1,94 @@ +# Performance Tests + +### NFT-PERF-01: Per-Frame Latency On Project Still Images + +**Summary**: Validate end-to-end latency for processing project nadir frames through geolocation output. + +**Traces to**: AC-4.1, AC-4.4 + +**Metric**: Capture-to-output latency p50/p95/p99 and dropped-frame rate. + +**Preconditions**: +- Jetson Orin Nano Super or equivalent production target is running in the intended power mode. +- `project_60_still_images` fixture is available. + +| Step | Consumer Action | Measurement | +|------|-----------------|-------------| +| 1 | Replay images at target 3 fps or faster stress rate | Measure latency from input timestamp to emitted estimate | +| 2 | Record all frame drops | Measure dropped-frame percentage | + +**Pass criteria**: p95 latency <400 ms; dropped frames <=10% under sustained load; no batching delay. + +**Duration**: Minimum 20 minutes or full fixture loop repeated enough times to reach stable measurements. + +--- + +### NFT-PERF-02: BASALT + Wrapper Replay Latency + +**Summary**: Validate relative VIO hot-path latency using synchronized public or representative camera/IMU data. + +**Traces to**: AC-2.1a, AC-4.1, AC-4.2 + +**Metric**: Per-frame VIO latency, completion rate, and memory usage. + +**Preconditions**: +- MUN-FRL/ALTO/EPFL/Kagaru or representative synchronized dataset slice is pinned. +- OpenVINS reference replay is available for comparison. + +| Step | Consumer Action | Measurement | +|------|-----------------|-------------| +| 1 | Replay synchronized camera/IMU stream through BASALT + wrapper | Measure per-frame processing time | +| 2 | Compare emitted trajectory against ground truth | Measure completion rate and error distribution | +| 3 | Monitor memory | Track CPU/GPU shared memory peak | + +**Pass criteria**: Normal-frame VO registration >95%; p95 processing latency <400 ms for the hot path; memory <8 GB shared. + +**Duration**: Dataset-dependent; at least one normal segment and one challenging segment. + +--- + +### NFT-PERF-03: Relocalization Trigger Path Latency + +**Summary**: Validate the heavy DINOv2-VLAD + FAISS + ALIKED/LightGlue path under bounded top-K settings. + +**Traces to**: AC-3.2, AC-3.3, AC-4.1, AC-8.6 + +**Metric**: Trigger-to-anchor latency, top-K query time, local verification time, accepted/rejected anchor counts. + +**Preconditions**: +- Precomputed descriptor index is loaded. +- Dynamic K settings are configured: K=5 stable, K=20 active-conflict, K=50 fallback. + +| Step | Consumer Action | Measurement | +|------|-----------------|-------------| +| 1 | Trigger relocalization from cold start or sharp turn | Measure DINOv2 descriptor time and FAISS query time | +| 2 | Verify top-K candidates | Measure ALIKED/LightGlue + RANSAC latency | +| 3 | Emit accepted/rejected decision | Measure total trigger-to-decision latency | + +**Pass criteria**: Heavy path is conditional, never blocks steady-state frame output; accepted anchor carries MRE <2.5 px and valid covariance. + +**Duration**: 100 relocalization trials across stable and active-conflict sector fixtures. + +--- + +### NFT-PERF-04: Cold Boot Time To First Fix + +**Summary**: Validate companion boot to first valid `GPS_INPUT`. + +**Traces to**: AC-NEW-1 + +**Metric**: Time from service start/boot marker to first valid `GPS_INPUT`. + +**Preconditions**: +- Engines/indexes are built before the run. +- Cache/index is available locally. +- FC state handoff is simulated or provided. + +| Step | Consumer Action | Measurement | +|------|-----------------|-------------| +| 1 | Start service from cold boot condition | Measure initialization stages | +| 2 | Wait for first valid output | Measure first valid `GPS_INPUT` timestamp | + +**Pass criteria**: 95th percentile <30 s over 50 runs. + +**Duration**: 50 cold-start trials. diff --git a/_docs/02_document/tests/resilience-tests.md b/_docs/02_document/tests/resilience-tests.md new file mode 100644 index 0000000..b0ef57f --- /dev/null +++ b/_docs/02_document/tests/resilience-tests.md @@ -0,0 +1,85 @@ +# Resilience Tests + +### NFT-RES-01: Total Visual Blackout With GPS Spoofing + +**Summary**: Validate degraded-mode behavior when the camera feed is totally occluded/blacked out and real GPS is spoofed or denied. + +**Traces to**: AC-3.5, AC-5.2, AC-NEW-8 + +**Preconditions**: +- Plane SITL or replay trace is emitting normal telemetry. +- System has a recent trusted visual/satellite anchor. + +**Fault injection**: +- Full camera blackout/total occlusion for 5 s, 15 s, and 35 s while spoofed GPS is present. + +| Step | Action | Expected Behavior | +|------|--------|-------------------| +| 1 | Inject total occlusion/blackout and spoofed GPS | Camera gate reports `usable_for_vio=false`, BASALT is bypassed, and system switches to `dead_reckoned` within <=1 processed frame or <=400 ms | +| 2 | Continue blackout | IMU-only covariance grows monotonically and spoofed GPS is ignored | +| 3 | Exceed 30 s or covariance >500 m | System emits no-fix/failsafe fields and QGC `VISUAL_BLACKOUT_FAILSAFE` | + +**Pass criteria**: All pre-VIO occlusion gate, timing, covariance, `fix_type`, `horiz_accuracy`, and status thresholds match AC-NEW-8. + +--- + +### NFT-RES-02: Sharp Turn And Disconnected Segment Relocalization + +**Summary**: Validate recovery when frame-to-frame overlap drops below the VO threshold. + +**Traces to**: AC-3.2, AC-3.3, AC-3.4, AC-8.6 + +**Preconditions**: +- Public or representative replay contains sharp-turn/disconnected segment cases, or equivalent synthetic sequence is generated from mapped imagery. + +**Fault injection**: +- Sequence transition with <5% overlap, heading change <70°, and drift <200 m. + +| Step | Action | Expected Behavior | +|------|--------|-------------------| +| 1 | Replay normal segment | BASALT + wrapper emits normal `vo_extrapolated` estimates | +| 2 | Inject sharp-turn/disconnected transition | VO failure is expected; system triggers VPR relocalization | +| 3 | Continue next segment | System connects segment through verified satellite anchor or reports degraded status | + +**Pass criteria**: Relocalization request is issued when no position is available for >=3 consecutive frames and >=2 s; verified anchor reconnects the segment or output remains degraded with growing covariance. + +--- + +### NFT-RES-03: Companion Computer Restart Mid-Flight + +**Summary**: Validate reboot recovery from flight-controller state and preloaded cache. + +**Traces to**: AC-5.3, AC-NEW-1 + +**Preconditions**: +- Replay/SITL mission is in progress. +- FDR has current segment logs. + +**Fault injection**: +- Kill and restart the GPS-denied service during a GPS-denied segment. + +| Step | Action | Expected Behavior | +|------|--------|-------------------| +| 1 | Kill service | FC continues on last known/IMU-extrapolated state | +| 2 | Restart service | Service reloads cache/index and uses FC state handoff | +| 3 | Observe first valid output | First valid `GPS_INPUT` emitted within <30 s | + +**Pass criteria**: No raw frames are required for recovery; first valid fix <30 s p95; failure is logged in FDR. + +--- + +### NFT-RES-04: Tile Cache Freshness Degradation + +**Summary**: Validate graceful behavior when the only available tile candidates are stale. + +**Traces to**: AC-8.2, AC-NEW-6 + +**Fault injection**: +- Mark cache tiles older than 6 months for active-conflict sector and older than 12 months for stable sector. + +| Step | Action | Expected Behavior | +|------|--------|-------------------| +| 1 | Replay frame requiring satellite anchor | Stale tiles are rejected or down-confidence weighted | +| 2 | Inspect emitted estimate | No stale tile produces `satellite_anchored` label past hard rejection threshold | + +**Pass criteria**: Freshness decay and hard rejection match AC-NEW-6. diff --git a/_docs/02_document/tests/resource-limit-tests.md b/_docs/02_document/tests/resource-limit-tests.md new file mode 100644 index 0000000..c160b86 --- /dev/null +++ b/_docs/02_document/tests/resource-limit-tests.md @@ -0,0 +1,85 @@ +# Resource Limit Tests + +### NFT-RES-LIM-01: Jetson Memory Budget + +**Summary**: Validate that runtime memory stays below the 8 GB shared LPDDR5 limit. + +**Traces to**: AC-4.2, Restrictions Onboard Hardware + +**Preconditions**: +- Jetson Orin Nano Super in production power/thermal mode. +- BASALT + wrapper, cache index, FAISS CPU index, and FDR enabled. + +**Monitoring**: +- CPU/GPU shared memory, process RSS, CUDA allocations, FAISS index memory. + +**Duration**: Minimum 60 minutes steady-state replay plus relocalization triggers. + +**Pass criteria**: Peak memory <8 GB shared; no OOM kill; no silent descriptor/index eviction. + +--- + +### NFT-RES-LIM-02: Thermal And Power Envelope + +**Summary**: Validate sustained 25 W operation without thermal throttling across the environmental envelope. + +**Traces to**: AC-NEW-5 + +**Preconditions**: +- Jetson cooling solution installed. +- Hot-soak chamber or production thermal test setup at +50 °C. + +**Monitoring**: +- Power mode, temperature sensors, throttle flags, CPU/GPU clocks, per-frame latency. + +**Duration**: 8 hours at sustained representative workload. + +**Pass criteria**: No thermal throttle event; p95 latency remains <400 ms; QGC receives thermal warning if any threshold is approached. + +--- + +### NFT-RES-LIM-03: Satellite Cache Storage Budget + +**Summary**: Validate persistent satellite cache footprint for up to 400 km² operational area. + +**Traces to**: AC-8.3, Restrictions Satellite Imagery + +**Monitoring**: +- Cache imagery, overviews, manifests, sidecars, FAISS descriptors/indexes. + +**Duration**: Full cache build/load test. + +**Pass criteria**: Persistent cache is <=10 GB unless the implementation explicitly defines and gets approval for a separate descriptor/index budget. + +--- + +### NFT-RES-LIM-04: Flight Data Recorder Rollover + +**Summary**: Validate FDR storage cap and rollover behavior under an 8-hour synthetic mission. + +**Traces to**: AC-NEW-3, AC-8.5 + +**Preconditions**: +- Synthetic 8-hour load with 3 fps navigation frames, full-rate IMU, emitted `GPS_INPUT`, health telemetry, tile writes, and failure thumbnails. + +**Monitoring**: +- FDR segment sizes, rollover events, retained payload classes. + +**Duration**: 8 hours. + +**Pass criteria**: FDR remains <=64 GB per flight; rollover is logged; no raw nav/AI frames are retained; no payload class is silently dropped. + +--- + +### NFT-RES-LIM-05: Cold Start Resource Spike + +**Summary**: Validate that CUDA/TensorRT/ONNX/FAISS initialization does not violate boot or memory budgets. + +**Traces to**: AC-NEW-1, AC-4.2 + +**Monitoring**: +- Initialization time, peak memory, engine/index load time. + +**Duration**: 50 cold-start trials. + +**Pass criteria**: First valid `GPS_INPUT` <30 s p95; peak memory <8 GB; no first-run engine build occurs at runtime. diff --git a/_docs/02_document/tests/security-tests.md b/_docs/02_document/tests/security-tests.md new file mode 100644 index 0000000..f901ef8 --- /dev/null +++ b/_docs/02_document/tests/security-tests.md @@ -0,0 +1,62 @@ +# Security Tests + +### NFT-SEC-01: Signed Cache Manifest Enforcement + +**Summary**: Validate that unsigned or tampered cache manifests cannot produce trusted anchors. + +**Traces to**: AC-8.2, AC-8.3, AC-NEW-4, AC-NEW-7 + +| Step | Consumer Action | Expected Response | +|------|-----------------|-------------------| +| 1 | Provide valid signed manifest | System accepts cache fixture if all freshness and resolution checks pass | +| 2 | Provide unsigned manifest | System rejects cache fixture and logs security event | +| 3 | Provide hash-mismatched tile sidecar | System rejects affected tile and emits no trusted anchor from it | + +**Pass criteria**: 0 unsigned or hash-mismatched fixtures produce `satellite_anchored` output or trusted generated tile promotion. + +--- + +### NFT-SEC-02: Cache Poisoning Write Gate + +**Summary**: Validate that generated onboard tiles are not written or promoted when parent-pose covariance is too weak. + +**Traces to**: AC-8.4, AC-NEW-7 + +| Step | Consumer Action | Expected Response | +|------|-----------------|-------------------| +| 1 | Replay generated tile candidate with parent sigma <=3 m | Tile may be written as candidate with full quality metadata | +| 2 | Replay candidate with parent sigma in (3 m, 5 m] | Tile is marked lower trust per sidecar policy | +| 3 | Replay candidate with parent sigma >5 m | Tile is not eligible for write/promotion | + +**Pass criteria**: Tile trust level and write eligibility match AC-NEW-7; no over-threshold tile becomes trusted basemap. + +--- + +### NFT-SEC-03: MAVLink Source And Spoofing Rejection + +**Summary**: Validate that spoofed real-GPS measurements and unauthorized MAVLink sources do not override trusted estimator state. + +**Traces to**: AC-3.5, AC-4.3, AC-NEW-2, AC-NEW-8 + +| Step | Consumer Action | Expected Response | +|------|-----------------|-------------------| +| 1 | Inject spoofed `GPS_RAW_INT` during normal visual operation | Estimator rejects inconsistent GPS based on FC health and visual/satellite consistency | +| 2 | Inject spoofed GPS during visual blackout | Spoofed GPS remains excluded until health and visual consistency gates pass | +| 3 | Inject MAVLink messages from unauthorized source ID | Message is ignored and security/status event is logged | + +**Pass criteria**: No unauthorized or spoofed input causes a confident position estimate; promotion/demotion status is visible to QGC and FDR. + +--- + +### NFT-SEC-04: No In-Flight Satellite Provider Access + +**Summary**: Validate that the runtime system does not call commercial or Suite satellite services during flight. + +**Traces to**: AC-8.1, AC-8.3, Restrictions Satellite Imagery + +| Step | Consumer Action | Expected Response | +|------|-----------------|-------------------| +| 1 | Run replay with network blocked | System continues using local cache | +| 2 | Run replay requiring missing tile | System reports degraded/relocalization-needed status, not an external fetch | + +**Pass criteria**: 0 outbound satellite-provider or Suite Service calls during runtime; missing cache data produces controlled degraded behavior. diff --git a/_docs/02_document/tests/test-data.md b/_docs/02_document/tests/test-data.md new file mode 100644 index 0000000..35e5ae9 --- /dev/null +++ b/_docs/02_document/tests/test-data.md @@ -0,0 +1,95 @@ +# Test Data Management + +## Seed Data Sets + +| Data Set | Description | Used by Tests | How Loaded | Cleanup | +|----------|-------------|---------------|------------|---------| +| `project_60_still_images` | 60 nadir images with WGS84 frame-center coordinates from `coordinates.csv`; height 400 m | FT-P-01, FT-P-02, FT-N-01, NFT-PERF-01 | Mounted from `_docs/00_problem/input_data/` | Read-only | +| `project_gmaps_reference_subset` | Google Maps reference images available for the first sample frames | FT-P-02, FT-N-01 | Mounted from `_docs/00_problem/input_data/` | Read-only | +| `expected_frame_centers` | Expected lat/lon and thresholds derived from `coordinates.csv` | FT-P-01, FT-P-02 | `_docs/00_problem/input_data/expected_results/results_report.md` | Read-only | +| `public_nadir_vio_candidates` | MUN-FRL, ALTO, EPFL fixed-wing, Kagaru, AerialVL/VPAir slices, EuRoC/UZH FPV proxy slices | FT-P-03, FT-P-04, NFT-PERF-02, NFT-RES-02 | Downloaded or mounted by replay harness; exact files pinned during implementation | Reset fixture volume | +| `sitl_spoofing_scenarios` | Generated ArduPilot Plane SITL GPS loss/spoofing traces | FT-N-02, NFT-RES-01, NFT-SEC-03 | Generated by test harness | Discard generated logs after report | +| `cache_integrity_fixtures` | Fresh, stale, unsigned, hash-mismatched, and low-resolution cache manifests | FT-N-03, NFT-SEC-01, NFT-SEC-02 | Mounted fixture volume | Read-only | + +## Public Dataset Coverage Plan + +| Public Data Source | Fit For This Project | Limitations | Planned Use | +|--------------------|----------------------|-------------|-------------| +| MUN-FRL | Strong nadir camera + IMU + GNSS/ground truth candidate | Helicopter/hexacopter, not fixed-wing | BASALT/OpenVINS/Kimera replay and covariance calibration | +| ALTO | Strong nadir aerial imagery with GPS/INS, altimeter, orthophotos | Helicopter/airborne collection, access/details must be pinned | VPR, satellite alignment, VO/geolocalization replay | +| EPFL fixed-wing micro UAV | Strong fixed-wing relevance with camera/navigation sensors | Availability and exact raw IMU packaging must be verified | Fixed-wing path realism and photogrammetry-style validation | +| Kagaru airborne vision | Fixed-wing/farmland relevance, downward stereo, INS/GPS | Older dataset; exact sensor compatibility must be verified | Agricultural terrain and fixed-wing motion checks | +| AerialVL | Strong UAV-to-satellite localization and VPR benchmark | IMU availability is less clear than image/GNSS/reference-map data | Satellite retrieval, anchor verification, visual localization | +| VPAir | Strong aircraft nadir VPR/localization with GPS-derived poses | Academic-use restriction; raw IMU not confirmed | VPR and cross-view localization only if license allows | +| EuRoC MAV | Excellent synchronized camera/IMU/ground-truth VIO benchmark | Not fixed-wing nadir, indoor MAV | BASALT/OpenVINS/Kimera baseline sanity tests | +| UZH FPV | Synchronized camera/IMU/ground-truth high-dynamics benchmark | Not nadir fixed-wing; non-commercial license | Stress VIO robustness only if license allows | + +## Data Isolation Strategy + +Every replay test uses read-only fixture mounts and writes results to a fresh `test-results//` directory. The system under test may write FDR and generated COG tiles only to run-scoped temporary volumes. + +## Input Data Mapping + +| Input Data File | Source Location | Description | Covers Scenarios | +|-----------------|----------------|-------------|------------------| +| `AD000001.jpg` ... `AD000060.jpg` | `_docs/00_problem/input_data/` | Project still-image set with expected WGS84 centers | FT-P-01, FT-P-02, NFT-PERF-01 | +| `coordinates.csv` | `_docs/00_problem/input_data/coordinates.csv` | Machine-readable expected frame centers | FT-P-01, FT-P-02 | +| `data_parameters.md` | `_docs/00_problem/input_data/data_parameters.md` | Height 400 m and camera model | FT-P-01, NFT-PERF-01 | +| `AD000001_gmaps.png`, `AD000002_gmaps.png` | `_docs/00_problem/input_data/` | Reference map screenshots for sample sanity checks | FT-P-02 | +| Public dataset slices | External fixture paths pinned during implementation | Synchronized camera/IMU/GNSS/ground truth where available | FT-P-03, FT-P-04, NFT-PERF-02, NFT-RES-02 | + +## Expected Results Mapping + +| Test Scenario ID | Input Data | Expected Result | Comparison Method | Tolerance | Expected Result Source | +|------------------|------------|-----------------|-------------------|-----------|------------------------| +| FT-P-01 | `AD000001.jpg` ... `AD000060.jpg` | Output WGS84 frame center per mapped row; >=80% within 50 m, >=50% within 20 m | Haversine distance threshold + aggregate pass rate | 50 m primary, 20 m stretch | `input_data/expected_results/results_report.md` | +| FT-P-02 | Same 60 images + map references where present | Output includes source label, covariance semi-major axis, and anchor age for every emitted estimate | Required-field validation + geolocation threshold | Required fields present; geolocation thresholds as above | `input_data/expected_results/results_report.md` | +| FT-P-03 | Public synchronized VIO dataset slice | BASALT + wrapper emits trajectory with calibrated covariance and no optimistic under-reporting | Dataset ground-truth trajectory comparison | Dataset-specific threshold pinned at implementation; must support AC-1/AC-2 signoff only after representative data | Public dataset ground truth | +| FT-P-04 | AerialVL/ALTO/VPAir-style aerial localization slice | Satellite retrieval returns candidate chunks and local verification produces accepted/rejected anchors | Georeference error + MRE + source-label checks | AC-1.1/1.2 and AC-2.2 thresholds where dataset supports them | Public dataset ground truth/reference map | +| FT-N-01 | Low-texture/repetitive frames from sample or public data | System emits degraded confidence or rejects anchor rather than confident false fix | Source label and covariance threshold | No `satellite_anchored` label unless gates pass | Fixture-specific | +| FT-N-02 | Plane SITL GPS spoof/loss trace | Spoofed GPS rejected; system promotes own estimate within <3 s when trigger conditions are met | Event timing and MAVLink field checks | <3 s promotion; blackout thresholds from AC-NEW-8 | Generated SITL trace | +| FT-N-03 | Stale/unsigned/hash-mismatched cache fixtures | Anchors rejected or downgraded; stale tile never emits `satellite_anchored` | Manifest validation + emitted label check | 0 accepted stale/invalid anchors | Cache fixture manifest | + +## External Dependency Mocks + +| External Service | Mock/Stub | How Provided | Behavior | +|------------------|-----------|--------------|----------| +| Azaion Suite Satellite Service | Offline cache stub | Local COG/manifest/descriptor fixture | Provides only preloaded tiles; no in-flight network fetch | +| Flight controller | ArduPilot Plane SITL and MAVLink replay | SITL container/process and recorded/generated tlogs | Emits IMU, attitude, altitude, airspeed, GPS health/spoofing events | +| QGroundControl | MAVLink observer/log parser | Test-side parser | Verifies downsampled status and `STATUSTEXT` events | + +## Data Validation Rules + +| Data Type | Validation | Invalid Examples | Expected System Behavior | +|-----------|------------|------------------|--------------------------| +| Image frame | Existing file, readable image, expected timestamp/order metadata if sequence replay | Missing image, corrupt image, unsupported resolution | Mark estimate unavailable/degraded, log error, continue if possible | +| Expected coordinate | Valid WGS84 latitude/longitude | Out-of-range lat/lon, missing row | Reject test fixture before replay | +| IMU trace | Monotonic timestamps, angular rate/accel fields, calibrated units | Non-monotonic timestamps, missing samples | Reject fixture or enter degraded mode depending scenario | +| Cache tile manifest | CRS, m/px, capture date, source, hashes, signature/provenance | Stale, unsigned, hash mismatch, low resolution | Reject or down-confidence per AC-8.2 and AC-NEW-6 | +| MAVLink output | Valid `GPS_INPUT` fields and fix type/accuracy semantics | Missing `horiz_accuracy`, impossible fix type | Fail test; output contract violated | + +## Phase 3 Validation Gate Result + +| Test Scenario ID | Shape | Required Input Data | Required Expected Result | Input Provided? | Expected Result Provided? | Validation Decision | +|------------------|-------|---------------------|--------------------------|-----------------|---------------------------|---------------------| +| FT-P-01 | Input/output | 60 project images + `coordinates.csv` | WGS84 center per image with 50 m / 20 m thresholds | Yes | Yes | Keep | +| FT-P-02 | Input/output | 60 project images + output schema expectations | Required confidence/source-label fields and thresholds | Yes | Yes | Keep | +| FT-P-03 | Input/output | Public or representative synchronized camera/IMU dataset | Dataset ground truth and calibrated covariance checks | Accepted as required external fixture | Accepted as dataset ground truth | Keep with acquisition task | +| FT-P-04 | Input/output | Public aerial localization or project cache fixture | Georeference, MRE, and source-label checks | Accepted as required external fixture | Accepted as dataset/reference-map ground truth | Keep with acquisition task | +| FT-N-01 | Behavioral/input-output | Ambiguous low-texture/repetitive frames | 0 confident false anchors | Accepted as project/public fixture | Yes | Keep | +| FT-N-02 | Behavioral | Generated Plane SITL spoof/blackout trace | Timing and MAVLink field thresholds from AC-NEW-8 | Generated by test harness | Yes | Keep | +| FT-N-03 | Behavioral/input-output | Cache integrity fixtures | 0 trusted anchors from stale/invalid tiles | Generated fixture | Yes | Keep | +| NFT-PERF-01 | Input/output | 60 project images | p95 latency and drop-rate thresholds | Yes | Yes | Keep | +| NFT-PERF-02 | Input/output | Public/representative synchronized camera/IMU dataset | VO registration, latency, memory thresholds | Accepted as required external fixture | Yes | Keep with acquisition task | +| NFT-PERF-03 | Behavioral/input-output | Precomputed descriptor/cache fixture | Trigger-path latency and MRE thresholds | Generated fixture | Yes | Keep | +| NFT-PERF-04 | Behavioral | Cold-start harness and cache fixture | <30 s p95 over 50 runs | Generated by test harness | Yes | Keep | +| NFT-RES-* | Behavioral | Fault triggers and generated traces | AC-defined timing/status thresholds | Generated by test harness | Yes | Keep | +| NFT-SEC-* | Behavioral/input-output | Cache/MAVLink/network fixtures | Rejection/no-fetch/no-promote thresholds | Generated fixture | Yes | Keep | +| NFT-RES-LIM-* | Behavioral | Jetson/cache/FDR monitoring environment | Numeric resource thresholds | Environment-dependent | Yes | Keep | + +**Coverage after validation**: 49/49 AC and restriction groups remain covered. No tests were removed. + +**Acquisition tasks required downstream**: +- Pin and download at least one strong synchronized nadir camera + IMU + ground-truth dataset, preferably MUN-FRL or ALTO, with EPFL fixed-wing and Kagaru as fixed-wing/farmland candidates. +- Pin license-compatible VPR/localization datasets for satellite anchor tests; VPAir and UZH FPV have non-commercial restrictions and must not be used for commercial acceptance unless license terms allow it. +- Create generated fixtures for Plane SITL spoofing, stale cache manifests, signed/unsigned manifests, FDR load, and thermal/resource monitoring during implementation. diff --git a/_docs/02_document/tests/traceability-matrix.md b/_docs/02_document/tests/traceability-matrix.md new file mode 100644 index 0000000..553da9a --- /dev/null +++ b/_docs/02_document/tests/traceability-matrix.md @@ -0,0 +1,80 @@ +# Traceability Matrix + +## Acceptance Criteria Coverage + +| AC ID | Acceptance Criterion Summary | Test IDs | Coverage | +|-------|------------------------------|----------|----------| +| AC-1.1 | >=80% frame centers within 50 m | FT-P-01, FT-P-04 | Covered | +| AC-1.2 | >=50% frame centers within 20 m | FT-P-01, FT-P-04 | Covered | +| AC-1.3 | Drift and anchor age reporting | FT-P-02, FT-P-03, NFT-RES-02 | Covered | +| AC-1.4 | Quantitative confidence and source label | FT-P-02, FT-N-01, FT-P-03 | Covered | +| AC-2.1a | VO registration >95% on normal segments | FT-P-03, NFT-PERF-02 | Covered | +| AC-2.1b | Satellite-anchor registration measured separately | FT-P-04 | Covered | +| AC-2.2 | MRE <1 px VO and <2.5 px satellite anchor | FT-P-03, FT-P-04 | Covered | +| AC-3.1 | Handles up to 350 m outliers | FT-N-01, NFT-RES-02 | Covered | +| AC-3.2 | Sharp turn relocalization | FT-P-04, NFT-RES-02, NFT-PERF-03 | Covered | +| AC-3.3 | >=3 disconnected segments via retrieval/relocalization | NFT-RES-02, FT-P-04 | Covered | +| AC-3.4 | Relocalization request after loss threshold | NFT-RES-02 | Covered | +| AC-3.5 | Total visual blackout/occlusion + GPS spoofing degraded mode | FT-N-02, NFT-RES-01, NFT-SEC-03 | Covered | +| AC-4.1 | End-to-end latency <400 ms p95 | NFT-PERF-01, NFT-PERF-02, NFT-PERF-03 | Covered | +| AC-4.2 | Memory below 8 GB shared | NFT-RES-LIM-01, NFT-RES-LIM-05 | Covered | +| AC-4.3 | MAVLink `GPS_INPUT` output for ArduPilot | FT-N-02, NFT-SEC-03 | Covered | +| AC-4.4 | Frame-by-frame streaming | FT-P-02, NFT-PERF-01 | Covered | +| AC-4.5 | Previous estimate corrections | FT-P-02 | Covered | +| AC-5.1 | Initialize from last trusted FC state | NFT-RES-03, NFT-PERF-04 | Covered | +| AC-5.2 | >3 s no-estimate fallback behavior | FT-N-02, NFT-RES-01 | Covered | +| AC-5.3 | Re-initialize after companion reboot | NFT-RES-03 | Covered | +| AC-6.1 | QGC status at 1-2 Hz | FT-N-02, NFT-SEC-03 | Covered | +| AC-6.2 | Ground station command ingress | FT-P-04, NFT-RES-02 | Covered | +| AC-6.3 | WGS84 output | FT-P-01, FT-P-02 | Covered | +| AC-7.1 | Object localization accuracy consistent with frame center in level flight | FT-P-01 | Covered at system boundary; detailed AI-camera tests deferred to component specs | +| AC-7.2 | Object coordinates from UAV position, gimbal angle, zoom, altitude | FT-P-01 | Covered at system boundary; detailed AI-camera tests deferred to component specs | +| AC-8.1 | Cache imagery 0.5 m/px minimum, 0.3 m/px ideal | FT-P-04, NFT-SEC-04 | Covered | +| AC-8.2 | Tile freshness thresholds | FT-N-03, NFT-RES-04, NFT-SEC-01 | Covered | +| AC-8.3 | Preloaded/preprocessed offline cache | NFT-SEC-04, NFT-RES-LIM-03 | Covered | +| AC-8.4 | Mid-flight tile generation and write-back | NFT-SEC-02, NFT-RES-LIM-04 | Covered | +| AC-8.5 | No raw frame retention | NFT-RES-LIM-04 | Covered | +| AC-8.6 | VPR retrieval chunks, multi-scale, dynamic K | FT-P-04, NFT-PERF-03 | Covered | +| AC-NEW-1 | Cold start first fix <30 s | NFT-PERF-04, NFT-RES-LIM-05, NFT-RES-03 | Covered | +| AC-NEW-2 | Spoofing promotion <3 s | FT-N-02, NFT-SEC-03 | Covered | +| AC-NEW-3 | FDR <=64 GB and payload retention | NFT-RES-LIM-04 | Covered | +| AC-NEW-4 | False-position safety budget | FT-N-01, NFT-SEC-01 | Covered | +| AC-NEW-5 | Thermal envelope and no throttle | NFT-RES-LIM-02 | Covered | +| AC-NEW-6 | Imagery freshness enforcement | FT-N-03, NFT-RES-04 | Covered | +| AC-NEW-7 | Cache-poisoning safety budget | FT-N-03, NFT-SEC-02 | Covered | +| AC-NEW-8 | Pre-VIO total occlusion gate, IMU-only blackout propagation, and spoofing degraded-mode budget | FT-N-02, NFT-RES-01 | Covered | + +## Restrictions Coverage + +| Restriction ID | Restriction Summary | Test IDs | Coverage | +|----------------|---------------------|----------|----------| +| R-UAV-01 | Fixed-wing UAV mission profile and 8-hour operations | NFT-RES-LIM-02, NFT-RES-LIM-04 | Covered | +| R-CAM-01 | Fixed downward navigation camera | FT-P-01, FT-P-03 | Covered | +| R-CAM-02 | ADTi 20MP 20L V1 and calibration assumptions | FT-P-01, NFT-PERF-01 | Covered | +| R-SAT-01 | Offline-only Satellite Service cache, no in-flight provider fetch | NFT-SEC-04 | Covered | +| R-SAT-02 | Cache resolution/freshness/metadata conventions | FT-N-03, NFT-RES-LIM-03 | Covered | +| R-HW-01 | Jetson Orin Nano Super 8 GB / 25 W | NFT-RES-LIM-01, NFT-RES-LIM-02 | Covered | +| R-SENSOR-01 | FC IMU available; sample data lacks synchronized IMU | FT-P-03, NFT-PERF-02 | Covered through public/representative dataset plan | +| R-MAV-01 | MAVLink, ArduPilot only, GPS_INPUT via pymavlink | FT-N-02, NFT-SEC-03 | Covered | +| R-GCS-01 | QGroundControl supported GCS | FT-N-02, NFT-SEC-03 | Covered | +| R-SAFETY-01 | False-position, cold-start, spoofing, and failsafe constraints | FT-N-01, FT-N-02, NFT-PERF-04, NFT-RES-01 | Covered | + +## Coverage Summary + +| Category | Total Items | Covered | Not Covered | Coverage % | +|----------|-------------|---------|-------------|------------| +| Acceptance Criteria | 39 | 39 | 0 | 100% | +| Restrictions | 10 | 10 | 0 | 100% | +| **Total** | 49 | 49 | 0 | 100% | + +## Uncovered Items Analysis + +| Item | Reason Not Covered | Risk | Mitigation | +|------|--------------------|------|------------| +| None | All current AC and restriction groups have black-box coverage | N/A | Continue to Phase 3 validation gate | + +## Data Coverage Caveats + +- Current project data fully supports still-image frame-center checks for 60 mapped images. +- Current project data does not contain synchronized IMU or ground-truth trajectory for BASALT VIO validation. +- Phase 3 must validate public dataset acquisition before FT-P-03, FT-P-04, and NFT-PERF-02 can remain in the executable test plan. diff --git a/_docs/_autodev_state.md b/_docs/_autodev_state.md new file mode 100644 index 0000000..a8671b8 --- /dev/null +++ b/_docs/_autodev_state.md @@ -0,0 +1,14 @@ +# Autodev State + +## Current Step +flow: greenfield +step: 3 +name: Plan +status: completed +tracker: jira +sub_step: + phase: 10 + name: plan-complete + detail: "FINAL_report.md and epics.md saved; Jira epics AZ-206 through AZ-218 created" +retry_count: 0 +cycle: 1