Skip to content

A spy satellite simulator in your browser, except the data is real. Live open source spatial intelligence on a photorealistic 3D globe.

26.4 KB
Raw Blame
import {
  createShellSurface,
  WEATHER_SHELL_HEIGHTS,
} from '../weather/shellRendering.js';
import { createWindRelief } from './relief.js';
import { orderWeatherImagery } from '../weather/imageryOrder.js';
import { NO_IMAGERY_HOST } from '../weather/imageryHost.js';
import { msg } from '../../i18n/index.js';
import { createWindGpuRendering } from './gpuRendering.js';
import { advectParticle, sampleWind } from './model.js';
import {
  createFieldRaster,
  SCALAR_UNAVAILABLE,
  trailEraseAlpha,
  windTrailColor,
} from './fields.js';

// English for diagnostics; the row status shows it translated (index.js). The
// scalar texts are the source's own; setOptions accepts only these overlays.
const FIELD_UNAVAILABLE = Object.freeze({
  speed: msg('Wind speed field unavailable'),
  ...SCALAR_UNAVAILABLE,
});

/** English status for a scalar overlay with no drawable field. */
export function fieldUnavailableText(overlay) {
  return Object.hasOwn(FIELD_UNAVAILABLE, overlay)
    ? FIELD_UNAVAILABLE[overlay]
    : null;
}
const WIND_FIELD_FADE_HIGH_METERS = 1_200_000;
const WIND_FIELD_FADE_LOW_METERS = 200_000;
const WIND_FIELD_LOG_RANGE = Math.log(
  WIND_FIELD_FADE_HIGH_METERS / WIND_FIELD_FADE_LOW_METERS,
);

// Snapshots own immutable decoded arrays. Compare their contents, not grid URLs
// (which include the scalar overlay) or only cycle IDs (which can be revised).
// This bounded scan runs on acquisition, never in the animation loop.
function sameWind(previous, next, previousField, nextField) {
  if (!previous || !next || !previousField || !nextField) return false;
  for (const key of ['model', 'level', 'units'])
    if (previous[key] !== next[key]) return false;
  for (const key of ['runIso', 'validIso', 'forecastHour', 'date', 'hour'])
    if (previous.cycle?.[key] !== next.cycle?.[key]) return false;
  for (const key of ['nx', 'ny', 'lo1', 'la1', 'dx', 'dy'])
    if (previousField[key] !== nextField[key]) return false;
  for (const key of ['u', 'v']) {
    const before = previousField[key];
    const after = nextField[key];
    if (!before || !after || before.length !== after.length) return false;
    if (before === after) continue;
    for (let i = 0; i < before.length; i++)
      if (before[i] !== after[i]) return false;
  }
  return true;
}

/** Globe-projected surface flow plus one owned, static colour field: globe
 * imagery on the globe host, a raised shell on the 3D Tiles host. */
