gps-denied-onboard/docs/02_components/03_Map_DataProvider/spec.md

Map Data Provider Component

Detailed Description

The Map Data Provider acts as the interface to the external "Custom Satellite Provider." It abstracts the complexity of fetching, caching, and georeferencing satellite imagery.

It maintains two layers of data:

1. Global Index: A pre-computed vector database (Faiss) of satellite tiles covering the operation area, used by Layer 2 for coarse localization.
2. Tile Cache: A local storage of high-resolution satellite raster tiles used by Layer 3 for fine matching.

It also handles the projection mathematics (Web Mercator <-> WGS84 Lat/Lon).

API Methods

initialize_region

• Input: bounding_box: {lat_min, lat_max, lon_min, lon_max}, zoom_level: int
• Output: void
• Description: Prepares the system for the target area. Checks if tiles are cached; if not, requests them from the provider. Loads the Faiss index into memory.
• Test Cases:
  • Region fully cached -> fast load.
  • Region missing -> initiates fetch (simulated).

get_tile_by_coords

• Input: lat: float, lon: float, radius_m: float
• Output: List[SatelliteTile]
• Description: Returns satellite tiles that cover the specified coordinate and radius. Used when we have a prior position (e.g., from L1 or History).
  • SatelliteTile: image: np.array, bounds: BoundingBox, gsd: float.
• Test Cases:
  • Coordinate edge case (tile boundary) -> Returns overlapping tiles.

get_global_index

• Input: void
• Output: FaissIndex, List[TileMetadata]
• Description: Returns the handle to the searchable vector index and the corresponding metadata map (mapping index ID to tile geolocation).
• Test Cases:
  • Verify index size matches number of tiles.

latlon_to_pixel

• Input: lat: float, lon: float, tile_bounds: BoundingBox, image_shape: tuple
• Output: x: int, y: int
• Description: Converts a GPS coordinate to pixel coordinates within a specific tile.
• Test Cases:
  • Lat/Lon matches tile center -> Output (w/2, h/2).
  • Lat/Lon matches NW corner -> Output (0, 0).

pixel_to_latlon

• Input: x: int, y: int, tile_bounds: BoundingBox, image_shape: tuple
• Output: lat: float, lon: float
• Description: Inverse of latlon_to_pixel.
• Test Cases:
  • Round trip test (LatLon -> Pixel -> LatLon) < 1e-6 error.

Integration Tests

• Mock Provider: Simulate the "Custom Satellite Provider" returning dummy tiles. Verify caching logic writes files to disk.

Non-functional Tests

• Memory Usage: Ensure loading the Faiss index for a large region (e.g., 100km x 100km) does not exceed available RAM.