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

# Glossary

**Status**: confirmed-by-user (Plan baseline 2026-05-09); cycle-1 additions appended 2026-05-19 pending re-confirmation
**Date**: 2026-05-09 baseline · 2026-05-19 cycle-1 additions (marked with `(source: cycle 1 as-built …)` in their entry)
**Scope**: project-specific terminology for the GPS-denied onboard pose-estimation system. Generic software / industry terms (REST, JSON, IMU, WGS84, etc.) are intentionally omitted.

Terms are alphabetical. Each entry: one-line definition + parenthetical source.

---

**`_STRATEGY_REGISTRY`** — Module-level dict in `runtime_root` mapping `(component_slug, strategy_name) → factory`, with `tier` and `depends_on` metadata. Populated per-binary by an `<role>_bootstrap.register_<role>_strategies()` call before `compose_root()` runs; `compose_root()` raises `StrategyNotLinkedError` if a config-selected strategy is absent. Runtime-side complement to ADR-002 build-time exclusion: the build decides which strategies *can* be registered, the registry decides which one this binary *does* register. Filled cycle-1 by AZ-591; public API is `register_strategy(component_slug, strategy_name, factory, *, tier, depends_on)`. (source: cycle 1 as-built; AZ-591 task spec)

**adti20** — Informal name for the production deployment camera, the **ADTi Surveyor Lite 20MP 20L V1** (APS-C ~23.6×15.7 mm, ~5472×3648 px, fixed downward, no gimbal). Pinned in `restrictions.md` §Cameras. (source: `restrictions.md`, user confirmation 2026-05-09)

**adti26** — Informal name for the camera that captured the 60 still-image test fixtures (`AD000001..AD000060.jpg`) under `_docs/00_problem/input_data/`. Distinct from the production-deployed `adti20`; calibration data must be sourced from public/factory references for these test images. (source: user confirmation 2026-05-09)

**AdHoP refinement** — OrthoLoC method-agnostic perspective preconditioning, conditional sub-stage between cross-domain matcher and pose estimation; invoked only when initial reprojection error exceeds threshold (component C3.5). (source: `solution.md` §C3.5, SQ2 Decision 2)

**AGL / Above Ground Level** — Vertical distance from the ground directly below the UAV; operational ceiling ≤1 km AGL. (source: `restrictions.md` §UAV & Flight)

**AI camera** — Operator-controlled gimbal+zoom camera consumed by AI detection systems; out of scope for nav-pose, in scope for AC-7.x object localization only. (source: `restrictions.md` §Cameras)

**`airborne_bootstrap`** — Module under `runtime_root/` that performs the two pre-`compose_root()` setup steps for the airborne binary: `register_airborne_strategies()` populates `_STRATEGY_REGISTRY` with 7 component-strategy slots (c1_vio, c2_vpr, c2_5_rerank, c3_matcher, c3_5_adhop, c4_pose, c5_state), and `build_pre_constructed(config)` constructs the 12-key infrastructure dict (`pre_constructed`). The airborne entrypoint `runtime_root.main()` calls both before `compose_root(config, pre_constructed=...)`. Missing registry entry → `StrategyNotLinkedError`; missing `pre_constructed` key → `AirborneBootstrapError`. Operator binary uses the parallel `operator_bootstrap` module today only as a placeholder. (source: cycle 1 as-built; AZ-591 + AZ-618 umbrella → AZ-619..AZ-624 subtasks)

**Camera calibration artifact** — JSON file carrying camera intrinsics + distortion + body-to-camera extrinsics + acquisition method (`factory_sheet | checkerboard_refined | hybrid`). The only way camera-specific parameters enter the system; no hard-coded camera math anywhere. Test fixtures and production deployments load different artifacts on the same code path. (source: user directive 2026-05-09)

**Companion / Companion PC** — The onboard Jetson Orin Nano Super running the GPS-denied estimation pipeline. Synonyms used interchangeably across docs. (source: `restrictions.md` §Onboard Hardware)

