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
18.2 KB
Raw Blame
/**
 * The arithmetic behind the map tools: Web Mercator, and the geodesic measures
 * drawn with it. No DOM, no extension API, no site knowledge — just numbers.
 *
 * **Why this is a second copy.** The app states these same rules in
 * `frontend/src/lib/measure.js`, and stating a rule twice is normally how the
 * two versions start disagreeing. There is no import across this boundary: the
 * extension ships as plain classic scripts with no build step, deliberately, so
 * that what the analyst loads into their browser is the file in the repo. The
 * guard is a test instead of a module system — `extensionMapMath.test.js` runs
 * both copies over the same points and fails on the first digit they disagree
 * about. Add a formula here, add it to that comparison.
 *
 * **Nothing here reads the site's map.** Where the camera is comes from the
 * address bar, parsed by the app (`engine/mapsites.py`); this turns that into
 * pixels. That is the rail the whole capture path already runs on: a coordinate
 * is what the URL says, verifiable by anyone holding the recorded link.
 *
 * **And nothing here is learned from a gesture.** How big the map is drawn is a
 * number the site wrote (a level, a height in metres, a span, a camera
 * distance), checked against a browser before it was believed
 * (`docs/MAP_SITES.md`). Measuring it off a drag instead is what put Earth's
 * drawing four times too small: a drag loses pixels to the site's threshold
 * and gains them to its glide, and one bad reading lived on through every zoom.
 * The one thing a gesture still says is *where* a site draws its centre, from a
 * zoom about a held pixel, below.
 *
 * Loaded before `mapoverlay.js` and left on `window.AzimutMapMath`.
 */

