leaflet-city-mapper 0.0.0-stage → 0.0.2

package/src/utils/pump.js

@@ -0,0 +1,226 @@
+import { emptyNode } from "./emptyNode.js";
+import { isClockWise } from "./isClockWise.js";
+import { lampPostGeometry } from "./lampPostGeometry.js";
+import { lightGeometry } from "./lightGeometry.js";
+import { parseColor } from "./parseColor.js";
+import { treeGeometry } from "./treeGeometry.js";
+import { triangulate } from "./triangulate.js";
+import { createProgram } from './createProgram.js';
+import { updateStatus } from "./releaseArea.js";
+import { loadSource } from './loadSource.js';
+import { setParent } from './setParent.js';
+import { update } from './update.js';
+import { getElevation } from "./getElevation.js";
+
+/** Share four load/build slots across source layers, nearest ground blocks first. */
+
+export function pump(backend, map = backend._map) {
+  // Meshes need the shared renderer; _attach() re-runs _updateArea() once it exists.
+  const shared = map && L.Layer._renderers.get(map);
+  if (!shared) return;
+  const layers = [...shared._layers].filter(layer =>
+    Number.isFinite(layer._inflight) && layer._areas && (layer.url || layer._geojson));
+  const pending = layers.flatMap(layer => [...layer._areas.values()]
+    .filter(area => !area.started && !area.request.signal.aborted)
+    .map(area => {
+      const center = area.coords && map.project(map.getCenter(), area.coords.z).divideBy(256);
+      return { layer, area, distance: center
+        ? Math.hypot(area.coords.x + 0.5 - center.x, area.coords.y + 0.5 - center.y) / 2 ** area.coords.z : 0 };
+    })).sort((a, b) => a.distance - b.distance);
+  let inflight = layers.reduce((sum, layer) => sum + layer._inflight, 0);
+  for (const { layer: backend, area } of pending) {
+    if (inflight >= 4) break;
+    if (backend._inflight >= 2) continue;
+    area.started = true;
+    backend._inflight++;
+    inflight++;
+    (async () => {
+      try {
+        // Let ground requests start first, and avoid rebuilding flat geometry when the DEM arrives.
+        await new Promise(requestAnimationFrame);
+        await map._terrain3D?._terrainPromise;
+        if (area.request.signal.aborted) return;
+        const coords = area.coords;
+        const data = await loadSource(backend, area);
+        if (area.request.signal.aborted) return;
+        if (data?.type !== 'FeatureCollection' || !Array.isArray(data.features)) {
+          throw new Error('Invalid GeoJSON response');
+        }
+        if (backend._geojson && typeof backend.options.style !== 'function') {
+          throw new Error('style must be a function');
+        }
+        const features = data.features;
+        const positions = [], normals = [], colors = [], uvs = [], featureFaces = [], lights = [];
+        const supports = new Set();
+        let skipped = 0;
+        const crs = map.options.crs;
+        const origin = crs.project(backend.location);
+        const metres = Math.cos(backend.location.lat * Math.PI / 180);
+        const groundOffset = point => point.ground || 0;
+        const addTriangle = (a, ah, b, bh, c, ch, nx, ny, nz, color) => {
+          const ux = b.x - a.x, uy = bh - ah, uz = a.y - b.y;
+          const vx = c.x - a.x, vy = ch - ah, vz = a.y - c.y;
+          // Orient the triangle to its intended outward normal after flipping north to -z.
+          if ((uy * vz - uz * vy) * nx + (uz * vx - ux * vz) * ny + (ux * vy - uy * vx) * nz < 0) {
+            const point = b, height = bh;
+            b = c; bh = ch; c = point; ch = height;
+          }
+          positions.push(a.x, ah + groundOffset(a), -a.y,
+            b.x, bh + groundOffset(b), -b.y,
+            c.x, ch + groundOffset(c), -c.y);
+          normals.push(nx, ny, nz, nx, ny, nz, nx, ny, nz);
+          colors.push(color.r, color.g, color.b, color.r, color.g, color.b, color.r, color.g, color.b);
+          if (backend.options.nightLight) uvs.push(...a.uv, ...b.uv, ...c.uv);
+        };
+        let deadline = performance.now() + 4;
+        for (const feature of features) {
+          if (area.request.signal.aborted) return;
+          if (performance.now() >= deadline) {
+            await new Promise(requestAnimationFrame);
+            if (area.request.signal.aborted) return;
+            deadline = performance.now() + 4;
+          }
+          const geometry = feature?.geometry;
+          const isTree = geometry?.type === 'Point';
+          if (backend.options.nightLight && !isTree) throw new Error('Night lights require Point geometry');
+          const polygons = geometry?.type === 'Polygon' ? [geometry.coordinates] : geometry?.type === 'MultiPolygon' ? geometry.coordinates : null;
+          if (!polygons && !isTree) throw new Error('Unsupported GeoJSON geometry');
+          const [lon, lat] = (isTree ? geometry.coordinates : polygons[0]?.[0]?.[0]) ?? [];
+          if (!Number.isFinite(lon) || !Number.isFinite(lat)) throw new Error('Invalid GeoJSON coordinates');
+          if (coords) {
+            const anchor = map.project(new L.LatLng(lat, lon), coords.z);
+            // Overlapping archive blocks may contain the same polygon; its first vertex owns it.
+            if (Math.floor(anchor.x / 256) !== coords.x || Math.floor(anchor.y / 256) !== coords.y) continue;
+          }
+          const style = backend.options.style(feature);
+          if (style === null) {
+            skipped++;
+            continue;
+          }
+          if (!style || typeof style !== 'object') throw new Error('style must return an extrusion style or null');
+          const { top, bottom = 0, color = 0xd9b38c } = style;
+          if (!Number.isFinite(top) || !Number.isFinite(bottom) || bottom < 0 || top <= bottom) {
+            throw new Error('Invalid extrusion heights: expected top > bottom >= 0');
+          }
+          const baseColor = parseColor(color);
+          const vertexStart = positions.length / 3;
+          if (isTree) {
+            const point = crs.project(new L.LatLng(lat, lon));
+            const elevation = map._terrain3D ? getElevation(map._terrain3D, [lat, lon]) : undefined;
+            const projected = {
+              x: (point.x - origin.x) * metres, y: (point.y - origin.y) * metres,
+              ground: Number.isFinite(elevation) && Number.isFinite(backend.root.position[1])
+                ? elevation - backend.root.position[1] : 0,
+            };
+            if (backend.options.nightLight) {
+              if (!Number.isFinite(style.lightFlux) || style.lightFlux <= 0) throw new Error('Invalid light flux');
+              const support = feature.properties?.cod_ouvrag || `${lon},${lat}`;
+              if (style.poleRadius > 0 && !supports.has(support)) {
+                lampPostGeometry(projected, style, addTriangle);
+                supports.add(support);
+              }
+              lightGeometry(projected, style, addTriangle);
+              lights.push({
+                position: [projected.x, projected.ground + top, -projected.y],
+                radius: Math.hypot(top, style.lightRadius), color: [baseColor.r, baseColor.g, baseColor.b],
+                flux: style.lightFlux,
+              });
+            } else treeGeometry(projected, style, addTriangle);
+          }
+          for (const rings of polygons || []) {
+            if (!rings.length) throw new Error('Empty GeoJSON polygon');
+            const paths = rings.map(ring => {
+              if (ring.length < 4) throw new Error('Invalid GeoJSON polygon ring');
+              return ring.slice(0, -1).map(([lng, lat]) => {
+                if (!Number.isFinite(lng) || !Number.isFinite(lat)) throw new Error('Invalid GeoJSON coordinates');
+                const point = crs.project(new L.LatLng(lat, lng));
+                const elevation = backend._map._terrain3D ? getElevation(backend._map._terrain3D, [lat, lng]) : undefined;
+                return {
+                  x: (point.x - origin.x) * metres,
+                  y: (point.y - origin.y) * metres,
+                  ground: Number.isFinite(elevation) && Number.isFinite(backend.root.position[1])
+                    ? elevation - backend.root.position[1] : 0,
+                };
+              });
+            });
+            const points = paths.flat();
+            for (const [a, b, c] of triangulate(paths[0], paths.slice(1))) {
+              addTriangle(points[a], top, points[b], top, points[c], top, 0, 1, 0, baseColor);
+              if (bottom > 0) addTriangle(points[a], bottom, points[b], bottom, points[c], bottom, 0, -1, 0, baseColor);
+            }
+            paths.forEach((path, index) => {
+              // Interior walls face into the courtyard; exterior walls face away from the building.
+              const sign = isClockWise(path) === (index === 0) ? -1 : 1;
+              for (let i = 0; i < path.length; i++) {
+                const a = path[i], b = path[(i + 1) % path.length];
+                const length = Math.hypot(b.x - a.x, b.y - a.y);
+                if (!length) continue;
+                const nx = sign * (b.y - a.y) / length, nz = sign * (b.x - a.x) / length;
+                addTriangle(a, bottom, b, bottom, b, top, nx, 0, nz, baseColor);
+                addTriangle(a, bottom, b, top, a, top, nx, 0, nz, baseColor);
+              }
+            });
+          }
+          const vertexEnd = positions.length / 3;
+          featureFaces.push({
+            id: feature.id ?? feature.properties?.objectid ?? JSON.stringify(geometry),
+            properties: feature.properties, baseColor,
+            faceStart: vertexStart / 3, faceEnd: vertexEnd / 3, vertexStart, vertexEnd,
+          });
+        }
+        if (!positions.length) {
+          Object.assign(area, { mesh: null, buildings: 0, skipped, done: true });
+          return;
+        }
+        const device = backend.renderer.device;
+        const attributes = {
+          position: { size: 3, data: new Float32Array(positions) },
+          normal: { size: 3, data: new Float32Array(normals) },
+          color: { size: 3, data: new Float32Array(colors) },
+        };
+        if (backend.options.nightLight) attributes.uv = { size: 2, data: new Float32Array(uvs) };
+        for (const [name, attribute] of Object.entries(attributes)) {
+          attribute.count = attribute.data.length / attribute.size;
+          attribute.buffer = device.createBuffer({
+            size: Math.max(4, attribute.data.byteLength),
+            usage: GPUBufferUsage.VERTEX | GPUBufferUsage.COPY_DST,
+          });
+          device.queue.writeBuffer(attribute.buffer, 0, attribute.data);
+        }
+        const meshGeometry = {
+          device,
+          attributes,
+          drawRange: { start: 0, count: attributes.position.count },
+        };
+        Object.assign(area, {
+          mesh: {
+            ...emptyNode(),
+            device,
+            geometry: meshGeometry,
+            program: createProgram(backend, {
+              vertexColors: true, roofTexture: Boolean(backend.options.roofTexture),
+              ...(backend.options.nightLight ? { nightLight: true, alphaMode: 'BLEND', doubleSided: true } : {})
+            }),
+            id: L.Layer._nextId++,
+            renderOrder: 0,
+            fadeDuration: 250,
+            extras: { featureFaces, lights },
+          },
+          buildings: featureFaces.length,
+          skipped,
+          done: true
+        });
+        setParent(area.mesh, backend.root);
+        update(backend);
+      } catch (error) {
+        if (area.request.signal.aborted) return;
+        area.error = error.message;
+        backend.fire('error', { error });
+      }
+    })().finally(() => {
+      backend._inflight--;
+      pump(backend, map);
+    });
+  }
+  for (const layer of layers) updateStatus(layer);
+}

