add solution drafts, add component decomposition , add spec for other docs

2026-04-22 22:56:36 +00:00 · 2025-11-19 23:07:29 +02:00
parent e87c33b0ee
commit 30339402f7
24 changed files with 2506 additions and 3 deletions
@@ -0,0 +1,57 @@
+# 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.
+