leaflet-city-mapper 0.0.1 → 0.0.2

package/src/utils/geometry.js

@@ -1,256 +1,2 @@
-/**
- * HSL inputs are linear-space to preserve the original building styling.
- * Numeric/CSS/RGB inputs are already sRGB; CSS alpha is not used for extrusion.
- * @param {number|string|Object} value 0xRRGGBB, CSS color, {r,g,b}, or {h,s,l} in 0..1.
- * @returns {Object} sRGB {r,g,b} components in 0..1.
- */
-export function parseColor(value) {
-  if (value && typeof value === 'object' && 'h' in value) {
-    const { h, s, l } = value;
-    const a = s * Math.min(l, 1 - l);
-    const channel = n => {
-      const k = (n + h * 12) % 12;
-      return l - a * Math.max(-1, Math.min(k - 3, 9 - k, 1));
-    };
-    const toSRGB = value => value <= 0.0031308 ? value * 12.92 : 1.055 * value ** (1 / 2.4) - 0.055;
-    return { r: toSRGB(channel(0)), g: toSRGB(channel(8)), b: toSRGB(channel(4)) };
-  }
-  if (value && typeof value === 'object' && 'r' in value) return value;
-  if (typeof value === 'number') return {
-    r: (value >> 16 & 255) / 255, g: (value >> 8 & 255) / 255, b: (value & 255) / 255,
-  };
-  if (typeof value !== 'string' || !CSS.supports('color', value)) throw new Error('Invalid 3D color');
-  const context = document.createElement('canvas').getContext('2d');
-  context.fillStyle = value;
-  context.fillRect(0, 0, 1, 1);
-  const [r, g, b] = context.getImageData(0, 0, 1, 1).data;
-  return { r: r / 255, g: g / 255, b: b / 255 };
-}
 
-/**
- * Paints the vertices `[start, end)` of a mesh and marks its color buffer dirty.
- * @param {Object} mesh Layer-created mesh with a color attribute.
- * @param {number} start Inclusive vertex index, not an offset into the RGB array.
- * @param {number} end Exclusive vertex index.
- * @param {Object} color sRGB {r,g,b}, typically from parseColor().
- */
-export function setVertexColor(mesh, start, end, color) {
-  for (let i = start; i < end; i++) {
-    mesh.geometry.attributes.color.data.set([color.r, color.g, color.b], i * 3);
-  }
-  mesh.geometry.attributes.color.needsUpdate = true;
-}
 