**D-PROJ-1** — *(CLOSED in this Plan cycle)* Camera calibration acquisition strategy. Resolved as: hybrid factory data sheet + per-unit ground-truth checkerboard refinement (~1 day per deployed unit). No physical hardware available this cycle, so production calibration is documented as instructions only. (source: `solution.md` Open decisions, user confirmation 2026-05-09)

**D-PROJ-2** — *(OPEN, parent-suite)* Two design tasks against `satellite-provider`: (i) post-landing tile ingest endpoint, (ii) multi-flight trust / staleness logic. Surfaced in `satellite-provider/_docs/` outside this Plan cycle as a parent-suite deliverable. Tracked via `_docs/_process_leftovers/2026-05-09_satellite-provider-design-tasks.md`. (source: `solution.md`, user confirmation 2026-05-09)

**D-PROJ-3** — Multi-flight fixture acquisition (AerialVL S03 + Maxar Open Data Ukraine + own multi-flight data). NOT pursued in this Plan cycle: AC-NEW-4 / AC-NEW-7 wording was relaxed to Monte-Carlo-over-current-data with stated CI; multi-flight statistical residual risk recorded for the Step 4 risk register. (source: `solution.md`, traceability-matrix.md, user confirmation 2026-05-09)

**Dead reckoned** — Source label `dead_reckoned`: estimate produced from IMU-only propagation with no visual or satellite anchoring. Carries monotonically growing covariance; emitted during visual blackouts or after re-localization fails. (source: AC-1.4, AC-NEW-8)

**Derkachi flight footage** — Representative cropped nadir video + synchronized `SCALED_IMU2` + `GLOBAL_POSITION_INT` telemetry under `input_data/flight_derkachi/`. Used for runtime cadence + VIO + replay testing. (source: `problem.md`, `data_parameters.md`)

**External position / GPS replacement** — What this system emits to the FC: WGS84 coordinates + honest covariance + provenance label, replacing real GPS when denied/spoofed. (source: AC-4.3, AC-6.3)

**FC / Flight Controller** — ArduPilot Plane or iNav. PX4 explicitly out of scope. (source: `restrictions.md` §Sensors & Integration)

**FDR / Flight Data Recorder** — Per-flight onboard NVM record (≤64 GB) of estimates, IMU traces, MAVLink stream, mid-flight tiles, system health, failed-tile thumbnails. Excludes raw nav/AI-camera frames. (source: AC-NEW-3)

**Flight** — Operator-authored mission persisted in the parent-suite `flights` REST service. Carries an ordered list of `Waypoint` entries (lat / lon / alt / objective / source). The DTO shape mirrors `suite/flights/Database/Entities/{Flight,Waypoint}.cs`. C12 reads the `Flight` pre-flight to derive the cache bbox + takeoff origin (AZ-489); the companion never reaches the flights service. (source: ADR-010, AZ-489)

