leaflet-city-mapper 0.0.9 → 0.1.1

package/src/textures/resizeRoofTexture.js

@@ -1,25 +1,32 @@
 import { rendererByLayer } from '../weakmaps/rendererByLayer.js';
+import { roofTexture } from '../globals/roofTexture.js';
+import { roofSampler } from '../globals/roofSampler.js';
+import { destroyTexture } from './destroyTexture.js';
 
-import { roofTexture } from '../globals/roofTexture.js';
-import { roofSampler } from '../globals/roofSampler.js';
-import { destroyTexture } from './destroyTexture.js';
-
-export function resizeRoofTexture(layer, roof, width, height) {
-  const renderer = rendererByLayer.get(layer);
-  const descriptor = roofTexture;
-  descriptor.size[0] = width; descriptor.size[1] = height;
-  descriptor.usage = GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.COPY_DST | GPUTextureUsage.RENDER_ATTACHMENT;
-  if (roof.texture && (roof.texture.width !== width || roof.texture.height !== height)) {
-    destroyTexture(layer, roof.texture.texture);
-    roof.texture.texture = renderer.device.createTexture(descriptor);
-    roof.texture.width = width; roof.texture.height = height;
-  }
-  roof.texture ||= /* alloc */ {
-    device: renderer.device,
-    texture: renderer.device.createTexture(descriptor),
-    sampler: renderer.device.createSampler(roofSampler),
-    samplerOptions: /* alloc */ { addressModeU: 'clamp-to-edge', addressModeV: 'clamp-to-edge' },
-    image: null, width, height,
-    format: 'rgba8unorm', srgb: false, flipY: false, uploaded: null,
-  };
-}
+/**
+ * Create or resize the GPU texture used for the roof atlas.
+ *
+ * @param {L.Layer} layer Rendering layer.
+ * @param {Object} roof Roof atlas state.
+ * @param {number} width Texture width in pixels.
+ * @param {number} height Texture height in pixels.
+ */
+export function resizeRoofTexture(layer, roof, width, height) {
+  const renderer = rendererByLayer.get(layer);
+  const descriptor = roofTexture;
+  descriptor.size[0] = width; descriptor.size[1] = height;
+  descriptor.usage = GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.COPY_DST | GPUTextureUsage.RENDER_ATTACHMENT;
+  if (roof.texture && (roof.texture.width !== width || roof.texture.height !== height)) {
+    destroyTexture(layer, roof.texture.texture);
+    roof.texture.texture = renderer.device.createTexture(descriptor);
+    roof.texture.width = width; roof.texture.height = height;
+  }
+  roof.texture ||= /* alloc */ {
+    device: renderer.device,
+    texture: renderer.device.createTexture(descriptor),
+    sampler: renderer.device.createSampler(roofSampler),
+    samplerOptions: /* alloc */ { addressModeU: 'clamp-to-edge', addressModeV: 'clamp-to-edge' },
+    image: null, width, height,
+    format: 'rgba8unorm', srgb: false, flipY: false, uploaded: null,
+  };
+}

package/src/textures/restoreMaterialTextures.js

@@ -1,16 +1,22 @@
-export function restoreMaterialTextures(material, device) {
-  let name, texture;
-  for (name in material) {
-    if (name !== 'baseTexture' && name !== 'metalTexture' && name !== 'emissiveTexture' && name !== 'occlusionTexture') continue;
-    texture = material[name];
-    if (!texture || texture.device === device) continue;
-    texture.device = device;
-    texture.texture = device.createTexture(/* alloc */ {
-      size: /* alloc */ [texture.image.width, texture.image.height],
-      format: texture.format,
-      usage: GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.COPY_DST | GPUTextureUsage.RENDER_ATTACHMENT,
-    });
-    texture.sampler = device.createSampler(texture.samplerOptions);
-    texture.uploaded = null;
-  }
-}
+/**
+ * Recreate material textures and samplers that belong to a different GPU device.
+ *
+ * @param {Object} material Material containing model texture states.
+ * @param {GPUDevice} device Device to own restored resources.
+ */
+export function restoreMaterialTextures(material, device) {
+  let name, texture;
+  for (name in material) {
+    if (name !== 'baseTexture' && name !== 'metalTexture' && name !== 'emissiveTexture' && name !== 'occlusionTexture') continue;
+    texture = material[name];
+    if (!texture || texture.device === device) continue;
+    texture.device = device;
+    texture.texture = device.createTexture(/* alloc */ {
+      size: /* alloc */ [texture.image.width, texture.image.height],
+      format: texture.format,
+      usage: GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.COPY_DST | GPUTextureUsage.RENDER_ATTACHMENT,
+    });
+    texture.sampler = device.createSampler(texture.samplerOptions);
+    texture.uploaded = null;
+  }
+}