package/src/utils/rasterTiles.js

@@ -0,0 +1,285 @@
+import { addRasterTile } from './addRasterTile.js';
+import { createProgram } from './createProgram.js';
+import { destroyTexture } from './destroyTexture.js';
+import { removeRasterTile } from './removeRasterTile.js';
+import { setParent } from './setParent.js';
+import { update } from './update.js';
+
+const TILE_SIZE = 256;
+// ponytail: cap horizon views at 169 tiles; raise the radius if extreme pitches need more.
+const TILE_RADIUS = 6;
+
+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();
+  for (let 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 (let 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 (const [key, coords] of wanted) {
+      if (backend._rasterTiles.get(key)?.done) continue;
+      const 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 (const [key, tile] of backend._rasterTiles) {
+    if (!required.has(key) && !tile.done) releaseRasterTile(backend, tile);
+  }
+  for (const [key, coords] of required) {
+    if (backend._rasterTiles.has(key)) continue;
+    const tile = { coords, request: new AbortController(), done: false };
+    backend._rasterTiles.set(key, tile);
+  }
+  pumpRasterTiles(backend);
+  pruneRasterTiles(backend);
+}
+
+function pumpRasterTiles(backend) {
+  const map = backend._map;
+  if (!map) return;
+  const center = map.project(map.getCenter(), 0).divideBy(TILE_SIZE);
+  const pending = [...backend._rasterTiles.values()].filter(tile => !tile.started && !tile.request.signal.aborted);
+  const distance = ({ coords }) => Math.hypot((coords.x + 0.5) / 2 ** coords.z - center.x,
+    (coords.y + 0.5) / 2 ** coords.z - center.y);
+  pending.sort((a, b) => a.coords.z - b.coords.z || distance(a) - distance(b));
+  for (const tile of pending) {
+    if (backend._loadingTiles >= 4) break;
+    loadRasterTile(backend, tile);
+  }
+}
+
+export function releaseRasterTiles(backend) {
+  for (const tile of backend._rasterTiles.values()) releaseRasterTile(backend, tile);
+  backend._rasterProgram?.pipelineCache.clear();
+  backend._rasterProgram = null;
+  if (backend._rasterGeometry) {
+    for (const attribute of Object.values(backend._rasterGeometry.attributes)) {
+      destroyTexture(backend, attribute.buffer);
+    }
+    backend._rasterGeometry = null;
+  }
+}
+
+export function setRasterTerrain(backend, terrain) {
+  if (backend._terrain3D === terrain) return;
+  for (const 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 (const tile of backend._rasterTiles.values()) {
+      if (tile.done) registerTerrainTile(backend, tile.coords, tile);
+    }
+  }
+}
+
+export function registerTerrainTile(backend, coords, tile) {
+  if (backend._terrain3D && tile.done && !tile.request.signal.aborted &&
+    backend._rasterTiles.get(`${coords.z}/${coords.x}/${coords.y}`) === tile) {
+    addRasterTile(backend._terrain3D, backend, coords, tile)
+      .catch(error => backend.fire('tileerror', { tile, coords, error }));
+  }
+}
+
+export function setRasterOpacity(backend, opacity) {
+  for (const tile of backend._rasterTiles.values()) {
+    if (tile.mesh) tile.mesh.opacity = opacity;
+    const terrainMesh = backend._terrain3D?._rasterTiles.get(tile);
+    if (terrainMesh) terrainMesh.opacity = opacity;
+  }
+  update(backend);
+}
+
+export function setRasterZIndex(backend, zIndex) {
+  for (const tile of backend._rasterTiles.values()) {
+    if (tile.mesh) tile.mesh.renderOrder = zIndex;
+    const terrainMesh = backend._terrain3D?._rasterTiles.get(tile);
+    if (terrainMesh) terrainMesh.renderOrder = zIndex;
+  }
+  update(backend);
+}
+
+export function getRasterTileSize() {
+  return new L.Point(TILE_SIZE, TILE_SIZE);
+}
+
+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 Promise.resolve(backend.ready).then(() => backend.options.archive.getZxy(
+    tile.coords.z, tile.coords.x, tile.coords.y, tile.request.signal
+  )).then(async result => {
+    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);
+    }
+  });
+}
+
+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: L.Layer._nextId++,
+    renderOrder: backend.options.zIndex || 0, tile, fadeDuration: 250, ground: true,
+  };
+  setParent(tile.mesh, backend.root);
+}
+
+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]) },
+  };
+  for (const [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 } };
+}
+
+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);
+}
+
+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 = [...wanted].filter(key => {
+    const tile = backend._rasterTiles.get(key);
+    if (tile?.done && now - tile.loadedAt < 250) {
+      backend._pruneAfter = Math.min(backend._pruneAfter, tile.loadedAt + 250);
+    }
+    return !tile?.done || now - tile.loadedAt < 250;
+  }).map(key => {
+    const [z, x, y] = key.split('/').map(Number);
+    return { z, x, y };
+  });
+  for (const [key, tile] of backend._rasterTiles) {
+    if (wanted.has(key)) continue;
+    const overlaps = pending.some(coords => {
+      const zoom = Math.min(coords.z, tile.coords.z);
+      return 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));
+    });
+    if (!overlaps) releaseRasterTile(backend, tile);
+  }
+  return Number.isFinite(backend._pruneAfter);
+}

