Skip to content

Kepler.gl is a powerful open source geospatial analysis tool for large-scale data sets.

fix(raster-tile): fix stuck black tiles for raster tile layer (#3598)

Igor Dykhta288c782bd355
diff --git a/src/components/src/side-panel/layer-panel/raster-tile-layer-configurator.tsx b/src/components/src/side-panel/layer-panel/raster-tile-layer-configurator.tsx
index f28b50926..ccc90a73a 100644
--- a/src/components/src/side-panel/layer-panel/raster-tile-layer-configurator.tsx
+++ b/src/components/src/side-panel/layer-panel/raster-tile-layer-configurator.tsx
@@ -474,6 +474,10 @@ function RasterTileLayerConfiguratorFactory(
{...visConfiguratorProps}
{...layer.visConfigSettings.showTileBorders}
/>
+ <VisConfigSwitch
+ {...visConfiguratorProps}
+ {...layer.visConfigSettings.showTileDebugInfo}
+ />
<VisConfigSlider {...visConfiguratorProps} {...layer.visConfigSettings.zoomOffset} />
</ConfigGroupCollapsibleContent>
</LayerConfigGroup>
@@ -709,6 +713,10 @@ function RasterTileLayerConfiguratorFactory(
{...visConfiguratorProps}
{...layer.visConfigSettings.showTileBorders}
/>
+ <VisConfigSwitch
+ {...visConfiguratorProps}
+ {...layer.visConfigSettings.showTileDebugInfo}
+ />
<VisConfigSlider {...visConfiguratorProps} {...layer.visConfigSettings.zoomOffset} />
</ConfigGroupCollapsibleContent>
</LayerConfigGroup>
diff --git a/src/deckgl-layers/src/raster/images.ts b/src/deckgl-layers/src/raster/images.ts
index d2ff7e7ed..cbd11742d 100644
--- a/src/deckgl-layers/src/raster/images.ts
+++ b/src/deckgl-layers/src/raster/images.ts
@@ -84,6 +84,16 @@ function loadImageItem(
return result;
}
+/**
+ * Load image items to webgl context
+ */
+type LoadImagesResult = {
+ /** Updated images state, or null if nothing changed */
+ images: ImageState | null;
+ /** True when at least one texture upload failed and should be retried */
+ hasPendingUploads: boolean;
+};
+
// eslint-disable-next-line complexity
export function loadImages({
gl,
@@ -91,8 +101,9 @@ export function loadImages({
images,
imagesData,
oldImagesData
-}: LoadImagesOptions): ImageState | null {
+}: LoadImagesOptions): LoadImagesResult {
let imagesDirty = false;
+ let hasPendingUploads = false;
if (oldImagesData) {
for (const key in oldImagesData) {
@@ -124,15 +135,18 @@ export function loadImages({
const loadedItem = loadImageItem(gl, device, imageData);
if (loadedItem) {
images[key] = loadedItem;
+ // Only mark dirty when the texture was actually uploaded.
+ imagesDirty = true;
+ } else {
+ // Upload failed (device not ready or createTexture threw). Signal that
+ // the caller should retry next frame — do NOT set imagesDirty so we
+ // don't propagate an images object with a missing key that causes
+ // draw() to bail permanently.
+ hasPendingUploads = true;
}
- imagesDirty = true;
- }
-
- if (imagesDirty) {
- return images;
}
- return null;
+ return {images: imagesDirty ? images : null, hasPendingUploads};
}
/**
diff --git a/src/deckgl-layers/src/raster/raster-layer/raster-layer.ts b/src/deckgl-layers/src/raster/raster-layer/raster-layer.ts
index baec755a5..4ab77b740 100644
--- a/src/deckgl-layers/src/raster/raster-layer/raster-layer.ts
+++ b/src/deckgl-layers/src/raster/raster-layer/raster-layer.ts
@@ -31,6 +31,10 @@ export default class RasterLayer extends BitmapLayer<RasterLayerAddedProps> {
};
_redrawScheduled = false;
+ _pendingImageRetry: RasterLayerAddedProps['images'] | null = null;
+ /** How many consecutive frames have retried a failed texture upload. */
+ _imageRetryCount = 0;
+ static readonly MAX_IMAGE_RETRY_ATTEMPTS = 3;
initializeState(): void {
patchPipelineValidation();
@@ -40,6 +44,40 @@ export default class RasterLayer extends BitmapLayer<RasterLayerAddedProps> {
}
draw(_opts: {shaderModuleProps: Record<string, unknown>}): void {
+ // If a previous frame had failed texture uploads, retry them now before
+ // checking whether the images state is complete. Pass oldImagesData: {} so
+ // all keys are treated as new and bypass the isEqual skip-check.
+ // Retries are bounded to MAX_IMAGE_RETRY_ATTEMPTS to avoid an infinite
+ // redraw loop when image data is permanently invalid.
+ if (this._pendingImageRetry) {
+ const retry = this._pendingImageRetry;
+ this._pendingImageRetry = null;
+ const {images: newImages, hasPendingUploads} = loadImages({
+ gl: this.context.device?.gl || this.context.gl,
+ device: this.context.device,
+ images: this.state.images,
+ imagesData: retry,
+ oldImagesData: {}
+ });
+ if (newImages) {
+ this.setState({images: newImages});
+ }
+ if (hasPendingUploads) {
+ this._imageRetryCount++;
+ if (this._imageRetryCount < RasterLayer.MAX_IMAGE_RETRY_ATTEMPTS) {
+ this._pendingImageRetry = retry;
+ this._scheduleRedraw();
+ } else {
+ console.warn(
+ `RasterLayer: texture upload failed after ${RasterLayer.MAX_IMAGE_RETRY_ATTEMPTS} attempts, giving up.`
+ );
+ this._imageRetryCount = 0;
+ }
+ } else {
+ this._imageRetryCount = 0;
+ }
+ }
+
const {model, images, coordinateConversion, bounds} = this.state;
const {desaturate, transparentColor, tintColor, moduleProps} = this.props;
@@ -158,7 +196,7 @@ export default class RasterLayer extends BitmapLayer<RasterLayerAddedProps> {
const device = this.context.device;
const gl = device?.gl || this.context.gl;
- const newImages = loadImages({
+ const {images: newImages, hasPendingUploads} = loadImages({
gl,
device,
images,
@@ -168,6 +206,14 @@ export default class RasterLayer extends BitmapLayer<RasterLayerAddedProps> {
if (newImages) {
this.setState({images: newImages});
}
+ // If any texture upload failed (device not ready / createTexture threw),
+ // stash the imagesData and schedule a retry next frame. The retry passes
+ // oldImagesData: {} so all keys bypass the isEqual skip-check.
+ if (hasPendingUploads) {
+ this._pendingImageRetry = props.images;
+ this._imageRetryCount = 0;
+ this._scheduleRedraw();
+ }
}
finalizeState(): void {
diff --git a/src/deckgl-layers/src/raster/raster-mesh-layer/raster-mesh-layer.ts b/src/deckgl-layers/src/raster/raster-mesh-layer/raster-mesh-layer.ts
index 67d343cd1..58a31bde2 100644
--- a/src/deckgl-layers/src/raster/raster-mesh-layer/raster-mesh-layer.ts
+++ b/src/deckgl-layers/src/raster/raster-mesh-layer/raster-mesh-layer.ts
@@ -75,6 +75,10 @@ export default class RasterMeshLayer extends SimpleMeshLayer<any, RasterLayerAdd
};
_redrawScheduled = false;
+ _pendingImageRetry: RasterLayerAddedProps['images'] | null = null;
+ /** How many consecutive frames have retried a failed texture upload. */
+ _imageRetryCount = 0;
+ static readonly MAX_IMAGE_RETRY_ATTEMPTS = 3;
initializeState(): void {
patchPipelineValidation();
@@ -153,7 +157,7 @@ export default class RasterMeshLayer extends SimpleMeshLayer<any, RasterLayerAdd
const device = this.context.device;
const gl = device?.gl || this.context.gl;
- const newImages = loadImages({
+ const {images: newImages, hasPendingUploads} = loadImages({
gl,
device,
images,
@@ -164,9 +168,51 @@ export default class RasterMeshLayer extends SimpleMeshLayer<any, RasterLayerAdd
if (newImages) {
this.setState({images: newImages});
}
+ // If any texture upload failed, stash the imagesData and schedule a retry
+ // next frame. The retry passes oldImagesData: {} so all keys bypass the
+ // isEqual skip-check.
+ if (hasPendingUploads) {
+ this._pendingImageRetry = props.images;
+ this._imageRetryCount = 0;
+ this._scheduleRedraw();
+ }
}
draw(_opts: Record<string, unknown>): void {
+ // If a previous frame had failed texture uploads, retry them now before
+ // checking whether the images state is complete. Pass oldImagesData: {} so
+ // all keys are treated as new and bypass the isEqual skip-check.
+ // Retries are bounded to MAX_IMAGE_RETRY_ATTEMPTS to avoid an infinite
+ // redraw loop when image data is permanently invalid.
+ if (this._pendingImageRetry) {
+ const retry = this._pendingImageRetry;
+ this._pendingImageRetry = null;
+ const {images: newImages, hasPendingUploads} = loadImages({
+ gl: this.context.device?.gl || this.context.gl,
+ device: this.context.device,
+ images: this.state.images,
+ imagesData: retry,
+ oldImagesData: {}
+ });
+ if (newImages) {
+ this.setState({images: newImages});
+ }
+ if (hasPendingUploads) {
+ this._imageRetryCount++;
+ if (this._imageRetryCount < RasterMeshLayer.MAX_IMAGE_RETRY_ATTEMPTS) {
+ this._pendingImageRetry = retry;
+ this._scheduleRedraw();
+ } else {
+ console.warn(
+ `RasterMeshLayer: texture upload failed after ${RasterMeshLayer.MAX_IMAGE_RETRY_ATTEMPTS} attempts, giving up.`
+ );
+ this._imageRetryCount = 0;
+ }
+ } else {
+ this._imageRetryCount = 0;
+ }
+ }
+
const {model, images} = this.state;
const {moduleProps} = this.props;
diff --git a/src/layers/src/raster-tile/config.ts b/src/layers/src/raster-tile/config.ts
index aaea25882..66cc6c0c8 100644
--- a/src/layers/src/raster-tile/config.ts
+++ b/src/layers/src/raster-tile/config.ts
@@ -774,6 +774,14 @@ export const rasterVisConfigs = {
property: 'showTileBorders',
description: 'Debug: render wireframe boundaries of raster tiles'
} as VisConfigBoolean,
+ showTileDebugInfo: {
+ type: 'boolean',
+ defaultValue: false,
+ label: 'Show Tile Debug Info',
+ group: '',
+ property: 'showTileDebugInfo',
+ description: 'Debug: overlay each tile with its coordinates, status, and pixel range'
+ } as VisConfigBoolean,
zoomOffset: {
type: 'number',
defaultValue: 0,
diff --git a/src/layers/src/raster-tile/image.ts b/src/layers/src/raster-tile/image.ts
index 6a428ac60..dd7eda983 100644
--- a/src/layers/src/raster-tile/image.ts
+++ b/src/layers/src/raster-tile/image.ts
@@ -368,9 +368,10 @@ async function loadSingleAssetSTAC(request: AssetRequestData): Promise<ImageData
const imageBands = await loadNpyArray(request, true);
if (!imageBands) {
- return {
- imageBands
- };
+ // loadNpyArray returns null when the request was aborted or the server
+ // returned no usable data. Propagate null imageBands so the caller
+ // (getTileData) can detect the empty result and avoid caching it as valid.
+ return {imageBands: null};
}
const imageMask = (request.useMask && imageBands.pop()) || null;
diff --git a/src/layers/src/raster-tile/raster-tile-layer.ts b/src/layers/src/raster-tile/raster-tile-layer.ts
index db410c5a1..23d444fff 100644
--- a/src/layers/src/raster-tile/raster-tile-layer.ts
+++ b/src/layers/src/raster-tile/raster-tile-layer.ts
@@ -9,7 +9,7 @@ import type {TextureProps} from '@luma.gl/core';
type Texture2DProps = Partial<TextureProps> & Record<string, any>;
import memoize from 'lodash/memoize';
-import {PathLayer} from '@deck.gl/layers';
+import {PathLayer, TextLayer} from '@deck.gl/layers';
import {DatasetType, PMTilesType, LAYER_TYPES} from '@kepler.gl/constants';
import {RasterLayer, RasterMeshLayer} from '@kepler.gl/deckgl-layers';
import {
@@ -127,6 +127,7 @@ export type RasterTileLayerVisConfigCommonSettings = {
enableTerrain: VisConfigBoolean;
enableTerrainTopView: VisConfigBoolean;
showTileBorders: VisConfigBoolean;
+ showTileDebugInfo: VisConfigBoolean;
zoomOffset: VisConfigNumber;
};
@@ -644,7 +645,8 @@ export default class RasterTileLayer extends KeplerLayer {
hasCategoricalColorMap: Boolean(categoricalColorMap),
hasShadowEffect,
onRedrawNeeded: layerCallbacks?.onRedrawNeeded,
- showTileBorders: visConfig.showTileBorders
+ showTileBorders: visConfig.showTileBorders,
+ showTileDebugInfo: visConfig.showTileDebugInfo
});
return [tileLayer];
@@ -659,6 +661,7 @@ export default class RasterTileLayer extends KeplerLayer {
const tileSource = data.tileSource;
const showTileBorders = visConfig.showTileBorders;
+ const showTileDebugInfo = visConfig.showTileDebugInfo;
const minZoom = metadata.minZoom || 0;
const maxZoom = metadata.maxZoom || 30;
@@ -687,6 +690,7 @@ export default class RasterTileLayer extends KeplerLayer {
tileSource,
showTileBorders,
+ showTileDebugInfo,
visible,
opacity,
@@ -768,6 +772,15 @@ export default class RasterTileLayer extends KeplerLayer {
const [min, max] = this.getMinMaxPixelValues(images.imageBands);
tilesBeingLoaded--;
+ // If the fetch returned an ImageData object but without any band arrays
+ // (e.g. loadNpyArray silently returned null because the AbortSignal fired
+ // just after the HTTP response arrived), treat this as a failed load and
+ // return null so deck.gl shows the parent tile as a placeholder and
+ // re-requests this tile on the next viewport change.
+ if (!images.imageBands || (Array.isArray(images.imageBands) && images.imageBands.length === 0)) {
+ return null;
+ }
+
// Add terrain data only if we requested it above
return {
images,
@@ -858,17 +871,59 @@ export default class RasterTileLayer extends KeplerLayer {
}
}
+/**
+ * Build a TextLayer debug overlay for a single tile.
+ * Shown when showTileDebugInfo is enabled regardless of tile load state.
+ */
+function buildTileDebugLayer(
+ id: string,
+ tile: {index: {x: number; y: number; z: number}; bbox: unknown},
+ status: string,
+ extra: string
+): TextLayer {
+ const bbox = tile.bbox as GeoBoundingBox;
+ const {west, south, east, north} = bbox;
+ const cx = (west + east) / 2;
+ const cy = (south + north) / 2;
+ const {x, y, z} = tile.index;
+ const label = `[${z}/${x}/${y}]\n${status}${extra ? `\n${extra}` : ''}`;
+
+ return new TextLayer({
+ id: `${id}-debug`,
+ data: [{position: [cx, cy, 0], text: label}],
+ getPosition: d => d.position,
+ getText: d => d.text,
+ getSize: 12,
+ getColor: [255, 255, 80, 230],
+ getBackgroundColor: [0, 0, 0, 160],
+ background: true,
+ backgroundPadding: [3, 2, 3, 2],
+ fontWeight: 'bold',
+ fontFamily: 'monospace',
+ lineHeight: 1.3,
+ billboard: true,
+ sizeUnits: 'pixels',
+ getTextAnchor: 'middle',
+ getAlignmentBaseline: 'center'
+ });
+}
+
function renderSubLayersStac(props: RenderSubLayersProps): DeckLayer<any> | DeckLayer<any>[] {
const {
tile,
data,
minPixelValue: globalMinPixelValue,
- maxPixelValue: globalMaxPixelValue
+ maxPixelValue: globalMaxPixelValue,
+ showTileDebugInfo
} = props;
const bbox = tile.bbox as GeoBoundingBox;
const {west, south, east, north} = bbox;
+ // When debug overlay is on but data hasn't arrived yet, show a placeholder label
if (!data) {
+ if (showTileDebugInfo) {
+ return [buildTileDebugLayer(props.id, tile, 'loading…', '')];
+ }
return [];
}
@@ -878,7 +933,20 @@ function renderSubLayersStac(props: RenderSubLayersProps): DeckLayer<any> | Deck
minPixelValue: tileMinPixelValue,
maxPixelValue: tileMaxPixelValue
} = data;
+
if (!images || (Array.isArray(images) && images.length === 0)) {
+ if (showTileDebugInfo) {
+ return [buildTileDebugLayer(props.id, tile, 'NO IMAGES', '')];
+ }
+ return [];
+ }
+
+ // Guard against an ImageData object that loaded but has no band arrays
+ // (loadNpyArray returned null e.g. because abort fired after HTTP response).
+ if (!images.imageBands || (Array.isArray(images.imageBands) && images.imageBands.length === 0)) {
+ if (showTileDebugInfo) {
+ return [buildTileDebugLayer(props.id, tile, 'NO BANDS (empty fetch)', '')];
+ }
return [];
}
@@ -889,6 +957,9 @@ function renderSubLayersStac(props: RenderSubLayersProps): DeckLayer<any> | Deck
? globalMaxPixelValue
: tileMaxPixelValue;
if (typeof minPixelValue !== 'number' || typeof maxPixelValue !== 'number') {
+ if (showTileDebugInfo) {
+ return [buildTileDebugLayer(props.id, tile, 'NO RANGE', '')];
+ }
return [];
}
@@ -921,10 +992,11 @@ function renderSubLayersStac(props: RenderSubLayersProps): DeckLayer<any> | Deck
_imageCoordinateSystem: COORDINATE_SYSTEM.CARTESIAN
});
+ const layers: DeckLayer<any>[] = [rasterLayer];
+
if (props.showTileBorders) {
const borderColor: [number, number, number, number] = [0, 255, 0, 200];
- return [
- rasterLayer,
+ layers.push(
new PathLayer({
id: `${props.id}-border`,
data: [
@@ -940,10 +1012,19 @@ function renderSubLayersStac(props: RenderSubLayersProps): DeckLayer<any> | Deck
getColor: borderColor,
widthMinPixels: 2
})
- ];
+ );
+ }
+
+ if (showTileDebugInfo) {
+ const bandCount = Array.isArray(images.imageBands) ? images.imageBands.length : 0;
+ const minStr = Number.isFinite(minPixelValue) ? minPixelValue.toFixed(2) : '?';
+ const maxStr = Number.isFinite(maxPixelValue) ? maxPixelValue.toFixed(2) : '?';
+ const extra = `bands:${bandCount} min:${minStr} max:${maxStr}${terrain ? ' 3D' : ''}`;
+ const status = bandCount === 0 ? 'BANDS MISSING' : 'OK';
+ layers.push(buildTileDebugLayer(props.id, tile, status, extra));
}
- return rasterLayer;
+ return layers;
}
function renderSubLayersPMTiles(props: {
@@ -951,6 +1032,7 @@ function renderSubLayersPMTiles(props: {
data: any;
tileSource: any;
showTileBorders: boolean;
+ showTileDebugInfo?: boolean;
minZoom: number;
maxZoom: number;
tile: any;
@@ -958,6 +1040,7 @@ function renderSubLayersPMTiles(props: {
const {
tileSource,
showTileBorders,
+ showTileDebugInfo,
minZoom,
maxZoom,
tile: {
@@ -1004,6 +1087,12 @@ function renderSubLayersPMTiles(props: {
);
}
+ if (showTileDebugInfo) {
+ const status = props.data?.image ? 'OK' : 'NO IMAGE';
+ const extra = `zoom:${zoom} min:${minZoom} max:${maxZoom}`;
+ layers.push(buildTileDebugLayer(props.id, props.tile, status, extra));
+ }
+
return layers;
}
diff --git a/src/layers/src/raster-tile/request-throttle.ts b/src/layers/src/raster-tile/request-throttle.ts
index ee3bdfe24..ecf41c4d0 100644
--- a/src/layers/src/raster-tile/request-throttle.ts
+++ b/src/layers/src/raster-tile/request-throttle.ts
@@ -5,7 +5,7 @@ import {getApplicationConfig} from '@kepler.gl/utils';
interface RequestQueue {
activeRequests: number;
- queue: Array<() => Promise<any>>;
+ queue: Array<() => void>;
}
class RequestThrottle {
@@ -51,18 +51,9 @@ class RequestThrottle {
: this.maxConcurrentRequests;
if (serverQueue.activeRequests >= maxConcurrentRequests && Boolean(maxConcurrentRequests)) {
- // Wait for a slot to become available
+ // Wait for a free slot. We push only the resolver — requestFunction is called once below.
await new Promise<void>(resolve => {
- serverQueue.queue.push(async () => {
- try {
- const result = await requestFunction();
- resolve();
- return result;
- } catch (error) {
- resolve();
- return null;
- }
- });
+ serverQueue.queue.push(resolve);
});
}
@@ -71,10 +62,10 @@ class RequestThrottle {
return await requestFunction();
} finally {
serverQueue.activeRequests--;
- // Process next request in queue if any
- const nextRequest = serverQueue.queue.shift();
- if (nextRequest) {
- nextRequest();
+ // Unblock the next waiting caller, if any
+ const nextResolve = serverQueue.queue.shift();
+ if (nextResolve) {
+ nextResolve();
}
}
}
diff --git a/src/layers/src/raster-tile/types.ts b/src/layers/src/raster-tile/types.ts
index 0be5cecc5..a231a265f 100644
--- a/src/layers/src/raster-tile/types.ts
+++ b/src/layers/src/raster-tile/types.ts
@@ -176,6 +176,7 @@ export type RenderSubLayersCustomProps = ColorRescaling &
hasCategoricalColorMap: boolean;
hasShadowEffect?: boolean;
showTileBorders?: boolean;
+ showTileDebugInfo?: boolean;
};
export interface RenderSubLayersDefaultProps {