leaflet-city-mapper 0.0.1 → 0.0.3

package/src/raster/addRasterTile.js

@@ -0,0 +1,114 @@
+import { cityMapper } from '../constants/cityMapper.js';
+import { createProgram } from '../rendering/createProgram.js';
+import { destroyTexture } from '../rendering/destroyTexture.js';
+import { terrainAtlas } from '../terrain/terrainAtlas.js';
+import { terrainGrid } from '../terrain/terrainGrid.js';
+import { setParent } from '../scene/setParent.js';
+import { update } from '../scene/update.js';
+
+export async function addRasterTile(backend, layer, coords, tile) {
+  const ready = await backend._terrainPromise;
+  if (!ready || !backend._map || backend._map._terrain3D !== backend || layer._terrain3D !== backend ||
+    tile.request.signal.aborted || !layer._rasterTiles.has(`${coords.z}/${coords.x}/${coords.y}`) ||
+    backend._rasterTiles.has(tile)) {
+    return;
+  }
+  // Match DEM pixel spacing, capped at 64 subdivisions per tile.
+  const divisions = Math.max(1, Math.min(64, 256 / 2 ** (coords.z - backend._terrainZoom)));
+  const map = backend._map, crs = map.options.crs;
+  const origin = crs.project(backend.location), metres = Math.cos(backend.location.lat * Math.PI / 180);
+  // Tile pixels map linearly to projected metres: one scaled unit grid per tile, elevation in the vertex shader.
+  const scale = crs.scale(coords.z), terrainScale = 2 ** (backend._terrainZoom - coords.z);
+  const corner = crs.transformation.untransform(new L.Point(coords.x * 256, coords.y * 256), scale);
+  const opposite = crs.transformation.untransform(new L.Point((coords.x + 1) * 256, (coords.y + 1) * 256), scale);
+  const device = backend.renderer.device;
+  const texture = tile.texture;
+  if (!backend._rasterProgram || backend._rasterProgram.device !== device) {
+    // DEM atlas over the archive's tile grid; invalid or missing samples become -1e9 (the shader's no-data).
+    // ponytail: one texture, capped by maxTextureDimension2D (32×32 DEM tiles at 8192 px); split it for larger archives.
+    const bounds = backend._terrainBounds, columns = bounds.max.x - bounds.min.x + 1, rows = bounds.max.y - bounds.min.y + 1;
+    const { elevations, low, high } = terrainAtlas(backend._terrainTiles, bounds);
+    if (backend._dem) destroyTexture(backend, backend._dem.texture);
+    backend._dem = {
+      texture: device.createTexture({
+        size: [columns * 256, rows * 256],
+        format: 'r32float',
+        usage: GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.COPY_DST,
+      }),
+      low: Number.isFinite(low) ? low : backend._terrainOriginElevation,
+      high: Number.isFinite(high) ? high : backend._terrainOriginElevation,
+    };
+    device.queue.writeTexture({ texture: backend._dem.texture }, elevations,
+      { bytesPerRow: columns * 1024 }, [columns * 256, rows * 256]);
+    backend._terrainGrids = new Map();
+    backend._rasterProgram = createProgram(backend, {
+      baseTexture: texture,
+      unlit: true,
+      terrain: backend._dem,
+      alphaMode: 'BLEND',
+      depthWrite: true,
+    });
+  }
+  let attributes = backend._terrainGrids.get(divisions);
+  let name, attribute;
+  if (!attributes) {
+    attributes = terrainGrid(divisions);
+    for ([name, attribute] of Object.entries(attributes)) {
+      attribute.size ||= 1;
+      attribute.count = attribute.data.length / attribute.size;
+      attribute.indexFormat = 'uint16';
+      attribute.buffer = device.createBuffer({
+        size: Math.max(4, attribute.data.byteLength),
+        usage: name === 'index'
+          ? GPUBufferUsage.INDEX | GPUBufferUsage.COPY_DST
+          : GPUBufferUsage.VERTEX | GPUBufferUsage.COPY_DST,
+      });
+      device.queue.writeBuffer(attribute.buffer, 0, attribute.data);
+    }
+    backend._terrainGrids.set(divisions, attributes);
+  }
+  const base = backend._terrainOriginElevation;
+  const bottom = Math.min(backend._dem.low, base) - base, top = Math.max(backend._dem.high, base) - base;
+  const sizeX = (opposite.x - corner.x) * metres, sizeZ = -(opposite.y - corner.y) * metres;
+  // ponytail: ray picking sees the flat unit grid; read the DEM back if terrain must be pickable.
+  const geometry = {
+    device,
+    attributes,
+    drawRange: { start: 0, count: attributes.index.count },
+    // Local bounds whose radius, scaled by the largest axis, still covers the displaced tile.
+    bounds: {
+      min: [0, bottom, 0], max: [1, top, 1], center: [0.5, (bottom + top) / 2, 0.5],
+      radius: Math.hypot(sizeX, top - bottom, sizeZ) / 2 / Math.max(sizeX, 1, sizeZ),
+    },
+  };
+  const mesh = {
+    position: [(corner.x - origin.x) * metres, 0, -(corner.y - origin.y) * metres],
+    rotation: [0, 0, 0],
+    scale: [sizeX, 1, sizeZ],
+    worldMatrix: [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1],
+    children: [],
+    visible: true,
+    device,
+    geometry,
+    program: backend._rasterProgram,
+    texture,
+    // DEM pixel of the tile's corner, DEM pixels per tile, and the elevation at the layer origin.
+    terrain: [
+      coords.x * 256 * terrainScale - backend._terrainBounds.min.x * 256,
+      coords.y * 256 * terrainScale - backend._terrainBounds.min.y * 256,
+      256 * terrainScale,
+      base,
+    ],
+    tile,
+    opacity: layer.options.opacity ?? 1,
+    id: cityMapper.nextId++,
+    renderOrder: layer.options.zIndex || 0,
+    fadeDuration: 250,
+    fadeStart: tile.loadedAt,
+    ground: true,
+  };
+  tile.mesh.visible = false;
+  setParent(mesh, backend.root);
+  update(backend);
+  backend._rasterTiles.set(tile, mesh);
+}