**Flights API / `flights` REST service** — Parent-suite .NET 8 REST microservice (`suite/flights/`) that owns `Flight` + `Waypoint` persistence. Read pre-flight by C12 `FlightsApiClient` over HTTPS. Operator-workstation-only — never reached from the airborne companion (Principle #9). (source: ADR-010, AZ-489)

**Flight state** — Boolean signal `IN_AIR | ON_GROUND` derived from FC `MAV_STATE` (MAVLink HEARTBEAT). Safety-critical: gates the post-landing upload path; `IN_AIR` forbids any outbound write to `satellite-provider`. Enforced primarily by process-level isolation — the Tile Manager (C11), which carries both the `TileDownloader` and the `TileUploader`, is not loaded in the airborne companion image. (source: user directive 2026-05-09)

**GCS / Ground Control Station** — QGroundControl. Mission Planner is out of scope. (source: `restrictions.md`)

**GPS denial / GPS spoofing** — Distinct failure modes the system must distinguish: denial = no fix; spoofing = false fix that must not be promoted into the estimator. (source: AC-3.5, AC-NEW-2, AC-NEW-8)

**`GPS_INPUT`** — MAVLink message used as the per-frame FC delivery channel for ArduPilot Plane. (source: AC-4.3, `restrictions.md`)

**GSD / Ground Sample Distance** — Meters-per-pixel on the ground; target 10–20 cm/px @ 1 km AGL for the nav camera. (source: `restrictions.md` §Cameras)

**Internal smoothing** — AC-4.5 scope: GTSAM iSAM2 retroactively refines past keyframes onboard and emits the corrected current frame; the FC log is forward-time only. NOT to be confused with FC-side retroactive correction (which neither ArduPilot nor iNav supports). (source: `solution.md` §C5, Mode B Fact #107)

**Jetson Orin Nano Super** — Pinned companion compute: 67 TOPS sparse INT8, 8 GB shared LPDDR5, 25 W TDP, JetPack/CUDA/TensorRT. (source: `restrictions.md`)

**`KltRansac`** — Engine-rule-mandatory simple-baseline `VioStrategy` (AZ-334). In cycle 1 this is the **production-default** airborne VIO selection because OKVIS2 (AZ-332) and VINS-Mono (AZ-333) are BLOCKED on Tier-2 prerequisites (CI build env + Jetson hardware + DBoW2 vocab; upstream vendoring decision). The `_STRATEGY_REGISTRY` still registers all three slots — config-selecting OKVIS2 / VINS-Mono raises `StrategyNotAvailableError` from `vio_factory.py` until their `BUILD_*` flag is ON and the Tier-2 follow-ups (AZ-592, AZ-593) land. ADR-001 / ADR-002 unchanged; only the production default selection shifts. (source: cycle 1 as-built; `implementation_completeness_cycle1_report.md`)

**Mid-flight bounded-delta GPS gate** — Third clause of Principle #11. Even when FC GPS health is "stable + non-spoofed for ≥ 10 s" and the visual/satellite consistency check has succeeded, the FC's reported position must be within ≤ 200 m (configurable) of the companion's last emitted `PoseEstimate` before the FC GPS is fused via `add_pose_anchor`. Catches "FC reports stable GPS but the value is wrong". (source: Principle #11 amended, ADR-010)

**Mid-flight tile generation** — Companion orthorectifies nav-camera frames into basemap-projected tiles in flight, deduplicates, stores locally in `satellite-provider`-compatible format. NO outbound upload while airborne — upload happens post-landing only. (source: AC-8.4, user directive 2026-05-09)

**Mission Planner UI** — Parent-suite operator-facing web UI at `suite/ui/` where operators author flight routes (waypoints + altitudes + objectives) before C12 cache provisioning. Persists routes to the `flights` REST service. Out of scope for this project's deliverables, but the `Flight` DTO it produces IS in scope as an inbound boundary. Not to be confused with the GCS-side "Mission Planner" desktop tool — that is out of scope (only QGroundControl is the supported GCS). (source: ADR-010)

**Mission profile** — 8 h flight, ~150 km² operational sector + ~50 km² transit corridor, ≤400 km² total cached, ~60 km/h cruise, ≤1 km AGL, eastern/southern Ukraine. (source: `restrictions.md`)

**`MSP2_SENSOR_GPS`** — MSP2 message used as the per-frame FC delivery channel for iNav (iNav has no inbound MAVLink external-positioning handler). (source: `restrictions.md`, AC-4.3)

**Nav camera / Navigation camera** — The fixed-downward (no gimbal) camera on the UAV; pinned model is `adti20`. Distinct from the operator-controlled AI camera. (source: `restrictions.md` §Cameras)

**Operator** — Pre-flight and post-flight human role: authors the flight route in the **Mission Planner UI** (`suite/ui`), classifies the operational area (active-conflict vs stable rear), drives C12 cache provisioning (which reads the `Flight` from the parent-suite `flights` REST service, downloads satellite tiles via the **Tile Manager** for the route bbox, and bakes the takeoff origin into the C10 Manifest), stages calibration onto the companion before takeoff, and after landing triggers the **Tile Manager** upload run. (source: `problem.md`, AC-3.4 / AC-6.2, ADR-010, user confirmation 2026-05-09 + 2026-05-11)

**`pre_constructed`** — Mandatory kwarg of `compose_root(config, pre_constructed=...)` carrying a 12-key dict of infrastructure objects (`c13_fdr`, `c6_descriptor_index`, `c6_tile_store`, `c7_inference`, `c3_lightglue_runtime`, `c3_feature_extractor`, `c282_ransac_filter`, `c5_wgs_converter`, `c5_se3_utils`, `c5_isam2_graph_handle`, `c5_imu_preintegrator`, `clock`). Built by `airborne_bootstrap.build_pre_constructed(config)` in 6 dependency-ordered phases (Phase A=c13/clock through Phase F=wire `main()`); GPU-touching builders gate on `BUILD_*` env flags. Tests stub by passing the same kwarg. Missing key → `AirborneBootstrapError`. (source: cycle 1 as-built; AZ-618 umbrella → AZ-619..AZ-624 subtasks)

**Tier-1 task / Tier-2 task** — Capability-readiness classification distinct from the `Tier-1 / Tier-2` test-environment split. A **Tier-1 task** is the cycle deliverable; passes the implement skill's cycle-end Completeness Gate without external hardware/CI prerequisites. A **Tier-2 task** is a follow-up gated on prerequisites that are not provisioned in this cycle (e.g., DBoW2 vocab artifact for OKVIS2; Jetson runner for VINS-Mono pybind11 binding). Tier-2 follow-ups are parked in `_docs/02_tasks/backlog/` with the Tier-1 task's BLOCKED handle naming them explicitly. The implement skill's "PASS-with-BLOCKED" terminal classification permits a Tier-1 task to ship in BLOCKED state if a Tier-2 follow-up is named in its Implementation Notes. (source: cycle 1 as-built; `implementation_completeness_cycle1_report.md`)

**Tile Manager** — Operator-side component (C11) that owns both directions of network I/O against `satellite-provider`: pre-flight download (F1) into the local C6 store via the `TileDownloader` interface, and post-landing upload (F10) from C6 to the parent-suite ingest endpoint via the `TileUploader` interface. Carries **no internal flight-state gating** (Batch 44 SRP refactor — the post-landing safety check lives in C12's `PostLandingUploadOrchestrator`, which reads the `flight_footer.clean_shutdown` field). Implemented as a separate binary / image so neither network path is loaded in the airborne companion (ADR-004 process-level isolation). Replaces the earlier "post-landing upload tool" naming after Plan-cycle scope expansion 2026-05-09. (source: user directive 2026-05-09; Batch 44 SRP refactor 2026-05-13)

**`satellite-provider`** — First-class architecture boundary: the suite's existing .NET 8 REST microservice at `/Users/obezdienie001/dev/azaion/suite/satellite-provider/`. Runs in Docker (`:5100`, OpenAPI at `/swagger`); downloads Google Maps tiles; stores them in PostgreSQL + filesystem (`./tiles/{zoomLevel}/{x}/{y}.jpg`). Read-only from the onboard runtime; receives post-landing tile uploads via a yet-to-be-designed ingest endpoint (parent-suite work, D-PROJ-2). Synonym in older docs: "Suite Sat Service" / "Azaion Suite Satellite Service". (source: parent-suite `satellite-provider/README.md`, user confirmation 2026-05-09)

**Satellite anchored** — Source label `satellite_anchored`: estimate produced by matching the current nav frame against pre-cached satellite tiles. Highest confidence among the three labels. (source: AC-1.4)

**Sector classification** — Pre-flight operator decision: active-conflict (6-month tile-freshness threshold) vs stable rear (12-month threshold). Drives the freshness gate at ingest and during runtime tile use. (source: AC-8.2, AC-NEW-6, `solution.md` operator-orchestrator section)

**Source label** — Provenance tag carried with every emitted estimate: `{satellite_anchored | visual_propagated | dead_reckoned}`. (source: AC-1.4)

**Suite Sat Service** — Synonym for `satellite-provider` used in earlier docs (problem.md, restrictions.md, solution_draft01/02). The actual implementation in the parent suite is the .NET 8 service; "Suite Sat Service" is the role name. (source: `restrictions.md`, parent-suite `satellite-provider/README.md`)

**Takeoff origin** — `LatLonAlt` baked into the C10 Manifest by C12 at build time from `Flight.waypoints[0]`. Consumed at boot by C5 via `set_takeoff_origin(origin, sigma_horiz_m, sigma_vert_m)` (AZ-490) as a Bayesian prior on the initial pose — iSAM2 attaches a `PriorFactorPose3` at `Pose3.Identity()` (origin BECOMES the local-ENU (0,0,0) anchor); ESKF seeds the nominal position to (0,0,0) + position-block covariance to `diag(sigma_horiz_m², sigma_horiz_m², sigma_vert_m²)`. Primary cold-start trust anchor per ADR-010; FC EKF GPS is secondary. (source: ADR-010, AZ-490)

**Tier-1 / Tier-2** — Testing-environment split: Tier-1 = workstation Docker (fast/cheap); Tier-2 = Jetson hardware (AC-bound). Both appear in the deployment plan and CI matrix per finding F6. (source: `_docs/02_document/tests/environment.md`)

**Tile** — Unit of persistent imagery on the companion; basemap-projected, deduplicated; the only persistent imagery format. Mid-flight-generated tiles use the same on-disk format as `satellite-provider` (`./{zoomLevel}/{x}/{y}.jpg` + matching metadata schema) so post-landing upload is byte-identical. (source: AC-8.4, AC-8.5, parent-suite `satellite-provider/README.md`, user confirmation 2026-05-09)

**Tile cache** — Local on-Jetson store, ≤10 GB, populated pre-flight from `satellite-provider`, augmented mid-flight by orthorectified nav-camera-derived tiles. (source: `restrictions.md`, AC-8.3, AC-8.4)

**Tile freshness** — <6 mo (active-conflict sectors) / <12 mo (stable rear); stale tiles must be rejected or downgraded. (source: AC-8.2, AC-NEW-6)

**TTFF / Time To First Fix** — From companion boot to first valid emitted external-position frame; budget <30 s p95. (source: AC-NEW-1)

**UAV** — Fixed-wing unmanned aerial vehicle this system runs on; ~60 km/h cruise, ≤1 km AGL, 8 h flights, eastern/southern Ukraine theater. (source: `restrictions.md`)

**VioStrategy** — Pluggable interface (Okvis2 / VinsMono / KltRansac) selected at startup by config; not hot-swappable mid-flight. The interchangeable-strategy pattern (ADR-001) plus build-time exclusion via per-implementation CMake `BUILD_*` flags (ADR-002) lets the project produce a small **deployment binary** (links the production-default + the engine-rule-mandatory simple-baseline) and a separate **research binary** that links every available strategy for the IT-12 comparative-study report. ADR-002 is purely technical (binary size on 8 GB shared Jetson, AC-NEW-1 boot budget, dependency / attack surface, accidental-selection risk); component licenses do not influence which strategy is the deployment-default. (source: `solution.md` §C1, `architecture.md` ADR-001 + ADR-002 + ADR-009)

**VIO / Visual-Inertial Odometry** — Frame-to-frame motion + IMU bias estimation via fused camera + IMU streams (component C1). (source: `solution.md` §C1)

**Visual propagated** — Source label `visual_propagated`: estimate produced by VIO frame-to-frame propagation with no fresh satellite anchor. Mid-confidence. (source: AC-1.4)

**VPR / Visual Place Recognition** — Descriptor-based retrieval of the nearest satellite tile to the current nav frame (component C2). (source: `solution.md` §C2)

**Waypoint** — Ordered `(lat, lon, alt, objective, source)` entry inside a `Flight`. Operationally meaningful ordering: `waypoints[0]` is the planned takeoff point and is extracted by C12 `FlightsApiClient` as the takeoff origin. C12 envelopes all waypoint lat/lon to derive the cache bbox. DTO shape mirrors `suite/flights/Database/Entities/Waypoint.cs`. (source: ADR-010, AZ-489)