leaflet-city-mapper 0.0.8 → 0.1.0

package/src/globals/shadowMeshLayout.js

@@ -1,3 +1,8 @@
+/**
+ * Reusable bind group layout descriptor for dynamically offset shadow mesh uniforms.
+ *
+ * @type {Object}
+ */
 export const shadowMeshLayout = {
   entries: [{
     binding: 0,

package/src/globals/shadowOffsets.js

@@ -1 +1,6 @@
+/**
+ * Reusable dynamic mesh uniform offsets for shadow drawing.
+ *
+ * @type {Array<number|null>}
+ */
 export const shadowOffsets = [null];

package/src/globals/shadowPass.js

@@ -1,3 +1,8 @@
+/**
+ * Reusable depth-only render pass descriptor for shadows.
+ *
+ * @type {Object}
+ */
 export const shadowPass = {
   colorAttachments: [],
   depthStencilAttachment: {

package/src/globals/shadowPipeline.js

@@ -1,3 +1,8 @@
+/**
+ * Reusable depth render pipeline descriptor for shadow meshes.
+ *
+ * @type {Object}
+ */
 export const shadowPipeline = {
   layout: null,
   vertex: {

package/src/globals/shadowPipelineLayout.js

@@ -1,3 +1,8 @@
+/**
+ * Reusable pipeline layout descriptor for shadow bind groups.
+ *
+ * @type {Object}
+ */
 export const shadowPipelineLayout = {
   bindGroupLayouts: [null, null]
 };

package/src/globals/shadowShader.js

@@ -1,3 +1,8 @@
+/**
+ * Reusable shader module descriptor for generated shadow code.
+ *
+ * @type {Object}
+ */
 export const shadowShader = {
   code: null
 };

package/src/globals/shadowTexture.js

@@ -1,3 +1,8 @@
+/**
+ * Reusable depth texture descriptor for the sunlight shadow map.
+ *
+ * @type {Object}
+ */
 export const shadowTexture = {
   size: [null, null],
   format: 'depth32float',

package/src/globals/shadowValues.js

@@ -1 +1,6 @@
+/**
+ * Reusable sunlight shadow matrix and parameter uniform data.
+ *
+ * @type {Float32Array}
+ */
 export const shadowValues = new Float32Array(20);

package/src/globals/shirt.js

@@ -1 +1,6 @@
+/**
+ * RGB shirt color for the shared walker model.
+ *
+ * @type {Array<number>}
+ */
 export const shirt = [0.75, 0.2, 0.15];

package/src/globals/sinObliquity.js

@@ -1,3 +1,8 @@
 import { radians } from './radians.js';
 
+/**
+ * Sine of Earth's axial obliquity used in celestial position calculations.
+ *
+ * @type {number}
+ */
 export const sinObliquity = Math.sin(23.4397 * radians);

package/src/globals/sizes.js

@@ -1,3 +1,8 @@
+/**
+ * Component counts for supported glTF accessor types.
+ *
+ * @type {Object<string, number>}
+ */
 export const sizes = {
   SCALAR: 1,
   VEC2: 2,

package/src/globals/skin.js

@@ -1,2 +1,7 @@
 // Pedestrian, about 1.77 m tall, prisms as in utils/vehicles.js (forward -z). Limbs hang from their pivot at y = 0.
+/**
+ * RGB skin color shared by walker and pedestrian models.
+ *
+ * @type {Array<number>}
+ */
 export const skin = [0.85, 0.64, 0.5];

package/src/globals/speed.js

@@ -1,3 +1,7 @@
 // Pure helpers of the 'traffic' type: lane interpolation and vehicle scheduling.
-/** Default urban speed (m/s) used to turn a lane's hourly `flow` into vehicles on the road. */
+/**
+ * Default urban speed in m/s used to turn a lane's hourly flow into vehicles on the road.
+ *
+ * @type {number}
+ */
 export const speed = 8;

package/src/globals/sunBindGroup.js

@@ -1,3 +1,8 @@
+/**
+ * Reusable bind group descriptor for sunlight uniforms, shadow texture and lights.
+ *
+ * @type {Object}
+ */
 export const sunBindGroup = {
   layout: null,
   entries: [{

package/src/globals/taillight.js

@@ -1 +1,6 @@
+/**
+ * Emissive red RGB color used for vehicle tail lights.
+ *
+ * @type {Array<number>}
+ */
 export const taillight = [1.7, 0.06, 0.05];

package/src/globals/tau.js

@@ -1 +1,6 @@
+/**
+ * Full circle angle in radians.
+ *
+ * @type {number}
+ */
 export const tau = 2 * Math.PI;

package/src/globals/terrainLayoutEntry.js

@@ -1,3 +1,8 @@
+/**
+ * Reusable bind group layout entry for the elevation texture.
+ *
+ * @type {Object}
+ */
 export const terrainLayoutEntry = {
   binding: 2,
   visibility: null,

package/src/globals/textureLayoutEntries.js

@@ -1,3 +1,8 @@
+/**
+ * Reusable bind group layout entries for material texture views.
+ *
+ * @type {Array<Object>}
+ */
 export const textureLayoutEntries = [{
     binding: null,
     visibility: null,

package/src/globals/tiledBounds.js

@@ -1 +1,6 @@
+/**
+ * Mutable holder for Leaflet's original grid tiled pixel bounds method.
+ *
+ * @type {{value: Function|undefined}}
+ */
 export const tiledBounds = { value: undefined };

package/src/globals/tooltipEvents.js

@@ -1 +1,6 @@
+/**
+ * Mutable holder for Leaflet's original tooltip event method.
+ *
+ * @type {{value: Function|undefined}}
+ */
 export const tooltipEvents = { value: undefined };

package/src/globals/tooltipPosition.js

@@ -1 +1,6 @@
+/**
+ * Mutable holder for Leaflet's original tooltip position method.
+ *
+ * @type {{value: Function|undefined}}
+ */
 export const tooltipPosition = { value: undefined };

package/src/globals/trafficClocks.js

@@ -1 +1,6 @@
+/**
+ * Cached timetable date formatters keyed by time zone.
+ *
+ * @type {Map<string, Intl.DateTimeFormat>}
+ */
 export const trafficClocks = new Map();

package/src/globals/trafficEmptyList.js

@@ -1 +1,6 @@
+/**
+ * Immutable empty feature list used when traffic data has no features.
+ *
+ * @type {ReadonlyArray}
+ */
 export const trafficEmptyList = Object.freeze([]);

package/src/globals/trafficEmptyOptions.js

@@ -1 +1,6 @@
+/**
+ * Immutable empty options used by traffic initialization and mesh creation.
+ *
+ * @type {Object}
+ */
 export const trafficEmptyOptions = Object.freeze({});

package/src/globals/trafficRouteMaterial.js

@@ -1 +1,6 @@
+/**
+ * Unlit material options for displayed traffic routes.
+ *
+ * @type {Object}
+ */
 export const trafficRouteMaterial = Object.freeze({ unlit: true });

package/src/globals/trafficShader.js

@@ -1,4 +1,8 @@
-// One workgroup per vehicle shares its lane lookup and pose across all model vertices.
+/**
+ * Compute shader for vehicle poses; one workgroup shares lane lookup across model vertices.
+ *
+ * @type {string}
+ */
 export const trafficShader = /* wgsl */`
   struct Params { seconds: f32, side: f32, vertices: u32, total: u32 }
   struct Vehicle { start: u32, count: u32, base: f32, speed: f32 }

package/src/globals/triangleContexts.js

@@ -1 +1,6 @@
+/**
+ * Stack of active triangle output contexts during tree geometry generation.
+ *
+ * @type {Array<Object>}
+ */
 export const triangleContexts = [];

package/src/globals/trousers.js

@@ -1 +1,6 @@
+/**
+ * RGB trousers color used by walker and pedestrian models.
+ *
+ * @type {Array<number>}
+ */
 export const trousers = [0.16, 0.2, 0.32];

package/src/globals/types.js

@@ -1,3 +1,8 @@
+/**
+ * Typed array constructors indexed by glTF accessor component type.
+ *
+ * @type {Object<number, Function>}
+ */
 export const types = {
   5120: Int8Array,
   5121: Uint8Array,

package/src/globals/tyre.js

@@ -1 +1,6 @@
+/**
+ * Dark RGB color for vehicle tyres.
+ *
+ * @type {Array<number>}
+ */
 export const tyre = [0.05, 0.05, 0.05];

package/src/globals/uVLayout.js

@@ -1,3 +1,8 @@
+/**
+ * WebGPU vertex buffer layout for two-component texture coordinates.
+ *
+ * @type {Object}
+ */
 export const uVLayout = Object.freeze({
   arrayStride: 8,
   attributes: Object.freeze([Object.freeze({

package/src/globals/vectorStyleNamedColors.js

@@ -1,3 +1,8 @@
+/**
+ * Supported named vector style colors as red, green, blue and alpha values.
+ *
+ * @type {Object<string, Array<number>>}
+ */
 export const vectorStyleNamedColors = {
   black: [0, 0, 0, 1],
   white: [255, 255, 255, 1],

package/src/globals/vectorTileEvents.js

@@ -1 +1,6 @@
+/**
+ * Map events that schedule vector tile refreshes.
+ *
+ * @type {string}
+ */
 export const vectorTileEvents = 'move zoom rotate pitch resize viewreset';

package/src/globals/vehicles.js

@@ -9,6 +9,8 @@ import { boatModel } from '../vehicles/boatModel.js';
 /**
  * `side`: default offset (metres) to the right of the lane centreline. `model(i)` gives the prisms of the i-th vehicle.
  * `lights`: night point lights in model space (see the night lighting grid), e.g. the pool cast by the headlights.
+ *
+ * @type {Object<string, Object>}
  */
 export const vehicles = {
   bicycle: {

package/src/globals/vertexShader.js

@@ -1,3 +1,8 @@
+/**
+ * Reusable shader module descriptor for material vertex code.
+ *
+ * @type {Object}
+ */
 export const vertexShader = {
   code: null
 };

package/src/globals/wantedTiles.js

@@ -1 +1,6 @@
+/**
+ * Reusable map of raster tiles wanted for the current update.
+ *
+ * @type {Map}
+ */
 export const wantedTiles = new Map();

package/src/globals/white.js

@@ -1 +1,6 @@
+/**
+ * Off-white RGB color used in vehicle models.
+ *
+ * @type {Array<number>}
+ */
 export const white = [0.92, 0.93, 0.92];

package/src/globals/workerCogSource.js

@@ -1 +1,6 @@
+/**
+ * Worker-local cache of open COG sources keyed by URL and asset.
+ *
+ * @type {Map}
+ */
 export const workerCogSource = new Map();

package/src/gpu/README.md

@@ -0,0 +1,29 @@
+# GPU resources
+
+[Source guide](../README.md) | [Project README](../../README.md)
+
+Requests WebGPU adapters and devices, initializes shared renderer resources and
+reports device or shader failures. Rendering operations are in a separate folder.
+
+## Renderer lifetime
+
+```mermaid
+flowchart LR
+  Attach["First scene owner"] --> Adapter["Request adapter + device"]
+  Adapter --> Canvas["Configure canvas"]
+  Canvas --> Resources["Create scene / camera / GPU resources"]
+  Resources --> Share["Other layers share renderer"]
+  Share --> Last{"Last owner removed?"}
+  Last -->|yes| Wait["Wait for submitted work"]
+  Wait --> Destroy["Destroy resources + device"]
+  Last -->|no| Transfer["Transfer ownership"]
+```
+
+Missing WebGPU or canvas context is an attachment error. Cleanup errors are
+reported to the layer; see [scene](../scene/README.md) for ownership transfer.
+
+- [initializeSharedRenderer.js](./initializeSharedRenderer.js): create shared renderer state.
+- [initializeRendererResources.js](./initializeRendererResources.js): initialize GPU resources.
+- [releaseRenderer.js](./releaseRenderer.js): release renderer resources.
+
+Related: [rendering](../rendering/README.md), [materials](../materials/README.md).

package/src/gpu/initializeRendererResources.js

@@ -1,8 +1,13 @@
 import { rendererByLayer } from '../weakmaps/rendererByLayer.js';
-
 import { sceneSunlightUniforms } from '../globals/sceneSunlightUniforms.js';
 import { resizeSunlight } from '../shadows/resizeSunlight.js';
 
+/**
+ * Create sunlight bindings and a fallback roof texture for the layer's renderer.
+ *
+ * @param {L.Layer} layer Layer owning the renderer.
+ * @param {GPUDevice} device Device used to create the resources.
+ */
 export function initializeRendererResources(layer, device) {
   const renderer = rendererByLayer.get(layer);
   const layout = device.createBindGroupLayout(/* alloc */ {

package/src/gpu/initializeSharedRenderer.js

@@ -1,11 +1,10 @@
-import { cameraByLayer } from '../weakmaps/cameraByLayer.js';
-import { layersByLayer } from '../weakmaps/layersByLayer.js';
-import { locationByLayer } from '../weakmaps/locationByLayer.js';
-import { rendererByLayer } from '../weakmaps/rendererByLayer.js';
-import { sceneByLayer } from '../weakmaps/sceneByLayer.js';
-import { sceneOriginByLayer } from '../weakmaps/sceneOriginByLayer.js';
-import { sharedByLayer } from '../weakmaps/sharedByLayer.js';
-
+import { cameraByLayer } from '../weakmaps/cameraByLayer.js';
+import { layersByLayer } from '../weakmaps/layersByLayer.js';
+import { locationByLayer } from '../weakmaps/locationByLayer.js';
+import { rendererByLayer } from '../weakmaps/rendererByLayer.js';
+import { sceneByLayer } from '../weakmaps/sceneByLayer.js';
+import { sceneOriginByLayer } from '../weakmaps/sceneOriginByLayer.js';
+import { sharedByLayer } from '../weakmaps/sharedByLayer.js';
 import { rendererDevices } from '../weakmaps/rendererDevices.js';
 import { emptyNode } from '../scene/createSceneNode.js';
 import { failAttachment } from '../scene/failAttachment.js';
@@ -17,6 +16,14 @@ import { createSceneCamera } from '../camera/createSceneCamera.js';
 import { initializeRendererResources } from './initializeRendererResources.js';
 import { mountRenderer } from './mountRenderer.js';
 
+/**
+ * Acquire a WebGPU device and initialize the shared scene, renderer and canvas.
+ *
+ * @param {L.Layer} layer Layer that owns the shared renderer.
+ * @param {L.Map} map Map receiving the renderer.
+ *
+ * @returns {Promise<void>} Resolves after the renderer is mounted.
+ */
 export async function initializeSharedRenderer(layer, map) {
   const canvas = document.createElement('canvas');
   if (!navigator.gpu) {

package/src/gpu/mountRenderer.js

@@ -1,10 +1,16 @@
 import { sizeByLayer } from '../weakmaps/sizeByLayer.js';
-
 import { onMapChange } from '../scene/onMapChange.js';
 import { startZoom } from '../animations/startZoom.js';
 import { onZoomAnim } from '../animations/onZoomAnim.js';
 import { endZoom } from '../animations/endZoom.js';
 
+/**
+ * Insert the rendering canvas and subscribe the layer to map and zoom events.
+ *
+ * @param {L.Layer} layer Layer receiving map events.
+ * @param {L.Map} map Map receiving the canvas.
+ * @param {HTMLCanvasElement} canvas WebGPU rendering canvas.
+ */
 export function mountRenderer(layer, map, canvas) {
   sizeByLayer.set(layer, null);
   canvas.className = 'leaflet-3d';

package/src/gpu/releaseRenderer.js

@@ -1,3 +1,11 @@
+/**
+ * Wait for submitted GPU work, release renderer resources and destroy the device.
+ *
+ * @param {Object} renderer Renderer whose resources are released.
+ * @param {L.Layer} layer Layer notified if resource cleanup fails.
+ *
+ * @returns {Promise<void>} Resolves after device destruction.
+ */
 export async function releaseRenderer(renderer, layer) {
   try {
     await renderer.device.queue.onSubmittedWorkDone();

package/src/gpu/rendererDeviceError.js

@@ -1,11 +1,13 @@
 import { layersByLayer } from '../weakmaps/layersByLayer.js';
 import { rendererByLayer } from '../weakmaps/rendererByLayer.js';
-
 import { rendererDevices } from '../weakmaps/rendererDevices.js';
 import { renderers } from '../weakmaps/renderers.js';
 
-
-
+/**
+ * Forward an uncaptured GPU error to layers using the current renderer.
+ *
+ * @param {GPUUncapturedErrorEvent} event Device error event.
+ */
 export function rendererDeviceError(event) {
   const map = rendererDevices.get(event.currentTarget);
   const owner = renderers.get(map);

package/src/gpu/rendererDeviceLost.js

@@ -1,11 +1,13 @@
 import { layersByLayer } from '../weakmaps/layersByLayer.js';
 import { rendererByLayer } from '../weakmaps/rendererByLayer.js';
-
 import { rendererDevices } from '../weakmaps/rendererDevices.js';
 import { renderers } from '../weakmaps/renderers.js';
 
-
-
+/**
+ * Report device loss to layers using the affected current renderer.
+ *
+ * @param {Array} result Device-lost information followed by the device.
+ */
 export function rendererDeviceLost([info, device]) {
   const map = rendererDevices.get(device);
   const owner = renderers.get(map);

package/src/gpu/reportShaderCompilation.js

@@ -1,3 +1,11 @@
+/**
+ * Report shader compilation errors or rejected compilation-info requests to the layer.
+ *
+ * @param {L.Layer} layer Layer receiving error events.
+ * @param {Promise[]} pending Compilation-info promises.
+ *
+ * @returns {Promise<void>} Resolves after reporting the results.
+ */
 export async function reportCompilation(layer, pending) {
   let info, message;
   try {

package/src/gpu/requestAdapter.js

@@ -1,5 +1,13 @@
 import { failAttachment } from '../scene/failAttachment.js';
 
+/**
+ * Request a WebGPU adapter and fail the layer attachment if it is unavailable.
+ *
+ * @param {L.Layer} layer Layer being attached.
+ * @param {L.Map} map Map receiving the layer.
+ *
+ * @returns {Promise<GPUAdapter>} The acquired adapter.
+ */
 export async function requestAdapter(layer, map) {
   let adapter;
   try {

package/src/gpu/requestDevice.js

@@ -1,5 +1,14 @@
 import { failAttachment } from '../scene/failAttachment.js';
 
+/**
+ * Request a device from an adapter and fail the layer attachment on rejection.
+ *
+ * @param {GPUAdapter} adapter Adapter providing the device.
+ * @param {L.Layer} layer Layer being attached.
+ * @param {L.Map} map Map receiving the layer.
+ *
+ * @returns {Promise<GPUDevice>} The acquired device.
+ */
 export async function requestDevice(adapter, layer, map) {
   try {
     return await adapter.requestDevice();

package/src/gpu/showWebGPUWarning.js

@@ -1,3 +1,8 @@
+/**
+ * Show a single accessible WebGPU-unavailable warning in the map container.
+ *
+ * @param {L.Map} map Map receiving the warning.
+ */
 export function showWebGPUWarning(map) {
   const container = map.getContainer();
   if (container.querySelector('.leaflet-webgpu-warning')) return;

package/src/index.js

@@ -1,11 +1,9 @@
 import { L } from './globals/L.js';
 import { layerProto } from './globals/layerProto.js';
 import { removeLayer as sharedRemoveLayer } from './globals/removeLayer.js';
-
 import './camera/mapCamera.js';
 import './sunlight/initSunlight.js';
 import './walk/initWalk.js';
-
 import { layerLayerAdd } from './scene/addRegisteredLayer.js';
 import { layerInitialize } from './scene/layerInitialize.js';
 import { removeLayer } from './core/removeLayer.js';

package/src/layer-controls/README.md

@@ -0,0 +1,25 @@
+# Layer controls
+
+[Source guide](../README.md) | [Project README](../../README.md)
+
+Manages layer control entry placement and loading or feature-count status.
+
+## Status follows the layer
+
+```mermaid
+flowchart LR
+  Progress["Progress event / source areas"] --> Count["Loaded + pending + errors"]
+  Count --> Status["Render layer status"]
+  Layer["Layer added"] --> Entry["Place status under control entry"]
+  Entry --> Changes["Reposition on layer changes"]
+  Changes --> Remove["Remove listener when layer leaves"]
+```
+
+Status reflects source progress, not GPU frame completion. Placement may fail
+when no layers control lists the layer; loading must remain independent of it.
+
+- [placeEntry.js](./placeEntry.js): place a layer entry.
+- [updateLayerCount.js](./updateLayerCount.js): update its status.
+- [renderLayerCount.js](./renderLayerCount.js): render loading and count information.
+
+Related: [scene](../scene/README.md), [sources](../sources/README.md).

package/src/layer-controls/layerControlInputId.js

@@ -4,6 +4,13 @@ import { layerControlAddItem } from '../globals/layerControlAddItem.js';
 // Leaflet 2 stores layer associations on its control, not on the input.
 if (layerControlAddItem && !L.Control.Layers) L.LayersControl.prototype._addItem = addLayerControlInputId;
 
+/**
+ * Add a layer-control item and attach its layer identifier to the selector.
+ *
+ * @param {Object} entry Layer-control entry.
+ *
+ * @returns {HTMLElement} The created label.
+ */
 export function addLayerControlInputId(entry) {
   const label = layerControlAddItem.call(this, entry);
   label.querySelector('.leaflet-control-layers-selector').layerId = L.Util.stamp(entry.layer);

package/src/layer-controls/layerCountTitle.js

@@ -1,5 +1,15 @@
 import { modelUrlByLayer } from '../weakmaps/modelUrlByLayer.js';
 
+/**
+ * Format a loading error or a count description for a layer-control status.
+ *
+ * @param {L.Layer} layer Layer whose status is described.
+ * @param {string} formatted Formatted loaded count.
+ * @param {number} pending Number of blocks still loading.
+ * @param {Error|string} [error] Loading error, if any.
+ *
+ * @returns {string} Status title.
+ */
 export function layerCountTitle(layer, formatted, pending, error) {
   return error ? `Unable to load: ${typeof error === 'string' ? error : error.message}` :
     `${formatted} loaded ${modelUrlByLayer.get(layer) ? 'models' : 'elements'} in the current area${pending ? `; ${pending} blocks loading` : ''}`;

package/src/layer-controls/placeEntry.js

@@ -2,6 +2,15 @@ import { L } from '../globals/L.js';
 import { placeEntryElement } from './placeEntryElement.js';
 import './layerControlInputId.js';
 
+/**
+ * Find a layers-control entry containing the layer and place an element beside it.
+ *
+ * @param {L.Map} map Map containing the layers control.
+ * @param {L.Layer} layer Layer to locate.
+ * @param {HTMLElement} element Element to place.
+ *
+ * @returns {boolean} Whether a matching entry was found.
+ */
 export function placeEntry(map, layer, element) {
   let input, entry;
   for (input of map.getContainer().querySelectorAll('.leaflet-control-layers-selector')) {

package/src/layer-controls/placeEntryElement.js

@@ -1,5 +1,12 @@
 import { L } from '../globals/L.js';
 
+/**
+ * Place a count, traffic status or other element next to a layer selector.
+ *
+ * @param {HTMLInputElement} input Layers-control selector.
+ * @param {L.Layer} layer Layer associated with the selector.
+ * @param {HTMLElement} element Element to place.
+ */
 export function placeEntryElement(input, layer, element) {
   const label = input.closest('label');
   if (element.classList.contains('layer-count')) {