isard 0.2.1 → 0.4.0

package/dist/resample.js

@@ -0,0 +1,164 @@
+/**
+ * Raster reprojection, the drawing half: a Web Mercator tile drawn from the source images it spans (tiles of another
+ * grid, or one image of a WMS), in a worker of the map (OffscreenCanvas) or in the page when the map has no workers.
+ * The page plans each tile (`grid.ts`): which images, where they go in a mosaic, and a mesh of control points giving,
+ * for the corners of 16 × 16 cells of the tile, the mosaic pixel under them. Here the images are fetched (kept for the
+ * neighbouring tiles), drawn into the mosaic, and every pixel of the tile sampled from it, its source position
+ * interpolated within its cell (bilinear), its color between the four nearest source pixels (bilinear, alpha
+ * premultiplied). This code knows no projection.
+ */
+import { Lru } from "./lru.js";
+/** Source images kept decoded (by the page, or shared by the workers of a pool): the neighbours of a tile share them */
+export const SOURCE_CACHE = 96;
+/**
+ * Samples the pixels of a `size` × `size` tile (RGBA, straight alpha) from a mosaic of `width` × `height` (RGBA,
+ * straight alpha) through the mesh of a job. Pixels whose position falls outside the mosaic, or on a NaN, stay
+ * transparent; the mosaic's edge fades over half a pixel
+ */
+export function resample(source, width, height, mesh, n, size) {
+    const out = new Uint8ClampedArray(size * size * 4);
+    const cell = size / n;
+    const stride = n + 1;
+    for (let row = 0; row < size; row += 1) {
+        const fy = (row + 0.5) / cell;
+        const j = Math.min(n - 1, Math.floor(fy));
+        const ty = fy - j;
+        for (let col = 0; col < size; col += 1) {
+            const fx = (col + 0.5) / cell;
+            const i = Math.min(n - 1, Math.floor(fx));
+            const tx = fx - i;
+            const a = 2 * (j * stride + i);
+            const b = a + 2 * stride;
+            // The corners of the cell, then the position in it
+            const w00 = (1 - tx) * (1 - ty);
+            const w10 = tx * (1 - ty);
+            const w01 = (1 - tx) * ty;
+            const w11 = tx * ty;
+            const u = w00 * mesh[a] +
+                w10 * mesh[a + 2] +
+                w01 * mesh[b] +
+                w11 * mesh[b + 2];
+            const v = w00 * mesh[a + 1] +
+                w10 * mesh[a + 3] +
+                w01 * mesh[b + 1] +
+                w11 * mesh[b + 3];
+            // Pixel centers at half pixels: the four around (u, v)
+            const sx = u - 0.5;
+            const sy = v - 0.5;
+            if (!(sx > -1 && sy > -1 && sx < width && sy < height))
+                continue;
+            const x0 = Math.floor(sx);
+            const y0 = Math.floor(sy);
+            const kx = sx - x0;
+            const ky = sy - y0;
+            let r = 0;
+            let g = 0;
+            let bl = 0;
+            let alpha = 0;
+            for (let k = 0; k < 4; k += 1) {
+                const x = x0 + (k & 1);
+                const y = y0 + (k >> 1);
+                if (x < 0 || y < 0 || x >= width || y >= height)
+                    continue;
+                const p = 4 * (y * width + x);
+                const wa = (k & 1 ? kx : 1 - kx) * (k >> 1 ? ky : 1 - ky) * source[p + 3];
+                r += wa * source[p];
+                g += wa * source[p + 1];
+                bl += wa * source[p + 2];
+                alpha += wa;
+            }
+            if (alpha <= 0)
+                continue;
+            const q = 4 * (row * size + col);
+            out[q] = r / alpha;
+            out[q + 1] = g / alpha;
+            out[q + 2] = bl / alpha;
+            out[q + 3] = alpha;
+        }
+    }
+    return out;
+}
+/**
+ * Draws planned tiles, keeping `cached` source images decoded. A missing source image (404, 204, 410) leaves its part
+ * empty; a tile with no source at all is missing; other errors reject (retried by the engine). In the page, or in a
+ * worker of the map (`close` frees the images kept)
+ */
+export function resampler(cached = SOURCE_CACHE) {
+    /** Tiles being drawn from each source image: an evicted one is closed once none is */
+    const users = new Map();
+    const evicted = new Set();
+    const close = (image) => {
+        evicted.delete(image);
+        image.then((bitmap) => bitmap?.close(), () => undefined);
+    };
+    /** Freed now, or once the tiles drawing from it are done */
+    const drop = (image) => {
+        if (users.has(image))
+            evicted.add(image);
+        else
+            close(image);
+    };
+    // Source images by URL: a request is shared by the tiles that need it, its signal is not theirs
+    const cache = new Lru(cached, drop);
+    const release = (image) => {
+        const count = (users.get(image) ?? 1) - 1;
+        if (count > 0)
+            users.set(image, count);
+        else {
+            users.delete(image);
+            if (evicted.has(image))
+                close(image);
+        }
+    };
+    const fetchImage = (url) => {
+        let image = cache.get(url);
+        if (!image) {
+            image = (async () => {
+                const response = await fetch(url);
+                if (response.status === 404 || response.status === 204 || response.status === 410)
+                    return null;
+                if (!response.ok)
+                    throw new Error(`isard: ${response.status} for a raster to reproject`);
+                return createImageBitmap(await response.blob());
+            })();
+            // A failure is not kept: the engine's retry fetches again
+            image.catch(() => cache.delete(url));
+            cache.set(url, image);
+        }
+        users.set(image, (users.get(image) ?? 0) + 1);
+        return image;
+    };
+    const draw = async (job, signal) => {
+        const pending = job.sources.map((s) => [s, fetchImage(s.url)]);
+        try {
+            const images = await Promise.all(pending.map(async ([s, image]) => [s, await image]));
+            signal.throwIfAborted();
+            if (!images.some(([, image]) => image))
+                return null;
+            const canvas = new OffscreenCanvas(job.width, job.height);
+            const context = canvas.getContext('2d', { willReadFrequently: true });
+            if (!context)
+                throw new Error('isard: no 2D canvas to reproject the tiles');
+            for (const [s, image] of images)
+                if (image)
+                    context.drawImage(image, s.x, s.y, s.w, s.h);
+            const mosaic = context.getImageData(0, 0, job.width, job.height).data;
+            const pixels = resample(mosaic, job.width, job.height, job.mesh, job.n, job.size);
+            return createImageBitmap(new ImageData(pixels, job.size, job.size), { premultiplyAlpha: 'none' });
+        }
+        finally {
+            for (const [, image] of pending)
+                release(image);
+        }
+    };
+    return {
+        draw,
+        cache,
+        close: () => {
+            for (const image of cache.values())
+                drop(image);
+            cache.clear();
+        },
+    };
+}
+//# sourceMappingURL=resample.js.map

