leaflet-city-mapper 0.0.9 → 0.1.1

package/src/sunlight/useSelectedTime.js

@@ -1,24 +1,26 @@
 import { sunlightByMap } from '../weakmaps/sunlightByMap.js';
+import { render } from './requestSunlightRender.js';
+import { updateSky } from './updateSky.js';
+import { updateSun } from './updateSun.js';
 
-
-
-import { render } from './requestSunlightRender.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 = /* alloc */ new Date(NaN);
-    map.fire('simulationtimechange', /* alloc */ { time: null, live: false });
-    sunlightByMap.delete(map);
-    updateSky(state);
-    render(map);
-    status.textContent = 'Error: choose a valid solar date';
-    return;
-  }
-  control.time = /* alloc */ new Date(`${date.value}T00:00:00Z`);
-  control.time.setUTCMinutes(Number(slider.value));
-  updateSun(state);
-}
+/**
+ * Select the control's UTC date and minute, or report an invalid date.
+ *
+ * @param {Object} state Sunlight and time-control state.
+ */
+export function useSelectedTime(state) {
+  const { control, map, date, slider, status } = state;
+  control.live = false;
+  if (!date.value || !date.validity.valid) {
+    control.time = /* alloc */ new Date(NaN);
+    map.fire('simulationtimechange', /* alloc */ { time: null, live: false });
+    sunlightByMap.delete(map);
+    updateSky(state);
+    render(map);
+    status.textContent = 'Error: choose a valid solar date';
+    return;
+  }
+  control.time = /* alloc */ new Date(`${date.value}T00:00:00Z`);
+  control.time.setUTCMinutes(Number(slider.value));
+  updateSun(state);
+}

package/src/terrain/README.md

@@ -0,0 +1,30 @@
+# Terrain
+
+[Source guide](../README.md) | [Project README](../../README.md)
+
+Loads elevation tiles and optional bridge data, applies terrain to the map and
+provides elevation sampling for other layers and interactions.
+
+## Elevation lifecycle
+
+```mermaid
+flowchart LR
+  Input["Archive / COG / streamed Float32 tiles"] --> Load["Load DEM + optional bridges"]
+  Load --> Apply["Apply terrain to map layers"]
+  Apply --> Events["terrainchange / terrainready"]
+  Events --> Consumers["Raster / models / traffic / walk"]
+  Query["Elevation query"] --> Bridge{"Bridge elevation?"}
+  Bridge -->|yes| Height["Elevation"]
+  Bridge -->|no| DEM["Sample DEM"]
+  DEM --> Height
+```
+
+Streamed tiles are 256 pixels. [getElevation.js](./getElevation.js) returns
+`null` when unavailable, not an actual zero. Removal aborts requests and
+releases terrain resources.
+
+- [initTerrain.js](./initTerrain.js): configure an archive, COG or streamed terrain source.
+- [loadTerrain.js](./loadTerrain.js): load archive terrain and bridge data.
+- [getElevation.js](./getElevation.js): sample the ready DEM or bridge elevation.
+
+Related: [cog](../cog/README.md), [raster](../raster/README.md), [geometry](../geometry/README.md).

package/src/terrain/applyTerrain.js

@@ -1,24 +1,30 @@
 import { locationByLayer } from '../weakmaps/locationByLayer.js';
 import { terrainOriginElevationByLayer } from '../weakmaps/terrainOriginElevationByLayer.js';
 import { terrainReadyByLayer } from '../weakmaps/terrainReadyByLayer.js';
+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/scheduleSceneUpdate.js';
 
