leaflet-city-mapper 0.0.1 → 0.0.3

package/src/sources/updateArea.js

@@ -0,0 +1,45 @@
+import { pump } from "./pump.js";
+import { releaseArea } from './releaseArea.js';
+import { compareAreaDistance } from './compareAreaDistance.js';
+
+/** Cover the visible ground bounds and one bordering block, clipped to the archive. */
+
+export function updateArea(backend) {
+  if (!backend._map || !backend._shared) return;
+  if (backend._geojson) {
+    if (!backend._areas.has('geojson')) {
+      backend._areas.set('geojson', { request: new AbortController() });
+    }
+    pump(backend);
+    return;
+  }
+  if (!backend.header) return;
+  const z = backend.header.minZoom;
+  const center = backend._map.project(backend._map.getCenter(), z).divideBy(256).floor();
+  const bounds = backend._map.getBounds();
+  const nw = backend._map.project(bounds.getNorthWest(), z).divideBy(256).floor();
+  const se = backend._map.project(bounds.getSouthEast(), z).divideBy(256).floor();
+  const archiveNW = backend._map.project([backend.header.maxLat, backend.header.minLon], z).divideBy(256).floor();
+  const archiveSE = backend._map.project([backend.header.minLat, backend.header.maxLon], z).divideBy(256).floor();
+  const wanted = new Map();
+  let x, y, key, area, coords;
+  for (x = Math.max(0, nw.x - 1, archiveNW.x); x <= Math.min(2 ** z - 1, se.x + 1, archiveSE.x); x++) {
+    for (y = Math.max(0, nw.y - 1, archiveNW.y); y <= Math.min(2 ** z - 1, se.y + 1, archiveSE.y); y++) {
+      wanted.set(`${x}/${y}`, { z, x, y });
+    }
+  }
+  for ([key, area] of backend._areas) {
+    if (!wanted.has(key)) {
+      releaseArea(backend, area);
+      backend._areas.delete(key);
+    }
+  }
+  // Load the nearest new blocks first without rebuilding retained geometry.
+  const areas = [];
+  for ([key, coords] of wanted) areas.push([key, coords, center]);
+  areas.sort(compareAreaDistance);
+  for ([key, coords] of areas) {
+    if (!backend._areas.has(key)) backend._areas.set(key, { coords, request: new AbortController() });
+  }
+  pump(backend);
+}

package/src/sources/updateStatus.js

@@ -0,0 +1,12 @@
+/** Emit a snapshot for consumers; ready does not wait for all neighborhood tasks. */
+export function updateStatus(backend, enabled = true) {
+  const progress = { enabled, loaded: 0, skipped: 0, pending: 0, errors: [] };
+  let area;
+  for (area of backend._areas.values()) {
+    if (area.error) progress.errors.push(area.error);
+    else if (!area.done) progress.pending++;
+    progress.loaded += area.buildings ?? 0;
+    progress.skipped += area.skipped ?? 0;
+  }
+  backend.fire('progress', progress);
+}

package/src/sunlight/addTimeLayer.js

@@ -0,0 +1,3 @@
+export function addTimeLayer(map) {
+  return this.control.addTo(map);
+}

package/src/sunlight/addTo.js

@@ -0,0 +1,10 @@
+import { underEntry } from '../scene/underEntry.js';
+import { styleTimeControl } from './styleTimeControl.js';
+
+export function addTo(map) {
+  L.Control.prototype.addTo.call(this, map);
+  const container = this.getContainer();
+  if (this.layer._map === map) underEntry(this.layer, container, styleTimeControl.bind(null, container));
+  else styleTimeControl(container, false);
+  return this;
+}

package/src/sunlight/atmosphere.js

