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.

9.3 KB
Raw Blame
import * as Cesium from 'cesium';
import { wrapLon } from './tileMath.js';

/** Equirectangular metres between {lon, lat} points, the short way round ±180°; street scale. */
export function metresBetween(a, b) {
  const lat = (((a.lat + b.lat) / 2) * Math.PI) / 180;
  return Math.hypot(
    wrapLon(b.lon - a.lon) * 111_320 * Math.cos(lat),
    (b.lat - a.lat) * 110_540,
  );
}

/** Whether a height (m) is plausible ellipsoidal land: Dead Sea to Everest, with geoid slack. */
export function plausibleSurfaceHeight(height) {
  return Number.isFinite(height) && height >= -500 && height <= 9000;
}

/**
 * Height (m) of the rendered surface, 3D tiles included, at `carto`; null
 * when unsampleable or implausible (`sampleHeight` reads kilometres
 * underground before tiles load).
 */
export function sampledSurfaceHeight(scene, carto) {
  let height = null;
  try {
    if (scene?.sampleHeightSupported) height = scene.sampleHeight(carto);
  } catch {
    /* not sampleable yet */
  }
  return plausibleSurfaceHeight(height) ? height : null;
}

/**
 * Ellipsoidal height (m) of the ground under the camera, or null. Under
 * Google 3D (globe hidden) the rendered surface counts, minus any roof above
 * the camera.
 */
export function groundUnderCamera(viewer) {
  const carto = viewer?.camera?.positionCartographic;
  const scene = viewer?.scene;
  if (!carto || !scene) return null;
  const globe = scene.globe;
  if (globe && globe.show !== false) {
    const ground = globe.getHeight?.(carto);
    if (Number.isFinite(ground)) return ground;
  }
  const sampled = sampledSurfaceHeight(scene, carto);
  return sampled !== null && sampled < carto.height ? sampled : null;
}

/** The ellipsoid `height` metres above `ellipsoid` (the ground at that height). */
function raisedEllipsoid(ellipsoid, height) {
  if (!Number.isFinite(height) || Math.abs(height) < 1) return ellipsoid;
  const { x, y, z } = ellipsoid.radii;
  return new Cesium.Ellipsoid(x + height, y + height, z + height);
}

/**
 * Where a screen point's ray meets the ground, as a Cartographic, or null.
 * `maxRange` (metres from the camera) drops hits near the horizon.
 */
function groundHit(camera, point, ellipsoid, maxRange) {
  let cartesian = null;
  try {
    cartesian = camera.pickEllipsoid(point, ellipsoid);
  } catch {
    cartesian = null;
  }
  if (!cartesian) return null;
  if (
    Number.isFinite(maxRange) &&
    camera.positionWC &&
    Cesium.Cartesian3.distance(cartesian, camera.positionWC) > maxRange
  )
    return null;
  return Cesium.Cartographic.fromCartesian(cartesian, ellipsoid) || null;
}

/** Camera height (m) above the ground under it. */
export function cameraHeightAboveGround(viewer) {
  const carto = viewer?.camera?.positionCartographic;
  if (!carto) return null;
  return carto.height - (groundUnderCamera(viewer) ?? 0);
}

/** Screen rays per side, less one, that `visibleBbox` casts. */
const BBOX_GRID = 5;

/**
 * Visible [west, south, east, north] degrees from the rays that hit the
 * ground, or null when fewer than four do. `groundHeight` raises the ellipsoid
 * to the ground (Denver is 1,600 m up); `maxRange` (m) drops far hits.
 */
export function visibleBbox(
  viewer,
  { groundHeight = null, maxRange = null } = {},
) {
  const scene = viewer?.scene;
  const camera = viewer?.camera;
  if (!scene || !camera) return null;
  const width = scene.canvas?.clientWidth || scene.canvas?.width || 0;
  const height = scene.canvas?.clientHeight || scene.canvas?.height || 0;
  const hits = [];
  if (width > 0 && height > 0) {
    const ellipsoid = raisedEllipsoid(
      scene.globe?.ellipsoid || Cesium.Ellipsoid.WGS84,
      groundHeight,
    );
    const point = new Cesium.Cartesian2();
    for (let i = 0; i <= BBOX_GRID; i++) {
      for (let j = 0; j <= BBOX_GRID; j++) {
        point.x = (width * i) / BBOX_GRID;
        point.y = (height * j) / BBOX_GRID;
        const carto = groundHit(camera, point, ellipsoid, maxRange);
        if (carto) hits.push(carto);
      }
    }
  }
  if (hits.length >= 4) {
    let west = Infinity;
    let south = Infinity;
    let east = -Infinity;
    let north = -Infinity;
    for (const carto of hits) {
      const lon = Cesium.Math.toDegrees(carto.longitude);
      const lat = Cesium.Math.toDegrees(carto.latitude);
      west = Math.min(west, lon);
      east = Math.max(east, lon);
      south = Math.min(south, lat);
      north = Math.max(north, lat);
    }
    // Hits on both sides of ±180° read as a box around the whole globe;
    // measured in 0–360° they are a narrow box across the date line, which
    // comes back as west > east (the convention tilesForBbox splits).
    if (east - west > 180) {
      let west360 = Infinity;
      let east360 = -Infinity;
      for (const carto of hits) {
        const lon = Cesium.Math.toDegrees(carto.longitude);
        const shifted = lon < 0 ? lon + 360 : lon;
        west360 = Math.min(west360, shifted);
        east360 = Math.max(east360, shifted);
      }
      if (east360 - west360 < east - west) {
        west = west360 > 180 ? west360 - 360 : west360;
        east = east360 > 180 ? east360 - 360 : east360;
      }
    }
    if (west !== east && north - south > 0) return [west, south, east, north];
  }
  return null;
}