package/src/raster/comparePendingTiles.js

@@ -0,0 +1,5 @@
+
+
+export function comparePendingTiles(a, b) {
+  return a.tile.coords.z - b.tile.coords.z || a.distance - b.distance;
+}

package/src/raster/createGeometry.js

@@ -0,0 +1,22 @@
+
+
+export function createGeometry(device) {
+  const attributes = {
+    position: { size: 3, data: new Float32Array([0, 0, 0, 1, 0, 0, 0, 0, 1, 1, 0, 1]) },
+    normal: { size: 3, data: new Float32Array([0, 1, 0, 0, 1, 0, 0, 1, 0, 0, 1, 0]) },
+    uv: { size: 2, data: new Float32Array([0, 0, 1, 0, 0, 1, 1, 1]) },
+    index: { data: new Uint16Array([0, 2, 1, 1, 2, 3]) },
+  };
+  let name, attribute;
+  for ([name, attribute] of Object.entries(attributes)) {
+    attribute.count = attribute.data.length / (attribute.size || 1);
+    attribute.indexFormat = 'uint16';
+    attribute.buffer = device.createBuffer({
+      size: attribute.data.byteLength,
+      usage: name === 'index' ? GPUBufferUsage.INDEX | GPUBufferUsage.COPY_DST
+        : GPUBufferUsage.VERTEX | GPUBufferUsage.COPY_DST,
+    });
+    device.queue.writeBuffer(attribute.buffer, 0, attribute.data);
+  }
+  return { device, attributes, drawRange: { start: 0, count: attributes.index.count } };
+}

package/src/raster/createRasterMesh.js

