@deck.gl-community/geo-layers 9.2.8 → 9.3.0-beta.2

package/src/shared-tile-2d-layer/shared-tile-2d-view.ts

@@ -0,0 +1,339 @@
+// deck.gl-community
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {type Viewport} from '@deck.gl/core';
+import {Matrix4, equals, type NumericArray} from '@math.gl/core';
+
+import {memoize} from '../utils/memoize';
+import {
+  STRATEGY_DEFAULT,
+  STRATEGY_NEVER,
+  STRATEGY_REPLACE,
+  SharedTile2DHeader,
+  type SharedTileset2D
+} from '../tileset/index';
+import {getCullBounds, sharedTile2DDeckAdapter, transformBox} from './deck-tileset-adapter';
+
+/** Bit flag marking a tile as visited during refinement traversal. */
+const TILE_STATE_VISITED = 1;
+/** Bit flag marking a tile as visible during refinement traversal. */
+const TILE_STATE_VISIBLE = 2;
+
+/** Built-in placeholder refinement handlers keyed by strategy name. */
+const STRATEGIES = {
+  [STRATEGY_DEFAULT]: updateTileStateDefault,
+  [STRATEGY_REPLACE]: updateTileStateReplace,
+  [STRATEGY_NEVER]: () => {}
+};
+
+/** View-specific visibility state cached per tile. */
+type TileViewState = {
+  /** Whether the tile was selected directly for the current viewport. */
+  isSelected: boolean;
+  /** Whether the tile should render in this viewport after refinement. */
+  isVisible: boolean;
+  /** Bit field used by refinement helpers while traversing ancestors and children. */
+  state: number;
+};
+
+/** Per-viewport traversal state for the deck-facing shared tile layer. */
+export class SharedTile2DView<DataT = any> {
+  /** Unique consumer identifier used by the shared tileset cache. */
+  readonly id = Symbol('tile-2d-view');
+
+  /** Shared tileset queried by this view. */
+  private _tileset: SharedTileset2D<DataT, Viewport>;
+  /** Tiles selected during the latest traversal. */
+  private _selectedTiles: SharedTile2DHeader<DataT>[] | null = null;
+  /** Incremented whenever this view's visible tile set changes. */
+  private _frameNumber = 0;
+  /** Last viewport used to compute tile selection. */
+  private _viewport: Viewport | null = null;
+  /** Last z-range used during tile selection. */
+  private _zRange: [number, number] | null = null;
+  /** Last model matrix applied to tile selection. */
+  private _modelMatrix = new Matrix4();
+  /** Inverse of the current model matrix. */
+  private _modelMatrixInverse = new Matrix4();
+  /** Per-tile visibility and selection flags for this view. */
+  private _state = new Map<SharedTile2DHeader<DataT>, TileViewState>();
+
+  /** Creates a viewport-specific view of a shared tileset. */
+  constructor(tileset: SharedTileset2D<DataT, Viewport>) {
+    this._tileset = tileset;
+    if (!this._tileset.adapter) {
+      this._tileset.setOptions({adapter: sharedTile2DDeckAdapter});
+    }
+    this._tileset.attachConsumer(this.id);
+  }
+
+  /** Releases this view and detaches it from the shared tileset. */
+  finalize(): void {
+    this._tileset.detachConsumer(this.id);
+    this._selectedTiles = null;
+    this._state.clear();
+  }
+
+  /** Tiles selected for the last viewport update. */
+  get selectedTiles(): SharedTile2DHeader<DataT>[] | null {
+    return this._selectedTiles;
+  }
+
+  /** Indicates whether all selected tiles are fully loaded for this view. */
+  get isLoaded(): boolean {
+    return this._selectedTiles !== null && this._selectedTiles.every((tile) => tile.isLoaded);
+  }
+
+  /** Indicates whether any selected tile needs to be re-requested. */
+  get needsReload(): boolean {
+    return this._selectedTiles !== null && this._selectedTiles.some((tile) => tile.needsReload);
+  }
+
+  /** Updates tile selection and visibility for a viewport and returns the current frame number. */
+  update(
+    viewport: Viewport,
+    {
+      zRange,
+      modelMatrix
+    }: {
+      zRange: [number, number] | null;
+      modelMatrix: NumericArray | null;
+    } = {zRange: null, modelMatrix: null}
+  ): number {
+    const modelMatrixAsMatrix4 = modelMatrix ? new Matrix4(modelMatrix) : new Matrix4();
+    const isModelMatrixNew = !modelMatrixAsMatrix4.equals(this._modelMatrix);
+
+    if (
+      !this._viewport ||
+      !viewport.equals(this._viewport) ||
+      !equals(this._zRange, zRange) ||
+      isModelMatrixNew
+    ) {
+      if (isModelMatrixNew) {
+        this._modelMatrixInverse = modelMatrixAsMatrix4.clone().invert();
+        this._modelMatrix = modelMatrixAsMatrix4;
+      }
+      this._viewport = viewport;
+      this._zRange = zRange;
+      const tileIndices = this._tileset.getTileIndices({
+        viewState: viewport,
+        maxZoom: this._tileset.maxZoom,
+        minZoom: this._tileset.minZoom,
+        zRange,
+        modelMatrix: this._modelMatrix,
+        modelMatrixInverse: this._modelMatrixInverse
+      });
+      this._selectedTiles = tileIndices.map((index) => this._tileset.getTile(index, true));
+      this._tileset.prepareTiles();
+    } else if (this.needsReload) {
+      this._selectedTiles = (this._selectedTiles || []).map((tile) =>
+        this._tileset.getTile(tile.index, true)
+      );
+      this._tileset.prepareTiles();
+    }
+
+    const changed = this._updateTileStates();
+    this._tileset.updateConsumer(this.id, this._selectedTiles || [], this._getVisibleTiles());
+
+    if (changed) {
+      this._frameNumber++;
+    }
+    return this._frameNumber;
+  }
+
+  /** Tests whether a tile should render in the current viewport and culling rectangle. */
+  isTileVisible(
+    tile: SharedTile2DHeader<DataT>,
+    cullRect?: {x: number; y: number; width: number; height: number},
+    modelMatrix?: Matrix4 | null
+  ): boolean {
+    const state = this._state.get(tile);
+    if (!state?.isVisible) {
+      return false;
+    }
+
+    if (!cullRect || !this._viewport) {
+      return true;
+    }
+    const boundsArr = this._getCullBounds({
+      viewport: this._viewport,
+      z: this._zRange,
+      cullRect
+    });
+    return boundsArr.some((bounds) => this._tileOverlapsBounds(tile, bounds, modelMatrix));
+  }
+
+  /** Collects tiles currently marked visible for this view. */
+  private _getVisibleTiles(): SharedTile2DHeader<DataT>[] {
+    const result: SharedTile2DHeader<DataT>[] = [];
+    for (const tile of this._tileset.tiles) {
+      if (this._state.get(tile)?.isVisible) {
+        result.push(tile);
+      }
+    }
+    return result;
+  }
+
+  /** Memoized screen-space culling bounds helper. */
+  private _getCullBounds = memoize(getCullBounds);
+
+  /** Recomputes selected and placeholder-visible tiles for the current view. */
+  private _updateTileStates(): boolean {
+    const refinementStrategy = this._tileset.refinementStrategy || STRATEGY_DEFAULT;
+    const allTiles = this._tileset.tiles;
+    const previousVisibility = new Map<SharedTile2DHeader<DataT>, boolean>();
+
+    for (const tile of allTiles) {
+      const existing = this._state.get(tile);
+      previousVisibility.set(tile, existing?.isVisible || false);
+      this._state.set(tile, {isSelected: false, isVisible: false, state: 0});
+    }
+
+    for (const tile of this._selectedTiles || []) {
+      const state = this._state.get(tile) || {isSelected: false, isVisible: false, state: 0};
+      state.isSelected = true;
+      state.isVisible = true;
+      this._state.set(tile, state);
+    }
+
+    if (typeof refinementStrategy === 'function') {
+      refinementStrategy(allTiles);
+    } else {
+      STRATEGIES[refinementStrategy](allTiles, this._state);
+    }
+
+    let changed = false;
+    for (const tile of allTiles) {
+      const state = this._state.get(tile);
+      if (state && state.isVisible !== previousVisibility.get(tile)) {
+        changed = true;
+      }
+    }
+    return changed;
+  }
+
+  /** Tests one tile against one culling bounds rectangle. */
+  private _tileOverlapsBounds(
+    tile: SharedTile2DHeader<DataT>,
+    [minX, minY, maxX, maxY]: [number, number, number, number],
+    modelMatrix?: Matrix4 | null
+  ): boolean {
+    const bbox = this._getTileBoundingBox(tile, modelMatrix);
+    if ('west' in bbox) {
+      return bbox.west < maxX && bbox.east > minX && bbox.south < maxY && bbox.north > minY;
+    }
+    const y0 = Math.min(bbox.top, bbox.bottom);
+    const y1 = Math.max(bbox.top, bbox.bottom);
+    return bbox.left < maxX && bbox.right > minX && y0 < maxY && y1 > minY;
+  }
+
+  /** Applies model-matrix transforms to non-geospatial tile bounds when needed. */
+  private _getTileBoundingBox(tile: SharedTile2DHeader<DataT>, modelMatrix?: Matrix4 | null) {
+    const {bbox} = tile;
+    if ('west' in bbox || !modelMatrix || Matrix4.IDENTITY.equals(modelMatrix)) {
+      return bbox;
+    }
+    const [left, top, right, bottom] = transformBox(
+      [bbox.left, bbox.top, bbox.right, bbox.bottom],
+      modelMatrix
+    );
+    return {left, top, right, bottom};
+  }
+}
+
+/** Default refinement strategy that prefers best available loaded descendants. */
+function updateTileStateDefault(
+  allTiles: SharedTile2DHeader[],
+  stateMap: Map<SharedTile2DHeader, TileViewState>
+) {
+  for (const tile of allTiles) {
+    getTileState(stateMap, tile).state = 0;
+  }
+  for (const tile of allTiles) {
+    if (getTileState(stateMap, tile).isSelected && !getPlaceholderInAncestors(tile, stateMap)) {
+      getPlaceholderInChildren(tile, stateMap);
+    }
+  }
+  for (const tile of allTiles) {
+    const state = getTileState(stateMap, tile);
+    state.isVisible = Boolean(state.state & TILE_STATE_VISIBLE);
+  }
+}
+
+/** Replacement refinement strategy that avoids visible overlap between ancestors and descendants. */
+function updateTileStateReplace(
+  allTiles: SharedTile2DHeader[],
+  stateMap: Map<SharedTile2DHeader, TileViewState>
+) {
+  for (const tile of allTiles) {
+    getTileState(stateMap, tile).state = 0;
+  }
+  for (const tile of allTiles) {
+    if (getTileState(stateMap, tile).isSelected) {
+      getPlaceholderInAncestors(tile, stateMap);
+    }
+  }
+  const sortedTiles = Array.from(allTiles).sort((t1, t2) => t1.zoom - t2.zoom);
+  for (const tile of sortedTiles) {
+    const tileState = getTileState(stateMap, tile);
+    tileState.isVisible = Boolean(tileState.state & TILE_STATE_VISIBLE);
+
+    if (tile.children && (tileState.isVisible || tileState.state & TILE_STATE_VISITED)) {
+      for (const child of tile.children) {
+        getTileState(stateMap, child).state = TILE_STATE_VISITED;
+      }
+    } else if (tileState.isSelected) {
+      getPlaceholderInChildren(tile, stateMap);
+    }
+  }
+}
+
+/** Searches upward for a loaded ancestor that can stand in for an unavailable selected tile. */
+function getPlaceholderInAncestors(
+  startTile: SharedTile2DHeader,
+  stateMap: Map<SharedTile2DHeader, TileViewState>
+): boolean {
+  let tile: SharedTile2DHeader | null = startTile;
+  while ((tile = tile.parent)) {
+    const state = getTileState(stateMap, tile);
+    state.state |= TILE_STATE_VISIBLE | TILE_STATE_VISITED;
+    if (tile.isLoaded || tile.content) {
+      return true;
+    }
+  }
+  return false;
+}
+
+/** Searches downward for loaded descendants that can stand in for an unavailable selected tile. */
+function getPlaceholderInChildren(
+  tile: SharedTile2DHeader,
+  stateMap: Map<SharedTile2DHeader, TileViewState>
+): void {
+  const state = getTileState(stateMap, tile);
+  state.state |= TILE_STATE_VISIBLE | TILE_STATE_VISITED;
+
+  if (!tile.children || !tile.children.length || tile.isLoaded || tile.content) {
+    return;
+  }
+
+  for (const child of tile.children) {
+    const childState = getTileState(stateMap, child);
+    if (!(childState.state & TILE_STATE_VISITED)) {
+      getPlaceholderInChildren(child, stateMap);
+    }
+  }
+}
+
+/** Returns view state for a tile, creating a default record when needed. */
+function getTileState(
+  stateMap: Map<SharedTile2DHeader, TileViewState>,
+  tile: SharedTile2DHeader
+): TileViewState {
+  let tileState = stateMap.get(tile);
+  if (!tileState) {
+    tileState = {isSelected: false, isVisible: false, state: 0};
+    stateMap.set(tile, tileState);
+  }
+  return tileState;
+}

