leaflet-city-mapper 0.0.1 → 0.0.2

package/src/index.js

@@ -1,82 +1,397 @@
+import './utils/mapCamera.js';
+
 /**
  * `new L.Layer({ source: { type, url, ...settings }, pane, attribution })`: layers with a `source`
- * load their type module on first use. Subclasses are unchanged.
+ * load their specialized utilities on first use. Native map layers also join the WebGPU scene.
  */
 
 /**
  * Router for `new L.Layer({ source: { type, url, ...settings }, pane, attribution })`.
- * It imports the type module on demand and turns the
- * layer into it; types receive flat options (`{ ...source, pane, attribution }`), so `layer.options.url` etc.
+ * It imports source utilities on demand and initializes the existing instance;
+ * types receive flat options (`{ ...source, pane, attribution }`), so `layer.options.url` etc.
  *
  * Folder layout:
- * - types/: one module per `source.type`, the only files imported by this router:
- *   - 'pmtiles': raster PMTiles basemap (an L.TileLayer), draped on the terrain when present;
- *   - '3d': shared WebGPU scene with a GLB/glTF model, PMTiles GeoJSON features, or empty;
- *   - 'geojson': inline or URL-backed GeoJSON features rendered by the shared 3D scene;
- *   - 'terrain': Float32 PMTiles DEM that deforms raster tiles, buildings and the camera, plus optional bridge decks;
- *   - 'sunlight': simulation clock control, sun/moon lighting and shadows;
- *   - 'traffic': vehicles moving along GeoJSON lanes (measured flow or timetable);
- *   - 'walk': third-person pedestrian moved with the keyboard, the camera following behind.
- * - scene/: named operations for GPU resources, model/archive loading, lighting, sources, picking
- *   and rendering. They receive the layer explicitly; types/3d.js declares its delegates, without mixins.
- * - utils/: computations and scene-data helpers, independent of Leaflet layers and GPU devices.
- *   Geometry, decoders, lighting grids, terrain sampling, traffic and collisions can be tested in Node;
- *   scene transforms/picking use browser DOMMatrix/DOMPoint, and CSS colors use a canvas.
+ * - Vector ('3d', 'geojson') and raster ('pmtiles') initialization lives here.
+ * - utils/: lazy operations for rendering, archives, geometry and specialized layers:
+ *   terrain (Float32 DEM), sunlight (clock and lighting), traffic and walking.
+ *   Operations receive the layer explicitly, without subclasses or prototype replacement.
  * Dataset-specific code and data (routes, timetables, API loaders) belong to the application, e.g. misc/.
  *
- * When `type` is omitted it is inferred from `source.url`: *.pmtiles -> 'pmtiles', anything else -> '3d'.
+ * When `type` is omitted, inline FeatureCollections use 'geojson'; otherwise *.pmtiles URLs use
+ * 'pmtiles' and other sources use '3d'.
  */
 
 const layerProto = Object.defineProperties({}, Object.getOwnPropertyDescriptors(L.Layer.prototype));
 
-// Stand-in while the type module loads: remembers the map, renders nothing.
-const Pending = L.Layer.extend({
-  onAdd() {},
-  onRemove() {},
-});
-
 // One chain for every pending layer: they become real layers in creation order, whatever the import timing.
 let loading = Promise.resolve();
+let sceneModules, sceneLoading, rasterModules;
+let nativeLoading;
 