@@ -0,0 +1,28 @@
+
+import { mix } from './mix.js';
+import { rgb } from './rgb.js';
+
+export function atmosphere(altitude) {
+  if (!Number.isFinite(altitude)) {
+    throw new Error('Invalid solar altitude');
+  }
+  const stops = [
+    [-18, [3, 7, 20], [17, 28, 54], [0.025, 0.04, 0.09]],
+    [-6, [37, 53, 84], [182, 106, 86], [0.12, 0.10, 0.14]],
+    [0, [101, 131, 171], [246, 170, 115], [0.38, 0.24, 0.18]],
+    [10, [74, 147, 208], [197, 221, 237], [0.80, 0.75, 0.68]],
+    [25, [53, 144, 213], [223, 238, 250], [1, 1, 1]],
+  ];
+  let upper = -1;
+  let i;
+  for (i = 0; i < stops.length; i++) {
+    if (stops[i][0] >= altitude) { upper = i; break; }
+  }
+  const b = stops[upper < 0 ? stops.length - 1 : upper],
+        a = stops[Math.max(0, upper - 1)];
+  const t = a === b || upper < 0 ? 1 : (altitude - a[0]) / (b[0] - a[0]);
+  return {
+    background: `linear-gradient(${rgb(mix(a[1], b[1], t))}, ${rgb(mix(a[2], b[2], t))})`,
+    tint: mix(a[3], b[3], t),
+  };
+}

package/src/sunlight/horizontalPosition.js

@@ -0,0 +1,16 @@
+
+export function horizontalPosition(d, lat, lng, ascension, declination) {
+  const rad = Math.PI / 180;
+  const hourAngle = (280.16 + 360.9856235 * d + lng) * rad - ascension;
+  const latitude = lat * rad;
+  const altitude = Math.asin(Math.sin(latitude) * Math.sin(declination) +
+    Math.cos(latitude) * Math.cos(declination) * Math.cos(hourAngle));
+  const southAzimuth = Math.atan2(Math.sin(hourAngle),
+    Math.cos(hourAngle) * Math.sin(latitude) - Math.tan(declination) * Math.cos(latitude));
+  const azimuth = (southAzimuth / rad + 180 + 360) % 360;
+  return {
+    altitude: altitude / rad, azimuth,
+    direction: [Math.sin(azimuth * rad) * Math.cos(altitude), Math.sin(altitude),
+    -Math.cos(azimuth * rad) * Math.cos(altitude)]
+  };
+}

package/src/sunlight/initSunlight.js

@@ -0,0 +1,14 @@
+import { onAddSun } from './onAddSun.js';
+import { underEntry } from '../scene/underEntry.js';
+import { initialize } from './initialize.js';
+import { onAdd } from './onAdd.js';
+import { addTo } from './addTo.js';
+import { remove } from './remove.js';
+
+L.Control.Time = L.Control.extend({
+  options: { position: 'bottomright' },
+  initialize,
+  onAdd,
+  addTo,
+  remove,
+});

package/src/sunlight/initialize.js

@@ -0,0 +1,11 @@
+import { addTimeLayer } from './addTimeLayer.js';
+import { removeTimeLayer } from './removeTimeLayer.js';
+
+export function initialize(options) {
+  L.Util.setOptions(this, options);
+  this.live = true;
+  this.layer = new L.Layer();
+  this.layer.control = this;
+  this.layer.onAdd = addTimeLayer;
+  this.layer.onRemove = removeTimeLayer;
+}

package/src/sunlight/mix.js

@@ -0,0 +1,6 @@
+export function mix(a, b, t) {
+  const values = [];
+  let i;
+  for (i = 0; i < a.length; i++) values.push(a[i] + (b[i] - a[i]) * t);
+  return values;
+}

package/src/sunlight/moonPosition.js

