gps-denied-onboard/_docs/02_document/glossary.md

# Glossary

> **Status**: confirmed-by-user
> **Date**: 2026-04-27
> **Scope**: project-specific terminology only. Generic software / network / OS terms (REST, JSON, TCP, container, etc.) are intentionally excluded.
> **Source convention**: `(source: <file> [§<section>])` — points back to the input where the term originates. `(decision: 2026-04-27)` marks terms whose meaning was locked during the Phase 2a.0 review.

---

## A

- **Absolute pose** — position + orientation derived from a cross-view match against the satellite basemap (Component 3 + PnP). Synonym: *visual fix*, *satellite-anchored fix*, *anchor fix*. Distinguished from *relative pose*. (source: solution.md §Component 3)
- **Active-conflict sector** — operational sub-area where building destruction or major scene change is expected; drives stricter freshness budget (<6 months) and larger VPR top-K. (source: AC-8.2, AC-NEW-6)
- **AGL** — Above Ground Level (altitude reference). UAV mission profile is ≤1 km AGL. (source: restrictions.md §UAV & Flight)
- **AI camera** — operator-controllable mission camera with gimbal + zoom; output consumed by onboard AI detection systems. Distinct from the nav cam. Pose available to this build: gimbal angle + zoom only (not airframe bank/pitch). (source: restrictions.md §Cameras, AC-7.1)
- **Airframe manifest** — per-airframe signed configuration document produced by the Provisioning Tool (Component 12) at client setup. Contains FC firmware version, MAVLink2 signing-key fingerprint, sysid assignments (10/11), camera intrinsics, FC parameter pinning. (decision: 2026-04-27)
- **Anchor fix** — see *absolute pose*.
- **ArduPilot** — autopilot firmware. The only autopilot target in v1 scope. Configured with `GPS1_TYPE=14` for MAVLink GPS injection. PX4 is out of v1 scope. (source: restrictions.md §Sensors & Integration; AC-4.3)
- **Azaion Suite** — the broader product family this build is one component of. Sibling components include Satellite Service, AI detection, semantic detection. (source: AC-8.1; decision: 2026-04-27)
- **Azaion Suite Satellite Service** — sibling Suite component responsible for upstream satellite imagery sourcing and onboard-tile ingest with 2-flight voting. Out of scope for this build except at the **tile-cache folder boundary**. Contract authorship lives in `../satellite-service/`. (source: AC-8.1; decision: 2026-04-27)

## B

- **Basemap** — the satellite reference imagery surface against which UAV nav-cam frames are matched. Stored as MBTiles z=19 in the local tile cache. (source: AC-NEW-7, solution.md §Tile generation; decision: 2026-04-27)
- **Bench-off** — comparative empirical measurement on Orin Nano Super @ 25 W against the dataset suite (AerialVL / UAV-VisLoc / AerialExtreMatch / 2chADCNN season set / TartanAir V2 / internal Mavic / first internal fixed-wing flight). Used to lock matcher / VO / VPR / z-level decisions. (source: solution.md §Component 3, §Component 4)

## C

- **Candidate pool** — Service-side staging area for onboard-generated tiles awaiting 2-flight voting promotion. Companion writes here post-flight; Service ingest reads. (source: solution.md §Tile generation; AC-NEW-7)
- **Companion computer** — the Jetson Orin Nano Super running this build alongside the FC. Not the FC itself, not the GCS. (source: restrictions.md §Onboard Hardware)
- **Companion-side FDR** — slim flight log on the companion NVMe holding ONLY signals the FC dataflash does not capture (per-stage gate values, source-label decisions, tile-generation events, failure thumbnails, Jetson health). 3-flight rolling retention, ~500 MB/flight compressed. Distinct from the FC dataflash. (decision: 2026-04-27, supersedes AC-NEW-3 v1.0)
- **Confidence score** — `(σ_xy, source_label)` pair carried on every emitted fix. Cross-cutting (Component 11). (source: AC-1.4)
- **Cross-view matching** — matching a UAV nav-cam frame against a satellite basemap chunk to obtain an absolute pose. Cross-domain (aerial photo ↔ ortho satellite tile) — distinguished from frame-to-frame VO matching. (source: solution.md §Component 3)
- **cuVSLAM** — NVIDIA's CUDA-accelerated monocular+IMU VO/SLAM engine. v1 visual odometry (Component 4). Apache-2.0, drop-in via `isaac_ros_visual_slam` ROS 2 wrapper. (source: solution.md §Component 4; M-22, M-23)