(() => {
  const TILE = 256; // the tile edge every one of these sites is scaled in
  const R = 6378137; // WGS84 equatorial radius (m) — the one Web Mercator uses
  //. Mercator sends the poles to infinity, so the projection is defined on a
  //. square and cut here. This is the value every slippy map cuts at.
  const MAX_LAT = 85.05112877980659;

  const rad = (deg) => (deg * Math.PI) / 180;
  const deg = (r) => (r * 180) / Math.PI;
  const clampLat = (lat) => Math.max(-MAX_LAT, Math.min(MAX_LAT, lat));

  /** The whole world, in CSS pixels, at this zoom. */
  function worldSize(zoom) {
    return TILE * Math.pow(2, zoom);
  }

  //. WGS84's first eccentricity — the whole difference between the two
  //. Mercators below. Anchored on the view centre they agree there and drift
  //. apart across the viewport, which measures as tens of metres at z12 and
  //. under a metre by z17. Which one a site draws in is still never assumed:
  //. a grid cell is metres wide.
  const E = 0.081819190842621;

  /** Geographic → world pixels, spherical Mercator (EPSG:3857). */
  function projectSpherical(lat, lon, zoom) {
    const size = worldSize(zoom);
    const phi = rad(clampLat(lat));
    return {
      x: ((lon + 180) / 360) * size,
      y: ((1 - Math.log(Math.tan(phi) + 1 / Math.cos(phi)) / Math.PI) / 2) * size,
    };
  }

  /** World pixels → geographic, spherical Mercator. */
  function unprojectSpherical(x, y, zoom) {
    const size = worldSize(zoom);
    const n = Math.PI - (2 * Math.PI * y) / size;
    return {
      lat: deg(Math.atan(0.5 * (Math.exp(n) - Math.exp(-n)))),
      lon: (x / size) * 360 - 180,
    };
  }

  /**
   * Geographic → world pixels, elliptical Mercator (EPSG:3395) — Yandex.
   *
   * The same map with the Earth's flattening kept in. Longitude is untouched;
   * only the northing moves, and only by a scale factor — which is why the
   * error from picking the wrong one grows with distance from the anchor
   * rather than showing up as a jump.
   */
  function projectEllipsoidal(lat, lon, zoom) {
    const size = worldSize(zoom);
    const phi = rad(clampLat(lat));
    const es = E * Math.sin(phi);
    const t = Math.tan(Math.PI / 4 + phi / 2) * Math.pow((1 - es) / (1 + es), E / 2);
    return {
      x: ((lon + 180) / 360) * size,
      y: ((1 - Math.log(t) / Math.PI) / 2) * size,
    };
  }

  /**
   * World pixels → geographic, elliptical Mercator.
   *
   * No closed form for the inverse, so it is iterated. The correction shrinks by
   * about the eccentricity squared each round, which puts eight rounds far below
   * a pixel anywhere on the map — and the loop leaves early once it stops moving.
   */
  function unprojectEllipsoidal(x, y, zoom) {
    const size = worldSize(zoom);
    const t = Math.exp((1 - (2 * y) / size) * Math.PI);
    let phi = Math.PI / 2 - 2 * Math.atan(1 / t);
    for (let i = 0; i < 8; i += 1) {
      const es = E * Math.sin(phi);
      const next =
        Math.PI / 2 - 2 * Math.atan((1 / t) * Math.pow((1 - es) / (1 + es), E / 2));
      if (Math.abs(next - phi) < 1e-12) {
        phi = next;
        break;
      }
      phi = next;
    }
    return { lat: deg(phi), lon: (x / size) * 360 - 180 };
  }

  /**
   * The flattenings we can write down, named per site by the app
   * (`engine/mapsites.py`). Unknown is a refusal rather than a default.
   */
  const PROJECTIONS = {
    webmercator: { project: projectSpherical, unproject: unprojectSpherical },
    ellipsoidal: { project: projectEllipsoidal, unproject: unprojectEllipsoidal },
  };

  function flattening(view) {
    const pair = PROJECTIONS[view?.projection];
    if (!pair) throw new Error(`no projection named "${view?.projection}"`);
    return pair;
  }

  const project = (lat, lon, zoom, how = "webmercator") =>
    PROJECTIONS[how].project(lat, lon, zoom);
  const unproject = (x, y, zoom, how = "webmercator") =>
    PROJECTIONS[how].unproject(x, y, zoom);

  /**
   * The way of writing `lon` that sits nearest `near`.
   *
   * A point a kilometre west of the antimeridian is at +179.99 and the view at
   * -179.99; subtract them raw and the point lands most of a world away, on the
   * far edge of the screen. The map wraps, so the nearest writing is the true
   * one.
   */
  function wrapNear(lon, near) {
    let out = lon;
    while (out - near > 180) out -= 360;
    while (near - out > 180) out += 360;
    return out;
  }

  /**
   * Where a point falls inside the map area, in CSS pixels of the page.
   *
   * `view` is what the URL said: `{ lat, lon, zoom, bearing }`, the camera
   * centred on the area. `area` is that rectangle, `{ x, y, w, h }` — placed
   * where this site draws its centre (`centreFromZoom`).
   */
  function toScreen(point, view, area) {
    const flat = flattening(view);
    const centre = flat.project(view.lat, view.lon, view.zoom);
    const here = flat.project(point.lat, wrapNear(point.lon, view.lon), view.zoom);
    return offsetToScreen(here.x - centre.x, here.y - centre.y, view, area);
  }

  /** The inverse: a page pixel back to a coordinate. */
  function toLatLon(at, view, area) {
    const flat = flattening(view);
    const centre = flat.project(view.lat, view.lon, view.zoom);
    const { dx, dy } = screenToOffset(at, view, area);
    return flat.unproject(centre.x + dx, centre.y + dy, view.zoom);
  }

  /**
   * A world-pixel offset from the centre, turned by the view's bearing.
   *
   * Bearing is the compass direction the map has *up* — Google Earth's `h`, and
   * the façade's own reading. So east up means north points left, which is a
   * turn of minus the bearing, not plus it.
   */
  function offsetToScreen(dx, dy, view, area) {
    const spun = turn(dx, dy, view);
    return { x: area.x + area.w / 2 + spun.dx, y: area.y + area.h / 2 + spun.dy };
  }

  /** A world-axis displacement in screen axes: the bearing applied, with no
   *  centre in it. `unturn` is the same turn the other way. */
  function turn(dx, dy, view) {
    const angle = -rad(view?.bearing || 0);
    const cos = Math.cos(angle);
    const sin = Math.sin(angle);
    return { dx: dx * cos - dy * sin, dy: dx * sin + dy * cos };
  }

  /** …and back, turning the other way. */
  function screenToOffset(at, view, area) {
    const { dx, dy } = unturn(at.x - (area.x + area.w / 2), at.y - (area.y + area.h / 2), view);
    return { dx, dy };
  }

  /**
   * A screen *displacement* back in the world's own axes.
   *
   * The same turn `screenToOffset` applies, with no centre in it: a zoom
   * anchor's offset is a vector rather than a point, and it is compared with
   * coordinates, which run along the world's axes and not the screen's.
   */
  function unturn(dx, dy, view) {
    const turn = rad(view?.bearing || 0);
    const cos = Math.cos(turn);
    const sin = Math.sin(turn);
    return { dx: dx * cos - dy * sin, dy: dx * sin + dy * cos };
  }

  // --- where the site draws its own centre ---------------------------------
  //
  // The address bar says how big. This answers "where": which pixel of
  // the window the coordinate in the address bar is actually under.
  //
  // It is not the middle of the window on every site, and the difference is not
  // small. Measured in a browser at 1600×1000: Yandex's centre sits 210 px
  // right of the window's, because its results panel is 420 px wide and the map
  // is centred in what is left; Apple's sits 67 px right; Bing's 40 px down,
  // under its header; OpenStreetMap's 27 px down, under its. Drawn on the
  // window's centre instead, every one of those is a fixed offset on the
  // ground — 90 m at z15 for Yandex — that no amount of scale accuracy touches,
  // because a pan cannot see it: slide the whole map and the offset slides with
  // it.
  //
  // A zoom can. Every one of these maps zooms about a point it holds still, so
  // that point is under the same pixel before and after while the centre
  // underneath it has moved — and the pixel that did not move is the one the
  // arithmetic below solves for. Two coordinates the site wrote, two zooms it
  // stated, one pixel this window counted; no assumption about panels, screens
  // or layout anywhere in it.

  /** How much the zoom has to have changed before the division below is worth
   *  doing. A tenth of a level is mostly the address bar's own rounding, and
   *  the answer comes out amplified by 1/(1−2^Δz). */
  const MIN_ZOOM_STEP = 0.5;

  /**
   * The pixel the site's camera centre is drawn at, from a zoom about a held
   * point — or null when this zoom cannot say.
   *
   * With `s = 2^zoom` and world coordinates `w()` taken at zoom 0, the held
   * point `P` is under the same pixel `p` before and after:
   *
   *     p = C + s₀·(w(P) − w(c₀)) = C + s₁·(w(P) − w(c₁))
   *
   * which fixes `w(P)`, and `C` with it. Both axes are solved the same way and
   * independently, so a site that is off-centre one way only says so.
   *
   * @param {object} before the view the address bar stated before the zoom
   * @param {object} after the view it states now
   * @param {{x: number, y: number}} at the pixel the zoom was made about
   */
  function centreFromZoom(before, after, at) {
    if (!before || !after || !at) return null;
    // A gesture that turned *and* zoomed cannot be read: the offset below is
    // turned by one bearing and there were two. A view held at a bearing is
    // fine, and that is what a rotated map is between two nudges of its
    // compass.
    if ((before.bearing || 0) !== (after.bearing || 0)) return null;
    if (before.zoom == null || after.zoom == null) return null;
    if (Math.abs(after.zoom - before.zoom) < MIN_ZOOM_STEP) return null;
    if (before.projection !== after.projection) return null;
    if (!PROJECTIONS[before.projection]) return null; // a view nothing can be drawn on
    const flat = flattening(before);
    const s0 = Math.pow(2, before.zoom);
    const s1 = Math.pow(2, after.zoom);
    const c0 = flat.project(before.lat, before.lon, 0);
    const c1 = flat.project(after.lat, wrapNear(after.lon, before.lon), 0);
    // Where the held point is in the world follows from the two zooms alone —
    // the bearing cancels, since the same turn carries both sides of `p = C +
    // R·s·(w(P) − w(c))`. What the turn does touch is the last step: the offset
    // taken off the held pixel is a world-axis one, and on a rotated map that
    // is not the offset the screen sees.
    const held = (axis) => (s0 * c0[axis] - s1 * c1[axis]) / (s0 - s1);
    const spun = turn(s0 * (held("x") - c0.x), s0 * (held("y") - c0.y), before);
    const centre = { x: at.x - spun.dx, y: at.y - spun.dy };
    return Number.isFinite(centre.x) && Number.isFinite(centre.y) ? centre : null;
  }

  /** How far from the centre the held point has to be before the division below
   *  says more than the address bar's own rounding does. */
  const MIN_ANCHOR_PX = 80;

  /**
   * The zoom a view is really at, from the pixel a zoom held still — even when
   * the address bar rounded the number it landed on.
   *
   * Bing is why. Its wheel moves a third of a level at a time and it writes one
   * decimal, so "15.3" is really 15.3333: a fortieth of a level, which is two
   * and a third percent of scale, which is five metres at the edge of the
   * screen. The centre solve above cannot see it — the frame is an offset, and
   * a scale error grows outward from it.
   *
   * With the frame already known, the same held point says it outright. The
   * point sits `d` pixels from the centre both before and after, so its place
   * in the world follows from the scale before it, and the scale after it
   * follows from where the centre went:
   *
   *     w(P) = w(c₀) + d/s₀      s₁ = d / (w(P) − w(c₁))
   *
   * Two things it will not do. It needs a `before` whose zoom is already exact,
   * because an error there comes straight out the other side — a whole level is
   * exact by definition, and a corrected one stays exact. And it is a
   * correction, not a replacement: an answer more than half a level from what
   * the site said is something else having moved, and is refused.
   *
   * @param {object} before the view before the zoom, at a zoom known to be true
   * @param {object} after what the address bar says now
   * @param {{x: number, y: number}} at the pixel the zoom was made about
   * @param {{x: number, y: number}} centre where this site draws its camera
   */
  function zoomFromAnchor(before, after, at, centre) {
    if (!before || !after || !at || !centre) return null;
    if ((before.bearing || 0) !== (after.bearing || 0)) return null;
    if (before.zoom == null || after.zoom == null) return null;
    if (before.projection !== after.projection) return null;
    if (!PROJECTIONS[before.projection]) return null;
    const flat = flattening(before);
    const s0 = Math.pow(2, before.zoom);
    const c0 = flat.project(before.lat, before.lon, 0);
    const c1 = flat.project(after.lat, wrapNear(after.lon, before.lon), 0);
    // the held pixel's offset from the centre, in the world's axes — which is
    // the frame the two coordinates below are measured in
    const held = unturn(at.x - centre.x, at.y - centre.y, before);
    const offsets = { x: held.dx, y: held.dy };
    const solve = (axis) => {
      const d = offsets[axis];
      if (Math.abs(d) < MIN_ANCHOR_PX) return null;
      const span = c0[axis] + d / s0 - c1[axis];
      if (!span || !Number.isFinite(span)) return null;
      const zoom = Math.log2(d / span);
      return Number.isFinite(zoom) ? zoom : null;
    };
    // the axis whose anchor sits furthest from the centre divides by the most
    const wide = Math.abs(offsets.x) >= Math.abs(offsets.y);
    const first = wide ? solve("x") : solve("y");
    const other = wide ? solve("y") : solve("x");
    const zoom = first ?? other;
    if (zoom == null) return null;
    return Math.abs(zoom - after.zoom) <= 0.5 ? zoom : null;
  }

  // --- geodesic measures (mirrored from lib/measure.js) --------------------

  /** Great-circle distance between two points, in metres (haversine). */
  function haversine(a, b) {
    const dLat = rad(b.lat - a.lat);
    const dLon = rad(b.lon - a.lon);
    const s =
      Math.sin(dLat / 2) ** 2 +
      Math.cos(rad(a.lat)) * Math.cos(rad(b.lat)) * Math.sin(dLon / 2) ** 2;
    return 2 * R * Math.asin(Math.min(1, Math.sqrt(s)));
  }

  /** Total length of a clicked path, in metres. */
  function pathLength(points) {
    let total = 0;
    for (let i = 1; i < points.length; i += 1) total += haversine(points[i - 1], points[i]);
    return total;
  }

  /** Area of a closed polygon on the sphere, in square metres. */
  function polygonArea(points) {
    if (points.length < 3) return 0;
    let sum = 0;
    for (let i = 0; i < points.length; i += 1) {
      const a = points[i];
      const b = points[(i + 1) % points.length];
      sum += rad(b.lon - a.lon) * (2 + Math.sin(rad(a.lat)) + Math.sin(rad(b.lat)));
    }
    return Math.abs((sum * R * R) / 2);
  }

  const FT_PER_M = 3.28084;
  const FT_PER_MI = 5280;
  const SQFT_PER_ACRE = 43560;
  const SQMI_PER_SQM = 3.861021585e-7;

  //. Written exactly as `lib/measure.js` writes them — the cross-check test
  //. compares the two strings, not just the two numbers, because a readout that
  //. reads differently in the extension is a second answer to one question.
  function formatDistance(m, units = "metric") {
    if (units === "imperial") {
      const ft = m * FT_PER_M;
      if (ft < FT_PER_MI) return `${ft < 10 ? ft.toFixed(1) : Math.round(ft)} ft`;
      const mi = ft / FT_PER_MI;
      return `${mi.toFixed(mi < 10 ? 2 : 1)} mi`;
    }
    if (m < 1000) return `${m < 10 ? m.toFixed(1) : Math.round(m)} m`;
    return `${(m / 1000).toFixed(m < 10000 ? 2 : 1)} km`;
  }

  function formatArea(m2, units = "metric") {
    if (units === "imperial") {
      const sqft = m2 * FT_PER_M * FT_PER_M;
      if (sqft < SQFT_PER_ACRE) return `${Math.round(sqft)} ft²`;
      const sqmi = m2 * SQMI_PER_SQM;
      if (sqmi < 1) return `${(sqft / SQFT_PER_ACRE).toFixed(2)} acres`;
      return `${sqmi.toFixed(2)} mi²`;
    }
    if (m2 < 10000) return `${Math.round(m2)} m²`;
    if (m2 < 1e6) return `${(m2 / 10000).toFixed(2)} ha`;
    return `${(m2 / 1e6).toFixed(2)} km²`;
  }

  // Exported: what another file or a test actually calls. The projections'
  // primitives are here because the round trip through them is the property
  // that pins this file down; everything else stays inside it.
  window.AzimutMapMath = {
    project,
    unproject,
    centreFromZoom,
    zoomFromAnchor,
    MIN_ZOOM_STEP,
    toScreen,
    toLatLon,
    turn,
    unturn,
    MIN_ANCHOR_PX,
    haversine,
    pathLength,
    polygonArea,
    formatDistance,
    formatArea,
  };
})();