Treat an empty raster or raster-DEM tile response as no data (#1551) (#8207)

* Represent an empty tile response as no data instead of a fake 1x1 image

Since #3428 an empty (HTTP 204) response was decoded into a fabricated
1x1 ImageBitmap so that empty raster tiles could be cached. That marker
leaked into every image consumer: for raster-dem it became a DEM with
dim 1 whose backfillBorder against a real neighbor threw "dem dimension
mismatch" and broke terrain rendering (#1551).

ImageRequest now resolves an empty payload with null data, keeping the
expiry headers. Raster and raster-dem sources mark such tiles loaded
without content. The image source, sprite loading and Map.loadImage
surface an explicit error instead of silently using a 1x1 image.

Co-Authored-By: Claude <noreply@anthropic.com>

* Skip color-relief tiles without a DEM before reading from it

A loaded raster-dem tile can now carry no DEM at all, and the first-tile setup
reads getUnpackVector() from it before the existing guard is reached, so a
colour-relief layer threw on every frame where an empty tile sorted first.

Reported by @johncarmack1984 in review.

Co-Authored-By: Claude <noreply@anthropic.com>

* Apply review suggestions: drop the unreachable transparent fallback, document the rejection

An empty response no longer reaches getImageUsingCreateImageBitmap, so the
byteLength branch and its transparent placeholder can go. loadImage now says it
rejects when the response carries no image data.

Suggested by @johncarmack1984 in review.

Co-Authored-By: Claude <noreply@anthropic.com>

* Apply review suggestions

Shorter changelog entry, the two inline explanations moved into tsdoc,
and a plain else in image_source: transformAndGetImage resolves a
response object or throws, never undefined.

* Update CHANGELOG.md

---------

Co-authored-by: Claude <noreply@anthropic.com>
Co-authored-by: Harel M <harel.mazor@gmail.com>

Author: 3 people

CHANGELOG.md

@@ -3,6 +3,7 @@
 - _...Add new stuff here..._
 
 ### 🐞 Bug fixes
+- Treat an empty tile response (e.g. HTTP 204) as no data: raster-DEM tiles now load without elevation instead of failing with a `dem dimension mismatch` error, and empty raster tiles render as transparent ([#1551](https://github.com/maplibre/maplibre-gl-js/issues/1551)) (by [@clement-igonet](https://github.com/clement-igonet))
 - _...Add new stuff here..._
 
 ## 6.7.0

src/source/image_source.ts

@@ -265,6 +265,8 @@ export class ImageSource extends Evented<SourceEventType> implements Source {
                     this.coordinates = newCoordinates;
                 }
                 this._finishLoading();
+            } else {
+                this.fire(new ErrorEvent(new Error(`Could not load image ${this.url}: the response is empty`)));
             }
         } catch (err) {
             // In case of abort error, the aborter may have started a new request so we don't want to clear its abort controller.

src/source/raster_dem_tile_source.test.ts

@@ -107,6 +107,32 @@ describe('RasterDEMTileSource', () => {
         expect(getImageSpy.mock.calls[0][3]).toEqual({colorSpaceConversion: 'none'});
     });
 
+    test('an empty tile response loads as a tile without DEM data', async () => {
+        server.respondWith('/source.json', JSON.stringify({
+            minzoom: 0,
+            maxzoom: 22,
+            tiles: ['http://example.com/{z}/{x}/{y}.png']
+        }));
+        const source = createSource({url: '/source.json'});
+        vi.spyOn(ImageRequest, 'getImage').mockResolvedValue({data: null});
+        const promise = waitForMetadataEvent(source);
+        await sleep(0);
+        server.respond();
+        await promise;
+        const tile = {
+            tileID: new OverscaledTileID(10, 0, 10, 5, 5),
+            state: 'loading',
+            loadVectorData () {},
+            setExpiryData() {},
+            actor: {sendAsync: vi.fn()}
+        } as any as Tile;
+        await source.loadTile(tile);
+
+        expect(tile.state).toBe('loaded');
+        expect(tile.dem).toBeUndefined();
+        expect((tile.actor as any).sendAsync).not.toHaveBeenCalled();
+    });
+
     test('can asynchronously transform tile request', async () => {
         server.respondWith('http://example.com/10/5/5.png',
             [200, {'Content-Type': 'image/png', 'Content-Length': 1, 'Cache-Control': 'max-age=100'}, '0']

src/source/raster_dem_tile_source.ts

@@ -64,11 +64,18 @@ export class RasterDEMTileSource extends RasterTileSource implements Source {
                 tile.state = 'unloaded';
                 return;
             }
-            if (response?.data) {
-                const img = response.data;
+            if (response) {
                 if (this.map._refreshExpiredTiles && (response.cacheControl || response.expires)) {
                     tile.setExpiryData({cacheControl: response.cacheControl, expires: response.expires});
                 }
+                // An empty response (e.g. HTTP 204 for a missing DEM tile) carries no elevation
+                // data: treat the tile as loaded without a DEM instead of building a degenerate
+                // one that would fail against its neighbors in backfillBorder (#1551).
+                if (!response.data) {
+                    tile.state = 'loaded';
+                    return;
+                }
+                const img = response.data;
                 const transfer = isImageBitmap(img) && offscreenCanvasSupported();
                 const rawImageData = transfer ? img : await this.readImageNow(img);
                 const params = {

src/source/raster_tile_source.test.ts

@@ -160,6 +160,34 @@ describe('RasterTileSource', () => {
         expect(transformSpy.mock.calls[0][1]).toBe('Tile');
     });
 
+    test('an empty tile response loads as a transparent tile, so the parent does not show through', async () => {
+        server.respondWith('/source.json', JSON.stringify({
+            minzoom: 0,
+            maxzoom: 22,
+            tiles: ['http://example.com/{z}/{x}/{y}.png']
+        }));
+        const source = createSource({url: '/source.json'});
+        vi.spyOn(ImageRequest, 'getImage').mockResolvedValue({data: null});
+        const update = vi.fn();
+        source.map.painter = {context: {}, getTileTexture: () => ({update})} as any;
+        const promise = waitForEvent(source, 'data', (e: MapSourceDataEvent) => e.sourceDataType === 'metadata');
+        await sleep(0);
+        server.respond();
+        await promise;
+        const tile = {
+            tileID: new OverscaledTileID(10, 0, 10, 5, 5),
+            state: 'loading',
+            loadVectorData () {},
+            setExpiryData() {}
+        } as any as Tile;
+        await source.loadTile(tile);
+
+        expect(tile.state).toBe('loaded');
+        expect(update).toHaveBeenCalledWith(
+            expect.objectContaining({width: 1, height: 1, data: new Uint8Array(4)}),
+            expect.anything());
+    });
+
     test('can asynchronously transform tile request', async () => {
         server.respondWith('http://example.com/10/5/5.png',
             [200, {'Content-Type': 'image/png', 'Content-Length': 1, 'Cache-Control': 'max-age=100'}, '0']

src/source/raster_tile_source.ts

@@ -8,6 +8,7 @@ import {MapSourceDataEvent, type SourceEventType} from '../ui/events.ts';
 import {loadTileJson} from './load_tilejson.ts';
 import {TileBounds} from '../tile/tile_bounds.ts';
 import {Texture} from '../webgl/texture.ts';
+import {RGBAImage} from '../util/image.ts';
 import {isAbortError} from '../util/abort_error.ts';
 
 import type {Source} from './source.ts';
@@ -221,13 +222,16 @@ export class RasterTileSource extends Evented<SourceEventType> implements Source
                 tile.state = 'unloaded';
                 return;
             }
-            if (response?.data) {
+            if (response) {
                 if (this.map._refreshExpiredTiles && (response.cacheControl || response.expires)) {
                     tile.setExpiryData({cacheControl: response.cacheControl, expires: response.expires});
                 }
                 const context = this.map.painter.context;
                 const gl = context.gl;
-                const img = response.data;
+                // An empty response (e.g. HTTP 204) is a tile that exists but has no content:
+                // it is drawn as fully transparent, which keeps it distinct from a missing
+                // tile (404), where the parent tile shows through instead.
+                const img = response.data ?? new RGBAImage({width: 1, height: 1}, new Uint8Array(4));
                 tile.texture = this.map.painter.getTileTexture(img.width);
                 if (tile.texture) {
                     tile.texture.update(img, {useMipmap: true, premultiply});

src/style/load_sprite.ts

@@ -62,7 +62,11 @@ async function doOnceCompleted(
     for (const spriteName in jsonsMap) {
         result[spriteName] = {};
 
-        const context = browser.getImageCanvasContext((await imagesMap[spriteName]).data);
+        const image = (await imagesMap[spriteName]).data;
+        if (!image) {
+            throw new Error(`Could not load sprite image for ${spriteName}: the response is empty`);
+        }
+        const context = browser.getImageCanvasContext(image);
         const json = (await jsonsMap[spriteName]).data;
 
         for (const id in json) {

src/ui/map.ts

@@ -3359,7 +3359,7 @@ export class Map extends Evented<MapEventType> {
      * domains must support [CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/Access_control_CORS).
      *
      * @param url - The URL of the image file. Image file must be in png, webp, or jpg format.
-     * @returns a promise that is resolved when the image is loaded
+     * @returns a promise that is resolved when the image is loaded, or rejected when the response has no image data (for example an HTTP 204)
      *
      * @example
      * Load an image from an external URL.
@@ -3371,7 +3371,11 @@ export class Map extends Evented<MapEventType> {
      * @see [Add an icon to the map](https://maplibre.org/maplibre-gl-js/docs/examples/add-an-icon-to-the-map/)
      */
     async loadImage(url: string): Promise<GetResourceResponse<HTMLImageElement | ImageBitmap>> {
-        return ImageRequest.getImage(await this._requestManager.transformRequest(url, ResourceType.Image), new AbortController());
+        const response = await ImageRequest.getImage(await this._requestManager.transformRequest(url, ResourceType.Image), new AbortController());
+        if (!response.data) {
+            throw new Error(`Could not load image ${url}: the response is empty`);
+        }
+        return response;
     }
 
     /**

src/util/image_request.test.ts

@@ -131,11 +131,29 @@ describe('ImageRequest', () => {
         expect(createImageBitmapSpy).toHaveBeenCalledWith(expect.any(Blob), options);
     });
 
-    test('getImage using createImageBitmap throws exception', async () => {
+    test('getImage resolves an empty response (e.g. HTTP 204) with null data and keeps the expiry headers', async () => {
         server.respondWith(request => { request.respond(200, {'Content-Type': 'image/png',
             'Cache-Control': 'cache',
             'Expires': 'expires'}, ''); });
 
+        const createImageBitmapSpy = vi.fn();
+        stubAjaxGetImage(createImageBitmapSpy);
+        const promise = ImageRequest.getImage({url: ''}, new AbortController());
+        server.respond();
+
+        const response = await promise;
+
+        expect(response.data).toBeNull();
+        expect(response.cacheControl).toBe('cache');
+        expect(response.expires).toBe('expires');
+        expect(createImageBitmapSpy).not.toHaveBeenCalled();
+    });
+
+    test('getImage using createImageBitmap throws exception', async () => {
+        server.respondWith(request => { request.respond(200, {'Content-Type': 'image/png',
+            'Cache-Control': 'cache',
+            'Expires': 'expires'}, '0'); });
+
         stubAjaxGetImage(() => Promise.reject(new Error('error')));
 
         const promise = ImageRequest.getImage({url: ''}, new AbortController());
@@ -149,7 +167,7 @@ describe('ImageRequest', () => {
         const makeRequestSky = vi.spyOn(ajax, 'makeRequest');
         server.respondWith(request => { request.respond(200, {'Content-Type': 'image/png',
             'Cache-Control': 'cache',
-            'Expires': 'expires'}, ''); });
+            'Expires': 'expires'}, '0'); });
 
         const promise = ImageRequest.getImage({url: ''}, new AbortController());
 

src/util/image_request.ts

@@ -172,6 +172,13 @@ export namespace ImageRequest {
         }
     };
 
+    /**
+     * Runs one queued image request.
+     *
+     * An empty response body (e.g. HTTP 204 for a tile without content) resolves with
+     * `data: null`, keeping the expiry headers, so callers can handle the absence
+     * explicitly and re-request when the headers say so.
+     */
     const doImageRequest = async (itemInQueue: ImageRequestQueueItem) => {
         itemInQueue.state = 'running';
         const {requestParameters, supportImageRefresh, imageBitmapOptions, onError, onSuccess, abortController} = itemInQueue;
@@ -205,7 +212,9 @@ export namespace ImageRequest {
                 // User using addProtocol can directly return HTMLImageElement/ImageBitmap type
                 // If HtmlImageElement is used to get image then response type will be HTMLImageElement
                 onSuccess(response);
-            } else if (response.data) {
+            } else if (!response.data || response.data.byteLength === 0) {
+                onSuccess({data: null, cacheControl: response.cacheControl, expires: response.expires});
+            } else {
                 const img = await arrayBufferToCanvasImageSource(response.data, imageBitmapOptions);
                 onSuccess({data: img, cacheControl: response.cacheControl, expires: response.expires});
             }