## D

- **Dead reckoning** — IMU-only position propagation when no visual fix is available. Source-label `dead_reckoned`. Performed FC-side by EKF3, never companion-side in v1. (source: AC-1.4, AC-5.2; M-26)
- **DEM** — Digital Elevation Model. SRTM-30 m DEM is loaded per-sector and consumed by Component 1b (Orthority) for orthorectification. (source: solution.md §Component 1b)
- **DDS** — middleware transport layer used by ROS 2 Humble. ~2–5 % CPU overhead accepted in exchange for `isaac_ros_visual_slam` + MAVROS integration. (source: solution.md §Component 9)

## E

- **EKF3** — ArduPilot's 24-state classical extended Kalman filter, runs at 400 Hz on the FC. The ONLY state-propagating filter in the v1 system. Consumes our `GPS_INPUT` plus its own IMU/baro/compass. (source: solution.md §Component 5; M-26)
- **ESKF** — Error-State Kalman Filter; tangent-space covariance on SO(3). Reserved for a hypothetical v1.x companion-side filter only — NOT used in v1. (source: solution.md §Component 5; S69)

## F

- **Failsafe** — autopilot fallback to IMU-only dead reckoning when this build fails to emit a fix for >3 s. (source: AC-5.2; restrictions.md §Failsafe)
- **FC** — Flight Controller; the ArduPilot board on the airframe. (source: restrictions.md §Sensors & Integration)
- **FC dataflash** — ArduPilot's microSD-resident binary log on the FC itself. Authoritative for IMU traces, received `GPS_INPUT` frames, EKF3 internal state, MAVLink raw tlog. Companion-side FDR does NOT duplicate these. (decision: 2026-04-27)
- **Failure thumbnail** — low-rate (≤0.1 Hz) downsampled JPEG of nav-cam frames that failed tile generation. Forensic-only, retained on companion FDR for AC-NEW-7 audit. Other frames are NOT retained (no raw-frame storage policy). (source: AC-8.5, AC-NEW-3 revised)
- **FDR** — Flight Data Recorder. In this build refers to the *companion-side* FDR (slim, companion-side-unique signals only). Not to be confused with the FC dataflash. See *Companion-side FDR*. (source: AC-NEW-3 revised; decision: 2026-04-27)
- **Fixed-wing** — UAV airframe type (winged, not multirotor). The only airframe class in scope. (source: restrictions.md §UAV & Flight)
- **Frame center** — geographic center of a navigation-camera frame projected onto the ground. Primary AC-1.1 / AC-1.2 accuracy target. Synonym: *photo center* (problem.md uses "photo", AC uses "frame"). (source: problem.md, AC-1.1)
- **Freshness budget** — maximum allowable age of a satellite tile: <6 months for active-conflict sectors, <12 months for stable rear sectors. Tiles past budget are rejected or down-confidence-weighted. (source: AC-8.2, AC-NEW-6)

## G

- **GCS** — Ground Control Station. In this build, **only QGroundControl** is supported. Mission Planner is not in scope. There is no Azaion-custom GCS service. (source: AC-6.1, restrictions.md §Sensors; decision: 2026-04-27)
- **GPS_INPUT** — MAVLink message ID used to inject the GPS-equivalent fix into ArduPilot. Carries `h_acc`, `v_acc`, `vel_acc` covariance. The single MAVLink output channel from this build to the FC in v1. (source: AC-4.3)
- **GPS-denial** — operational condition where real GPS is jammed, spoofed, or otherwise unavailable. The trigger condition for this build's promotion to FC primary GPS source. (source: problem.md, AC-NEW-2)
- **GPS-Denied system / GPS-Denied stack** — this build itself; the onboard companion-computer software stack. Synonyms: *the build*, *companion-side software*. (source: AC-8.1)
- **GSD** — Ground Sample Distance, in cm/px on the ground. Nav cam at 1 km AGL ≈ 12 cm/px. Basemap at z=19 ≈ 60 cm/px. Scale ratio (basemap GSD / nav-cam GSD) is the matcher's binding constraint. (source: restrictions.md §Cameras, AC-8.1; decision: 2026-04-27)

## I

