isard 0.7.0 → 1.0.0

package/dist/map.js

@@ -5,17 +5,20 @@
  * the camera animations in animation.ts.
  */
 import { easeTo, flyTo } from "./animation.js";
-import { BASEMAPS, basemapName, HILLSHADE, SEA } from "./basemaps.js";
+import { BASEMAPS, HILLSHADE, RENAMED_BASEMAPS, SEA } from "./basemaps.js";
 import { AttributionControl } from "./controls.js";
 import { destroyedEngine, engineUrl, loadEngine, loadFullEngineLater, preloadFullEngine, startTileLoader, } from "./engine-loader.js";
 import { ExtrusionLayer, extrusionStyle } from "./extrusions.js";
 import { CircleLayer, circleStyle, FillLayer, fillStyle, LineLayer, lineStyle, } from "./features.js";
+import { IGN_PRESETS } from "./geoplateforme.js";
 import { Glyphs } from "./glyphs.js";
 import { equirectangularGrid, gridLoader, gridZooms, resolveGrid } from "./grid.js";
 import { Icons, readPixels } from "./icons.js";
 import { Interaction } from "./interaction.js";
 import { CustomLayer, GroundLayer, ModelLayer, NetworkLayer, RasterLayer, Tiles3dLayer, } from "./layers.js";
+import { loadPanoramas } from "./panoramas.js";
 import { PointCloudLayer } from "./pointclouds.js";
+import { headerRules, onHeaderRules } from "./requests.js";
 import { atmosphereSettings, bodySettings, haloSettings, rgb, terrainSettings, } from "./settings.js";
 import { injectStyle } from "./style.js";
 import { SymbolLayer, symbolStyle } from "./symbols.js";