package/src/shared-tile-2d-layer/url-template.ts

@@ -0,0 +1,40 @@
+// deck.gl-community
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import type {TileIndex} from '../tileset/types';
+
+/** URL template accepted by {@link SharedTile2DLayer} when loading tiles directly by URL. */
+export type URLTemplate = string | string[] | null;
+
+function stringHash(s: string): number {
+  return Math.abs(s.split('').reduce((a, b) => ((a << 5) - a + b.charCodeAt(0)) | 0, 0));
+}
+
+/** Expands one tile URL template for a given tile index. */
+export function getURLFromTemplate(
+  template: URLTemplate,
+  tile: {
+    index: TileIndex;
+    id: string;
+  }
+): string | null {
+  if (!template || !template.length) {
+    return null;
+  }
+  const {index, id} = tile;
+
+  if (Array.isArray(template)) {
+    template = template[stringHash(id) % template.length];
+  }
+
+  let url = template;
+  for (const key of Object.keys(index)) {
+    url = url.replace(new RegExp(`{${key}}`, 'g'), String(index[key as keyof TileIndex]));
+  }
+
+  if (Number.isInteger(index.y) && Number.isInteger(index.z)) {
+    url = url.replace(/\{-y\}/g, String(Math.pow(2, index.z) - index.y - 1));
+  }
+  return url;
+}