- **Isaac ROS** — NVIDIA's robotics middleware extensions on ROS 2 Humble. Provides `isaac_ros_visual_slam` for cuVSLAM integration. v1 orchestration platform alongside MAVROS. (source: solution.md §Component 9; Q6 → A)

## J

- **Jetson Orin Nano Super** — the onboard processing platform. 67 TOPS sparse INT8, 8 GB shared LPDDR5 (CPU+GPU share the same pool), 25 W TDP. Runs JetPack 6 / Ubuntu 22.04. (source: restrictions.md §Onboard Hardware)
- **Jetson UI** — pre-flight web UI deployed on the Jetson companion, accessed by the operator via wired connection during pre-flight. Used for: drawing route + operational sector, triggering tile fetch from the Suite Satellite Service, running Provisioning Tool steps, walking through camera intrinsics calibration. Requires pre-flight internet. (decision: 2026-04-27)

## L

- **LiteSAM** — purpose-built satellite↔aerial AVL matcher (S58, MDPI Oct 2025). Used in this build in three NON-inline roles: (a) re-localization fallback (cold start, σ_xy > 50 m, sharp turn after VO loss); (b) offline validation oracle; (c) distillation teacher for a future inline student model. NOT inline due to ~1.5–2 s/pair latency on Orin Nano Super. (source: solution.md §Component 3; M-24)

## M

- **Mahalanobis gate** — outlier rejection mechanism in Component 5. Drops fix candidates whose innovation w.r.t. the cuVSLAM relative-pose prior exceeds a threshold derived from AC-NEW-4. NOT a state-propagating filter — pure gate. (source: solution.md §Component 5; M-26)
- **MAVLink2 signing** — per-link cryptographic signing on every companion ↔ FC link. **Mandatory in v1**. Per-airframe signing key written to FC FRAM via `MAV_CMD_SETUP_SIGNING` during Provisioning Tool bootstrap. USB connections bypass signing — bench-only. (source: solution.md §Component 6; R10)
- **MAVROS** — ROS 2 ↔ MAVLink bridge node. Owned by Component 9. Subscribes to FC `RAW_IMU` / `SCALED_IMU` / `ATTITUDE`; publishes our `GPS_INPUT`. (source: solution.md §Component 9)
- **MAVSDK** — high-level MAVLink library. Used in this build for general telemetry (sysid=10) only. Does NOT inject `GPS_INPUT` (no native API; that goes through pymavlink). (source: AC-4.3, restrictions.md §Sensors)
- **MBTiles** — SQLite-backed tile-storage container format. **One file** for the whole tile cache (not thousands of filesystem entries). Used by Component 1 for the persistent tile cache; opened with WAL + connection pool + transaction batching. (source: solution.md §Component 1)
- **Mission YAML** — per-mission configuration written by Jetson UI alongside the tile fetch. Contains operational area polygon, sector classes (active-conflict / stable rear), mission ID. One of three configuration scopes. (decision: 2026-04-27)

## N

- **Nadir** — straight-down direction from the airframe. Nav cam is fixed nadir-pointing. (source: restrictions.md §Cameras)
- **Nav cam / Navigation camera** — fixed downward-pointing 20 MP APS-C camera (ADTi 20MP 20L V1). Consumed by this build for position estimation. NOT operator-controllable, NOT gimbaled. Distinct from the AI camera. (source: restrictions.md §Cameras)

## O