@@ -0,0 +1,47 @@
+import { cityMapper } from "../constants/cityMapper.js";
+import { createProgram } from "../rendering/createProgram.js";
+import { setParent } from "../scene/setParent.js";
+import { TILE_SIZE } from "../constants/TILE_SIZE.js";
+import { createGeometry } from './createGeometry.js';
+
+export function createRasterMesh(backend, tile) {
+  const device = backend.renderer.device;
+  const texture = {
+    device,
+    texture: device.createTexture({
+      size: [tile.image.width, tile.image.height],
+      format: 'rgba8unorm',
+      usage: GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.COPY_DST | GPUTextureUsage.RENDER_ATTACHMENT,
+    }),
+    sampler: device.createSampler({ addressModeU: 'clamp-to-edge', addressModeV: 'clamp-to-edge',
+      magFilter: 'linear', minFilter: 'linear' }),
+    image: tile.image, format: 'rgba8unorm', srgb: false, uploaded: null,
+  };
+  if (!backend._rasterProgram) {
+    backend._rasterProgram = createProgram(backend, {
+      baseTexture: texture, unlit: true, alphaMode: 'BLEND',
+    });
+  }
+  if (!backend._rasterGeometry) backend._rasterGeometry = createGeometry(device);
+  const { coords } = tile;
+  const crs = backend._map.options.crs;
+  const origin = crs.project(backend.location);
+  const metres = Math.cos(backend.location.lat * Math.PI / 180);
+  const scale = crs.scale(coords.z);
+  const corner = crs.transformation.untransform(new L.Point(coords.x * TILE_SIZE, coords.y * TILE_SIZE), scale);
+  const opposite = crs.transformation.untransform(new L.Point((coords.x + 1) * TILE_SIZE, (coords.y + 1) * TILE_SIZE), scale);
+  const sizeX = (opposite.x - corner.x) * metres;
+  const sizeZ = -(opposite.y - corner.y) * metres;
+  tile.texture = texture;
+  tile.mesh = {
+    position: [(corner.x - origin.x) * metres, 0, -(corner.y - origin.y) * metres],
+    rotation: [0, 0, 0],
+    scale: [sizeX, 1, sizeZ],
+    worldMatrix: [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1],
+    children: [], visible: true, device, geometry: backend._rasterGeometry,
+    program: backend._rasterProgram, texture,
+    opacity: backend.options.opacity, id: cityMapper.nextId++,
+    renderOrder: backend.options.zIndex || 0, tile, fadeDuration: 250, ground: true,
+  };
+  setParent(tile.mesh, backend.root);
+}

package/src/raster/finishAttachment.js

@@ -0,0 +1,11 @@
+import { setRasterTerrain } from "./setRasterTerrain.js";
+
+export async function finishAttachment(backend, map, attached) {
+  try {
+    await attached;
+    backend._added.resolve();
+    setRasterTerrain(backend, map._terrain3D);
+  } catch (error) {
+    backend.fire('error', { error });
+  }
+}

package/src/raster/finishRasterTile.js

@@ -0,0 +1,47 @@
+import { update } from "../scene/update.js";
+import { registerTerrainTile } from "./registerTerrainTile.js";
+import { pruneRasterTiles } from "./pruneRasterTiles.js";
+import { pumpRasterTiles } from './pumpRasterTiles.js';
+import { createRasterMesh } from './createRasterMesh.js';
+
+export async function finishRasterTile(backend, tile) {
+  try {
+    await backend.ready;
+    const result = await backend.options.archive.getZxy(
+      tile.coords.z, tile.coords.x, tile.coords.y, tile.request.signal
+    );
+    if (tile.request.signal.aborted) return;
+    if (!result) throw new Error(`Tile ${tile.coords.z}/${tile.coords.x}/${tile.coords.y} is not in the offline archive`);
+    try {
+      tile.image = await createImageBitmap(new Blob([result.data]));
+    } catch {
+      throw new Error(`Unable to decode tile ${tile.coords.z}/${tile.coords.x}/${tile.coords.y}`);
+    }
+    if (tile.request.signal.aborted) {
+      tile.image.close();
+      tile.image = null;
+      return;
+    }
+    createRasterMesh(backend, tile);
+    tile.loadedAt = performance.now();
+    tile.done = true;
+    backend._rasterVersion = (backend._rasterVersion || 0) + 1;
+    registerTerrainTile(backend, tile.coords, tile);
+    backend.fire('tileload', { tile, coords: tile.coords });
+    update(backend);
+  } catch (error) {
+    if (tile.request.signal.aborted) return;
+    tile.error = error.message;
+    backend._rasterVersion = (backend._rasterVersion || 0) + 1;
+    backend.fire('tileerror', { tile, coords: tile.coords, error });
+    backend.fire('error', { error, coords: tile.coords });
+  } finally {
+    backend._loadingTiles--;
+    if (backend._map) {
+      pumpRasterTiles(backend);
+      pruneRasterTiles(backend);
+      if (!backend._loadingTiles) backend.fire('load');
+      update(backend);
+    }
+  }
+}

package/src/raster/getRasterEvents.js

@@ -0,0 +1,6 @@
+import { updateRasterTiles } from "./updateRasterTiles.js";
+
+export function getRasterEvents(layer) {
+  const update = updateRasterTiles.bind(null, layer);
+  return { moveend: update, zoomend: update, rotate: update, pitch: update, resize: update };
+}

