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), }; }