- **ODOMETRY** — alternate MAVLink ExtNav channel (richer covariance, native yaw error, quality field). **Intentionally disabled in v1** (Option A in M-30) due to ArduPilot EKF3 double-fusion bugs (#30076 / #32506). Re-enables in v1.1 once F-T9 SITL confirms PR #30080-class clean source-switching. (source: AC-4.3 v1 scope clause)
- **Operational area** — the pre-cached union of sector + transit corridor for a mission. Up to ~400 km² total. Cache is persistent across flights. (source: restrictions.md §UAV & Flight)
- **Operator** — the UAV pilot operating the mission. Responsible for: pre-flight tile fetch via Jetson UI, monitoring via QGC during flight, optional re-localization hints via QGC. Single human role; no co-operator distinction in v1. (source: restrictions.md, AC-6.2)
- **Orthority** — Python library used by Component 1b for per-frame orthorectification. Frame-camera model + GeoTIFF DEM. Pip-installable, MIT-class license. Documented fall-back: `cv2.warpPerspective + bilinear DEM` if F-T14 latency budget (≤50 ms/frame) is exceeded. (source: solution.md §Component 1b; M-27)
- **Orthorectification / Ortho** — projecting a nav-cam frame onto the basemap projection (EPSG:3857 z=19) using the camera model + per-sector DEM. Output is a basemap-aligned tile. (source: solution.md §Component 1b)

## P

- **PnP** — Perspective-n-Point, the geometric step that turns matched 2D-3D correspondences (cross-view matcher output) into an absolute pose + covariance. (source: solution.md §Component 3)
- **Provisioning Tool** — Jetson-side `provision-fc.py` workflow that runs once at client setup. Does FC parameter pinning (`GPS1_TYPE=14`, `EK3_SRC1_*`, `SERIAL2_*`), MAVLink2 signing-key bootstrap, and a smoke-test (`RAW_IMU` rate + `GPS_INPUT` round-trip). Produces the per-airframe signed manifest. Component 12. (decision: 2026-04-27)
- **pymavlink** — low-level MAVLink Python library. Used in this build EXCLUSIVELY for `GPS_INPUT` injection (sysid=11). MAVSDK has no native `GPS_INPUT` API. (source: AC-4.3, M-6)

## Q

- **QGC / QGroundControl** — the supported GCS software. Operator-side application running on a laptop or tablet, communicating with the FC via MAVLink. Receives a 1–2 Hz downsampled telemetry summary from the companion through the FC. NOT running on the companion. (source: AC-6.1, restrictions.md §Sensors; decision: 2026-04-27)

## R

- **Re-localization (re-loc)** — the act of recovering an absolute pose after VO/cuVSLAM tracking loss. Triggers: cold start (AC-NEW-1), sharp turn (AC-3.2), disconnected segment (AC-3.3), σ_xy > 50 m, VO failure for ≥2 frames. VPR + LiteSAM are the re-loc workhorses; SP+LG inline matcher is invoked after VPR narrows the candidate set. (source: AC-3.3, AC-8.6, solution.md §Component 3)
- **Relative pose** — frame-to-frame pose increment produced by cuVSLAM. Distinguished from *absolute pose* (matcher + PnP). (source: solution.md §Component 4)
- **ROS 2 Humble** — middleware platform on JetPack 6 / Ubuntu 22.04. v1 orchestration target (Q6 → A, locked 2026-04-26). Replaces the draft01 "single Python asyncio process". (source: solution.md §Component 9; M-29)

## S

- **Sector** — operational sub-area within the operational area. Two sub-types matter: *active-conflict* (stricter freshness, K=20 VPR top-K) and *stable rear* (relaxed freshness, K=5). Plus a separate terrain classification (`flat` / `moderate` / `rugged`) used by Component 1b. (source: AC-8.2, AC-NEW-6, solution.md §Component 1b)
- **σ_xy / sigma_xy** — 2D position uncertainty: the 95% covariance ellipse semi-major axis in meters. Carried on every emitted fix; gates Component 1b tile-generation eligibility (≤5 m hard, ≤3 m for full-quality writes). (source: AC-1.4, AC-NEW-7)
- **SITL** — Software-In-The-Loop ArduPilot simulator. Used by F-T9 to validate the full MAVLink loop (GPS_INPUT injection, source switching, MAVLink2 signing). (source: solution.md §F-T9)
- **Source label** — categorical tag on every emitted fix: `satellite_anchored` (matcher+PnP succeeded), `vo_extrapolated` (cuVSLAM continuation from last anchor), `dead_reckoned` (no recent visual fix). Drives FC's confidence treatment. (source: AC-1.4)
- **Spoofing-promotion** — the system action of promoting our estimate to FC primary GPS source when real GPS is detected as spoofed/lost. Latency target <3 s (AC-NEW-2). Driven by Component 7 watching `GPS_RAW_INT`, `EKF_STATUS_REPORT`, `SYS_STATUS`. (source: AC-NEW-2)
- **Stable rear sector** — operational sub-area where major scene change is not expected. Relaxed freshness budget (<12 months); smaller VPR top-K (K=5). Opposite of active-conflict sector. (source: AC-8.2)
- **Suite Service ingest** — server-side process at the Suite Satellite Service that consumes onboard-uploaded tiles via the candidate pool and applies 2-flight voting before promoting them to trusted basemap. Out of scope for this build (lives in `../satellite-service/`). (source: AC-NEW-7)
- **sysid (system ID)** — MAVLink endpoint identifier. Companion uses two: **10** (MAVSDK telemetry) and **11** (pymavlink GPS_INPUT). FC uses its native `SYSID_THISMAV`. Routing handled by ArduPilot's native MAVLink routing — no `mavlink-router` daemon. (source: solution.md §Component 6; M-31)

## T

- **TartanAir V2** — synthetic dataset (Q4 → A, locked) used as early-stage matcher and VO baseline before real flight data is available. (source: solution.md, Q4)
- **TensorRT (TRT)** — NVIDIA's GPU inference compiler. All heavy NN inference in this build runs as TRT engines (FP16 default; INT8 where validated). Engines built at install time, not at first run, to meet AC-NEW-1 cold-start budget. (source: solution.md §Component 9, AC-NEW-1)
- **Tile** — slippy-XYZ z=19, 512×512 px, ~60 cm/px GSD. The unit of basemap **storage** in the tile cache. Decoupled from the VPR chunk (the unit of retrieval). Carries sidecar metadata: `parent_pose_sigma_xy`, `terrain_class`, `trust_level`, `capture_date`. (decision: 2026-04-27, supersedes z=20 in restrictions.md / solution.md)
- **Tile cache** — the persistent MBTiles store on the companion NVMe at `/var/azaion/tile-cache/` (path TBD with Suite Service contract). Read+write during flight. ~700 MB for a 400 km² operational area at z=19. Persistent across flights — not redownloaded. (source: restrictions.md §Satellite Imagery; decision: 2026-04-27)
- **Tile-cache folder** — the **boundary contract** between this build and the Suite Satellite Service. Pre-flight: tiles arrive in this folder via the Service's fetch flow (out-of-scope mechanism). In-flight: this build reads + writes to this folder. Post-flight: this build's uploader pushes new tiles from this folder to the Service candidate pool. The folder layout / file naming is owned by `../satellite-service/`. (decision: 2026-04-27)
- **Trust level** — sidecar metadata on each onboard-generated tile: `candidate` (default; σ_xy ≤ 5 m), `soft` (σ_xy ∈ (3, 5] m), or trusted-basemap (post Service-side 2-flight voting). Determines whether downstream flights match against it. (source: AC-NEW-7)
- **TTFF** — Time-to-First-Fix on cold start. Budget: <30 s from companion-computer boot to first valid `GPS_INPUT` (AC-NEW-1). Drives TRT engine pre-build, FAISS index pre-load, mmap-warm tile cache. (source: AC-NEW-1)

## V

- **Visual fix** — see *absolute pose*.
- **VO** — Visual Odometry. Frame-to-frame relative pose. In v1 supplied by cuVSLAM in monocular+IMU mode. Distinguished from cross-view matching against the satellite basemap. (source: solution.md §Component 4)
- **VPR** — Visual Place Recognition. Global descriptor retrieval (DINOv2 SALAD/BoQ; AnyLoc fallback) over a FAISS IVF index of per-chunk descriptors. Narrows the basemap to a top-K candidate-chunk shortlist on re-localization triggers. **Conditionally invoked**, not per-frame. (source: solution.md §Component 2; AC-8.6)
- **VPR chunk** — ground-footprint-sized (~600–800 m at 1 km AGL, 40–50 % overlap) retrieval unit derived from the z=19 storage tile cache. **Decoupled from the storage tile** — must NOT be conflated. Multi-scale: fine-scale (z=19-derived) + coarse (z=17/z=18 effective scale) for change-robust retrieval in active-conflict sectors. (source: AC-8.6, restrictions.md §Satellite Imagery)

## W

- **WGS84** — coordinate system used for all output GPS coordinates. Matches `GPS_INPUT` spec. (source: AC-6.3)

## Z

- **z=19 / Storage tile zoom** — slippy-XYZ zoom level 19, ~60 cm/px GSD, 512×512 tiles. The pinned basemap storage zoom for v1. Scale ratio to nav cam at 1 km AGL is **5×** (above the 4× safety threshold quoted in solution.md draft03 §Component 1) — accepted as v1 default with documented fall-back to z=20 if matcher bench-off shows AC-2.2 (MRE <2.5 px cross-domain) failure. ~700 MB cache for a 400 km² operational area. (decision: 2026-04-27, supersedes restrictions.md §Satellite Imagery z=20 clause)