package/src/raster/getRasterTileSize.js

@@ -0,0 +1,5 @@
+import { TILE_SIZE } from '../constants/TILE_SIZE.js';
+
+export function getRasterTileSize() {
+  return new L.Point(TILE_SIZE, TILE_SIZE);
+}

package/src/raster/initRaster.js

@@ -0,0 +1,38 @@
+import { isLoading } from './isLoading.js';
+import { getRasterEvents } from './getRasterEvents.js';
+import { readyRaster } from './readyRaster.js';
+import { reportError } from './reportError.js';
+import { emptyNode } from '../scene/emptyNode.js';
+import { read } from '../archives/read.js';
+import { getHeader } from '../archives/getHeader.js';
+import { getZxy } from '../archives/getZxy.js';
+import { onPMTileAdd } from './onPMTileAdd.js';
+import { onPMTileRemove } from './onPMTileRemove.js';
+import { getRasterTileSize } from './getRasterTileSize.js';
+import { setPMTileOpacity } from './setPMTileOpacity.js';
+import { setPMTileZIndex } from './setPMTileZIndex.js';
+
+export function initRaster(layer, options) {
+  layer._read = read.bind(null, layer);
+  layer.getHeader = getHeader.bind(null, layer);
+  layer.getZxy = getZxy.bind(null, layer);
+  layer.getTileSize = getRasterTileSize;
+  layer.isLoading = isLoading.bind(null, layer);
+  layer.setOpacity = setPMTileOpacity.bind(null, layer);
+  layer.setZIndex = setPMTileZIndex.bind(null, layer);
+  layer.onAdd = onPMTileAdd.bind(null, layer);
+  layer.onRemove = onPMTileRemove.bind(null, layer);
+  layer.getEvents = getRasterEvents.bind(null, layer);
+  options = { ariaLabel: 'PMTiles raster', maxZoom: 18, opacity: 1, zIndex: 0, ...options };
+  L.Util.setOptions(layer, options);
+  layer.root = emptyNode();
+  layer._areas = new Map();
+  layer._rasterTiles = new Map();
+  layer._loadingTiles = 0;
+  layer._added = Promise.withResolvers();
+  layer.url = new URL(options.url, document.baseURI).href;
+  layer._directories = new Map();
+  layer.ready = Promise.resolve(layer.options.archive || layer)
+    .then(readyRaster.bind(null, layer))
+    .catch(reportError.bind(null, layer));
+}

package/src/raster/isLoading.js

@@ -0,0 +1,5 @@
+
+
+export function isLoading(layer) {
+  return layer._loadingTiles > 0;
+}

package/src/raster/loadRasterTile.js

@@ -0,0 +1,10 @@
+import { finishRasterTile } from './finishRasterTile.js';
+
+export function loadRasterTile(backend, tile) {
+  tile.started = true;
+  const first = backend._loadingTiles === 0;
+  backend._loadingTiles++;
+  backend.fire('tileloadstart', { tile, coords: tile.coords });
+  if (first) backend.fire('loading');
+  return finishRasterTile(backend, tile);
+}

package/src/raster/onPMTileAdd.js

@@ -0,0 +1,10 @@
+import { finishAttachment } from './finishAttachment.js';
+import { updateAttachedTiles } from './updateAttachedTiles.js';
+import { attach } from '../scene/attach.js';
+
+export function onPMTileAdd(backend, map) {
+  if (!backend.location) backend.location = map.getCenter();
+  const attached = attach(backend, map);
+  finishAttachment(backend, map, attached);
+  updateAttachedTiles(backend, map, attached);
+}

package/src/raster/onPMTileRemove.js

@@ -0,0 +1,8 @@
+import { releaseRasterTiles } from './releaseRasterTiles.js';
+import { onRemove3DLayer } from '../scene/onRemove3DLayer.js';
+
+export function onPMTileRemove(backend, map) {
+  releaseRasterTiles(backend);
+  backend._terrain3D = null;
+  onRemove3DLayer(backend, map);
+}

package/src/raster/pruneRasterTiles.js