-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/scheduleSceneUpdate.js';
-
-export function applyTerrain(layer, map, bridges) {
-
-  terrainReadyByLayer.set(layer, true);
-  terrainOriginElevationByLayer.set(layer, getElevation(layer, locationByLayer.get(layer)) ?? 0);
-  let mapLayer;
-  for (mapLayer of Object.values(map._layers)) {
-    setTerrainHeight(mapLayer);
-    conformModelToTerrain(mapLayer, layer);
-  }
-  if (bridges) addBridges(layer, bridges);
-  map.fire('terrainchange');
-  update(layer);
-  layer.fire('terrainready');
-}
+/**
+ * Mark terrain ready, update map layers and bridge geometry, and notify listeners.
+ *
+ * @param {L.Layer} layer Terrain layer.
+ * @param {L.Map} map Map containing the terrain.
+ * @param {Object} [bridges] Optional bridge GeoJSON.
+ */
+export function applyTerrain(layer, map, bridges) {
+
+  terrainReadyByLayer.set(layer, true);
+  terrainOriginElevationByLayer.set(layer, getElevation(layer, locationByLayer.get(layer)) ?? 0);
+  let mapLayer;
+  for (mapLayer of Object.values(map._layers)) {
+    setTerrainHeight(mapLayer);
+    conformModelToTerrain(mapLayer, layer);
+  }
+  if (bridges) addBridges(layer, bridges);
+  map.fire('terrainchange');
+  update(layer);
+  layer.fire('terrainready');
+}

package/src/terrain/clearLayerTerrain.js

@@ -1,9 +1,11 @@
 import { kindByLayer } from '../weakmaps/kindByLayer.js';
-
-
-
 import { setRasterTerrain } from '../raster/setRasterTerrain.js';
 
+/**
+ * Clear a raster layer's terrain association.
+ *
+ * @param {L.Layer} layer Layer to update if it is raster.
+ */
 export function clearLayerTerrain(layer) {
   if (kindByLayer.get(layer) === 'raster') setRasterTerrain(layer, null);
 }

package/src/terrain/copyTerrainTile.js

@@ -1,12 +1,20 @@
-export function copyTerrainTile(atlas, values, start, columns) {
-  let row, column, value;
-  for (row = 0; row < 256; row++) {
-    for (column = 0; column < 256; column++) {
-      value = values[row * 256 + column];
-      if (!Number.isFinite(value) || value <= -1000) continue;
-      atlas.elevations[start + row * columns * 256 + column] = value;
-      atlas.low = Math.min(atlas.low, value);
-      atlas.high = Math.max(atlas.high, value);
-    }
-  }
-}
+/**
+ * Copy valid elevations from a DEM tile into an atlas and update its extrema.
+ *
+ * @param {Object} atlas Destination elevations and minimum and maximum values.
+ * @param {Float32Array} values Source 256-by-256 elevation tile.
+ * @param {number} start First destination index.
+ * @param {number} columns Number of tile columns in the atlas.
+ */
+export function copyTerrainTile(atlas, values, start, columns) {
+  let row, column, value;
+  for (row = 0; row < 256; row++) {
+    for (column = 0; column < 256; column++) {
+      value = values[row * 256 + column];
+      if (!Number.isFinite(value) || value <= -1000) continue;
+      atlas.elevations[start + row * columns * 256 + column] = value;
+      atlas.low = Math.min(atlas.low, value);
+      atlas.high = Math.max(atlas.high, value);
+    }
+  }
+}

package/src/terrain/getElevation.js

@@ -2,15 +2,18 @@ import { bridgesByLayer } from '../weakmaps/bridgesByLayer.js';
 import { terrainReadyByLayer } from '../weakmaps/terrainReadyByLayer.js';
 import { terrainTilesByLayer } from '../weakmaps/terrainTilesByLayer.js';
 import { terrainZoomByLayer } from '../weakmaps/terrainZoomByLayer.js';
-
 import { L } from '../globals/L.js';
-
-
 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. */
