Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
19 commits
Select commit Hold shift + click to select a range
0e57bfe
docs: plan for issue 9
GeoBradDev Nov 8, 2026
31c3383
feat: add pure OurAirports CSV transform with RFC 4180 parser (#9)
GeoBradDev Nov 8, 2026
e63b856
feat: add data:airports script and commit pinned OurAirports snapshot…
GeoBradDev Nov 8, 2026
82cfcf3
feat: load airports from same-origin /data/airports.json (#9)
GeoBradDev Nov 8, 2026
8a25329
feat: size airport points in meters with pixel clamps (#9)
GeoBradDev Nov 8, 2026
8ae19a1
feat: draw and count large and medium airports, heatmap keeps all (#9)
GeoBradDev Nov 8, 2026
59ddecf
docs: describe the bundled airports snapshot and data:airports script…
GeoBradDev Nov 8, 2026
fe7e20f
docs: record issue 9 radius outcome and long task measurements in plan
GeoBradDev Nov 8, 2026
27fe045
test: add failing test for 5 px ports covering zoom 2 labels (#9)
GeoBradDev Nov 8, 2026
2be6d04
fix: size port points in meters with pixel clamps so zoom 2 labels st…
GeoBradDev Nov 8, 2026
384fe32
test: add failing tests for lax CSV quoting and empty snapshot guard …
GeoBradDev Nov 8, 2026
86fbc13
fix: make the CSV parser strict and refuse empty airport snapshots (#9)
GeoBradDev Nov 8, 2026
ed3b63e
test: add failing test for __proto__ input type lost from counts (#9)
GeoBradDev Nov 8, 2026
f19568d
fix: count every input type, including __proto__, in inputByType (#9)
GeoBradDev Nov 8, 2026
5d1b644
test: add failing test for build script main guard under a symlinked …
GeoBradDev Nov 8, 2026
660a600
fix: compare realpaths in the build script main guard (#9)
GeoBradDev Nov 8, 2026
401bd28
test: add failing tests for fetchedAt recorded as a bare UTC date (#9)
GeoBradDev Nov 8, 2026
d592ad9
fix: record the airports fetch time as a full UTC ISO timestamp (#9)
GeoBradDev Nov 8, 2026
2fab952
docs: describe clamped airport and port point sizes truthfully (#9)
GeoBradDev Nov 8, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 12 additions & 7 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,9 +7,9 @@ Built with React 19, Vite, MapLibre GL (through `react-map-gl`), deck.gl (`@deck
## What it does

- **Basemap:** CARTO dark-matter vector style rendered by MapLibre GL.
- **Airports layer:** every non-closed airport from the OurAirports CSV, drawn as amber points. Click a point to see its properties.
- **Sea ports layer:** the bundled ports GeoJSON, drawn as green points. Click a point to see its properties.
- **Heatmap layer (WebGPU only):** a two-pass compute shader bins airport positions into a 1024 x 512 grid and colorizes it into a bitmap overlay. It runs once, after the airports load. The layer toggle appears whenever WebGPU is present, with a status line: `AWAITING AIRPORTS`, `NO AIRPORT DATA` (the airports fetch failed, or the airports file loaded with 0 airports), `COMPUTING...`, `READY`, or `COMPUTE FAILED` with a `RETRY` button (thrown errors, asynchronous validation or out-of-memory errors, and device loss all count as failures). Without WebGPU the toggle is hidden and the panel says `WEBGPU UNAVAILABLE: HEATMAP AND COMPUTE BENCHMARK OFF`.
- **Airports layer:** large and medium airports (5,282) from the bundled OurAirports snapshot, drawn as amber points sized in meters and clamped to 1.5 to 8 px: at world zoom they all draw as small dots of the same size, and zoomed in, large airports draw larger than medium ones until both reach 8 px. The layer count is the number of points drawn. Click a point to see its properties.
- **Sea ports layer:** the bundled ports GeoJSON, drawn as green points sized in meters and clamped to 2 to 8 px, so they are small dots at world zoom and grow as you zoom in. Click a point to see its properties.
- **Heatmap layer (WebGPU only):** a two-pass compute shader bins all included airport positions (large, medium, and small: 48,072) into a 1024 x 512 grid and colorizes it into a bitmap overlay. It runs once, after the airports load. The layer toggle appears whenever WebGPU is present, with a status line: `AWAITING AIRPORTS`, `NO AIRPORT DATA` (the airports fetch failed, or the airports file loaded with 0 airports), `COMPUTING...`, `READY`, or `COMPUTE FAILED` with a `RETRY` button (thrown errors, asynchronous validation or out-of-memory errors, and device loss all count as failures). Without WebGPU the toggle is hidden and the panel says `WEBGPU UNAVAILABLE: HEATMAP AND COMPUTE BENCHMARK OFF`.
- **Load states:** each data layer shows `LOADING...`, its feature count, or `LOAD FAILED` with a `RETRY` button that refetches without reloading the page. The header shows `SYS LOADING`, `SYS NOMINAL`, or `SYS DEGRADED` (any failed layer, heatmap failure, missing WebGPU, failed or lost render device, or failed basemap; the list is in its tooltip and announced to screen readers). If the basemap style fails to load, the map area says `BASEMAP UNAVAILABLE` and the data layers still draw. If the map cannot be created at all (no usable WebGL2), it says `MAP UNAVAILABLE` / `WEBGL2 REQUIRED` and RENDER shows `Failed`.
- **Stress test:** a slider from 0 to 5,000,000 points in steps of 100,000. Points are generated on the main thread 150 ms after the slider stops moving, then drawn as a deck.gl binary attribute layer.
- **GPU info panel:** GPU name (the WebGPU adapter, or the WebGL renderer string when the adapter offers none; a long name is cut off with an ellipsis and shown in full on hover), RENDER: the backend deck.gl actually draws with (`WebGL2`, `WebGPU`, `Detecting...` until deck has created its device, `Failed` if deck could not create one, or `Lost` if the device was lost), active point count, frame time with a 60-frame sparkline, an on-demand WebGPU compute benchmark (press `RUN` next to WEBGPU COMPUTE: 5 sequential dispatches over a 64 MB storage buffer, reported as the median in GB/s, labelled `est.` because it is CPU timed, or `Too fast` when the timer is too coarse to measure it; out-of-memory, validation errors, and device loss show `Failed`; the buffer and device are freed when the run ends, and the run stops if the tab is hidden), and heatmap compute time. At 1024px wide or less it shows only RENDER, active point count, and frame time. On small screens (see below) it is hidden while a feature popup is open.
Expand All @@ -20,7 +20,7 @@ Built with React 19, Vite, MapLibre GL (through `react-map-gl`), deck.gl (`@deck
- **Node.js:** current LTS (CI uses `lts/*`). Vite 8 needs Node 20.19+ or 22.12+.
- **Browser:** any browser with WebGL 2 for the map and point layers. deck.gl draws through WebGL; WebGPU is used only for compute.
- **WebGPU (optional):** needed for the heatmap and the WEBGPU COMPUTE readout. Use a browser and GPU where `navigator.gpu.requestAdapter()` returns an adapter, for example current Chrome or Edge on desktop. Without it the app still runs: RENDER still shows `WebGL2` (deck.gl renders with WebGL either way), the heatmap toggle never appears (a note in the layer panel says so), the header shows `SYS DEGRADED`, and on screens wider than 1024px WEBGPU COMPUTE shows `--`.
- **Network access:** the basemap style and tiles come from CARTO and the airports CSV comes from GitHub at runtime. The ports data is bundled.
- **Network access:** the basemap style and tiles come from CARTO at runtime. The airports and ports data are bundled and served same-origin. `npm run data:airports` (optional, local only) fetches from GitHub.

## Setup from a clean clone

Expand All @@ -43,14 +43,15 @@ Open the URL Vite prints (default `http://localhost:5173`). No API keys or envir
| `npm run lint` | ESLint over the repo (`eslint.config.js`, includes `react-hooks` rules). |
| `npm test` | Run the Vitest suite once (jsdom). Includes a real `vite build` that checks the MapLibre worker is bundled. |
| `npm run test:watch` | Vitest in watch mode. |
| `npm run data:airports` | Rebuild `public/data/airports.json` and `airports.meta.json` from OurAirports at the pinned commit in `scripts/build-airports.mjs`. Needs network and Node 20+. Refuses to write when no airports are included and warns about upstream types it does not know. Not run in CI; commit the regenerated files. |

CI (`.github/workflows/ci.yml`) runs `npm ci`, `npm run lint`, `npm test`, `npm run build`, and `npm audit --omit=dev --audit-level=high` on pushes to `main` and on pull requests.
CI (`.github/workflows/ci.yml`) runs `npm ci`, `npm run lint`, `npm test`, `npm run build`, and `npm audit --omit=dev --audit-level=high` on pushes to `main` and on pull requests. It does not run `npm run data:airports` or fetch airport data.

## Data sources and licenses

| Data | Where it comes from | License |
| --- | --- | --- |
| Airports | [OurAirports](https://ourairports.com/data/) `airports.csv`, fetched at runtime from `https://raw.githubusercontent.com/davidmegginson/ourairports-data/main/airports.csv` (see `src/config/sources.js`). | Public domain. |
| Airports | `public/data/airports.json`, bundled and served at `/data/airports.json`. Built by `npm run data:airports` from [OurAirports](https://ourairports.com/data/) `airports.csv` at commit `64af12951161ed52bc733eb4101224643c48850a` of `davidmegginson/ourairports-data`, fetched 2026-11-08T05:00:09Z (UTC). Keeps `large_airport`, `medium_airport`, and `small_airport` rows with valid coordinates (rounded to 3 decimal places); drops `closed`, `heliport`, `seaplane_base`, `balloonport`, and any other type. 86,347 source rows, 48,072 kept; 1,967,855 bytes, about 624 KB gzip. Source URL, commit, fetch time (`fetchedAt`, ISO 8601 in UTC), and counts per type are in `public/data/airports.meta.json`. | Public domain. |
| Sea ports | `public/data/ports.geojson`, bundled with the app and served at `/data/ports.geojson`. The file is the Natural Earth `ne_10m_ports` dataset (1,081 points). | [Natural Earth](https://www.naturalearthdata.com/about/terms-of-use/) data is public domain. |
| Basemap | [CARTO](https://carto.com/basemaps) dark-matter GL style, `https://basemaps.cartocdn.com/gl/dark-matter-gl-style/style.json`, built from OpenStreetMap data. | Map data © [OpenStreetMap contributors](https://www.openstreetmap.org/copyright), ODbL. Map style and tiles © [CARTO](https://carto.com/attributions); use is subject to CARTO's basemap terms, which may require a license for commercial or high-volume use. The MapLibre attribution control shows the required credits; keep it visible. |

Expand All @@ -69,12 +70,16 @@ src/
status/systemStatus.js deriveSystemStatus(): the header's NOMINAL, LOADING, or DEGRADED and its issues
store/mapStore.js zustand store: viewport, layer visibility, stress count, selection,
render device and basemap health
data/airports.js decodeAirports() and selectMajorAirports() for the bundled airports file
public/data/ports.geojson bundled ports data
public/data/airports.json bundled airports data (generated), with airports.meta.json
scripts/ build-airports.mjs (npm run data:airports) and its pure CSV transform
```

## Known limitations

- The airports layer depends on GitHub raw being reachable. A failed fetch shows `LOAD FAILED` and can be retried.
- Airports are a snapshot of OurAirports at the pinned commit; they change only when `npm run data:airports` is rerun and the files are committed. A failed fetch of `/data/airports.json` shows `LOAD FAILED` and can be retried.
- Small airports are in the heatmap but are not drawn as points at any zoom, and heliports, seaplane bases, and balloonports are not included at all.
- The basemap needs CARTO to be reachable; offline, only the overlays draw. There is no basemap retry; reload the page. Tile errors after the style loads are not reported.
- The heatmap runs once per page load from the first non-empty airports list (again only after a failed run is retried) and does not update afterwards.
- Stress points are generated on the main thread. Large counts (millions of points) briefly block the UI once the slider settles.
Expand Down
Loading
Loading