@@ -48,11 +51,13 @@ const CORNERS = ['top-left', 'top-right', 'bottom-left', 'bottom-right'];
 const MAX_POLLS = 30;
 /** The name of a basemap, checked: an unknown one throws */
 function checkBasemap(basemap) {
-    const name = basemapName(basemap);
-    if (name !== 'none' && !(name in VECTOR_BASEMAPS) && !(name in BASEMAPS)) {
+    const renamed = RENAMED_BASEMAPS[basemap];
+    if (renamed)
+        throw new Error(`isard: the basemap '${basemap}' is now named '${renamed}'`);
+    if (basemap !== 'none' && !(basemap in VECTOR_BASEMAPS) && !(basemap in BASEMAPS)) {
         throw new Error(`isard: unknown basemap '${basemap}'`);
     }
-    return name;
+    return basemap;
 }
 /** A map (see `GeoMap.create`); layers take it as their host */
 export class GeoMap {
@@ -138,13 +143,17 @@ export class GeoMap {
     basemapPool;
     /** Stops watching the device pixel ratio */
     unwatchRatio;
+    /** Stops following the page's request headers (`setRequestHeaders`) */
+    unwatchHeaders = () => undefined;
     /** Stops listening to the canvas's context loss and restoration */
     unwatchContext;
     /** The loaders of the relief by encoding, URL and floor: the same loader for the same tiles (the engine keeps its
      * tiles when only the exaggeration changes) */
     terrainLoaders = new Map();
     /** Loads the engine (once per page) and creates a map filling `container` */
-    static async create(container, options = {}) {
+    static async create(container, given = {}) {
+        // A preset under the options given
+        const options = given.preset ? { ...IGN_PRESETS[given.preset], ...given } : given;
         // With 3D Tiles from the start when asked, or when only that engine's URL is given (as before the core engine)
         const full = options.tiles3d === true || (options.wasmUrl !== undefined && options.coreWasmUrl === undefined);
         // Before anything is created
@@ -162,7 +171,7 @@ export class GeoMap {
         this.tiles3dModule = tiles3dModule;
         this.tiles3dOptions = { ...options };
         this.glyphsUrl = options.glyphs;
-        this.basemapWorkerUrl = options.basemapWorkerUrl;
+        this.basemapWorkerUrl = options.basemapWorkerUrl ?? defaultWorkerUrl(options.assetsUrl);
         this.basemapTileSize = options.basemapTileSize;
         this.container = container;
         this.canvas = document.createElement('canvas');
@@ -202,6 +211,8 @@ export class GeoMap {
             globeColor: this.earth ? SEA['osm-positron'] : rgb(body.color),
         };
         this.#engine = this.createEngine();
+        // Once it has an engine: a map whose creation failed before is not left following them
+        this.unwatchHeaders = onHeaderRules((rules) => sendHeaders(this.#engine, rules));
         // The browser may take the GPU away (driver reset, background tab on mobile): the map waits, then rebuilds
         const lost = (event) => {
             event.preventDefault();
@@ -256,6 +267,7 @@ export class GeoMap {
         // The body first: the layers' shaders may take its size
         const { radius, flattening, atmosphere: air, relief } = this.settings.body;
         engine.setBody(radius, flattening, haloSettings(air), ...relief);
+        sendHeaders(engine, headerRules());
         const { zoomRange, maxPitch, globe, sky, atmosphere, terrain, loading, background, globeColor } = this.settings;
         engine.setZoomRange(...zoomRange);
         engine.setMaxPitch(maxPitch);
@@ -349,8 +361,68 @@ export class GeoMap {
                 report(error);
             }
         }
+        this.applySwipe();
+        // A street-level eye stays one in the new engine
+        if (this.#firstPerson)
+            this.setFirstPerson(this.#firstPerson);
+        // What the old engine drew over the scene: the viewshed, the panoramas shown
+        if (this.viewshed)
+            this.setViewshed(this.viewshed);
+        for (const set of this.panoramaSets)
+            if (set.current)
+                void set.show(set.current.index).catch(report);
         this.resize();
     }
+    /** The street-level eye, while there is one (`setFirstPerson`) */
+    #firstPerson;
+    /** The street-level eye, if the camera is one */
+    get firstPerson() {
+        return this.#firstPerson;
+    }
+    /**
+     * Puts the camera at street level: an eye `height` metres above the ground, looking `bearing` and `pitch`, the
+     * drag turning it around (the wheel narrows or widens its field of view); undefined gives back the camera turning
+     * around a point, above where the eye stood, facing the same way
+     */
+    setFirstPerson(view) {
+        if (!view) {
+            const was = this.#firstPerson;
+            this.#firstPerson = undefined;
+            if (was)
+                this.setCamera({ center: was.lonLat, zoom: 18, pitch: 60, bearing: was.bearing });
+            return;
+        }
+        const eye = {
+            height: 1.7,
+            pitch: 90,
+            fov: 75,
+            ...view,
+            lonLat: [view.lonLat[0], view.lonLat[1]],
+        };
+        eye.pitch = Math.max(1, Math.min(179, eye.pitch));
+        eye.fov = Math.max(10, Math.min(140, eye.fov));
+        eye.bearing = ((eye.bearing % 360) + 360) % 360;
+        this.#firstPerson = eye;
+        this.engine.setFirstPerson(eye.lonLat[0], eye.lonLat[1], eye.height, eye.bearing, eye.pitch, eye.fov);
+        this.requestRender();
+    }
+    /** The swipe set (`setSwipe`), applied again with the layers' ids of a new engine */
+    swipe;
+    /**
+     * Compares two states of a place: `layers` shown on one side of a vertical line only, at `position` CSS pixels
+     * from the left of the map (left of it by default, `side: 'right'` for the other), the layers beneath them on the
+     * other side. Set again as the line moves (a slider, a drag); undefined stops
+     */
+    setSwipe(options) {
+        this.swipe = options && options.layers.length > 0 ? { ...options, layers: [...options.layers] } : undefined;
+        this.applySwipe();
+        this.requestRender();
+    }
+    applySwipe() {
+        const s = this.swipe;
+        const ids = Uint32Array.from((s?.layers ?? []).filter((l) => l.id >= 0), (l) => l.id);
+        this.engine.setSwipe(s && ids.length > 0 ? s.position : Number.NaN, s?.side === 'right', ids);
+    }
     /** @internal Forgets a removed layer */
     detach(layer) {
         this.unlist(layer);
@@ -368,7 +440,7 @@ export class GeoMap {
         if (index >= 0)
             this.layers.splice(index, 1);
     }
-    add(layer) {
+    addLayer(layer) {
         // On the core engine, a 3D Tiles layer or a model waits for the engine with 3D Tiles: it is created with the
         // others on it
         if (layer.needsFullEngine && !this.tiles3dModule)
@@ -439,6 +511,37 @@ export class GeoMap {
         }
     }
     // ── Camera ──
+    /**
+     * The camera's methods together: `get`, `set`, `easeTo`, `flyTo`, `bounds`, `firstPerson` and `setFirstPerson`
+     * (street level), `project`, `unproject`; the same as the map's own (`getCamera`, `setCamera`…)
+     */
+    camera = {
+        get: () => this.getCamera(),
+        set: (camera) => this.setCamera(camera),
+        easeTo: (camera, options) => this.easeTo(camera, options),
+        flyTo: (camera, options) => this.flyTo(camera, options),
+        bounds: () => this.getBounds(),
+        firstPerson: () => this.firstPerson,
+        setFirstPerson: (view) => this.setFirstPerson(view),
+        project: (lonLat, height) => this.project(lonLat, height),
+        unproject: (point) => this.unproject(point),
+    };
+    /**
+     * What lies under a point or at a position, together: `feature` (`pickFeature`), `surface` (`pickSurface`),
+     * `surfaceAt`, `elevationAt`, `metersPerPixel`
+     */
+    query = {
+        feature: (point, options) => this.pickFeature(point, options),
+        surface: (point) => this.pickSurface(point),
+        surfaceAt: (lonLat) => this.surfaceAt(lonLat),
+        elevationAt: (lonLat) => this.elevationAt(lonLat),
+        metersPerPixel: (point) => this.metersPerPixel(point),
+    };
+    /** What is drawn over the scene, together: `viewshed` (`setViewshed`), `swipe` (`setSwipe`) */
+    effects = {
+        viewshed: (options) => this.setViewshed(options),
+        swipe: (options) => this.setSwipe(options),
+    };
     getCamera() {
         return this.frameCamera ?? this.engine.camera();
     }
@@ -515,7 +618,10 @@ export class GeoMap {
      * (`direction`): the relief, extrusions, 3D Tiles and models hide what lies behind them (only what the map has
      * loaded for its view). Several observers (16 at most): what any of them sees is seen, what is hidden from all those
      * that reach it is hidden, in the colors and opacity of the first. Undefined or none removes it */
+    /** The viewshed set, set again in a new engine */
+    viewshed;
     setViewshed(options) {
+        this.viewshed = options;
         let observers = [];
         if (options)
             observers = 'position' in options ? [options] : options;
@@ -643,6 +749,77 @@ export class GeoMap {
     unproject(point) {
         return this.engine.ground(point[0], point[1]);
     }
+    /**
+     * Street-level panoramas (oriented images of a vehicle's cameras, the iTowns immersive format): their positions
+     * and calibrations loaded, none shown until `show`, which projects one onto the scene around it
+     */
+    async addPanoramas(options) {
+        // Drawn by the engine with 3D Tiles: loaded first if needed
+        if (!this.tiles3dModule) {
+            this.upgrade();
+            await this.upgrading;
+            if (!this.tiles3dModule)
+                throw new Error('isard: panoramas need the engine with 3D Tiles, which failed to load');
+        }
+        const host = {
+            setPanorama: (...args) => {
+                this.engine.setPanorama(...args);
+                this.requestRender();
+            },
+            setPanoramaImage: (index, image) => this.engine.setPanoramaImage(index, image),
+            clearPanorama: () => this.engine.clearPanorama(),
+            geoidHeight: (lon, lat) => this.engineClass.geoidHeight(lon, lat),
+            firstPerson: () => this.firstPerson,
+            setFirstPerson: (view) => this.setFirstPerson(view),
+            elevationAt: (lonLat) => this.elevationAt(lonLat),
+            listen: (click, key, wheel) => {
+                const off = this.on('click', ({ lonLat }) => click(lonLat));
+                const container = this.getContainer();
+                // Before the map's own wheel (its zoom, the eye's field of view)
+                const onWheel = (e) => {
+                    e.preventDefault();
+                    e.stopImmediatePropagation();
+                    wheel(e);
+                };
+                container.addEventListener('keydown', key);
+                container.addEventListener('wheel', onWheel, { capture: true, passive: false });
+                return () => {
+                    off();
+                    container.removeEventListener('keydown', key);
+                    container.removeEventListener('wheel', onWheel, { capture: true });
+                };
+            },
+        };
+        const panoramas = await loadPanoramas(host, options);
+        this.panoramaSets.add(panoramas);
+        return panoramas;
+    }
+    /** The panorama sets, their panorama shown again in a new engine */
+    panoramaSets = new Set();
+    /** Altitude of the relief at a position, in metres (exaggeration included): from the copy of its tiles the map
+     * keeps, as fine as the tiles loaded there; undefined without relief or where none is loaded yet */
+    elevationAt(lonLat) {
+        return this.engine.elevationAt(lonLat[0], lonLat[1]);
+    }
+    /** Metres on the ground per CSS pixel at a screen point (default the center of the map), across the screen: for a
+     * scale bar; undefined above the horizon */
+    metersPerPixel(point) {
+        const [x, y] = point ?? [this.canvas.clientWidth / 2, this.canvas.clientHeight / 2];
+        const a = this.unproject([x - 0.5, y]);
+        const b = this.unproject([x + 0.5, y]);
+        if (!a || !b)
+            return undefined;
+        // Haversine, on the mean radius of the body
+        const rad = Math.PI / 180;
+        const [dLat, dLon] = [(b[1] - a[1]) * rad, (b[0] - a[0]) * rad];
+        const h = Math.sin(dLat / 2) ** 2 + Math.cos(a[1] * rad) * Math.cos(b[1] * rad) * Math.sin(dLon / 2) ** 2;
+        return 2 * this.settings.body.radius * Math.asin(Math.min(1, Math.sqrt(h)));
+    }
+    /** Whether a double click zooms in (Shift: out), on by default: off while a drawing takes double clicks */
+    setDoubleClickZoom(enabled) {
+        if (this.interaction)
+            this.interaction.doubleClickZoom = enabled;
+    }
     /** What is drawn under a screen point (CSS pixels), on the relief or standing on it (a roof, a wall, a mesh): its
      * position and its height above the relief, in metres; undefined where nothing was drawn. The last frame's scene is
      * drawn again and read back, waiting for the GPU (a stall): for clicks and drags */
@@ -698,7 +875,7 @@ export class GeoMap {
     }
     // ── Layers ──
     /** Replaces the basemap and the IGN hillshade, under the other layers (hillshade by default: 0, none). The former
-     * names of the Géoplateforme basemaps (`LegacyBasemap`) are taken under their new ones */
+     * names of the Géoplateforme basemaps throw, naming the new ones */
     setBasemap(basemap, hillshade = 0) {
         const name = checkBasemap(basemap);
         if (this.basemap && this.hasLayer(this.basemap))
@@ -776,7 +953,52 @@ export class GeoMap {
         const { halo = 0, haloOpacity = 0.11, ramp, unreachedColor = 'rgba(140, 140, 140, 0.25)', fade = 0 } = options;
         const style = { width, max, contour, opacity, halo, haloOpacity, ramp, unreachedColor, fade };
         validateNetwork(nodes, edges);
-        return this.add(new NetworkLayer(this, { nodes, edges, lines }, costs, style, edgeWidths));
+        return this.addLayer(new NetworkLayer(this, { nodes, edges, lines }, costs, style, edgeWidths));
+    }
+    /**
+     * A layer from its description, as an application's configuration gives it: `{ type, ...options }`, the options of
+     * the `add…` method of that type (`'lines'` for `addLines`, `'tiles3d'` for `addTiles3d`…); `before` to go under
+     * another layer. The layer's `ready` resolves once the map has drawn it
+     */
+    add(spec) {
+        switch (spec.type) {
+            case 'lines':
+                return this.addLines(spec);
+            case 'circles':
+                return this.addCircles(spec);
+            case 'fills':
+                return this.addFills(spec);
+            case 'symbols':
+                return this.addSymbols(spec);
+            case 'extrusions':
+                return this.addExtrusions(spec);
+            case 'raster':
+                return this.addRaster(spec);
+            case 'ground':
+                return this.addGround(spec);
+            case 'network':
+                return this.addNetwork(spec);
+            case 'tiles3d':
+                return this.addTiles3d(spec);
+            case 'pointcloud':
+                return this.addPointCloud(spec);
+            case 'models':
+                return this.addModels(spec);
+            default:
+                throw new Error(`isard: no layer of type ${String(spec.type)}`);
+        }
+    }
+    /** @internal Resolves once the map is idle (everything in view loaded and drawn) */
+    whenIdle() {
+        if (this.gone)
+            return Promise.resolve();
+        return new Promise((resolve) => {
+            const off = this.on('idle', () => {
+                off();
+                resolve();
+            });
+            this.requestRender();
+        });
     }
     /** Lines from GeoJSON (line strings, and polygon outlines), styled per feature */
     addLines(options) {
@@ -864,7 +1086,7 @@ export class GeoMap {
      * when it asks for another count or URL
      */
     basemapWorkers(count, url) {
-        const sharedUrl = this.basemapWorkerUrl ?? defaultWorkerUrl();
+        const sharedUrl = this.basemapWorkerUrl;
         const shared = defaultWorkerCount();
         const workers = Math.max(1, count ?? shared);
         const workerUrl = url ?? sharedUrl;
@@ -900,15 +1122,20 @@ export class GeoMap {
     };
     /** Adds a layer, under `before` if given */
     place(layer, before) {
-        this.add(layer);
+        this.addLayer(layer);
         if (before)
             this.moveLayer(layer, before);
         return layer;
     }
     /** Textured meshes in 3D Tiles (photogrammetry, buildings), drawn with depth over the basemap */
     addTiles3d(options) {
-        const { url, maxScreenSpaceError = 16, opacity = 1, pointSize } = options;
-        return this.add(new Tiles3dLayer(this, url, { maxScreenSpaceError, opacity, ...(pointSize !== undefined ? { pointSize } : {}) }));
+        const { url, maxScreenSpaceError = 16, opacity = 1, pointSize, color, geoid = false } = options;
+        return this.addLayer(new Tiles3dLayer(this, url, geoid, {
+            maxScreenSpaceError,
+            opacity,
+            ...(pointSize !== undefined ? { pointSize } : {}),
+            ...(color !== undefined ? { color } : {}),
+        }));
     }
     /**
      * A point cloud (see `PointCloudOptions`): a COPC file read by range requests (IGN's LiDAR HD…), or 3D Tiles
@@ -1077,6 +1304,7 @@ export class GeoMap {
         this.basemapPool = undefined;
         this.unwatchRatio?.();
         this.unwatchRatio = undefined;
+        this.unwatchHeaders();
         this.resizeObserver.disconnect();
         this.interaction?.destroy();
         this.loader?.destroy();
@@ -1103,4 +1331,8 @@ export class GeoMap {
             listeners.clear();
     }
 }
+/** The page's request headers to an engine (its own requests: raster tiles, tilesets, point clouds) */
+function sendHeaders(engine, rules) {
+    engine.setRequestHeaders(rules.map(([prefix]) => prefix), Uint32Array.from(rules, ([, headers]) => Object.keys(headers).length), rules.flatMap(([, headers]) => Object.entries(headers).flat()));
+}
 //# sourceMappingURL=map.js.map