-/**
- * Triangulates a polygon given as `{x, y}` points.
- * Rings omit the repeated closing point; winding is normalized internally.
- * Vertex indices remain relative to the original inputs after duplicate/collinear
- * cleanup. Hole bridges duplicate endpoints, not source vertices.
- * @param {Object[]} contour Outer boundary.
- * @param {Object[][]} [holes] Interior boundaries.
- *
- * @returns {number[][]} Triangles as indices in `[...contour, ...holes.flat()]`.
- */
-export function triangulate(contour, holes = []) {
-  const points = [contour, ...holes].flat();
-  if (points.some(p => !Number.isFinite(p.x) || !Number.isFinite(p.y))) throw new Error('Invalid polygon coordinates');
-  // Translate near the origin to avoid cancellation with geographic coordinates.
-  const vertices = points.map((p, index) => ({ x: p.x - contour[0].x, y: p.y - contour[0].y, index }));
-  const cross = (a, b, c) => (b.x - a.x) * (c.y - a.y) - (b.y - a.y) * (c.x - a.x);
-  const equal = (a, b) => a.x === b.x && a.y === b.y;
-  // Remove zero-area corners before connecting holes; keep original vertex indices.
-  const clean = ring => {
-    let changed = true;
-    while (changed && ring.length > 3) {
-      changed = false;
-      for (let i = 0; i < ring.length; i++) {
-        const a = ring[(i + ring.length - 1) % ring.length], b = ring[i], c = ring[(i + 1) % ring.length];
-        if (equal(a, b) || Math.abs(cross(a, b, c)) < 1e-10) {
-          ring.splice(i, 1); changed = true; break;
-        }
-      }
-    }
-    if (ring.length < 3) throw new Error('Degenerate polygon ring');
-    return ring;
-  };
-  let offset = 0;
-  const rings = [contour, ...holes].map((path, index) => {
-    const ring = clean(vertices.slice(offset, offset += path.length));
-    if (isClockWise(ring) !== Boolean(index)) ring.reverse();
-    return ring;
-  });
-  const inside = (point, ring) => {
-    let result = false;
-    for (let i = 0, j = ring.length - 1; i < ring.length; j = i++) {
-      const a = ring[i], b = ring[j];
-      if ((a.y > point.y) !== (b.y > point.y) &&
-        point.x < (b.x - a.x) * (point.y - a.y) / (b.y - a.y) + a.x) result = !result;
-    }
-    return result;
-  };
-  const intersects = (a, b, c, d) => {
-    if (equal(a, c) || equal(a, d) || equal(b, c) || equal(b, d)) return false;
-    const abC = cross(a, b, c), abD = cross(a, b, d), cdA = cross(c, d, a), cdB = cross(c, d, b);
-    const on = (p, q, r) => Math.min(p.x, q.x) <= r.x && r.x <= Math.max(p.x, q.x) &&
-      Math.min(p.y, q.y) <= r.y && r.y <= Math.max(p.y, q.y);
-    return abC * abD < 0 && cdA * cdB < 0 ||
-      abC === 0 && on(a, b, c) || abD === 0 && on(a, b, d) ||
-      cdA === 0 && on(c, d, a) || cdB === 0 && on(c, d, b);
-  };
-  let polygon = rings[0].slice();
-  // A bridge must stay inside the outer boundary, outside every hole, and cross no edge.
-  // ponytail: quadratic ear clipping for building footprints; use spatial indexing for large rings.
-  for (const hole of rings.slice(1).sort((a, b) => Math.min(...a.map(p => p.x)) - Math.min(...b.map(p => p.x)))) {
-    let bridge, distance = Infinity;
-    for (let h = 0; h < hole.length; h++) for (let p = 0; p < polygon.length; p++) {
-      const a = hole[h], b = polygon[p], d = (a.x - b.x) ** 2 + (a.y - b.y) ** 2;
-      if (d >= distance) continue;
-      const mid = { x: (a.x + b.x) / 2, y: (a.y + b.y) / 2 };
-      if (!inside(mid, rings[0]) || rings.slice(1).some(r => inside(mid, r))) continue;
-      if ([polygon, ...rings.slice(1)].some(r => r.some((c, i) => intersects(a, b, c, r[(i + 1) % r.length])))) continue;
-      bridge = [h, p]; distance = d;
-    }
-    if (!bridge) throw new Error('Unable to connect polygon hole');
-    const [h, p] = bridge;
-    polygon = [...polygon.slice(0, p + 1), ...hole.slice(h), ...hole.slice(0, h + 1),
-    polygon[p], ...polygon.slice(p + 1)];
-  }
-  // Clip a convex corner only when no other vertex is inside/on its triangle.
-  const result = [];
-  while (polygon.length > 3) {
-    let clipped = false;
-    for (let i = 0; i < polygon.length; i++) {
-      const a = polygon[(i + polygon.length - 1) % polygon.length], b = polygon[i], c = polygon[(i + 1) % polygon.length];
-      if (cross(a, b, c) <= 1e-10) continue;
-      if (polygon.some(p => !equal(p, a) && !equal(p, b) && !equal(p, c) &&
-        cross(a, b, p) >= 0 && cross(b, c, p) >= 0 && cross(c, a, p) >= 0)) continue;
-      result.push([a.index, b.index, c.index]); polygon.splice(i, 1); clipped = true; break;
-    }
-    if (!clipped) throw new Error('Unable to triangulate polygon: invalid or self-intersecting rings');
-  }
-  if (cross(...polygon) > 1e-10) result.push(polygon.map(p => p.index));
-  const area = ring => Math.abs(ring.reduce((sum, p, i) => {
-    const q = ring[(i + 1) % ring.length]; return sum + p.x * q.y - q.x * p.y;
-  }, 0)) / 2;
-  // Reject incomplete coverage instead of silently emitting a partial roof.
-  const expected = area(rings[0]) - rings.slice(1).reduce((sum, ring) => sum + area(ring), 0);
-  const actual = result.reduce((sum, triangle) => sum + cross(...triangle.map(i => vertices[i])) / 2, 0);
-  if (expected <= 0 || Math.abs(actual - expected) > Math.max(1e-7, expected * 1e-8)) throw new Error('Polygon triangulation area mismatch');
-  return result;
-}
-
-/**
- * @returns {boolean} Whether the `{x, y}` points are in clockwise order.
- */
-export function isClockWise(points) {
-  let area = 0;
-  for (let i = 0; i < points.length; i++) {
-    const a = points[i], b = points[(i + 1) % points.length];
-    area += a.x * b.y - b.x * a.y;
-  }
-  return area < 0;
-}
-
-/** Low-poly tree, sharing the source block's buffers, picking and terrain offset. */
-export function treeGeometry(point, style, addTriangle) {
-  const { top, bottom = 0, trunkRadius, crownRadius, crownBottom, crownShape = 'round' } = style;
-  if (![trunkRadius, crownRadius, crownBottom].every(Number.isFinite) ||
-    trunkRadius <= 0 || crownRadius < trunkRadius || crownBottom <= bottom || crownBottom >= top ||
-    !['round', 'cone'].includes(crownShape)) {
-      throw new Error('Invalid tree dimensions or crown shape');
-    }
-  const trunk = parseColor(style.trunkColor ?? 0x72513a);
-  const crown = parseColor(style.color ?? 0x4f823b);
-  const ring = radius => Array.from({ length: 8 }, (_, i) => ({
-    x: point.x + Math.cos(i * Math.PI / 4) * radius,
-    y: point.y + Math.sin(i * Math.PI / 4) * radius,
-    ground: point.ground,
-  }));
-  const surface = (lowRadius, low, highRadius, high, color) => {
-    const lower = ring(lowRadius), upper = ring(highRadius);
-    for (let i = 0; i < 8; i++) {
-      const next = (i + 1) % 8;
-      const angle = (i + 0.5) * Math.PI / 4;
-      const slope = (lowRadius - highRadius) / (high - low);
-      const length = Math.hypot(1, slope);
-      const nx = Math.cos(angle) / length, ny = slope / length, nz = -Math.sin(angle) / length;
-      if (lowRadius) addTriangle(lower[i], low, lower[next], low, upper[next], high, nx, ny, nz, color);
-      if (highRadius) addTriangle(lower[i], low, upper[next], high, upper[i], high, nx, ny, nz, color);
-    }
-  };
-  surface(trunkRadius, bottom, trunkRadius, crownBottom + (top - crownBottom) * 0.25, trunk);
-  if (crownShape === 'cone') {
-    const base = ring(crownRadius);
-    for (let i = 0; i < 8; i++) addTriangle(point, crownBottom, base[i], crownBottom,
-      base[(i + 1) % 8], crownBottom, 0, -1, 0, crown);
-    surface(crownRadius, crownBottom, 0, top, crown);
-  } else {
-    const profile = [[0, 0], [0.35, 0.8], [0.6, 1], [0.85, 0.7], [1, 0]];
-    for (let i = 1; i < profile.length; i++) {
-      const [low, lr] = profile[i - 1], [high, hr] = profile[i];
-      surface(lr * crownRadius, crownBottom + low * (top - crownBottom),
-        hr * crownRadius, crownBottom + high * (top - crownBottom), crown);
-    }
-  }
-}
-
-/** Three crossed emitter discs; illumination itself is evaluated on receiving surfaces. */
-export function lightGeometry(point, style, addTriangle) {
-  if (!Number.isFinite(style.lightRadius) || style.lightRadius <= 0) throw new Error('Invalid light radius');
-  const color = parseColor(style.color);
-  const quad = (a, b, c, d, height, normal) => {
-    addTriangle(a, height, b, height, c, height, ...normal, color);
-    addTriangle(a, height, c, height, d, height, ...normal, color);
-  };
-  const r = 0.65;
-  const emitter = (u, v, axis) => ({
-    x: point.x + (axis === 2 ? 0 : u * r),
-    y: point.y + (axis === 1 ? 0 : axis === 2 ? u * r : v * r),
-    ground: point.ground + (axis === 0 ? 0 : v * r), uv: [u, v],
-  });
-  for (let axis = 0; axis < 3; axis++) {
-    quad(emitter(-1, -1, axis), emitter(1, -1, axis), emitter(1, 1, axis), emitter(-1, 1, axis),
-      style.top, axis === 0 ? [0, 1, 0] : axis === 1 ? [0, 0, 1] : [1, 0, 0]);
-  }
-}
-
-/** Schematic support and lamp head; wall-mounted fixtures do not get an invented pole. */
-export function lampPostGeometry(point, style, addTriangle) {
-  const color = parseColor(0x50565a), radius = style.poleRadius;
-  if (!Number.isFinite(radius) || radius <= 0) throw new Error('Invalid lamp pole radius');
-  const ring = r => Array.from({ length: 6 }, (_, i) => ({
-    x: point.x + Math.cos(i * Math.PI / 3) * r,
-    y: point.y + Math.sin(i * Math.PI / 3) * r, ground: point.ground, uv: [3, 3],
-  }));
-  const center = { ...point, uv: [3, 3] };
-  for (const [r, low, high] of [[radius, 0, style.top], [radius * 2.5, style.top - 0.25, style.top + 0.15]]) {
-    const points = ring(r);
-    for (let i = 0; i < 6; i++) {
-      const a = points[i], b = points[(i + 1) % 6], angle = (i + 0.5) * Math.PI / 3;
-      const nx = Math.cos(angle), nz = -Math.sin(angle);
-      addTriangle(a, low, b, low, b, high, nx, 0, nz, color);
-      addTriangle(a, low, b, high, a, high, nx, 0, nz, color);
-      addTriangle(center, high, a, high, b, high, 0, 1, 0, color);
-      addTriangle(center, low, b, low, a, low, 0, -1, 0, color);
-    }
-  }
-}
-
-/** Cache local AABB and center for ray picking and transparent mesh sorting. */
-export function computeBounds(geometry) {
-  const min = [Infinity, Infinity, Infinity],
-        max = [-Infinity, -Infinity, -Infinity],
-        data = geometry.attributes.position.data;
-  for (let i = 0; i < data.length; i++) {
-    min[i % 3] = Math.min(min[i % 3], data[i]);
-    max[i % 3] = Math.max(max[i % 3], data[i]);
-  }
-  const center = min.map((v, i) => (v + max[i]) / 2);
-  let radius = 0;
-  for (let i = 0; i < data.length; i += 3) {
-    radius = Math.max(radius, Math.hypot(
-      data[i] - center[0], data[i + 1] - center[1], data[i + 2] - center[2]
-    ));
-  }
-  geometry.bounds = { min, max, center, radius };
-}

