Draw air quality on both globes from one retained station model

scripts/check-import-directions.mjs

@@ -35,6 +35,7 @@ const navaraPackage = /^(?:(?:three|postprocessing)(?:\/|$)|@navaramap\/)/;
 // Navara only in render/navara*.js. The list grows with each moved layer.
 const RENDERED_LAYER_DIRS = [
   'src/layers/alpr/',
+  'src/layers/airQuality/',
   'src/layers/radio/',
   'src/layers/bikeshare/',
   'src/layers/earthquakes/',

scripts/package-boundaries.json

@@ -3452,6 +3452,7 @@
       "src/data/geoImportImages.js",
       "src/app/layers/airQuality.js",
       "src/layers/airQuality/index.js",
+      "src/layers/airQuality/render/cesium.js",
       "src/layers/airQuality/model.js",
       "src/layers/airQuality/source.js",
       "src/ui/statusText.js",
@@ -3655,6 +3656,7 @@
       "src/layers/satellites/render/cesium.js",
       "src/layers/earthquakes/render/cesium.js",
       "src/layers/earthquakes/render/navara.js",
+      "src/layers/airQuality/render/navara.js",
       "src/layers/earthquakes/render/navaraGeometry.js",
       "src/layers/earthquakes/render/navaraGrid.js",
       "src/layers/installations/render/navara.js",
@@ -4266,6 +4268,7 @@
       "src/data/cameraFraming.js",
       "src/app/layers/airQuality.js",
       "src/layers/airQuality/index.js",
+      "src/layers/airQuality/render/cesium.js",
       "src/layers/airQuality/model.js",
       "src/layers/airQuality/source.js",
       "src/ui/statusText.js",
@@ -5508,7 +5511,13 @@
   "air-quality": {
     "exports": ["./layers/air-quality"],
     "modules": [
+      "src/geo/cartesian3.js",
+      "src/geo/check.js",
+      "src/geo/debug.js",
+      "src/geo/developerError.js",
+      "src/geo/math.js",
       "src/layers/airQuality/index.js",
+      "src/layers/airQuality/render/cesium.js",
       "src/layers/airQuality/model.js",
       "src/layers/airQuality/source.js",
       "src/sources/httpBody.js",

scripts/qa-air-quality-switch.mjs

@@ -0,0 +1,138 @@
+import puppeteer from 'puppeteer';
+import sharp from 'sharp';
+import assert from 'node:assert/strict';
+import { blockPaidQaMaps } from './qa-map-policy.mjs';
+
+const base = new URL(process.argv[2]);
+if (
+  !['localhost', '127.0.0.1'].includes(base.hostname) ||
+  ['', '4173', '4185', '4186', '4187', '4188', '4189', '4194'].includes(
+    base.port,
+  )
+)
+  throw new Error('Supply an unreserved local keyless preview URL');
+base.search = '?engine=navara&welcome=0&look=cinematic';
+base.hash =
+  'v=2&lat=43.6500&lon=-79.3800&alt=46000&heading=0&pitch=-90&roll=0&map=sentinel2&l=4';
+const b = await puppeteer.launch({
+  headless: true,
+  args: ['--use-angle=metal', '--enable-gpu'],
+});
+try {
+  const p = await b.newPage();
+  await blockPaidQaMaps(p);
+  await p.setViewport({ width: 1024, height: 768 });
+  const errors = [];
+  p.on('pageerror', (e) => {
+    errors.push(e.message);
+    console.log('error', e.message.split('?')[0]);
+  });
+  await p.evaluateOnNewDocument(() => {
+    const fetch = window.fetch.bind(window);
+    window.fetch = (input, o) => {
+      const url = new URL(input.url ?? input, document.baseURI);
+      if (url.hostname === 'api.weather.gc.ca') {
+        const records = url.pathname.includes('aqhi-stations')
+          ? [
+              {
+                geometry: { type: 'Point', coordinates: [-79.38, 43.65] },
+                properties: {
+                  location_id: 'QA1',
+                  location_name_en: 'QA Toronto',
+                },
+              },
+            ]
+          : [
+              {
+                properties: {
+                  location_id: 'QA1',
+                  aqhi: 9,
+                  observation_datetime: new Date().toISOString(),
+                },
+              },
+            ];
+        return Promise.resolve(
+          Response.json({
+            type: 'FeatureCollection',
+            features: records.map((f) => ({ type: 'Feature', ...f })),
+          }),
+        );
+      }
+      return fetch(input, o);
+    };
+  });
+  await p.goto(base.href);
+  const ready = async (kind) => {
+    await p.waitForFunction(
+      (k) =>
+        window.__godsEyeView?.engine.kind === k &&
+        !document.querySelector('#globe-engine')?.disabled &&
+        !document.querySelector('.engine-switch-frame') &&
+        document.querySelector('#loading-screen.hidden'),
+      { timeout: 90000 },
+      kind,
+    );
+    await p.evaluate(
+      () => window.__godsEyeView.styleManager.initialRestorePromise,
+    );
+  };
+  const capture = async (visible) => {
+    await p.evaluate(async (show) => {
+      const d = window.__godsEyeView;
+      await d.dataManager.setEnabled('air-quality', show, { origin: 'user' });
+      d.engine.render.request('qa-air-quality');
+    }, visible);
+    await new Promise((r) => setTimeout(r, 3900));
+    const shot = await p.screenshot();
+    return sharp(shot)
+      .extract({ left: 537, top: 403, width: 22, height: 18 })
+      .removeAlpha()
+      .png()
+      .toBuffer()
+      .then((buf) => sharp(buf).stats());
+  };
+  await ready('navara');
+  await p.evaluate(() => {
+    const d = window.__godsEyeView;
+    if (d.tileset || window.__GOOGLE_MAPS_API_KEY__)
+      throw Error('Keyless required');
+    window.qaAir = d.dataManager.layers.get('air-quality').module;
+  });
+  for (const kind of ['navara', 'cesium', 'navara']) {
+    if ((await p.evaluate(() => window.__godsEyeView.engine.kind)) !== kind) {
+      await p.select('#globe-engine', kind);
+      await ready(kind);
+      const same = await p.evaluate(
+        () =>
+          window.__godsEyeView.dataManager.layers.get('air-quality').module ===
+          window.qaAir,
+      );
+      assert.ok(same);
+    }
+    const off = await capture(false),
+      on = await capture(true);
+    const values = await p.evaluate(() => ({
+      records: window.qaAir.getAnalystRecords(),
+      card: window.qaAir.getRowControls().list.items,
+      stats: window.qaAir.getStats(),
+    })); // An interior patch away from the label must take on the high-risk orange.
+    const orange = (v) => v.channels[0].mean - v.channels[2].mean;
+    assert.ok(
+      orange(on) > orange(off) + 5,
+      kind + ' must draw the station footprint',
+    );
+    console.log(
+      'PASS',
+      kind,
+      values.records[0].id,
+      'AQHI',
+      values.records[0].value,
+    );
+    assert.equal(values.records[0].name, 'QA Toronto');
+    assert.equal(values.records[0].value, 9);
+    assert.equal(values.card.length, 1);
+  }
+  assert.deepEqual(errors, []);
+} finally {
+  await b.close();
+}

src/app/constructCatalog.js

@@ -184,7 +184,7 @@ export function createApplicationCatalog({
       ],
       [
         'air-quality',
-        () => createApplicationAirQuality({ source: sources['air-quality'] }),
+        () => sessionModel('air-quality', () => createApplicationAirQuality({ source: sources['air-quality'] })),
       ],
       [
         'fire-perimeters',

src/app/layers/airQuality.js

@@ -1,6 +1,15 @@
+import { rendererFor } from './renderers.js';
+import { createAirQualityCesiumRenderer } from '../../layers/airQuality/render/cesium.js';
 import { createAirQualityLayer } from '../../layers/airQuality/index.js';
 import { overlayHost } from './overlayHost.js';
 /** Wire air-quality readings to the application overlay host. */
 export function createApplicationAirQuality(options) {
-  return createAirQualityLayer({ overlayHost, ...options });
+  return createAirQualityLayer({
+    overlayHost,
+    createRenderer: ({ viewer, engine }) =>
+      engine
+        ? rendererFor('air-quality', engine, { viewer })
+        : createAirQualityCesiumRenderer({ viewer }),
+    ...options,
+  });
 }

src/app/layers/renderers.js

@@ -1,3 +1,4 @@
+import { createAirQualityCesiumRenderer } from '../../layers/airQuality/render/cesium.js';
 import { createFirmsCesiumRenderer } from '../../layers/firms/render/cesium.js';
 import { createEarthquakesCesiumRenderer } from '../../layers/earthquakes/render/cesium.js';
 import { createLaunchesCesiumRenderer } from '../../layers/launches/render/cesium.js';
@@ -92,6 +93,7 @@ export const layerAvailableOn = (layerId, engineKind) =>
 /** Cesium renderers extracted from their layers (render/cesium.js). */
 export const CESIUM_LAYER_RENDERERS = Object.freeze({
   earthquakes: createEarthquakesCesiumRenderer,
+  'air-quality': (_engine, options) => createAirQualityCesiumRenderer(options),
   'local-firms': createFirmsCesiumRenderer,
   'rocket-launches': createLaunchesCesiumRenderer,
   satellites: createSatellitesCesiumRenderer,

src/app/layers/renderers.test.mjs

@@ -59,6 +59,7 @@ test('the default registry: every layer on Cesium, none yet on Navara', () => {
 test('the aircraft, vessels, satellites, launches and earthquakes have extracted Cesium renderers', () => {
   assert.deepEqual(Object.keys(CESIUM_LAYER_RENDERERS), [
     'earthquakes',
+    'air-quality',
     'local-firms',
     'rocket-launches',
     'satellites',

src/app/navaraLayers.test.mjs

@@ -25,6 +25,7 @@ test('the Navara mode registers migrated renderers once', async () => {
     'satellites',
     'ais-live-vessels',
     'earthquakes',
+    'air-quality',
     'local-firms',
     'military-installations',
     'bikeshare',
@@ -44,6 +45,7 @@ test('the Navara mode registers migrated renderers once', async () => {
       'military',
       'local-adsb',
       'earthquakes',
+      'air-quality',
       'alpr-cameras',
       'satellites',
       'rocket-launches',

src/app/navaraMode.js

@@ -56,6 +56,7 @@ const NAVARA_CREDIT_KEYS = new Set([
   'celestrak',
   'launch-library-2',
   'usgs',
+  'eccc-aqhi',
   'firms',
   'gbfs',
   'overture-military-names',
@@ -122,6 +123,11 @@ export async function registerNavaraLayerRenderers() {
           ...navaraViews.get(engine),
         });
     },
+    'air-quality': async () => {
+      const { createAirQualityNavaraRenderer } =
+        await import('../layers/airQuality/render/navara.js');
+      return (engine) => createAirQualityNavaraRenderer(engine, navaraViews.get(engine));
+    },
     earthquakes: async () => {
       const { createEarthquakesNavaraRenderer } =
         await import('../layers/earthquakes/render/navara.js');

src/app/navaraScene.test.mjs

@@ -182,6 +182,7 @@ test('Navara keeps attribution for every available W1/W2 source and excludes una
     'celestrak',
     'launch-library-2',
     'usgs',
+    'eccc-aqhi',
     'firms',
     'gbfs',
     'overture-military-names',

src/layers/airQuality/index.js

@@ -1,4 +1,6 @@
-import * as Cesium from 'cesium';
+import { fromDegrees } from '../../geo/cartesian3.js';
+import { toDegrees } from '../../geo/math.js';
+import { createAirQualityCesiumRenderer } from './render/cesium.js';
 import { msg, t, tn } from '../../i18n/index.js';
 import { translateFeedError } from '../../ui/statusText.js';
 import {
@@ -23,13 +25,13 @@ const STATION_MARKER_RADIUS_M = 6_000;
 const READOUT_LIMIT = 5;
 
 /** Own one air-quality display, its refresh lifecycle, and its readout card. */
-export function createAirQualityLayer({ source, overlayHost } = {}) {
+export function createAirQualityLayer({ source, overlayHost, createRenderer = createAirQualityCesiumRenderer } = {}) {
   if (typeof source?.getSnapshot !== 'function')
     throw new TypeError('Air quality requires a snapshot source');
   if (!overlayHost) throw new TypeError('Air quality requires an overlay host');
-  let _viewer = null;
+  let initialized = false;
   let _request = null;
-  let _dataSource = null;
+  let renderer = null;
   let _readings = [];
   let _count = 0;
   let _lastUpdate = null;
@@ -41,14 +43,13 @@ export function createAirQualityLayer({ source, overlayHost } = {}) {
 
   /** The camera's lon/lat rectangle in degrees, or null when unresolvable. */
   const viewRectangle = () => {
-    const rectangle = _viewer?.camera?.computeViewRectangle?.();
+    const rectangle = renderer?.viewRectangle();
     if (!rectangle) return null;
-    const toDeg = Cesium.Math.toDegrees;
     return {
-      west: toDeg(rectangle.west),
-      south: toDeg(rectangle.south),
-      east: toDeg(rectangle.east),
-      north: toDeg(rectangle.north),
+      west: toDegrees(rectangle.west),
+      south: toDegrees(rectangle.south),
+      east: toDegrees(rectangle.east),
+      north: toDegrees(rectangle.north),
     };
   };
 
@@ -59,23 +60,35 @@ export function createAirQualityLayer({ source, overlayHost } = {}) {
     source: 'ECCC MSC GeoMet',
     updateInterval: 1_200_000,
 
-    init(viewer) {
-      if (_viewer) throw new Error('Air quality layer is already initialized');
-      _viewer = viewer;
-      _dataSource = new Cesium.CustomDataSource('air-quality');
-      _dataSource.show = false;
-      viewer.dataSources.add(_dataSource);
-      _readings = [];
-      _count = 0;
-      _lastUpdate = null;
-      _lastError = null;
-      _enabled = false;
+    init(viewer, { engine = null } = {}) {
+      if (initialized) throw new Error('Air quality layer is already initialized');
+      initialized = true;
+      try {
+        if (viewer || engine) this.attachRenderer(viewer, { engine });
+      } catch (error) {
+        this.destroy();
+        throw error;
+      }
+    },
+
+    attachRenderer(viewer, { engine = null } = {}) {
+      if (!initialized || renderer) throw new Error('Invalid air quality scene attachment');
+      renderer = createRenderer({ viewer, engine });
+      renderer.setVisible(_enabled);
+      overlayHost.setVisible(AIR_QUALITY_OVERLAY_SOURCE_ID, _enabled);
+      if (_readings.length) this._render();
+    },
+
+    detachRenderer() {
+      overlayHost.clearSource(AIR_QUALITY_OVERLAY_SOURCE_ID);
       overlayHost.setVisible(AIR_QUALITY_OVERLAY_SOURCE_ID, false);
+      renderer?.destroy();
+      renderer = null;
     },
 
     enable() {
       _enabled = true;
-      if (_dataSource) _dataSource.show = true;
+      renderer?.setVisible(true);
       overlayHost.setVisible(AIR_QUALITY_OVERLAY_SOURCE_ID, true);
       notify();
     },
@@ -85,14 +98,14 @@ export function createAirQualityLayer({ source, overlayHost } = {}) {
       _request?.abort();
       _request = null;
       _enabled = false;
-      if (_dataSource) _dataSource.show = false;
+      renderer?.setVisible(false);
       overlayHost.clearSource(AIR_QUALITY_OVERLAY_SOURCE_ID);
       overlayHost.setVisible(AIR_QUALITY_OVERLAY_SOURCE_ID, false);
       notify();
     },
 
     async update() {
-      if (!_enabled || !_dataSource) return false;
+      if (!_enabled) return false;
       _request?.abort();
       const request = new AbortController();
       _request = request;
@@ -122,45 +135,11 @@ export function createAirQualityLayer({ source, overlayHost } = {}) {
 
     /** Rebuild entities and overlay labels from the current readings. */
     _render() {
-      if (!_dataSource) return;
-      _dataSource.entities.removeAll();
+      if (!renderer) return;
+      renderer.replace(_readings, STATION_MARKER_RADIUS_M);
       const overlayEntries = [];
       for (const reading of _readings) {
-        const position = Cesium.Cartesian3.fromDegrees(
-          reading.lon,
-          reading.lat,
-        );
-        const color = Cesium.Color.fromCssColorString(reading.color);
-        _dataSource.entities.add(
-          new Cesium.Entity({
-            id: `air-quality:${reading.id}`,
-            position,
-            ellipse: {
-              // Static axes, as in the earthquake layer: a per-frame axis
-              // re-tessellates the clamped ground primitive every frame.
-              semiMajorAxis: STATION_MARKER_RADIUS_M,
-              semiMinorAxis: STATION_MARKER_RADIUS_M,
-              material: new Cesium.ColorMaterialProperty(color.withAlpha(0.35)),
-              outline: true,
-              outlineColor: color.withAlpha(0.9),
-              outlineWidth: 2,
-              heightReference: Cesium.HeightReference.CLAMP_TO_GROUND,
-            },
-            properties: {
-              provider: reading.provider,
-              scale: reading.scale,
-              value: reading.value,
-              band: reading.band,
-              name: reading.name,
-              zone: reading.zone,
-              risk: reading.risk,
-              observedMs: reading.observedMs,
-              note: reading.note,
-              lat: reading.lat,
-              lon: reading.lon,
-            },
-          }),
-        );
+        const position = fromDegrees(reading.lon, reading.lat);
         overlayEntries.push(
           createAirQualityOverlayEntry({
             id: reading.id,
@@ -184,17 +163,12 @@ export function createAirQualityLayer({ source, overlayHost } = {}) {
       }
     },
 
-    destroy(viewer = _viewer) {
+    destroy() {
       _request?.abort();
       _request = null;
       _enabled = false;
-      overlayHost.clearSource(AIR_QUALITY_OVERLAY_SOURCE_ID);
-      overlayHost.setVisible(AIR_QUALITY_OVERLAY_SOURCE_ID, false);
-      if (_dataSource) {
-        viewer?.dataSources?.remove(_dataSource, true);
-        _dataSource = null;
-      }
-      _viewer = null;
+      initialized = false;
+      this.detachRenderer();
       _readings = [];
       _count = 0;
       _lastUpdate = null;

src/layers/airQuality/ownership.test.mjs

@@ -273,3 +273,24 @@ test('a failed refresh over good readings reports degraded, not nominal', async
     'showing old data after a failure is degraded',
   );
 });
+
+test('station data stays queryable and attaches to a fresh scene without polling', async () => {
+  let polls = 0;
+  const h = harness({ getSnapshot: async () => {
+    polls++;
+    return [reading('Toronto', 7)];
+  } });
+  try {
+    h.layer.detachRenderer();
+    assert.equal(h.sources.length, 0);
+    assert.equal(await h.layer.update(), true);
+    assert.equal(h.events.length, 0);
+    assert.equal(h.layer.getAnalystRecords()[0].value, 7);
+    h.layer.attachRenderer(h.viewer);
+    assert.equal(h.events.at(-1)[0], 'air-quality');
+    assert.equal(h.sources[0].entities.values.length, 1);
+    assert.equal(polls, 1);
+  } finally {
+    h.layer.destroy();
+  }
+});

src/layers/airQuality/render/cesium.js

@@ -0,0 +1,56 @@
+import * as Cesium from 'cesium';
+
+export function createAirQualityCesiumRenderer({ viewer }) {
+  const dataSource = new Cesium.CustomDataSource('air-quality');
+  dataSource.show = false;
+  viewer.dataSources.add(dataSource);
+  return {
+    viewRectangle: () => viewer.camera?.computeViewRectangle?.(),
+    setVisible(visible) {
+      dataSource.show = visible;
+    },
+    replace(readings, radius) {
+      dataSource.entities.removeAll();
+      for (const reading of readings) {
+        const position = Cesium.Cartesian3.fromDegrees(
+          reading.lon,
+          reading.lat,
+        );
+        const color = Cesium.Color.fromCssColorString(reading.color);
+        dataSource.entities.add(
+          new Cesium.Entity({
+            id: `air-quality:${reading.id}`,
+            position,
+            ellipse: {
+              // Static axes, as in the earthquake layer: a per-frame axis
+              // re-tessellates the clamped ground primitive every frame.
+              semiMajorAxis: radius,
+              semiMinorAxis: radius,
+              material: new Cesium.ColorMaterialProperty(color.withAlpha(0.35)),
+              outline: true,
+              outlineColor: color.withAlpha(0.9),
+              outlineWidth: 2,
+              heightReference: Cesium.HeightReference.CLAMP_TO_GROUND,
+            },
+            properties: {
+              provider: reading.provider,
+              scale: reading.scale,
+              value: reading.value,
+              band: reading.band,
+              name: reading.name,
+              zone: reading.zone,
+              risk: reading.risk,
+              observedMs: reading.observedMs,
+              note: reading.note,
+              lat: reading.lat,
+              lon: reading.lon,
+            },
+          }),
+        );
+      }
+    },
+    destroy() {
+      viewer.dataSources.remove(dataSource, true);
+    },
+  };
+}

src/layers/airQuality/render/navara.js

@@ -0,0 +1,100 @@
+import * as geo from '../../../geo/index.js';
+
+function stationFeature(reading, radius) {
+  const origin = geo.cartesian3.fromDegrees(reading.lon, reading.lat);
+  const frame = geo.transforms.eastNorthUpToFixedFrame(origin);
+  const ring = [];
+  for (let i = 0; i < 48; i++) {
+    const angle = (i * 2 * Math.PI) / 48;
+    const local = geo.cartesian3.create(
+      radius * Math.cos(angle),
+      radius * Math.sin(angle),
+      0,
+    );
+    const world = geo.matrix4.multiplyByPoint(
+      frame,
+      local,
+      geo.cartesian3.create(),
+    );
+    const point = geo.cartographic.fromCartesian(world);
+    ring.push([
+      geo.math.toDegrees(point.longitude),
+      geo.math.toDegrees(point.latitude),
+    ]);
+  }
+  ring.push(ring[0]);
+  return {
+    type: 'Feature',
+    id: `air-quality:${reading.id}`,
+    properties: { ...reading },
+    geometry: { type: 'Polygon', coordinates: [ring] },
+  };
+}
+
+/** One native GeoJSON layer per AQHI colour, independent of station count. */
+export function createAirQualityNavaraRenderer(engine, { view }) {
+  let visible = false;
+  let batches = [];
+  function release(items) {
+    for (const { layer, source } of items) {
+      layer?.delete();
+      source.delete();
+    }
+  }
+  return {
+    viewRectangle: () => engine.camera.viewRectangle(),
+    setVisible(show) {
+      if (visible === show) return;
+      visible = show;
+      for (const { layer, source, paint } of batches) {
+        layer.update({ type: 'vector', source, polygon: { ...paint, show } });
+      }
+      engine.render.request('air-quality-visibility');
+    },
+    replace(rows, radius) {
+      const groups = new Map();
+      for (const row of rows) {
+        if (!groups.has(row.color)) groups.set(row.color, []);
+        groups.get(row.color).push(stationFeature(row, radius));
+      }
+      const next = [];
+      try {
+        for (const [css, features] of groups) {
+          const color = Number.parseInt(css.slice(1), 16);
+          const paint = {
+            color,
+            transparent: true,
+            opacity: 0.35,
+            clampToGround: true,
+            outline: true,
+            outlineShow: true,
+            outlineColor: color,
+            outlineWidth: 2,
+          };
+          const source = view.addSource({
+            type: 'geojson',
+            data: { type: 'FeatureCollection', features },
+          });
+          const batch = { source, paint };
+          next.push(batch);
+          batch.layer = view.addLayer({
+            type: 'vector',
+            source,
+            polygon: { ...paint, show: visible },
+          });
+        }
+      } catch (error) {
+        release(next);
+        throw error;
+      }
+      release(batches);
+      batches = next;
+      engine.render.request('air-quality-readings');
+    },
+    destroy() {
+      release(batches);
+      batches = [];
+      engine.render.request('air-quality-destroy');
+    },
+  };
+}