/** The point on the ground under the camera, as {lon, lat} degrees. */
export function cameraNadir(viewer) {
  const carto = viewer?.camera?.positionCartographic;
  if (!carto) return null;
  return {
    lon: Cesium.Math.toDegrees(carto.longitude),
    lat: Cesium.Math.toDegrees(carto.latitude),
  };
}

/**
 * Where coverage tiles are ranked from: halfway between the nadir and the
 * screen centre's ground, or the nadir when that is out of `maxRange`.
 */
export function viewFocus(
  viewer,
  { groundHeight = null, maxRange = null } = {},
) {
  const nadir = cameraNadir(viewer);
  const scene = viewer?.scene;
  const width = scene?.canvas?.clientWidth || scene?.canvas?.width || 0;
  const height = scene?.canvas?.clientHeight || scene?.canvas?.height || 0;
  if (!nadir || !width || !height) return nadir;
  const hit = groundHit(
    viewer.camera,
    new Cesium.Cartesian2(width / 2, height / 2),
    raisedEllipsoid(
      scene.globe?.ellipsoid || Cesium.Ellipsoid.WGS84,
      groundHeight,
    ),
    maxRange,
  );
  if (!hit) return nadir;
  const ahead = {
    lon: Cesium.Math.toDegrees(hit.longitude),
    lat: Cesium.Math.toDegrees(hit.latitude),
  };
  return {
    lon: wrapLon(nadir.lon + wrapLon(ahead.lon - nadir.lon) / 2),
    lat: (nadir.lat + ahead.lat) / 2,
  };
}

/**
 * Horizon occluder depth below WGS84 (m): ground can lie below the ellipsoid
 * (NYC −22 m), and an occluder at 0 m would hide the cones around it.
 */
const HORIZON_CULL_DEPTH_M = 1000;
const HORIZON_CULL_ELLIPSOID = new Cesium.Ellipsoid(
  Cesium.Ellipsoid.WGS84.radii.x - HORIZON_CULL_DEPTH_M,
  Cesium.Ellipsoid.WGS84.radii.y - HORIZON_CULL_DEPTH_M,
  Cesium.Ellipsoid.WGS84.radii.z - HORIZON_CULL_DEPTH_M,
);

/**
 * Hide billboards and points behind the horizon: they skip the depth test, so
 * nothing else stops the far side drawing through the globe. Re-culls on
 * pre-render after the camera moves; stops when nothing is left to cull.
 * @param {{getViewer: () => object|null, items: () => Iterable<{position: object, show: boolean}>, onChange?: () => void}} options
 */
export function createHorizonCull({ getViewer, items, onChange }) {
  const occluder = new Cesium.EllipsoidalOccluder(HORIZON_CULL_ELLIPSOID);
  let from = null;
  let stopListening = null;

  /** Show what is in front of the horizon, hide the rest; the count seen. */
  function cull(list, position) {
    occluder.cameraPosition = position;
    let seen = 0;
    let changed = false;
    for (const item of list) {
      seen++;
      const show = occluder.isPointVisible(item.position);
      if (item.show !== show) {
        item.show = show;
        changed = true;
      }
    }
    if (changed) onChange?.();
    return seen;
  }

  /** Cull everything from the camera at `position`; the count seen. */
  function cullAll(position) {
    from = Cesium.Cartesian3.clone(position, from);
    return cull(items(), position);
  }

  function onPreRender() {
    const position = getViewer()?.camera?.positionWC;
    if (!position || (from && Cesium.Cartesian3.equals(from, position))) return;
    if (!cullAll(position)) stop();
  }

  /** Cull `added` items (or all) now, then all again whenever the camera moves. */
  function update(added) {
    const viewer = getViewer();
    const position = viewer?.camera?.positionWC;
    if (position && !(added ? cull(added, position) : cullAll(position)))
      return;
    stopListening ||=
      viewer?.scene?.preRender?.addEventListener(onPreRender) || null;
  }

  function stop() {
    stopListening?.();
    stopListening = null;
    from = null;
  }

  return { update, stop };
}

/** The middle of the visible ground, else the point under the camera; null without a camera. */
export function viewCentre(viewer) {
  if (!viewer) return null;
  const bbox = visibleBbox(viewer);
  if (bbox) {
    // Across the date line (west > east) the middle is on the far side of 0°.
    const span = bbox[2] - bbox[0] + (bbox[0] > bbox[2] ? 360 : 0);
    let lon = bbox[0] + span / 2;
    if (lon > 180) lon -= 360;
    return { lat: (bbox[1] + bbox[3]) / 2, lon };
  }
  const carto = viewer.camera?.positionCartographic;
  if (!carto) return null;
  return {
    lat: Cesium.Math.toDegrees(carto.latitude),
    lon: Cesium.Math.toDegrees(carto.longitude),
  };
}