package/dist/resample.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resample.js","sourceRoot":"","sources":["../src/resample.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Raster reprojection, the drawing half: a Web Mercator tile drawn from the source images it spans (tiles of another\n * grid, or one image of a WMS), in a worker of the map (OffscreenCanvas) or in the page when the map has no workers.\n * The page plans each tile (`grid.ts`): which images, where they go in a mosaic, and a mesh of control points giving,\n * for the corners of 16 × 16 cells of the tile, the mosaic pixel under them. Here the images are fetched (kept for the\n * neighbouring tiles), drawn into the mosaic, and every pixel of the tile sampled from it, its source position\n * interpolated within its cell (bilinear), its color between the four nearest source pixels (bilinear, alpha\n * premultiplied). This code knows no projection.\n */\nimport { Lru } from './lru.ts';\n\n/** Source images kept decoded (by the page, or shared by the workers of a pool): the neighbours of a tile share them */\nexport const SOURCE_CACHE = 96;\n\n/** A source image and the rectangle of the mosaic it covers (pixels) */\nexport interface Placed {\n  url: string;\n  x: number;\n  y: number;\n  w: number;\n  h: number;\n}\n\n/** How to draw a Mercator tile of `size` pixels: the mosaic of the source images, and the mesh of `n` × `n` cells\n * ((n + 1)² points, rows from the north, x then y): the mosaic position of each corner, NaN where the source CRS has\n * none */\nexport interface Job {\n  size: number;\n  width: number;\n  height: number;\n  sources: Placed[];\n  n: number;\n  mesh: Float32Array;\n}\n\n/**\n * Samples the pixels of a `size` × `size` tile (RGBA, straight alpha) from a mosaic of `width` × `height` (RGBA,\n * straight alpha) through the mesh of a job. Pixels whose position falls outside the mosaic, or on a NaN, stay\n * transparent; the mosaic's edge fades over half a pixel\n */\nexport function resample(\n  source: Uint8ClampedArray,\n  width: number,\n  height: number,\n  mesh: Float32Array,\n  n: number,\n  size: number,\n): Uint8ClampedArray<ArrayBuffer> {\n  const out = new Uint8ClampedArray(size * size * 4);\n  const cell = size / n;\n  const stride = n + 1;\n  for (let row = 0; row < size; row += 1) {\n    const fy = (row + 0.5) / cell;\n    const j = Math.min(n - 1, Math.floor(fy));\n    const ty = fy - j;\n    for (let col = 0; col < size; col += 1) {\n      const fx = (col + 0.5) / cell;\n      const i = Math.min(n - 1, Math.floor(fx));\n      const tx = fx - i;\n      const a = 2 * (j * stride + i);\n      const b = a + 2 * stride;\n      // The corners of the cell, then the position in it\n      const w00 = (1 - tx) * (1 - ty);\n      const w10 = tx * (1 - ty);\n      const w01 = (1 - tx) * ty;\n      const w11 = tx * ty;\n      const u =\n        w00 * (mesh[a] as number) +\n        w10 * (mesh[a + 2] as number) +\n        w01 * (mesh[b] as number) +\n        w11 * (mesh[b + 2] as number);\n      const v =\n        w00 * (mesh[a + 1] as number) +\n        w10 * (mesh[a + 3] as number) +\n        w01 * (mesh[b + 1] as number) +\n        w11 * (mesh[b + 3] as number);\n      // Pixel centers at half pixels: the four around (u, v)\n      const sx = u - 0.5;\n      const sy = v - 0.5;\n      if (!(sx > -1 && sy > -1 && sx < width && sy < height)) continue;\n      const x0 = Math.floor(sx);\n      const y0 = Math.floor(sy);\n      const kx = sx - x0;\n      const ky = sy - y0;\n      let r = 0;\n      let g = 0;\n      let bl = 0;\n      let alpha = 0;\n      for (let k = 0; k < 4; k += 1) {\n        const x = x0 + (k & 1);\n        const y = y0 + (k >> 1);\n        if (x < 0 || y < 0 || x >= width || y >= height) continue;\n        const p = 4 * (y * width + x);\n        const wa = (k & 1 ? kx : 1 - kx) * (k >> 1 ? ky : 1 - ky) * (source[p + 3] as number);\n        r += wa * (source[p] as number);\n        g += wa * (source[p + 1] as number);\n        bl += wa * (source[p + 2] as number);\n        alpha += wa;\n      }\n      if (alpha <= 0) continue;\n      const q = 4 * (row * size + col);\n      out[q] = r / alpha;\n      out[q + 1] = g / alpha;\n      out[q + 2] = bl / alpha;\n      out[q + 3] = alpha;\n    }\n  }\n  return out;\n}\n\n/** Draws a planned tile: its image, null where the source has nothing; rejects on errors */\nexport type DrawJob = (job: Job, signal: AbortSignal) => Promise<ImageBitmap | null>;\n\n/**\n * Draws planned tiles, keeping `cached` source images decoded. A missing source image (404, 204, 410) leaves its part\n * empty; a tile with no source at all is missing; other errors reject (retried by the engine). In the page, or in a\n * worker of the map (`close` frees the images kept)\n */\nexport function resampler(cached = SOURCE_CACHE): { draw: DrawJob; close: () => void; cache: { capacity: number } } {\n  type Image = Promise<ImageBitmap | null>;\n  /** Tiles being drawn from each source image: an evicted one is closed once none is */\n  const users = new Map<Image, number>();\n  const evicted = new Set<Image>();\n  const close = (image: Image) => {\n    evicted.delete(image);\n    image.then(\n      (bitmap) => bitmap?.close(),\n      () => undefined,\n    );\n  };\n  /** Freed now, or once the tiles drawing from it are done */\n  const drop = (image: Image) => {\n    if (users.has(image)) evicted.add(image);\n    else close(image);\n  };\n  // Source images by URL: a request is shared by the tiles that need it, its signal is not theirs\n  const cache = new Lru<string, Image>(cached, drop);\n  const release = (image: Image) => {\n    const count = (users.get(image) ?? 1) - 1;\n    if (count > 0) users.set(image, count);\n    else {\n      users.delete(image);\n      if (evicted.has(image)) close(image);\n    }\n  };\n  const fetchImage = (url: string): Image => {\n    let image = cache.get(url);\n    if (!image) {\n      image = (async () => {\n        const response = await fetch(url);\n        if (response.status === 404 || response.status === 204 || response.status === 410) return null;\n        if (!response.ok) throw new Error(`isard: ${response.status} for a raster to reproject`);\n        return createImageBitmap(await response.blob());\n      })();\n      // A failure is not kept: the engine's retry fetches again\n      image.catch(() => cache.delete(url));\n      cache.set(url, image);\n    }\n    users.set(image, (users.get(image) ?? 0) + 1);\n    return image;\n  };\n  const draw: DrawJob = async (job, signal) => {\n    const pending = job.sources.map((s) => [s, fetchImage(s.url)] as const);\n    try {\n      const images = await Promise.all(pending.map(async ([s, image]) => [s, await image] as const));\n      signal.throwIfAborted();\n      if (!images.some(([, image]) => image)) return null;\n      const canvas = new OffscreenCanvas(job.width, job.height);\n      const context = canvas.getContext('2d', { willReadFrequently: true });\n      if (!context) throw new Error('isard: no 2D canvas to reproject the tiles');\n      for (const [s, image] of images) if (image) context.drawImage(image, s.x, s.y, s.w, s.h);\n      const mosaic = context.getImageData(0, 0, job.width, job.height).data;\n      const pixels = resample(mosaic, job.width, job.height, job.mesh, job.n, job.size);\n      return createImageBitmap(new ImageData(pixels, job.size, job.size), { premultiplyAlpha: 'none' });\n    } finally {\n      for (const [, image] of pending) release(image);\n    }\n  };\n  return {\n    draw,\n    cache,\n    close: () => {\n      for (const image of cache.values()) drop(image);\n      cache.clear();\n    },\n  };\n}\n"]}

package/dist/settings.d.ts

@@ -0,0 +1,39 @@
+import type { PngEncoding } from './terrain.ts';
+import type { AtmosphereOptions, BodyOptions, CelestialBody, LoadingMode, TerrainModel, TerrainOptions } from './types.ts';
+/** Decodes the relief tiles of a URL for the engine: 256 × 256 altitudes, null where there is no tile */
+export type TerrainLoader = (z: number, x: number, y: number, signal: AbortSignal) => Promise<Float32Array | null>;
+/** Settings replayed on a new engine after a WebGL context loss */
+export interface Settings {
+    body: Required<BodyOptions>;
+    zoomRange: [min: number, max: number];
+    maxPitch: number;
+    globe: boolean;
+    sky: boolean;
+    atmosphere: Float32Array | undefined;
+    terrain: {
+        url: string;
+        exaggeration: number;
+        maxZoom: number;
+        geoid: boolean;
+        /** Decodes the tiles of `url` for the engine (an encoding other than raw floats) */
+        loader?: TerrainLoader;
+        /** Credits of the model */
+        attribution?: string;
+    } | undefined;
+    loading: LoadingMode;
+    background: [r: number, g: number, b: number];
+    globeColor: [r: number, g: number, b: number];
+}
+/** A body from the option, its defaults filled in */
+export declare function bodySettings(body: CelestialBody | undefined): Required<BodyOptions>;
+/** The halo of an atmosphere for the engine (RGB 0-1 and its strength, the color's alpha): undefined for none */
+export declare function haloSettings(atmosphere: boolean | string): Float32Array | undefined;
+/** Relief settings from the option: undefined when off. On the Earth the Terrain Tiles by default (worldwide,
+ * Terrarium PNGs decoded by `terrainLoader`) or the IGN terrain model (France, raised by the geoid); NASA's on the Moon
+ * and Mars; an ArcGIS image service asked for in the body's Mercator. `terrainLoader`: the loader of PNG tiles in an
+ * encoding, the same for the same tiles (the engine keeps its tiles when only the exaggeration changes) */
+export declare function terrainSettings(terrain: boolean | TerrainModel | TerrainOptions | undefined, body: CelestialBody | undefined, radius: number, terrainLoader: (url: string, encoding: PngEncoding, floor?: number) => TerrainLoader): Settings['terrain'];
+/** Sky settings for the engine: colors (RGB 0-1) and blends, MapLibre's defaults */
+export declare function atmosphereSettings(options: AtmosphereOptions | undefined): Float32Array | undefined;
+/** A CSS color to RGB 0-1 (its alpha dropped); black if unknown */
+export declare function rgb(color: string): [r: number, g: number, b: number];

package/dist/settings.js

@@ -0,0 +1,104 @@
+/**
+ * The settings of a map's engine from its options: the body, its halo, its relief, the sky. Kept by the map and
+ * replayed on a new engine (after a context loss, or on the engine with 3D Tiles).
+ */
+import { BODY_TERRAINS, IGN_ATTRIBUTION, IMAGE_SERVER, imageServerTerrain, TERRAIN_TILES, TERRAIN_TILES_ATTRIBUTION, TERRAIN_URL, } from "./basemaps.js";
+import { parseCssColor } from "./color.js";
+/** The named bodies; a body's `color` is that of its globe under the tiles (the Earth's follows its basemap), its
+ * `relief` the range of its ground (the Earth's dry land, from the Dead Sea to Everest). Mars: the sphere of its
+ * equatorial radius (its data take planetocentric latitudes), a faint butterscotch halo of dust */
+const BODIES = {
+    earth: { radius: 6378137, flattening: 1 / 298.257223563, atmosphere: true, color: '#cacaca', relief: [-450, 8900] },
+    moon: { radius: 1737400, flattening: 0, atmosphere: false, color: '#77756f', relief: [-9200, 10800] },
+    mars: {
+        radius: 3396190,
+        flattening: 0,
+        atmosphere: 'rgba(232, 168, 120, 0.6)',
+        color: '#b5714a',
+        relief: [-8300, 21300],
+    },
+};
+/** The Earth's halo, RGB 0-1 and its strength: what `atmosphere: true` draws */
+const EARTH_HALO = Float32Array.of(0.42, 0.66, 1, 1);
+/** A body from the option, its defaults filled in */
+export function bodySettings(body) {
+    if (body === undefined || typeof body === 'string')
+        return BODIES[body ?? 'earth'];
+    const relief = [-0.01 * body.radius, 0.01 * body.radius];
+    return { flattening: 0, atmosphere: false, color: '#808080', relief, ...body };
+}
+/** The halo of an atmosphere for the engine (RGB 0-1 and its strength, the color's alpha): undefined for none */
+export function haloSettings(atmosphere) {
+    if (atmosphere === true)
+        return EARTH_HALO;
+    const color = atmosphere === false ? undefined : parseCssColor(atmosphere);
+    return color && Float32Array.from(color);
+}
+/** Relief settings from the option: undefined when off. On the Earth the Terrain Tiles by default (worldwide,
+ * Terrarium PNGs decoded by `terrainLoader`) or the IGN terrain model (France, raised by the geoid); NASA's on the Moon
+ * and Mars; an ArcGIS image service asked for in the body's Mercator. `terrainLoader`: the loader of PNG tiles in an
+ * encoding, the same for the same tiles (the engine keeps its tiles when only the exaggeration changes) */
+export function terrainSettings(terrain, body, radius, terrainLoader) {
+    if (!terrain)
+        return undefined;
+    let options = {};
+    if (typeof terrain === 'string')
+        options = { model: terrain };
+    else if (terrain !== true)
+        options = terrain;
+    const earth = (body ?? 'earth') === 'earth';
+    const exaggeration = options.exaggeration ?? 1;
+    if (options.url === undefined && earth) {
+        if (options.model === 'ign') {
+            const geoid = options.geoid ?? true;
+            return { url: TERRAIN_URL, exaggeration, maxZoom: options.maxZoom ?? 15, geoid, attribution: IGN_ATTRIBUTION };
+        }
+        return {
+            url: TERRAIN_TILES.url,
+            exaggeration,
+            maxZoom: options.maxZoom ?? TERRAIN_TILES.maxZoom,
+            geoid: options.geoid ?? false,
+            // The sea floor of the model at sea level: the oceans stay flat under the basemap's water
+            loader: terrainLoader(TERRAIN_TILES.url, 'terrarium', 0),
+            attribution: TERRAIN_TILES_ATTRIBUTION,
+        };
+    }
+    const preset = body === 'moon' || body === 'mars' ? BODY_TERRAINS[body] : undefined;
+    const url = options.url ?? preset?.url;
+    if (url === undefined)
+        throw new Error('isard: the relief of this body needs a url');
+    const encoding = options.encoding ?? 'float32';
+    // PNG encodings are fetched tile by tile: a {bbox} or an image service would be fetched as it is
+    if (encoding !== 'float32' &&
+        (IMAGE_SERVER.test(url) || !/\{z\}/.test(url) || !/\{x\}/.test(url) || !/\{y\}/.test(url))) {
+        throw new Error(`isard: the '${encoding}' terrain encoding takes a tile URL with {z}, {x} and {y} (${url})`);
+    }
+    return {
+        url: IMAGE_SERVER.test(url) ? imageServerTerrain(url, earth, radius) : url,
+        exaggeration,
+        maxZoom: options.maxZoom ?? (options.url === undefined && preset ? preset.maxZoom : 15),
+        geoid: options.geoid ?? false,
+        ...(encoding === 'float32' ? {} : { loader: terrainLoader(url, encoding) }),
+        // NASA's credits for its models
+        ...(options.url === undefined && preset ? { attribution: preset.attribution } : {}),
+    };
+}
+/** Sky settings for the engine: colors (RGB 0-1) and blends, MapLibre's defaults */
+export function atmosphereSettings(options) {
+    if (!options)
+        return undefined;
+    return Float32Array.from([
+        ...rgb(options.skyColor ?? '#9cc7ec'),
+        ...rgb(options.horizonColor ?? '#e8f1f8'),
+        ...rgb(options.fogColor ?? '#f2f5f8'),
+        options.skyHorizonBlend ?? 0.6,
+        options.horizonFogBlend ?? 0.7,
+        options.fogGroundBlend ?? 0.4,
+    ]);
+}
+/** A CSS color to RGB 0-1 (its alpha dropped); black if unknown */
+export function rgb(color) {
+    const [r, g, b] = parseCssColor(color) ?? [0, 0, 0, 1];
+    return [r, g, b];
+}
+//# sourceMappingURL=settings.js.map

package/dist/settings.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"settings.js","sourceRoot":"","sources":["../src/settings.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EACL,aAAa,EACb,eAAe,EACf,YAAY,EACZ,kBAAkB,EAClB,aAAa,EACb,yBAAyB,EACzB,WAAW,GACZ,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAuC3C;;mGAEmG;AACnG,MAAM,MAAM,GAAuE;IACjF,KAAK,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,UAAU,EAAE,CAAC,GAAG,aAAa,EAAE,UAAU,EAAE,IAAI,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,EAAE,CAAC,CAAC,GAAG,EAAE,IAAI,CAAC,EAAE;IACnH,IAAI,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,UAAU,EAAE,CAAC,EAAE,UAAU,EAAE,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,EAAE,CAAC,CAAC,IAAI,EAAE,KAAK,CAAC,EAAE;IACrG,IAAI,EAAE;QACJ,MAAM,EAAE,OAAO;QACf,UAAU,EAAE,CAAC;QACb,UAAU,EAAE,0BAA0B;QACtC,KAAK,EAAE,SAAS;QAChB,MAAM,EAAE,CAAC,CAAC,IAAI,EAAE,KAAK,CAAC;KACvB;CACF,CAAC;AAEF,gFAAgF;AAChF,MAAM,UAAU,GAAG,YAAY,CAAC,EAAE,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;AAErD,qDAAqD;AACrD,MAAM,UAAU,YAAY,CAAC,IAA+B;IAC1D,IAAI,IAAI,KAAK,SAAS,IAAI,OAAO,IAAI,KAAK,QAAQ;QAAE,OAAO,MAAM,CAAC,IAAI,IAAI,OAAO,CAAC,CAAC;IACnF,MAAM,MAAM,GAAqB,CAAC,CAAC,IAAI,GAAG,IAAI,CAAC,MAAM,EAAE,IAAI,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC;IAC3E,OAAO,EAAE,UAAU,EAAE,CAAC,EAAE,UAAU,EAAE,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,CAAC;AACjF,CAAC;AAED,iHAAiH;AACjH,MAAM,UAAU,YAAY,CAAC,UAA4B;IACvD,IAAI,UAAU,KAAK,IAAI;QAAE,OAAO,UAAU,CAAC;IAC3C,MAAM,KAAK,GAAG,UAAU,KAAK,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,aAAa,CAAC,UAAU,CAAC,CAAC;IAC3E,OAAO,KAAK,IAAI,YAAY,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;AAC3C,CAAC;AAED;;;2GAG2G;AAC3G,MAAM,UAAU,eAAe,CAC7B,OAA4D,EAC5D,IAA+B,EAC/B,MAAc,EACd,aAAoF;IAEpF,IAAI,CAAC,OAAO;QAAE,OAAO,SAAS,CAAC;IAC/B,IAAI,OAAO,GAAmB,EAAE,CAAC;IACjC,IAAI,OAAO,OAAO,KAAK,QAAQ;QAAE,OAAO,GAAG,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC;SACzD,IAAI,OAAO,KAAK,IAAI;QAAE,OAAO,GAAG,OAAO,CAAC;IAC7C,MAAM,KAAK,GAAG,CAAC,IAAI,IAAI,OAAO,CAAC,KAAK,OAAO,CAAC;IAC5C,MAAM,YAAY,GAAG,OAAO,CAAC,YAAY,IAAI,CAAC,CAAC;IAC/C,IAAI,OAAO,CAAC,GAAG,KAAK,SAAS,IAAI,KAAK,EAAE,CAAC;QACvC,IAAI,OAAO,CAAC,KAAK,KAAK,KAAK,EAAE,CAAC;YAC5B,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,IAAI,IAAI,CAAC;YACpC,OAAO,EAAE,GAAG,EAAE,WAAW,EAAE,YAAY,EAAE,OAAO,EAAE,OAAO,CAAC,OAAO,IAAI,EAAE,EAAE,KAAK,EAAE,WAAW,EAAE,eAAe,EAAE,CAAC;QACjH,CAAC;QACD,OAAO;YACL,GAAG,EAAE,aAAa,CAAC,GAAG;YACtB,YAAY;YACZ,OAAO,EAAE,OAAO,CAAC,OAAO,IAAI,aAAa,CAAC,OAAO;YACjD,KAAK,EAAE,OAAO,CAAC,KAAK,IAAI,KAAK;YAC7B,0FAA0F;YAC1F,MAAM,EAAE,aAAa,CAAC,aAAa,CAAC,GAAG,EAAE,WAAW,EAAE,CAAC,CAAC;YACxD,WAAW,EAAE,yBAAyB;SACvC,CAAC;IACJ,CAAC;IACD,MAAM,MAAM,GAAG,IAAI,KAAK,MAAM,IAAI,IAAI,KAAK,MAAM,CAAC,CAAC,CAAC,aAAa,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IACpF,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,IAAI,MAAM,EAAE,GAAG,CAAC;IACvC,IAAI,GAAG,KAAK,SAAS;QAAE,MAAM,IAAI,KAAK,CAAC,4CAA4C,CAAC,CAAC;IACrF,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,SAAS,CAAC;IAC/C,iGAAiG;IACjG,IACE,QAAQ,KAAK,SAAS;QACtB,CAAC,YAAY,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAC1F,CAAC;QACD,MAAM,IAAI,KAAK,CAAC,eAAe,QAAQ,8DAA8D,GAAG,GAAG,CAAC,CAAC;IAC/G,CAAC;IACD,OAAO;QACL,GAAG,EAAE,YAAY,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,kBAAkB,CAAC,GAAG,EAAE,KAAK,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,GAAG;QAC1E,YAAY;QACZ,OAAO,EAAE,OAAO,CAAC,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,KAAK,SAAS,IAAI,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC;QACvF,KAAK,EAAE,OAAO,CAAC,KAAK,IAAI,KAAK;QAC7B,GAAG,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,aAAa,CAAC,GAAG,EAAE,QAAQ,CAAC,EAAE,CAAC;QAC3E,gCAAgC;QAChC,GAAG,CAAC,OAAO,CAAC,GAAG,KAAK,SAAS,IAAI,MAAM,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,MAAM,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACpF,CAAC;AACJ,CAAC;AAED,oFAAoF;AACpF,MAAM,UAAU,kBAAkB,CAAC,OAAsC;IACvE,IAAI,CAAC,OAAO;QAAE,OAAO,SAAS,CAAC;IAC/B,OAAO,YAAY,CAAC,IAAI,CAAC;QACvB,GAAG,GAAG,CAAC,OAAO,CAAC,QAAQ,IAAI,SAAS,CAAC;QACrC,GAAG,GAAG,CAAC,OAAO,CAAC,YAAY,IAAI,SAAS,CAAC;QACzC,GAAG,GAAG,CAAC,OAAO,CAAC,QAAQ,IAAI,SAAS,CAAC;QACrC,OAAO,CAAC,eAAe,IAAI,GAAG;QAC9B,OAAO,CAAC,eAAe,IAAI,GAAG;QAC9B,OAAO,CAAC,cAAc,IAAI,GAAG;KAC9B,CAAC,CAAC;AACL,CAAC;AAED,mEAAmE;AACnE,MAAM,UAAU,GAAG,CAAC,KAAa;IAC/B,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,GAAG,aAAa,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;IACvD,OAAO,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;AACnB,CAAC","sourcesContent":["/**\n * The settings of a map's engine from its options: the body, its halo, its relief, the sky. Kept by the map and\n * replayed on a new engine (after a context loss, or on the engine with 3D Tiles).\n */\nimport {\n  BODY_TERRAINS,\n  IGN_ATTRIBUTION,\n  IMAGE_SERVER,\n  imageServerTerrain,\n  TERRAIN_TILES,\n  TERRAIN_TILES_ATTRIBUTION,\n  TERRAIN_URL,\n} from './basemaps.ts';\nimport { parseCssColor } from './color.ts';\nimport type { PngEncoding } from './terrain.ts';\nimport type {\n  AtmosphereOptions,\n  BodyOptions,\n  CelestialBody,\n  LoadingMode,\n  TerrainModel,\n  TerrainOptions,\n} from './types.ts';\n\n/** Decodes the relief tiles of a URL for the engine: 256 × 256 altitudes, null where there is no tile */\nexport type TerrainLoader = (z: number, x: number, y: number, signal: AbortSignal) => Promise<Float32Array | null>;\n\n/** Settings replayed on a new engine after a WebGL context loss */\nexport interface Settings {\n  body: Required<BodyOptions>;\n  zoomRange: [min: number, max: number];\n  maxPitch: number;\n  globe: boolean;\n  sky: boolean;\n  atmosphere: Float32Array | undefined;\n  terrain:\n    | {\n        url: string;\n        exaggeration: number;\n        maxZoom: number;\n        geoid: boolean;\n        /** Decodes the tiles of `url` for the engine (an encoding other than raw floats) */\n        loader?: TerrainLoader;\n        /** Credits of the model */\n        attribution?: string;\n      }\n    | undefined;\n  loading: LoadingMode;\n  background: [r: number, g: number, b: number];\n  globeColor: [r: number, g: number, b: number];\n}\n\n/** The named bodies; a body's `color` is that of its globe under the tiles (the Earth's follows its basemap), its\n * `relief` the range of its ground (the Earth's dry land, from the Dead Sea to Everest). Mars: the sphere of its\n * equatorial radius (its data take planetocentric latitudes), a faint butterscotch halo of dust */\nconst BODIES: Record<Exclude<CelestialBody, BodyOptions>, Required<BodyOptions>> = {\n  earth: { radius: 6378137, flattening: 1 / 298.257223563, atmosphere: true, color: '#cacaca', relief: [-450, 8900] },\n  moon: { radius: 1737400, flattening: 0, atmosphere: false, color: '#77756f', relief: [-9200, 10800] },\n  mars: {\n    radius: 3396190,\n    flattening: 0,\n    atmosphere: 'rgba(232, 168, 120, 0.6)',\n    color: '#b5714a',\n    relief: [-8300, 21300],\n  },\n};\n\n/** The Earth's halo, RGB 0-1 and its strength: what `atmosphere: true` draws */\nconst EARTH_HALO = Float32Array.of(0.42, 0.66, 1, 1);\n\n/** A body from the option, its defaults filled in */\nexport function bodySettings(body: CelestialBody | undefined): Required<BodyOptions> {\n  if (body === undefined || typeof body === 'string') return BODIES[body ?? 'earth'];\n  const relief: [number, number] = [-0.01 * body.radius, 0.01 * body.radius];\n  return { flattening: 0, atmosphere: false, color: '#808080', relief, ...body };\n}\n\n/** The halo of an atmosphere for the engine (RGB 0-1 and its strength, the color's alpha): undefined for none */\nexport function haloSettings(atmosphere: boolean | string): Float32Array | undefined {\n  if (atmosphere === true) return EARTH_HALO;\n  const color = atmosphere === false ? undefined : parseCssColor(atmosphere);\n  return color && Float32Array.from(color);\n}\n\n/** Relief settings from the option: undefined when off. On the Earth the Terrain Tiles by default (worldwide,\n * Terrarium PNGs decoded by `terrainLoader`) or the IGN terrain model (France, raised by the geoid); NASA's on the Moon\n * and Mars; an ArcGIS image service asked for in the body's Mercator. `terrainLoader`: the loader of PNG tiles in an\n * encoding, the same for the same tiles (the engine keeps its tiles when only the exaggeration changes) */\nexport function terrainSettings(\n  terrain: boolean | TerrainModel | TerrainOptions | undefined,\n  body: CelestialBody | undefined,\n  radius: number,\n  terrainLoader: (url: string, encoding: PngEncoding, floor?: number) => TerrainLoader,\n): Settings['terrain'] {\n  if (!terrain) return undefined;\n  let options: TerrainOptions = {};\n  if (typeof terrain === 'string') options = { model: terrain };\n  else if (terrain !== true) options = terrain;\n  const earth = (body ?? 'earth') === 'earth';\n  const exaggeration = options.exaggeration ?? 1;\n  if (options.url === undefined && earth) {\n    if (options.model === 'ign') {\n      const geoid = options.geoid ?? true;\n      return { url: TERRAIN_URL, exaggeration, maxZoom: options.maxZoom ?? 15, geoid, attribution: IGN_ATTRIBUTION };\n    }\n    return {\n      url: TERRAIN_TILES.url,\n      exaggeration,\n      maxZoom: options.maxZoom ?? TERRAIN_TILES.maxZoom,\n      geoid: options.geoid ?? false,\n      // The sea floor of the model at sea level: the oceans stay flat under the basemap's water\n      loader: terrainLoader(TERRAIN_TILES.url, 'terrarium', 0),\n      attribution: TERRAIN_TILES_ATTRIBUTION,\n    };\n  }\n  const preset = body === 'moon' || body === 'mars' ? BODY_TERRAINS[body] : undefined;\n  const url = options.url ?? preset?.url;\n  if (url === undefined) throw new Error('isard: the relief of this body needs a url');\n  const encoding = options.encoding ?? 'float32';\n  // PNG encodings are fetched tile by tile: a {bbox} or an image service would be fetched as it is\n  if (\n    encoding !== 'float32' &&\n    (IMAGE_SERVER.test(url) || !/\\{z\\}/.test(url) || !/\\{x\\}/.test(url) || !/\\{y\\}/.test(url))\n  ) {\n    throw new Error(`isard: the '${encoding}' terrain encoding takes a tile URL with {z}, {x} and {y} (${url})`);\n  }\n  return {\n    url: IMAGE_SERVER.test(url) ? imageServerTerrain(url, earth, radius) : url,\n    exaggeration,\n    maxZoom: options.maxZoom ?? (options.url === undefined && preset ? preset.maxZoom : 15),\n    geoid: options.geoid ?? false,\n    ...(encoding === 'float32' ? {} : { loader: terrainLoader(url, encoding) }),\n    // NASA's credits for its models\n    ...(options.url === undefined && preset ? { attribution: preset.attribution } : {}),\n  };\n}\n\n/** Sky settings for the engine: colors (RGB 0-1) and blends, MapLibre's defaults */\nexport function atmosphereSettings(options: AtmosphereOptions | undefined): Float32Array | undefined {\n  if (!options) return undefined;\n  return Float32Array.from([\n    ...rgb(options.skyColor ?? '#9cc7ec'),\n    ...rgb(options.horizonColor ?? '#e8f1f8'),\n    ...rgb(options.fogColor ?? '#f2f5f8'),\n    options.skyHorizonBlend ?? 0.6,\n    options.horizonFogBlend ?? 0.7,\n    options.fogGroundBlend ?? 0.4,\n  ]);\n}\n\n/** A CSS color to RGB 0-1 (its alpha dropped); black if unknown */\nexport function rgb(color: string): [r: number, g: number, b: number] {\n  const [r, g, b] = parseCssColor(color) ?? [0, 0, 0, 1];\n  return [r, g, b];\n}\n"]}

package/dist/symbols.d.ts

@@ -1,10 +1,12 @@
 /**
- * Text labels from GeoJSON: at points, at the middle of lines, at the center of polygons. Shaped on the page, placed by
- * the engine every frame with collisions shared by all symbol layers (the top layer first, each layer in data order),
- * drawn with a halo, standing on the relief.
+ * Text labels and icons from GeoJSON: at points, at the middle of lines, at the center of polygons. Shaped on the page,
+ * placed by the engine every frame with collisions shared by all symbol layers (the top layer first, each layer in
+ * data order), drawn with a halo, standing on the relief. The icons are the map's images (`map.addImage`, a vector
+ * basemap's sprite), beside their text or stretched around it.
  */
 import { type Feature, type FeatureData, type FeatureLayerStyle, type Placement, type Properties, type Size, type Styled } from './features.ts';
 import { type Glyphs, type TextPart } from './glyphs.ts';
+import { type Icons } from './icons.ts';
 import { Layer } from './layers.ts';
 import type { Anchor } from './overlay.ts';
 import type { LayerHost } from './types.ts';
@@ -16,7 +18,7 @@ export interface SymbolStyle<P = Properties> extends Omit<FeatureLayerStyle<P>,
     /** CSS pixels, or zoom stops (default 12) */
     size: Styled<Size, P>;
     /** `'point'` (default): horizontal text; `'line'`: along the line at its middle, kept upright */
-    placement: 'point' | 'line';
+    placement: Styled<'point' | 'line', P>;
     color: Styled<string, P>;
     haloColor: Styled<string, P>;
     /** CSS pixels (default 0) */
@@ -29,31 +31,74 @@ export interface SymbolStyle<P = Properties> extends Omit<FeatureLayerStyle<P>,
     maxWidth: Styled<number, P>;
     /** Ems (default 1.2) */
     lineHeight: Styled<number, P>;
-    /** Shown even where it overlaps other labels, and hiding none (MapLibre's allow-overlap and ignore-placement)
-     * (default false) */
-    overlap: Styled<boolean, P>;
+    /** Shown even where it overlaps other labels, and hiding none (MapLibre's allow-overlap and ignore-placement);
+     * `'allow'`: shown even where it overlaps, still hiding the labels after it; `'ignore'`: shown only where it fits,
+     * hiding none (default false) */
+    overlap: Styled<Overlap, P>;
+    /** Shown without its icon where the icon does not fit (default false) */
+    textOptional: Styled<boolean, P>;
+    /** An image of the map (`map.addImage`); empty: none (default) */
+    icon: Styled<string, P>;
+    /** Scale of the image, or zoom stops (default 1) */
+    iconSize: Styled<Size, P>;
+    /** Side of the icon at the anchor (default `'center'`) */
+    iconAnchor: Styled<Anchor, P>;
+    /** Shift, CSS pixels at size 1 (default [0, 0]) */
+    iconOffset: Styled<[x: number, y: number], P>;
+    /** Degrees, clockwise (default 0) */
+    iconRotate: Styled<number, P>;
+    /** `'viewport'`: facing the screen; `'map'`: turning with the map, along its line when placed on one; `'auto'`
+     * (default): `'map'` with the `'line'` placement */
+    iconRotationAlignment: Styled<'map' | 'viewport' | 'auto', P>;
+    /** As `overlap`, for the icon (default false) */
+    iconOverlap: Styled<Overlap, P>;
+    /** Shown without its text where the text does not fit (default false) */
+    iconOptional: Styled<boolean, P>;
+    /** Stretched around its text: its width, its height, both (a road shield; `'none'` by default) */
+    iconTextFit: Styled<'none' | 'width' | 'height' | 'both', P>;
+    /** Room around the text of a fitted icon: top, right, bottom, left (CSS pixels, default 0) */
+    iconTextFitPadding: Styled<[top: number, right: number, bottom: number, left: number], P>;
+    /** Color of a signed distance field image (default black) */
+    iconColor: Styled<string, P>;
+    /** 0 to 1 (default 1) */
+    iconOpacity: Styled<number, P>;
 }
+/** How a label's text or icon meets the others: `true` shown wherever and hiding none, `'allow'` shown wherever,
+ * `'ignore'` hiding none, `false` neither (MapLibre's allow-overlap and ignore-placement) */
+export type Overlap = boolean | 'allow' | 'ignore';
 export interface SymbolOptions<P = Properties> extends Partial<SymbolStyle<P>>, Placement {
     data: FeatureData<P>;
 }
-/** The map's glyphs, for a layer */
+/** The map's glyphs and icons, for a layer */
 export interface GlyphHost extends LayerHost {
     readonly glyphs: Glyphs;
+    readonly icons: Icons;
 }
 export declare class SymbolLayer<P = Properties> extends Layer {
     private readonly host;
     private style;
     private list;
+    /** The features in groups that do not change (`setGroups`): each group's labels kept between updates */
+    private groups;
+    private readonly chunks;
     /** Bumped by each change: a shaping that finished after a newer one began is dropped */
     private generation;
+    /** Bumped by each change of style: the labels kept are shaped again */
+    private styleGeneration;
+    /** No style function takes the index of a feature: a group's labels do not depend on its place */
+    private indexFree;
     private labels;
     get features(): readonly Feature<P>[];
     setData(data: FeatureData<P>): void;
     setStyle(style: Partial<SymbolStyle<P>>): void;
     setFilter(filter: ((properties: P, index: number) => boolean) | undefined): void;
     setVisible(visible: boolean): void;
-    /** Shapes the labels (loading their glyphs first) and sends them */
+    private styled;
+    /** The runs of text of each feature of a group (none for a feature filtered out) */
+    private parts;
+    /** Shapes the labels (loading their glyphs first) and sends them; the groups' labels still valid are kept */
     private update;
+    /** The labels of a group of features, `base` the index of its first feature */
     private build;
     private send;
     private sendLayer;