isard 1.10.0 → 1.11.0

package/dist/map/quality.js

@@ -0,0 +1,61 @@
+/**
+ * The map's quality: what it draws less of on a device that cannot keep up. Each level a ceiling on the pixels drawn
+ * (the device's pixel ratio capped: a high-density screen draws four times the pixels of its CSS size), the sun's
+ * shadows (the solid scene drawn twice more for them: the sun's map, the camera's depth) and how far the 3D Tiles are
+ * refined (their screen-space error multiplied: fewer, coarser tiles far away). 'auto' starts high and steps down
+ * when the frames stay slow while the map moves.
+ */
+export const QUALITY = {
+    high: { pixelRatio: Number.POSITIVE_INFINITY, shadows: true, errorScale: 1 },
+    medium: { pixelRatio: 1.5, shadows: true, errorScale: 1.5 },
+    low: { pixelRatio: 1, shadows: false, errorScale: 2.5 },
+};
+/** The level under each, for 'auto' */
+const LOWER = { high: 'medium', medium: 'low', low: undefined };
+/** A move measured before it is judged: `WINDOW` frames, or `WINDOW_MS` of them on a slow device (at least
+ * `MIN_FRAMES`); a gap past `GAP_MS` between two frames is no move (the map was still) */
+const WINDOW = 60;
+const WINDOW_MS = 2000;
+const MIN_FRAMES = 10;
+const GAP_MS = 500;
+/** The median interval between the frames of a move past which the map steps down (some 40 frames a second) */
+const SLOW_MS = 25;
+/** After a step down, the time the new level is given before it is judged */
+const SETTLE_MS = 3000;
+/**
+ * 'auto': the intervals between the frames drawn while the map moves; once a window of them (`WINDOW`) has a median
+ * past `SLOW_MS`, `step` is called with the level under the current one. It never steps up: at the display's rate a fast
+ * frame tells nothing of what a finer level would cost
+ */
+export class QualityWatch {
+    level;
+    step;
+    intervals = [];
+    last = 0;
+    settled = 0;
+    constructor(level, step) {
+        this.level = level;
+        this.step = step;
+    }
+    /** A frame drawn at `now` (ms), the map moving or not */
+    frame(now, moving) {
+        const gap = now - this.last;
+        this.last = now;
+        if (!moving || gap > GAP_MS || now < this.settled)
+            return;
+        this.intervals.push(gap);
+        const spent = this.intervals.reduce((sum, i) => sum + i, 0);
+        if (this.intervals.length < WINDOW && (spent < WINDOW_MS || this.intervals.length < MIN_FRAMES))
+            return;
+        const sorted = [...this.intervals].sort((a, b) => a - b);
+        const median = sorted[Math.floor(sorted.length / 2)] ?? 0;
+        const lower = LOWER[this.level];
+        this.intervals.length = 0;
+        if (median <= SLOW_MS || !lower)
+            return;
+        this.level = lower;
+        this.settled = now + SETTLE_MS;
+        this.step(lower);
+    }
+}
+//# sourceMappingURL=quality.js.map