package/src/utils/getElevation.js

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

package/src/utils/getHeader.js

@@ -0,0 +1,9 @@
+import { decodeHeader } from './decodeHeader.js';
+import { read } from './read.js';
+
+/** Cache header initialization; failures remain visible to all callers. */
+
+export function getHeader(backend) {
+  if (backend.options.archive && backend.options.archive !== backend) return backend.options.archive.getHeader();
+  return backend._header ||= read(backend, 0, 127).then(decodeHeader);
+}

package/src/utils/getZxy.js

@@ -0,0 +1,76 @@
+import { decodeDirectory } from './decodeDirectory.js';
+import { decompress } from './decompress.js';
+import { tileId } from './tileId.js';
+import { read } from './read.js';
+import { getHeader } from './getHeader.js';
+
+/** Nearest directory entry at/before the Hilbert ID, then follow leaf pointers. */
+
+export async function getZxy(backend, z, x, y, signal) {
+  if (backend.options.archive && backend.options.archive !== backend && backend.options.archive.getZxy) {
+    return backend.options.archive.getZxy(z, x, y, signal);
+  }
+  const id = tileId(z, x, y);
+  signal?.throwIfAborted();
+  const header = await getHeader(backend);
+  signal?.throwIfAborted();
+  if (z < header.minZoom || z > header.maxZoom) {
+    return;
+  }
+  let offset = header.rootDirectoryOffset, length = header.rootDirectoryLength;
+  const visited = new Set();
+  for (let depth = 0; depth < 4; depth++) {
+    if (visited.has(offset)) {
+      throw new Error('Cyclic PMTiles directory');
+    }
+    visited.add(offset);
+    const key = `${offset}:${length}`;
+    if (!backend._directories.has(key)) {
+      if (backend._directories.size >= 32) {
+        backend._directories.delete(backend._directories.keys().next().value);
+      }
+      const pending = read(backend, offset, length)
+        .then(data => decompress(data, header.internalCompression))
+        .then(decodeDirectory)
+        .catch(error => {
+          if (backend._directories.get(key) === pending) {
+            backend._directories.delete(key);
+          }
+          throw error;
+        });
+      backend._directories.set(key, pending);
+    }
+    const entries = await backend._directories.get(key);
+    signal?.throwIfAborted();
+    let low = 0, high = entries.length - 1;
+    while (low <= high) {
+      const mid = (low + high) >> 1;
+      if (entries[mid].tileId <= id) {
+        low = mid + 1;
+      } else {
+        high = mid - 1;
+      }
+    }
+    const entry = entries[high];
+    if (!entry) {
+      return;
+    }
+    if (entry.runLength) {
+      if (id - entry.tileId >= entry.runLength) {
+        return;
+      }
+      if (entry.offset + entry.length > header.tileDataLength) {
+        throw new Error('PMTiles tile outside data section');
+      }
+      const data = await decompress(await read(backend, header.tileDataOffset + entry.offset, entry.length, signal), header.tileCompression);
+      signal?.throwIfAborted();
+      return { data };
+    }
+    if (entry.offset + entry.length > header.leafDirectoryLength) {
+      throw new Error('PMTiles directory outside leaf section');
+    }
+    offset = header.leafDirectoryOffset + entry.offset;
+    length = entry.length;
+  }
+  throw new Error('PMTiles directory depth exceeds four levels');
+}

