isard 0.8.0 → 1.1.0

package/dist/map.d.ts

@@ -1,13 +1,19 @@
-import { type Control, type ControlPosition } from './controls.ts';
-import { ExtrusionLayer, type ExtrusionOptions } from './extrusions.ts';
-import { CircleLayer, type CircleOptions, FillLayer, type FillOptions, LineLayer, type LineOptions } from './features.ts';
-import { type ImageOptions, type Pixels } from './icons.ts';
-import { CustomLayer, type CustomLayerInterface, GroundLayer, type GroundOptions, type Layer, ModelLayer, type ModelOptions, NetworkLayer, RasterLayer, Tiles3dLayer } from './layers.ts';
-import { type PanoramaOptions, type Panoramas } from './panoramas.ts';
-import { PointCloudLayer, type PointCloudOptions } from './pointclouds.ts';
-import { SymbolLayer, type SymbolOptions } from './symbols.ts';
+/**
+ * The map: canvas, camera, layers, events, overlays, credits and the frame loop. Frames are drawn on demand only: an
+ * idle map costs nothing. Hover events are coalesced to one per frame, so the values computed for a mouse position are
+ * drawn in the same frame. The engine's loading is in engine-loader.ts, its settings from the options in settings.ts,
+ * the camera animations in animation.ts.
+ */
+import { type PmtilesOptions, VectorTiles, type VectorTilesOptions } from './basemap/vectortiles.ts';
+import { ExtrusionLayer, type ExtrusionOptions } from './layers/extrusions.ts';
+import { CircleLayer, type CircleOptions, FillLayer, type FillOptions, LineLayer, type LineOptions } from './layers/features.ts';
+import { type ImageOptions, type Pixels } from './layers/icons.ts';
+import { CustomLayer, type CustomLayerInterface, GroundLayer, type GroundOptions, type Layer, ModelLayer, type ModelOptions, NetworkLayer, RasterLayer, Tiles3dLayer } from './layers/layers.ts';
+import { type PanoramaOptions, type Panoramas } from './layers/panoramas.ts';
+import { PointCloudLayer, type PointCloudOptions } from './layers/pointclouds.ts';
+import { SymbolLayer, type SymbolOptions } from './layers/symbols.ts';
 import type { AnimationOptions, AtmosphereOptions, Basemap, FeatureHit, FirstPersonView, FlyToOptions, GeoMapOptions, LoadingMode, LonLat, MapEvents, NetworkOptions, Point, Projection, RasterOptions, SwipeOptions, TerrainModel, TerrainOptions, Tiles3dOptions, ViewshedOptions } from './types.ts';