package/src/utils/raycast.js

@@ -0,0 +1,60 @@
+import { intersectMeshes } from './intersectMeshes.js';
+import { traverse } from './traverse.js';
+import { updateCamera } from './updateCamera.js';
+import { updateWorldMatrix } from './updateWorldMatrix.js';
+
+/** Raycasting, hover/click highlight and tooltips. */
+/**
+ * Finds the objects under a mouse or pointer event, nearest first.
+ *
+ * @param {MouseEvent} event
+ * @param {Object[]} [objects] Defaults to this layer's root children, not all map layers.
+ * @param {boolean} [recursive] Also test the descendants of `objects`.
+ * @returns {Object[]} Nearest hit per mesh: object, shared-world point/distance and triangle faceIndex.
+ */
+
+export function raycast(backend, event, objects = backend.root.children, recursive = true) {
+  if (!backend.renderer) {
+    return [];
+  }
+  backend._beforeRaycast?.();
+  const rect = backend._map.getContainer().getBoundingClientRect();
+  updateWorldMatrix(backend.scene);
+  updateCamera(backend.camera);
+  // Unproject the mouse (-1..1) into a world-space ray from the camera.
+  const inverseCamera = new DOMMatrix(backend.camera.projectionViewMatrix).inverse();
+  const inverseCameraValues = inverseCamera.toFloat64Array();
+  if (![...inverseCameraValues].every(Number.isFinite)) {
+    throw new Error('Singular 3D transform');
+  }
+  backend.raycaster.origin[0] = backend.camera.position[0];
+  backend.raycaster.origin[1] = backend.camera.position[1];
+  backend.raycaster.origin[2] = backend.camera.position[2];
+  const unprojected = new DOMPoint(
+    ((event.clientX - rect.left) / rect.width) * 2 - 1,
+    -((event.clientY - rect.top) / rect.height) * 2 + 1,
+    0,
+    1
+  ).matrixTransform(inverseCamera);
+  const end = [
+    unprojected.x / unprojected.w,
+    unprojected.y / unprojected.w,
+    unprojected.z / unprojected.w
+  ];
+  backend.raycaster.direction[0] = end[0] - backend.raycaster.origin[0];
+  backend.raycaster.direction[1] = end[1] - backend.raycaster.origin[1];
+  backend.raycaster.direction[2] = end[2] - backend.raycaster.origin[2];
+  const rayLength = Math.hypot(...backend.raycaster.direction) || 1;
+  backend.raycaster.direction[0] /= rayLength;
+  backend.raycaster.direction[1] /= rayLength;
+  backend.raycaster.direction[2] /= rayLength;
+  const meshes = [];
+  for (const object of objects) {
+    if (recursive) traverse(object, mesh => {
+      if (!mesh.visible) return true;
+      if (mesh.geometry && mesh._appearance !== 0) meshes.push(mesh);
+    });
+    else if (object.geometry && object.visible && object._appearance !== 0) meshes.push(object);
+  }
+  return intersectMeshes(backend.raycaster, meshes, backend.renderer.uniformData?.[55]);
+}