package/src/utils/glass.js

@@ -0,0 +1 @@
+export const glass = [0.12, 0.15, 0.18], tyre = [0.05, 0.05, 0.05];

package/src/utils/headlight.js

@@ -0,0 +1 @@
+export const headlight = [1.9, 1.85, 1.7];

package/src/utils/hit.js

@@ -0,0 +1,41 @@
+import { CELL } from './CELL.js';
+import { collider } from './collider.js';
+import { computeBounds } from './computeBounds.js';
+import { horizontalRay } from './horizontalRay.js';
+import { traverse } from './traverse.js';
+import { updateWorldMatrix } from './updateWorldMatrix.js';
+
+// Horizontal normal of the nearest wall faced within `reach` metres of the feet at world (x, y, z), walking along
+// the unit (dx, dz); knee and chest rays, so arches and tree crowns above the head let the walker through.
+// ponytail: traffic vehicles and boats move on the GPU and are not obstacles.
+
+export function hit(layer, x, y, z, dx, dz, reach) {
+  const skip = other => other === layer || ['terrain', 'traffic'].includes(other._type);
+  updateWorldMatrix(layer.scene);
+  let best = reach, found = null;
+  for (const other of layer._shared._layers) {
+    if (skip(other)) continue;
+    traverse(other.root, mesh => {
+      if (!mesh.visible) return true;
+      if (!mesh.geometry?.attributes?.position?.data || mesh.program?.depthTest === false) return;
+      if (!mesh.geometry.bounds) computeBounds(mesh.geometry);
+      const m = mesh.worldMatrix, { center: k, radius } = mesh.geometry.bounds;
+      if (Math.hypot(m[0] * k[0] + m[4] * k[1] + m[8] * k[2] + m[12] - x, m[2] * k[0] + m[6] * k[1] + m[10] * k[2] + m[14] - z) >
+        radius * Math.hypot(m[0], m[1], m[2]) + reach) return;
+      const c = collider(mesh), ox = x - m[12] + c.origin[0], oy = y - m[13] + c.origin[1], oz = z - m[14] + c.origin[2];
+      const seen = new Set();
+      for (let ix = Math.floor(Math.min(ox, ox + dx * reach) / CELL); ix <= Math.floor(Math.max(ox, ox + dx * reach) / CELL); ix++)
+        for (let iz = Math.floor(Math.min(oz, oz + dz * reach) / CELL); iz <= Math.floor(Math.max(oz, oz + dz * reach) / CELL); iz++)
+          for (const t of c.cells.get(ix + ',' + iz) || []) {
+            // Walls are one-way: walking out of a building (e.g. starting inside one) is allowed.
+            if (seen.has(t) || dx * c.nrm[t * 2] + dz * c.nrm[t * 2 + 1] >= 0) continue;
+            seen.add(t);
+            for (const height of [0.4, 1.5]) {
+              const d = horizontalRay(c.tri, t, ox, oy + height, oz, dx, dz);
+              if (d >= 0 && d < best) { best = d; found = [c.nrm[t * 2], c.nrm[t * 2 + 1]]; }
+            }
+          }
+    });
+  }
+  return found;
+}