@@ -0,0 +1,17 @@
+import { solarPosition } from "./solarPosition.js";
+import { horizontalPosition } from "./horizontalPosition.js";
+
+// Low-precision geocentric lunar orbit; no parallax or atmospheric refraction.
+
+export function moonPosition(date, lat, lng) {
+  solarPosition(date, lat, lng);
+  const rad = Math.PI / 180, d = new Date(date).getTime() / 86400000 - 10957.5;
+  const anomaly = (134.963 + 13.064993 * d) * rad;
+  const longitude = (218.316 + 13.176396 * d + 6.289 * Math.sin(anomaly)) * rad;
+  const latitude = 5.128 * Math.sin((93.272 + 13.229350 * d) * rad) * rad;
+  const obliquity = 23.4397 * rad;
+  const x = Math.cos(latitude) * Math.cos(longitude);
+  const y = Math.cos(latitude) * Math.sin(longitude) * Math.cos(obliquity) - Math.sin(latitude) * Math.sin(obliquity);
+  const z = Math.cos(latitude) * Math.sin(longitude) * Math.sin(obliquity) + Math.sin(latitude) * Math.cos(obliquity);
+  return horizontalPosition(d, lat, lng, Math.atan2(y, x), Math.asin(z));
+}

package/src/sunlight/onAdd.js

@@ -0,0 +1,5 @@
+import { onAddSun } from './onAddSun.js';
+
+export function onAdd(map) {
+  return onAddSun(this, map);
+}

package/src/sunlight/onAddSun.js

@@ -0,0 +1,66 @@
+import { cityMapper } from '../constants/cityMapper.js';
+import { update as updateScene } from '../scene/update.js';
+import { atmosphere } from './atmosphere.js';
+import { moonPosition } from './moonPosition.js';
+import { projectCelestialBody } from './projectCelestialBody.js';
+import { solarPosition } from './solarPosition.js';
+import { updateSky } from './updateSky.js';
+import { render } from './render.js';
+import { updateSun } from './updateSun.js';
+import { useLiveTime } from './useLiveTime.js';
+import { useSelectedTime } from './useSelectedTime.js';
+import { tickSun } from './tickSun.js';
+import { removeSun } from './removeSun.js';
+
+export function onAddSun(control, map) {
+  map._timeControl = control;
+  const originalSky = map.getContainer().style.getPropertyValue('--leaflet-sky-background');
+  const disc = 'position:absolute;width:18px;height:18px;border-radius:50%;transform:translate(-50%,-50%);pointer-events:none;';
+  const sunDisc = L.DomUtil.create('div', 'sunlight-sun');
+  const moonDisc = L.DomUtil.create('div', 'sunlight-moon');
+  sunDisc.style.cssText = disc + 'background:#fff3bd;box-shadow:0 0 18px 7px #ffd27699;';
+  moonDisc.style.cssText = disc + 'background:#dce5f2;box-shadow:0 0 10px 2px #cbdcff55;';
+  sunDisc.setAttribute('role', 'img'); sunDisc.setAttribute('aria-label', 'Sun');
+  moonDisc.setAttribute('role', 'img'); moonDisc.setAttribute('aria-label', 'Moon');
+  const container = L.DomUtil.create('div', 'sunlight-control');
+  container.style.cssText = 'color:#222;width:min(200px,calc(100vw - 60px));font:12px/1.4 sans-serif;';
+  const date = document.createElement('input');
+  date.type = 'date';
+  date.style.cssText = 'width:100%;box-sizing:border-box;';
+  date.setAttribute('aria-label', 'Solar date (UTC)');
+  const slider = document.createElement('input');
+  slider.type = 'range';
+  slider.style.cssText = 'width:100%;box-sizing:border-box;margin:10px 0 4px;cursor:pointer;';
+  slider.min = '0'; slider.max = '1439'; slider.step = '1';
+  slider.setAttribute('aria-label', 'Time of day (UTC)');
+  const output = document.createElement('output');
+  output.style.cssText = 'font-weight:bold;font-variant-numeric:tabular-nums;';
+  output.setAttribute('aria-live', 'off');
+  const now = document.createElement('button');
+  now.type = 'button'; now.textContent = 'Now';
+  const timeRow = document.createElement('div');
+  timeRow.className = 'sunlight-time';
+  timeRow.style.cssText = 'display:flex;justify-content:space-between;align-items:center;';
+  timeRow.append(output, now);
+  const status = document.createElement('div');
+  status.className = 'sunlight-status';
+  status.style.marginTop = '5px';
+  status.setAttribute('role', 'status');
+  const note = document.createElement('small');
+  note.style.color = '#555';
+  note.textContent = 'Indicative · loaded geometry only. Streetlight illumination is estimated, not measured lux.';
+  container.append(date, slider, timeRow, status, note);
+  const state = { control, map, originalSky, sunDisc, moonDisc, date, slider, output, status };
+  state.update = updateSun.bind(null, state);
+  state.updateSky = updateSky.bind(null, state);
+  now.onclick = useLiveTime.bind(null, state);
+  date.onchange = slider.oninput = useSelectedTime.bind(null, state);
+  L.DomEvent.disableClickPropagation(container);
+  L.DomEvent.disableScrollPropagation(container);
+  state.update();
+  state.timer = setInterval(tickSun, 60000, state);
+  map.on('moveend', state.update);
+  map.on('move rotate pitch resize', state.updateSky);
+  control.onRemove = removeSun.bind(null, state);
+  return container;
+}