package/src/utils/read.js

@@ -0,0 +1,29 @@
+export async function read(backend, offset, length, signal) {
+  signal?.throwIfAborted();
+  if (!Number.isSafeInteger(offset) || !Number.isSafeInteger(length) ||
+    offset < 0 || length <= 0 || !Number.isSafeInteger(offset + length)) {
+    throw new Error('Invalid PMTiles byte range');
+  }
+  const response = await fetch(backend.url, {
+    headers: { Range: `bytes=${offset}-${offset + length - 1}` }, signal,
+  });
+  if (!response.ok) {
+    throw new Error(`Unable to read PMTiles: HTTP ${response.status}`);
+  }
+  const etag = response.headers.get('ETag');
+  if (backend._etag && etag !== backend._etag) {
+    throw new Error('PMTiles archive changed; recreate the layer');
+  }
+  if (etag) backend._etag = etag;
+  let data = await response.arrayBuffer();
+  if (response.status === 200) {
+    data = data.slice(offset, offset + length);
+  } else if (response.status !== 206 ||
+    !response.headers.get('Content-Range')?.startsWith(`bytes ${offset}-${offset + length - 1}/`)) {
+    throw new Error('Invalid PMTiles range response');
+  }
+  if (data.byteLength !== length) {
+    throw new Error('Truncated PMTiles range');
+  }
+  return data;
+}