@@ -0,0 +1,37 @@
+import { releaseRasterTile } from './releaseRasterTile.js';
+
+export function pruneRasterTiles(backend) {
+  const wanted = backend._wantedRasterTiles;
+  const now = performance.now();
+  if (backend._pruneVersion === backend._rasterVersion && backend._pruneWanted === wanted &&
+    now < backend._pruneAfter) return Number.isFinite(backend._pruneAfter);
+  backend._pruneVersion = backend._rasterVersion;
+  backend._pruneWanted = wanted;
+  backend._pruneAfter = Infinity;
+  const pending = [];
+  let key, tile, parts, overlaps, coords, zoom;
+  for (key of wanted) {
+    tile = backend._rasterTiles.get(key);
+    if (tile?.done && now - tile.loadedAt < 250) {
+      backend._pruneAfter = Math.min(backend._pruneAfter, tile.loadedAt + 250);
+    }
+    if (!tile?.done || now - tile.loadedAt < 250) {
+      parts = key.split('/');
+      pending.push({ z: Number(parts[0]), x: Number(parts[1]), y: Number(parts[2]) });
+    }
+  }
+  for ([key, tile] of backend._rasterTiles) {
+    if (wanted.has(key)) continue;
+    overlaps = false;
+    for (coords of pending) {
+      zoom = Math.min(coords.z, tile.coords.z);
+      if (Math.floor(coords.x / 2 ** (coords.z - zoom)) === Math.floor(tile.coords.x / 2 ** (tile.coords.z - zoom)) &&
+        Math.floor(coords.y / 2 ** (coords.z - zoom)) === Math.floor(tile.coords.y / 2 ** (tile.coords.z - zoom))) {
+        overlaps = true;
+        break;
+      }
+    }
+    if (!overlaps) releaseRasterTile(backend, tile);
+  }
+  return Number.isFinite(backend._pruneAfter);
+}

package/src/raster/pumpRasterTiles.js

@@ -0,0 +1,22 @@
+import { TILE_SIZE } from "../constants/TILE_SIZE.js";
+import { comparePendingTiles } from './comparePendingTiles.js';
+import { loadRasterTile } from './loadRasterTile.js';
+
+export function pumpRasterTiles(backend) {
+  const map = backend._map;
+  if (!map) return;
+  const center = map.project(map.getCenter(), 0).divideBy(TILE_SIZE);
+  const pending = [];
+  let tile, coords;
+  for (tile of backend._rasterTiles.values()) {
+    if (tile.started || tile.request.signal.aborted) continue;
+    ({ coords } = tile);
+    pending.push({ tile, distance: Math.hypot((coords.x + 0.5) / 2 ** coords.z - center.x,
+      (coords.y + 0.5) / 2 ** coords.z - center.y) });
+  }
+  pending.sort(comparePendingTiles);
+  for ({ tile } of pending) {
+    if (backend._loadingTiles >= 4) break;
+    loadRasterTile(backend, tile);
+  }
+}

package/src/raster/readyRaster.js

@@ -0,0 +1,13 @@
+import { getHeader } from "../archives/getHeader.js";
+
+export async function readyRaster(layer, archive) {
+  const header = await archive.getHeader();
+  layer.options.archive = archive;
+  layer.header = header;
+  if (layer.options.maxNativeZoom === undefined) {
+    layer.options.maxNativeZoom = header.maxZoom;
+  }
+  layer.options.maxZoom = Math.max(layer.options.minZoom || 0, layer.options.maxZoom);
+  layer.fire('ready');
+  return layer;
+}

package/src/raster/registerTerrainTile.js

@@ -0,0 +1,12 @@
+import { addRasterTile } from './addRasterTile.js';
+
+export async function registerTerrainTile(backend, coords, tile) {
+  if (backend._terrain3D && tile.done && !tile.request.signal.aborted &&
+    backend._rasterTiles.get(`${coords.z}/${coords.x}/${coords.y}`) === tile) {
+    try {
+      await addRasterTile(backend._terrain3D, backend, coords, tile);
+    } catch (error) {
+      backend.fire('tileerror', { tile, coords, error });
+    }
+  }
+}

package/src/raster/releaseRasterTile.js

@@ -0,0 +1,18 @@
+import { destroyTexture } from '../rendering/destroyTexture.js';
+import { removeRasterTile } from './removeRasterTile.js';
+import { setParent } from '../scene/setParent.js';
+import { update } from '../scene/update.js';
+
+export function releaseRasterTile(backend, tile) {
+  const key = `${tile.coords.z}/${tile.coords.x}/${tile.coords.y}`;
+  if (backend._rasterTiles.get(key) !== tile) return;
+  backend._rasterTiles.delete(key);
+  backend._rasterVersion = (backend._rasterVersion || 0) + 1;
+  tile.request.abort();
+  if(backend._terrain3D) removeRasterTile(backend._terrain3D, tile);
+  if (tile.mesh) setParent(tile.mesh, null);
+  if (tile.texture) destroyTexture(backend, tile.texture.texture);
+  tile.image?.close();
+  backend.fire('tileunload', { tile, coords: tile.coords });
+  update(backend);
+}

