gps-denied-desktop/docs/02_components/06_L2_Global_ReLocalization/spec.md

L2 Global ReLocalization Component

Detailed Description

L2 Global ReLocalization addresses the "Kidnapped Robot" problem. It is triggered when L1 fails (tracking lost) or periodically to drift-correct. It uses AnyLoc (DINOv2 + VLAD) to describe the current UAV image and queries the Map Data Provider's Faiss index to find the most similar satellite tiles.

It does NOT give a precise coordinate, but rather a "Top-K" list of candidate tiles (coarse location).

API Methods

localize_coarse

• Input: frame: FrameObject, top_k: int
• Output: List[CandidateLocation]
• Description:
  1. Runs DINOv2 inference on the frame to get feature map.
  2. Aggregates features via VLAD to get a global descriptor vector.
  3. Queries Map Data Provider's Global Index.
  4. Returns list of candidates.
     • CandidateLocation: { tile_id: str, similarity_score: float, center_gps: LatLon }
• Test Cases:
  • Input Frame A -> Returns Satellite Tile covering Frame A's location in Top-3.
  • Input Black/Occluded Image -> Returns Low confidence or random.

Integration Tests

• Recall Test: Run on dataset where ground truth is known. Verify that the correct tile is within the returned Top-5 for > 80% of queries.

Non-functional Tests

• Query Time: Vector search must be extremely fast (< 50ms) even with large indices. DINOv2 inference is the bottleneck.