package/dist/map/quality.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"quality.js","sourceRoot":"","sources":["../../src/map/quality.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAcH,MAAM,CAAC,MAAM,OAAO,GAA+C;IACjE,IAAI,EAAE,EAAE,UAAU,EAAE,MAAM,CAAC,iBAAiB,EAAE,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,CAAC,EAAE;IAC5E,MAAM,EAAE,EAAE,UAAU,EAAE,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,GAAG,EAAE;IAC3D,GAAG,EAAE,EAAE,UAAU,EAAE,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,GAAG,EAAE;CACxD,CAAC;AAEF,uCAAuC;AACvC,MAAM,KAAK,GAAmD,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,EAAE,SAAS,EAAE,CAAC;AAEhH;0FAC0F;AAC1F,MAAM,MAAM,GAAG,EAAE,CAAC;AAClB,MAAM,SAAS,GAAG,IAAI,CAAC;AACvB,MAAM,UAAU,GAAG,EAAE,CAAC;AACtB,MAAM,MAAM,GAAG,GAAG,CAAC;AAEnB,+GAA+G;AAC/G,MAAM,OAAO,GAAG,EAAE,CAAC;AAEnB,6EAA6E;AAC7E,MAAM,SAAS,GAAG,IAAI,CAAC;AAEvB;;;;GAIG;AACH,MAAM,OAAO,YAAY;IAMb;IACS;IANF,SAAS,GAAa,EAAE,CAAC;IAClC,IAAI,GAAG,CAAC,CAAC;IACT,OAAO,GAAG,CAAC,CAAC;IAEpB,YACU,KAAc,EACL,IAA8B;QADvC,UAAK,GAAL,KAAK,CAAS;QACL,SAAI,GAAJ,IAAI,CAA0B;IAC9C,CAAC;IAEJ,yDAAyD;IACzD,KAAK,CAAC,GAAW,EAAE,MAAe;QAChC,MAAM,GAAG,GAAG,GAAG,GAAG,IAAI,CAAC,IAAI,CAAC;QAE5B,IAAI,CAAC,IAAI,GAAG,GAAG,CAAC;QAChB,IAAI,CAAC,MAAM,IAAI,GAAG,GAAG,MAAM,IAAI,GAAG,GAAG,IAAI,CAAC,OAAO;YAAE,OAAO;QAC1D,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAEzB,MAAM,KAAK,GAAG,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC,GAAG,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC;QAE5D,IAAI,IAAI,CAAC,SAAS,CAAC,MAAM,GAAG,MAAM,IAAI,CAAC,KAAK,GAAG,SAAS,IAAI,IAAI,CAAC,SAAS,CAAC,MAAM,GAAG,UAAU,CAAC;YAAE,OAAO;QAExG,MAAM,MAAM,GAAG,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;QACzD,MAAM,MAAM,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;QAC1D,MAAM,KAAK,GAAG,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAEhC,IAAI,CAAC,SAAS,CAAC,MAAM,GAAG,CAAC,CAAC;QAC1B,IAAI,MAAM,IAAI,OAAO,IAAI,CAAC,KAAK;YAAE,OAAO;QACxC,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;QACnB,IAAI,CAAC,OAAO,GAAG,GAAG,GAAG,SAAS,CAAC;QAC/B,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACnB,CAAC;CACF","sourcesContent":["/**\n * The map's quality: what it draws less of on a device that cannot keep up. Each level a ceiling on the pixels drawn\n * (the device's pixel ratio capped: a high-density screen draws four times the pixels of its CSS size), the sun's\n * shadows (the solid scene drawn twice more for them: the sun's map, the camera's depth) and how far the 3D Tiles are\n * refined (their screen-space error multiplied: fewer, coarser tiles far away). 'auto' starts high and steps down\n * when the frames stay slow while the map moves.\n */\n\nimport type { Quality } from '../types.ts';\n\n/** What a level draws */\nexport interface QualitySettings {\n  /** The highest pixel ratio drawn */\n  pixelRatio: number;\n  /** The sun casts its shadows (its light and the night stay without) */\n  shadows: boolean;\n  /** Multiplies the 3D Tiles' screen-space error */\n  errorScale: number;\n}\n\nexport const QUALITY: Readonly<Record<Quality, QualitySettings>> = {\n  high: { pixelRatio: Number.POSITIVE_INFINITY, shadows: true, errorScale: 1 },\n  medium: { pixelRatio: 1.5, shadows: true, errorScale: 1.5 },\n  low: { pixelRatio: 1, shadows: false, errorScale: 2.5 },\n};\n\n/** The level under each, for 'auto' */\nconst LOWER: Readonly<Record<Quality, Quality | undefined>> = { high: 'medium', medium: 'low', low: undefined };\n\n/** A move measured before it is judged: `WINDOW` frames, or `WINDOW_MS` of them on a slow device (at least\n * `MIN_FRAMES`); a gap past `GAP_MS` between two frames is no move (the map was still) */\nconst WINDOW = 60;\nconst WINDOW_MS = 2000;\nconst MIN_FRAMES = 10;\nconst GAP_MS = 500;\n\n/** The median interval between the frames of a move past which the map steps down (some 40 frames a second) */\nconst SLOW_MS = 25;\n\n/** After a step down, the time the new level is given before it is judged */\nconst SETTLE_MS = 3000;\n\n/**\n * 'auto': the intervals between the frames drawn while the map moves; once a window of them (`WINDOW`) has a median\n * past `SLOW_MS`, `step` is called with the level under the current one. It never steps up: at the display's rate a fast\n * frame tells nothing of what a finer level would cost\n */\nexport class QualityWatch {\n  private readonly intervals: number[] = [];\n  private last = 0;\n  private settled = 0;\n\n  constructor(\n    private level: Quality,\n    private readonly step: (level: Quality) => void,\n  ) {}\n\n  /** A frame drawn at `now` (ms), the map moving or not */\n  frame(now: number, moving: boolean): void {\n    const gap = now - this.last;\n\n    this.last = now;\n    if (!moving || gap > GAP_MS || now < this.settled) return;\n    this.intervals.push(gap);\n\n    const spent = this.intervals.reduce((sum, i) => sum + i, 0);\n\n    if (this.intervals.length < WINDOW && (spent < WINDOW_MS || this.intervals.length < MIN_FRAMES)) return;\n\n    const sorted = [...this.intervals].sort((a, b) => a - b);\n    const median = sorted[Math.floor(sorted.length / 2)] ?? 0;\n    const lower = LOWER[this.level];\n\n    this.intervals.length = 0;\n    if (median <= SLOW_MS || !lower) return;\n    this.level = lower;\n    this.settled = now + SETTLE_MS;\n    this.step(lower);\n  }\n}\n"]}