package/src/raster/releaseRasterTiles.js

@@ -0,0 +1,15 @@
+import { destroyTexture } from '../rendering/destroyTexture.js';
+import { releaseRasterTile } from './releaseRasterTile.js';
+
+export function releaseRasterTiles(backend) {
+  let tile, attribute;
+  for (tile of backend._rasterTiles.values()) releaseRasterTile(backend, tile);
+  backend._rasterProgram?.pipelineCache.clear();
+  backend._rasterProgram = null;
+  if (backend._rasterGeometry) {
+    for (attribute of Object.values(backend._rasterGeometry.attributes)) {
+      destroyTexture(backend, attribute.buffer);
+    }
+    backend._rasterGeometry = null;
+  }
+}

package/src/raster/removeRasterTile.js

@@ -0,0 +1,13 @@
+import { destroyTexture } from '../rendering/destroyTexture.js';
+import { setParent } from '../scene/setParent.js';
+import { update } from '../scene/update.js';
+
+export function removeRasterTile(layer, tile) {
+  layer._terrainRequest?.abort();
+  const mesh = layer._rasterTiles.get(tile);
+  if (!mesh) return;
+  setParent(mesh, null);
+  update(layer);
+  if (mesh.texture !== tile.texture) destroyTexture(layer, mesh.texture.texture);
+  layer._rasterTiles.delete(tile);
+}

package/src/raster/reportError.js

@@ -0,0 +1,6 @@
+
+
+export function reportError(layer, error) {
+  layer.fire('error', { error });
+  throw error;
+}

package/src/raster/setPMTileOpacity.js

@@ -0,0 +1,7 @@
+import { setRasterOpacity } from './setRasterOpacity.js';
+
+export function setPMTileOpacity(backend, opacity) {
+  backend.options.opacity = opacity;
+  setRasterOpacity(backend, opacity);
+  return backend;
+}

package/src/raster/setPMTileZIndex.js

@@ -0,0 +1,7 @@
+import { setRasterZIndex } from './setRasterZIndex.js';
+
+export function setPMTileZIndex(backend, zIndex) {
+  backend.options.zIndex = zIndex;
+  setRasterZIndex(backend, zIndex);
+  return backend;
+}

package/src/raster/setRasterOpacity.js

@@ -0,0 +1,11 @@
+import { update } from '../scene/update.js';
+
+export function setRasterOpacity(backend, opacity) {
+  let tile, terrainMesh;
+  for (tile of backend._rasterTiles.values()) {
+    if (tile.mesh) tile.mesh.opacity = opacity;
+    terrainMesh = backend._terrain3D?._rasterTiles.get(tile);
+    if (terrainMesh) terrainMesh.opacity = opacity;
+  }
+  update(backend);
+}

package/src/raster/setRasterTerrain.js

@@ -0,0 +1,21 @@
+import { removeRasterTile } from './removeRasterTile.js';
+import { setParent } from '../scene/setParent.js';
+import { registerTerrainTile } from './registerTerrainTile.js';
+
+export function setRasterTerrain(backend, terrain) {
+  if (backend._terrain3D === terrain) return;
+  let tile;
+  for (tile of backend._rasterTiles.values()) {
+    if(backend._terrain3D) removeRasterTile(backend._terrain3D, tile);
+    if (tile.mesh) {
+      tile.mesh.visible = true;
+      setParent(tile.mesh, backend.root);
+    }
+  }
+  backend._terrain3D = terrain || null;
+  if (terrain) {
+    for (tile of backend._rasterTiles.values()) {
+      if (tile.done) registerTerrainTile(backend, tile.coords, tile);
+    }
+  }
+}

package/src/raster/setRasterZIndex.js

