gps-denied-onboard/_docs/00_research/02_fact_cards.md

# 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.