package/dist/map.d.ts

@@ -26,7 +26,7 @@ import { Tiles3dLayer } from './layers/tiles3d.ts';
 import { type TreeOptions } from './layers/trees.ts';
 import { type HoverPicking } from './map/hover-pick.ts';
 import { type LayerSpec } from './map/layer-spec.ts';
-import type { AnimationOptions, AtmosphereOptions, Basemap, FeatureHit, FirstPersonView, FlyToOptions, GeoMapOptions, LoadingMode, LonLat, MapEvents, NetworkOptions, PickOptions, Point, Projection, RasterOptions, SunOptions, SwipeOptions, TerrainModel, TerrainOptions, Tiles3dOptions, ViewshedOptions } from './types.ts';
+import type { AnimationOptions, AtmosphereOptions, Basemap, FeatureHit, FirstPersonView, FlyToOptions, GeoMapOptions, LoadingMode, LonLat, MapEvents, NetworkOptions, PickOptions, Point, Projection, Quality, RasterOptions, SunOptions, SwipeOptions, TerrainModel, TerrainOptions, Tiles3dOptions, ViewshedOptions } from './types.ts';
 import { type Control, type ControlPosition } from './ui/controls.ts';
 import type { Camera, PickHit, RasterLayerStats } from './wasm/isard.js';
 export type { LayerSpec } from './map/layer-spec.ts';
