@tellegen/svelte 0.5.1 → 0.5.2

package/README.md

@@ -260,6 +260,13 @@ besides its click callbacks:
 - `extraLayers`: deck.gl layers drawn after tellegen's own, in the same
   overlay.
 - `attribution`: `'compact'` (default) or `'full'`. There is no off switch.
+- `declutterMarkers`: default `true`. At low zoom the map draws one bus
+  marker per crowded spot, about 16 pixels across. It keeps a generator
+  before a substation before any other bus, as recorded in a grid made by
+  tellegen-synth, then the bus with the most generation and demand. Zooming
+  in shows the rest. The selected bus always draws, and every bus is still
+  in the case: the bus picker finds it and a line's tooltip names it.
+  `false` draws every marker at every zoom.
 - `onMapReady(map, overlay)`: called with the MapLibre map and the deck
   overlay once they exist. It may return a cleanup, and it fires again after
   a context-loss or basemap rebuild. If it throws, the map and its window

package/dist/TellegenMap.svelte

@@ -31,6 +31,7 @@
 		type MapTheme
 	} from './basemap.js';
 	import { caseDeltas, caseRatings, displayMetaFor, displaySeriesFor } from './display.js';
+	import { declutterBuses, declutterZoom, withBus } from './declutter.js';
 	import {
 		type CaseState,
 		type CameraSnapshot,
@@ -84,6 +85,7 @@
 		cartoApiKey,
 		extraLayers = [],
 		attribution = 'compact',
+		declutterMarkers = true,
 		onMapReady,
 		onBasemapFallback,
 		onBasemapError
@@ -125,6 +127,11 @@
 		/** Attribution control mode. There is no off switch: tile licences
 		 * require the credit on screen. */
 		attribution?: 'compact' | 'full';
+		/** At low zoom, draw one bus marker per crowded spot: a generator before
+		 * a substation before any other bus, then the larger bus. Zooming in
+		 * shows the rest, and a selected bus always draws. `false` draws every
+		 * marker at every zoom. */
+		declutterMarkers?: boolean;
 		/** Called once the map and overlay exist, with an optional cleanup. It
 		 * fires again after a context-loss or basemap remount, after the previous
 		 * cleanup ran. It runs before the first style loads, and a switch to the
@@ -232,6 +239,11 @@
 	let mapGen = $state(0);
 	// Cap automatic remounts so sustained GPU pressure cannot loop forever.
 	let glRebuilds = 0;
+	// The zoom the bus markers are thinned at, in quarter steps, so panning
+	// never thins them again. A zoom gesture reads it at most every
+	// MARKER_ZOOM_SAMPLE_MS, and the end of every zoom reads it at once.
+	let markerZoom = $state(declutterZoom(DEFAULT_CAMERA.zoom));
+	const MARKER_ZOOM_SAMPLE_MS = 150;
 
 	type LayerCtors = {
 		PathLayer: typeof PathLayer;
@@ -441,6 +453,52 @@
 		return primary ? attachmentColor(primary) : busNeutral;
 	}
 
+	// The buses each bus layer could draw at the current zoom: with
+	// `declutterMarkers`, one per crowded spot (see declutterBuses). A generated
+	// grid's line taps are left out before thinning, and its bus kinds rank the
+	// buses. Selection is not read here, so selecting a bus thins nothing again.
+	const thinnedMarkers = $derived.by(() => {
+		const zoom = markerZoom;
+		const thin = (buses: NetworkBus[], kinds?: ReadonlyMap<number, string>) =>
+			declutterMarkers ? declutterBuses(buses, { zoom, kinds }) : buses;
+		const sets = new Map<string, NetworkBus[]>();
+		if (app.studyView) {
+			sets.set('study-buses', thin(app.studyView.network.buses));
+			return sets;
+		}
+		for (const c of app.cases) if (c.network) sets.set(`buses-${c.id}`, thin(c.network.buses));
+		for (const c of app.localCases) {
+			if (c.view) sets.set(`local-buses-${c.id}`, thin(c.markerBuses, c.busKinds));
+		}
+		return sets;
+	});
+	// The data of each bus layer: its thinned buses, plus the selected bus when
+	// thinning (or a line tap's missing marker) left it out, so it keeps its
+	// marker and selection ring. The arrays keep their identity until the zoom
+	// bucket or the selection changes them, so deck.gl does not rebuild the
+	// layer's attributes on every redraw.
+	const busMarkers = $derived.by(() => {
+		const selected = app.selectedBus;
+		const sets = new Map<string, NetworkBus[]>();
+		const add = (id: string, all: NetworkBus[], pinned: number | null) => {
+			const shown = thinnedMarkers.get(id);
+			if (shown) sets.set(id, withBus(shown, all, pinned));
+		};
+		if (app.studyView) {
+			add('study-buses', app.studyView.network.buses, selected);
+			return sets;
+		}
+		for (const c of app.cases) {
+			if (c.network)
+				add(`buses-${c.id}`, c.network.buses, c.id === app.activeCaseId ? selected : null);
+		}
+		for (const c of app.localCases) {
+			if (c.view)
+				add(`local-buses-${c.id}`, c.view.buses, c.id === app.activeLocalId ? selected : null);
+		}
+		return sets;
+	});
+
 	// Layers whose click selects something (a bus or a branch); the overlay-level
 	// click handler must not treat those clicks as "empty map" and clear the selection.
 	function isSelectableLayer(layerId: string | undefined): boolean {
@@ -967,6 +1025,18 @@
 					if (document.visibilityState === 'visible') repaint();
 				};
 				const syncCues = () => scheduleCueSync();
+				let zoomTimer: ReturnType<typeof setTimeout> | null = null;
+				const readZoom = () => {
+					if (zoomTimer !== null) {
+						clearTimeout(zoomTimer);
+						zoomTimer = null;
+					}
+					markerZoom = declutterZoom(m.getZoom());
+				};
+				const sampleZoom = () => {
+					zoomTimer ??= setTimeout(readZoom, MARKER_ZOOM_SAMPLE_MS);
+				};
+				readZoom();
 				const saveCamera = () => {
 					const center = m.getCenter();
 					app.camera = {
@@ -1024,6 +1094,9 @@
 				m.on('load', syncCues);
 				m.on('move', syncCues);
 				m.on('resize', syncCues);
+				// 'zoom' does not fire while the camera only pans.
+				m.on('zoom', sampleZoom);
+				m.on('zoomend', readZoom);
 
 				map = m;
 				overlay = o;
@@ -1039,6 +1112,9 @@
 					m.off('load', syncCues);
 					m.off('move', syncCues);
 					m.off('resize', syncCues);
+					m.off('zoom', sampleZoom);
+					m.off('zoomend', readZoom);
+					if (zoomTimer !== null) clearTimeout(zoomTimer);
 					m.off('style.load', applyStyleExtras);
 					detachFallback();
 					detachReady?.();
@@ -1151,7 +1227,7 @@
 				}),
 				new ScatterplotLayer<NetworkBus>({
 					id: 'study-buses',
-					data: study.network.buses,
+					data: busMarkers.get('study-buses') ?? study.network.buses,
 					getPosition: (b) => [b.lon, b.lat],
 					getRadius: (b) => marker.radius(Math.max(b.demand_mw, b.gen_mw)),
 					radiusUnits: marker.radiusUnits,
@@ -1222,7 +1298,7 @@
 				}),
 				new ScatterplotLayer<NetworkBus>({
 					id: `buses-${c.id}`,
-					data: c.network.buses,
+					data: busMarkers.get(`buses-${c.id}`) ?? c.network.buses,
 					getPosition: (b) => [b.lon, b.lat],
 					getRadius: (b) => marker.radius(Math.max(b.demand_mw, b.gen_mw)),
 					radiusUnits: marker.radiusUnits,
@@ -1258,14 +1334,11 @@
 		// Local cases are grey until the browser solve returns. A .pwd display
 		// file contributes substation points only, in a cooler slate so they
 		// read as diagram derived positions. A generated grid's line taps draw
-		// no marker, as their lines show them, unless one is the selected bus.
+		// no marker, as their lines show them, unless one is the selected bus
+		// (see busMarkers).
 		for (const c of app.localCases) {
 			if (c.view) {
 				const d = display.get(c.id);
-				const selectedTap =
-					c.id === app.activeLocalId && app.selectedBus !== null && c.tapBuses.has(app.selectedBus)
-						? c.view.buses.find((b) => b.id === app.selectedBus)
-						: undefined;
 				layers.push(
 					new PathLayer<NetworkBranch>({
 						id: `local-branches-${c.id}`,
@@ -1305,7 +1378,7 @@
 					}),
 					new ScatterplotLayer<NetworkBus>({
 						id: `local-buses-${c.id}`,
-						data: selectedTap ? [...c.markerBuses, selectedTap] : c.markerBuses,
+						data: busMarkers.get(`local-buses-${c.id}`) ?? c.markerBuses,
 						getPosition: (b) => [b.lon, b.lat],
 						getRadius: (b) => marker.radius(Math.max(b.demand_mw, b.gen_mw)),
 						radiusUnits: marker.radiusUnits,

package/dist/TellegenMap.svelte.d.ts

@@ -42,6 +42,11 @@ type $$ComponentProps = {
     /** Attribution control mode. There is no off switch: tile licences
      * require the credit on screen. */
     attribution?: 'compact' | 'full';
+    /** At low zoom, draw one bus marker per crowded spot: a generator before
+     * a substation before any other bus, then the larger bus. Zooming in
+     * shows the rest, and a selected bus always draws. `false` draws every
+     * marker at every zoom. */
+    declutterMarkers?: boolean;
     /** Called once the map and overlay exist, with an optional cleanup. It
      * fires again after a context-loss or basemap remount, after the previous
      * cleanup ran. It runs before the first style loads, and a switch to the

package/dist/bus-kinds.d.ts

@@ -1,8 +1,14 @@
 import type { NetworkBus } from './api.js';
-/** Ids of the buses a generated grid marks as line taps: points where a line
- * is tapped, with no load or machine. tellegen-synth records the kind in
- * each bus row's `extras.tellegen_synth.kind`; the map view does not carry
+/** Each bus's kind as a generated grid records it, by bus id: `generator`,
+ * `substation`, `converter`, `load` or `tap`. tellegen-synth writes the kind
+ * in each bus row's `extras.tellegen_synth.kind`; the map view does not carry
  * it. Empty for any other module, and for text that does not parse. */
+export declare function readBusKinds(moduleJson: string | null | undefined): ReadonlyMap<number, string>;
+/** Ids of the buses in `kinds` that are line taps: points where a line is
+ * tapped, with no load or machine. */
+export declare function tapsOf(kinds: ReadonlyMap<number, string>): ReadonlySet<number>;
+/** Ids of the buses a generated grid marks as line taps. Empty for any other
+ * module, and for text that does not parse. */
 export declare function tapBusIds(moduleJson: string | null | undefined): ReadonlySet<number>;
 /** `buses` less the taps, the ones the map draws as markers. The same array
  * when there is no tap to drop, so the map layer keeps its data. */

package/dist/bus-kinds.js

@@ -1,31 +1,45 @@
 /** The `extras` key under which tellegen-synth records each element's
  * annotation in the modules it writes. */
 const SYNTH_EXTRAS = 'tellegen_synth';
-/** Ids of the buses a generated grid marks as line taps: points where a line
- * is tapped, with no load or machine. tellegen-synth records the kind in
- * each bus row's `extras.tellegen_synth.kind`; the map view does not carry
+/** Each bus's kind as a generated grid records it, by bus id: `generator`,
+ * `substation`, `converter`, `load` or `tap`. tellegen-synth writes the kind
+ * in each bus row's `extras.tellegen_synth.kind`; the map view does not carry
  * it. Empty for any other module, and for text that does not parse. */
-export function tapBusIds(moduleJson) {
-    const ids = new Set();
-    // Only a module tellegen-synth wrote is parsed a second time; a branch's
-    // `"tap"` ratio is in every transmission case.
-    if (!moduleJson?.includes(`"${SYNTH_EXTRAS}"`) || !moduleJson.includes('"tap"'))
-        return ids;
+export function readBusKinds(moduleJson) {
+    const kinds = new Map();
+    // Only a module tellegen-synth wrote is parsed a second time.
+    if (!moduleJson?.includes(`"${SYNTH_EXTRAS}"`))
+        return kinds;
     let buses;
     try {
         buses = JSON.parse(moduleJson)?.value?.data?.buses;
     }
     catch {
-        return ids;
+        return kinds;
     }
     if (!Array.isArray(buses))
-        return ids;
+        return kinds;
     for (const bus of buses) {
-        if (typeof bus?.id === 'number' && bus.extras?.[SYNTH_EXTRAS]?.kind === 'tap')
-            ids.add(bus.id);
+        const kind = bus?.extras?.[SYNTH_EXTRAS]?.kind;
+        if (typeof bus?.id === 'number' && typeof kind === 'string')
+            kinds.set(bus.id, kind);
     }
+    return kinds;
+}
+/** Ids of the buses in `kinds` that are line taps: points where a line is
+ * tapped, with no load or machine. */
+export function tapsOf(kinds) {
+    const ids = new Set();
+    for (const [id, kind] of kinds)
+        if (kind === 'tap')
+            ids.add(id);
     return ids;
 }
+/** Ids of the buses a generated grid marks as line taps. Empty for any other
+ * module, and for text that does not parse. */
+export function tapBusIds(moduleJson) {
+    return tapsOf(readBusKinds(moduleJson));
+}
 /** `buses` less the taps, the ones the map draws as markers. The same array
  * when there is no tap to drop, so the map layer keeps its data. */
 export function withoutTaps(buses, taps) {

package/dist/declutter.d.ts

@@ -0,0 +1,52 @@
+/** Bus fields the declutter reads. `NetworkBus` has all of them. */
+export interface DeclutterBus {
+    id: number;
+    lon: number;
+    lat: number;
+    demand_mw: number;
+    gen_mw: number;
+}
+export interface DeclutterOptions {
+    /** Map zoom the cells are laid out at. Pass a bucketed zoom
+     * (`declutterZoom`) so small camera moves keep the same result. */
+    zoom: number;
+    /** Cell side in CSS pixels. Each cell keeps one bus. */
+    cellPx?: number;
+    /** Bus kinds by id, as tellegen-synth records them (`generator`,
+     * `substation`, `converter`, `load`, `tap`). Without them, buses rank by
+     * power alone. */
+    kinds?: ReadonlyMap<number, string>;
+}
+/** Default cell side in CSS pixels: about twice the diameter of the marker
+ * for a bus of up to about 10 MW. */
+export declare const DECLUTTER_CELL_PX = 16;
+/** Zoom step the map lays its cells out at. */
+export declare const DECLUTTER_ZOOM_STEP = 0.25;
+/** `zoom` rounded down to a whole `step`, so panning and small zooms land on
+ * the same value and leave the thinned markers as they are. */
+export declare function declutterZoom(zoom: number, step?: number): number;
+/** How strongly a bus kind claims its cell: a generator before a substation
+ * or converter station, before anything else. */
+export declare function kindRank(kind: string | undefined): number;
+/** The buses a map at `zoom` draws markers for, so that a crowded grid does
+ * not cover the map. Each bus is placed in Web Mercator world pixels (at a
+ * MapLibre zoom the world is 512·2^zoom CSS pixels square) and binned into
+ * square cells of `cellPx`; each cell keeps its strongest bus. A generator
+ * outranks a substation or converter, which outranks any other bus. Then the
+ * larger |generation| + |demand| wins, then the lower id, so the result does
+ * not depend on the input order. The selection is not an input: `withBus`
+ * adds a selected bus back on top, so selecting one never hides another.
+ *
+ * The kept buses come back in input order. When no two buses share a cell,
+ * the input array itself comes back, so a map layer keeps its data. Longitudes
+ * wrap, so 190 and -170 share a cell, and the cells tile the world with ±180
+ * on a cell edge, so the seam thins like any other place. Latitudes clamp to
+ * the Mercator limit. A bus without finite coordinates is kept, as there is no
+ * cell to place it in. */
+export declare function declutterBuses<T extends DeclutterBus>(buses: T[], options: DeclutterOptions): T[];
+/** `shown` with bus `id` from `all` added at the end when it is missing, so a
+ * selected bus that the map thinned out, or a line tap it never draws, still
+ * gets its marker. `shown` itself when there is nothing to add. */
+export declare function withBus<T extends {
+    id: number;
+}>(shown: T[], all: readonly T[], id: number | null | undefined): T[];

package/dist/declutter.js

@@ -0,0 +1,95 @@
+/** Default cell side in CSS pixels: about twice the diameter of the marker
+ * for a bus of up to about 10 MW. */
+export const DECLUTTER_CELL_PX = 16;
+/** Zoom step the map lays its cells out at. */
+export const DECLUTTER_ZOOM_STEP = 0.25;
+// The Web Mercator world is this many CSS pixels across at zoom 0, as MapLibre
+// and deck.gl lay it out.
+const WORLD_PX = 512;
+// Web Mercator's latitude limit, where the square world ends.
+const MAX_LAT = 85.0511287798066;
+/** `zoom` rounded down to a whole `step`, so panning and small zooms land on
+ * the same value and leave the thinned markers as they are. */
+export function declutterZoom(zoom, step = DECLUTTER_ZOOM_STEP) {
+    // Snap first, so 4.75 / 0.25 does not land a hair under 19.
+    return Math.floor(Math.round((zoom / step) * 1e6) / 1e6) * step;
+}
+/** How strongly a bus kind claims its cell: a generator before a substation
+ * or converter station, before anything else. */
+export function kindRank(kind) {
+    if (kind === 'generator')
+        return 2;
+    if (kind === 'substation' || kind === 'converter')
+        return 1;
+    return 0;
+}
+function busPower(bus) {
+    const power = Math.abs(bus.gen_mw) + Math.abs(bus.demand_mw);
+    return Number.isFinite(power) ? power : 0;
+}
+/** The buses a map at `zoom` draws markers for, so that a crowded grid does
+ * not cover the map. Each bus is placed in Web Mercator world pixels (at a
+ * MapLibre zoom the world is 512·2^zoom CSS pixels square) and binned into
+ * square cells of `cellPx`; each cell keeps its strongest bus. A generator
+ * outranks a substation or converter, which outranks any other bus. Then the
+ * larger |generation| + |demand| wins, then the lower id, so the result does
+ * not depend on the input order. The selection is not an input: `withBus`
+ * adds a selected bus back on top, so selecting one never hides another.
+ *
+ * The kept buses come back in input order. When no two buses share a cell,
+ * the input array itself comes back, so a map layer keeps its data. Longitudes
+ * wrap, so 190 and -170 share a cell, and the cells tile the world with ±180
+ * on a cell edge, so the seam thins like any other place. Latitudes clamp to
+ * the Mercator limit. A bus without finite coordinates is kept, as there is no
+ * cell to place it in. */
+export function declutterBuses(buses, options) {
+    const { zoom, cellPx = DECLUTTER_CELL_PX, kinds } = options;
+    if (buses.length < 2 || !Number.isFinite(zoom) || !(cellPx > 0))
+        return buses;
+    const world = WORLD_PX * 2 ** zoom;
+    // A whole number of columns, so the cells tile the world without a sliver
+    // at the seam.
+    const columns = Math.max(1, Math.round(world / cellPx));
+    // Past about zoom 21 a 16 px cell is under a metre across, and its key
+    // would outgrow exact integers. Nothing needs thinning there.
+    if (!Number.isSafeInteger(columns * columns))
+        return buses;
+    const cell = world / columns;
+    const rank = (bus) => (kinds ? kindRank(kinds.get(bus.id)) : 0);
+    const outranks = (a, b) => {
+        const byKind = rank(a) - rank(b);
+        if (byKind !== 0)
+            return byKind > 0;
+        const byPower = busPower(a) - busPower(b);
+        if (byPower !== 0)
+            return byPower > 0;
+        return a.id < b.id;
+    };
+    const winners = new Map();
+    for (const bus of buses) {
+        const { lon, lat } = bus;
+        if (!Number.isFinite(lon) || !Number.isFinite(lat))
+            continue;
+        const x = ((((lon + 180) % 360) + 360) % 360) / 360;
+        const phi = (Math.max(-MAX_LAT, Math.min(MAX_LAT, lat)) * Math.PI) / 180;
+        const y = 0.5 - Math.log(Math.tan(Math.PI / 4 + phi / 2)) / (2 * Math.PI);
+        const column = Math.floor((x * world) / cell) % columns;
+        const row = Math.min(columns - 1, Math.max(0, Math.floor((y * world) / cell)));
+        const key = row * columns + column;
+        const held = winners.get(key);
+        if (!held || outranks(bus, held))
+            winners.set(key, bus);
+    }
+    const kept = new Set(winners.values());
+    const shown = buses.filter((bus) => kept.has(bus) || !Number.isFinite(bus.lon) || !Number.isFinite(bus.lat));
+    return shown.length === buses.length ? buses : shown;
+}
+/** `shown` with bus `id` from `all` added at the end when it is missing, so a
+ * selected bus that the map thinned out, or a line tap it never draws, still
+ * gets its marker. `shown` itself when there is nothing to add. */
+export function withBus(shown, all, id) {
+    if (id === null || id === undefined || shown.some((bus) => bus.id === id))
+        return shown;
+    const bus = all.find((b) => b.id === id);
+    return bus ? [...shown, bus] : shown;
+}

package/dist/state.svelte.d.ts

@@ -95,6 +95,10 @@ export declare class LocalCase {
     coordsKind: CoordsKind | undefined;
     /** Map geometry when the file carried or received coordinates. */
     view: LocalView | null;
+    /** Each bus's kind in a generated grid, by bus id (`generator`,
+     * `substation`, `converter`, `load`, `tap`); empty for any other case. At
+     * low zoom the map keeps generators and substations over other buses. */
+    readonly busKinds: ReadonlyMap<number, string>;
     /** Buses a generated grid marks as line taps. The map draws no marker for
      * them; the bus picker and the selection still reach them. */
     readonly tapBuses: ReadonlySet<number>;

package/dist/state.svelte.js

@@ -1,5 +1,5 @@
 import { DEFAULT_MC_PF_OPTIONS, summarizeMcExcludedIslands } from '@tellegen/engine';
-import { tapBusIds, withoutTaps } from './bus-kinds.js';
+import { readBusKinds, tapsOf, withoutTaps } from './bus-kinds.js';
 import { DEFAULT_FORMULATION } from '@tellegen/engine';
 import { DiagnosticLog, errorEntry } from './log.svelte.js';
 import { graphInputs } from './diagram/graph-inputs.js';
@@ -28,9 +28,13 @@ export class LocalCase {
     coordsKind = $state.raw(undefined);
     /** Map geometry when the file carried or received coordinates. */
     view = $state.raw(null);
+    /** Each bus's kind in a generated grid, by bus id (`generator`,
+     * `substation`, `converter`, `load`, `tap`); empty for any other case. At
+     * low zoom the map keeps generators and substations over other buses. */
+    busKinds = $derived(readBusKinds(this.studyInputJson));
     /** Buses a generated grid marks as line taps. The map draws no marker for
      * them; the bus picker and the selection still reach them. */
-    tapBuses = $derived(tapBusIds(this.studyInputJson));
+    tapBuses = $derived(tapsOf(this.busKinds));
     /** `view.buses` less the line taps: the buses the map draws as markers. */
     markerBuses = $derived(withoutTaps(this.view?.buses ?? [], this.tapBuses));
     syntheticCenter = $state.raw(undefined);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tellegen/svelte",
-  "version": "0.5.1",
+  "version": "0.5.2",
   "description": "Svelte components for tellegen power system maps, local case files, and browser solves.",
   "keywords": [
     "svelte",
@@ -67,7 +67,7 @@
     "pack:dry-run": "npm pack --dry-run --cache ../../node_modules/.cache/npm-pack"
   },
   "dependencies": {
-    "@tellegen/engine": "^0.5.1"
+    "@tellegen/engine": "^0.6.0"
   },
   "peerDependencies": {
     "@deck.gl/core": "^9.4.0",