package/src/utils/horizontalPosition.js

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

package/src/utils/horizontalRay.js

@@ -0,0 +1,12 @@
+// Möller-Trumbore for the horizontal ray (ox, oy, oz) + d·(dx, 0, dz) against triangle t; returns d or -1.
+export function horizontalRay(v, t, ox, oy, oz, dx, dz) {
+  const i = t * 9, ex = v[i + 3] - v[i], ey = v[i + 4] - v[i + 1], ez = v[i + 5] - v[i + 2];
+  const fx = v[i + 6] - v[i], fy = v[i + 7] - v[i + 1], fz = v[i + 8] - v[i + 2];
+  const px = -dz * fy, py = dz * fx - dx * fz, pz = dx * fy, det = ex * px + ey * py + ez * pz;
+  if (Math.abs(det) < 1e-9) return -1;
+  const tx = ox - v[i], ty = oy - v[i + 1], tz = oz - v[i + 2], u = (tx * px + ty * py + tz * pz) / det;
+  if (u < 0 || u > 1) return -1;
+  const qx = ty * ez - tz * ey, qy = tz * ex - tx * ez, qz = tx * ey - ty * ex, w = (dx * qx + dz * qz) / det;
+  if (w < 0 || u + w > 1) return -1;
+  return (fx * qx + fy * qy + fz * qz) / det;
+}

