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

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	Tile Manager
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	Backend-relative state, velocity, bias, tracking quality	Internal DTO; FDR event	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 Service
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	Tile Manager
GeneratedTile	In-flight tile candidate with trust/provenance metadata	COG + sidecar + FDR event	Tile Manager
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

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.