package/src/sunlight/projectCelestialBody.js

@@ -0,0 +1,13 @@
+/** Perspective projection of a celestial direction; null when behind the camera. */
+
+export function projectCelestialBody(dir, size, pitch, bearing) {
+  const [x, y, z] = dir;
+  const forward = -x * Math.sin(bearing) * Math.sin(pitch) - y * Math.cos(pitch) - z * Math.cos(bearing) * Math.sin(pitch);
+  if (forward > 0) {
+    return {
+      left: size.x / 2 + size.y * 1.5 * (x * Math.cos(bearing) - z * Math.sin(bearing)) / forward,
+      top:  size.y / 2 - size.y * 1.5 * (-x * Math.sin(bearing) * Math.cos(pitch) + y * Math.sin(pitch) - z * Math.cos(bearing) * Math.cos(pitch)) / forward
+    };
+  }
+  return null;
+}

package/src/sunlight/remove.js

@@ -0,0 +1,7 @@
+export function remove() {
+  if (this._map?.hasLayer(this.layer)) {
+    this._map.removeLayer(this.layer);
+    return this;
+  }
+  return L.Control.prototype.remove.call(this);
+}

package/src/sunlight/removeSun.js

@@ -0,0 +1,15 @@
+import { render } from './render.js';
+import { updateSky } from './updateSky.js';
+
+export function removeSun(state) {
+  const { map, timer, sunDisc, moonDisc } = state;
+  clearInterval(timer);
+  delete map._timeControl;
+  map.fire('simulationtimechange', { time: null, live: false });
+  map.off('moveend', state.update);
+  map.off('move rotate pitch resize', state.updateSky);
+  delete map._sunlight;
+  updateSky(state);
+  sunDisc.remove(); moonDisc.remove();
+  render(map);
+}

package/src/sunlight/removeTimeLayer.js

@@ -0,0 +1,3 @@
+export function removeTimeLayer() {
+  return L.Control.prototype.remove.call(this.control);
+}

package/src/sunlight/render.js

@@ -0,0 +1,7 @@
+import { cityMapper } from '../constants/cityMapper.js';
+import { update as updateScene } from '../scene/update.js';
+
+export function render(map) {
+  const renderer = cityMapper.renderers.get(map);
+  if (renderer) updateScene(renderer);
+}

package/src/sunlight/rgb.js

@@ -0,0 +1,6 @@
+export function rgb(values) {
+  const rounded = [];
+  let value;
+  for (value of values) rounded.push(Math.round(value));
+  return `rgb(${rounded.join(', ')})`;
+}

package/src/sunlight/solarPosition.js

