isard 0.3.0 → 0.5.0

package/dist/map.d.ts

@@ -1,7 +1,9 @@
 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 { 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 { PointCloudLayer, type PointCloudOptions } from './pointclouds.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';
@@ -72,6 +74,8 @@ export declare class GeoMap {
     /** The last frame found everything loaded ('idle' sent) */
     private settled;
     private inFrame;
+    /** The camera of the frame being drawn: what `getCamera` gives the custom layers while the engine is busy */
+    private frameCamera;
     /** 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 */
@@ -92,8 +96,8 @@ export declare class GeoMap {
     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 */
+    /** A 3D Tiles layer or a model 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;
     /** Downloads and compiles the engine with 3D Tiles once the map is idle (`tiles3d: 'preload'`), without running
      * it: the first 3D Tiles layer then only instantiates it */
@@ -193,6 +197,18 @@ export declare class GeoMap {
     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>;
+    /**
+     * An image for the symbol layers' icons (`icon: name`), as MapLibre's `addImage`: its pixels (an image, a canvas,
+     * `ImageData`, or RGBA bytes with their size), `pixelRatio` 2 for an image drawn at twice its CSS size; `sdf` for a
+     * signed distance field drawn in the `iconColor`; `stretchX`, `stretchY` and `content` for an icon stretched around its
+     * text. An image of the same name is replaced
+     */
+    addImage(name: string, image: Pixels | (CanvasImageSource & {
+        width: number;
+        height: number;
+    }), options?: ImageOptions): void;
+    hasImage(name: string): boolean;
+    removeImage(name: string): void;
     /**
      * 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
@@ -212,6 +228,24 @@ export declare class GeoMap {
     private place;
     /** Textured meshes in 3D Tiles (photogrammetry, buildings), drawn with depth over the basemap */
     addTiles3d(options: Tiles3dOptions): Tiles3dLayer;
+    /**
+     * A point cloud (see `PointCloudOptions`): a COPC file read by range requests (IGN's LiDAR HD…), or 3D Tiles
+     * points; with depth, on the engine with 3D Tiles; under `before` if given
+     */
+    addPointCloud(options: PointCloudOptions & {
+        before?: Layer;
+    }): PointCloudLayer;
+    /** A glTF model drawn at positions (see `ModelOptions`), with depth; on the engine with 3D Tiles, as they are */
+    addModels(options: ModelOptions & {
+        before?: Layer;
+    }): ModelLayer;
+    /**
+     * The page's own WebGL drawing at its place among the layers, in every frame (see `CustomLayerInterface`): raw
+     * WebGL, three.js… with the matrices of the frame (`frame.matrixAt`); under `before` if given
+     */
+    addCustomLayer(layer: CustomLayerInterface, options?: {
+        before?: Layer;
+    }): CustomLayer;
     /** Asks for a frame; several calls before the next frame draw it once */
     requestRender(): void;
     private frame;

package/dist/map.js

@@ -12,8 +12,10 @@ 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 { GroundLayer, NetworkLayer, RasterLayer, Tiles3dLayer } from "./layers.js";
+import { CustomLayer, GroundLayer, ModelLayer, NetworkLayer, RasterLayer, Tiles3dLayer, } from "./layers.js";
+import { PointCloudLayer } from "./pointclouds.js";
 import { atmosphereSettings, bodySettings, haloSettings, rgb, terrainSettings, } from "./settings.js";
 import { injectStyle } from "./style.js";
 import { SymbolLayer, symbolStyle } from "./symbols.js";
@@ -56,6 +58,7 @@ function checkBasemap(basemap) {
 export class GeoMap {
     canvas;
     #glyphs;
+    #icons;
     /** Layers new layers go under */
     onTop = new Set();
     /** The vector basemap, if any: its tiles' workers and its labels */
@@ -127,6 +130,8 @@ export class GeoMap {
     /** The last frame found everything loaded ('idle' sent) */
     settled = false;
     inFrame = false;
+    /** The camera of the frame being drawn: what `getCamera` gives the custom layers while the engine is busy */
+    frameCamera;
     /** Vector tiles made by `vectorTiles()`, destroyed with the map */
     vectorSets = new Set();
     /** The workers drawing vector tiles, shared by every `VectorTiles` of the map; created on first use */
@@ -270,8 +275,8 @@ export class GeoMap {
     startLoader(engine) {
         return this.tiles3dModule && startTileLoader(this.tiles3dModule, this.tiles3dOptions, engine);
     }
-    /** 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 */
+    /** A 3D Tiles layer or a model 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 */
     upgrade() {
         this.upgrading ??= loadFullEngineLater(engineUrl('full', this.tiles3dOptions)).then(({ module, Engine }) => {
             this.upgrading = undefined;
@@ -316,13 +321,14 @@ export class GeoMap {
         this.lost = false;
         this.setCamera(camera);
         this.#glyphs?.attach(this.#engine);
+        this.#icons?.attach(this.#engine);
         const engine = this.#engine;
         // No layer refers to an id of the old engine while the others are created
         for (const layer of this.layers)
             layer.forgetEngine();
         for (const layer of this.layers) {
             // Still waiting for the engine with 3D Tiles (loading, or failed): created with it
-            if (layer instanceof Tiles3dLayer && !this.tiles3dModule)
+            if (layer.needsFullEngine && !this.tiles3dModule)
                 continue;
             // A layer that fails is reported and left out; the others are created
             try {
@@ -363,8 +369,9 @@ export class GeoMap {
             this.layers.splice(index, 1);
     }
     add(layer) {
-        // On the core engine, a 3D Tiles layer waits for the engine with 3D Tiles: it is created with the others on it
-        if (layer instanceof Tiles3dLayer && !this.tiles3dModule)
+        // 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)
             this.upgrade();
         else
             layer.attach(this.engine);
@@ -433,7 +440,7 @@ export class GeoMap {
     }
     // ── Camera ──
     getCamera() {
-        return this.engine.camera();
+        return this.frameCamera ?? this.engine.camera();
     }
     setCamera(camera) {
         const c = { ...this.getCamera(), ...camera };
@@ -758,6 +765,34 @@ export class GeoMap {
         }
         return this.#glyphs;
     }
+    /** @internal The icons of the symbol layers: the application's images and the vector basemaps' sprites */
+    get icons() {
+        if (!this.#icons) {
+            const gl = this.canvas.getContext('webgl2');
+            const max = gl?.getParameter(gl.MAX_TEXTURE_SIZE);
+            this.#icons = new Icons(typeof max === 'number' ? max : undefined);
+            this.#icons.attach(this.engine);
+        }
+        return this.#icons;
+    }
+    /**
+     * An image for the symbol layers' icons (`icon: name`), as MapLibre's `addImage`: its pixels (an image, a canvas,
+     * `ImageData`, or RGBA bytes with their size), `pixelRatio` 2 for an image drawn at twice its CSS size; `sdf` for a
+     * signed distance field drawn in the `iconColor`; `stretchX`, `stretchY` and `content` for an icon stretched around its
+     * text. An image of the same name is replaced
+     */
+    addImage(name, image, options = {}) {
+        const pixels = 'data' in image ? image : readPixels(image);
+        if (!pixels)
+            throw new Error(`isard: the image ${name} has no pixels`);
+        this.icons.add(name, pixels, options);
+    }
+    hasImage(name) {
+        return this.#icons?.has(name) ?? false;
+    }
+    removeImage(name) {
+        this.#icons?.remove(name);
+    }
     /**
      * 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
@@ -824,8 +859,27 @@ export class GeoMap {
     }
     /** Textured meshes in 3D Tiles (photogrammetry, buildings), drawn with depth over the basemap */
     addTiles3d(options) {
-        const { url, maxScreenSpaceError = 16, opacity = 1 } = options;
-        return this.add(new Tiles3dLayer(this, url, { maxScreenSpaceError, opacity }));
+        const { url, maxScreenSpaceError = 16, opacity = 1, pointSize } = options;
+        return this.add(new Tiles3dLayer(this, url, { maxScreenSpaceError, opacity, ...(pointSize !== undefined ? { pointSize } : {}) }));
+    }
+    /**
+     * A point cloud (see `PointCloudOptions`): a COPC file read by range requests (IGN's LiDAR HD…), or 3D Tiles
+     * points; with depth, on the engine with 3D Tiles; under `before` if given
+     */
+    addPointCloud(options) {
+        return this.place(new PointCloudLayer(this, options), options.before);
+    }
+    /** A glTF model drawn at positions (see `ModelOptions`), with depth; on the engine with 3D Tiles, as they are */
+    addModels(options) {
+        return this.place(new ModelLayer(this, options), options.before);
+    }
+    /**
+     * The page's own WebGL drawing at its place among the layers, in every frame (see `CustomLayerInterface`): raw
+     * WebGL, three.js… with the matrices of the frame (`frame.matrixAt`); under `before` if given
+     */
+    addCustomLayer(layer, options = {}) {
+        const custom = new CustomLayer(this, layer, this.canvas, this, (lon, lat, altitude) => this.engineClass.customMatrix(lon, lat, altitude), () => this.getCamera());
+        return this.place(custom, options.before);
     }
     // ── Frames ──
     /** Asks for a frame; several calls before the next frame draw it once */
@@ -899,7 +953,15 @@ export class GeoMap {
         const t0 = performance.now();
         // The engine asks for the next frame while it draws (uploads past the frame budget, fades): not ignored
         this.inFrame = false;
-        const loading = this.engine.render();
+        // As the engine has it now (a listener may have moved it), for the custom layers drawn in the frame
+        this.frameCamera = this.layers.some((layer) => layer instanceof CustomLayer) ? this.engine.camera() : undefined;
+        let loading;
+        try {
+            loading = this.engine.render();
+        }
+        finally {
+            this.frameCamera = undefined;
+        }
         this.inFrame = true;
         // The picking pass sees the frame just drawn; its answer comes on a later frame
         if (hovered && this.listeners.hoverfeature.size > 0)
@@ -970,12 +1032,16 @@ export class GeoMap {
         this.resizeObserver.disconnect();
         this.interaction?.destroy();
         this.loader?.destroy();
+        // Custom layers free their WebGL objects, models their data, while the context is there
+        for (const layer of this.layers)
+            layer.dispose();
         this.engine.free();
         // Work still under way (labels being shaped, tiles arriving, timers) may call the engine after this: it finds one
         // that does nothing, and nothing is drawn again
         this.#engine = destroyedEngine(camera);
         // Glyph ranges still arriving upload to it, not to the freed engine
         this.#glyphs?.attach(this.#engine);
+        this.#icons?.attach(this.#engine);
         this.lost = true;
         for (const control of [...this.controls.keys()])
             this.removeControl(control);