Satellite Retrieval

1. High-Level Overview

Purpose: Convert a query frame and prior state into ranked satellite/cache VPR chunk candidates using DINOv2-VLAD descriptors and FAISS.

Architectural Pattern: Query service / retrieval index adapter.

Upstream dependencies: Camera ingest/calibration, cache/tile lifecycle, safety/anchor wrapper.

Downstream consumers: Anchor verification, FDR.

2. Internal Interfaces

Interface: `CandidateRetriever`

Method	Input	Output	Async	Error Types
`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
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.

Key Dependencies:

Library	Purpose
DINOv2 / ONNX / TensorRT candidate path	Query descriptor extraction
FAISS CPU	Top-K retrieval

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.

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.

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.

2.8 KiB Raw Blame History