@@ -0,0 +1,17 @@
+import { horizontalPosition } from "./horizontalPosition.js";
+
+// Solar centre, without atmospheric refraction.
+
+export function solarPosition(date, lat, lng) {
+  const time = new Date(date).getTime();
+  if (!Number.isFinite(time) || !Number.isFinite(lat) || Math.abs(lat) > 90 ||
+    !Number.isFinite(lng) || Math.abs(lng) > 180) throw new Error('Invalid solar date or location');
+  const rad = Math.PI / 180, d = time / 86400000 - 10957.5;
+  const mean = (357.5291 + 0.98560028 * d) * rad;
+  const longitude = mean + (1.9148 * Math.sin(mean) + 0.02 * Math.sin(2 * mean) +
+    0.0003 * Math.sin(3 * mean) + 102.9372 + 180) * rad;
+  const obliquity = 23.4397 * rad;
+  const declination = Math.asin(Math.sin(longitude) * Math.sin(obliquity));
+  const ascension = Math.atan2(Math.sin(longitude) * Math.cos(obliquity), Math.cos(longitude));
+  return horizontalPosition(d, lat, lng, ascension, declination);
+}

package/src/sunlight/styleTimeControl.js

@@ -0,0 +1,7 @@
+export function styleTimeControl(container, nested) {
+  container.classList.toggle('leaflet-control', !nested);
+  container.classList.toggle('leaflet-bar', !nested);
+  Object.assign(container.style, nested
+    ? { background: '', padding: '2px 0 6px 20px', margin: '0' }
+    : { background: '#fff', padding: '8px', margin: '' });
+}

package/src/sunlight/tickSun.js

@@ -0,0 +1,5 @@
+import { updateSun } from './updateSun.js';
+
+export function tickSun(state) {
+  if (state.control.live) updateSun(state);
+}

package/src/sunlight/updateSky.js

@@ -0,0 +1,20 @@
+import { projectCelestialBody } from './projectCelestialBody.js';
+
+export function updateSky({ map, originalSky, sunDisc, moonDisc }) {
+  const sun = map._sunlight, sky = map._pitchSky;
+  if (sun) map.getContainer().style.setProperty('--leaflet-sky-background', sun.background);
+  else if (originalSky) map.getContainer().style.setProperty('--leaflet-sky-background', originalSky);
+  else map.getContainer().style.removeProperty('--leaflet-sky-background');
+  const size = map.getSize(), pitch = map.getPitch() * Math.PI / 180, bearing = map.getBearing() * Math.PI / 180;
+  let disc, body, point, left, top;
+  for ([disc, body] of [[sunDisc, sun], [moonDisc, sun?.moon]]) {
+    disc.hidden = true;
+    if (!sky || !body || body.altitude <= 0 || !sun) continue;
+    if (disc.parentNode !== sky) sky.append(disc);
+    point = projectCelestialBody(body.direction, size, pitch, bearing);
+    if (!point) continue;
+    ({ left, top } = point);
+    disc.hidden = left < 0 || left > size.x || top < 0 || top > sky.clientHeight || sky.style.display === 'none';
+    disc.style.left = `${left}px`; disc.style.top = `${top}px`;
+  }
+}

package/src/sunlight/updateSun.js

@@ -0,0 +1,34 @@
+import { atmosphere } from './atmosphere.js';
+import { moonPosition } from './moonPosition.js';
+import { solarPosition } from './solarPosition.js';
+import { render } from './render.js';
+import { updateSky } from './updateSky.js';
+
+export function updateSun(state) {
+  const { control, map, date, slider, output, status } = state;
+  try {
+    if (control.live) control.time = new Date();
+    const time = control.time.toISOString();
+    date.value = time.slice(0, 10);
+    slider.value = String(control.time.getUTCHours() * 60 + control.time.getUTCMinutes());
+    output.textContent = `${time.slice(11, 16)} UTC${control.live ? ' · now' : ''}`;
+    const center = map.getCenter();
+    const sun = map._sunlight = solarPosition(control.time, center.lat, center.lng);
+    Object.assign(sun, atmosphere(sun.altitude));
+    sun.moon = moonPosition(control.time, center.lat, center.lng);
+    status.textContent = sun.altitude <= 0
+      ? 'Night · no direct sunlight'
+      : sun.altitude < 3
+        ? 'Low sun · shadows paused'
+        : `Sun altitude ${sun.altitude.toFixed(1)}°`;
+    map.fire('simulationtimechange', { time: new Date(control.time), live: control.live });
+    updateSky(state);
+    render(map);
+  } catch (error) {
+    delete map._sunlight;
+    updateSky(state);
+    render(map);
+    status.textContent = `Error: ${error.message}`;
+    console.error('Solar simulation', error);
+  }
+}

