# 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.