isard 0.0.0-stage → 0.2.0

package/dist/map.d.ts

@@ -0,0 +1,203 @@
+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 { GroundLayer, type GroundOptions, type Layer, NetworkLayer, RasterLayer, Tiles3dLayer } from './layers.ts';
+import { SymbolLayer, type SymbolOptions } from './symbols.ts';
+import type { AnimationOptions, AtmosphereOptions, Basemap, FeatureHit, FlyToOptions, GeoMapOptions, LoadingMode, LonLat, MapEvents, NetworkOptions, Point, Projection, RasterOptions, TerrainModel, TerrainOptions, Tiles3dOptions } from './types.ts';
+import { VectorTiles, type VectorTilesOptions } from './vectortiles.ts';
+import type { Camera, PickHit, RasterLayerStats } from './wasm/isard.js';
+/** MapLibre's default easing: cubic Bézier (0.25, 0.1, 0.25, 1) */
+export declare function defaultEasing(t: number): number;
+/** A map (see `GeoMap.create`); layers take it as their host */
+export declare class GeoMap {
+    #private;
+    readonly canvas: HTMLCanvasElement;
+    /** Layers new layers go under */
+    private readonly onTop;
+    /** The vector basemap, if any: its tiles' workers and its labels */
+    private vector;
+    private readonly glyphsUrl;
+    private readonly basemapWorkerUrl;
+    private readonly container;
+    /** Markers and popups, over the canvas */
+    private readonly overlay;
+    private readonly corners;
+    private readonly controls;
+    private readonly positioned;
+    /** Canvas size in CSS pixels, kept on resize so placing overlays never reads the layout */
+    private size;
+    /** Layers in drawing order (bottom first), to recreate them after a context loss */
+    private readonly layers;
+    private readonly settings;
+    /** The WebGL context is lost: nothing is drawn until it is restored */
+    private lost;
+    private readonly listeners;
+    private readonly resizeObserver;
+    private readonly interaction;
+    private loader;
+    /** The class of the engine: without 3D Tiles until a 3D Tiles layer is added, unless asked for from the start */
+    private engineClass;
+    /** The module of the engine with 3D Tiles once it runs this map (the decoding workers run it too) */
+    private tiles3dModule;
+    /** The engine with 3D Tiles is loading, for the 3D Tiles layers added on the core engine */
+    private upgrading;
+    /** What loading the engine with 3D Tiles and its workers needs */
+    private readonly tiles3dOptions;
+    private gone;
+    /** The map is of the Earth: a basemap by default */
+    private readonly earth;
+    /** The body, as the option named it */
+    private readonly body;
+    private basemap;
+    private hillshade;
+    /** Called when the credits of the layers or relief change (the attribution controls) */
+    private readonly attributionListeners;
+    /** Credits of the raster layers that have some (basemaps, hillshade, the Géoplateforme's rasters…) */
+    private readonly rasterCredits;
+    private animation;
+    private hoverPoint;
+    /** Frame polling the engine for the answer of the hover picking, 0 if none */
+    private hoverPoll;
+    /** What 'hoverfeature' looks for: within `radius` CSS pixels, in `layers` only if given */
+    hoverPicking: {
+        radius?: number;
+        layers?: readonly Layer[];
+    };
+    private frameRequest;
+    private lastCamera;
+    /** The camera moved since the last 'moveend' */
+    private moving;
+    /** The last frame found everything loaded ('idle' sent) */
+    private settled;
+    private inFrame;
+    /** Vector tiles made by `vectorTiles()`, destroyed with the map */
+    private readonly vectorSets;
+    /** The workers drawing vector tiles, shared by every `VectorTiles` of the map; created on first use */
+    private basemapPool;
+    /** Stops watching the device pixel ratio */
+    private unwatchRatio;
+    /** Loads the engine (once per page) and creates a map filling `container` */
+    static create(container: HTMLElement, options?: GeoMapOptions): Promise<GeoMap>;
+    private constructor();
+    /** The element the map was created in */
+    getContainer(): HTMLElement;
+    getCanvas(): HTMLCanvasElement;
+    private createEngine;
+    /** The decoding workers of 3D Tiles, with the engine that has them (they run its module) and unless turned off */
+    private startLoader;
+    /** A 3D Tiles layer on the core engine: loads the engine with 3D Tiles, then rebuilds the map on it (camera,
+     * settings and layers kept, as after a context loss); the layer is created then */
+    private upgrade;
+    /** After a context loss: a new engine with the same camera, settings and layers (same handles, same order) */
+    private restore;
+    /** Takes a layer out of the drawing order (to put it back elsewhere, or for good) */
+    private unlist;
+    private add;
+    /** 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;
+    getCamera(): Camera;
+    setCamera(camera: Partial<Camera>): void;
+    /** Animated move to a camera: over `duration` milliseconds (or the options), ease-out by default */
+    easeTo(camera: Partial<Camera>, options?: number | AnimationOptions): void;
+    /**
+     * Flight to a camera that zooms out on its way and back in (van Wijk and Nuij's optimal path, as MapLibre's
+     * `flyTo`): long moves stay readable. Pitch and bearing follow the progress.
+     */
+    flyTo(camera: Partial<Camera>, options?: FlyToOptions): void;
+    /** Longitudes and latitudes the view covers on the ground: `[west, south, east, north]` */
+    getBounds(): [west: number, south: number, east: number, north: number];
+    /** Lowest zoom the camera accepts (the widest view) */
+    setMinZoom(zoom: number): void;
+    setMaxZoom(zoom: number): void;
+    /** Highest pitch, degrees, up to 85 */
+    setMaxPitch(pitch: number): void;
+    /** Sky over the plane and the fog of the ground (see `GeoMapOptions.atmosphere`); undefined to remove them */
+    setAtmosphere(options: AtmosphereOptions | undefined): void;
+    setProjection(projection: Projection): void;
+    /** How tiles load and show (see `LoadingMode`) */
+    setLoading(mode: LoadingMode): void;
+    /** Space behind the globe (stars, atmosphere halo) */
+    setSky(enabled: boolean): void;
+    /** Relief under the basemap: true for the body's terrain model (on the Earth the worldwide Terrain Tiles, NASA's
+     * on the Moon and Mars), one of the Earth's models by name (`'ign'`), its options, or false; on another body, its
+     * options with a `url` */
+    setTerrain(terrain: boolean | TerrainModel | TerrainOptions): void;
+    private attributionChanged;
+    /** Color behind the map, a CSS color (its alpha ignored) */
+    setBackground(color: string): void;
+    /** Tile counters of the raster layers, for diagnostics */
+    stats(): RasterLayerStats[];
+    /**
+     * Network edge under a screen point (CSS pixels), undefined if none. Reads one pixel of an offscreen picking pass:
+     * cheap whatever the number of features, call it on hover.
+     */
+    pick(point: Point, radius?: number, layers?: readonly Layer[]): PickHit | undefined;
+    /**
+     * The feature under a screen point (CSS pixels), or the nearest one within `radius` pixels: its layer handle, its
+     * index there and, for line, circle and fill layers, the feature itself; undefined if none. `layers` restricts the
+     * search to some layers (the others hide nothing).
+     */
+    pickFeature(point: Point, options?: {
+        radius?: number;
+        layers?: readonly Layer[];
+    }): FeatureHit | undefined;
+    /** A hit with its layer handle and feature; undefined if the layer is gone */
+    private featureHit;
+    /** Asks the engine what is under the pointer; its answer, read without waiting for the GPU, comes on a later frame */
+    private requestHoverPick;
+    private readonly pollHoverPick;
+    private cancelHoverPick;
+    /** Screen point (CSS pixels) of a position, undefined behind the camera */
+    project(lonLat: LonLat): Point | undefined;
+    /** Position under a screen point (CSS pixels), undefined above the horizon */
+    unproject(point: Point): LonLat | undefined;
+    /** Adds a control in a corner of the map; controls stack from the corner inward */
+    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 */
+    setBasemap(basemap: Basemap, hillshade?: number): void;
+    /** Raster tiles ({z}, {x}, {y} URL; Web Mercator, or reprojected from an equirectangular `grid`), over the layers
+     * already added */
+    addRaster(options: RasterOptions & {
+        before?: Layer;
+    }): RasterLayer;
+    /** Line network colored by a value per node; `layer.setValues` recolors it in one texture upload */
+    addNetwork(options: NetworkOptions): NetworkLayer;
+    /** 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 */
+    addCircles<P = Record<string, unknown>>(options: CircleOptions<P>): CircleLayer<P>;
+    /** Filled polygons from GeoJSON (holes included), styled per feature; over the relief they lie on the ground */
+    addFills<P = Record<string, unknown>>(options: FillOptions<P>): FillLayer<P>;
+    /** The application's fragment shader over the ground (see `GroundOptions`); under `before` if given */
+    addGround(options: GroundOptions & {
+        before?: Layer;
+    }): GroundLayer;
+    /** Polygons raised into blocks with depth (buildings), styled per feature; tiles of them come with `setTile` */
+    addExtrusions<P = Record<string, unknown>>(options?: ExtrusionOptions<P>): ExtrusionLayer<P>;
+    /** Text labels from GeoJSON (points, the middle of lines, the center of polygons), placed without overlaps */
+    addSymbols<P = Record<string, unknown>>(options: SymbolOptions<P>): SymbolLayer<P>;
+    /**
+     * Vector tiles with a MapLibre style (OpenFreeMap's Positron by default): `tiles.raster(…)` draws its fills and lines
+     * (or a subset) as a raster layer, `tiles.labels(…)` its labels. `setBasemap('osm-positron')` does both for the
+     * basemap.
+     */
+    vectorTiles(options?: VectorTilesOptions): VectorTiles;
+    /** Adds a layer, under `before` if given */
+    private place;
+    /** Textured meshes in 3D Tiles (photogrammetry, buildings), drawn with depth over the basemap */
+    addTiles3d(options: Tiles3dOptions): Tiles3dLayer;
+    /** Asks for a frame; several calls before the next frame draw it once */
+    requestRender(): void;
+    private frame;
+    private drawFrame;
+    /** Resizes when the device pixel ratio changes (browser zoom, a window moved to another screen) */
+    private watchRatio;
+    private resize;
+    destroy(): void;
+}