package/src/sunlight/useLiveTime.js

@@ -0,0 +1,6 @@
+import { updateSun } from './updateSun.js';
+
+export function useLiveTime(state) {
+  state.control.live = true;
+  updateSun(state);
+}

package/src/sunlight/useSelectedTime.js

@@ -0,0 +1,20 @@
+import { render } from './render.js';
+import { updateSky } from './updateSky.js';
+import { updateSun } from './updateSun.js';
+
+export function useSelectedTime(state) {
+  const { control, map, date, slider, status } = state;
+  control.live = false;
+  if (!date.value || !date.validity.valid) {
+    control.time = new Date(NaN);
+    map.fire('simulationtimechange', { time: null, live: false });
+    delete map._sunlight;
+    updateSky(state);
+    render(map);
+    status.textContent = 'Error: choose a valid solar date';
+    return;
+  }
+  control.time = new Date(`${date.value}T00:00:00Z`);
+  control.time.setUTCMinutes(Number(slider.value));
+  updateSun(state);
+}

package/src/terrain/clearLayerTerrain.js

@@ -0,0 +1,5 @@
+import { setRasterTerrain } from '../raster/setRasterTerrain.js';
+
+export function clearLayerTerrain(layer) {
+  if (layer._type === 'pmtiles') setRasterTerrain(layer, null);
+}

package/src/terrain/getElevation.js

@@ -0,0 +1,10 @@
+import { bridgeElevation } from '../geometry/bridgeElevation.js';
+import { terrainElevation } from './terrainElevation.js';
+
+/** @param {L.LatLng|L.Point} location LatLng, or a pixel point at the terrain zoom. */
+
+export function getElevation(backend, location) {
+  if (!backend._map || !backend._terrainReady) return null;
+  const point = location instanceof L.Point ? location : backend._map.project(location, backend._terrainZoom);
+  return bridgeElevation(point, backend._bridges) ?? terrainElevation(point, backend._terrainTiles);
+}

package/src/terrain/initTerrain.js

@@ -0,0 +1,20 @@
+import { onTerrainRemove } from './onTerrainRemove.js';
+import { onTerrainAdd } from './onTerrainAdd.js';
+import { init3D } from '../scene/init3D.js';
+
+/**
+ * Renders IGN Float32 DEM tiles and PMTiles raster basemaps in the shared WebGPU scene.
+ * Source options: `url` (single-zoom Float32 PMTiles DEM); `bridges` (optional GeoJSON deck polygons with Z, see _addBridges).
+ */
+export function initTerrain(layer, options) {
+  const terrainSource = options.url;
+  const layerOptions = { ...options };
+  delete layerOptions.url;
+  init3D(layer, layerOptions);
+  layer.terrainSource = terrainSource;
+  layer._terrainTiles = new Map();
+  layer._rasterTiles = new Map();
+  layer._terrainReady = false;
+  layer.onAdd = onTerrainAdd.bind(null, layer);
+  layer.onRemove = onTerrainRemove.bind(null, layer);
+}

package/src/terrain/loadReadyTerrain.js

@@ -0,0 +1,5 @@
+import { loadTerrain } from './loadTerrain.js';
+
+export function loadReadyTerrain() {
+  loadTerrain(this.backend).then(this.resolve, this.reject);
+}

