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.tsxindex 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.tsindex 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 complexityexport 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.tsindex 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.tsindex 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, RasterLayerAddconst 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, RasterLayerAddif (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.tsindex 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.tsindex 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<ImageDataconst 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.tsindex 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 abovereturn {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 labelif (!data) {+ if (showTileDebugInfo) {+ return [buildTileDebugLayer(props.id, tile, 'loading…', '')];+ }return [];}@@ -878,7 +933,20 @@ function renderSubLayersStac(props: RenderSubLayersProps): DeckLayer<any> | DeckminPixelValue: 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> | DeckgetColor: 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.tsindex 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.tsindex 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 {