-import { type PmtilesOptions, VectorTiles, type VectorTilesOptions } from './vectortiles.ts';
+import { type Control, type ControlPosition } from './ui/controls.ts';
 import type { Camera, PickHit, RasterLayerStats } from './wasm/isard.js';
 /** A map (see `GeoMap.create`); layers take it as their host */
 export declare class GeoMap {
@@ -91,7 +97,7 @@ export declare class GeoMap {
      * tiles when only the exaggeration changes) */
     private readonly terrainLoaders;
     /** Loads the engine (once per page) and creates a map filling `container` */
-    static create(container: HTMLElement, options?: GeoMapOptions): Promise<GeoMap>;
+    static create(container: HTMLElement, given?: GeoMapOptions): Promise<GeoMap>;
     private constructor();
     /** The element the map was created in */
     getContainer(): HTMLElement;
@@ -126,13 +132,50 @@ export declare class GeoMap {
     private applySwipe;
     /** Takes a layer out of the drawing order (to put it back elsewhere, or for good) */
     private unlist;
-    private add;
+    private addLayer;
     /** Index in the engine of the layer at `index`: the layers waiting for the engine with 3D Tiles are not in it yet */
     private engineIndex;
     /** Moves a layer under all the others */
     private toBottom;
     /** Listens to an event; returns the function that stops listening */
     on<K extends keyof MapEvents>(type: K, listener: (event: MapEvents[K]) => void): () => void;
+    /**
+     * 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`…)
+     */
+    readonly camera: {
+        readonly get: () => Camera;
+        readonly set: (camera: Partial<Camera>) => void;
+        readonly easeTo: (camera: Partial<Camera>, options?: number | AnimationOptions) => void;
+        readonly flyTo: (camera: Partial<Camera>, options?: FlyToOptions) => void;
+        readonly bounds: () => [west: number, south: number, east: number, north: number];
+        readonly firstPerson: () => Readonly<Required<FirstPersonView>> | undefined;
+        readonly setFirstPerson: (view: FirstPersonView | undefined) => void;
+        readonly project: (lonLat: LonLat, height?: number) => Point | undefined;
+        readonly unproject: (point: Point) => LonLat | undefined;
+    };
+    /**
+     * What lies under a point or at a position, together: `feature` (`pickFeature`), `surface` (`pickSurface`),
+     * `surfaceAt`, `elevationAt`, `metersPerPixel`
+     */
+    readonly query: {
+        readonly feature: (point: Point, options?: {
+            radius?: number;
+            layers?: readonly Layer[];
+        }) => FeatureHit | undefined;
+        readonly surface: (point: Point) => {
+            lonLat: LonLat;
+            height: number;
+        } | undefined;
+        readonly surfaceAt: (lonLat: LonLat) => number | undefined;
+        readonly elevationAt: (lonLat: LonLat) => number | undefined;
+        readonly metersPerPixel: (point?: Point) => number | undefined;
+    };
+    /** What is drawn over the scene, together: `viewshed` (`setViewshed`), `swipe` (`setSwipe`) */
+    readonly effects: {
+        readonly viewshed: (options: ViewshedOptions | readonly ViewshedOptions[] | undefined) => void;
+        readonly swipe: (options: SwipeOptions | undefined) => void;
+    };
     getCamera(): Camera;
     setCamera(camera: Partial<Camera>): void;
     /** Animated move to a camera: over `duration` milliseconds (or the options), ease-out by default */
@@ -228,7 +271,7 @@ export declare class GeoMap {
     addControl(control: Control, position?: ControlPosition): this;
     removeControl(control: Control): this;
     /** 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: Basemap, hillshade?: number): void;
     /** Raster tiles ({z}, {x}, {y} URL; Web Mercator, or reprojected from another `grid`: longitudes and latitudes,
      * Lambert-93, UTM…), over the layers already added */
@@ -244,6 +287,12 @@ export declare class GeoMap {
     addPmtiles(url: string, options?: PmtilesOptions): Promise<RasterLayer | VectorTiles>;
     /** Line network colored by a value per node; `layer.setValues` recolors it in one texture upload */
     addNetwork(options: NetworkOptions): NetworkLayer;
+    /**
+     * 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<P = Record<string, unknown>>(spec: LayerSpec<P>): Layer;
     /** Lines from GeoJSON (line strings, and polygon outlines), styled per feature */
     addLines<P = Record<string, unknown>>(options: LineOptions<P>): LineLayer<P>;
     /** Discs from GeoJSON points, styled per feature */
@@ -316,3 +365,35 @@ export declare class GeoMap {
     private resize;
     destroy(): void;
 }
+/** A layer by its type and the options of its `add…` method (`GeoMap.add`) */
+export type LayerSpec<P = Record<string, unknown>> = ({
+    type: 'lines';
+} & LineOptions<P>) | ({
+    type: 'circles';
+} & CircleOptions<P>) | ({
+    type: 'fills';
+} & FillOptions<P>) | ({
+    type: 'symbols';
+} & SymbolOptions<P>) | ({
+    type: 'extrusions';
+} & ExtrusionOptions<P>) | ({
+    type: 'raster';
+} & RasterOptions & {
+    before?: Layer;
+}) | ({
+    type: 'ground';
+} & GroundOptions & {
+    before?: Layer;
+}) | ({
+    type: 'network';
+} & NetworkOptions) | ({
+    type: 'tiles3d';
+} & Tiles3dOptions) | ({
+    type: 'pointcloud';
+} & PointCloudOptions & {
+    before?: Layer;
+}) | ({
+    type: 'models';
+} & ModelOptions & {
+    before?: Layer;
+});

package/dist/map.js

@@ -4,25 +4,26 @@
  * drawn in the same frame. The engine's loading is in engine-loader.ts, its settings from the options in settings.ts,
  * the camera animations in animation.ts.
  */
-import { easeTo, flyTo } from "./animation.js";
-import { BASEMAPS, basemapName, HILLSHADE, SEA } from "./basemaps.js";
-import { AttributionControl } from "./controls.js";
+import { BASEMAPS, HILLSHADE, RENAMED_BASEMAPS, SEA } from "./basemap/basemaps.js";
+import { equirectangularGrid, gridLoader, gridZooms, resolveGrid } from "./basemap/grid.js";
+import { encodedTerrainLoader } from "./basemap/terrain.js";
+import { BasemapWorkers, defaultWorkerCount, defaultWorkerUrl, pmtilesLayer, pmtilesRasterLoader, VECTOR_BASEMAPS, VectorTiles, } from "./basemap/vectortiles.js";
+import { headerRules, onHeaderRules } from "./engine/requests.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 { 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 { IGN_PRESETS } from "./geoplateforme.js";
+import { ExtrusionLayer, extrusionStyle } from "./layers/extrusions.js";
+import { CircleLayer, circleStyle, FillLayer, fillStyle, LineLayer, lineStyle, } from "./layers/features.js";
+import { Glyphs } from "./layers/glyphs.js";
+import { Icons, readPixels } from "./layers/icons.js";
+import { CustomLayer, GroundLayer, ModelLayer, NetworkLayer, RasterLayer, Tiles3dLayer, } from "./layers/layers.js";
+import { loadPanoramas } from "./layers/panoramas.js";
+import { PointCloudLayer } from "./layers/pointclouds.js";
+import { SymbolLayer, symbolStyle } from "./layers/symbols.js";
 import { atmosphereSettings, bodySettings, haloSettings, rgb, terrainSettings, } from "./settings.js";
-import { injectStyle } from "./style.js";
-import { SymbolLayer, symbolStyle } from "./symbols.js";
-import { encodedTerrainLoader } from "./terrain.js";
-import { BasemapWorkers, defaultWorkerCount, defaultWorkerUrl, pmtilesLayer, pmtilesRasterLoader, VECTOR_BASEMAPS, VectorTiles, } from "./vectortiles.js";
+import { AttributionControl } from "./ui/controls.js";
+import { Interaction } from "./ui/interaction.js";
+import { injectStyle } from "./ui/style.js";
+import { easeTo, flyTo } from "./util/animation.js";
 /** Reports an error without throwing it here: the console shows it, as an uncaught one */
 function report(error) {
     if (typeof reportError === 'function')
@@ -50,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 {
@@ -148,7 +151,9 @@ export class GeoMap {
      * 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
@@ -166,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');
@@ -435,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)
@@ -506,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();
     }
@@ -839,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))
@@ -917,7 +953,62 @@ 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 A layer made anew from its description, in the place of `old` in the drawing order (old removed) */
+    rebuildLayer(old, spec) {
+        const index = this.layers.indexOf(old);
+        const above = index >= 0 ? this.layers[index + 1] : undefined;
+        const layer = this.add(spec);
+        if (!('before' in spec && spec.before) && index >= 0)
+            this.moveLayer(layer, above);
+        old.remove();
+        return layer;
+    }
+    /** @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) {
@@ -1005,7 +1096,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;
@@ -1041,7 +1132,7 @@ 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;
@@ -1049,7 +1140,7 @@ export class GeoMap {
     /** Textured meshes in 3D Tiles (photogrammetry, buildings), drawn with depth over the basemap */
     addTiles3d(options) {
         const { url, maxScreenSpaceError = 16, opacity = 1, pointSize, color, geoid = false } = options;
-        return this.add(new Tiles3dLayer(this, url, geoid, {
+        return this.addLayer(new Tiles3dLayer(this, url, geoid, {
             maxScreenSpaceError,
             opacity,
             ...(pointSize !== undefined ? { pointSize } : {}),