package/src/terrain/loadTerrain.js

@@ -0,0 +1,63 @@
+import { addBridges } from '../geometry/addBridges.js';
+import { conformModelToTerrain } from '../geometry/conformModelToTerrain.js';
+import { getElevation } from './getElevation.js';
+import { setTerrainHeight } from './setTerrainHeight.js';
+import { update } from '../scene/update.js';
+import { compareDistance } from '../utils/compareDistance.js';
+import { loadTerrainTiles } from './loadTerrainTiles.js';
+import { readBridges } from './readBridges.js';
+
+
+export async function loadTerrain(backend) {
+  if (backend._terrainLoading || !backend._map) return;
+  backend._terrainLoading = true;
+  backend._terrainReady = false;
+  const controller = backend._terrainController = new AbortController();
+  let x, y, i, layer;
+  try {
+    if (!backend.terrainSource) throw new Error('Terrain layer requires a PMTiles elevation archive');
+    const archive = backend._terrainArchive = new L.Layer({ source: { type: 'pmtiles', url: backend.terrainSource } });
+    await archive.ready;
+    const header = archive.header;
+    if (header.tileType !== 0 || header.minZoom !== header.maxZoom) {
+      throw new Error('Expected a single-zoom Float32 PMTiles terrain archive');
+    }
+    backend._terrainZoom = header.maxZoom;
+    const map = backend._map;
+    const northwest = map.project([header.maxLat, header.minLon], backend._terrainZoom).divideBy(256).floor();
+    const southeast = map.project([header.minLat, header.maxLon], backend._terrainZoom).divideBy(256).floor();
+    backend._terrainBounds = new L.Bounds(northwest, southeast);
+    const tiles = [];
+    const center = map.project(map.getCenter(), backend._terrainZoom).divideBy(256);
+    for (x = northwest.x; x <= southeast.x; x++) {
+      for (y = northwest.y; y <= southeast.y; y++) {
+        tiles.push({ z: backend._terrainZoom, x, y, distance: Math.hypot(x + 0.5 - center.x, y + 0.5 - center.y) });
+      }
+    }
+    tiles.sort(compareDistance);
+    const state = { backend, archive, controller, tiles, next: 0 };
+    const workers = [];
+    for (i = 0; i < Math.min(4, tiles.length); i++) workers.push(loadTerrainTiles(state));
+    await Promise.all(workers);
+    const bridges = backend.options.bridges && await fetch(backend.options.bridges, { signal: controller.signal })
+      .then(readBridges);
+    if (controller.signal.aborted || backend._map !== map) return;
+    backend._terrainReady = true;
+    backend._terrainOriginElevation = getElevation(backend, backend.location) ?? 0;
+    for (layer of Object.values(map._layers)) {
+      setTerrainHeight(layer);
+      conformModelToTerrain(layer, backend);
+    }
+
+    if (bridges) addBridges(backend, bridges);
+    map.fire('terrainchange');
+    update(backend);
+    backend.fire('terrainready');
+    return true;
+  } catch (error) {
+    if (!controller.signal.aborted) backend.fire('error', { error });
+    return false;
+  } finally {
+    backend._terrainLoading = false;
+  }
+}

package/src/terrain/loadTerrainTiles.js

@@ -0,0 +1,13 @@
+export async function loadTerrainTiles(state) {
+  const { backend, archive, controller, tiles } = state;
+  let coords, result;
+  while (state.next < tiles.length) {
+    controller.signal.throwIfAborted();
+    coords = tiles[state.next++];
+    result = await archive.getZxy(coords.z, coords.x, coords.y, controller.signal);
+    if (!result || result.data.byteLength !== 256 * 256 * 4) {
+      throw new Error(`Missing or invalid Float32 terrain tile ${coords.z}/${coords.x}/${coords.y}`);
+    }
+    backend._terrainTiles.set(`${coords.x}/${coords.y}`, new Float32Array(result.data));
+  }
+}

package/src/terrain/onTerrainAdd.js

@@ -0,0 +1,21 @@
+import { loadTerrain } from "./loadTerrain.js";
+import { setRasterTerrain } from '../raster/setRasterTerrain.js';
+import { onAdd3DLayer } from '../scene/onAdd3DLayer.js';
+import { loadReadyTerrain } from './loadReadyTerrain.js';
+import { setLayerTerrain } from './setLayerTerrain.js';
+
+export function onTerrainAdd(backend, map) {
+  if (map._terrain3D && map._terrain3D !== backend) {
+    throw new Error('Only one terrain layer can be active per map');
+  }
+  map._terrain3D = backend;
+  onAdd3DLayer(backend, map);
+  if (backend.root) backend._terrainPromise = loadTerrain(backend);
+  else {
+    const pending = Promise.withResolvers();
+    backend._terrainPromise = pending.promise;
+    backend.once('ready', loadReadyTerrain, { backend, ...pending });
+  }
+  map.eachLayer(setLayerTerrain, backend);
+  map.fire('terrainchange');
+}

package/src/terrain/onTerrainChange.js

@@ -0,0 +1,14 @@
+import { releaseArea } from '../sources/releaseArea.js';
+import { updateArea } from "../sources/updateArea.js";
+
+/** GeoJSON source areas: loading, building and releasing. */
+
+export function onTerrainChange(layer) {
+  if (!layer._map) return;
+  let area;
+  for (area of layer._areas.values()) {
+    releaseArea(layer, area);
+  }
+  layer._areas.clear();
+  updateArea(layer);
+}

package/src/terrain/onTerrainRemove.js

@@ -0,0 +1,41 @@
+import { destroyTexture } from '../rendering/destroyTexture.js';
+import { conformModelToTerrain } from '../geometry/conformModelToTerrain.js';
+import { disposeMesh } from '../rendering/disposeMesh.js';
+import { setRasterTerrain } from '../raster/setRasterTerrain.js';
+import { removeRasterTile } from '../raster/removeRasterTile.js';
+import { setTerrainHeight } from './setTerrainHeight.js';
+import { onRemove3DLayer } from '../scene/onRemove3DLayer.js';
+import { clearLayerTerrain } from './clearLayerTerrain.js';
+
+export function onTerrainRemove(layer, map) {
+  layer._terrainController?.abort();
+  layer._terrainLoading = false;
+  layer._terrainReady = false;
+  map.eachLayer(clearLayerTerrain);
+  let tile, l, grid, attribute;
+  for (tile of layer._rasterTiles.keys()) removeRasterTile(layer, tile);
+  if (map._terrain3D === layer) delete map._terrain3D;
+  for (l of Object.values(map._layers)) {
+    conformModelToTerrain(l, null);
+    setTerrainHeight(l);
+  }
+
+  map.fire('terrainchange');
+  layer._terrainTiles.clear();
+  layer._terrainOriginElevation = 0;
+  layer._terrainPromise = null;
+  if (layer._rasterProgram) {
+    layer._rasterProgram.pipelineCache.clear();
+  }
+  layer._rasterProgram = null;
+  if (layer._dem) destroyTexture(layer, layer._dem.texture);
+  layer._dem = null;
+  for (grid of layer._terrainGrids?.values() || []) {
+    for (attribute of Object.values(grid)) destroyTexture(layer, attribute.buffer);
+  }
+  layer._terrainGrids = null;
+  layer._bridges = null;
+  disposeMesh(layer, layer._bridgeMesh);
+  layer._bridgeMesh = null;
+  onRemove3DLayer(layer, map);
+}

package/src/terrain/readBridges.js

@@ -0,0 +1,4 @@
+export function readBridges(response) {
+  if (!response.ok) throw new Error(`Bridges: HTTP ${response.status}`);
+  return response.json();
+}