leaflet-city-mapper 0.0.8 → 0.1.0

package/src/sources/extrusionStyle.js

@@ -1,3 +1,14 @@
+/**
+ * Evaluate and validate a feature's extrusion style.
+ *
+ * @param {L.Layer} layer Source layer with a style function.
+ * @param {Object} feature GeoJSON feature.
+ *
+ * @returns {Object|null} Valid style, or null to skip the feature.
+ *
+ * @throws {Error} If the style is neither an object nor null.
+ * @throws {Error} If extrusion heights do not satisfy top > bottom >= 0.
+ */
 export function extrusionStyle(layer, feature) {
   const style = layer.options.style(feature);
   if (style === null) return null;

package/src/sources/featureAnchor.js

@@ -1,3 +1,15 @@
+/**
+ * Return the point or first polygon coordinate used to assign a feature to an area.
+ *
+ * @param {Object} feature GeoJSON feature.
+ * @param {boolean} nightLight Whether point geometry is required for a night light.
+ *
+ * @returns {Array<number>} Anchor coordinates in longitude, latitude order.
+ *
+ * @throws {Error} If a night-light feature is not a point.
+ * @throws {Error} If the geometry type is unsupported.
+ * @throws {Error} If anchor coordinates are not finite.
+ */
 export function featureAnchor(feature, nightLight) {
   const geometry = feature?.geometry, point = geometry?.type === 'Point';
   if (nightLight && !point) throw /* alloc */ new Error('Night lights require Point geometry');

package/src/sources/groundOffset.js

@@ -1,3 +1,10 @@
+/**
+ * Read the projected point's ground offset, defaulting to zero.
+ *
+ * @param {Object} point Projected point.
+ *
+ * @returns {number} Ground offset.
+ */
 export function groundOffset(point) {
   return point.ground || 0;
 }

package/src/sources/initVectorTiles.js

@@ -5,6 +5,12 @@ import { readyVectorTiles } from './readyVectorTiles.js';
 import { reportError } from '../raster/reportRasterError.js';
 import { noOperation } from '../utils/noOperation.js';
 
+/**
+ * Configure a vector tile layer asynchronously and report initialization errors.
+ *
+ * @param {L.Layer} layer Layer to initialize.
+ * @param {Object} options Vector tile configuration.
+ */
 export function initVectorTiles(layer, options) {
   kindByLayer.set(layer, 'pending');
   const ready = configureVectorTileLayer(layer, options)

package/src/sources/initializeGeoJSON.js

@@ -1,10 +1,13 @@
 import { geojsonByLayer } from '../weakmaps/geojsonByLayer.js';
-
-
-
 import { setGeoJSONLayerData } from './setGeoJSONLayerData.js';
 import { init3D } from '../scene/init3D.js';
 
+/**
+ * Mark a layer as GeoJSON-backed and initialize its 3D scene.
+ *
+ * @param {L.Layer} layer Layer to initialize.
+ * @param {Object} options Layer options.
+ */
 export function initializeGeoJSON(layer, options) {
   geojsonByLayer.set(layer, true);
   init3D(layer, options);

package/src/sources/isVectorTileSource.js

@@ -1,3 +1,10 @@
+/**
+ * Detect a tileJSON or templated tile URL when inline data is absent.
+ *
+ * @param {Object} options Source options.
+ *
+ * @returns {boolean} Whether the options identify a vector tile source.
+ */
 export function isVectorTileSource(options) {
   return options.data === undefined && (options.tileJSON !== undefined ||
     typeof options.url === 'string' && /\{[zxy]\}|%7B[zxy]%7D/i.test(options.url));

package/src/sources/matchesAreaTile.js

@@ -1,5 +1,15 @@
 import { L } from '../globals/L.js';
 
+/**
+ * Check whether an anchor belongs to the given area tile.
+ *
+ * @param {L.Map} map Map used to project the anchor.
+ * @param {Object} coords Tile coordinates, if the area is tiled.
+ * @param {number} lon Anchor longitude.
+ * @param {number} lat Anchor latitude.
+ *
+ * @returns {boolean} Whether the anchor belongs to the area.
+ */
 export function matchesAreaTile(map, coords, lon, lat) {
   if (!coords) return true;
   const anchor = map.project(/* alloc */ new L.LatLng(lat, lon), coords.z);

package/src/sources/pendingSourceAreas.js

@@ -1,7 +1,14 @@
-import { areasByLayer } from '../weakmaps/areasByLayer.js';
-
+import { areasByLayer } from '../weakmaps/areasByLayer.js';
 import { compareDistance } from '../utils/compareDistance.js';
 
+/**
+ * Gather unstarted, unaborted source areas in order of distance from the map center.
+ *
+ * @param {Array<L.Layer>} layers Source layers.
+ * @param {L.Map} map Map providing the view center and projection.
+ *
+ * @returns {Array<Object>} Pending layer and area entries with distances.
+ */
 export function pendingSourceAreas(layers, map) {
   const pending = /* alloc */ [];
   let layer, area, center;

package/src/sources/prepareAreaGeometryJob.js

@@ -2,6 +2,16 @@ import { projectedTree } from '../projections/projectTreePoint.js';
 import { parseColor } from '../colors/parseColor.js';
 import { projectAreaPolygons } from './projectAreaPolygons.js';
 
+/**
+ * Queue projected feature geometry and resolved style values for the geometry worker.
+ *
+ * @param {Object} context Area build context and job queue.
+ * @param {Object} feature GeoJSON feature.
+ * @param {number} lon Anchor longitude.
+ * @param {number} lat Anchor latitude.
+ * @param {Object} style Validated extrusion style.
+ * @param {Object} baseColor Parsed feature color.
+ */
 export function prepareAreaGeometryJob(context, feature, lon, lat, style, baseColor) {
   const geometry = feature.geometry;
   const polygons = projectAreaPolygons(context, geometry);

package/src/sources/projectAreaPolygons.js

@@ -1,5 +1,15 @@
 import { projectRing } from '../projections/projectRing.js';
 
+/**
+ * Project every ring of a polygon or multipolygon into the area coordinate system.
+ *
+ * @param {Object} context Area projection context.
+ * @param {Object} geometry GeoJSON geometry.
+ *
+ * @returns {Array} Projected polygons, or an empty array for other geometry types.
+ *
+ * @throws {Error} If a polygon contains no rings.
+ */
 export function projectAreaPolygons(context, geometry) {
   const rings = geometry.type === 'Polygon' ? /* alloc */ [geometry.coordinates]
     : geometry.type === 'MultiPolygon' ? geometry.coordinates : /* alloc */ [];

package/src/sources/pumpSourceAreas.js

@@ -3,17 +3,17 @@ import { geojsonByLayer } from '../weakmaps/geojsonByLayer.js';
 import { inflightByLayer } from '../weakmaps/inflightByLayer.js';
 import { layersByLayer } from '../weakmaps/layersByLayer.js';
 import { urlByLayer } from '../weakmaps/urlByLayer.js';
-
 import { renderers } from '../weakmaps/renderers.js';
-
-
-
 import { updateStatus } from './updateSourceStatus.js';
-
 import { buildArea } from './buildArea.js';
 import { pendingSourceAreas } from './pendingSourceAreas.js';
 
-/** Share four load/build slots across source layers, nearest ground blocks first. */
+/**
+ * Share four load/build slots across source layers, nearest ground blocks first.
+ *
+ * @param {L.Layer} layer Layer used to find the shared renderer.
+ * @param {L.Map} [map] Map containing the source layers.
+ */
 export function pump(layer, map = layer._map) {
   const shared = map && renderers.get(map);
   if (!shared || !layersByLayer.has(shared)) return;

package/src/sources/readyVectorTiles.js

@@ -1,5 +1,12 @@
 import { kindByLayer } from '../weakmaps/kindByLayer.js';
 
+/**
+ * Reattach a configured vector tile layer and emit its ready event.
+ *
+ * @param {L.Layer} layer Configured layer.
+ *
+ * @returns {L.Layer} The layer.
+ */
 export function readyVectorTiles(layer) {
   const map = layer._map;
   map?.removeLayer(layer);

package/src/sources/releaseArea.js

@@ -1,14 +1,16 @@
 import { highlightedFeatureByLayer } from '../weakmaps/highlightedFeatureByLayer.js';
 import { hoveredFeatureByLayer } from '../weakmaps/hoveredFeatureByLayer.js';
-
-
-
 import { setHighlight } from '../picking/setHighlight.js';
 import { showFeature } from '../picking/showFeature.js';
 import { setParent } from '../scene/setParent.js';
 import { update } from '../scene/scheduleSceneUpdate.js';
 
-/** Cancel pending work and dispose this block's GPU data, including any hover highlight. */
+/**
+ * Cancel pending work and dispose this block's GPU data, including any hover highlight.
+ *
+ * @param {L.Layer} layer Layer owning the area.
+ * @param {Object} area Area to release.
+ */
 export function releaseArea(layer, area) {
   area.request.abort();
   let attribute;

package/src/sources/setGeoJSONData.js

@@ -1,10 +1,15 @@
 import { areasByLayer } from '../weakmaps/areasByLayer.js';
-
-
-
 import { releaseArea } from './releaseArea.js';
 import { updateArea } from './updateArea.js';
 
+/**
+ * Replace a layer's GeoJSON data, releasing old areas and scheduling a rebuild.
+ *
+ * @param {L.Layer} layer GeoJSON layer.
+ * @param {Object} data Replacement GeoJSON data.
+ *
+ * @returns {L.Layer} The updated layer.
+ */
 export function setGeoJSONData(layer, data) {
   layer.options.data = data;
   delete layer.options.url;

package/src/sources/setGeoJSONLayerData.js

@@ -1,5 +1,12 @@
 import { setGeoJSONData } from './setGeoJSONData.js';
 
+/**
+ * Replace this layer's GeoJSON data and rebuild its areas.
+ *
+ * @param {Object} data Replacement GeoJSON data.
+ *
+ * @returns {L.Layer} This layer.
+ */
 export function setGeoJSONLayerData(data) {
   return setGeoJSONData(this, data);
 }

package/src/sources/sourceAreaContext.js

@@ -1,8 +1,15 @@
 import { locationByLayer } from '../weakmaps/locationByLayer.js';
-
 import { radians } from '../globals/radians.js';
 
-
+/**
+ * Create the projection and job context for building a source area.
+ *
+ * @param {L.Layer} layer Source layer.
+ * @param {Object} area Area being built.
+ * @param {L.Map} map Map supplying the CRS.
+ *
+ * @returns {Object} Area build context.
+ */
 export function sourceAreaContext(layer, area, map) {
   const crs = map.options.crs, origin = crs.project(locationByLayer.get(layer));
   return /* alloc */ {

package/src/sources/updateArea.js

@@ -2,15 +2,15 @@ import { areasByLayer } from '../weakmaps/areasByLayer.js';
 import { geojsonByLayer } from '../weakmaps/geojsonByLayer.js';
 import { headerByLayer } from '../weakmaps/headerByLayer.js';
 import { sharedByLayer } from '../weakmaps/sharedByLayer.js';
-
-
-
 import { pump } from "./pumpSourceAreas.js";
 import { releaseArea } from './releaseArea.js';
 import { compareAreaDistance } from './compareAreaDistance.js';
 
-/** Cover the visible ground bounds and one bordering block, clipped to the archive. */
-
+/**
+ * Update source areas covering visible ground and one bordering block, clipped to the archive.
+ *
+ * @param {L.Layer} layer Source layer.
+ */
 export function updateArea(layer) {
   if (!layer._map || !sharedByLayer.get(layer)) return;
   if (geojsonByLayer.get(layer)) {

package/src/sources/updateSourceStatus.js

@@ -1,8 +1,11 @@
 import { areasByLayer } from '../weakmaps/areasByLayer.js';
 
-
-
-/** Emit a snapshot for consumers; ready does not wait for all neighborhood tasks. */
+/**
+ * Emit a source progress snapshot; ready does not wait for all neighborhood tasks.
+ *
+ * @param {L.Layer} layer Source layer.
+ * @param {boolean} [enabled] Enabled state to include in the snapshot.
+ */
 export function updateStatus(layer, enabled = true) {
   const progress = /* alloc */ { enabled, loaded: 0, skipped: 0, pending: 0, errors: /* alloc */ [] };
   let area;

package/src/sunlight/README.md

@@ -0,0 +1,28 @@
+# Sunlight and time controls
+
+[Source guide](../README.md) | [Project README](../../README.md)
+
+Integrates sunlight and a time control with Leaflet. Time and map position
+determine the sun, moon and sky state used by the scene.
+
+## Clock to scene
+
+```mermaid
+flowchart LR
+  Clock["Live / selected time"] --> Sun["updateSun"]
+  Center["Map center"] --> Sun
+  Sun --> Position["Solar + lunar positions"]
+  Position --> Sky["Sky + scene sunlight"]
+  Sky --> Render["Request render"]
+  Sun --> Event["simulationtimechange"]
+  Event --> Traffic["Traffic clock"]
+```
+
+Astronomical calculations live in [astronomy](../astronomy/README.md);
+[shadows](../shadows/README.md) pause below the low-sun threshold.
+
+- [initSunlight.js](./initSunlight.js): install sunlight and time control integration.
+- [updateSun.js](./updateSun.js): update celestial positions and sky state.
+- [initializeTimeControl.js](./initializeTimeControl.js): set up the time control.
+
+Related: [astronomy](../astronomy/README.md), [lighting](../lighting/README.md), [shadows](../shadows/README.md).

package/src/sunlight/addTimeControlToMap.js

@@ -1,7 +1,14 @@
-import { L } from '../globals/L.js';
+import { L } from '../globals/L.js';
 import { underEntry } from '../layer-controls/underEntry.js';
 import { styleTimeControl } from './styleTimeControl.js';
 
+/**
+ * Add the time control to a map and place it under its layer entry when available.
+ *
+ * @param {L.Map} map Map receiving the control.
+ *
+ * @returns {L.Control} The time control.
+ */
 export function addTo(map) {
   L.Control.prototype.addTo.call(this, map);
   const container = this.getContainer();

package/src/sunlight/addTimeLayer.js

@@ -1,7 +1,12 @@
-import { controlByLayer } from '../weakmaps/controlByLayer.js';
-
-
-
+import { controlByLayer } from '../weakmaps/controlByLayer.js';
+
+/**
+ * Add the control associated with this time layer to a map.
+ *
+ * @param {L.Map} map Map receiving the control.
+ *
+ * @returns {L.Control} The associated time control.
+ */
 export function addTimeLayer(map) {
   return controlByLayer.get(this).addTo(map);
 }

package/src/sunlight/atmosphere.js

@@ -1,10 +1,17 @@
 import { atmosphereStops } from '../globals/atmosphereStops.js';
 import { atmosphereColor } from '../globals/atmosphereColor.js';
-
 import { mix } from '../colors/mixColor.js';
 import { rgb } from '../colors/formatRGB.js';
 
-
+/**
+ * Interpolate sky background and light tint for a solar altitude.
+ *
+ * @param {number} altitude Solar altitude in degrees.
+ *
+ * @returns {Object} CSS background gradient and RGB tint.
+ *
+ * @throws {Error} If the altitude is not finite.
+ */
 export function atmosphere(altitude) {
   if (!Number.isFinite(altitude)) {
     throw /* alloc */ new Error('Invalid solar altitude');

package/src/sunlight/createSun.js

@@ -4,6 +4,13 @@ import { updateSun } from './updateSun.js';
 import { useLiveTime } from './useLiveTime.js';
 import { useSelectedTime } from './useSelectedTime.js';
 
+/**
+ * Create the time-control UI, celestial discs and bound update handlers.
+ *
+ * @param {L.Map} map Map associated with the control.
+ *
+ * @returns {Object} Sunlight and control state.
+ */
 export function createSun(map) {
   const disc = 'position:absolute;width:18px;height:18px;border-radius:50%;transform:translate(-50%,-50%);pointer-events:none;';
   const sunDisc = L.DomUtil.create('div', 'sunlight-sun');

package/src/sunlight/initSunlight.js

@@ -12,6 +12,11 @@ class TimeControl extends extendLeafletClass(L.Control) {
   static initHooks = true;
   static defaultOptions = { position: 'bottomright' };
 
+  /**
+   * Initialize the time control and its hooks explicitly when using Leaflet 2.
+   *
+   * @param {Object} options Time control options.
+   */
   constructor(options) {
     super(options);
     if (L.version.startsWith('2.')) {

package/src/sunlight/initializeTimeControl.js

@@ -1,12 +1,14 @@
-import { controlByLayer } from '../weakmaps/controlByLayer.js';
-import { kindByLayer } from '../weakmaps/kindByLayer.js';
-
-import { L } from '../globals/L.js';
-
-
+import { controlByLayer } from '../weakmaps/controlByLayer.js';
+import { kindByLayer } from '../weakmaps/kindByLayer.js';
+import { L } from '../globals/L.js';
 import { addTimeLayer } from './addTimeLayer.js';
 import { removeTimeLayer } from './removeTimeLayer.js';
 
+/**
+ * Apply time-control options and create its associated time layer.
+ *
+ * @param {Object} options Time control options.
+ */
 export function initialize(options) {
   L.Util.setOptions(this, options);
   this.live = true;

package/src/sunlight/onAddSun.js

@@ -1,10 +1,19 @@
-import { timeControlByMap } from '../weakmaps/timeControlByMap.js';
-
+import { timeControlByMap } from '../weakmaps/timeControlByMap.js';
 import { sunlightByControl } from '../weakmaps/sunlightByControl.js';
 import { sunByMap } from '../weakmaps/sunByMap.js';
 import { createSun } from './createSun.js';
 import { tickSun } from './tickSun.js';
 
+/**
+ * Attach sunlight state and update listeners for a time control.
+ *
+ * @param {L.Control} control Time control being added.
+ * @param {L.Map} map Map receiving the control.
+ *
+ * @returns {HTMLElement} Time-control container.
+ *
+ * @throws {Error} If another time control is already active on the map.
+ */
 export function onAddSun(control, map) {
   let state = sunByMap.get(map);
   if (state?.control && state.control !== control) {

package/src/sunlight/onAddTimeControl.js

@@ -1,5 +1,12 @@
 import { onAddSun } from './onAddSun.js';
 
+/**
+ * Attach this time control's sunlight state to the map.
+ *
+ * @param {L.Map} map Map receiving the control.
+ *
+ * @returns {HTMLElement} Time-control container.
+ */
 export function onAdd(map) {
   return onAddSun(this, map);
 }

package/src/sunlight/onRemoveSun.js

@@ -1,7 +1,7 @@
 import { sunlightByControl } from '../weakmaps/sunlightByControl.js';
-
 import { removeSun } from './removeSun.js';
 
+/** Remove the current time control's sunlight state and association. */
 export function onRemoveSun() {
   const sunlight = sunlightByControl.get(this);
   if (!sunlight) return;

package/src/sunlight/removeSun.js

@@ -1,12 +1,14 @@
-import { sunlightByMap } from '../weakmaps/sunlightByMap.js';
-import { timeControlByMap } from '../weakmaps/timeControlByMap.js';
-
+import { sunlightByMap } from '../weakmaps/sunlightByMap.js';
+import { timeControlByMap } from '../weakmaps/timeControlByMap.js';
 import { sunByMap } from '../weakmaps/sunByMap.js';
-
-
 import { render } from './requestSunlightRender.js';
 import { updateSky } from './updateSky.js';
 
+/**
+ * Remove sunlight listeners, celestial discs and map state, then redraw.
+ *
+ * @param {Object} state Sunlight and time-control state.
+ */
 export function removeSun(state) {
   const { map, timer, sunDisc, moonDisc } = state;
   const shared = sunByMap.get(map);

package/src/sunlight/removeTimeControl.js

@@ -1,4 +1,10 @@
-import { L } from '../globals/L.js';
+import { L } from '../globals/L.js';
+
+/**
+ * Remove the time layer if attached, otherwise remove this control directly.
+ *
+ * @returns {L.Control} The time control.
+ */
 export function remove() {
   if (this._map?.hasLayer(this.layer)) {
     this._map.removeLayer(this.layer);

package/src/sunlight/removeTimeLayer.js

@@ -1,8 +1,11 @@
-import { controlByLayer } from '../weakmaps/controlByLayer.js';
-
-import { L } from '../globals/L.js';
-
-
+import { controlByLayer } from '../weakmaps/controlByLayer.js';
+import { L } from '../globals/L.js';
+
+/**
+ * Remove the control associated with this time layer.
+ *
+ * @returns {L.Control} The associated time control.
+ */
 export function removeTimeLayer() {
   return L.Control.prototype.remove.call(controlByLayer.get(this));
 }

package/src/sunlight/requestSunlightRender.js

@@ -1,8 +1,11 @@
-import { renderers } from '../weakmaps/renderers.js';
-
-
+import { renderers } from '../weakmaps/renderers.js';
 import { update as updateScene } from '../scene/scheduleSceneUpdate.js';
 
+/**
+ * Schedule a scene update if the map has a shared renderer.
+ *
+ * @param {L.Map} map Map whose scene should update.
+ */
 export function render(map) {
   const renderer = renderers.get(map);
   if (renderer) updateScene(renderer);

package/src/sunlight/styleTimeControl.js

@@ -1,3 +1,9 @@
+/**
+ * Style the time-control container for nested or standalone placement.
+ *
+ * @param {HTMLElement} container Time-control container.
+ * @param {boolean} nested Whether it is placed beneath a layer entry.
+ */
 export function styleTimeControl(container, nested) {
   container.classList.toggle('leaflet-control', !nested);
   container.classList.toggle('leaflet-bar', !nested);

package/src/sunlight/tickSun.js

@@ -1,5 +1,10 @@
 import { updateSun } from './updateSun.js';
 
+/**
+ * Refresh sunlight on the timer only while the control uses live time.
+ *
+ * @param {Object} state Sunlight and time-control state.
+ */
 export function tickSun(state) {
   if (state.control.live) updateSun(state);
 }

package/src/sunlight/updateCelestialDisc.js

@@ -1,5 +1,16 @@
 import { projectCelestialBody } from '../projections/projectCelestialBody.js';
 
+/**
+ * Project and position a celestial disc, hiding it when it is below the horizon or outside the sky.
+ *
+ * @param {HTMLElement} disc Sun or moon element.
+ * @param {Object|null|undefined} body Celestial altitude and direction.
+ * @param {HTMLElement|null|undefined} sky Sky container.
+ * @param {L.Point} size Viewport dimensions.
+ * @param {number} pitch Camera pitch in radians.
+ * @param {number} bearing Camera bearing in radians.
+ * @param {Object} projection Reusable projection result.
+ */
 export function updateCelestialDisc(disc, body, sky, size, pitch, bearing, projection) {
   disc.hidden = true;
   if (!sky || !body || body.altitude <= 0) return;

package/src/sunlight/updateSky.js

@@ -1,13 +1,15 @@
 import { pitchSkyByMap } from '../weakmaps/pitchSkyByMap.js';
 import { sunlightByMap } from '../weakmaps/sunlightByMap.js';
-
 import { radians } from '../globals/radians.js';
-
 import { mapGetPitch } from '../camera/mapGetPitch.js';
 import { mapGetBearing } from '../camera/mapGetBearing.js';
-
 import { updateCelestialDisc } from './updateCelestialDisc.js';
 
+/**
+ * Update the map sky background and celestial disc positions.
+ *
+ * @param {Object} state Sunlight state containing the map, discs and projection scratch.
+ */
 export function updateSky({ map, originalSky, sunDisc, moonDisc, projection }) {
   const sun = sunlightByMap.get(map), sky = pitchSkyByMap.get(map);
   if (sun) map.getContainer().style.setProperty('--leaflet-sky-background', sun.background);

package/src/sunlight/updateSun.js

@@ -1,13 +1,15 @@
-import { sunlightByMap } from '../weakmaps/sunlightByMap.js';
-
-
-
+import { sunlightByMap } from '../weakmaps/sunlightByMap.js';
 import { atmosphere } from './atmosphere.js';
 import { moonPosition } from '../astronomy/moonPosition.js';
 import { solarPosition } from '../astronomy/solarPosition.js';
 import { render } from './requestSunlightRender.js';
 import { updateSky } from './updateSky.js';
 
+/**
+ * Update simulation time, solar and lunar positions, sky styling and status.
+ *
+ * @param {Object} state Sunlight and time-control state.
+ */
 export function updateSun(state) {
   const { control, map, date, slider, output, status } = state;
   try {

package/src/sunlight/useLiveTime.js

@@ -1,5 +1,10 @@
 import { updateSun } from './updateSun.js';
 
+/**
+ * Switch to live simulation time and refresh sunlight.
+ *
+ * @param {Object} state Sunlight and time-control state.
+ */
 export function useLiveTime(state) {
   state.control.live = true;
   updateSun(state);