package/src/tile-grid-layer/tile-grid-layer.ts

@@ -0,0 +1,158 @@
+// deck.gl-community
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {CompositeLayer, type Color, type DefaultProps} from '@deck.gl/core';
+import {PathLayer, TextLayer} from '@deck.gl/layers';
+
+import type {SharedTile2DHeader} from '../tileset/index';
+import type {TileBoundingBox} from '../tileset/types';
+
+/** Label content or formatter used by {@link TileGridLayer}. */
+type TileGridLabelAccessor = string | ((tile: SharedTile2DHeader<unknown>) => string);
+
+/**
+ * Props for {@link TileGridLayer}, a helper overlay for visualizing tile loading
+ * and tile selection in tiled layers.
+ */
+export type TileGridLayerProps = {
+  /** Tile header whose bounds and index should be visualized. */
+  tile: SharedTile2DHeader<unknown>;
+  /** Whether to draw an outline around the tile bounds. Defaults to `true`. */
+  showBorder?: boolean;
+  /** Whether to render a label at the tile center. Defaults to `true`. */
+  showLabel?: boolean;
+  /** Static label text or formatter for per-tile label content. */
+  getLabel?: TileGridLabelAccessor;
+  /** Stroke color used for the tile border. */
+  borderColor?: Color;
+  /** Text color used for the tile label. */
+  labelColor?: Color;
+  /** Background color used behind the tile label text. */
+  labelBackgroundColor?: Color;
+  /** Minimum screen-space width of the tile border in pixels. */
+  borderWidthMinPixels?: number;
+  /** Screen-space font size of the tile label in pixels. */
+  labelSize?: number;
+};
+
+/** Internal derived geometry used to render one tile grid overlay. */
+type TileGridLayerItem = {
+  path: [number, number][];
+  center: [number, number];
+  label: string;
+};
+
+/** Default prop values for {@link TileGridLayer}. */
+const defaultProps: DefaultProps<TileGridLayerProps> = {
+  tile: {type: 'object', value: undefined!},
+  showBorder: true,
+  showLabel: true,
+  getLabel: {
+    type: 'function',
+    value: (tile: SharedTile2DHeader<unknown>) =>
+      `z${tile.index.z} x${tile.index.x} y${tile.index.y}`
+  },
+  borderColor: [255, 255, 255, 180],
+  labelColor: [255, 255, 255, 255],
+  labelBackgroundColor: [15, 23, 42, 210],
+  borderWidthMinPixels: 1,
+  labelSize: 12
+};
+
+/** Converts a tile bounding box into a closed outline path. */
+function getTilePath(bbox: TileBoundingBox): [number, number][] {
+  if ('west' in bbox) {
+    return [
+      [bbox.west, bbox.north],
+      [bbox.west, bbox.south],
+      [bbox.east, bbox.south],
+      [bbox.east, bbox.north],
+      [bbox.west, bbox.north]
+    ];
+  }
+
+  return [
+    [bbox.left, bbox.top],
+    [bbox.left, bbox.bottom],
+    [bbox.right, bbox.bottom],
+    [bbox.right, bbox.top],
+    [bbox.left, bbox.top]
+  ];
+}
+
+/** Returns the center point of a tile bounding box. */
+function getTileCenter(bbox: TileBoundingBox): [number, number] {
+  if ('west' in bbox) {
+    return [(bbox.west + bbox.east) / 2, (bbox.north + bbox.south) / 2];
+  }
+
+  return [(bbox.left + bbox.right) / 2, (bbox.top + bbox.bottom) / 2];
+}
+
+/**
+ * Helper layer that renders a tile outline and optional label for visualizing tile
+ * loading, coverage, and traversal.
+ */
+export class TileGridLayer extends CompositeLayer<TileGridLayerProps> {
+  static layerName = 'TileGridLayer';
+  static defaultProps: DefaultProps<TileGridLayerProps> = defaultProps;
+
+  /** Builds the tile border and label sublayers. */
+  renderLayers() {
+    const {
+      tile,
+      showBorder,
+      showLabel,
+      getLabel,
+      borderColor,
+      labelColor,
+      labelBackgroundColor,
+      borderWidthMinPixels,
+      labelSize
+    } = this.props;
+
+    const item: TileGridLayerItem = {
+      path: getTilePath(tile.bbox),
+      center: getTileCenter(tile.bbox),
+      label: typeof getLabel === 'function' ? getLabel(tile) : getLabel
+    };
+
+    return [
+      showBorder
+        ? new PathLayer<TileGridLayerItem>(
+            this.getSubLayerProps({
+              id: 'border'
+            }),
+            {
+              data: [item],
+              getPath: (d) => d.path,
+              getColor: borderColor,
+              widthMinPixels: borderWidthMinPixels,
+              pickable: false
+            }
+          )
+        : null,
+      showLabel
+        ? new TextLayer<TileGridLayerItem>(
+            this.getSubLayerProps({
+              id: 'label'
+            }),
+            {
+              data: [item],
+              getPosition: (d) => d.center,
+              getText: (d) => d.label,
+              getColor: labelColor,
+              getBackgroundColor: labelBackgroundColor,
+              getSize: labelSize,
+              sizeUnits: 'pixels',
+              background: true,
+              getTextAnchor: 'middle',
+              getAlignmentBaseline: 'center',
+              pickable: false
+            }
+          )
+        : null
+    ];
+  }
+}

