diff --git a/_bmad-output/implementation-artifacts/2-2-coordinate-projection-and-base-map-loading.md b/_bmad-output/implementation-artifacts/2-2-coordinate-projection-and-base-map-loading.md new file mode 100644 index 0000000..47888c3 --- /dev/null +++ b/_bmad-output/implementation-artifacts/2-2-coordinate-projection-and-base-map-loading.md @@ -0,0 +1,87 @@ +# Story 2.2: Coordinate Projection & Base Map Loading + +Status: ready-for-dev + +## Story + +As the renderer, +I want a `MapBounds` dataclass and a `project()` function converting `(lat, lon)` to pixel `(x, y)`, and a basemap module that loads `background.png` into memory once, +So that all rendering uses consistent coordinates and the base map is always available without disk I/O in the loop. + +## Acceptance Criteria + +AC1: **Given** a `MapBounds` from home lat/lon and coverage radius **When** `project(lat, lon, bounds)` is called with the home location **Then** it returns pixel coordinates at the centre of the 800×480 display (±2px) + +AC2: **Given** `project()` is called with a position outside the map bounds **When** the result is used **Then** the returned pixel coordinate is outside display dimensions — no clamping, callers handle clipping + +AC3: **Given** `background.png` exists at `BACKGROUND_PATH` **When** `basemap.load()` is called **Then** it returns a `PIL.Image` (800×480) loaded into memory + +AC4: **Given** `background.png` does not exist at `BACKGROUND_PATH` **When** `basemap.load()` is called **Then** it raises `FileNotFoundError` (logged as ERROR by the caller) + +## Tasks / Subtasks + +- [ ] Task 1: Define `MapBounds` dataclass in `src/planemapper/renderer/projection.py` (AC: #1, #2) + - [ ] 1.1 Replace `# stub` with full implementation + - [ ] 1.2 Add imports: `from __future__ import annotations`, `from dataclasses import dataclass, field`, `import math` + - [ ] 1.3 Define `MapBounds` dataclass fields: `home_lat: float`, `home_lon: float`, `radius_nm: float`, `width: int = DISPLAY_WIDTH`, `height: int = DISPLAY_HEIGHT` + - [ ] 1.4 Import `DISPLAY_WIDTH` and `DISPLAY_HEIGHT` from `planemapper.constants` + +- [ ] Task 2: Implement `project()` in `src/planemapper/renderer/projection.py` (AC: #1, #2) + - [ ] 2.1 Signature: `def project(lat: float, lon: float, bounds: MapBounds) -> tuple[int, int]:` + - [ ] 2.2 Equirectangular linear mapping: map `(home_lat, home_lon)` to `(width//2, height//2)` + - [ ] 2.3 Scale: `deg_per_nm_lat = 1/60`; `deg_per_nm_lon = 1/(60 * math.cos(math.radians(bounds.home_lat)))` + - [ ] 2.4 Pixel scale: `px_per_nm_x = (bounds.width / 2) / bounds.radius_nm`; `px_per_nm_y = (bounds.height / 2) / bounds.radius_nm` + - [ ] 2.5 Convert: `x = bounds.width // 2 + int((lon - bounds.home_lon) / deg_per_nm_lon * px_per_nm_x)`; `y = bounds.height // 2 - int((lat - bounds.home_lat) / deg_per_nm_lat * px_per_nm_y)` (y-axis inverted — screen Y increases downward) + - [ ] 2.6 Return `(x, y)` + +- [ ] Task 3: Implement `basemap.load()` in `src/planemapper/renderer/basemap.py` (AC: #3, #4) + - [ ] 3.1 Replace `# stub` with full implementation + - [ ] 3.2 Add imports: `from PIL import Image`; `from planemapper.constants import BACKGROUND_PATH` + - [ ] 3.3 Signature: `def load() -> Image.Image:` + - [ ] 3.4 Open with `Image.open(BACKGROUND_PATH)`, call `.copy()` to force full load into memory (avoids lazy read) + - [ ] 3.5 Let `FileNotFoundError` propagate naturally — do NOT catch it + +- [ ] Task 4: Write tests in `tests/test_projection.py` (AC: #1, #2) + - [ ] 4.1 Replace the existing placeholder test (`def test_placeholder(): pass`) + - [ ] 4.2 Test AC1: Create `MapBounds(home_lat=53.0, home_lon=-6.0, radius_nm=100.0)`, call `project(53.0, -6.0, bounds)`, assert result is `(400, 240)` exactly (home maps to centre) + - [ ] 4.3 Test AC2: Call `project` with a point well outside bounds (e.g. 10 degrees away), assert returned pixel is outside display dimensions (< 0 or > 800 or > 480) + +- [ ] Task 5: Write tests in `tests/test_basemap.py` (AC: #3, #4) + - [ ] 5.1 Create `tests/test_basemap.py` + - [ ] 5.2 Test AC3: Create a real 800×480 PNG in `tmp_path`, monkeypatch `planemapper.renderer.basemap.BACKGROUND_PATH` to that path, call `basemap.load()`, assert returns `Image` of size `(800, 480)` + - [ ] 5.3 Test AC4: Monkeypatch `BACKGROUND_PATH` to a nonexistent path, call `basemap.load()`, assert `FileNotFoundError` is raised + +- [ ] Task 6: Run quality gates + - [ ] 6.1 `python -m pytest tests/` — all tests pass, 0 failures + - [ ] 6.2 `python -m ruff check .` — zero violations + - [ ] 6.3 `python -m ruff format --check .` — no formatting issues + +## Dev Notes + +### Critical Context + +**Module locations (both exist as `# stub`):** +- `src/planemapper/renderer/projection.py` — add `MapBounds` dataclass + `project()` function +- `src/planemapper/renderer/basemap.py` — add `load()` function + +**Constants already defined in `src/planemapper/constants.py`:** +```python +DISPLAY_WIDTH = 800 +DISPLAY_HEIGHT = 480 +BACKGROUND_PATH = Path("/etc/planemapper/background.png") +``` + +**Projection formula detail:** +The equirectangular projection maps a ~100nm radius around home to the full display. Latitude is simple (1 nm = 1/60 degree). Longitude must account for convergence at non-equatorial latitudes: `deg_per_nm_lon = 1 / (60 * cos(home_lat_radians))`. The y-axis is inverted because screen pixel Y increases downward while geographic latitude increases upward. + +**`MapBounds` default field values** use `DISPLAY_WIDTH` (800) and `DISPLAY_HEIGHT` (480) as defaults — these are module-level constants, safe to use as default values in a dataclass without `field(default_factory=...)`. + +**`basemap.load()` must force pixels into memory.** `PIL.Image.open()` is lazy by default — the file handle stays open and the pixel data is not read until accessed. Calling `.copy()` forces an immediate full decode and returns a new in-memory `Image`. Do not use `.load()` alone (it reads pixels but keeps the original file handle open). + +**`FileNotFoundError` from `basemap.load()`.** `PIL.Image.open()` raises `FileNotFoundError` naturally when the path does not exist. Do not add a try/except — the caller (the radar loop) is responsible for logging ERROR and handling the failure. + +**Coordinate convention:** internal code uses `(lat, lon)` order throughout — do not swap to `(lon, lat)`. + +**Existing test file:** `tests/test_projection.py` contains only `def test_placeholder(): pass` — replace it entirely; do not add alongside the placeholder. + +**No existing `tests/test_basemap.py`** — create this file from scratch. diff --git a/_bmad-output/implementation-artifacts/sprint-status.yaml b/_bmad-output/implementation-artifacts/sprint-status.yaml index 8600c2d..4e8c481 100644 --- a/_bmad-output/implementation-artifacts/sprint-status.yaml +++ b/_bmad-output/implementation-artifacts/sprint-status.yaml @@ -35,7 +35,7 @@ # - Dev moves story to 'review', then runs code-review (fresh context, different LLM recommended) generated: 2026-04-22 -last_updated: 2026-04-22 # 2-1 done, epic-2 in-progress +last_updated: 2026-04-22 # 2-1 done, 2-2 ready-for-dev, epic-2 in-progress project: planeMapper project_key: NOKEY tracking_system: file-system @@ -54,7 +54,7 @@ development_status: # Epic 2: Live Radar Display epic-2: in-progress 2-1-aircraft-data-model-and-fetcher: done - 2-2-coordinate-projection-and-base-map-loading: backlog + 2-2-coordinate-projection-and-base-map-loading: ready-for-dev 2-3-home-marker-and-airspace-outlines: backlog 2-4-altitude-colour-bands-and-aircraft-type-icons: backlog 2-5-per-aircraft-drawing: backlog