package/src/utils/hull.js

@@ -0,0 +1 @@
+export const hull = [[-5.5, 30], [5.5, 30], [5.5, -20], [4, -26], [1.5, -30], [-1.5, -30], [-4, -26], [-5.5, -20]];

package/src/utils/initSunlight.js

@@ -0,0 +1,9 @@
+import { onAddSun } from './onAddSun.js';
+import { onRemoveSun } from './onRemoveSun.js';
+
+// Sun/moon clock control and sky colours; the control is created on first add (`layer.control`).
+export function initSunlight(layer, options) {
+  L.Util.setOptions(layer, options);
+  layer.onAdd = map => onAddSun(layer, map);
+  layer.onRemove = () => onRemoveSun(layer);
+}

package/src/utils/initTerrain.js

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

package/src/utils/initTraffic.js

@@ -0,0 +1,93 @@
+/**
+ * Vehicles moving along GeoJSON lanes; a compute pass places them on the GPU every frame.
+ * Source options:
+ * - `url`: GeoJSON (Multi)LineStrings, or a JS module whose default export `(time, layer, signal)` returns them (time-dependent data);
+ * - `vehicle`: 'car' (default) or 'boat'; `side`: offset right of the lane centreline in metres (vehicle default);
+ * - `speed`: m/s of `flow` lanes; `outline`: draw the lanes.
+ * Lane properties: `flow` (vehicles/h) or `timetable` (see scheduledTrips.js), optional fixed `elevation`
+ * in metres, `name`/`description` for the default tooltip. The status line (vehicle count, then the FeatureCollection `note`) sits under the layer's entry in the layers control.
+ * The 'sunlight' layer on the same map drives the time; without one, vehicles run live.
+ */
+import { build } from './build.js';
+import { tooltip } from './tooltip.js';
+import { speed } from './speed.js';
+import { vehicles } from './vehicles.js';
+import {
+  addTraffic,
+  placeTraffic,
+  removeTraffic,
+  readyTraffic,
+  tickTraffic,
+  updateTraffic,
+  updateTrafficTerrain,
+} from './traffic.js';
+
+export function initTraffic(layer, { url, vehicle = 'car', side, outline, speed: velocity = speed, ...options } = {}) {
+  const { model, lights, side: defaultSide } = vehicles[vehicle];
+  side ??= defaultSide;
+  layer._init3D({
+    tooltip,
+    nightLight: Boolean(lights),
+    ...options,
+  });
+  const status = L.DomUtil.create('small', 'traffic-status');
+  status.style.cssText = 'display:block;max-width:200px;margin:0 0 4px 20px;color:#555;';
+  const template = build(model(0)), stride = template.position.length, vertices = stride / 3;
+  const params = new ArrayBuffer(16), paramFloats = new Float32Array(params), paramInts = new Uint32Array(params);
+  const state = {
+    layer, url, model, lights, side, outline, velocity, status, template, stride, vertices,
+    params, paramFloats, paramInts,
+    ready: false, frame: undefined, request: undefined, lanes: [], tripsKey: undefined,
+    mesh: undefined, route: undefined, litAt: -Infinity,
+    trips: [], rebasedAt: 0, nextCheck: -Infinity, elapsed: 0, gpu: null,
+    lanesDirty: true, stale: false, loaded: undefined, file: undefined,
+  };
+  // Lane points are [x, z, ground, cumulative length]. Mirrors along() and place().
+  const shader = `
+    struct Params { seconds: f32, side: f32, vertices: u32, total: u32 }
+    struct Vehicle { start: u32, count: u32, base: f32, speed: f32 }
+    @group(0) @binding(0) var<uniform> params: Params;
+    @group(0) @binding(1) var<storage, read> model: array<f32>;
+    @group(0) @binding(2) var<storage, read> points: array<vec4f>;
+    @group(0) @binding(3) var<storage, read> vehicles: array<Vehicle>;
+    @group(0) @binding(4) var<storage, read_write> position: array<f32>;
+    @group(0) @binding(5) var<storage, read_write> normal: array<f32>;
+    @compute @workgroup_size(64)
+    fn main(@builtin(global_invocation_id) id: vec3u) {
+      let v = id.x;
+      if (v >= params.total) { return; }
+      let vehicle = vehicles[v / params.vertices];
+      let last = vehicle.start + vehicle.count - 1u;
+      let length = points[last].w;
+      var s = vehicle.base + params.seconds * vehicle.speed;
+      s -= length * floor(s / length);
+      var i = vehicle.start + 1u;
+      while (i < last && points[i].w < s) { i++; }
+      let a = points[i - 1u];
+      let b = points[i];
+      let d = select(b.w - a.w, 1.0, b.w == a.w);
+      let t = (s - a.w) / d;
+      let dx = (b.x - a.x) / d;
+      let dz = (b.y - a.y) / d;
+      let cx = a.x + (b.x - a.x) * t - dz * params.side;
+      let cz = a.y + (b.y - a.y) * t + dx * params.side;
+      let y = a.z + (b.z - a.z) * t;
+      let k = (v % params.vertices) * 3u;
+      let n = params.vertices * 3u + k;
+      let o = v * 3u;
+      position[o] = cx - model[k] * dz - model[k + 2u] * dx;
+      position[o + 1u] = y + model[k + 1u];
+      position[o + 2u] = cz + model[k] * dx - model[k + 2u] * dz;
+      normal[o] = -model[n] * dz - model[n + 2u] * dx;
+      normal[o + 1u] = model[n + 1u];
+      normal[o + 2u] = model[n] * dx - model[n + 2u] * dz;
+    }`;
+  state.shader = shader;
+  state.tick = tickTraffic.bind(null, state);
+  state.update = updateTraffic.bind(null, state);
+  state.terrain = updateTrafficTerrain.bind(null, state);
+  layer._beforeRaycast = placeTraffic.bind(null, state);
+  layer.on('ready', readyTraffic.bind(null, state));
+  layer.on('add', addTraffic.bind(null, state));
+  layer.on('remove', removeTraffic.bind(null, state));
+}

