Skip to content

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

WebGPU Groundtruth

A browser map that renders global airports and sea ports over a dark vector basemap and uses WebGPU compute shaders for an airport density heatmap and an on-demand GPU throughput benchmark. A stress-test slider adds up to 5,000,000 random points so you can watch frame time under load.

Built with React 19, Vite, MapLibre GL (through react-map-gl), deck.gl (@deck.gl/mapbox overlay with ScatterplotLayer and BitmapLayer), and zustand for UI state.

What it does

  • Basemap: CARTO dark-matter vector style rendered by MapLibre GL.
  • 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.
  • Small screens (640px wide or less, or up to 1024px wide and 500px tall or less): the layer panel starts collapsed behind a "Sensor layers" button (it shows <n> FAILED when a layer has failed), the header drops the coordinates and hides the status visually (screen readers still hear it), and the feature popup opens as a bottom sheet.

Requirements

  • 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 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

git clone https://github.com/GeoBradDev/WebGPU-Example.git
cd WebGPU-Example
npm ci
npm run dev

Open the URL Vite prints (default http://localhost:5173). No API keys or environment variables are needed.

Scripts

Command What it does
npm run dev Start the Vite dev server with hot reload.
npm run build Production build into dist/.
npm run preview Serve the built dist/ locally (default port 4173).
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. It does not run npm run data:airports or fetch airport data.

Data sources and licenses

Data Where it comes from License
Airports public/data/airports.json, bundled and served at /data/airports.json. Built by npm run data:airports from OurAirports 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 data is public domain.
Basemap CARTO dark-matter GL style, https://basemaps.cartocdn.com/gl/dark-matter-gl-style/style.json, built from OpenStreetMap data. Map data © OpenStreetMap contributors, ODbL. Map style and tiles © CARTO; 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.

Note: the comment in src/config/sources.js and the parser in src/hooks/usePorts.js refer to the NGA World Port Index (PORT_NAME), but the bundled file is Natural Earth and uses name. The parser falls back to name, so labels still work.

Project layout

src/
  App.jsx                 header, layout, wires hooks to the map
  components/             MapView (MapLibre + deck.gl), LayerPanel, GPUInfoPanel, FeaturePopup
  config/                 data URLs, layer ids, basemap style, MapLibre worker setup
  hooks/                  data loading (useAirports, usePorts), WebGPU (useGPUCapabilities,
                          useGPUCompute, useGPUHeatmap), useStressPoints, useMediaQuery
  layers/index.js         buildLayers(): visibility and data to deck.gl layers
  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

  • 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.
  • The WEBGPU COMPUTE benchmark is CPU timed (submit to onSubmittedWorkDone), so it includes driver and callback latency and reads lower than the real memory bandwidth. The RUN control is hidden at 1024px wide or less along with the rest of WEBGPU COMPUTE.
  • RENDER is set when deck.gl reports the device it created, and changes afterwards only to Lost when that device is lost. A deck that never reports a device or an error leaves RENDER at Detecting... and the header at SYS LOADING.
  • Unit tests run in jsdom, which has no WebGL or WebGPU. GPU code paths are covered by mocks and pure helpers only; check rendering in a real browser.

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages