Skip to content

The OSINT investigator's workbench. One case, one folder, every tool. Local-first: your media and your investigations never leave your machine.

JavaScript
46.8 KB
Raw Blame
/**
 * The globe: Satellite's 3D view, drawn by the app itself.
 *
 * The flat map stays MapLibre's. Tilted over relief, MapLibre's camera is a
 * centre seated on the ground, and every height that arrives under it moved
 * the eye; years of gestures were written to hold it still. Here the eye is the
 * camera (camera.js) and nothing but the hand moves it: a drag turns the Earth
 * under the grabbed point, an orbit swings round the pressed ground, the wheel
 * slides the eye along the line to the ground under the pointer. The ground
 * sharpens where it stands as its tiles come (tree.js, pictures.js), built off
 * the page's thread (worker.js), and drawn only when something changed.
 *
 * What the rest of the app asks of a map it asks of this the same way: the
 * methods below are the façade's (lib/map/facade.js) that a tilted view uses,
 * speaking the app's view (a centre, a whole zoom, the app's bearing, a tilt),
 * read off the eye and the ground under the middle of the screen.
 *
 * What the flat map lays over its imagery is drawn here too, by whoever is
 * handed in as `laid` (mirror.js): the ground's share painted into a picture
 * per tile over the imagery (drapes.js), the rest stood on the screen once a
 * frame is drawn. The hand's presses are handed to it as they come, so the
 * flat map's own listeners hear them.
 */
import { createTileBatcher } from '../map/tileBatch.js';
import { createWheelKind, wheelLevels, wheelValue } from '../map/wheel.js';
import {
  MAX_TILT,
  aimed,
  axes,
  cameraFor,
  distanceFor,
  dolly,
  focalOf,
  lifted,
  orbit,
  project,
  rayAt,
  tiltCeiling,
  turnBetween,
  turned,
  viewOf,
} from './camera.js';
import { EARTH, add, dot, ecef, geodetic, haversine, length, localFrame, metresPerPixel, normalize, raySphere, scale, sub, wrapLon } from './earth.js';
import { createDrapes, UPLOADS_PER_FRAME as DRAPE_UPLOADS } from './drapes.js';
import { createPictures } from './pictures.js';
import { createRenderer, groundUniforms, toneUniforms } from './renderer.js';
import { createTree } from './tree.js';
import { GLOBE_QUALITY, qualityOf } from '../quality3d.js';

/** Asks for what is out of view come after every ask for what is in it. */
const ROUND_RANK = 1e12;

/** The ground the eye keeps above, metres. */
export const CLEARANCE = 4;
/** The nearest the wheel brings the eye to the ground under the pointer, metres. */
export const NEAREST = 12;
/** Zoom levels the wheel may go past the imagery's own last one, as the flat map's overzoom does. */
const OVERZOOM = 2;
/** The app's zoom range, as the flat map and the routes that read a view take it. */
const ZOOM_MIN = 1;
const ZOOM_MAX = 22;
/** The farthest the eye goes from the Earth's centre: the whole globe in view, small. */
export const FARTHEST = EARTH * 5;
/** Pixels a press may move and still be a click. */
const CLICK_SLOP = 4;
/** A second press this soon after a click, this near it, is a double click. */
const DOUBLE_MS = 400;
const DOUBLE_SLOP = 8;
/** Degrees an orbit turns or tilts per pixel of the hand (gestures.js, the flat map's). */
const ORBIT_PER_PX = 0.25;
/**
 * How many times farther than seen square on the grabbed ground may move for a
 * pixel of the hand. Near the horizon a pixel is kilometres, and holding the
 * point exactly there would throw the view across the country: past this, the
 * grabbed point slips instead.
 */
const SLIP = 8;
/** Degrees the view turns per pixel when the sky is dragged: looking round from where the eye stands. */
const LOOK_PER_PX = 0.12;
/** ms a drag's last moves are read over for its fling, and how soon after the last one it must let go. */
const FLING_WINDOW = 100;
const FLING_GRACE = 60;
/** ms over which a fling's speed falls to a third. */
const FLING_FADE = 320;
/** ms over which the wheel's zoom is eased in. */
const WHEEL_EASE = 90;
/** The highest ground there is, at real scale: no ray meets ground above it. */
const TOP = 9000;
/** Lines of sight to marks traced per frame, at most, once the view has stopped. */
const SIGHTS_PER_FRAME = 60;
/** Below the sea, metres: a point whose line to the eye dips under this sphere is past the horizon. */
const HORIZON_DIP = 1000;

const appZoom = (view) => Math.min(ZOOM_MAX, Math.max(ZOOM_MIN, Math.round(view.zoom)));

/**
 * @param {HTMLCanvasElement} canvas
 * @param {object} [o]
 * @param {(provider: string) => void} [o.onMetered] billed pictures came (the meter counts them)
 * @param {(provider: string, error: Error) => void} [o.onFailed] a picture could not be read
 * @param {string} [o.quality] how much it draws (lib/quality3d.js), read once: Full unless said
 * @returns the globe, or null when the browser has no WebGL2
 */
export function createGlobe(canvas, { onMetered = () => {}, onFailed = () => {}, quality = 'full' } = {}) {
  const level = GLOBE_QUALITY[qualityOf(quality)];
  const renderer = createRenderer(canvas, { antialias: level.antialias });
  if (!renderer) return null;

  let camera = cameraFor({ lat: 20, lon: 0, zoom: 2 }, { width: 800, height: 600 });
  let exaggeration = 1;
  let imagery = null;
  // how the ground is drawn: a plain ground where there is no picture, and the pictures' tone
  let look = { plain: groundUniforms(null), tone: toneUniforms() };
  let fallbackRelief = false;
  // a capture under way, drawn as sharp as Full draws it
  let capturing = false;
  let destroyed = false;
  let lost = false;

  const listeners = new Map();
  const emit = (name, payload) => {
    for (const handler of listeners.get(name) ?? []) handler(payload);
  };

  // -- the tiles ---------------------------------------------------------------------

  const worker = new Worker(new URL('./worker.js', import.meta.url), { type: 'module' });
  const tree = createTree({
    request: (tiles) => worker.postMessage({ type: 'mesh', tiles }),
    release: (n) => renderer.deleteMesh(n.mesh),
    budget: level.meshes,
    sharpness: level.sharpness,
    round: level.round,
  });
  worker.onmessage = ({ data }) => {
    if (destroyed || data.type !== 'mesh') return;
    if (data.failed) tree.arrived(data.key, null);
    else {
      if (data.fallback) fallbackRelief = true;
      tree.arrived(data.key, { ...data, mesh: renderer.createMesh(data.vertices) });
    }
    heightsChanged();
    schedule();
  };

  const batcher = createTileBatcher();
  const pictures = createPictures({
    fetch: async (provider, z, x, y, signal) => {
      try {
        const { status, data } = await batcher.get(`/api/tiles/batch/${provider}`, z, x, y, signal);
        if (status === 404 || status === 204) return null;
        if (status !== 200) {
          const error = new Error(`tile answered ${status}`);
          error.status = status;
          error.body = new Blob([data], { type: 'text/plain' });
          throw error;
        }
        return await createImageBitmap(new Blob([data]));
      } finally {
        // a frame to lay it in, once it is decoded: the store takes it before the frame comes
        schedule();
      }
    },
    upload: (bitmap) => renderer.createTexture(bitmap),
    release: (handle) => renderer.deleteTexture(handle),
    onMetered,
    onFailed,
    budget: level.pictureBytes,
    uploads: level.uploads,
  });

  // what the flat map lays on the ground, painted per tile by `laid` (mirror.js)
  let laid = null;
  // off while a capture is drawn: a tilted capture is the imagery on its relief alone
  let draping = true;
  const drapes = createDrapes({
    // a frame to lay it in once it is painted: nothing else may be asking for one
    compose: (tile, signal) => (laid ? laid.compose(tile, signal) : Promise.resolve(null)).finally(schedule),
    upload: (picture) => renderer.createOverlayTexture(picture),
    release: (handle) => renderer.deleteTexture(handle),
    budget: level.drapeBytes,
    uploads: Math.min(DRAPE_UPLOADS, level.uploads + 2),
  });

  // -- the size ----------------------------------------------------------------------

  let css = { width: 1, height: 1 };
  function measure() {
    css = { width: Math.max(1, canvas.clientWidth), height: Math.max(1, canvas.clientHeight) };
    const dpr = Math.min(level.pixelsMax, globalThis.devicePixelRatio || 1);
    const width = Math.round(css.width * dpr);
    const height = Math.round(css.height * dpr);
    if (canvas.width !== width || canvas.height !== height) {
      canvas.width = width;
      canvas.height = height;
    }
  }
  measure();
  // A tab put away hides the canvas: read at no size the view would say a zoom
  // far out, which the app takes for where the analyst looks. It keeps its size
  // until it shows again.
  const resizer = new ResizeObserver(() => {
    if (!canvas.clientWidth || !canvas.clientHeight) return;
    measure();
    changed();
  });
  resizer.observe(canvas);

  // -- the ground under a ray ----------------------------------------------------------

  /** The ground's height as drawn (exaggerated) at a point, or 0 where none is held yet. */
  function groundHeight(lat, lon) {
    return (tree.groundAt(lat, wrapLon(lon))?.h ?? 0) * exaggeration;
  }

  /**
   * Where a ray from `origin` first meets the ground as drawn, or null when it
   * meets none. Marched by how far above the ground it is, a step never under
   * a hundredth of the way gone, then halved down to the crossing.
   */
  function march(origin, dir) {
    const top = EARTH + TOP * Math.max(1, exaggeration);
    let t = 0;
    if (length(origin) > top) {
      const enter = raySphere(origin, dir, top);
      if (enter == null) return null;
      t = enter;
    }
    const gapAt = (s) => {
      const g = geodetic(add(origin, scale(dir, s)));
      return g.h - groundHeight(g.lat, g.lon);
    };
    let before = null;
    for (let i = 0; i < 600; i += 1) {
      const p = add(origin, scale(dir, t));
      const g = geodetic(p);
      const gap = g.h - groundHeight(g.lat, g.lon);
      if (gap <= 0.02) {
        if (before == null) return p;
        let lo = before;
        let hi = t;
        for (let k = 0; k < 30; k += 1) {
          const mid = (lo + hi) / 2;
          if (gapAt(mid) > 0) lo = mid;
          else hi = mid;
        }
        return add(origin, scale(dir, hi));
      }
      // above every summit and climbing: nothing left to meet
      if (g.h > top - EARTH && dot(dir, normalize(p)) >= 0) return null;
      before = t;
      t += Math.max(gap * 0.5, 0.25 + t * 0.01);
    }
    return null;
  }

  /** The ground under a pixel of the view, or null on the sky. */
  const pick = (x, y) => march(camera.eye, rayAt(camera, css, x, y));

  // the ground under the middle of the screen, which the app's view is read at
  let centreCache = null;
  function centre() {
    if (centreCache) return centreCache;
    const hit = pick(css.width / 2, css.height / 2);
    // looking past the ground: the point under the eye stands in for it
    const target = hit ?? ecef(geodetic(camera.eye).lat, geodetic(camera.eye).lon, 0);
    centreCache = { target, view: viewOf(camera, css, target), onGround: Boolean(hit) };
    return centreCache;
  }
  function heightsChanged() {
    centreCache = null;
    groundMoved = true;
    groundStamp += 1;
  }

  // -- the camera, moved -----------------------------------------------------------

  let moved = false;
  // a step each time the ground's heights as drawn change, which a mark's height is kept against
  let groundStamp = 0;
  // finer heights came in: what stands on the ground stands somewhere else on screen
  let groundMoved = false;
  let lastHeading = null;
  let lastTilt = null;
  let unsettled = false;

  function changed() {
    centreCache = null;
    moved = true;
    unsettled = true;
    schedule();
  }

  /** Whether the eye of `next` stands clear of the ground, and looks at the Earth from as high as it stands. */
  function clear(next) {
    const g = geodetic(next.eye);
    // a tilt past what the height allows is refused, unless the move takes some of it back
    const tilt = next.tilt <= Math.max(tiltCeiling(g.h), camera.tilt) + 1e-6;
    // likewise a height past the farthest: a wide view handed in from the flat map stands there
    const far = length(next.eye) <= Math.max(FARTHEST, length(camera.eye) + 1);
    return g.h - groundHeight(g.lat, g.lon) >= CLEARANCE && far && tilt;
  }

  /** Whether the ground leaves the line from the eye of `next` to `point` open, to within a hundredth of the way. */
  function sees(next, point) {
    const to = sub(point, next.eye);
    const distance = length(to);
    const hit = march(next.eye, scale(to, 1 / distance));
    return !hit || length(sub(hit, next.eye)) >= distance - Math.max(2, distance * 0.01);
  }

  /** Take a camera if its eye is clear of the ground; false leaves the view as it was. */
  function take(next) {
    if (!clear(next)) return false;
    camera = next;
    changed();
    return true;
  }

  /**
   * The ground came up under the eye (finer heights, or a stronger
   * exaggeration): it rises clear, and with no hand on the view it looks back
   * at the ground that was in the middle, so the view keeps its centre.
   */
  function keepClear() {
    const g = geodetic(camera.eye);
    const short = groundHeight(g.lat, g.lon) + CLEARANCE - g.h;
    if (short > 0) {
      const middle = !press && centreCache?.onGround ? centreCache.target : null;
      camera = lifted(camera, short);
      if (middle) camera = aimed(camera, css, middle, css.width / 2, css.height / 2);
      changed();
    }
  }

  // -- the hand ----------------------------------------------------------------------

  let press = null;
  // the last click, for a press that comes as the second of a double click
  let lastClick = null;
  // a tool reading the clicks (a measure being drawn) takes a double click as two clicks
  let clicksRead = false;
  let fling = null;
  let wheel = { pending: 0, delta: 0, kind: 'wheel', target: null, onGround: false, x: -1, y: -1 };
  const wheelKind = createWheelKind(() => performance.now());
  let hover = null;

  const local = (e) => {
    const box = canvas.getBoundingClientRect();
    // a page scaled to the window (a plate) shows the canvas larger or smaller than its own pixels
    const sx = box.width ? css.width / box.width : 1;
    const sy = box.height ? css.height / box.height : 1;
    return { x: (e.clientX - box.left) * sx, y: (e.clientY - box.top) * sy };
  };

  function stopMotion() {
    fling = null;
    wheel.pending = 0;
    wheel.delta = 0;
    wheel.target = null;
  }

  /** A press, a move or a release handed on as it came, with the ground under it (null on the sky). */
  function relay(type, e, at = local(e)) {
    if (!listeners.get('pointer')?.size) return;
    const hit = pick(at.x, at.y);
    const ground = hit ? geodetic(hit) : null;
    emit('pointer', { type, x: at.x, y: at.y, ground: ground && { lat: ground.lat, lon: wrapLon(ground.lon) }, event: e });
  }

  function onDown(e) {
    if (e.button > 2) return;
    relay('mousedown', e);
    stopMotion();
    pending = null;
    const at = local(e);
    // the second press of a double click, held, turns as the middle button does
    const second =
      !clicksRead &&
      e.button === 0 &&
      lastClick &&
      performance.now() - lastClick.at < DOUBLE_MS &&
      Math.hypot(at.x - lastClick.x, at.y - lastClick.y) < DOUBLE_SLOP;
    lastClick = null;
    const turning = e.button === 1 || e.button === 2 || e.shiftKey || e.ctrlKey || second;
    press = { ...at, from: at, button: e.button, moved: false, second, out: e.shiftKey, id: e.pointerId, samples: [] };
    if (turning) {
      press.kind = 'orbit';
      press.pivot = pick(at.x, at.y) ?? centre().target;
      // the eye can swing over any ground as far round the pivot as it stands from it
      const round = geodetic(press.pivot);
      tree.knowGround(round.lat, wrapLon(round.lon), length(sub(camera.eye, press.pivot)));
      // the pixel the pivot is held on through the swing
      press.pivotAt = project(camera, css, press.pivot) ?? { x: css.width / 2, y: css.height / 2 };
    } else {
      const grab = pick(at.x, at.y);
      if (grab) {
        press.kind = 'pan';
        press.grab = grab;
        press.radius = length(grab);
      } else press.kind = 'look';
    }
    canvas.setPointerCapture?.(e.pointerId);
    // a field that had the keys gives them back, so Page Up and Down tilt
    const focused = document.activeElement;
    if (focused && focused !== document.body) focused.blur?.();
  }

  function onMove(e) {
    const at = local(e);
    if (!press) {
      hover = at;
      relay('mousemove', e, at);
      if (listeners.get('pointer-move')?.size) schedule();
      return;
    }
    if (e.pointerId !== press.id) return;
    if (!press.moved && Math.hypot(at.x - press.from.x, at.y - press.from.y) < CLICK_SLOP) return;
    press.moved = true;
    const dx = at.x - press.x;
    const dy = at.y - press.y;
    press.x = at.x;
    press.y = at.y;
    if (press.kind === 'pan') panTo(at, press, Math.hypot(dx, dy));
    else if (press.kind === 'orbit') {
      // the turn and the tilt each go if their own eye is clear and still sees the pivot past
      // the ground between, so the view slides along a slope and never swings behind a ridge
      const { pivot, pivotAt } = press;
      const swing = (dHeading, dTilt) => {
        const next = aimed(orbit(camera, pivot, dHeading, dTilt), css, pivot, pivotAt.x, pivotAt.y);
        if (sees(next, pivot)) take(next);
      };
      swing(dx * ORBIT_PER_PX, 0);
      swing(0, -dy * ORBIT_PER_PX);
    } else {
      // the sky held and pulled: the view turns and tilts the other way, from where the eye stands
      const { up } = localFrame(camera.eye);
      take(turned(camera, camera.eye, up, dx * LOOK_PER_PX * (Math.PI / 180)));
      take({ ...camera, tilt: Math.min(tiltCeiling(geodetic(camera.eye).h), Math.max(0, camera.tilt + dy * LOOK_PER_PX)) });
    }
  }

  /**
   * Turn the Earth so the ground `hold.grab` comes back under the hand at `at`,
   * the hand having moved `moved` pixels, the turn noted in `hold.samples` for
   * a fling.
   *
   * The hand's ray is met on the sphere through the grabbed point, or, when
   * the eye stands lower than that point (a summit seen from its valley), on
   * the level through it: from inside the sphere the ray would only leave it
   * on the far side of the Earth.
   */
  function panTo(at, hold, moved) {
    const dir = rayAt(camera, css, at.x, at.y);
    let hit = null;
    if (length(camera.eye) > hold.radius + 1) {
      const t = raySphere(camera.eye, dir, hold.radius);
      if (t != null) hit = add(camera.eye, scale(dir, t));
    } else {
      const level = normalize(hold.grab);
      const facing = dot(dir, level);
      const t = Math.abs(facing) > 1e-9 ? dot(sub(hold.grab, camera.eye), level) / facing : -1;
      if (t > 0) hit = add(camera.eye, scale(dir, t));
    }
    // past the ground the grabbed point stands on, the hand has nothing to hold: the move waits
    if (!hit) return;
    const turn = turnBetween(hit, hold.grab);
    if (!turn) return;
    const most = (SLIP * length(sub(hold.grab, camera.eye)) * moved) / (focalOf(css.height) * EARTH);
    turn.angle = Math.min(turn.angle, most);
    camera = turned(camera, [0, 0, 0], turn.axis, turn.angle);
    keepClear();
    changed();
    const now = performance.now();
    hold.samples.push({ at: now, axis: turn.axis, angle: turn.angle });
    while (hold.samples.length && now - hold.samples[0].at > FLING_WINDOW) hold.samples.shift();
  }

  function onUp(e) {
    relay('mouseup', e);
    if (!press || e.pointerId !== press.id) return;
    const ended = press;
    press = null;
    canvas.releasePointerCapture?.(e.pointerId);
    if (!ended.moved) {
      const hit = pick(ended.from.x, ended.from.y);
      const at = hit ? geodetic(hit) : null;
      // a double click that never moved slides the eye a level toward the ground (Shift: away)
      if (ended.second) {
        if (hit) zoomToward(hit, ended.from, ended.out ? -1 : 1);
        return;
      }
      if (ended.button === 0) lastClick = { at: performance.now(), x: ended.from.x, y: ended.from.y };
      if (ended.button === 0 && at) {
        emit('click', { lat: at.lat, lon: wrapLon(at.lon) });
        relay('click', e, ended.from);
      } else if (ended.button === 2 && at) {
        emit('contextmenu', { lat: at.lat, lon: wrapLon(at.lon), x: ended.from.x, y: ended.from.y });
        relay('contextmenu', e, ended.from);
      }
      // a middle click puts north back up, as on the flat map
      else if (ended.button === 1) api.setBearing(0);
      return;
    }
    if (ended.kind === 'pan') {
      const now = performance.now();
      const recent = ended.samples.filter((s) => now - s.at <= FLING_WINDOW);
      const last = recent[recent.length - 1];
      if (last && now - last.at <= FLING_GRACE && recent.length > 1) {
        const span = Math.max(16, now - recent[0].at);
        const angle = recent.reduce((sum, s) => sum + s.angle, 0);
        // never faster than the view's width a frame
        const most = (css.width * metresAtCentre()) / (16 * EARTH);
        fling = { axis: last.axis, rate: Math.min(angle / span, most) };
      }
    }
    schedule();
  }

  function onWheel(e) {
    e.preventDefault();
    fling = null;
    pending = null;
    const at = local(e);
    const value = wheelValue(e);
    wheel.kind = wheelKind(value);
    wheel.delta -= value;
    if (!wheel.target || Math.hypot(at.x - wheel.x, at.y - wheel.y) > 2) {
      const dir = rayAt(camera, css, at.x, at.y);
      const ground = march(camera.eye, dir);
      // over the sky the eye slides along the ray, as toward ground as far away as it stands high
      wheel.target = ground ?? add(camera.eye, scale(dir, Math.max(200, 3 * geodetic(camera.eye).h)));
      wheel.onGround = Boolean(ground);
      wheel.x = at.x;
      wheel.y = at.y;
    }
    schedule();
  }

  /**
   * Slide toward the wheel's target by `levels` of zoom (negative backs off),
   * short of the ground. The eye keeps its heading and its tilt, as the flat
   * map's zoom keeps its turn and tilt, and the Earth is then turned so the
   * ground under the pointer is back under it.
   */
  function zoomBy(levels) {
    const target = wheel.target;
    if (!target) return false;
    const distance = length(sub(target, camera.eye));
    // no nearer than the imagery's last level, a little enlarged, would frame the ground from
    const ceiling = Math.min(ZOOM_MAX, (imagery ? imagery.deepest + imagery.shift : 19) + OVERZOOM);
    const nearest = Math.max(NEAREST, distanceFor(geodetic(target).lat, ceiling, css.height));
    let share = 1 - 2 ** -levels;
    if (distance * (1 - share) < nearest) share = Math.min(share, Math.max(0, 1 - nearest / distance));
    if (Math.abs(share) < 1e-9) return false;
    const slid = dolly(camera, target, share);
    // rising, the eye levels as it must to keep the Earth in view
    let next = { ...slid, heading: camera.heading, tilt: Math.min(camera.tilt, tiltCeiling(geodetic(slid.eye).h)) };
    if (wheel.onGround) {
      const dir = rayAt(next, css, wheel.x, wheel.y);
      const t = raySphere(next.eye, dir, length(target));
      const turn = t == null ? null : turnBetween(add(next.eye, scale(dir, t)), target);
      if (turn) next = turned(next, [0, 0, 0], turn.axis, turn.angle);
    }
    return take(next);
  }

  /** Slide `levels` toward the ground at `hit`, under the pixel `at`, eased as the wheel is. */
  function zoomToward(hit, at, levels) {
    wheel.target = hit;
    wheel.onGround = true;
    wheel.x = at.x;
    wheel.y = at.y;
    wheel.pending += levels;
    schedule();
  }

  const onMenu = (e) => e.preventDefault();
  const onLeave = (e) => {
    hover = null;
    relay('mouseout', e);
  };
  // The press is the map's: no text selected, no page scrolled by the middle
  // button. Said on the mouse event the press brings rather than on the pointer
  // one: cancelling a pointer press keeps the browser from sending the mouse
  // events at all, and the page hears presses by those (a menu closing on a
  // press outside it, the guard on a middle click's paste in lib/clipboardPaste.js).
  const onMouseDown = (e) => e.preventDefault();
  canvas.addEventListener('mousedown', onMouseDown);
  canvas.addEventListener('pointerdown', onDown);
  canvas.addEventListener('pointermove', onMove);
  canvas.addEventListener('pointerup', onUp);
  canvas.addEventListener('pointercancel', onUp);
  canvas.addEventListener('pointerleave', onLeave);
  canvas.addEventListener('wheel', onWheel, { passive: false });
  canvas.addEventListener('contextmenu', onMenu);
  const onLost = (e) => {
    e.preventDefault();
    lost = true;
    emit('lost');
  };
  canvas.addEventListener('webglcontextlost', onLost);

  // -- the frame ---------------------------------------------------------------------

  let raf = 0;
  let last = 0;
  let revealed = false;
  let loading = 0;
  let idleWaiters = [];

  function schedule() {
    if (!raf && !destroyed) raf = requestAnimationFrame(draw);
  }

  /** The eased parts of a movement, one frame on: the fling, the wheel. True while one goes on. */
  function step(dt) {
    let going = false;
    if (fling) {
      camera = turned(camera, [0, 0, 0], fling.axis, fling.rate * dt);
      keepClear();
      changed();
      fling.rate *= Math.exp(-dt / FLING_FADE);
      // stopped once the ground moves under a tenth of a pixel a frame
      if (fling.rate * 16 * EARTH < 0.1 * metresAtCentre()) fling = null;
      else going = true;
    }
    if (wheel.delta) {
      wheel.pending += wheelLevels(wheel.delta, wheel.kind);
      wheel.delta = 0;
    }
    if (Math.abs(wheel.pending) > 1e-4) {
      const take = wheel.pending * (1 - Math.exp(-dt / WHEEL_EASE));
      wheel.pending -= take;
      if (!zoomBy(take)) wheel.pending = 0;
      going = true;
    } else {
      wheel.pending = 0;
      // the next turn of the wheel reads the ground under the pointer afresh
      wheel.target = null;
    }
    return going;
  }

  /** Metres a pixel spans in the middle of the screen. */
  const metresAtCentre = () => length(sub(centre().target, camera.eye)) / focalOf(css.height);

  function draw(now) {
    raf = 0;
    if (destroyed || lost) return;
    const dt = last ? Math.min(64, now - last) : 16;
    last = now;
    const going = step(dt) || Boolean(press);
    keepClear();
    const view = centre().view;
    if (imagery) {
      pictures.setImagery({
        ...imagery,
        // where billed pictures stop: the flat view's reach (quotaGuard.js counts zoom on 512 px tiles)
        view: { lat: view.lat, lon: view.lon, zoom: view.zoom - 1, width: css.width, height: css.height, pitch: view.pitch },
      });
    }
    pictures.begin();
    drapes.begin();
    const limit = imagery ? Math.max(imagery.deepest + imagery.shift, 16) : 16;
    // a capture is drawn as sharp as Full draws it, whatever this computer shows on screen
    const sharp = capturing ? GLOBE_QUALITY.full.sharpness : level.sharpness;
    const { drawn, waiting, view: seen, round } = tree.frame(camera, css, { exaggeration, limit, sharp });
    const tiles = [];
    for (const n of drawn) {
      const distance = n.bound ? length(sub(n.bound.mid, camera.eye)) : 0;
      tiles.push({
        mesh: n.mesh,
        centre: n.centre,
        quarters: n.quarters,
        picture: pictures.pictureFor(n, n.z * 1e9 + distance),
        drape: laid && draping ? drapes.drapeFor(n, n.z * 1e9 + distance) : null,
      });
    }
    lastDrawn = drawn;
    // the pictures of the ground all round, after the frame's own, so a turn finds it dressed
    for (const n of round) {
      const distance = n.bound ? length(sub(n.bound.mid, camera.eye)) : 0;
      pictures.pictureFor(n, ROUND_RANK + n.z * 1e9 + distance);
    }
    // both stores lay their arrivals every frame, whichever has some
    const laying = [pictures.end(), drapes.end()].some(Boolean);
    // first shown once the eye stands where it was asked and every tile drawn has a picture
    if (!revealed && !pending && tiles.length && tiles.every((t) => t.picture)) {
      revealed = true;
      emit('shown');
    }
    renderer.draw({
      view: { ...seen, cssWidth: css.width, cssHeight: css.height },
      size: { width: canvas.width, height: canvas.height },
      tiles,
      exaggeration,
      look,
    });
    loading = waiting + pictures.waiting;
    const sightsDue = laid ? traceSights(going) : false;
    if (laid) {
      laid.frame({ moved: moved || groundMoved });
      groundMoved = false;
    }
    if (moved) {
      viewStamp += 1;
      moved = false;
      emit('view-move', api.camera());
      if (lastHeading !== null && Math.abs(camera.heading - lastHeading) > 1e-6) emit('rotate', api.camera());
      if (lastTilt !== null && Math.abs(camera.tilt - lastTilt) > 1e-6) emit('pitch', api.camera());
      lastHeading = camera.heading;
      lastTilt = camera.tilt;
    }
    if (hover && listeners.get('pointer-move')?.size) {
      const hit = pick(hover.x, hover.y);
      if (hit) {
        const g = geodetic(hit);
        emit('pointer-move', { lat: g.lat, lon: wrapLon(g.lon) });
      }
    }
    if (!going && unsettled) {
      unsettled = false;
      emit('view-settled', api.camera());
    }
    if (going || laying || sightsDue) schedule();
    if (!going && !press && !pending && loading === 0 && !laying) {
      const waiters = idleWaiters;
      idleWaiters = [];
      for (const resolve of waiters) resolve();
    }
  }

  // -- what stands on the ground: where it is seen, and whether --------------------

  let lastDrawn = [];
  // the camera's axes as last read, for the marks projected many a frame
  const lens = { camera: null, width: 0, height: 0, axes: null, f: 1 };
  // the view the lines of sight were traced for, a step each time it moves
  let viewStamp = 0;
  // marks' ground → { hidden, stamp }: whether the relief stands between it and the eye
  const sights = new Map();
  let sightsAsked = [];

  /** Whether the curve of the Earth hides `p` from the eye. */
  function overHorizon(p) {
    const eye = camera.eye;
    const d = sub(p, eye);
    const t = -dot(eye, d) / dot(d, d);
    if (t <= 0 || t >= 1) return false;
    return length(add(eye, scale(d, t))) < EARTH - HORIZON_DIP;
  }

  /**
   * Trace the lines of sight asked since the view stopped, a few a frame:
   * while the view moves each mark keeps what it was last found to be, so
   * nothing blinks under a ridge mid-gesture. True while some are left.
   */
  function traceSights(going) {
    if (going || press) {
      sightsAsked = [];
      return false;
    }
    let traced = 0;
    while (sightsAsked.length && traced < SIGHTS_PER_FRAME) {
      const { key, point } = sightsAsked.pop();
      const entry = sights.get(key);
      if (entry?.stamp === viewStamp) continue;
      sights.set(key, { hidden: !sees(camera, point), stamp: viewStamp });
      traced += 1;
    }
    if (traced) groundMoved = true;
    if (sights.size > 20000) sights.clear();
    return sightsAsked.length > 0;
  }

  /** Whether the relief hides a point, as last traced; asked again once the view has stopped. */
  function hiddenByRelief(key, point) {
    const entry = sights.get(key);
    if (entry?.stamp !== viewStamp) sightsAsked.push({ key, point });
    return entry?.hidden ?? false;
  }

  // -- the façade --------------------------------------------------------------------

  /**
   * A placement waiting for the height of its ground (`{ wanted, ticket }`):
   * a turn, a tilt or a zoom asked meanwhile is made to it, another placement
   * replaces it, and a hand on the view drops it.
   */
  let pending = null;
  let tickets = 0;

  /** The ground's height at a point as drawn, if a tile fine enough to say it is held; else null. */
  function groundKnown(lat, lon) {
    const ground = tree.groundAt(lat, wrapLon(lon));
    return ground && ground.z >= 10 ? ground.h * exaggeration : null;
  }

  /** The ground's height at a point, asked of the app (the readout's own route); 0 when it cannot say. */
  async function heightOf(lat, lon) {
    try {
      const answer = await fetch(`/api/terrain/elevation?lat=${lat}&lon=${wrapLon(lon)}`);
      const value = answer.ok ? (await answer.json()).elevation : null;
      return Number.isFinite(value) ? value : 0;
    } catch {
      return 0;
    }
  }

  /**
   * A whole camera of the app's. The eye stands where the view says relative
   * to the ground at its centre, so that ground's height is part of it: handed
   * in, read off a tile held there, or else asked of the app first. Until the
   * app answers, the eye is placed as if the ground were where the tiles say,
   * and it is placed again once, when the answer comes, unless the hand or
   * another placement moved it meanwhile.
   */
  function place(wanted) {
    const { lat, lon } = wanted;
    const known = Number.isFinite(wanted.elevation) ? wanted.elevation : groundKnown(lat, lon);
    if (known != null) {
      pending = null;
      put({ ...wanted, elevation: known });
      return;
    }
    const ticket = (tickets += 1);
    pending = { wanted, ticket };
    putProvisional();
    heightOf(lat, lon).then((height) => {
      if (pending?.ticket !== ticket || destroyed) return;
      const { wanted: last } = pending;
      pending = null;
      put({ ...last, elevation: height * exaggeration });
    });
  }

  /** The waiting placement, put where the tiles held say its ground is meanwhile. */
  function putProvisional() {
    const { wanted } = pending;
    put({ ...wanted, elevation: (tree.groundAt(wanted.lat, wrapLon(wanted.lon))?.h ?? 0) * exaggeration });
  }

  /** A change to the view: made to the placement still waiting for its ground, or to the view as it stands. */
  function change(changes) {
    if (pending) {
      pending.wanted = { ...pending.wanted, ...changes };
      putProvisional();
    } else place({ ...centre().view, ...changes });
  }

  /** The eye placed at once for a camera whose ground height is `elevation`. */
  function put({ lat, lon, zoom, bearing = 0, pitch, elevation: height }) {
    const now = centre().view;
    let next = cameraFor(
      { lat, lon, zoom, bearing, pitch: Number.isFinite(pitch) ? pitch : now.pitch, elevation: height },
      css
    );
    // a tilt that would put the eye in a slope stops where it is clear
    for (let tries = 0; tries < 12 && !clear(next) && next.tilt > 0; tries += 1) {
      next = cameraFor({ lat, lon, zoom, bearing, pitch: Math.max(0, next.tilt - 6), elevation: height }, css);
    }
    stopMotion();
    camera = next;
    keepClear();
    changed();
  }

  function fitBounds({ north, south, east, west }, options = {}) {
    const pad = Array.isArray(options.padding) ? options.padding : [options.padding ?? 0, options.padding ?? 0];
    const lat = (north + south) / 2;
    const lon = (east + west) / 2;
    const wide = haversine({ lat, lon: west }, { lat, lon: east });
    const tall = haversine({ lat: south, lon }, { lat: north, lon });
    const perPixel = Math.max(wide / Math.max(1, css.width - 2 * pad[0]), tall / Math.max(1, css.height - 2 * pad[1]), 0.05);
    let zoom = Math.floor(Math.log2(metresPerPixel(lat, 0) / perPixel));
    if (options.maxZoom != null) zoom = Math.min(zoom, options.maxZoom);
    const now = pending?.wanted ?? centre().view;
    place({ lat, lon, zoom: Math.max(1, zoom), bearing: now.bearing, pitch: now.pitch });
  }

  const api = {
    camera() {
      const view = centre().view;
      return { lat: view.lat, lon: view.lon, zoom: appZoom(view), bearing: view.bearing, pitch: Math.round(view.pitch) };
    },
    getZoom: () => appZoom(centre().view),
    exactZoom: () => Math.min(ZOOM_MAX, Math.max(ZOOM_MIN, centre().view.zoom)),
    centreElevation: () => (centre().onGround ? centre().view.elevation : null),
    setCamera: (wanted) => place(wanted),
    setView: ({ lat, lon }, zoom) => {
      const now = pending?.wanted ?? centre().view;
      place({ lat, lon, zoom, bearing: now.bearing, pitch: now.pitch });
    },
    setZoom: (zoom) => change({ zoom }),
    setBearing: (deg) => change({ bearing: Number(deg) || 0 }),
    setPitch: (deg) => change({ pitch: Math.min(MAX_TILT, Math.max(0, Number(deg) || 0)) }),
    maxPitch: () => MAX_TILT,
    panBy: (dx, dy) => {
      const grab = pick(css.width / 2 + dx, css.height / 2 + dy);
      if (grab) panTo({ x: css.width / 2, y: css.height / 2 }, { grab, radius: length(grab), samples: [] }, Math.hypot(dx, dy));
    },
    fitBounds,
    fitPoints(points, options) {
      const usable = (points ?? []).filter((p) => Number.isFinite(p?.lat) && Number.isFinite(p?.lon));
      if (!usable.length) return false;
      fitBounds(
        {
          north: Math.max(...usable.map((p) => p.lat)),
          south: Math.min(...usable.map((p) => p.lat)),
          east: Math.max(...usable.map((p) => p.lon)),
          west: Math.min(...usable.map((p) => p.lon)),
        },
        options
      );
      return true;
    },
    containerPointToLatLng({ x, y }) {
      const hit = pick(x, y);
      if (!hit) return null;
      const g = geodetic(hit);
      return { lat: g.lat, lon: wrapLon(g.lon) };
    },
    latLngToContainerPoint({ lat, lon }) {
      const at = project(camera, css, ecef(lat, lon, groundHeight(lat, lon)));
      return at ? { x: at.x, y: at.y } : { x: NaN, y: NaN };
    },
    /**
     * The ground under a point of the view, read on a sphere through the ground at the
     * view's middle rather than marched over the heights: quick enough for a whole grid
     * of points (a plate's lit country), near enough round the middle. Null in the sky.
     */
    surfaceAt({ x, y }) {
      const dir = rayAt(camera, css, x, y);
      const t = raySphere(camera.eye, dir, length(centre().target));
      if (t == null) return null;
      const g = geodetic(add(camera.eye, scale(dir, t)));
      return { lat: g.lat, lon: wrapLon(g.lon) };
    },
    /**
     * Where a point `metres` above the sea stands on screen, raised as the
     * ground under it is (exaggeration), or null behind the eye: an eye or a
     * target standing in the air, which no ground point can place.
     */
    projectAt(lat, lon, metres) {
      const at = project(camera, css, ecef(lat, lon, metres * exaggeration));
      return at ? { x: at.x, y: at.y } : null;
    },
    /** Whether a tool reads the map's clicks: then a double click is two clicks, never a zoom. */
    readClicks(on) {
      clicksRead = Boolean(on);
      lastClick = null;
    },
    onSurface: (target) => target === canvas,
    /** A wheel over something laid on the view (a marker, a card): it zooms as over the ground under it. */
    wheel: (e) => onWheel(e),
    tilesLoading: () => loading > 0 || Boolean(press) || Boolean(fling) || wheel.pending !== 0,
    drewReliefFallback: () => fallbackRelief,
    /** Resolves once the view has stopped and every tile it wants is drawn. */
    idle() {
      return new Promise((resolve) => {
        idleWaiters.push(resolve);
        schedule();
      });
    },
    /**
     * The view as drawn, on a canvas of its own: once it is complete, or after
     * `timeout` ms with `complete` false. The imagery on its relief alone, as
     * every tilted capture is, so `keep` has nothing to choose.
     */
    async snapshot({ timeout = 12000, ratio = null, laid: withLaid = false, into = null } = {}) {
      // a lighter level shows less on screen, never in what is filed: the capture is drawn as Full draws it
      const lighter = level !== GLOBE_QUALITY.full;
      if (lighter) {
        capturing = true;
        ratio ??= Math.min(GLOBE_QUALITY.full.pixelsMax, globalThis.devicePixelRatio || 1);
        schedule();
      }
      // drawn at `ratio` device pixels per CSS pixel for a print, as far as the GPU allows
      if (ratio) {
        const most = Math.min(8192, renderer.gl.getParameter(renderer.gl.MAX_RENDERBUFFER_SIZE) || 4096);
        const scale = Math.min(ratio, most / css.width, most / css.height);
        canvas.width = Math.max(1, Math.round(css.width * scale));
        canvas.height = Math.max(1, Math.round(css.height * scale));
        changed();
      }
      const deadline = new Promise((r) => setTimeout(() => r(false), timeout));
      const settled = api.idle().then(async () => {
        // what is laid on the ground is painted tile by tile after the tiles come
        while (withLaid && laid && drapes.waiting > 0 && !destroyed) await api.idle();
        return true;
      });
      const complete = await Promise.race([settled, deadline]);
      // drawn and copied in one go: the canvas keeps no frame once it is shown.
      // A tilted capture is the imagery on its relief alone; a plate's takes
      // what is laid on the ground and what stands on it too.
      if (raf) cancelAnimationFrame(raf);
      raf = 0;
      draping = withLaid;
      draw(performance.now());
      const copy = into ?? document.createElement('canvas');
      copy.width = canvas.width;
      copy.height = canvas.height;
      const ctx = copy.getContext('2d');
      ctx.drawImage(canvas, 0, 0);
      if (withLaid) laid?.paintMarks?.(ctx, canvas.width / css.width);
      draping = true;
      capturing = false;
      if (ratio) {
        measure();
        changed();
      }
      schedule();
      return { canvas: copy, complete };
    },
    /**
     * The ground drawn where there is no picture: `{ colour, tints, tintOpacity,
     * shade }` (renderer.js `groundUniforms`), or null for the pale stone a
     * ground waits for its picture on.
     */
    setGround(style) {
      look = { ...look, plain: groundUniforms(style) };
      schedule();
    },
    /** The pictures' tone, as the flat map paints a raster (renderer.js `toneUniforms`). */
    setTone(tone) {
      look = { ...look, tone: toneUniforms(tone ?? {}) };
      schedule();
    },
    on(name, handler) {
      if (!listeners.has(name)) listeners.set(name, new Set());
      listeners.get(name).add(handler);
      return () => listeners.get(name)?.delete(handler);
    },
    /**
     * The imagery the ground is drawn in: the provider's tile id (what the
     * tiles are asked for), whether it is billed, its picture size in CSS
     * pixels and the deepest level it serves. Null leaves the ground bare.
     */
    setImagery(next) {
      imagery = next
        ? { provider: next.id, metered: Boolean(next.metered), shift: Math.round(Math.log2((next.cell ?? 256) / 256)), deepest: next.deepest, shallowest: next.shallowest ?? 0 }
        : null;
      pictures.setImagery(imagery);
      schedule();
    },
    setExaggeration(next) {
      const value = Number(next) || 1;
      if (value === exaggeration) return;
      exaggeration = value;
      groundStamp += 1;
      keepClear();
      changed();
    },
    /**
     * Who paints what the flat map lays over its imagery: `{ compose(tile,
     * signal), frame({ moved }) }` (mirror.js), or null for nothing.
     */
    setLaid(next) {
      laid = next;
      drapes.invalidate();
      schedule();
    },
    /** What is laid on the ground changed over `bounds` (degrees), or everywhere. */
    invalidate(bounds = null) {
      drapes.invalidate(bounds);
      schedule();
    },
    /** Draw again: something standing on the ground changed. */
    redraw() {
      groundMoved = true;
      schedule();
    },
    /**
     * Where a point of the ground stands on screen, how far it is, and the
     * engine zoom it is seen at; null behind the eye, past the horizon, or
     * (once the view has stopped and the line was traced) behind the relief.
     */
    standingAt(lat, lon, memo = null) {
      // a mark asked every frame keeps its point until the ground under it changes
      let point = memo?.stamp === groundStamp ? memo.point : null;
      if (!point) {
        point = ecef(lat, lon, groundHeight(lat, lon) + 1);
        if (memo) {
          memo.point = point;
          memo.stamp = groundStamp;
        }
      }
      if (lens.camera !== camera || lens.width !== css.width || lens.height !== css.height) {
        lens.camera = camera;
        lens.width = css.width;
        lens.height = css.height;
        lens.axes = axes(camera);
        lens.f = focalOf(css.height);
      }
      const { forward, right, up } = lens.axes;
      const v = sub(point, camera.eye);
      const depth = dot(v, forward);
      if (depth <= 0) return null;
      const x = css.width / 2 + (dot(v, right) / depth) * lens.f;
      const y = css.height / 2 - (dot(v, up) / depth) * lens.f;
      if (x < -css.width || y < -css.height || x > 2 * css.width || y > 2 * css.height) return null;
      if (overHorizon(point)) return null;
      if (hiddenByRelief((memo && (memo.key ??= `${lat},${lon}`)) || `${lat},${lon}`, point)) return null;
      return { x, y, distance: depth };
    },
    /** The engine zoom ground `distance` metres away is seen at, at a latitude. */
    zoomAt(lat, distance) {
      return Math.log2((focalOf(css.height) * EARTH * 2 * Math.PI * Math.cos((lat * Math.PI) / 180)) / (256 * Math.max(distance, 1))) - 1;
    },
    /** Metres a screen pixel spans at a point of the ground, seen from where the eye stands. */
    metresPerPixelAt({ lat, lon }) {
      return length(sub(ecef(lat, lon, groundHeight(lat, lon)), camera.eye)) / focalOf(css.height);
    },
    /** The tiles the last frame drew: `{ z, x, y }`. */
    drawnTiles: () => lastDrawn.map(({ z, x, y }) => ({ z, x, y })),
    /** The view's size in CSS pixels. */
    size: () => ({ ...css }),
    /** The way the eye faces, degrees clockwise from north (the engine's own bearing). */
    heading: () => camera.heading,
    /** What the pointer shows over the globe. */
    setCursor(cursor) {
      canvas.style.cursor = cursor || '';
    },
    /** Metres across and down the middle of the view, as the flat façade says them. */
    viewSpanMeters() {
      const across = metresAtCentre() * css.width;
      return { across, down: metresAtCentre() * css.height };
    },
    /** The ground the view shows, as the box that holds it: corners and edges read, the sky left out. */
    viewBounds() {
      const points = [];
      for (const fx of [0, 0.25, 0.5, 0.75, 1]) {
        for (const fy of [0, 0.25, 0.5, 0.75, 1]) {
          const hit = pick(fx * css.width, fy * css.height);
          if (hit) points.push(geodetic(hit));
        }
      }
      if (!points.length) points.push(geodetic(centre().target));
      return {
        west: wrapLon(Math.min(...points.map((p) => p.lon))),
        south: Math.min(...points.map((p) => p.lat)),
        east: wrapLon(Math.max(...points.map((p) => p.lon))),
        north: Math.max(...points.map((p) => p.lat)),
      };
    },
    /** Pictures and meshes that failed are asked again. */
    retry() {
      pictures.retry();
      tree.retry();
      schedule();
    },
    destroy() {
      destroyed = true;
      if (raf) cancelAnimationFrame(raf);
      resizer.disconnect();
      canvas.removeEventListener('mousedown', onMouseDown);
      canvas.removeEventListener('pointerdown', onDown);
      canvas.removeEventListener('pointermove', onMove);
      canvas.removeEventListener('pointerup', onUp);
      canvas.removeEventListener('pointercancel', onUp);
      canvas.removeEventListener('pointerleave', onLeave);
      canvas.removeEventListener('wheel', onWheel);
      canvas.removeEventListener('contextmenu', onMenu);
      canvas.removeEventListener('webglcontextlost', onLost);
      worker.terminate();
      tree.dispose();
      pictures.dispose();
      drapes.dispose();
      renderer.dispose();
      for (const resolve of idleWaiters) resolve();
      idleWaiters = [];
      listeners.clear();
    },
  };

  schedule();
  return api;
}