package/src/utils/initWalk.js

@@ -0,0 +1,72 @@
+import {
+  controlOnAdd, onBlur, onKey, onLayerAdd, onLayerRemove, onPointer, onReady, onTerrain, start, step, stop, toggle
+} from './walk.js';
+
+/**
+ * Third-person walk mode, toggled by a map button (and Esc): a pedestrian at the map centre runs with W/S (or ↑/↓) and
+ * turns with A/D (or ←/→); the camera swings back behind it while it moves. Dragging the map only turns the camera
+ * (bearing, pitch); the wheel changes the camera distance.
+ * The walker follows the terrain, bridges included, and `layer.walker` exposes `{ latlng, heading, phase }`.
+ * Source options: `speed` (m/s, default 6), `distance` (camera distance in metres, default 20), `position` (button corner, default 'topleft').
+ * Visible meshes of the other 3D layers (buildings, trees, models, streetlights) are solid; terrain and traffic are not.
+ */
+export function initWalk(layer, {
+  speed = 70,
+  distance = 20,
+  position = 'bottomright',
+  ...options
+} = {}) {
+  layer._init3D(options);
+  const keys = new Set();
+  const control = new L.Control({ position });
+  const container = L.DomUtil.create('div', 'leaflet-bar leaflet-control');
+  container.style.cssText = 'display:flex;align-items:center;background:#fff;';
+  const button = L.DomUtil.create('button', '', container);
+  button.type = 'button';
+  button.title = 'Walk';
+  button.setAttribute('aria-label', 'Walk');
+  button.setAttribute('aria-pressed', 'false');
+  button.textContent = '🚶';
+  button.style.cssText = 'width:30px;height:30px;padding:0;border:0;border-radius:4px;background:#fff;font-size:18px;line-height:30px;cursor:pointer;';
+  const hint = L.DomUtil.create('small', '', container);
+  hint.style.cssText = 'display:none;padding:0 8px;color:#333;white-space:nowrap;';
+  hint.textContent = 'W/S: run · A/D: turn · drag: look around · Esc: exit';
+  L.DomEvent.disableClickPropagation(container);
+
+  const context = {
+    layer,
+    speed,
+    distance,
+    keys,
+    control,
+    container,
+    button,
+    hint,
+    meshes: null,
+    frame: null,
+    last: undefined,
+    swing: 0,
+    saved: null,
+    drag: null,
+    ready: false,
+    state: layer.walker = { latlng: null, heading: 0, phase: 0 }
+  }
+  context.step = step.bind(context);
+  context.onKey = onKey.bind(context);
+  context.onBlur = onBlur.bind(context);
+  context.onPointer = onPointer.bind(context);
+  context.onTerrain = onTerrain.bind(context);
+  context.start = start.bind(context);
+  context.stop = stop.bind(context);
+  context.toggle = toggle.bind(context);
+  context.controlOnAdd = controlOnAdd.bind(context);
+  context.onReady = onReady.bind(context);
+  context.onLayerAdd = onLayerAdd.bind(context);
+  context.onLayerRemove = onLayerRemove.bind(context);
+
+  control.onAdd = context.controlOnAdd;
+  L.DomEvent.on(button, 'click', context.toggle);
+  layer.on('ready', context.onReady);
+  layer.on('add', context.onLayerAdd);
+  layer.on('remove', context.onLayerRemove);
+};