package/src/textures/textureBinding.js

@@ -1,3 +1,12 @@
+/**
+ * Reserve texture and sampler bindings and produce their WGSL declarations when enabled.
+ *
+ * @param {Array<Object>} bindings Program binding descriptions to extend.
+ * @param {string} name Shader texture uniform name.
+ * @param {boolean} enabled Whether the texture is used.
+ *
+ * @returns {string} WGSL declarations, or an empty string when disabled.
+ */
 export function textureBinding(bindings, name, enabled) {
   if (!enabled) return '';
   const current = 3 + bindings.length * 2;

package/src/textures/updateRoofAtlas.js

@@ -1,23 +1,29 @@
 import { loadingTilesByLayer } from '../weakmaps/loadingTilesByLayer.js';
 import { rasterVersionByLayer } from '../weakmaps/rasterVersionByLayer.js';
 import { roofRasterByLayer } from '../weakmaps/roofRasterByLayer.js';
+import { L } from '../globals/L.js';
+import { roofSignatures } from '../globals/roofSignatures.js';
+import { rebuildRoofAtlas } from './rebuildRoofAtlas.js';
 
-import { L } from '../globals/L.js';
-import { roofSignatures } from '../globals/roofSignatures.js';
-import { rebuildRoofAtlas } from './rebuildRoofAtlas.js';
-
-export function updateRoofAtlas(layer, rasters, now) {
-  const signatures = roofSignatures;
-  signatures.length = 0;
-  let loading = false, rasterLayer;
-  for (rasterLayer of rasters) {
-    signatures.push(`${L.Util.stamp(rasterLayer)}:${rasterVersionByLayer.get(rasterLayer) || 0}:${rasterLayer.options.opacity}:${rasterLayer.options.zIndex}`);
-    loading ||= Boolean(loadingTilesByLayer.get(rasterLayer));
-  }
-  const signature = signatures.join('|');
-  signatures.length = 0;
-  if (!roofRasterByLayer.get(layer) || roofRasterByLayer.get(layer).signature !== signature &&
-    (!loading || now - roofRasterByLayer.get(layer).updatedAt >= 50)) {
-    rebuildRoofAtlas(layer, rasters, signature, now);
-  }
-}
+/**
+ * Rebuild a changed roof atlas, throttling updates while raster tiles are loading.
+ *
+ * @param {L.Layer} layer Rendering layer owning the atlas.
+ * @param {Array<L.Layer>} rasters Raster layers included in the atlas.
+ * @param {number} now Current frame time in milliseconds.
+ */
+export function updateRoofAtlas(layer, rasters, now) {
+  const signatures = roofSignatures;
+  signatures.length = 0;
+  let loading = false, rasterLayer;
+  for (rasterLayer of rasters) {
+    signatures.push(`${L.Util.stamp(rasterLayer)}:${rasterVersionByLayer.get(rasterLayer) || 0}:${rasterLayer.options.opacity}:${rasterLayer.options.zIndex}`);
+    loading ||= Boolean(loadingTilesByLayer.get(rasterLayer));
+  }
+  const signature = signatures.join('|');
+  signatures.length = 0;
+  if (!roofRasterByLayer.get(layer) || roofRasterByLayer.get(layer).signature !== signature &&
+    (!loading || now - roofRasterByLayer.get(layer).updatedAt >= 50)) {
+    rebuildRoofAtlas(layer, rasters, signature, now);
+  }
+}

package/src/textures/updateRoofRaster.js

@@ -6,6 +6,14 @@ import { roofRastersByLayer } from '../weakmaps/roofRastersByLayer.js';
 import { updateRoofAtlas } from './updateRoofAtlas.js';
 import { destroyTexture } from './destroyTexture.js';
 
+/**
+ * Update or remove the roof atlas according to scene texture settings and active rasters.
+ *
+ * @param {L.Layer} layer Rendering layer.
+ * @param {number} now Current frame time in milliseconds.
+ *
+ * @returns {Array<L.Layer>} Raster layers contributing to the roof atlas.
+ */
 export function updateRoofRaster(layer, now) {
   const map = layer._map;
   let rasters = roofRastersByLayer.get(layer);

package/src/textures/uploadCanvasTexture.js

@@ -1,6 +1,21 @@
 import { current } from '../native/isCurrentNativeLayer.js';
 import { refreshNativeLayer } from '../native/refreshNativeLayer.js';
 
+/**
+ * Rasterize a native canvas or image into a GPU texture and refresh its layer when ready.
+ *
+ * @param {Object} state Native layer state.
+ * @param {string} key Texture cache key.
+ * @param {Object} texture Destination texture state.
+ * @param {HTMLCanvasElement|HTMLImageElement} image Source image.
+ * @param {GPUDevice} device Device owning the destination.
+ * @param {number} width Image width in pixels.
+ * @param {number} height Image height in pixels.
+ *
+ * @returns {Promise<void>} Completion of the upload attempt.
+ *
+ * @throws {Error} Internally if SVG rasterization lacks a 2D context; reported to the source layer.
+ */
 export async function uploadCanvasTexture(state, key, texture, image, device, width, height) {
   let bitmap, source = image;
   try {

package/src/textures/uploadMeshTexture.js

@@ -1,26 +1,32 @@
-import { meshImage } from '../globals/meshImage.js';
-import { meshTarget } from '../globals/meshTarget.js';
-import { meshCopySize } from '../globals/meshCopySize.js';
-
-export function uploadMeshTexture(device, texture) {
-  if (texture.uploaded === texture.image) return;
-  device.queue.copyExternalImageToTexture(
-    (
-      meshImage.source = texture.image,
-      meshImage.flipY = Boolean(texture.flipY),
-      meshImage
-    ),
-    (
-      meshTarget.texture = texture.texture,
-      meshTarget
-    ),
-    (
-      meshCopySize[0] = texture.image.width,
-      meshCopySize[1] = texture.image.height,
-      meshCopySize
-    )
-  );
-  meshImage.source = null;
-  meshTarget.texture = null;
-  texture.uploaded = texture.image;
-}
+import { meshImage } from '../globals/meshImage.js';
+import { meshTarget } from '../globals/meshTarget.js';
+import { meshCopySize } from '../globals/meshCopySize.js';
+
+/**
+ * Upload a mesh texture's image if it has changed since the previous upload.
+ *
+ * @param {GPUDevice} device Device owning the texture.
+ * @param {Object} texture Texture state containing its image and flip setting.
+ */
+export function uploadMeshTexture(device, texture) {
+  if (texture.uploaded === texture.image) return;
+  device.queue.copyExternalImageToTexture(
+    (
+      meshImage.source = texture.image,
+      meshImage.flipY = Boolean(texture.flipY),
+      meshImage
+    ),
+    (
+      meshTarget.texture = texture.texture,
+      meshTarget
+    ),
+    (
+      meshCopySize[0] = texture.image.width,
+      meshCopySize[1] = texture.image.height,
+      meshCopySize
+    )
+  );
+  meshImage.source = null;
+  meshTarget.texture = null;
+  texture.uploaded = texture.image;
+}

package/src/textures/uploadNativeImage.js

@@ -1,13 +1,26 @@
-export function uploadNativeImage(state, key, texture, image, device, width, height) {
-  try {
-    device.queue.copyExternalImageToTexture(
-      /* alloc */ { source: image },
-      /* alloc */ { texture: texture.texture },
-      /* alloc */ [width, height]);
-  } catch (error) {
-    texture.texture.destroy();
-    state.textures.delete(key);
-    throw error;
-  }
-  texture.uploaded = image;
-}
+/**
+ * Upload a native image, removing its cached GPU texture if the copy fails.
+ *
+ * @param {Object} state Native layer state containing the texture cache.
+ * @param {string} key Texture cache key.
+ * @param {Object} texture Destination texture state.
+ * @param {HTMLImageElement} image Source image.
+ * @param {GPUDevice} device Device owning the destination.
+ * @param {number} width Image width in pixels.
+ * @param {number} height Image height in pixels.
+ *
+ * @throws {Error} If the GPU image copy fails.
+ */
+export function uploadNativeImage(state, key, texture, image, device, width, height) {
+  try {
+    device.queue.copyExternalImageToTexture(
+      /* alloc */ { source: image },
+      /* alloc */ { texture: texture.texture },
+      /* alloc */ [width, height]);
+  } catch (error) {
+    texture.texture.destroy();
+    state.textures.delete(key);
+    throw error;
+  }
+  texture.uploaded = image;
+}

package/src/textures/uploadRoofTile.js

@@ -1,23 +1,29 @@
-import { roofImage } from '../globals/roofImage.js';
-import { roofTarget } from '../globals/roofTarget.js';
-import { roofCopySize } from '../globals/roofCopySize.js';
-
-export function uploadRoofTile(device, tile) {
-  const source = tile.texture;
-  if (source.uploaded !== source.image) {
-    device.queue.copyExternalImageToTexture((
-      roofImage.source = tile.image,
-      roofImage
-    ), (
-      roofTarget.texture = source.texture,
-      roofTarget
-    ), (
-      roofCopySize[0] = source.texture.width,
-      roofCopySize[1] = source.texture.height,
-      roofCopySize
-    ));
-    roofImage.source = null;
-    roofTarget.texture = null;
-    source.uploaded = source.image;
-  }
-}
+import { roofImage } from '../globals/roofImage.js';
+import { roofTarget } from '../globals/roofTarget.js';
+import { roofCopySize } from '../globals/roofCopySize.js';
+
+/**
+ * Upload a roof tile image when its texture does not already contain it.
+ *
+ * @param {GPUDevice} device Device owning the destination texture.
+ * @param {Object} tile Raster tile with image and texture state.
+ */
+export function uploadRoofTile(device, tile) {
+  const source = tile.texture;
+  if (source.uploaded !== source.image) {
+    device.queue.copyExternalImageToTexture((
+      roofImage.source = tile.image,
+      roofImage
+    ), (
+      roofTarget.texture = source.texture,
+      roofTarget
+    ), (
+      roofCopySize[0] = source.texture.width,
+      roofCopySize[1] = source.texture.height,
+      roofCopySize
+    ));
+    roofImage.source = null;
+    roofTarget.texture = null;
+    source.uploaded = source.image;
+  }
+}

package/src/traffic/README.md

@@ -0,0 +1,30 @@
+# Traffic
+
+[Source guide](../README.md) | [Project README](../../README.md)
+
+Loads traffic lanes and schedules trips for vehicles and pedestrians, updating
+their poses in the shared GPU scene as simulation time advances.
+
+## Lane data to moving objects
+
+```mermaid
+flowchart LR
+  GeoJSON["GeoJSON lines"] --> Lanes["Lanes + properties"]
+  Lanes --> Project["Project to local metres"]
+  Terrain["Terrain / explicit elevation"] --> Project
+  Project --> Trips["Flow / timetable trips"]
+  Clock["Simulation time"] --> Trips
+  Trips --> Pose["GPU poses"]
+  Shapes["Vehicle shapes"] --> Pose
+  Pose --> Frame["Scene update"]
+```
+
+New lane loads abort the previous request; live time schedules further frames.
+Collision queries use current traffic bounds, but traffic does not steer around
+the walker. Timetables use their configured time zone.
+
+- [initTraffic.js](./initTraffic.js): configure a traffic layer.
+- [loadTraffic.js](./loadTraffic.js): request lanes for the current time.
+- [tickTraffic.js](./tickTraffic.js): refresh trips and poses.
+
+Related: [vehicles](../vehicles/README.md), [sunlight](../sunlight/README.md), [terrain](../terrain/README.md).

package/src/traffic/addTraffic.js

@@ -1,9 +1,12 @@
 import { trafficByLayer } from '../weakmaps/trafficByLayer.js';
-
-
 import { placeTraffic } from './placeTraffic.js';
 import { startTraffic } from './startTraffic.js';
 
+/**
+ * Register traffic state on layer addition and start loading if the layer is ready.
+ *
+ * @param {Object} state Traffic layer state.
+ */
 export function addTraffic(state) {
   trafficByLayer.set(state.layer, state);
   if (state.ready) startTraffic(state);

package/src/traffic/clockMinutes.js

@@ -1,5 +1,12 @@
 
 
+/**
+ * Convert an HH:MM clock string to minutes after midnight.
+ *
+ * @param {string} clockTime Clock time in HH:MM form.
+ *
+ * @returns {number} Minutes after midnight.
+ */
 export function clockMinutes(clockTime) {
   const parts = clockTime.split(':');
   return Number(parts[0]) * 60 + Number(parts[1]);

package/src/traffic/compareDepartures.js

@@ -1,5 +1,13 @@
 
 
+/**
+ * Order departure times numerically.
+ *
+ * @param {number} a First departure in minutes.
+ * @param {number} b Second departure in minutes.
+ *
+ * @returns {number} Signed difference between the departures.
+ */
 export function compareDepartures(a, b) {
   return a - b;
 }

package/src/traffic/createTrafficMesh.js

@@ -1,7 +1,18 @@
 import * as createMeshApi from '../rendering/createMesh.js';
 
-export function createTrafficMesh(state, data, featureFaces, material, usage = 0) {
-  const result = createMeshApi.createMesh(state.layer, data, material, usage);
-  result.extras.featureFaces = featureFaces;
-  return result;
+/**
+ * Create a traffic mesh and attach its feature ranges for picking.
+ *
+ * @param {Object} state Traffic layer state.
+ * @param {Object} data Mesh geometry data.
+ * @param {Array} featureFaces Face ranges for picking.
+ * @param {Object} material Mesh material options.
+ * @param {number} [usage=0] Additional GPU buffer usage flags.
+ *
+ * @returns {Object} The created mesh.
+ */
+export function createTrafficMesh(state, data, featureFaces, material, usage = 0) {
+  const result = createMeshApi.createMesh(state.layer, data, material, usage);
+  result.extras.featureFaces = featureFaces;
+  return result;
 }

package/src/traffic/destroyTrafficGpu.js

@@ -1,3 +1,8 @@
+/**
+ * Destroy the traffic compute buffers and release the GPU state.
+ *
+ * @param {Object} state Traffic layer state.
+ */
 export function destroyTrafficGpu(state) {
   state.gpu?.params?.destroy();
   state.gpu?.template?.destroy();

package/src/traffic/disposeTrafficObject.js

@@ -1,18 +1,21 @@
 import { highlightedFeatureByLayer } from '../weakmaps/highlightedFeatureByLayer.js';
 import { hoveredFeatureByLayer } from '../weakmaps/hoveredFeatureByLayer.js';
-
-
-
 import * as disposeMesh from '../rendering/disposeMesh.js';
 import * as setHighlight from '../picking/setHighlight.js';
 import * as showFeature from '../picking/showFeature.js';
 
-export function disposeTrafficObject(state, object) {
-  if (!object) return;
-  if (highlightedFeatureByLayer.get(state.layer)?.mesh === object) {
-    setHighlight.setHighlight(state.layer, null);
-    hoveredFeatureByLayer.set(state.layer, null);
-    showFeature.showFeature(state.layer, null);
-  };
-  disposeMesh.disposeMesh(state.layer, object);
+/**
+ * Dispose a traffic mesh, clearing the layer's highlight and tooltip if they reference it.
+ *
+ * @param {Object} state Traffic layer state.
+ * @param {Object|null} object Mesh to dispose, if present.
+ */
+export function disposeTrafficObject(state, object) {
+  if (!object) return;
+  if (highlightedFeatureByLayer.get(state.layer)?.mesh === object) {
+    setHighlight.setHighlight(state.layer, null);
+    hoveredFeatureByLayer.set(state.layer, null);
+    showFeature.showFeature(state.layer, null);
+  };
+  disposeMesh.disposeMesh(state.layer, object);
 }

package/src/traffic/drawTrafficRoute.js

@@ -2,7 +2,11 @@ import { trafficRouteMaterial } from '../globals/trafficRouteMaterial.js';
 import { routeGeometry } from '../geometry/routeGeometry.js';
 import { createTrafficMesh } from './createTrafficMesh.js';
 
-
+/**
+ * Create the optional route outline mesh from the current traffic lanes.
+ *
+ * @param {Object} state Traffic layer state.
+ */
 export function drawTrafficRoute(state) {
   state.route = createTrafficMesh(state, routeGeometry(state.lanes),
     /* alloc */ [], trafficRouteMaterial);

package/src/traffic/failTraffic.js

@@ -1,6 +1,12 @@
-export function failTraffic(state, error) {
-  state.error = error;
-  state.status.textContent = `${state.vehicle}: Error: ${error.message}`;
-  state.status.setAttribute('role', 'alert');
-  console.error('Traffic layer', error);
-}
+/**
+ * Record and log a traffic error and expose it in the layer status.
+ *
+ * @param {Object} state Traffic layer state.
+ * @param {Error} error Error to report.
+ */
+export function failTraffic(state, error) {
+  state.error = error;
+  state.status.textContent = `${state.vehicle}: Error: ${error.message}`;
+  state.status.setAttribute('role', 'alert');
+  console.error('Traffic layer', error);
+}

package/src/traffic/failedTrafficLoad.js

@@ -1,5 +1,12 @@
 import { failTraffic } from './failTraffic.js';
 
-export function failedTrafficLoad(state, signal, error) {
-  if (!signal.aborted && error.name !== 'AbortError') failTraffic(state, error);
+/**
+ * Report traffic loading errors unless the request was cancelled.
+ *
+ * @param {Object} state Traffic layer state.
+ * @param {AbortSignal} signal Signal for the lane request.
+ * @param {Error} error Loading failure.
+ */
+export function failedTrafficLoad(state, signal, error) {
+  if (!signal.aborted && error.name !== 'AbortError') failTraffic(state, error);
 }

package/src/traffic/featuresToTrafficLanes.js

@@ -1,9 +1,17 @@
 import { trafficEmptyList } from '../globals/trafficEmptyList.js';
+
 // GeoJSON (Multi)LineStrings become lanes ({latlngs, properties, elevation?}); prepare() adds `points` ([x, z, ground]),
 // `lengths` and `length` in layer-local metres.
 
 
 
+/**
+ * Convert GeoJSON line and multiline features to lanes, preserving their properties and elevation.
+ *
+ * @param {Object} collection GeoJSON feature collection.
+ *
+ * @returns {Array} Lanes with latitude-longitude points and feature properties.
+ */
 export function toLanes({ features = trafficEmptyList }) {
   const lanes = /* alloc */ [];
   let geometry, properties, lines, line, latlngs, lng, lat, i;

package/src/traffic/fetchTrafficLanes.js

@@ -1,10 +1,21 @@
-export async function fetchTrafficLanes(state, time, signal) {
-  const href = /* alloc */ new URL(state.url, document.baseURI).href;
-  if (/\.m?js(?:[?#]|$)/i.test(state.url)) return (await import(href)).default(time, state.layer, signal);
-  if (!state.file) {
-    const response = await fetch(href, /* alloc */ { signal });
-    if (!response.ok) throw /* alloc */ new Error(`HTTP ${response.status}`);
-    state.file = await response.json();
-  }
-  return state.file;
-}
+/**
+ * Load time-dependent lanes from a JS module or fetch and cache a static GeoJSON response.
+ *
+ * @param {Object} state Traffic layer state.
+ * @param {Date} time Current simulation time.
+ * @param {AbortSignal} signal Signal for cancelling the request.
+ *
+ * @returns {Promise<Object>} The loaded GeoJSON data.
+ *
+ * @throws {Error} If the static data request returns a non-success status.
+ */
+export async function fetchTrafficLanes(state, time, signal) {
+  const href = /* alloc */ new URL(state.url, document.baseURI).href;
+  if (/\.m?js(?:[?#]|$)/i.test(state.url)) return (await import(href)).default(time, state.layer, signal);
+  if (!state.file) {
+    const response = await fetch(href, /* alloc */ { signal });
+    if (!response.ok) throw /* alloc */ new Error(`HTTP ${response.status}`);
+    state.file = await response.json();
+  }
+  return state.file;
+}

package/src/traffic/groundTraffic.js

@@ -1,8 +1,12 @@
 import { rootByLayer } from '../weakmaps/rootByLayer.js';
-
 import { readyTerrainOf } from '../terrain/readyTerrainOf.js';
 import { mapElevationOf } from '../terrain/mapElevationOf.js';
 
+/**
+ * Update lane point heights from ready terrain or explicit elevations and invalidate GPU lane data.
+ *
+ * @param {Object} state Traffic layer state.
+ */
 export function groundTraffic(state) {
   const { layer, lanes } = state;
   const terrain = readyTerrainOf(layer._map);