package/src/utils/readAccessor.js

@@ -0,0 +1,68 @@
+import { types } from "./types.js";
+import { sizes } from "./sizes.js";
+
+/** Decode packed, interleaved, normalized or sparse glTF accessor data. */
+
+export function readAccessor(description, index) {
+  const spec = description.accessors[index], Type = types[spec.componentType], size = sizes[spec.type];
+  if (!Type || !size || !Number.isInteger(spec.count) || spec.count < 0) {
+    throw new Error('Invalid glTF accessor');
+  }
+  const data = new Type(spec.count * size);
+  // The destination callback is sequential for base data and sparse-indexed for overrides.
+  const read = (viewIndex, offset, count, stride, output) => {
+    const view = description.bufferViews[viewIndex], bytes = Type.BYTES_PER_ELEMENT;
+    const buffer = description.buffers[view.buffer].binary;
+    stride ||= size * bytes;
+    if (!buffer || stride < size * bytes || offset < 0 ||
+      (view.byteOffset || 0) + view.byteLength > buffer.byteLength ||
+      (count - 1) * stride + size * bytes + offset > view.byteLength) throw new Error('glTF accessor outside buffer view');
+    for (let i = 0; i < count; i++) {
+      const values = new Type(buffer.slice((view.byteOffset || 0) + offset + i * stride,
+        (view.byteOffset || 0) + offset + i * stride + size * bytes));
+      data.set(values, output(i) * size);
+    }
+  };
+  if (spec.bufferView !== undefined) {
+    read(
+      spec.bufferView,
+      spec.byteOffset || 0,
+      spec.count,
+      description.bufferViews[spec.bufferView].byteStride,
+      i => i
+    );
+  }
+  if (spec.sparse) {
+    const sparse = spec.sparse, Index = types[sparse.indices.componentType];
+    if (![Uint8Array, Uint16Array, Uint32Array].includes(Index)) {
+      throw new Error('Invalid sparse glTF indices');
+    }
+    const view = description.bufferViews[sparse.indices.bufferView];
+    const offset = (view.byteOffset || 0) + (sparse.indices.byteOffset || 0);
+    if (sparse.count > spec.count || (sparse.indices.byteOffset || 0) + sparse.count * Index.BYTES_PER_ELEMENT > view.byteLength) {
+      throw new Error('Invalid sparse glTF indices');
+    }
+    const indices = new Index(description.buffers[view.buffer].binary.slice(offset, offset + sparse.count * Index.BYTES_PER_ELEMENT));
+    read(
+      sparse.values.bufferView,
+      sparse.values.byteOffset || 0,
+      sparse.count,
+      0,
+      i => {
+        if (indices[i] >= spec.count) throw new Error('Invalid sparse glTF index');
+        return indices[i];
+      }
+    );
+  }
+  if (spec.componentType === 5126) {
+    return { data, size };
+  }
+  const normalized = new Float32Array(data.length);
+  // Normalization is a glTF accessor rule, not sRGB conversion; indices stay integers.
+  for (let i = 0; i < data.length; i++) {
+    normalized[i] = spec.normalized
+      ? Math.max(-1, data[i] / (Type === Int8Array ? 127 : Type === Int16Array ? 32767 : Type === Uint8Array ? 255 : Type === Uint32Array ? 4294967295 : 65535))
+      : data[i];
+  }
+  return { data: normalized, size, indices: data };
+}