leaflet-city-mapper 0.0.9 → 0.1.1

package/src/traffic/initTraffic.js

@@ -4,24 +4,9 @@ import { trafficEmptyOptions } from '../globals/trafficEmptyOptions.js';
 import { vehicles } from '../globals/vehicles.js';
 import { trafficShader } from '../globals/trafficShader.js';
 import { trafficByLayer } from '../weakmaps/trafficByLayer.js';
-
-
-/**
- * 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), 'boat', 'bus', 'tram', 'metro', 'bicycle' or 'pedestrian'; `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 (count and vehicle type) sits under the layer's entry in the layers control.
- * L.Control.Time on the same map drives the time; without one, vehicles run live.
- */
 import { build } from '../geometry/buildGeometryParts.js';
 import { init3D } from '../scene/init3D.js';
 import { tooltip } from './trafficTooltip.js';
-
-
-
 import { addTraffic } from './addTraffic.js';
 import { placeTraffic } from './placeTraffic.js';
 import { removeTraffic } from './removeTraffic.js';
@@ -30,6 +15,23 @@ import { tickTraffic } from './tickTraffic.js';
 import { updateTraffic } from './updateTraffic.js';
 import { updateTrafficTerrain } from './updateTrafficTerrain.js';
 
+/**
+ * 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), 'boat', 'bus', 'tram', 'metro', 'bicycle' or 'pedestrian'; `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 (count and vehicle type) sits under the layer's entry in the layers control.
+ * L.Control.Time on the same map drives the time; without one, vehicles run live.
+ */
+
+/**
+ * Initialize a traffic layer's model, GPU inputs, status and lifecycle handlers.
+ *
+ * @param {L.Layer} layer Traffic layer.
+ * @param {Object} [options] Source URL, vehicle, lane offset, outline and other layer options.
+ */
 export function initTraffic(layer, { url, vehicle = 'car', side, outline, speed: velocity = sharedSpeed, ...options } = trafficEmptyOptions) {
   const { model, lights, side: defaultSide } = vehicles[vehicle];
   side ??= defaultSide;

package/src/traffic/loadTraffic.js

@@ -3,6 +3,11 @@ import { fetchTrafficLanes } from './fetchTrafficLanes.js';
 import { loadedTrafficLanes } from './loadedTrafficLanes.js';
 import { failedTrafficLoad } from './failedTrafficLoad.js';
 
+/**
+ * Cancel the previous lane request and load lanes for the current valid simulation time.
+ *
+ * @param {Object} state Traffic layer state.
+ */
 export function loadTraffic(state) {
   const { time } = trafficNow(state);
   if (!Number.isFinite(time?.getTime())) return;

package/src/traffic/loadedTrafficLanes.js

@@ -1,16 +1,23 @@
 import { toLanes } from './featuresToTrafficLanes.js';
 import { prepareTraffic } from './prepareTraffic.js';
 
-export function loadedTrafficLanes(state, signal, data) {
-  if (signal.aborted || !state.layer._map) return;
-  state.error = null;
-  if (data === state.loaded) {
-    state.nextCheck = -Infinity;
-    if (!state.frame) state.tick();
-    return;
-  }
-  state.loaded = data;
-  state.lanes = toLanes(data);
-  prepareTraffic(state);
-  if (!state.frame) state.tick();
+/**
+ * Apply loaded lanes unless cancelled or detached, preparing new data and restarting traffic updates.
+ *
+ * @param {Object} state Traffic layer state.
+ * @param {AbortSignal} signal Signal for the completed request.
+ * @param {Object} data Loaded GeoJSON data.
+ */
+export function loadedTrafficLanes(state, signal, data) {
+  if (signal.aborted || !state.layer._map) return;
+  state.error = null;
+  if (data === state.loaded) {
+    state.nextCheck = -Infinity;
+    if (!state.frame) state.tick();
+    return;
+  }
+  state.loaded = data;
+  state.lanes = toLanes(data);
+  prepareTraffic(state);
+  if (!state.frame) state.tick();
 }

package/src/traffic/locateTraffic.js

@@ -1,11 +1,20 @@
-import { along } from '../geometry/interpolateRoute.js';
-
-export function locateTraffic(state, trip, target) {
-  const { points, lengths, length } = trip.lane;
-  let distance = trip.distance + state.elapsed * trip.speed;
-  distance -= length * Math.floor(distance / length);
-  const position = along(points, lengths, distance, target);
-  position.x -= position.dz * state.side;
-  position.z += position.dx * state.side;
-  return position;
-}
+import { along } from '../geometry/interpolateRoute.js';
+
+/**
+ * Interpolate a trip's current position along its looping lane and apply the lateral offset.
+ *
+ * @param {Object} state Traffic layer state.
+ * @param {Object} trip Trip with lane, distance and speed.
+ * @param {Object} target Reusable output position.
+ *
+ * @returns {Object} Position and direction along the lane.
+ */
+export function locateTraffic(state, trip, target) {
+  const { points, lengths, length } = trip.lane;
+  let distance = trip.distance + state.elapsed * trip.speed;
+  distance -= length * Math.floor(distance / length);
+  const position = along(points, lengths, distance, target);
+  position.x -= position.dz * state.side;
+  position.z += position.dx * state.side;
+  return position;
+}

package/src/traffic/moveTraffic.js

@@ -1,15 +1,21 @@
-export function moveTraffic(state, seconds) {
-  const { device } = state.gpu;
-  state.paramFloats[0] = state.elapsed = seconds;
-  state.paramFloats[1] = state.side;
-  state.paramInts[2] = state.vertices;
-  state.paramInts[3] = state.trips.length * state.vertices;
-  device.queue.writeBuffer(state.gpu.params, 0, state.params);
-  const encoder = device.createCommandEncoder(), pass = encoder.beginComputePass();
-  pass.setPipeline(state.gpu.pipeline);
-  pass.setBindGroup(0, state.gpu.bindGroup);
-  pass.dispatchWorkgroups(state.trips.length);
-  pass.end();
-  device.queue.submit(/* alloc */ [encoder.finish()]);
-  state.stale = true;
-}
+/**
+ * Dispatch the GPU traffic pose computation for the elapsed time and mark CPU geometry stale.
+ *
+ * @param {Object} state Traffic layer state.
+ * @param {number} seconds Seconds elapsed since the trip positions were rebased.
+ */
+export function moveTraffic(state, seconds) {
+  const { device } = state.gpu;
+  state.paramFloats[0] = state.elapsed = seconds;
+  state.paramFloats[1] = state.side;
+  state.paramInts[2] = state.vertices;
+  state.paramInts[3] = state.trips.length * state.vertices;
+  device.queue.writeBuffer(state.gpu.params, 0, state.params);
+  const encoder = device.createCommandEncoder(), pass = encoder.beginComputePass();
+  pass.setPipeline(state.gpu.pipeline);
+  pass.setBindGroup(0, state.gpu.bindGroup);
+  pass.dispatchWorkgroups(state.trips.length);
+  pass.end();
+  device.queue.submit(/* alloc */ [encoder.finish()]);
+  state.stale = true;
+}

package/src/traffic/placeTraffic.js

@@ -1,5 +1,10 @@
 import { locateTraffic } from './locateTraffic.js';
 
+/**
+ * Refresh stale CPU traffic positions and normals from the current trip poses.
+ *
+ * @param {Object} state Traffic layer state.
+ */
 export function placeTraffic(state) {
   if (!state.mesh || !state.stale) return;
   state.stale = false;

package/src/traffic/prepareTraffic.js

@@ -1,12 +1,14 @@
 import { locationByLayer } from '../weakmaps/locationByLayer.js';
-
 import { radians } from '../globals/radians.js';
 import { L } from '../globals/L.js';
-
-
 import { disposeTrafficObject } from './disposeTrafficObject.js';
 import { groundTraffic } from './groundTraffic.js';
 
+/**
+ * Project lane coordinates to local metres, compute distances and heights, and invalidate old route geometry.
+ *
+ * @param {Object} state Traffic layer state.
+ */
 export function prepareTraffic(state) {
   const { layer, lanes } = state;
   const crs = layer._map.options.crs, origin = crs.project(locationByLayer.get(layer));

package/src/traffic/readyTraffic.js

@@ -1,6 +1,11 @@
 import { startTraffic } from './startTraffic.js';
 
-export function readyTraffic(state) {
-  state.ready = true;
-  if (state.layer._map) startTraffic(state);
+/**
+ * Mark a traffic layer ready and start it if already attached to a map.
+ *
+ * @param {Object} state Traffic layer state.
+ */
+export function readyTraffic(state) {
+  state.ready = true;
+  if (state.layer._map) startTraffic(state);
 }

package/src/traffic/rebaseTraffic.js

@@ -1,11 +1,13 @@
 import { rendererByLayer } from '../weakmaps/rendererByLayer.js';
-
-
-
 import { destroyTrafficGpu } from './destroyTrafficGpu.js';
 import { trafficStorage } from './trafficStorage.js';
 import { uploadTrafficLanes } from './uploadTrafficLanes.js';
 
+/**
+ * Upload current lanes and trips, recreating device resources as needed and binding the traffic compute pipeline.
+ *
+ * @param {Object} state Traffic layer state.
+ */
 export function rebaseTraffic(state) {
   const { device } = rendererByLayer.get(state.layer);
   if (state.gpu?.device !== device) {

package/src/traffic/rebuildTrafficMesh.js

@@ -4,7 +4,11 @@ import { createTrafficMesh } from './createTrafficMesh.js';
 import { disposeTrafficObject } from './disposeTrafficObject.js';
 import { trafficBounds } from './trafficBounds.js';
 
-
+/**
+ * Replace the batched vehicle mesh and feature ranges when the active trip set changes.
+ *
+ * @param {Object} state Traffic layer state.
+ */
 export function rebuildTrafficMesh(state) {
   const { trips, model, vertices } = state;
   disposeTrafficObject(state, state.mesh);

package/src/traffic/refreshTrafficTrips.js

@@ -1,32 +1,42 @@
-import { tripsAt } from './tripsAt.js';
-import { failTraffic } from './failTraffic.js';
-import { drawTrafficRoute } from './drawTrafficRoute.js';
-import { rebuildTrafficMesh } from './rebuildTrafficMesh.js';
-import { rebaseTraffic } from './rebaseTraffic.js';
-import { trafficStatusText } from './trafficStatusText.js';
-
-export function refreshTrafficTrips(state, time, ms, valid) {
-  let text;
-  try {
-    if (valid) state.trips = tripsAt(time, state.lanes, state.velocity);
-    else state.trips.length = 0;
-    text = trafficStatusText(state, valid);
-  } catch (error) {
-    failTraffic(state, error);
-    return;
-  }
-  state.rebasedAt = ms;
-  state.nextCheck = ms + 1000;
-  let key = '', trip;
-  for (trip of state.trips) key += `${key ? ',' : ''}${trip.id}`;
-  const routeNeeded = state.outline && !state.route && state.lanes.length;
-  const changed = key !== state.tripsKey || Boolean(routeNeeded);
-  if (routeNeeded) drawTrafficRoute(state);
-  if (key !== state.tripsKey) { rebuildTrafficMesh(state); state.tripsKey = key; }
-  if (state.mesh) rebaseTraffic(state);
-  if (!state.error) {
-    if (state.status.textContent !== text) state.status.textContent = text;
-    state.status.removeAttribute('role');
-  }
-  return changed;
-}
+import { tripsAt } from './tripsAt.js';
+import { failTraffic } from './failTraffic.js';
+import { drawTrafficRoute } from './drawTrafficRoute.js';
+import { rebuildTrafficMesh } from './rebuildTrafficMesh.js';
+import { rebaseTraffic } from './rebaseTraffic.js';
+import { trafficStatusText } from './trafficStatusText.js';
+
+/**
+ * Recompute scheduled trips and status, rebuilding changed geometry and rebasing GPU data.
+ *
+ * @param {Object} state Traffic layer state.
+ * @param {Date|undefined} time Simulation time, if available.
+ * @param {number|undefined} ms Simulation timestamp in milliseconds, if available.
+ * @param {boolean} valid Whether the simulation timestamp is valid.
+ *
+ * @returns {boolean|undefined} Whether geometry changed, or undefined if updating trips failed.
+ */
+export function refreshTrafficTrips(state, time, ms, valid) {
+  let text;
+  try {
+    if (valid) state.trips = tripsAt(time, state.lanes, state.velocity);
+    else state.trips.length = 0;
+    text = trafficStatusText(state, valid);
+  } catch (error) {
+    failTraffic(state, error);
+    return;
+  }
+  state.rebasedAt = ms;
+  state.nextCheck = ms + 1000;
+  let key = '', trip;
+  for (trip of state.trips) key += `${key ? ',' : ''}${trip.id}`;
+  const routeNeeded = state.outline && !state.route && state.lanes.length;
+  const changed = key !== state.tripsKey || Boolean(routeNeeded);
+  if (routeNeeded) drawTrafficRoute(state);
+  if (key !== state.tripsKey) { rebuildTrafficMesh(state); state.tripsKey = key; }
+  if (state.mesh) rebaseTraffic(state);
+  if (!state.error) {
+    if (state.status.textContent !== text) state.status.textContent = text;
+    state.status.removeAttribute('role');
+  }
+  return changed;
+}

package/src/traffic/removeTraffic.js

@@ -1,9 +1,12 @@
 import { trafficByLayer } from '../weakmaps/trafficByLayer.js';
-
-
 import { disposeTrafficObject } from './disposeTrafficObject.js';
 import { destroyTrafficGpu } from './destroyTrafficGpu.js';
 
+/**
+ * Abort loading, unregister listeners and release traffic meshes, GPU resources and lane state.
+ *
+ * @param {Object} state Traffic layer state.
+ */
 export function removeTraffic(state) {
   state.request?.abort();
   cancelAnimationFrame(state.frame);

package/src/traffic/routeColor.js

@@ -1,6 +1,13 @@
-export function routeColor(properties) {
-  const color = properties?.route_color;
-  if (!/^[\da-f]{6}$/i.test(color)) return /* alloc */ [0.1, 0.55, 0.65];
-  const value = Number.parseInt(color, 16);
-  return /* alloc */ [(value >> 16 & 255) / 255, (value >> 8 & 255) / 255, (value & 255) / 255];
-}
+/**
+ * Decode a six-digit route color to normalized RGB, falling back to the default route color.
+ *
+ * @param {Object|null|undefined} properties Route properties containing an optional route_color.
+ *
+ * @returns {number[]} Normalized RGB components.
+ */
+export function routeColor(properties) {
+  const color = properties?.route_color;
+  if (!/^[\da-f]{6}$/i.test(color)) return /* alloc */ [0.1, 0.55, 0.65];
+  const value = Number.parseInt(color, 16);
+  return /* alloc */ [(value >> 16 & 255) / 255, (value >> 8 & 255) / 255, (value & 255) / 255];
+}

package/src/traffic/scheduledTrips.js

@@ -2,14 +2,17 @@ import { trafficClocks } from '../globals/trafficClocks.js';
 import { clockMinutes } from './clockMinutes.js';
 import { compareDepartures } from './compareDepartures.js';
 
-
 /**
  * Trips of a frequency-based timetable (like GTFS frequencies.txt) underway at `date`, in the timetable's local time.
+ *
+ * @param {Date|string|number} date Simulation date.
  * @param {{timeZone: string, duration: number, services: Array<{from: string, to: string, every?: number, months?: number[], weekdays?: number[]}>}} timetable
  * `duration` and `every` are minutes; `from`/`to` are 'HH:MM' first/last departures; months are 1-12, weekdays 0 (Sunday)-6.
+ *
  * @returns {Array<{id: string, departure: string, progress: number}>} `progress` is 0-1 along the lane.
+ *
+ * @throws {Error} If the date is invalid.
  */
-
 export function scheduledTrips(date, { timeZone, duration, services }) {
   const time = date instanceof Date ? date
     : /* alloc */ new Date(date);

package/src/traffic/startTraffic.js

@@ -1,8 +1,13 @@
 import { underEntry } from '../layer-controls/underEntry.js';
 
-export function startTraffic(state) {
-  state.layer._map.off('simulationtimechange layerremove', state.update).on('simulationtimechange layerremove', state.update);
-  state.layer._map.off('terrainchange', state.terrain).on('terrainchange', state.terrain);
-  underEntry(state.layer, state.status);
-  state.update();
+/**
+ * Register time and terrain listeners, show the layer status and start traffic updates.
+ *
+ * @param {Object} state Traffic layer state.
+ */
+export function startTraffic(state) {
+  state.layer._map.off('simulationtimechange layerremove', state.update).on('simulationtimechange layerremove', state.update);
+  state.layer._map.off('terrainchange', state.terrain).on('terrainchange', state.terrain);
+  underEntry(state.layer, state.status);
+  state.update();
 }

package/src/traffic/tickTraffic.js

@@ -1,12 +1,14 @@
 import { rendererByLayer } from '../weakmaps/rendererByLayer.js';
-
-
-
 import { update as updateScene } from '../scene/scheduleSceneUpdate.js';
 import { trafficNow } from './trafficNow.js';
 import { refreshTrafficTrips } from './refreshTrafficTrips.js';
 import { updateTrafficPose } from './updateTrafficPose.js';
 
+/**
+ * Update trips and GPU poses for the simulation clock, scheduling another frame in live mode.
+ *
+ * @param {Object} state Traffic layer state.
+ */
 export function tickTraffic(state) {
   state.frame = undefined;
   if (!state.ready || !state.layer._map) return;

package/src/traffic/trafficBounds.js

@@ -1,5 +1,10 @@
 import { computeBounds } from '../geometry/computeBounds.js';
 
+/**
+ * Compute conservative traffic mesh bounds from lane points, vehicle dimensions and lateral offset.
+ *
+ * @param {Object} state Traffic layer state.
+ */
 export function trafficBounds(state) {
   let radius = 20, height = 5;
   let i, lane, x, z, y;

package/src/traffic/trafficNow.js

@@ -1,11 +1,16 @@
 import { timeControlByMap } from '../weakmaps/timeControlByMap.js';
 
-
-
-export function trafficNow(state) {
-  const control = timeControlByMap.get(state.layer._map);
-  const live = control ? control.live : true;
-  return /* alloc */ {
-    live, time: live ? /* alloc */ new Date() : control.time,
-  };
-}
+/**
+ * Return the selected simulation time, or the current time when the map clock is live.
+ *
+ * @param {Object} state Traffic layer state.
+ *
+ * @returns {Object} Live-mode flag and selected time.
+ */
+export function trafficNow(state) {
+  const control = timeControlByMap.get(state.layer._map);
+  const live = control ? control.live : true;
+  return /* alloc */ {
+    live, time: live ? /* alloc */ new Date() : control.time,
+  };
+}

package/src/traffic/trafficStatusText.js

@@ -1,5 +1,13 @@
-export function trafficStatusText(state, valid) {
-  if (!valid) return `${state.vehicle}: select a valid simulation date`;
-  if (!state.loaded) return `${state.vehicle}: loading…`;
-  return `${state.trips.length} ${state.vehicle === 'boat' ? 'boats' : state.vehicle}`;
-}
+/**
+ * Format the traffic layer status for an invalid clock, loading state or active trip count.
+ *
+ * @param {Object} state Traffic layer state.
+ * @param {boolean} valid Whether the simulation time is valid.
+ *
+ * @returns {string} Status text.
+ */
+export function trafficStatusText(state, valid) {
+  if (!valid) return `${state.vehicle}: select a valid simulation date`;
+  if (!state.loaded) return `${state.vehicle}: loading…`;
+  return `${state.trips.length} ${state.vehicle === 'boat' ? 'boats' : state.vehicle}`;
+}

package/src/traffic/trafficStorage.js

@@ -1,5 +1,13 @@
-export function trafficStorage(device, data) {
-  const buffer = device.createBuffer(/* alloc */ { size: Math.max(16, data.byteLength), usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST });
-  device.queue.writeBuffer(buffer, 0, data);
-  return buffer;
-}
+/**
+ * Create and initialize a GPU storage buffer with at least 16 bytes.
+ *
+ * @param {GPUDevice} device Device creating the buffer.
+ * @param {TypedArray} data Buffer contents.
+ *
+ * @returns {GPUBuffer} The initialized storage buffer.
+ */
+export function trafficStorage(device, data) {
+  const buffer = device.createBuffer(/* alloc */ { size: Math.max(16, data.byteLength), usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST });
+  device.queue.writeBuffer(buffer, 0, data);
+  return buffer;
+}

package/src/traffic/trafficTooltip.js

@@ -1,3 +1,10 @@
+/**
+ * Build a text-only traffic tooltip from the route name, departure and description.
+ *
+ * @param {Object} feature Feature containing traffic properties.
+ *
+ * @returns {HTMLElement} Tooltip content.
+ */
 export function tooltip({ properties: p }) {
   const content = document.createElement('div');
   content.style.whiteSpace = 'pre-line';

package/src/traffic/tripsAt.js

@@ -1,8 +1,15 @@
 import { vehicleOffsets } from "./vehicleOffsets.js";
 import { scheduledTrips } from "./scheduledTrips.js";
 
-// A lane with a `timetable` runs scheduled trips end to end; one with a `flow` (vehicles/h) loops evenly spaced vehicles.
-
+/**
+ * Generate active timetable trips and evenly spaced looping vehicles for flow-based lanes at the given time.
+ *
+ * @param {Date} time Simulation time.
+ * @param {Array} lanes Prepared traffic lanes.
+ * @param {number} velocity Flow-vehicle speed in metres per second.
+ *
+ * @returns {Array} Active trips and their lane positions.
+ */
 export function tripsAt(time, lanes, velocity) {
   const trips = /* alloc */ [];
   let l, lane, timetable, flow, trip, travelled, offsets, k;

package/src/traffic/updateTraffic.js

@@ -1,12 +1,15 @@
 import { controlByLayer } from '../weakmaps/controlByLayer.js';
-
-
-
 import { loadTraffic } from './loadTraffic.js';
 
-export function updateTraffic(state, event) {
-  if (event?.layer && !controlByLayer.get(event.layer)?.time) return;
-  cancelAnimationFrame(state.frame);
-  loadTraffic(state);
-  state.tick();
+/**
+ * Reload lanes and tick the simulation when the clock changes or a relevant layer is removed.
+ *
+ * @param {Object} state Traffic layer state.
+ * @param {Object} [event] Map event, optionally containing a removed layer.
+ */
+export function updateTraffic(state, event) {
+  if (event?.layer && !controlByLayer.get(event.layer)?.time) return;
+  cancelAnimationFrame(state.frame);
+  loadTraffic(state);
+  state.tick();
 }

package/src/traffic/updateTrafficLights.js

@@ -1,18 +1,23 @@
-import { locateTraffic } from './locateTraffic.js';
-
-export function updateTrafficLights(state) {
-  state.litAt = performance.now();
-  const lights = /* alloc */ [];
-  const target = state.position ||= /* alloc */ {};
-  let trip, x, y, z, dx, dz, lx, ly, lz, light;
-  for (trip of state.trips) {
-    ({ x, y, z, dx, dz } = locateTraffic(state, trip, target));
-    for (light of state.lights) {
-      [lx, ly, lz] = light.position;
-      lights.push(/* alloc */ {
-        ...light, position: /* alloc */ [x - lx * dz - lz * dx, y + ly, z + lx * dx - lz * dz],
-      });
-    }
-  }
-  state.mesh.extras.lights = lights;
-}
+import { locateTraffic } from './locateTraffic.js';
+
+/**
+ * Rebuild the mesh's light snapshot by transforming each vehicle light to its current lane pose.
+ *
+ * @param {Object} state Traffic layer state.
+ */
+export function updateTrafficLights(state) {
+  state.litAt = performance.now();
+  const lights = /* alloc */ [];
+  const target = state.position ||= /* alloc */ {};
+  let trip, x, y, z, dx, dz, lx, ly, lz, light;
+  for (trip of state.trips) {
+    ({ x, y, z, dx, dz } = locateTraffic(state, trip, target));
+    for (light of state.lights) {
+      [lx, ly, lz] = light.position;
+      lights.push(/* alloc */ {
+        ...light, position: /* alloc */ [x - lx * dz - lz * dx, y + ly, z + lx * dx - lz * dz],
+      });
+    }
+  }
+  state.mesh.extras.lights = lights;
+}

package/src/traffic/updateTrafficPose.js

@@ -1,8 +1,15 @@
-import { moveTraffic } from './moveTraffic.js';
-import { updateTrafficLights } from './updateTrafficLights.js';
-
-export function updateTrafficPose(state, ms, live) {
-  if (!state.mesh) return;
-  moveTraffic(state, (ms - state.rebasedAt) / 1000);
-  if (state.lights && (!live || !(performance.now() - state.litAt < 100))) updateTrafficLights(state);
-}
+import { moveTraffic } from './moveTraffic.js';
+import { updateTrafficLights } from './updateTrafficLights.js';
+
+/**
+ * Update GPU vehicle poses and refresh light positions, throttling live light updates.
+ *
+ * @param {Object} state Traffic layer state.
+ * @param {number} ms Simulation timestamp in milliseconds.
+ * @param {boolean} live Whether the simulation clock is live.
+ */
+export function updateTrafficPose(state, ms, live) {
+  if (!state.mesh) return;
+  moveTraffic(state, (ms - state.rebasedAt) / 1000);
+  if (state.lights && (!live || !(performance.now() - state.litAt < 100))) updateTrafficLights(state);
+}