@@ -119,8 +119,19 @@ export declare class GeoMap {
     setSwipe(options: SwipeOptions | undefined): void;
     private applySwipe;
     private addLayer;
+    /** Whether the canvas's WebGL context is lost, its event come or not */
+    private contextLost;
     /** Listens to an event; returns the function that stops listening */
     on<K extends keyof MapEvents>(type: K, listener: (event: MapEvents[K]) => void): () => void;
+    /** 'auto': the frames watched, the map stepped down while they stay slow */
+    private qualityWatch;
+    private movingNow;
+    /** The map's quality: `'high'`, `'medium'` or `'low'` (as `GeoMapOptions.quality` says; `'auto'` the level it
+     * stepped down to) */
+    getQuality(): Quality;
+    /** Sets the map's quality (`GeoMapOptions.quality`); `'auto'` starts again from `'high'` */
+    setQuality(quality: Quality | 'auto'): void;
+    private applyQuality;
     getCamera(): Camera;
     setCamera(camera: Partial<Camera>): void;
     /** Animated move to a camera: over `duration` milliseconds (or the options), ease-out by default */

package/dist/map.js

@@ -39,6 +39,7 @@ import { addSpec } from "./map/layer-spec.js";
 import { LayerStack } from "./map/layer-stack.js";
 import { OverlayHost } from "./map/overlay-host.js";
 import { panoramaHost } from "./map/panorama-host.js";
+import { QUALITY, QualityWatch } from "./map/quality.js";
 import { rasterSource } from "./map/raster-source.js";
 import { SymbolAtlases } from "./map/symbol-atlases.js";
 import { applyViewshed } from "./map/viewshed.js";
@@ -158,6 +159,7 @@ export class GeoMap {
             upgrading: () => this.engines.upgrading !== undefined,
             working: () => this.#working > 0,
             drawn: (hovered) => {
+                this.qualityWatch?.frame(performance.now(), this.movingNow);
                 // The picking pass sees the frame just drawn; its answer comes on a later frame
                 if (hovered && this.listeners.has('hoverfeature'))
                     this.hoverPick.request(hovered, this.hoverPicking);
@@ -181,6 +183,17 @@ export class GeoMap {
             this.setSun(options.sun);
         this.resizeObserver = new ResizeObserver(() => this.resize());
         this.resizeObserver.observe(container);
+        this.#quality = options.quality === 'auto' || options.quality === undefined ? 'high' : options.quality;
+        if (options.quality === 'auto') {
+            this.qualityWatch = new QualityWatch('high', (level) => this.applyQuality(level));
+            // The frames measured are those of a move
+            this.on('movestart', () => {
+                this.movingNow = true;
+            });
+            this.on('moveend', () => {
+                this.movingNow = false;
+            });
+        }
         this.unwatchRatio = watchPixelRatio(() => this.resize());
         this.resize();
         const interactive = options.interactive ?? true;
@@ -345,13 +358,26 @@ export class GeoMap {
         // others on it
         if (layer.needsFullEngine && !this.engines.tiles3d)
             this.upgrade();
-        else
-            layer.attach(this.engine);
+        else {
+            try {
+                layer.attach(this.engine);
+            }
+            catch (error) {
+                // A context lost before the browser says so (its event comes later): nothing could be made on it, the layer is
+                // made with the others on the next engine (`restore`). Any other failure is the caller's
+                if (!this.contextLost())
+                    throw error;
+            }
+        }
         // Under the layers kept on top (the basemap's labels)
         this.stack.add(layer);
         this.requestRender();
         return layer;
     }
+    /** Whether the canvas's WebGL context is lost, its event come or not */
+    contextLost() {
+        return this.lost || this.canvas.getContext('webgl2')?.isContextLost() === true;
+    }
     /** @internal Keeps a layer above the layers added after it (they go under it), as the labels of a basemap */
     keepOnTop(layer) {
         this.onTop.add(layer);
@@ -375,6 +401,38 @@ export class GeoMap {
         this.listeners.emit(type, event);
     }
     // ── Camera ──
+    #quality = 'high';
+    /** 'auto': the frames watched, the map stepped down while they stay slow */
+    qualityWatch;
+    movingNow = false;
+    /** The map's quality: `'high'`, `'medium'` or `'low'` (as `GeoMapOptions.quality` says; `'auto'` the level it
+     * stepped down to) */
+    getQuality() {
+        return this.#quality;
+    }
+    /** @internal What its quality draws */
+    get quality() {
+        return QUALITY[this.#quality];
+    }
+    /** Sets the map's quality (`GeoMapOptions.quality`); `'auto'` starts again from `'high'` */
+    setQuality(quality) {
+        this.qualityWatch = quality === 'auto' ? new QualityWatch('high', (level) => this.applyQuality(level)) : undefined;
+        this.applyQuality(quality === 'auto' ? 'high' : quality);
+    }
+    applyQuality(quality) {
+        if (quality === this.#quality)
+            return;
+        this.#quality = quality;
+        // The canvas at its pixel ratio, the sun's shadows, the layers' detail
+        this.resize();
+        if (this.sun)
+            this.setSun(this.sun);
+        this.layers.forEach((layer) => {
+            layer.qualityChanged();
+        });
+        this.emit('quality', { quality });
+        this.requestRender();
+    }
     getCamera() {
         return this.frames.camera ?? this.engine.camera();
     }
@@ -473,8 +531,8 @@ export class GeoMap {
         // The twilight: from 6° above the horizon to 6° under it, smoothly
         const dusk = Math.min(1, Math.max(0, (6 - altitude) / 12));
         const night = Math.min(1, Math.max(0, options.night ?? dusk * dusk * (3 - 2 * dusk)));
-        // The shadows fade with the sun's light
-        const opacity = Math.min(1, Math.max(0, options.opacity ?? 0.35)) * (1 - night);
+        // The shadows fade with the sun's light; none at a low quality (its light and the night stay)
+        const opacity = this.quality.shadows ? Math.min(1, Math.max(0, options.opacity ?? 0.35)) * (1 - night) : 0;
         this.engine.setSun(azimuth, altitude, opacity, night);
         this.requestRender();
     }
@@ -728,7 +786,7 @@ export class GeoMap {
     }
     /** Lines from GeoJSON (line strings, and polygon outlines), styled per feature */
     addLines(options) {
-        return this.place(new LineLayer(this, options.data, lineStyle(options)), options.before);
+        return this.place(new LineLayer(this, options.data, lineStyle(options), options.altitudeReference), options.before);
     }
     /** Discs from GeoJSON points, styled per feature */
     addCircles(options) {
@@ -888,7 +946,7 @@ export class GeoMap {
         if (this.lost)
             return;
         const { clientWidth: width, clientHeight: height } = this.canvas;
-        const ratio = window.devicePixelRatio || 1;
+        const ratio = Math.min(window.devicePixelRatio || 1, this.quality.pixelRatio);
         this.canvas.width = Math.round(width * ratio);
         this.canvas.height = Math.round(height * ratio);
         this.engine.resize(width, height, ratio);