mirror of
https://github.com/azaion/gps-denied-onboard.git
synced 2026-06-21 18:41:13 +00:00
Oleksandr Bezdieniezhnykh
72a9df6b57
Keep VIO package and native bridge paths backend-neutral so BASALT remains an implementation choice rather than a component boundary. Co-authored-by: Cursor <cursoragent@cursor.com>
149 lines
8.4 KiB
Markdown
149 lines
8.4 KiB
Markdown
# 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
|
|
|
|
```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.
|