Add Map.getImage()

CHANGELOG.md

@@ -3,6 +3,7 @@
 ### ✨ Features and improvements
 - Improve performance by sending style layers to worker thread before processing it on main thread to allow parallel processing ([#2131](https://github.com/maplibre/maplibre-gl-js/pull/2131))
 - [Breaking] Resize map when container element is resized. the resize related events now has different data associated with it ([#2157](https://github.com/maplibre/maplibre-gl-js/pull/2157))
+- Add Map.getImage() to retrieve previously-loaded images. ([#2168](https://github.com/maplibre/maplibre-gl-js/pull/2168))
 - *...Add new stuff here...*
 
 ### 🐞 Bug fixes

src/ui/map.test.ts

@@ -17,6 +17,7 @@ import {CameraOptions} from './camera';
 import Terrain, {} from '../render/terrain';
 import {mercatorZfromAltitude} from '../geo/mercator_coordinate';
 import Transform from '../geo/transform';
+import {StyleImageInterface} from '../style/style_image';
 
 function createStyleSource() {
     return {
@@ -2204,6 +2205,102 @@ describe('Map', () => {
         });
     });
 
+    test('map getImage matches addImage, uintArray', () => {
+        const map = createMap();
+        const id = 'add-get-uint';
+        const inputImage = {width: 2, height: 1, data: new Uint8Array(8)};
+
+        map.addImage(id, inputImage);
+        expect(map.hasImage(id)).toBeTruthy();
+
+        const gotImage = map.getImage(id);
+        expect(gotImage.data.width).toEqual(inputImage.width);
+        expect(gotImage.data.height).toEqual(inputImage.height);
+        expect(gotImage.sdf).toBe(false);
+    });
+
+    test('map getImage matches addImage, uintClampedArray', () => {
+        const map = createMap();
+        const id = 'add-get-uint-clamped';
+        const inputImage = {width: 1, height: 2, data: new Uint8ClampedArray(8)};
+
+        map.addImage(id, inputImage);
+        expect(map.hasImage(id)).toBeTruthy();
+
+        const gotImage = map.getImage(id);
+        expect(gotImage.data.width).toEqual(inputImage.width);
+        expect(gotImage.data.height).toEqual(inputImage.height);
+        expect(gotImage.sdf).toBe(false);
+    });
+
+    test('map getImage matches addImage, ImageData', () => {
+        const map = createMap();
+        const id = 'add-get-image-data';
+        const inputImage = new ImageData(1, 3);
+
+        map.addImage(id, inputImage);
+        expect(map.hasImage(id)).toBeTruthy();
+
+        const gotImage = map.getImage(id);
+        expect(gotImage.data.width).toEqual(inputImage.width);
+        expect(gotImage.data.height).toEqual(inputImage.height);
+        expect(gotImage.sdf).toBe(false);
+    });
+
+    test('map getImage matches addImage, StyleImageInterface uint', () => {
+        const map = createMap();
+        const id = 'add-get-style-image-iface-uint';
+        const inputImage: StyleImageInterface = {
+            width: 3,
+            height: 1,
+            data: new Uint8Array(12)
+        };
+
+        map.addImage(id, inputImage);
+        expect(map.hasImage(id)).toBeTruthy();
+
+        const gotImage = map.getImage(id);
+        expect(gotImage.data.width).toEqual(inputImage.width);
+        expect(gotImage.data.height).toEqual(inputImage.height);
+        expect(gotImage.sdf).toBe(false);
+    });
+
+    test('map getImage matches addImage, StyleImageInterface clamped', () => {
+        const map = createMap();
+        const id = 'add-get-style-image-iface-clamped';
+        const inputImage: StyleImageInterface = {
+            width: 4,
+            height: 1,
+            data: new Uint8ClampedArray(16)
+        };
+
+        map.addImage(id, inputImage);
+        expect(map.hasImage(id)).toBeTruthy();
+
+        const gotImage = map.getImage(id);
+        expect(gotImage.data.width).toEqual(inputImage.width);
+        expect(gotImage.data.height).toEqual(inputImage.height);
+        expect(gotImage.sdf).toBe(false);
+    });
+
+    test('map getImage matches addImage, StyleImageInterface SDF', () => {
+        const map = createMap();
+        const id = 'add-get-style-image-iface-sdf';
+        const inputImage: StyleImageInterface = {
+            width: 5,
+            height: 1,
+            data: new Uint8Array(20)
+        };
+
+        map.addImage(id, inputImage, {sdf: true});
+        expect(map.hasImage(id)).toBeTruthy();
+
+        const gotImage = map.getImage(id);
+        expect(gotImage.data.width).toEqual(inputImage.width);
+        expect(gotImage.data.height).toEqual(inputImage.height);
+        expect(gotImage.sdf).toBe(true);
+    });
+
     test('map does not fire `styleimagemissing` for empty icon values', done => {
         const map = createMap();
 

src/ui/map.ts

@@ -36,7 +36,7 @@ import type {LngLatBoundsLike} from '../geo/lng_lat_bounds';
 import type {FeatureIdentifier, StyleOptions, StyleSetterOptions} from '../style/style';
 import type {MapEvent, MapDataEvent} from './events';
 import type {CustomLayerInterface} from '../style/style_layer/custom_style_layer';
-import type {StyleImageInterface, StyleImageMetadata} from '../style/style_image';
+import type {StyleImage, StyleImageInterface, StyleImageMetadata} from '../style/style_image';
 import type {PointLike} from './camera';
 import type ScrollZoomHandler from './handler/scroll_zoom';
 import type BoxZoomHandler from './handler/box_zoom';
@@ -1909,6 +1909,22 @@ class Map extends Camera {
         this.style.updateImage(id, existingImage);
     }
 
+    /**
+     * Returns an image, specified by ID, currently available in the map.
+     * This includes both images from the style's original sprite
+     * and any images that have been added at runtime using {@link Map#addImage}.
+     *
+     * @param id The ID of the image.
+     * @returns {StyleImage} An image in the map with the specified ID.
+     *
+     * @example
+     * var coffeeShopIcon = map.getImage("coffee_cup");
+     *
+     */
+    getImage(id: string): StyleImage {
+        return this.style.getImage(id);
+    }
+
     /**
      * Check whether or not an image with a specific ID exists in the style. This checks both images
      * in the style's original sprite and any images