-// Shared registry: type modules (src/types) register here.
-L.Layer.types = {};
+/**
+ * The '3d' layer type: native WebGPU scene synchronized with the map camera.
+ * Layers on one map share a canvas, scene and camera; each has its own root transform.
+ *
+ * @typedef {Object} Layer3DOptions Layer options; pane and attribution remain standard L.Layer options.
+ * @property {string} [type] '3d', 'geojson', 'pmtiles', 'terrain', 'sunlight', 'traffic' or 'walk'.
+ * @property {number[]} [center] Local origin [lat,lng]; defaults to the first map center.
+ * @property {number} [terrainOffset=0] Vertical offset in metres when terrain is enabled.
+ * @property {boolean} [terrainConform=false] Fit lower model geometry to local terrain elevation.
+ * @property {'OPAQUE'|'MASK'|'BLEND'} [alphaMode] Override every glTF material's alpha mode.
+ * @property {number[]} [rotation] Model Euler rotation [x,y,z] in radians, YXZ order.
+ * @property {number[]} [scale] Model scale [x,y,z].
+ * @property {string} [url] GLB/glTF model URL or PMTiles archive URL.
+ * @property {function(Object): (ExtrusionStyle|null)} [style] Source styling; null skips a feature.
+ * @property {function(PickedFeature): (Node|string)} [tooltip] Tooltip content; strings are text.
+ * @property {string} [ariaLabel='3D scene'] Shared canvas accessible name.
+ * @property {boolean} [nightLight=false] Point sources: emissive bulbs and local illumination.
+ * @property {boolean} [nightSparkle=false] Model: sparse luminous points at night.
+ *
+ * @typedef {Object} ExtrusionStyle
+ * @property {number} top Roof height in metres; must exceed bottom.
+ * @property {number} [bottom=0] Nonnegative base height.
+ * @property {number|string|Object} [color=0xd9b38c] RGB/CSS color or linear-space {h,s,l}.
+ * @property {number} [trunkRadius] Point tree trunk radius in metres.
+ * @property {number} [crownRadius] Point tree crown radius in metres.
+ * @property {number} [crownBottom] Point tree crown base in metres.
+ * @property {string} [crownShape='round'] Point tree crown shape.
+ * @property {number|string|Object} [trunkColor=0x72513a] Point tree bark color.
+ * @property {number} [lightRadius] Point light estimated ground reach in metres.
+ * @property {number} [lightFlux] Point light luminous flux in lumens.
+ *
+ * @typedef {Object} PickedFeature
+ * @property {string|number} id Source feature id or configured model URL.
+ * @property {Object} properties GeoJSON properties or model-level glTF extras.
+ * @property {Object} mesh Intersected mesh.
+ * @property {number[]} point Intersection [x,y,z] in shared scene metres.
+ * @property {Object} [model] Configured model root; absent for source polygons.
+ * @property {number} [vertexStart] First polygon vertex in the batched mesh.
+ * @property {number} [vertexEnd] Exclusive end of the polygon's vertex range.
+ *
+ * @typedef {Object} SourceArea
+ * @property {Object} coords Archive block {z,x,y}.
+ * @property {AbortController} request Cancellation prevents attaching obsolete results.
+ * @property {boolean} [done] Geometry built successfully, including empty blocks.
+ * @property {Object|null} [mesh] Batched GPU mesh.
+ * @property {number} [buildings] Emitted feature count.
+ * @property {number} [skipped] Features skipped by style.
+ * @property {string} [error] Failed load/build message.
+ *
+ * @param {L.Layer} backend
+ * @param {Layer3DOptions} [options] World origin comes from center or the first map centre.
+ */
+
+L.Layer._renderers = new WeakMap();
+L.Layer._nextId = 0;
 