-
+/**
+ * Sample bridge or DEM elevation when the terrain layer is ready.
+ *
+ * @param {L.Layer} layer Terrain layer.
+ * @param {L.LatLng|L.Point} location LatLng, or a pixel point at the terrain zoom.
+ *
+ * @returns {number|null} Elevation in metres, or null when unavailable.
+ */
 export function getElevation(layer, location) {
   if (!layer._map || !terrainReadyByLayer.get(layer)) return null;
   const point = location instanceof L.Point ? location : layer._map.project(location, terrainZoomByLayer.get(layer));

package/src/terrain/initTerrain.js

@@ -4,9 +4,6 @@ import { terrainReadyByLayer } from '../weakmaps/terrainReadyByLayer.js';
 import { terrainSourceByLayer } from '../weakmaps/terrainSourceByLayer.js';
 import { terrainTilesByLayer } from '../weakmaps/terrainTilesByLayer.js';
 import { streamTerrainByLayer } from '../weakmaps/streamTerrainByLayer.js';
-
-
-
 import { onTerrainRemove } from './onTerrainRemove.js';
 import { onTerrainAdd } from './onTerrainAdd.js';
 import { init3D } from '../scene/init3D.js';
@@ -16,6 +13,11 @@ import { init3D } from '../scene/init3D.js';
  * Source options: `url` (single-zoom Float32 PMTiles or supported COG DEM),
  * or `getTile(z, x, y, signal)` for streamed 256px Float32 elevations;
  * `bridges` (optional GeoJSON deck polygons with Z, see _addBridges).
+ *
+ * @param {L.Layer} layer Terrain layer to initialize.
+ * @param {Object} options Terrain and rendering options.
+ *
+ * @throws {Error} If getTile is supplied but is not a function.
  */
 export function initTerrain(layer, options) {
   if (options.getTile !== undefined && typeof options.getTile !== 'function') {

package/src/terrain/loadReadyTerrain.js

@@ -1,5 +1,6 @@
-import { loadTerrain } from './loadTerrain.js';
-
-export function loadReadyTerrain() {
-  loadTerrain(this.backend).then(this.resolve, this.reject);
-}
+import { loadTerrain } from './loadTerrain.js';
+
+/** Load the terrain backend after it is ready and settle the associated promise. */
+export function loadReadyTerrain() {
+  loadTerrain(this.backend).then(this.resolve, this.reject);
+}

package/src/terrain/loadTerrain.js

@@ -6,14 +6,22 @@ import { terrainLoadingByLayer } from '../weakmaps/terrainLoadingByLayer.js';
 import { terrainReadyByLayer } from '../weakmaps/terrainReadyByLayer.js';
 import { terrainSourceByLayer } from '../weakmaps/terrainSourceByLayer.js';
 import { workerMapByLayer } from '../weakmaps/workerMapByLayer.js';
-
 import { createLayer } from '../scene/createLayer.js';
-
 import { loadTerrainTiles } from './loadTerrainTiles.js';
 import { readBridges } from './readBridges.js';
 import { terrainTileQueue } from './terrainTileQueue.js';
 import { applyTerrain } from './applyTerrain.js';
 
+/**
+ * Load archive terrain tiles and optional bridges, then apply them to the map.
+ *
+ * @param {L.Layer} layer Terrain layer.
+ *
+ * @returns {Promise<boolean|undefined>} True on success, false on failure, or undefined if skipped or cancelled.
+ *
+ * @throws {Error} Raised internally and reported as a layer error if the archive URL is missing.
+ * @throws {Error} Raised internally and reported as a layer error if the archive is not single-zoom Float32.
+ */
 export async function loadTerrain(layer) {
   if (terrainLoadingByLayer.get(layer) || !layer._map) return;
   terrainLoadingByLayer.set(layer, true);

package/src/terrain/loadTerrainTiles.js

@@ -1,7 +1,15 @@
 import { terrainTilesByLayer } from '../weakmaps/terrainTilesByLayer.js';
+import { getZxy } from '../archives/getZxy.js';
 
-
-
+/**
+ * Consume the shared tile queue and store decoded Float32 terrain tiles.
+ *
+ * @param {Object} state Queue, archive, layer and cancellation state.
+ *
+ * @returns {Promise<void>} Resolves when the queue is exhausted.
+ *
+ * @throws {Error} If a tile is missing or has an invalid byte length.
+ */
 export async function loadTerrainTiles(state) {
   const { backend: layer, archive, controller, tiles } = state;
   let coords, result;
@@ -15,4 +23,3 @@ export async function loadTerrainTiles(state) {
     terrainTilesByLayer.get(layer).set(`${coords.x}/${coords.y}`, /* alloc */ new Float32Array(result.data));
   }
 }
-import { getZxy } from '../archives/getZxy.js';

package/src/terrain/mapElevationOf.js

@@ -1,11 +1,19 @@
-import { terrain3DByMap } from '../weakmaps/terrain3DByMap.js';
-import { streamTerrainByMap } from '../weakmaps/streamTerrainByMap.js';
-import { getElevation } from './getElevation.js';
-import { gridTerrainElevation } from '../native/gridTerrainElevation.js';
-
-export function mapElevationOf(map, location) {
-  const terrain = terrain3DByMap.get(map);
-  if (terrain) return getElevation(terrain, location);
-  const stream = streamTerrainByMap.get(map);
-  return stream && gridTerrainElevation(stream, location);
-}
+import { terrain3DByMap } from '../weakmaps/terrain3DByMap.js';
+import { streamTerrainByMap } from '../weakmaps/streamTerrainByMap.js';
+import { getElevation } from './getElevation.js';
+import { gridTerrainElevation } from '../native/gridTerrainElevation.js';
+
+/**
+ * Sample the map's archive or streamed terrain at a location.
+ *
+ * @param {L.Map} map Map containing terrain.
+ * @param {L.LatLng|L.Point} location Location to sample.
+ *
+ * @returns {number|null|undefined} Elevation in metres, or a nullish value when unavailable.
+ */
+export function mapElevationOf(map, location) {
+  const terrain = terrain3DByMap.get(map);
+  if (terrain) return getElevation(terrain, location);
+  const stream = streamTerrainByMap.get(map);
+  return stream && gridTerrainElevation(stream, location);
+}

package/src/terrain/onTerrainAdd.js

@@ -3,16 +3,20 @@ import { terrainPromiseByLayer } from '../weakmaps/terrainPromiseByLayer.js';
 import { terrain3DByMap } from '../weakmaps/terrain3DByMap.js';
 import { streamTerrainByMap } from '../weakmaps/streamTerrainByMap.js';
 import { streamTerrainByLayer } from '../weakmaps/streamTerrainByLayer.js';
-
-
-
-
 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';
 
+/**
+ * Attach archive or streamed terrain to a map and start loading when needed.
+ *
+ * @param {L.Layer} layer Terrain layer.
+ * @param {L.Map} map Map receiving the terrain.
+ *
+ * @throws {Error} If another terrain layer is already active on the map.
+ */
 export function onTerrainAdd(layer, map) {
 
   if (streamTerrainByMap.get(map) || terrain3DByMap.get(map) && terrain3DByMap.get(map) !== layer) {

package/src/terrain/onTerrainChange.js

@@ -1,12 +1,12 @@
 import { areasByLayer } from '../weakmaps/areasByLayer.js';
-
-
-
 import { releaseArea } from '../sources/releaseArea.js';
 import { updateArea } from "../sources/updateArea.js";
 
-/** GeoJSON source areas: loading, building and releasing. */
-
+/**
+ * Release and reload source areas when terrain changes.
+ *
+ * @param {L.Layer} layer Source layer to update.
+ */
 export function onTerrainChange(layer) {
   if (!layer._map) return;
   let area;

package/src/terrain/onTerrainRemove.js

@@ -12,10 +12,7 @@ import { terrainReadyByLayer } from '../weakmaps/terrainReadyByLayer.js';
 import { terrainTilesByLayer } from '../weakmaps/terrainTilesByLayer.js';
 import { terrain3DByMap } from '../weakmaps/terrain3DByMap.js';
 import { streamTerrainByMap } from '../weakmaps/streamTerrainByMap.js';
-
-
 import { renderEmpty } from '../globals/renderEmpty.js';
-
 import { destroyTexture } from '../textures/destroyTexture.js';
 import { conformModelToTerrain } from '../geometry/conformModelToTerrain.js';
 import { disposeMesh } from '../rendering/disposeMesh.js';
@@ -25,6 +22,12 @@ import { setTerrainHeight } from './setTerrainHeight.js';
 import { onRemove3DLayer } from '../scene/onRemove3DLayer.js';
 import { clearLayerTerrain } from './clearLayerTerrain.js';
 
+/**
+ * Detach terrain from a map and release associated requests and rendering resources.
+ *
+ * @param {L.Layer} layer Terrain layer to remove.
+ * @param {L.Map} map Map containing the terrain.
+ */
 export function onTerrainRemove(layer, map) {
   const stream = streamTerrainByMap.get(map);
   if (stream?.layer === layer) {

package/src/terrain/readBridges.js

@@ -1,4 +1,13 @@
-export function readBridges(response) {
-  if (!response.ok) throw /* alloc */ new Error(`Bridges: HTTP ${response.status}`);
-  return response.json();
-}
+/**
+ * Read bridge GeoJSON from a successful HTTP response.
+ *
+ * @param {Response} response Bridge request response.
+ *
+ * @returns {Promise<Object>} Parsed bridge GeoJSON.
+ *
+ * @throws {Error} If the response has a non-success status.
+ */
+export function readBridges(response) {
+  if (!response.ok) throw /* alloc */ new Error(`Bridges: HTTP ${response.status}`);
+  return response.json();
+}

package/src/terrain/readyTerrainOf.js

@@ -1,7 +1,14 @@
-import { terrain3DByMap } from '../weakmaps/terrain3DByMap.js';
-import { terrainReadyByLayer } from '../weakmaps/terrainReadyByLayer.js';
-
-export function readyTerrainOf(map) {
-  const terrain = terrain3DByMap.get(map);
-  return terrainReadyByLayer.get(terrain) && terrain;
-}
+import { terrain3DByMap } from '../weakmaps/terrain3DByMap.js';
+import { terrainReadyByLayer } from '../weakmaps/terrainReadyByLayer.js';
+
+/**
+ * Find the map's archive terrain if it is ready.
+ *
+ * @param {L.Map} map Map to inspect.
+ *
+ * @returns {L.Layer|false|undefined} Ready terrain or a falsy value.
+ */
+export function readyTerrainOf(map) {
+  const terrain = terrain3DByMap.get(map);
+  return terrainReadyByLayer.get(terrain) && terrain;
+}

package/src/terrain/sampleTerrainTile.js

@@ -1,7 +1,16 @@
-export function sample(tiles, px, py) {
-  const tileX = Math.floor(px / 256), tileY = Math.floor(py / 256);
-  const tile = tiles.get(`${tileX}/${tileY}`);
-  if (!tile) return null;
-  const elevation = tile[(py - tileY * 256) * 256 + px - tileX * 256];
-  return Number.isFinite(elevation) && elevation > -1000 ? elevation : null;
-}
+/**
+ * Sample one integer pixel from the terrain tile map.
+ *
+ * @param {Map} tiles DEM tiles keyed by x/y.
+ * @param {number} px Global pixel x coordinate.
+ * @param {number} py Global pixel y coordinate.
+ *
+ * @returns {number|null} Elevation, or null for a missing or invalid sample.
+ */
+export function sample(tiles, px, py) {
+  const tileX = Math.floor(px / 256), tileY = Math.floor(py / 256);
+  const tile = tiles.get(`${tileX}/${tileY}`);
+  if (!tile) return null;
+  const elevation = tile[(py - tileY * 256) * 256 + px - tileX * 256];
+  return Number.isFinite(elevation) && elevation > -1000 ? elevation : null;
+}

package/src/terrain/setLayerTerrain.js

@@ -1,9 +1,11 @@
 import { kindByLayer } from '../weakmaps/kindByLayer.js';
-
-
-
 import { setRasterTerrain } from '../raster/setRasterTerrain.js';
 
+/**
+ * Associate a raster layer with this terrain layer.
+ *
+ * @param {L.Layer} layer Layer to update if it is raster.
+ */
 export function setLayerTerrain(layer) {
   if (kindByLayer.get(layer) === 'raster') setRasterTerrain(layer, this);
 }

package/src/terrain/setTerrainHeight.js

@@ -2,12 +2,13 @@ import { locationByLayer } from '../weakmaps/locationByLayer.js';
 import { rootByLayer } from '../weakmaps/rootByLayer.js';
 import { terrainBaseYByLayer } from '../weakmaps/terrainBaseYByLayer.js';
 import { terrain3DByMap } from '../weakmaps/terrain3DByMap.js';
-
-
-
-
 import { getElevation } from './getElevation.js';
 
+/**
+ * Position a layer's root at its saved base height plus available terrain elevation.
+ *
+ * @param {L.Layer} layer Layer whose root height should change.
+ */
 export function setTerrainHeight(layer) {
 
   if (!rootByLayer.get(layer) || !locationByLayer.get(layer)) return;

package/src/terrain/terrainAtlas.js

@@ -1,7 +1,13 @@
 import { copyTerrainTile } from './copyTerrainTile.js';
 
-/** Float32 DEM atlas; missing samples retain the shader no-data sentinel. */
-
+/**
+ * Build a Float32 DEM atlas; missing samples retain the shader no-data sentinel.
+ *
+ * @param {Map} tiles DEM tiles keyed by x/y.
+ * @param {L.Bounds} bounds Tile-coordinate bounds.
+ *
+ * @returns {Object} Atlas elevations and valid minimum and maximum values.
+ */
 export function terrainAtlas(tiles, bounds) {
   const columns = bounds.max.x - bounds.min.x + 1, rows = bounds.max.y - bounds.min.y + 1;
   const elevations = /* alloc */ new Float32Array(columns * rows * 65536).fill(-1e9);

package/src/terrain/terrainElevation.js

@@ -1,7 +1,13 @@
 import { sample } from './sampleTerrainTile.js';
 
-/** Bilinear DEM sampling, with the original first-valid-neighbour no-data rule. */
-
+/**
+ * Sample the DEM bilinearly, falling back to the first valid neighbour for no-data.
+ *
+ * @param {L.Point} point Pixel location at terrain zoom.
+ * @param {Map} tiles DEM tiles keyed by x/y.
+ *
+ * @returns {number|null} Elevation, or null when no neighbour is valid.
+ */
 export function terrainElevation(point, tiles) {
   const x = point.x - 0.5, y = point.y - 0.5;
   const x0 = Math.floor(x), y0 = Math.floor(y);

package/src/terrain/terrainTileQueue.js

@@ -1,27 +1,34 @@
 import { terrainBoundsByLayer } from '../weakmaps/terrainBoundsByLayer.js';
 import { terrainZoomByLayer } from '../weakmaps/terrainZoomByLayer.js';
+import { L } from '../globals/L.js';
+import { archiveNorthWest } from '../globals/archiveNorthWest.js';
+import { archiveSouthEast } from '../globals/archiveSouthEast.js';
+import { compareDistance } from '../utils/compareDistance.js';
 
-import { L } from '../globals/L.js';
-import { archiveNorthWest } from '../globals/archiveNorthWest.js';
-import { archiveSouthEast } from '../globals/archiveSouthEast.js';
-import { compareDistance } from '../utils/compareDistance.js';
-
-export function terrainTileQueue(layer, header) {
-  const map = layer._map
-  terrainZoomByLayer.set(layer, header.maxZoom);
-  archiveNorthWest[0] = header.maxLat; archiveNorthWest[1] = header.minLon;
-  const northwest = map.project(archiveNorthWest, terrainZoomByLayer.get(layer)).divideBy(256).floor();
-  archiveSouthEast[0] = header.minLat; archiveSouthEast[1] = header.maxLon;
-  const southeast = map.project(archiveSouthEast, terrainZoomByLayer.get(layer)).divideBy(256).floor();
-  terrainBoundsByLayer.set(layer, /* alloc */ new L.Bounds(northwest, southeast));
-  const tiles = /* alloc */ [];
-  const center = map.project(map.getCenter(), terrainZoomByLayer.get(layer)).divideBy(256);
-  let x, y;
-  for (x = northwest.x; x <= southeast.x; x++) {
-    for (y = northwest.y; y <= southeast.y; y++) {
-      tiles.push(/* alloc */ { z: terrainZoomByLayer.get(layer), x, y, distance: Math.hypot(x + 0.5 - center.x, y + 0.5 - center.y) });
-    }
-  }
-  tiles.sort(compareDistance);
-  return tiles;
-}
+/**
+ * Build the archive terrain tile queue ordered by distance from the map center.
+ *
+ * @param {L.Layer} layer Terrain layer.
+ * @param {Object} header Archive bounds and zoom metadata.
+ *
+ * @returns {Object[]} Tile coordinates with their distance from the center.
+ */
+export function terrainTileQueue(layer, header) {
+  const map = layer._map
+  terrainZoomByLayer.set(layer, header.maxZoom);
+  archiveNorthWest[0] = header.maxLat; archiveNorthWest[1] = header.minLon;
+  const northwest = map.project(archiveNorthWest, terrainZoomByLayer.get(layer)).divideBy(256).floor();
+  archiveSouthEast[0] = header.minLat; archiveSouthEast[1] = header.maxLon;
+  const southeast = map.project(archiveSouthEast, terrainZoomByLayer.get(layer)).divideBy(256).floor();
+  terrainBoundsByLayer.set(layer, /* alloc */ new L.Bounds(northwest, southeast));
+  const tiles = /* alloc */ [];
+  const center = map.project(map.getCenter(), terrainZoomByLayer.get(layer)).divideBy(256);
+  let x, y;
+  for (x = northwest.x; x <= southeast.x; x++) {
+    for (y = northwest.y; y <= southeast.y; y++) {
+      tiles.push(/* alloc */ { z: terrainZoomByLayer.get(layer), x, y, distance: Math.hypot(x + 0.5 - center.x, y + 0.5 - center.y) });
+    }
+  }
+  tiles.sort(compareDistance);
+  return tiles;
+}

package/src/textures/README.md

@@ -0,0 +1,29 @@
+# Textures
+
+[Source guide](../README.md) | [Project README](../../README.md)
+
+Manages image uploads and GPU textures for scene meshes, models and native
+layers, including the raster atlas used for roofs.
+
+## Upload, reuse and release
+
+```mermaid
+flowchart LR
+  Model["Model images"] --> Cache["Texture cache: color / data"]
+  Native["Native images"] --> Upload["GPU texture upload"]
+  Cache --> Upload
+  Rasters["Raster versions / opacity / order"] --> Atlas["Roof atlas"]
+  Atlas --> Upload
+  Upload --> Bind["Mesh bind group"]
+  Bind --> Draw["Render"]
+  Draw --> Release["Destroy after submitted work"]
+```
+
+Atlas rebuilds are throttled while tiles load. Binding changes trigger a bind
+group rebuild; resource destruction must wait for submitted GPU work.
+
+- [prepareMeshTextures.js](./prepareMeshTextures.js): prepare textures for a mesh.
+- [modelTextureFor.js](./modelTextureFor.js): create or reuse a model texture.
+- [updateRoofAtlas.js](./updateRoofAtlas.js): refresh the roof atlas when raster layers change.
+
+Related: [materials](../materials/README.md), [raster](../raster/README.md), [native](../native/README.md).