Add tile loading placeholders

Author: charlieforward9

docs/api-reference/geo-layers/terrain-layer.md

@@ -145,7 +145,10 @@ new deck.TerrainLayer({});
 
 ## Properties
 
-When in Tiled Mode, inherits from all [TileLayer](./tile-layer.md) properties. Forwards `wireframe` property to [SimpleMeshLayer](../mesh-layers/simple-mesh-layer.md).
+When in Tiled Mode, inherits from all [TileLayer](./tile-layer.md) properties. Tiled terrain
+forwards `renderPlaceholder` to its internal `TileLayer`; this can be used to render loading
+footprints before terrain meshes are available. Forwards `wireframe` property to
+[SimpleMeshLayer](../mesh-layers/simple-mesh-layer.md).
 
 
 

docs/api-reference/geo-layers/tile-layer.md

@@ -302,6 +302,10 @@ If not supplied, the `maxCacheByteSize` is set to `Infinity`.
 
 How the tile layer refines the visibility of tiles. When zooming in and out, if the layer only shows tiles from the current zoom level, then the user may observe undesirable flashing while new data is loading. By setting `refinementStrategy` the layer can attempt to maintain visual continuity by displaying cached data from a different zoom level before data is available.
 
+`refinementStrategy` only reuses loaded tile content that is already in the cache. To render
+synthetic content while a selected tile has no loaded content and no cached ancestor or child is
+visible, use [`renderPlaceholder`](#renderplaceholder).
+
 This prop accepts one of the following:
 
 * `'best-available'`: If a tile in the current viewport is waiting for its data to load, use cached content from the closest zoom level to fill the empty space. This approach minimizes the visual flashing due to missing content.
@@ -358,6 +362,44 @@ Note that the following sub layer props are overridden by `TileLayer` internally
 - `visible` (toggled based on tile visibility)
 - `highlightedObjectIndex` (set based on the parent layer's highlight state)
 
+#### `renderPlaceholder` (Function, optional) {#renderplaceholder}
+
+Renders one or an array of Layer instances for a selected tile while its data is loading.
+
+This prop is disabled by default. When supplied, it is called for selected tiles that have no loaded
+content and no generated sublayers. With the default `refinementStrategy: 'best-available'`, cached
+ancestor or child content still takes priority, so placeholders only fill cold-start or cache-miss
+gaps. With `refinementStrategy: 'no-overlap'`, placeholders are shown instead of cached refinement
+content for selected loading tiles.
+
+The callback receives all the `TileLayer` props and the following props:
+
+* `id` (string): A unique id for this placeholder sublayer
+* `data` (null): Placeholder tiles do not have loaded tile data
+* `bounds` (number[4]): Bounds of the tile in `[left, bottom, right, top]` order
+* `tile` ([Tile](#tile))
+
+- Default: `null`
+
+For raster tiles, return a `BitmapLayer` that spans `props.bounds`. Set `pickable: false` if
+placeholder layers should not participate in picking.
+
+```ts
+renderPlaceholder: props => {
+  const {data, bounds, ...otherProps} = props;
+
+  return new BitmapLayer(otherProps, {
+    image: 'data:image/png;base64,...',
+    bounds,
+    pickable: false,
+    opacity: 0.35
+  });
+}
+```
+
+Placeholder sublayers do not make the tile or layer loaded. `isLoaded`, `onViewportLoad`, tile cache
+behavior, and tile error handling continue to depend on the real tile request.
+
 #### `zRange` (number[2], optional) {#zrange}
 
 An array representing the height range of the content in the tiles, as `[minZ, maxZ]`. This is designed to support tiles with 2.5D content, such as buildings or terrains. At high pitch angles, such a tile may "extrude into" the viewport even if its 2D bounding box is out of view. Therefore, it is necessary to provide additional information for the layer to behave correctly. The value of this prop is used for two purposes: 1) to determine the necessary tiles to load and/or render; 2) to determine the possible intersecting tiles during picking.

examples/website/image-tile/app.tsx

@@ -2,7 +2,7 @@
 // SPDX-License-Identifier: MIT
 // Copyright (c) vis.gl contributors
 
-/* global fetch, DOMParser */
+/* global fetch, DOMParser, setTimeout */
 import React, {useState, useEffect} from 'react';
 import {createRoot} from 'react-dom/client';
 
@@ -24,6 +24,11 @@ const INITIAL_VIEW_STATE: OrthographicViewState = {
 
 const ROOT_URL =
   'https://raw.githubusercontent.com/visgl/deck.gl-data/master/website/image-tiles/moon.image';
+const PLACEHOLDER_IMAGE =
+  'data:image/svg+xml;charset=utf-8,' +
+  '%3Csvg xmlns="http://www.w3.org/2000/svg" width="8" height="8" viewBox="0 0 8 8"%3E' +
+  '%3Crect width="8" height="8" fill="%23242a2e"/%3E' +
+  '%3Cpath d="M0 8 8 0" stroke="%23404a50" stroke-width="1"/%3E%3C/svg%3E';
 
 function getTooltip({tile, bitmap}: TileLayerPickingInfo<ImageBitmap, BitmapLayerPickingInfo>) {
   if (tile && bitmap) {
@@ -35,11 +40,19 @@ function getTooltip({tile, bitmap}: TileLayerPickingInfo<ImageBitmap, BitmapLaye
   return null;
 }
 
+function sleep(ms: number): Promise<void> {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}
+
 export default function App({
   autoHighlight = true,
+  showPlaceholders = true,
+  loadDelay = 0,
   onTilesLoad
 }: {
   autoHighlight?: boolean;
+  showPlaceholders?: boolean;
+  loadDelay?: number;
   onTilesLoad?: () => void;
 }) {
   const [dimensions, setDimensions] = useState<{width: number; height: number; tileSize: number}>();
@@ -85,14 +98,37 @@ export default function App({
       minZoom: -7,
       maxZoom: 0,
       extent: [0, 0, dimensions.width, dimensions.height],
-      getTileData: ({index}) => {
+      getTileData: async ({index}) => {
         const {x, y, z} = index;
+        if (loadDelay > 0) {
+          await sleep(loadDelay);
+        }
         return load(
           `${ROOT_URL}/moon.image_files/${15 + z}/${x}_${y}.jpeg`
         ) as Promise<ImageBitmap>;
       },
       onViewportLoad: onTilesLoad,
 
+      renderPlaceholder: showPlaceholders
+        ? props => {
+            const {width, height} = dimensions;
+            const {bounds} = props;
+            const otherProps = {...props} as Partial<typeof props>;
+            delete otherProps.data;
+            delete otherProps.bounds;
+            return new BitmapLayer(otherProps, {
+              image: PLACEHOLDER_IMAGE,
+              bounds: [
+                clamp(bounds[0], 0, width),
+                clamp(bounds[1], 0, height),
+                clamp(bounds[2], 0, width),
+                clamp(bounds[3], 0, height)
+              ],
+              pickable: false,
+              opacity: 0.5
+            });
+          }
+        : undefined,
       renderSubLayers: props => {
         const [[left, bottom], [right, top]] = props.tile.boundingBox;
         const {width, height} = dimensions;

examples/website/map-tile/app.tsx

@@ -2,16 +2,18 @@
 // SPDX-License-Identifier: MIT
 // Copyright (c) vis.gl contributors
 
+/* global setTimeout */
 import React, {useState, useCallback} from 'react';
 import {createRoot} from 'react-dom/client';
 
 import {DeckGL} from '@deck.gl/react';
-import {MapView} from '@deck.gl/core';
+import {COORDINATE_SYSTEM, MapView, _GlobeView as GlobeView} from '@deck.gl/core';
 import {TileLayer} from '@deck.gl/geo-layers';
 import {BitmapLayer, PathLayer} from '@deck.gl/layers';
+import {load} from '@loaders.gl/core';
 import ZoomRangeWidget from './zoom-range-widget';
 
-import type {Position, MapViewState} from '@deck.gl/core';
+import type {GlobeViewState, Position, MapViewState, TextureSource} from '@deck.gl/core';
 import type {TileLayerPickingInfo} from '@deck.gl/geo-layers';
 
 const INITIAL_VIEW_STATE: MapViewState = {
@@ -23,8 +25,22 @@ const INITIAL_VIEW_STATE: MapViewState = {
   bearing: 0
 };
 
+const INITIAL_GLOBE_VIEW_STATE: GlobeViewState = {
+  latitude: 47.65,
+  longitude: 7,
+  zoom: 2.25,
+  maxZoom: 20
+};
+
 // Approximate bounding box of France [west, south, east, north]
 const FRANCE_EXTENT = [-5.14, 41.33, 9.56, 51.09];
+const PLACEHOLDER_GRID_CELLS = 16;
+const PLACEHOLDER_GRID_SEGMENTS = 24;
+const PLACEHOLDER_BACKGROUND_IMAGE: TextureSource = {
+  width: 1,
+  height: 1,
+  data: new Uint8Array([238, 241, 239, 255])
+};
 
 const COPYRIGHT_LICENSE_STYLE: React.CSSProperties = {
   position: 'absolute',
@@ -49,17 +65,50 @@ function getTooltip({tile}: TileLayerPickingInfo) {
   return null;
 }
 
+function sleep(ms: number): Promise<void> {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}
+
+function getPlaceholderGridPaths(bounds: [number, number, number, number]): Position[][] {
+  const [west, south, east, north] = bounds;
+  const paths: Position[][] = [];
+
+  for (let index = 0; index <= PLACEHOLDER_GRID_CELLS; index++) {
+    const gridPosition = index / PLACEHOLDER_GRID_CELLS;
+    const longitude = west + (east - west) * gridPosition;
+    const latitude = south + (north - south) * gridPosition;
+    const verticalPath: Position[] = [];
+    const horizontalPath: Position[] = [];
+
+    for (let segment = 0; segment <= PLACEHOLDER_GRID_SEGMENTS; segment++) {
+      const linePosition = segment / PLACEHOLDER_GRID_SEGMENTS;
+      verticalPath.push([longitude, south + (north - south) * linePosition]);
+      horizontalPath.push([west + (east - west) * linePosition, latitude]);
+    }
+
+    paths.push(verticalPath, horizontalPath);
+  }
+
+  return paths;
+}
+
 export default function App({
   showBorder = false,
+  globeView = false,
+  showPlaceholders = true,
+  loadDelay = 0,
   onTilesLoad,
   onZoomChange,
-  minZoom = 4,
-  maxZoom = 7,
+  minZoom = globeView ? 0 : 4,
+  maxZoom = globeView ? 19 : 7,
   visibleMinZoom,
-  visibleMaxZoom = 7,
+  visibleMaxZoom = globeView ? undefined : 7,
   useExtent = false
 }: {
   showBorder?: boolean;
+  globeView?: boolean;
+  showPlaceholders?: boolean;
+  loadDelay?: number;
   onTilesLoad?: () => void;
   onZoomChange?: (zoom: number) => void;
   minZoom?: number;
@@ -68,7 +117,9 @@ export default function App({
   visibleMaxZoom?: number;
   useExtent?: boolean;
 }) {
-  const [zoom, setZoom] = useState(INITIAL_VIEW_STATE.zoom);
+  const [zoom, setZoom] = useState(
+    globeView ? INITIAL_GLOBE_VIEW_STATE.zoom : INITIAL_VIEW_STATE.zoom
+  );
   const onViewStateChange = useCallback(
     ({viewState}) => {
       setZoom(viewState.zoom);
@@ -84,6 +135,13 @@ export default function App({
     // Since these OSM tiles support HTTP/2, we can make many concurrent requests
     // and we aren't limited by the browser to a certain number per domain.
     maxRequests: 20,
+    getTileData:
+      loadDelay > 0
+        ? async ({url}) => {
+            await sleep(loadDelay);
+            return load(url as string) as Promise<ImageBitmap>;
+          }
+        : undefined,
 
     pickable: true,
     onViewportLoad: onTilesLoad,
@@ -93,16 +151,56 @@ export default function App({
     minZoom,
     maxZoom,
     tileSize: 512,
+    refinementStrategy: 'no-overlap',
     visibleMinZoom,
     visibleMaxZoom,
     extent: useExtent ? FRANCE_EXTENT : undefined,
+    renderPlaceholder: showPlaceholders
+      ? props => {
+          const {id, bounds} = props;
+          const otherProps = {...props} as Partial<typeof props>;
+          delete otherProps.data;
+          delete otherProps.id;
+          delete otherProps.bounds;
+
+          return [
+            new BitmapLayer(
+              {...otherProps, id: `${id}-fill`},
+              {
+                image: PLACEHOLDER_BACKGROUND_IMAGE,
+                bounds,
+                _imageCoordinateSystem: COORDINATE_SYSTEM.CARTESIAN,
+                pickable: false,
+                opacity: 0.92
+              }
+            ),
+            new PathLayer<Position[]>(
+              {...otherProps, id: `${id}-grid`},
+              {
+                data: getPlaceholderGridPaths(bounds),
+                getPath: d => d,
+                getColor: [72, 86, 88, 190],
+                getWidth: 1,
+                widthUnits: 'pixels',
+                widthMinPixels: 1,
+                widthMaxPixels: 1,
+                pickable: false,
+                parameters: {
+                  depthTest: false
+                }
+              }
+            )
+          ];
+        }
+      : undefined,
     renderSubLayers: props => {
       const [[west, south], [east, north]] = props.tile.boundingBox;
       const {data, ...otherProps} = props;
 
       return [
         new BitmapLayer(otherProps, {
           image: data,
+          _imageCoordinateSystem: COORDINATE_SYSTEM.CARTESIAN,
           bounds: [west, south, east, north]
         }),
         showBorder &&
@@ -128,8 +226,8 @@ export default function App({
   return (
     <DeckGL
       layers={[tileLayer]}
-      views={new MapView({repeat: true})}
-      initialViewState={INITIAL_VIEW_STATE}
+      views={globeView ? new GlobeView() : new MapView({repeat: true})}
+      initialViewState={globeView ? INITIAL_GLOBE_VIEW_STATE : INITIAL_VIEW_STATE}
       controller={true}
       getTooltip={getTooltip}
       onViewStateChange={onViewStateChange}
@@ -152,5 +250,5 @@ export default function App({
 }
 
 export function renderToDOM(container: HTMLDivElement) {
-  createRoot(container).render(<App />);
+  createRoot(container).render(<App globeView={true} loadDelay={750} />);
 }

modules/geo-layers/src/index.ts

@@ -27,7 +27,12 @@ export type {H3ClusterLayerProps} from './h3-layers/h3-cluster-layer';
 export type {H3HexagonLayerProps} from './h3-layers/h3-hexagon-layer';
 export type {GreatCircleLayerProps} from './great-circle-layer/great-circle-layer';
 export type {S2LayerProps} from './s2-layer/s2-layer';
-export type {TileLayerProps, TileLayerPickingInfo} from './tile-layer/tile-layer';
+export type {
+  TileLayerProps,
+  TileLayerPickingInfo,
+  TileLayerRenderSubLayersProps,
+  TileLayerRenderPlaceholderProps
+} from './tile-layer/tile-layer';
 export type {TripsLayerProps} from './trips-layer/trips-layer';
 export type {QuadkeyLayerProps} from './quadkey-layer/quadkey-layer';
 export type {TerrainLayerProps} from './terrain-layer/terrain-layer';

modules/geo-layers/src/terrain-layer/terrain-layer.ts

@@ -355,7 +355,8 @@ export default class TerrainLayer<ExtraPropsT extends {} = {}> extends Composite
       onTileError,
       maxCacheSize,
       maxCacheByteSize,
-      refinementStrategy
+      refinementStrategy,
+      renderPlaceholder
     } = this.props;
 
     if (this.state.isTiled) {
@@ -366,6 +367,7 @@ export default class TerrainLayer<ExtraPropsT extends {} = {}> extends Composite
         {
           getTileData: this.getTiledTerrainData.bind(this),
           renderSubLayers: this.renderSubLayers.bind(this),
+          renderPlaceholder,
           updateTriggers: {
             getTileData: {
               elevationData: urlTemplateToUpdateTrigger(elevationData),