-// Core L.Layer has no initialize and init hooks get no arguments: keep the options for the hook.
 L.Layer.include({
+  _layerAdd(event) {
+    const native = !this._3d && (
+      this instanceof L.GridLayer ||
+      this instanceof L.Polyline ||
+      this instanceof L.CircleMarker ||
+      this instanceof L.Marker && !(this.options.icon instanceof L.DivIcon) ||
+      this instanceof L.ImageOverlay && !(this instanceof L.VideoOverlay) && !(this instanceof L.SVGOverlay)
+    );
+    if (native) {
+      if (this instanceof L.GridLayer || this instanceof L.ImageOverlay) {
+        this.options.crossOrigin ||= true;
+      }
+      if (this instanceof L.Marker) this.options.icon.options.crossOrigin ||= true;
+    }
+    layerProto._layerAdd.call(this, event);
+    if (!native || !event.target.hasLayer(this)) return;
+    this._initNativeGPU(event.target);
+  },
+  _initNativeGPU(map) {
+    if (this._nativeGPU) return;
+    if (!document.getElementById('leaflet-webgpu-targets')) {
+      const style = document.createElement('style');
+      style.id = 'leaflet-webgpu-targets';
+      style.textContent = '.leaflet-webgpu-target{opacity:0!important}';
+      document.head.append(style);
+    }
+    const state = this._nativeGPU = { source: this, map, hidden: new Set() };
+    state.hide = () => {
+      const htmlIcon = this instanceof L.Marker && this.options.icon instanceof L.DivIcon;
+      const targets = [htmlIcon ? null : this._icon, htmlIcon ? null : this._shadow];
+      for (const element of state.hidden) {
+        if (targets.includes(element)) continue;
+        element.classList.remove('leaflet-webgpu-target');
+        state.hidden.delete(element);
+      }
+      for (const element of targets) {
+        if (!element || state.hidden.has(element)) continue;
+        element.classList.add('leaflet-webgpu-target');
+        state.hidden.add(element);
+      }
+    };
+    state.hide();
+    this.once('remove', () => {
+      if (this._nativeGPU === state) this._nativeGPU = null;
+      state.dispose?.();
+      for (const element of state.hidden) {
+        element.classList.remove('leaflet-webgpu-target');
+      }
+    });
+
+    nativeLoading ||= import('./utils/nativeLayer.js');
+    this.ready = nativeLoading.then(({ nativeLayer }) => {
+      if (this._nativeGPU !== state) return this;
+      return nativeLayer(state);
+    });
+    this.ready.catch(error => this.fire('error', { error }));
+  },
+  _init3D(options = {}) {
+    const layer = this;
+    const ready = sceneLoading ||= Promise.all([
+      import('./utils/onAdd3DLayer.js'),
+      import('./utils/onRemove3DLayer.js'),
+      import('./utils/updateArea.js'),
+      import('./utils/onTerrainChange.js'),
+    ]).then(([add, remove, update, terrain]) => sceneModules = { ...add, ...remove, ...update, ...terrain });
+    layer._3d = true;
+    L.Util.setOptions(layer, { ariaLabel: '3D scene', ...options });
+    layer.onAdd = map => {
+      if (sceneModules) return sceneModules.onAdd3DLayer(layer, map);
+      ready.then(({ onAdd3DLayer }) => {
+        if (layer._map === map) onAdd3DLayer(layer, map);
+      }).catch(error => layer.fire('error', { error }));
+    };
+    layer.onRemove = map => {
+      if (sceneModules) return sceneModules.onRemove3DLayer(layer, map);
+      ready.then(({ onRemove3DLayer }) => onRemove3DLayer(layer, map))
+        .catch(error => layer.fire('error', { error }));
+    };
+    layer.getEvents = () => {
+      const events = {};
+      if (layer.url) {
+        events.moveend = events.zoomend = events.rotate = events.pitch = events.resize = () =>
+          sceneModules ? sceneModules.updateArea(layer) : ready.then(({ updateArea }) => updateArea(layer));
+      }
+      if (layer._geojson || layer.url) {
+        events.terrainchange = () => sceneModules
+          ? sceneModules.onTerrainChange(layer)
+          : ready.then(({ onTerrainChange }) => onTerrainChange(layer));
+      }
+      return events;
+    };
+    // ponytail: models are recognised by extension; extensionless model URLs need a .glb/.gltf suffix or query.
+    const isModel = !layer._geojson && /\.(glb|gltf)(?:[?#]|$)/i.test(layer.options.url);
+    layer.modelUrl = isModel ? layer.options.url : null;
+    layer.url = layer.options.url && !isModel && !layer._geojson ? new URL(layer.options.url, document.baseURI).href : null;
+    layer._directories = new Map();
+    if (layer.options.center) {
+      layer.location = new L.LatLng(layer.options.center[0], layer.options.center[1]);
+    }
+    /** @type {Map<string, SourceArea>} Keys are archive x/y, not screen tiles. */
+    layer._areas = new Map();
+    layer._inflight = 0;
+    layer._added = Promise.withResolvers();
+    queueMicrotask(async () => {
+      try {
+        await ready;
+        layer.root = (await import('./utils/emptyNode.js')).emptyNode();
+        layer.raycaster = { origin: [0, 0, 0], direction: [0, 0, 0] };
+        if (layer.url || layer._geojson) {
+          layer.group = layer.root;
+          if (layer.url) layer.header = await (await import('./utils/getHeader.js')).getHeader(layer);
+        }
+        if (layer._map) {
+          await (await import('./utils/attach.js')).attach(layer, layer._map);
+          layer._added.resolve();
+        }
+        if (layer.modelUrl) await (await import('./utils/loadModel.js')).loadModel(layer);
+        if (layer._shared) (await import('./utils/update.js')).update(layer);
+        layer.fire('ready');
+      } catch (error) {
+        layer.fire('error', { error });
+      }
+    });
+  },
+  _initRaster(options) {
+    const layer = this;
+    const [{ read }, { getHeader }, { getZxy }, { onPMTileAdd }, { onPMTileRemove },
+      { getRasterTileSize, updateRasterTiles }, { setPMTileOpacity }, { setPMTileZIndex }, { emptyNode }] = rasterModules;
+    layer._read = (offset, length, signal) => read(layer, offset, length, signal);
+    layer.getHeader = () => getHeader(layer);
+    layer.getZxy = (z, x, y, signal) => getZxy(layer, z, x, y, signal);
+    layer.getTileSize = () => getRasterTileSize();
+    layer.isLoading = () => layer._loadingTiles > 0;
+    layer.setOpacity = opacity => setPMTileOpacity(layer, opacity);
+    layer.setZIndex = zIndex => setPMTileZIndex(layer, zIndex);
+    layer.onAdd = map => onPMTileAdd(layer, map);
+    layer.onRemove = map => onPMTileRemove(layer, map);
+    const update = () => updateRasterTiles(layer);
+    layer.getEvents = () => ({
+      moveend: update,
+      zoomend: update,
+      rotate: update,
+      pitch: update,
+      resize: update,
+    });
+    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(async 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;
+    }).catch(error => {
+      layer.fire('error', { error });
+      throw error;
+    });
+  },
   initialize(options = {}) {
     if (Object.getPrototypeOf(this) !== L.Layer.prototype || !options.source) {
       if (layerProto.initialize) return layerProto.initialize.apply(this, arguments);
       L.Util.setOptions(this, options);
       return;
     }
-    const layer = this;
-    const { source: { type = /\.pmtiles(?:[?#]|$)/i.test(options.source.url) ? 'pmtiles' : '3d', ...source }, ...core } = options;
+    const {
+      source: {
+        type = options.source.data?.type === 'FeatureCollection'
+          ? 'geojson'
+          : /\.pmtiles(?:[?#]|$)/i.test(options.source.url) ? 'pmtiles' : '3d',
+        ...source
+      },
+      ...core
+    } = options;
     const settings = { ...source, ...core };
-    // A stand-in created by the entry point before this module loaded may already be on a map.
-    const map = layer._map;
-    map?.removeLayer(layer);
-    delete layer.onAdd;
-    delete layer.onRemove;
-    if (L.Layer.types[type]) {
-      Object.setPrototypeOf(layer, L.Layer.types[type].prototype);
-      layer.options = Object.create(L.Layer.types[type].prototype.options);
-      L.Layer.types[type].prototype.initialize.call(layer, settings);
-      map?.addLayer(layer);
+    L.Util.setOptions(this, core);
+    this._type = type;
+    if (type === '3d') {
+      this._init3D(settings);
+      return;
+    }
+    if (type === 'pmtiles' && rasterModules) {
+      this._initRaster(settings);
       return;
     }
-    Object.setPrototypeOf(layer, Pending.prototype);
-    L.Util.setOptions(layer, core);
-    map?.addLayer(layer);
+    this.onAdd = () => {};
+    this.onRemove = () => {};
     // ponytail: type methods (setOpacity, add, ...) exist only once `ready` resolves.
-    loading = loading.catch(() => {}).then(() => import(`./types/${type}.js`));
-    const pending = layer.ready = loading.then(() => {
-      const map = layer._map;
-      map?.removeLayer(layer);
-      Object.setPrototypeOf(layer, L.Layer.types[type].prototype);
-      layer.options = Object.create(L.Layer.types[type].prototype.options);
-      L.Layer.types[type].prototype.initialize.call(layer, settings);
-      map?.addLayer(layer);
-      return layer.ready === pending ? layer : layer.ready;
+    loading = loading.catch(() => {}).then(async () => {
+      switch (type) {
+        case 'geojson': {
+          const { setGeoJSONData } = await import('./utils/setGeoJSONData.js');
+          return (layer, options) => {
+            layer._geojson = true;
+            layer.setData = data => setGeoJSONData(layer, data);
+            layer._init3D(options);
+          };
+        }
+        case 'pmtiles': {
+          rasterModules = await Promise.all([
+            import('./utils/read.js'),
+            import('./utils/getHeader.js'),
+            import('./utils/getZxy.js'),
+            import('./utils/onPMTileAdd.js'),
+            import('./utils/onPMTileRemove.js'),
+            import('./utils/rasterTiles.js'),
+            import('./utils/setPMTileOpacity.js'),
+            import('./utils/setPMTileZIndex.js'),
+            import('./utils/emptyNode.js'),
+          ]);
+          return (layer, options) => layer._initRaster(options);
+        }
+        case 'terrain':
+          return (await import('./utils/initTerrain.js')).initTerrain;
+        case 'sunlight':
+          return (await import('./utils/initSunlight.js')).initSunlight;
+        case 'traffic':
+          return (await import('./utils/initTraffic.js')).initTraffic;
+        case 'walk':
+          return (await import('./utils/initWalk.js')).initWalk;
+        default:
+          throw new Error(`Unknown layer type: ${type}`);
+      }
+    });
+    const ready = this.ready = loading.then(initialize => {
+      const map = this._map;
+      map?.removeLayer(this);
+      delete this.onAdd;
+      delete this.onRemove;
+      initialize(this, settings);
+      map?.addLayer(this);
+      return this.ready === ready ? this : this.ready;
     });
+    ready.catch(error => this.fire('error', { error }));
   },
+});
+
+L.Layer.addInitHook(function () {
+  if (this instanceof L.Polyline || this instanceof L.CircleMarker) {
+    const refresh = () => this._nativeGPU?.refresh?.();
+    this.beforeAdd = this.onAdd = this.onRemove = this._updateBounds = () => {};
+    this.getEvents = () => ({});
+    // Leaflet mutators call this renderer contract, but no SVG/Canvas renderer is created.
+    this._renderer = {
+      options: { tolerance: 0 },
+      _updatePath: refresh,
+      _updateStyle: refresh,
+      _bringToFront: () => this._nativeGPU?.reorder?.(true),
+      _bringToBack: () => this._nativeGPU?.reorder?.(false),
+    };
+    if (this instanceof L.Polyline) {
+      const closest = this.closestLayerPoint;
+      this.closestLayerPoint = function (point) {
+        this._project();
+        this._parts = this._rings;
+        return closest.call(this, point);
+      };
+    }
+    if (this instanceof L.Circle) {
+      const getBounds = this.getBounds;
+      this.getBounds = function () {
+        this._project();
+        return getBounds.call(this);
+      };
+    }
+  } else if (this instanceof L.GridLayer) {
+    const initialize = this._initContainer;
+    this._initContainer = function () {
+      initialize.call(this);
+      this._container.remove();
+    };
+    this._updateOpacity = function () {
+      if (!this._map) return;
+      const now = Date.now();
+      let fading = false, prune = false;
+      for (const tile of Object.values(this._tiles || {})) {
+        if (!tile.current || !tile.loaded) continue;
+        tile._gpuOpacity = this._map._fadeAnimated ? Math.min(1, (now - tile.loaded) / 200) : 1;
+        if (tile._gpuOpacity < 1) fading = true;
+        else if (!tile.active) {
+          this._onOpaqueTile(tile);
+          tile.active = true;
+          prune = true;
+        }
+      }
+      if (prune && !this._noPrune) this._pruneTiles();
+      this._nativeGPU?.refresh?.();
+      cancelAnimationFrame(this._fadeFrame);
+      if (fading) this._fadeFrame = requestAnimationFrame(() => this._updateOpacity());
+    };
+  } else if (this instanceof L.ImageOverlay && !(this instanceof L.VideoOverlay) && !(this instanceof L.SVGOverlay)) {
+    this.onAdd = function () {
+      if (!this._image) this._initImage();
+      if (this._image.complete && this._image.naturalWidth) queueMicrotask(() => this.fire('load'));
+    };
+    this.onRemove = () => {};
+    this.getEvents = () => ({});
+    this._reset = () => this._nativeGPU?.refresh?.();
+  }
 });

package/src/utils/CELL.js

@@ -0,0 +1,4 @@
+// Walls (non-horizontal triangles) of a mesh in world space, bucketed by 8 m cells; `origin` is the world translation
+// at build time, since layer roots only move vertically with the terrain afterwards.
+
+export const CELL = 8;

package/src/utils/addBridges.js

@@ -0,0 +1,66 @@
+import { createMesh } from './createMesh.js';
+import { triangulate } from './triangulate.js';
+
+/**
+ * Bare-earth DEMs drop bridges: `getElevation` returns the deck height inside these polygons (GeoJSON
+ * Polygon/MultiPolygon with Z, e.g. IGN BD TOPO), and one mesh draws the 1.2 m thick decks.
+ * ponytail: anything under a deck (quays, boats asking `getElevation`) also gets the deck height.
+ */
+
+export function addBridges(backend, geojson) {
+  const map = backend._map, crs = map.options.crs, zoom = backend._terrainZoom;
+  const origin = crs.project(backend.location), metres = Math.cos(backend.location.lat * Math.PI / 180);
+  const base = backend.root.position[1], position = [], normal = [], color = [];
+  const local = ([lng, lat, z]) => {
+    const p = crs.project(new L.LatLng(lat, lng));
+    return [(p.x - origin.x) * metres, z - base, -(p.y - origin.y) * metres];
+  };
+  const push = (p, n) => { position.push(...p); normal.push(...n); color.push(0.6, 0.58, 0.54); };
+  backend._bridges = new Map();
+  for (const { geometry } of geojson.features) {
+    const polygons = geometry.type === 'Polygon' ? [geometry.coordinates] : geometry.type === 'MultiPolygon' ? geometry.coordinates : [];
+    for (const polygon of polygons) {
+      const rings = polygon.map(ring => ring.slice(0, -1)).filter(ring => ring.length >= 3);
+      if (!rings.length) continue;
+      const pixels = rings.flat().map(([lng, lat, z]) => { const p = map.project([lat, lng], zoom); return [p.x, p.y, z]; });
+      const points = rings.flat().map(local);
+      let triangles;
+      try {
+        const starts = rings.map((ring, r) => rings.slice(0, r).reduce((sum, previous) => sum + previous.length, 0));
+        const [contour, ...holes] = rings.map((ring, r) => ring.map((c, i) => ({ x: pixels[starts[r] + i][0], y: pixels[starts[r] + i][1] })));
+        triangles = triangulate(contour, holes);
+      } catch { continue; }
+      const bridge = {
+        triangles: triangles.map(t => t.map(i => pixels[i])),
+        min: [Math.min(...pixels.map(p => p[0])), Math.min(...pixels.map(p => p[1]))],
+        max: [Math.max(...pixels.map(p => p[0])), Math.max(...pixels.map(p => p[1]))],
+      };
+      for (let x = Math.floor(bridge.min[0] / 64); x <= Math.floor(bridge.max[0] / 64); x++) {
+        for (let y = Math.floor(bridge.min[1] / 64); y <= Math.floor(bridge.max[1] / 64); y++) {
+          const key = `${x}/${y}`;
+          backend._bridges.set(key, [...backend._bridges.get(key) || [], bridge]);
+        }
+      }
+      const below = p => [p[0], p[1] - 1.2, p[2]];
+      for (let [a, b, c] of triangles) {
+        // Counter-clockwise seen from above, so double-sided shading keeps the top lit.
+        const [pa, pb, pc] = [points[a], points[b], points[c]];
+        if ((pb[2] - pa[2]) * (pc[0] - pa[0]) - (pb[0] - pa[0]) * (pc[2] - pa[2]) < 0) [b, c] = [c, b];
+        for (const i of [a, b, c]) push(points[i], [0, 1, 0]);
+        for (const i of [a, c, b]) push(below(points[i]), [0, -1, 0]);
+      }
+      let start = 0;
+      for (const ring of rings) {
+        for (let i = 0; i < ring.length; i++) {
+          const p = points[start + i], q = points[start + (i + 1) % ring.length];
+          const length = Math.hypot(q[0] - p[0], q[2] - p[2]) || 1, n = [(q[2] - p[2]) / length, 0, -(q[0] - p[0]) / length];
+          for (const corner of [p, q, below(q), p, below(q), below(p)]) push(corner, n);
+        }
+        start += ring.length;
+      }
+    }
+  }
+  if (position.length) {
+    backend._bridgeMesh = createMesh(backend, { position, normal, color });
+  }
+}

package/src/utils/addRasterTile.js

@@ -0,0 +1,112 @@
+import { createProgram } from './createProgram.js';
+import { destroyTexture } from './destroyTexture.js';
+import { terrainAtlas } from './terrainAtlas.js';
+import { terrainGrid } from './terrainGrid.js';
+import { setParent } from './setParent.js';
+import { update } from './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);
+  if (!attributes) {
+    attributes = terrainGrid(divisions);
+    for (const [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: L.Layer._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/utils/along.js

@@ -0,0 +1,9 @@
+/** Point and unit direction at distance `s` along `points` ([x, z, y?]) with cumulative `lengths`. */
+
+export function along(points, lengths, s) {
+  let i = 1;
+  while (i < lengths.length - 1 && lengths[i] < s) i++;
+  const a = points[i - 1], b = points[i], d = lengths[i] - lengths[i - 1] || 1;
+  const t = (s - lengths[i - 1]) / d;
+  return { x: a[0] + (b[0] - a[0]) * t, y: (a[2] ?? 0) + ((b[2] ?? 0) - (a[2] ?? 0)) * t, z: a[1] + (b[1] - a[1]) * t, dx: (b[0] - a[0]) / d, dz: (b[1] - a[1]) / d };
+}

package/src/utils/atmosphere.js

@@ -0,0 +1,20 @@
+
+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]],
+  ];
+  const upper = stops.findIndex(stop => stop[0] >= altitude);
+  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]);
+  const mix = index => a[index].map((value, i) => value + (b[index][i] - value) * t);
+  const rgb = values => `rgb(${values.map(Math.round).join(', ')})`;
+  return { background: `linear-gradient(${rgb(mix(1))}, ${rgb(mix(2))})`, tint: mix(3) };
+}