package/src/tile-source-layer/tile-source-layer.ts

@@ -12,7 +12,7 @@ import type {TileSource} from '@loaders.gl/loader-utils';
 const devicePixelRatio = (typeof window !== 'undefined' && window.devicePixelRatio) || 1;
 
 export type TileSourceLayerProps = TileLayerProps & {
-  tileSource: TileSource<any>;
+  tileSource: TileSource;
   showTileBorders?: boolean;
 };
 
@@ -30,7 +30,7 @@ export class TileSourceLayer extends CompositeLayer<TileSourceLayerProps> {
   };
 
   state: {
-    tileSource: TileSource<any> | null;
+    tileSource: TileSource | null;
   } = undefined!;
 
   initializeState() {

package/src/tileset/adapter.ts

@@ -0,0 +1,47 @@
+// deck.gl-community
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import type {Matrix4} from '@math.gl/core';
+import type {Bounds, TileBoundingBox, TileIndex, ZRange} from './types';
+
+/** Traversal inputs required by a {@link SharedTileset2DAdapter}. */
+export type SharedTileset2DTraversalContext<ViewStateT> = {
+  /** Consumer-defined view state used by the adapter. */
+  viewState: ViewStateT;
+  /** Tile size in pixels. */
+  tileSize: number;
+  /** Bounding box limiting tile generation. */
+  extent?: Bounds | null;
+  /** Minimum zoom level to request. */
+  minZoom?: number;
+  /** Maximum zoom level to request. */
+  maxZoom?: number;
+  /** Integer zoom offset applied during tile selection. */
+  zoomOffset?: number;
+  /** Elevation range used during geospatial tile selection. */
+  zRange?: ZRange | null;
+  /** Optional model matrix applied by the surrounding layer stack. */
+  modelMatrix?: Matrix4 | null;
+  /** Inverse of the current model matrix. */
+  modelMatrixInverse?: Matrix4 | null;
+};
+
+/** Minimal tile metadata inputs required by a {@link SharedTileset2DAdapter}. */
+export type SharedTileset2DTileContext<ViewStateT> = {
+  /** Consumer-defined view state used by the adapter. */
+  viewState: ViewStateT;
+  /** Tile size in pixels. */
+  tileSize: number;
+};
+
+/** Adapter used by {@link SharedTileset2D} to compute traversal and tile bounds without depending on a specific viewport implementation. */
+export type SharedTileset2DAdapter<ViewStateT> = {
+  /** Returns tile indices that should be selected for one traversal context. */
+  getTileIndices: (context: SharedTileset2DTraversalContext<ViewStateT>) => TileIndex[];
+  /** Returns the structured bounding box for one tile index. */
+  getTileBoundingBox: (
+    context: SharedTileset2DTileContext<ViewStateT>,
+    index: TileIndex
+  ) => TileBoundingBox;
+};

package/src/tileset/index.ts

@@ -0,0 +1,22 @@
+// deck.gl-community
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+export type {
+  TileLoadProps,
+  Bounds,
+  ZRange,
+  GeoBoundingBox,
+  NonGeoBoundingBox,
+  TileBoundingBox
+} from './types';
+export type {
+  SharedTileset2DAdapter,
+  SharedTileset2DTraversalContext,
+  SharedTileset2DTileContext
+} from './adapter';
+export type {RefinementStrategy, Tileset2DProps as SharedTileset2DBaseProps} from './tileset-2d';
+export {STRATEGY_DEFAULT, STRATEGY_NEVER, STRATEGY_REPLACE} from './tileset-2d';
+export type {SharedTileset2DProps} from './tileset-2d';
+export {SharedTileset2D} from './tileset-2d';
+export {SharedTile2DHeader} from './tile-2d-header';