Oleksandr Bezdieniezhnykh
3.7 KiB
Satellite Service
1. High-Level Overview
Purpose: Own the onboard boundary to the suite Satellite Service: import pre-flight mission cache packages, upload generated-tile packages after flight, and convert query frames into ranked local VPR candidates using preloaded DINOv2-VLAD descriptors and FAISS.
Architectural Pattern: Offline sync gateway + local retrieval index adapter.
Upstream dependencies: Camera ingest/calibration, Tile Manager, safety/anchor wrapper, Azaion Suite Satellite Service before/after flight.
Downstream consumers: Anchor verification, FDR.
2. Internal Interfaces
Interface: SatelliteService
| Method | Input | Output | Async | Error Types |
|---|---|---|---|---|
import_mission_cache |
CacheImportRequest |
CacheImportResult |
Yes | SyncUnavailable, PackageInvalid |
upload_generated_tiles |
GeneratedTileUploadRequest |
GeneratedTileUploadResult |
Yes | SyncUnavailable, PackageRejected |
retrieve |
RetrievalRequest |
RetrievalResult |
Yes | IndexUnavailable, DescriptorFailed |
load_index |
IndexLoadRequest |
IndexStatus |
No | ManifestInvalid, IndexUnavailable |
Input DTOs:
RetrievalRequest:
frame: FramePacket
prior_estimate: PositionEstimate optional
search_radius_m: number optional
max_candidates: integer
Output DTOs:
RetrievalResult:
query_descriptor_id: string
candidates: list[VprCandidate]
VprCandidate:
chunk_id: string
tile_id: string
score: number
footprint: geometry
freshness_status: enum
3. Data Access Patterns
| Query | Frequency | Hot Path | Index Needed |
|---|---|---|---|
| Top-K FAISS search | Triggered only | No steady-state | FAISS index |
| Import/export package sync | Pre-flight / post-flight only | No mid-flight | Package manifest and sidecar hashes |
| Load chunk metadata | Per candidate | No | PostgreSQL/PostGIS spatial and chunk indexes |
4. Implementation Details
State Management: Holds loaded descriptor model and FAISS index handles; tracks pre-flight import and post-flight upload package status.
Key Dependencies:
| Library | Purpose |
|---|---|
| DINOv2 / ONNX / TensorRT candidate path | Query descriptor extraction |
| FAISS CPU | Top-K retrieval |
| Satellite Service client | Pre-flight cache import and post-flight generated-tile upload |
Error Handling Strategy:
- If descriptor extraction or index load fails, return no candidates and trigger degraded mode.
- Optimized engines are allowed only after descriptor-fidelity tests pass.
- Network/package sync failures are allowed only before takeoff or after landing; during flight, the component must never call a satellite provider or suite service.
5. Caveats & Edge Cases
Known limitations:
- VPR result is only a candidate, never an accepted fix.
- Cross-domain retrieval can be wrong under seasonal, lighting, or terrain ambiguity.
- External Satellite Service availability cannot be part of the mid-flight localization safety case.
Performance bottlenecks:
- Descriptor extraction on Jetson must be trigger-limited and profiled separately from BASALT.
6. Dependency Graph
Must be implemented after: cache manifest/index schema, camera frame DTOs.
Can be implemented in parallel with: anchor verification.
Blocks: satellite relocalization flow.
7. Logging Strategy
| Log Level | When | Example |
|---|---|---|
| ERROR | Index unavailable | faiss_index_unavailable id=... |
| WARN | No candidates | vpr_no_candidates frame_id=... |
| INFO | Retrieval invoked | vpr_query candidates=... latency_ms=... |
Log format: FDR structured event.
Log storage: FDR segment.