@@ -0,0 +1,11 @@
+import { update } from '../scene/update.js';
+
+export function setRasterZIndex(backend, zIndex) {
+  let tile, terrainMesh;
+  for (tile of backend._rasterTiles.values()) {
+    if (tile.mesh) tile.mesh.renderOrder = zIndex;
+    terrainMesh = backend._terrain3D?._rasterTiles.get(tile);
+    if (terrainMesh) terrainMesh.renderOrder = zIndex;
+  }
+  update(backend);
+}

package/src/raster/updateAttachedTiles.js

@@ -0,0 +1,10 @@
+import { updateRasterTiles } from "./updateRasterTiles.js";
+
+export async function updateAttachedTiles(backend, map, attached) {
+  try {
+    await Promise.all([attached, backend.ready]);
+    if (backend._map === map && map.hasLayer(backend)) updateRasterTiles(backend);
+  } catch (error) {
+    backend.fire('error', { error });
+  }
+}

package/src/raster/updateRasterTiles.js

@@ -0,0 +1,59 @@
+import { TILE_RADIUS } from '../constants/TILE_RADIUS.js';
+import { pumpRasterTiles } from './pumpRasterTiles.js';
+import { TILE_SIZE } from '../constants/TILE_SIZE.js';
+import { releaseRasterTile } from './releaseRasterTile.js';
+import { pruneRasterTiles } from './pruneRasterTiles.js';
+
+// ponytail: cap horizon views at 169 tiles; raise the radius if extreme pitches need more.
+
+export function updateRasterTiles(backend) {
+  const map = backend._map;
+  if (!map || !backend._shared || !backend.header) return;
+
+  const zoom = Math.max(backend.header.minZoom ?? 0, Math.min(
+    Math.round(map.getZoom()),
+    backend.options.maxZoom,
+    backend.options.maxNativeZoom
+  ));
+  backend._tileZoom = zoom;
+  const bounds = map.getBounds();
+  const northWest = map.project(bounds.getNorthWest(), zoom).divideBy(TILE_SIZE).floor();
+  const southEast = map.project(bounds.getSouthEast(), zoom).divideBy(TILE_SIZE).floor();
+  const archiveNorthWest = backend.header.maxLat === undefined || backend.header.minLon === undefined
+    ? new L.Point(0, 0)
+    : map.project([backend.header.maxLat, backend.header.minLon], zoom).divideBy(TILE_SIZE).floor();
+  const archiveSouthEast = backend.header.minLat === undefined || backend.header.maxLon === undefined
+    ? new L.Point(2 ** zoom - 1, 2 ** zoom - 1)
+    : map.project([backend.header.minLat, backend.header.maxLon], zoom).divideBy(TILE_SIZE).floor();
+  const center = map.project(map.getCenter(), zoom).divideBy(TILE_SIZE).floor();
+  const wanted = new Map();
+  let x, y, key, coords, parent, tile;
+  for (x = Math.max(0, northWest.x, archiveNorthWest.x, center.x - TILE_RADIUS);
+    x <= Math.min(2 ** zoom - 1, southEast.x, archiveSouthEast.x, center.x + TILE_RADIUS); x++) {
+    for (y = Math.max(0, northWest.y, archiveNorthWest.y, center.y - TILE_RADIUS);
+      y <= Math.min(2 ** zoom - 1, southEast.y, archiveSouthEast.y, center.y + TILE_RADIUS); y++) {
+      wanted.set(`${zoom}/${x}/${y}`, { z: zoom, x, y });
+    }
+  }
+  backend._wantedRasterTiles = new Set(wanted.keys());
+  const coverage = new Map();
+  const parentZoom = Math.max(backend.header.minZoom ?? 0, zoom - 2), factor = 2 ** (zoom - parentZoom);
+  if (parentZoom < zoom) {
+    for ([key, coords] of wanted) {
+      if (backend._rasterTiles.get(key)?.done) continue;
+      parent = { z: parentZoom, x: Math.floor(coords.x / factor), y: Math.floor(coords.y / factor) };
+      coverage.set(`${parent.z}/${parent.x}/${parent.y}`, parent);
+    }
+  }
+  const required = new Map([...coverage, ...wanted]);
+  for ([key, tile] of backend._rasterTiles) {
+    if (!required.has(key) && !tile.done) releaseRasterTile(backend, tile);
+  }
+  for ([key, coords] of required) {
+    if (backend._rasterTiles.has(key)) continue;
+    tile = { coords, request: new AbortController(), done: false };
+    backend._rasterTiles.set(key, tile);
+  }
+  pumpRasterTiles(backend);
+  pruneRasterTiles(backend);
+}