export function createWindRendering({
  cesium,
  container,
  getViewer,
  getHost = () => ({
    collection:
      getViewer?.()?.imageryLayers ?? getViewer?.()?.scene?.imageryLayers,
    kind: 'globe',
  }),
  eventTarget = globalThis.window,
  createGpuRendering = createWindGpuRendering,
  onStatusChange,
} = {}) {
  let canvas = null;
  let context = null;
  let snapshot = null;
  let field = null;
  let particles = [];
  let frame = null;
  let running = false;
  let lastTime = null;
  let cssWidth = 1;
  let cssHeight = 1;
  let warned = false;
  let overlay = 'none';
  let paused = false;
  let reducedMotion = false;
  let imagery = null;
  let shell = null;
  let imageryCollection = null;
  let imageryKind = null;
  let imageryError = null;
  let imageryErrorRemove = null;
  let media = null;
  let removers = [];
  let bounds = null;
  let cameraChanged = true;
  let painted = 0;
  const gpu = createGpuRendering({ cesium, getViewer });
  let gpuActive = false;
  let gpuVisible = false;
  let reportedGpuReady = null;
  let gpuNarrow = false;
  let flowTime = 0;
  const relief = createWindRelief({ cesium, getViewer });
  const signature = Array(8).fill(null);
  const wind = { u: 0, v: 0 };
  const before = { lon: 0, lat: 0 };
  const world =
    typeof cesium.Cartesian3 === 'function' ? new cesium.Cartesian3() : {};
  const screenA =
    typeof cesium.Cartesian2 === 'function' ? new cesium.Cartesian2() : {};
  const screenB =
    typeof cesium.Cartesian2 === 'function' ? new cesium.Cartesian2() : {};
  const degree = Math.PI / 180;
  const hidden = () => globalThis.document?.hidden === true;
  const still = () => paused || reducedMotion;
  const budget = () =>
    Math.max(
      200,
      Math.min(
        cssWidth < 600 ? 1000 : 3000,
        Math.floor((cssWidth * cssHeight) / 420),
      ),
    );
  const viewerReady = () => {
    const viewer = getViewer?.();
    return viewer && !viewer.isDestroyed?.() ? viewer : null;
  };

  function cancel() {
    if (frame !== null) globalThis.cancelAnimationFrame(frame);
    frame = null;
  }
  function schedule() {
    if (
      running &&
      field &&
      canvas &&
      !hidden() &&
      !still() &&
      (!gpuActive || gpuVisible) &&
      frame === null
    )
      frame = globalThis.requestAnimationFrame(draw);
  }
  function clearPixels() {
    context?.clearRect(0, 0, cssWidth, cssHeight);
  }

  function resize(viewer) {
    const ratio = Math.min(2, globalThis.devicePixelRatio || 1);
    cssWidth =
      viewer?.scene?.canvas?.clientWidth || container?.clientWidth || 1;
    cssHeight =
      viewer?.scene?.canvas?.clientHeight || container?.clientHeight || 1;
    const width = Math.max(1, Math.floor(cssWidth * ratio));
    const height = Math.max(1, Math.floor(cssHeight * ratio));
    // Assigning even unchanged dimensions erases a real canvas.
    if (canvas.width === width && canvas.height === height) return false;
    canvas.width = width;
    canvas.height = height;
    canvas.style.width = `${cssWidth}px`;
    canvas.style.height = `${cssHeight}px`;
    context.setTransform?.(ratio, 0, 0, ratio, 0, 0);
    return true;
  }

  function checkCamera(scene) {
    const camera = scene.camera;
    const position = camera?.positionWC;
    const values = [
      position?.x,
      position?.y,
      position?.z,
      camera?.heading,
      camera?.pitch,
      camera?.roll,
      cssWidth,
      cssHeight,
    ];
    let changed = false;
    for (let i = 0; i < values.length; i++) {
      if (values[i] !== signature[i]) changed = true;
      signature[i] = values[i];
    }
    return changed;
  }

  function updateBounds(scene) {
    bounds = null;
    if (!scene.camera?.computeViewRectangle || !cesium.Ellipsoid) return;
    try {
      const rect = scene.camera.computeViewRectangle(cesium.Ellipsoid.WGS84);
      if (!rect) return;
      const west = rect.west / degree;
      let east = rect.east / degree;
      const south = Math.max(-89, rect.south / degree);
      const north = Math.min(89, rect.north / degree);
      if (east < west) east += 360;
      if (
        [west, east, south, north].every(Number.isFinite) &&
        east > west &&
        north > south
      )
        bounds = {
          west,
          east,
          sinSouth: Math.sin(south * degree),
          sinNorth: Math.sin(north * degree),
        };
    } catch {
      /* A sky-facing camera can have no earth rectangle. */
    }
  }

  function makeOccluder(scene) {
    if (
      !cesium.EllipsoidalOccluder ||
      !cesium.Ellipsoid ||
      !scene.camera?.positionWC
    )
      return null;
    return new cesium.EllipsoidalOccluder(
      cesium.Ellipsoid.WGS84,
      scene.camera.positionWC,
    );
  }

  function project(scene, occluder, lon, lat, result) {
    if (!Number.isFinite(lon) || !Number.isFinite(lat)) return null;
    const point = cesium.Cartesian3.fromDegrees(
      lon,
      lat,
      0,
      cesium.Ellipsoid?.WGS84,
      world,
    );
    if (occluder && !occluder.isPointVisible(point)) return null;
    const projected = cesium.SceneTransforms.worldToWindowCoordinates(
      scene,
      point,
      result,
    );
    if (
      !projected ||
      !Number.isFinite(projected.x) ||
      !Number.isFinite(projected.y)
    )
      return null;
    // A perspective surface normal dims the limb instead of accumulating a bright rim.
    const camera = scene.camera?.positionWC;
    const dx = camera?.x - point.x;
    const dy = camera?.y - point.y;
    const dz = camera?.z - point.z;
    const denominator =
      Math.hypot(point.x, point.y, point.z) * Math.hypot(dx, dy, dz);
    const cosine =
      denominator > 0
        ? (point.x * dx + point.y * dy + point.z * dz) / denominator
        : 1;
    projected.visibility = Number.isFinite(cosine)
      ? Math.max(0, Math.min(1, cosine / 0.3))
      : 1;
    return projected;
  }
  const inView = (point) =>
    point &&
    point.x >= 0 &&
    point.y >= 0 &&
    point.x <= cssWidth &&
    point.y <= cssHeight;

  function spawn(particle, scene, occluder) {
    for (let attempt = 0; attempt < 6; attempt++) {
      const west = bounds?.west ?? -180;
      const east = bounds?.east ?? 180;
      const low = bounds?.sinSouth ?? -0.9998;
      const high = bounds?.sinNorth ?? 0.9998;
      particle.lon = ((west + Math.random() * (east - west) + 540) % 360) - 180;
      particle.lat = Math.asin(low + Math.random() * (high - low)) / degree;
      particle.age = 1 + Math.random() * 7;
      particle.life = 8 + Math.random() * 4;
      if (inView(project(scene, occluder, particle.lon, particle.lat, screenA)))
        return;
    }
  }
  function seed(scene, occluder) {
    const count = budget();
    if (particles.length > count) particles.length = count;
    while (particles.length < count)
      particles.push({ lon: 0, lat: 0, age: 0, life: 10 });
    updateBounds(scene);
    for (const particle of particles) spawn(particle, scene, occluder);
  }

  function removeImagery() {
    imageryErrorRemove?.();
    imageryErrorRemove = null;
    if (imagery && imageryCollection && !imageryCollection.isDestroyed?.())
      imageryCollection.remove(imagery, true);
    else if (imagery && !imagery.isDestroyed?.()) imagery.destroy?.();
    imagery = null;
    shell?.destroy();
    shell = null;
    imageryCollection = null;
    imageryKind = null;
  }
  function updateImageryFade(camera, settled = false) {
    // The tileset shell keeps the quantised move-end fade; globe imagery keeps
    // its smooth per-frame fade.
    if (
      (!imagery && !shell) ||
      !camera?.positionCartographic ||
      (imageryKind === 'tileset' && !settled)
    )
      return;
    const height = camera.positionCartographic.height;
    const fade = !gpuActive
      ? 1
      : height <= WIND_FIELD_FADE_LOW_METERS
        ? 0
        : height >= WIND_FIELD_FADE_HIGH_METERS
          ? 1
          : Math.log(height / WIND_FIELD_FADE_LOW_METERS) /
            WIND_FIELD_LOG_RANGE;
    const baseAlpha = overlay === 'temperature' ? 1 : 0.85;
    const smoothAlpha = baseAlpha * fade;
    const alpha =
      gpuActive && imageryKind === 'tileset'
        ? Math.round(smoothAlpha * 10) / 10
        : smoothAlpha;
    if (shell) {
      shell.setAlpha(alpha);
      shell.setShow(alpha > 0 && getHost().kind !== 'none');
      return;
    }
    if (Math.abs(imagery.alpha - alpha) > 0.005) imagery.alpha = alpha;
    const show = alpha > 0;
    if (imagery.show !== show) imagery.show = show;
  }
  function installImagery() {
    removeImagery();
    imageryError = null;
    const viewer = viewerReady();
    if (!snapshot || overlay === 'none' || !viewer) return;
    const { collection, kind } = getHost();
    if (kind === 'none') {
      imageryError = NO_IMAGERY_HOST;
      return;
    }
    const raster = createFieldRaster(snapshot, overlay);
    if (!raster) {
      imageryError = fieldUnavailableText(overlay);
      return;
    }
    if (
      kind === 'tileset'
        ? !cesium.Primitive
        : !collection || !cesium.SingleTileImageryProvider
    ) {
      imageryError = msg('Globe imagery unavailable');
      return;
    }
    try {
      const texture = document.createElement('canvas');
      texture.width = raster.width;
      texture.height = raster.height;
      const ctx = texture.getContext('2d');
      const pixels = ctx.createImageData(raster.width, raster.height);
      pixels.data.set(raster.rgba);
      ctx.putImageData(pixels, 0, 0);
      if (kind === 'tileset') {
        shell = createShellSurface({
          viewer,
          cesium,
          rectangle: cesium.Rectangle.MAX_VALUE,
          height: WEATHER_SHELL_HEIGHTS.wind,
        });
        shell.setImage(texture);
        imageryKind = kind;
        shell.setAlpha(overlay === 'temperature' ? 1 : 0.85);
        updateImageryFade(viewer.scene.camera, true);
        viewer.scene?.requestRender?.();
        return;
      }
      const provider = new cesium.SingleTileImageryProvider({
        url: texture.toDataURL('image/png'),
        tileWidth: raster.width,
        tileHeight: raster.height,
        rectangle: cesium.Rectangle.MAX_VALUE,
      });
      imagery = collection.addImageryProvider(provider);
      orderWeatherImagery(collection, imagery, 0);
      imageryCollection = collection;
      imageryKind = kind;
      // Temperature colors carry quantitative meaning; double transparency
      // blends orange heat into blue ocean and obscures useful gradients.
      imagery.alpha = overlay === 'temperature' ? 1 : 0.85;
      if (gpuActive) updateImageryFade(viewer.scene.camera, true);
      imageryErrorRemove = provider.errorEvent?.addEventListener(() => {
        imageryError = msg('Globe field image unavailable');
      });
      viewer.scene?.requestRender?.();
    } catch {
      removeImagery();
      imageryError = msg('Globe field image unavailable');
    }
  }

  function rehome() {
    if (!snapshot || overlay === 'none') return;
    const { collection, kind } = getHost();
    const wasHidden = imageryError === NO_IMAGERY_HOST;
    if ((imagery || shell) && kind !== 'none' && kind !== imageryKind) {
      installImagery();
      onStatusChange?.();
      return;
    }
    // A host without imagery hides the retained shell until a host returns.
    if (shell && kind === 'none') shell.setShow(false);
    if (imagery && collection !== imageryCollection) {
      imageryCollection?.remove(imagery, false);
      imageryCollection = collection;
      if (collection) {
        collection.add(imagery);
        orderWeatherImagery(collection, imagery, 0);
      }
      viewerReady()?.scene?.requestRender?.();
    }
    if ((gpuActive || kind === 'tileset') && kind !== 'none')
      updateImageryFade(viewerReady()?.scene?.camera, true);
    if (kind === 'none') imageryError = NO_IMAGERY_HOST;
    else if (wasHidden) {
      imageryError = null;
      if (!imagery && !shell) installImagery();
    }
    if (wasHidden !== (imageryError === NO_IMAGERY_HOST)) onStatusChange?.();
  }

  /** No idle animation for pause/reduced motion; scene events repaint only changed views. */
  function viewChanged() {
    if (gpuActive) {
      const viewer = viewerReady();
      if (viewer) updateImageryFade(viewer.scene.camera);
      const narrow = (viewer?.scene?.canvas?.clientWidth || 800) < 700;
      let visibilityUpdated = false;
      if (running && field && !hidden() && narrow !== gpuNarrow) {
        gpuNarrow = narrow;
        gpuActive = gpu.setField(field);
        if (!gpuActive && viewer) {
          resize(viewer);
          seed(viewer.scene, makeOccluder(viewer.scene));
        }
        motionChanged();
        visibilityUpdated = true;
      }
      if (gpuActive && viewer && !visibilityUpdated) {
        gpuVisible = gpu.updateVisibility(viewer.scene.camera);
        if (gpuVisible) schedule();
        else {
          cancel();
          lastTime = null;
        }
      }
      const ready = gpuActive ? gpu.getDiagnostics().ready : null;
      if (ready !== reportedGpuReady) {
        reportedGpuReady = ready;
        onStatusChange?.();
      }
      return; // Cesium projects persistent curves; only a responsive budget change rebuilds them.
    }
    if (!running || !field || hidden() || !canvas) return;
    const viewer = viewerReady();
    if (!viewer) return;
    const resized = resize(viewer);
    if (resized || checkCamera(viewer.scene)) {
      cameraChanged = true;
      if (still()) paint(viewer, 0, true);
      else schedule();
    }
  }
  function motionChanged() {
    reducedMotion = media?.matches === true;
    cancel();
    lastTime = null;
    cameraChanged = true;
    gpu.setOptions({ overlay, paused: still() });
    if (!running || !field || hidden()) return;
    const viewer = viewerReady();
    if (gpuActive) {
      if (viewer) updateImageryFade(viewer.scene.camera);
      gpuVisible = viewer ? gpu.updateVisibility(viewer.scene.camera) : false;
      if (gpuVisible) {
        gpu.tick(flowTime);
        viewer.scene.requestRender();
        schedule();
      }
      return;
    }
    if (still() && viewer) paint(viewer, 0, true);
    else schedule();
  }
  function listen(target, event, callback) {
    if (!target?.addEventListener) return;
    target.addEventListener(event, callback);
    removers.push(() => target.removeEventListener(event, callback));
  }
  function cameraSettled() {
    if (gpuActive || imageryKind === 'tileset')
      updateImageryFade(viewerReady()?.scene?.camera, true);
    cameraMoved();
  }
  function cameraMoved() {
    viewChanged();
    // A parked request-render scene may never run preRender until we wake it.
    if (gpuActive && running && field && !hidden())
      viewerReady()?.scene?.requestRender?.();
  }
  function listenScene(event, callback) {
    if (!event?.addEventListener) return;
    const remove = event.addEventListener(callback);
    removers.push(
      typeof remove === 'function'
        ? remove
        : () => event.removeEventListener(callback),
    );
  }
  function attachListeners() {
    if (removers.length) return;
    media = globalThis.matchMedia?.('(prefers-reduced-motion: reduce)') ?? null;
    reducedMotion = media?.matches === true;
    listen(media, 'change', motionChanged);
    listen(globalThis.document, 'visibilitychange', motionChanged);
    listen(globalThis, 'resize', cameraMoved);
    listen(eventTarget, 'gev:map-stack-changed', rehome);
    const viewer = viewerReady();
    const camera = viewer?.scene?.camera;
    listenScene(viewer?.scene?.preRender, viewChanged);
    listenScene(camera?.moveEnd, cameraSettled);
  }
  function detachListeners() {
    for (const remove of removers) remove();
    removers = [];
    media = null;
  }

  function paint(viewer, dt, staticFrame, fadeSeconds = dt) {
    const scene = viewer.scene;
    const resized = resize(viewer);
    const changed = checkCamera(scene) || cameraChanged || resized;
    const occluder = makeOccluder(scene);
    if (changed) {
      clearPixels();
      updateBounds(scene);
      cameraChanged = false;
    }
    if (particles.length !== budget()) seed(scene, occluder);
    if (staticFrame) clearPixels();
    context.globalAlpha = 1;
    context.globalCompositeOperation = 'destination-out';
    context.fillStyle = `rgba(0,0,0,${trailEraseAlpha(fadeSeconds)})`;
    context.fillRect(0, 0, cssWidth, cssHeight);
    context.globalCompositeOperation = 'source-over';
    context.lineCap = 'round';
    const cameraHeight = scene.camera?.positionCartographic?.height ?? 1e6;
    const speedScale = Math.max(0.002, Math.min(4000, cameraHeight / 400));
    const advection = { speedScale };
    // Stroke length is a display sample of the local field, not frame travel.
    // At low FPS capped advection still moves the head by dt, but a readable
    // world-anchored tail survives without extra projections or screen stretching.
    const strokeSeconds = staticFrame ? 3 : 2;
    painted = 0;
    for (const particle of particles) {
      sampleWind(field, particle.lon, particle.lat, wind);
      if (!staticFrame) {
        advectParticle(particle, wind, dt, advection);
        particle.age += dt;
      }
      let point = project(scene, occluder, particle.lon, particle.lat, screenB);
      if (changed && !inView(point)) {
        // Refill newly exposed regions while retaining world anchors still in view.
        spawn(particle, scene, occluder);
        sampleWind(field, particle.lon, particle.lat, wind);
        point = project(scene, occluder, particle.lon, particle.lat, screenB);
      }
      if (particle.age > particle.life || !inView(point)) {
        spawn(particle, scene, occluder);
        continue;
      }
      before.lon = particle.lon;
      before.lat = particle.lat;
      advectParticle(before, wind, -strokeSeconds, advection);
      const previous = project(
        scene,
        occluder,
        before.lon,
        before.lat,
        screenA,
      );
      if (!inView(previous)) continue;
      const startX = previous.x;
      const startY = previous.y;
      const visibility = previous.visibility;
      const distance = Math.hypot(point.x - startX, point.y - startY);
      // Perspective/frustum jumps and antimeridian discontinuities never become strokes.
      if (
        Math.abs(before.lon - particle.lon) > 180 ||
        distance > Math.min(80, cssWidth * 0.08)
      )
        continue;
      const alpha =
        Math.min(visibility, point.visibility) *
        Math.min(1, particle.age / 0.8, (particle.life - particle.age) / 1.2);
      if (alpha <= 0) continue;
      const speed = Math.hypot(wind.u, wind.v);
      context.globalAlpha = alpha * 0.55;
      context.lineWidth = 1.0;
      context.strokeStyle =
        overlay === 'none' ? windTrailColor(speed) : '#9ddce4';
      context.beginPath();
      context.moveTo(startX, startY);
      context.lineTo(point.x, point.y);
      context.stroke();
      if (distance > 0.6) {
        context.globalAlpha = alpha * 0.9;
        context.strokeStyle = '#d6f4f5';
        context.lineWidth = 1.35;
        context.beginPath();
        context.moveTo(
          startX + (point.x - startX) * 0.72,
          startY + (point.y - startY) * 0.72,
        );
        context.lineTo(point.x, point.y);
        context.stroke();
      }
      if (staticFrame) {
        // Preserve direction at rest with a small arrowhead, without moving the field.
        if (distance > 2) {
          const ux = (point.x - startX) / distance;
          const uy = (point.y - startY) / distance;
          context.beginPath();
          context.moveTo(point.x - ux * 3 - uy * 2, point.y - uy * 3 + ux * 2);
          context.lineTo(point.x, point.y);
          context.lineTo(point.x - ux * 3 + uy * 2, point.y - uy * 3 - ux * 2);
          context.stroke();
        }
      }
      painted++;
    }
    context.globalAlpha = 1;
  }

  function draw(time) {
    frame = null;
    if (!running || !field || hidden() || still()) return;
    if (gpuActive && !gpuVisible) {
      lastTime = null;
      return;
    }
    const viewer = viewerReady();
    if (!viewer) return;
    try {
      const resized = !gpuActive && resize(viewer);
      if (resized) cameraChanged = true;
      const elapsed =
        lastTime === null ? 1 / 60 : Math.max(0, (time - lastTime) / 1000);
      // Limit full particle paints to 30 Hz while preserving elapsed-time motion/fading.
      if (lastTime === null || elapsed >= 0.032 || cameraChanged) {
        if (gpuActive) {
          flowTime += elapsed;
          gpu.tick(flowTime);
          viewer.scene.requestRender();
          cameraChanged = false;
        } else paint(viewer, Math.min(0.1, elapsed), false, elapsed);
        lastTime = time;
      }
    } catch (error) {
      if (!warned) {
        console.warn('[Data:Wind] frame failed:', error?.message || error);
        warned = true;
      }
    }
    schedule();
  }

  return {
    rehome,
    attach() {
      if (canvas) return;
      canvas = document.createElement('canvas');
      canvas.dataset.gevWind = '1';
      Object.assign(canvas.style, {
        position: 'absolute',
        inset: '0',
        pointerEvents: 'none',
        zIndex: '1',
      });
      canvas.setAttribute?.('aria-hidden', 'true');
      context = canvas.getContext('2d');
      container.appendChild(canvas);
    },
    setField(next) {
      const nextField = next?.grid
        ? { ...next.grid, u: next.u, v: next.v }
        : next;
      const viewer = viewerReady();
      const nextNarrow = (viewer?.scene?.canvas?.clientWidth || 800) < 700;
      const reuseGeometry =
        gpuActive &&
        gpuNarrow === nextNarrow &&
        gpu.supported() &&
        sameWind(snapshot, next, field, nextField);
      snapshot = next;
      field = nextField;
      cameraChanged = true;
      lastTime = null;
      cancel();
      if (canvas && field) {
        gpuNarrow = nextNarrow;
        if (!reuseGeometry) {
          gpuActive = gpu.supported() && gpu.setField(field);
          reportedGpuReady = gpuActive ? gpu.getDiagnostics().ready : null;
          flowTime = 0;
        }
        clearPixels();
        particles = [];
        if (viewer && !gpuActive) {
          resize(viewer);
          seed(viewer.scene, makeOccluder(viewer.scene));
        }
        installImagery();
        relief.attach();
        motionChanged();
      }
    },
    setOptions(options = {}) {
      const nextOverlay = ['none', 'speed', 'temperature', 'pressure'].includes(
        options.overlay,
      )
        ? options.overlay
        : overlay;
      const newPaused =
        typeof options.paused === 'boolean' ? options.paused : paused;
      const changedOverlay = nextOverlay !== overlay;
      const changedPause = newPaused !== paused;
      overlay = nextOverlay;
      paused = newPaused;
      if (changedOverlay) {
        installImagery();
        clearPixels();
      }
      if (changedOverlay || changedPause) motionChanged();
    },
    start() {
      if (running || !canvas) return;
      running = true;
      attachListeners();
      rehome();
      motionChanged();
    },
    stop() {
      running = false;
      cancel();
      lastTime = null;
      detachListeners();
      gpu.setOptions({ overlay, paused: true });
    },
    clear() {
      cancel();
      snapshot = null;
      field = null;
      particles = [];
      painted = 0;
      gpu.clear();
      relief.clear();
      gpuActive = false;
      gpuVisible = false;
      reportedGpuReady = null;
      flowTime = 0;
      removeImagery();
      imageryError = null;
      clearPixels();
    },
    destroy() {
      this.stop();
      this.clear();
      gpu.destroy();
      relief.destroy();
      canvas?.remove();
      canvas = null;
      context = null;
    },
    getParticleCount() {
      return gpuActive ? gpu.getParticleCount() : particles.length;
    },
    getDiagnostics() {
      return {
        overlay,
        paused,
        reducedMotion,
        hidden: hidden(),
        particleCount: gpuActive ? gpu.getParticleCount() : particles.length,
        renderMode: gpuActive ? 'gpu-streamlines' : 'canvas-fallback',
        gpu: gpu.getDiagnostics(),
        relief: relief.getDiagnostics(),
        painted,
        framePending: frame !== null,
        imageryActive: imagery !== null || shell !== null,
        host: shell ? 'shell' : imagery ? 'globe' : null,
        shell: shell?.getDiagnostics() ?? null,
        imageryError,
      };
    },
  };
}