@deck.gl/geo-layers 8.7.7 → 8.8.0-alpha.2

package/src/tile-layer/{tileset-2d.js → tileset-2d.ts}

@@ -2,6 +2,9 @@ import Tile2DHeader from './tile-2d-header';
 import {getTileIndices, tileToBoundingBox} from './utils';
 import {RequestScheduler} from '@loaders.gl/loader-utils';
 import {Matrix4} from '@math.gl/core';
+import {assert, Viewport} from '@deck.gl/core';
+import {Bounds, TileIndex, ZRange} from './types';
+import {TileLayerProps} from './tile-layer';
 
 // bit masks
 const TILE_STATE_VISITED = 1;
@@ -29,6 +32,13 @@ export const STRATEGY_NEVER = 'never';
 export const STRATEGY_REPLACE = 'no-overlap';
 export const STRATEGY_DEFAULT = 'best-available';
 
+export type RefinementStrategyFunction = (tiles: Tile2DHeader[]) => void;
+export type RefinementStrategy =
+  | typeof STRATEGY_NEVER
+  | typeof STRATEGY_REPLACE
+  | typeof STRATEGY_DEFAULT
+  | RefinementStrategyFunction;
+
 const DEFAULT_CACHE_SCALE = 5;
 
 const STRATEGIES = {
@@ -37,17 +47,52 @@ const STRATEGIES = {
   [STRATEGY_NEVER]: () => {}
 };
 
+export type Tileset2DProps = Pick<
+  TileLayerProps,
+  | 'getTileData'
+  | 'tileSize'
+  | 'maxCacheSize'
+  | 'maxCacheByteSize'
+  | 'refinementStrategy'
+  | 'extent'
+  | 'maxZoom'
+  | 'minZoom'
+  | 'maxRequests'
+  | 'zoomOffset'
+> & {
+  onTileLoad: (tile: Tile2DHeader) => void;
+  onTileUnload: (tile: Tile2DHeader) => void;
+  onTileError: (error: any, tile: Tile2DHeader) => void;
+};
+
 /**
- * Manages loading and purging of tiles data. This class caches recently visited tiles
- * and only create new tiles if they are present.
+ * Manages loading and purging of tile data. This class caches recently visited tiles
+ * and only creates new tiles if they are present.
  */
-
 export default class Tileset2D {
+  private opts: Tileset2DProps;
+  private _requestScheduler: RequestScheduler;
+  private _cache: Map<string, Tile2DHeader>;
+  private _dirty: boolean;
+  private _tiles: Tile2DHeader[];
+
+  private _cacheByteSize: number;
+  private _viewport: Viewport | null;
+  private _selectedTiles: Tile2DHeader[] | null;
+  private _frameNumber: number;
+  private _modelMatrix: Matrix4;
+  private _modelMatrixInverse: Matrix4;
+
+  private _maxZoom?: number;
+  private _minZoom?: number;
+
+  private onTileLoad: (tile: Tile2DHeader) => void;
+
   /**
    * Takes in a function that returns tile data, a cache size, and a max and a min zoom level.
    * Cache size defaults to 5 * number of tiles in the current viewport
    */
-  constructor(opts) {
+  constructor(opts: Tileset2DProps) {
     this.opts = opts;
 
     this.onTileLoad = tile => {
@@ -85,19 +130,19 @@ export default class Tileset2D {
     return this._tiles;
   }
 
-  get selectedTiles() {
+  get selectedTiles(): Tile2DHeader[] | null {
     return this._selectedTiles;
   }
 
-  get isLoaded() {
-    return this._selectedTiles.every(tile => tile.isLoaded);
+  get isLoaded(): boolean {
+    return this._selectedTiles !== null && this._selectedTiles.every(tile => tile.isLoaded);
   }
 
-  get needsReload() {
-    return this._selectedTiles.some(tile => tile.needsReload);
+  get needsReload(): boolean {
+    return this._selectedTiles !== null && this._selectedTiles.some(tile => tile.needsReload);
   }
 
-  setOptions(opts) {
+  setOptions(opts: Tileset2DProps): void {
     Object.assign(this.opts, opts);
     if (Number.isFinite(opts.maxZoom)) {
       this._maxZoom = Math.floor(opts.maxZoom);
@@ -108,7 +153,7 @@ export default class Tileset2D {
   }
 
   // Clean up any outstanding tile requests.
-  finalize() {
+  finalize(): void {
     for (const tile of this._cache.values()) {
       if (tile.isLoading) {
         tile.abort();
@@ -119,11 +164,11 @@ export default class Tileset2D {
     this._selectedTiles = null;
   }
 
-  reloadAll() {
-    for (const tileId of this._cache.keys()) {
-      const tile = this._cache.get(tileId);
-      if (!this._selectedTiles.includes(tile)) {
-        this._cache.delete(tileId);
+  reloadAll(): void {
+    for (const id of this._cache.keys()) {
+      const tile = this._cache.get(id) as Tile2DHeader;
+      if (!this._selectedTiles || !this._selectedTiles.includes(tile)) {
+        this._cache.delete(id);
       } else {
         tile.setNeedsReload();
       }
@@ -132,14 +177,14 @@ export default class Tileset2D {
 
   /**
    * Update the cache with the given viewport and model matrix and triggers callback onUpdate.
-   * @param {*} viewport
-   * @param {*} onUpdate
-   * @param {*} modelMatrix
    */
-  update(viewport, {zRange, modelMatrix} = {}) {
+  update(
+    viewport: Viewport,
+    {zRange, modelMatrix}: {zRange?: ZRange; modelMatrix?: Matrix4} = {}
+  ): number {
     const modelMatrixAsMatrix4 = new Matrix4(modelMatrix);
     const isModelMatrixNew = !modelMatrixAsMatrix4.equals(this._modelMatrix);
-    if (!viewport.equals(this._viewport) || isModelMatrixNew) {
+    if (!this._viewport || !viewport.equals(this._viewport) || isModelMatrixNew) {
       if (isModelMatrixNew) {
         this._modelMatrixInverse = modelMatrixAsMatrix4.clone().invert();
         this._modelMatrix = modelMatrixAsMatrix4;
@@ -161,9 +206,7 @@ export default class Tileset2D {
       }
       // Check for needed reloads explicitly even if the view/matrix has not changed.
     } else if (this.needsReload) {
-      this._selectedTiles = this._selectedTiles.map(tile =>
-        this._getTile({x: tile.x, y: tile.y, z: tile.z})
-      );
+      this._selectedTiles = this._selectedTiles!.map(tile => this._getTile(tile.index));
     }
 
     // Update tile states
@@ -184,8 +227,24 @@ export default class Tileset2D {
 
   /* Public interface for subclassing */
 
-  // Returns array of {x, y, z}
-  getTileIndices({viewport, maxZoom, minZoom, zRange, modelMatrix, modelMatrixInverse}) {
+  /** Returns array of tile indices in the current viewport */
+  getTileIndices({
+    viewport,
+    maxZoom,
+    minZoom,
+    zRange,
+    modelMatrix,
+    modelMatrixInverse
+  }: {
+    viewport: Viewport;
+    maxZoom?: number;
+    minZoom?: number;
+    zRange: ZRange | undefined;
+    tileSize?: number;
+    modelMatrix?: Matrix4;
+    modelMatrixInverse?: Matrix4;
+    zoomOffset?: number;
+  }): TileIndex[] {
     const {tileSize, extent, zoomOffset} = this.opts;
     return getTileIndices({
       viewport,
@@ -193,30 +252,41 @@ export default class Tileset2D {
       minZoom,
       zRange,
       tileSize,
-      extent,
+      extent: extent as Bounds | undefined,
       modelMatrix,
       modelMatrixInverse,
       zoomOffset
     });
   }
 
-  // Add custom metadata to tiles
-  getTileMetadata({x, y, z}) {
+  /** Returns unique string key for a tile index */
+  getTileId(index: TileIndex) {
+    return `${index.x}-${index.y}-${index.z}`;
+  }
+
+  /** Returns a zoom level for a tile index */
+  getTileZoom(index: TileIndex) {
+    return index.z;
+  }
+
+  /** Returns additional metadata to add to tile, bbox by default */
+  getTileMetadata(index: TileIndex) {
+    assert(this._viewport);
     const {tileSize} = this.opts;
-    return {bbox: tileToBoundingBox(this._viewport, x, y, z, tileSize)};
+    return {bbox: tileToBoundingBox(this._viewport, index.x, index.y, index.z, tileSize)};
   }
 
-  // Returns {x, y, z} of the parent tile
-  getParentIndex(tileIndex) {
-    // Perf: mutate the input object to avoid GC
-    tileIndex.x = Math.floor(tileIndex.x / 2);
-    tileIndex.y = Math.floor(tileIndex.y / 2);
-    tileIndex.z -= 1;
-    return tileIndex;
+  /** Returns index of the parent tile */
+  getParentIndex(index: TileIndex) {
+    const x = Math.floor(index.x / 2);
+    const y = Math.floor(index.y / 2);
+    const z = index.z - 1;
+    return {x, y, z};
   }
 
   // Returns true if any tile's visibility changed
   updateTileStates() {
+    assert(this._selectedTiles);
     const refinementStrategy = this.opts.refinementStrategy || STRATEGY_DEFAULT;
 
     const visibilities = new Array(this._cache.size);
@@ -251,10 +321,10 @@ export default class Tileset2D {
 
   /* Private methods */
 
-  _pruneRequests() {
+  _pruneRequests(): void {
     const {maxRequests} = this.opts;
 
-    const abortCandidates = [];
+    const abortCandidates: Tile2DHeader[] = [];
     let ongoingRequestCount = 0;
     for (const tile of this._cache.values()) {
       // Keep track of all the ongoing requests
@@ -268,7 +338,7 @@ export default class Tileset2D {
 
     while (maxRequests > 0 && ongoingRequestCount > maxRequests && abortCandidates.length > 0) {
       // There are too many ongoing requests, so abort some that are unselected
-      const tile = abortCandidates.shift();
+      const tile = abortCandidates.shift()!;
       tile.abort();
       ongoingRequestCount--;
     }
@@ -281,14 +351,16 @@ export default class Tileset2D {
     // Reset states
     for (const tile of _cache.values()) {
       tile.parent = null;
-      tile.children.length = 0;
+      if (tile.children) {
+        tile.children.length = 0;
+      }
     }
 
     // Rebuild tree
     for (const tile of _cache.values()) {
-      const parent = this._getNearestAncestor(tile.x, tile.y, tile.z);
+      const parent = this._getNearestAncestor(tile);
       tile.parent = parent;
-      if (parent) {
+      if (parent?.children) {
         parent.children.push(tile);
       }
     }
@@ -299,6 +371,7 @@ export default class Tileset2D {
    */
   /* eslint-disable complexity */
   _resizeCache() {
+    assert(this.selectedTiles);
     const {_cache, opts} = this;
 
     const maxCacheSize =
@@ -309,11 +382,11 @@ export default class Tileset2D {
     const overflown = _cache.size > maxCacheSize || this._cacheByteSize > maxCacheByteSize;
 
     if (overflown) {
-      for (const [tileId, tile] of _cache) {
+      for (const [id, tile] of _cache) {
         if (!tile.isVisible) {
           // delete tile
           this._cacheByteSize -= opts.maxCacheByteSize ? tile.byteLength : 0;
-          _cache.delete(tileId);
+          _cache.delete(id);
           this.opts.onTileUnload(tile);
         }
         if (_cache.size <= maxCacheSize && this._cacheByteSize <= maxCacheByteSize) {
@@ -324,30 +397,33 @@ export default class Tileset2D {
       this._dirty = true;
     }
     if (this._dirty) {
-      this._tiles = Array.from(this._cache.values())
-        // sort by zoom level so that smaller tiles are displayed on top
-        .sort((t1, t2) => t1.z - t2.z);
+      // sort by zoom level so that smaller tiles are displayed on top
+      this._tiles = Array.from(this._cache.values()).sort((t1, t2) => t1.zoom - t2.zoom);
 
       this._dirty = false;
     }
   }
   /* eslint-enable complexity */
 
-  _getTile({x, y, z}, create) {
-    const tileId = `${x},${y},${z}`;
-    let tile = this._cache.get(tileId);
+  _getTile(index: TileIndex, create: true): Tile2DHeader;
+  _getTile(index: TileIndex, create?: false): Tile2DHeader | undefined;
+  _getTile(index: TileIndex, create?: boolean): Tile2DHeader | undefined {
+    const id = this.getTileId(index);
+    let tile = this._cache.get(id);
     let needsReload = false;
 
     if (!tile && create) {
-      tile = new Tile2DHeader({x, y, z});
-      Object.assign(tile, this.getTileMetadata(tile));
+      tile = new Tile2DHeader(index);
+      Object.assign(tile, this.getTileMetadata(tile.index));
+      Object.assign(tile, {id, zoom: this.getTileZoom(tile.index)});
       needsReload = true;
-      this._cache.set(tileId, tile);
+      this._cache.set(id, tile);
       this._dirty = true;
     } else if (tile && tile.needsReload) {
       needsReload = true;
     }
-    if (needsReload) {
+    if (tile && needsReload) {
+      // eslint-disable-next-line @typescript-eslint/no-floating-promises
       tile.loadData({
         getData: this.opts.getTileData,
         requestScheduler: this._requestScheduler,
@@ -359,11 +435,11 @@ export default class Tileset2D {
     return tile;
   }
 
-  _getNearestAncestor(x, y, z) {
+  _getNearestAncestor(tile: Tile2DHeader): Tile2DHeader | null {
     const {_minZoom = 0} = this;
-    let index = {x, y, z};
 
-    while (index.z > _minZoom) {
+    let index = tile.index;
+    while (this.getTileZoom(index) > _minZoom) {
       index = this.getParentIndex(index);
       const parent = this._getTile(index);
       if (parent) {
@@ -380,7 +456,7 @@ export default class Tileset2D {
 // For all the selected && pending tiles:
 // - pick the closest ancestor as placeholder
 // - if no ancestor is visible, pick the closest children as placeholder
-function updateTileStateDefault(allTiles) {
+function updateTileStateDefault(allTiles: Tile2DHeader[]) {
   for (const tile of allTiles) {
     tile.state = 0;
   }
@@ -390,12 +466,12 @@ function updateTileStateDefault(allTiles) {
     }
   }
   for (const tile of allTiles) {
-    tile.isVisible = Boolean(tile.state & TILE_STATE_VISIBLE);
+    tile.isVisible = Boolean(tile.state! & TILE_STATE_VISIBLE);
   }
 }
 
 // Until a selected tile and all its selected siblings are loaded, use the closest ancestor as placeholder
-function updateTileStateReplace(allTiles) {
+function updateTileStateReplace(allTiles: Tile2DHeader[]) {
   for (const tile of allTiles) {
     tile.state = 0;
   }
@@ -405,11 +481,11 @@ function updateTileStateReplace(allTiles) {
     }
   }
   // Always process parents first
-  const sortedTiles = Array.from(allTiles).sort((t1, t2) => t1.z - t2.z);
+  const sortedTiles = Array.from(allTiles).sort((t1, t2) => t1.zoom - t2.zoom);
   for (const tile of sortedTiles) {
-    tile.isVisible = Boolean(tile.state & TILE_STATE_VISIBLE);
+    tile.isVisible = Boolean(tile.state! & TILE_STATE_VISIBLE);
 
-    if (tile.isVisible || tile.state & TILE_STATE_VISITED) {
+    if (tile.children && (tile.isVisible || tile.state! & TILE_STATE_VISITED)) {
       // If the tile is rendered, or if the tile has been explicitly hidden, hide all of its children
       for (const child of tile.children) {
         child.state = TILE_STATE_VISITED;
@@ -421,10 +497,11 @@ function updateTileStateReplace(allTiles) {
 }
 
 // Walk up the tree until we find one ancestor that is loaded. Returns true if successful.
-function getPlaceholderInAncestors(tile) {
+function getPlaceholderInAncestors(startTile: Tile2DHeader) {
+  let tile: Tile2DHeader | null = startTile;
   while (tile) {
     if (tile.isLoaded || tile.content) {
-      tile.state |= TILE_STATE_VISIBLE;
+      tile.state! |= TILE_STATE_VISIBLE;
       return true;
     }
     tile = tile.parent;

package/src/tile-layer/types.ts

@@ -0,0 +1,17 @@
+export type ZRange = [minZ: number, maxZ: number];
+
+export type Bounds = [minX: number, minY: number, maxX: number, maxY: number];
+
+export type TileBoundingBox =
+  | {left: number; top: number; right: number; bottom: number}
+  | {west: number; north: number; east: number; south: number};
+
+export type TileIndex = {x: number; y: number; z: number};
+
+export type TileLoadProps = {
+  index: TileIndex;
+  id: string;
+  bbox: TileBoundingBox;
+  url?: string | null;
+  signal?: AbortSignal;
+};

package/src/tile-layer/{utils.js → utils.ts}

@@ -1,7 +1,11 @@
+import {Viewport} from '@deck.gl/core';
+import {Matrix4} from '@math.gl/core';
+import Tile2DHeader from './tile-2d-header';
 import {getOSMTileIndices} from './tile-2d-traversal';
+import {Bounds, TileBoundingBox, TileIndex, ZRange} from './types';
 
 const TILE_SIZE = 512;
-const DEFAULT_EXTENT = [-Infinity, -Infinity, Infinity, Infinity];
+const DEFAULT_EXTENT: Bounds = [-Infinity, -Infinity, Infinity, Infinity];
 
 export const urlType = {
   type: 'url',
@@ -30,7 +34,7 @@ export const urlType = {
   }
 };
 
-function transformBox(bbox, modelMatrix) {
+function transformBox(bbox: Bounds, modelMatrix: Matrix4): Bounds {
   const transformedCoords = [
     // top-left
     modelMatrix.transformAsPoint([bbox[0], bbox[1]]),
@@ -41,7 +45,7 @@ function transformBox(bbox, modelMatrix) {
     // bottom-right
     modelMatrix.transformAsPoint([bbox[2], bbox[3]])
   ];
-  const transformedBox = [
+  const transformedBox: Bounds = [
     // Minimum x coord
     Math.min(...transformedCoords.map(i => i[0])),
     // Minimum y coord
@@ -54,27 +58,38 @@ function transformBox(bbox, modelMatrix) {
   return transformedBox;
 }
 
-export function getURLFromTemplate(template, properties) {
+function stringHash(s: string): number {
+  return Math.abs(s.split('').reduce((a, b) => ((a << 5) - a + b.charCodeAt(0)) | 0, 0));
+}
+
+export function getURLFromTemplate(template: string | string[], tile: Tile2DHeader): string | null {
   if (!template || !template.length) {
     return null;
   }
+  const {index, id} = tile;
+
   if (Array.isArray(template)) {
-    const index = Math.abs(properties.x + properties.y) % template.length;
-    template = template[index];
+    const i = stringHash(id) % template.length;
+    template = template[i];
   }
 
-  const {x, y, z} = properties;
-  return template
-    .replace(/\{x\}/g, x)
-    .replace(/\{y\}/g, y)
-    .replace(/\{z\}/g, z)
-    .replace(/\{-y\}/g, Math.pow(2, z) - y - 1);
+  let url = template;
+  for (const key of Object.keys(index)) {
+    const regex = new RegExp(`{${key}}`, 'g');
+    url = url.replace(regex, String(index[key]));
+  }
+
+  // Back-compatible support for {-y}
+  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;
 }
 
 /**
  * gets the bounding box of a viewport
  */
-function getBoundingBox(viewport, zRange, extent) {
+function getBoundingBox(viewport: Viewport, zRange: number[] | null, extent: Bounds): Bounds {
   let bounds;
   if (zRange && zRange.length === 2) {
     const [minZ, maxZ] = zRange;
@@ -107,22 +122,22 @@ function getBoundingBox(viewport, zRange, extent) {
   ];
 }
 
-function getIndexingCoords(bbox, scale, modelMatrixInverse) {
+function getIndexingCoords(bbox: Bounds, scale: number, modelMatrixInverse?: Matrix4): Bounds {
   if (modelMatrixInverse) {
     const transformedTileIndex = transformBox(bbox, modelMatrixInverse).map(
       i => (i * scale) / TILE_SIZE
     );
-    return transformedTileIndex;
+    return transformedTileIndex as Bounds;
   }
-  return bbox.map(i => (i * scale) / TILE_SIZE);
+  return bbox.map(i => (i * scale) / TILE_SIZE) as Bounds;
 }
 
-function getScale(z, tileSize) {
+function getScale(z: number, tileSize: number): number {
   return (Math.pow(2, z) * TILE_SIZE) / tileSize;
 }
 
 // https://wiki.openstreetmap.org/wiki/Slippy_map_tilenames#Lon..2Flat._to_tile_numbers_2
-export function osmTile2lngLat(x, y, z) {
+export function osmTile2lngLat(x: number, y: number, z: number): [number, number] {
   const scale = getScale(z, TILE_SIZE);
   const lng = (x / scale) * 360 - 180;
   const n = Math.PI - (2 * Math.PI * y) / scale;
@@ -130,11 +145,17 @@ export function osmTile2lngLat(x, y, z) {
   return [lng, lat];
 }
 
-function tile2XY(x, y, z, tileSize) {
+function tile2XY(x: number, y: number, z: number, tileSize: number): [number, number] {
   const scale = getScale(z, tileSize);
   return [(x / scale) * TILE_SIZE, (y / scale) * TILE_SIZE];
 }
-export function tileToBoundingBox(viewport, x, y, z, tileSize = TILE_SIZE) {
+export function tileToBoundingBox(
+  viewport: Viewport,
+  x: number,
+  y: number,
+  z: number,
+  tileSize: number = TILE_SIZE
+): TileBoundingBox {
   if (viewport.isGeospatial) {
     const [west, north] = osmTile2lngLat(x, y, z);
     const [east, south] = osmTile2lngLat(x + 1, y + 1, z);
@@ -145,11 +166,17 @@ export function tileToBoundingBox(viewport, x, y, z, tileSize = TILE_SIZE) {
   return {left, top, right, bottom};
 }
 
-function getIdentityTileIndices(viewport, z, tileSize, extent, modelMatrixInverse) {
+function getIdentityTileIndices(
+  viewport: Viewport,
+  z: number,
+  tileSize: number,
+  extent: Bounds,
+  modelMatrixInverse?: Matrix4
+) {
   const bbox = getBoundingBox(viewport, null, extent);
   const scale = getScale(z, tileSize);
   const [minX, minY, maxX, maxY] = getIndexingCoords(bbox, scale, modelMatrixInverse);
-  const indices = [];
+  const indices: TileIndex[] = [];
 
   /*
       |  TILE  |  TILE  |  TILE  |
@@ -179,17 +206,27 @@ export function getTileIndices({
   modelMatrix,
   modelMatrixInverse,
   zoomOffset = 0
+}: {
+  viewport: Viewport;
+  maxZoom?: number;
+  minZoom?: number;
+  zRange: ZRange | undefined;
+  extent?: Bounds;
+  tileSize?: number;
+  modelMatrix?: Matrix4;
+  modelMatrixInverse?: Matrix4;
+  zoomOffset?: number;
 }) {
   let z = viewport.isGeospatial
     ? Math.round(viewport.zoom + Math.log2(TILE_SIZE / tileSize)) + zoomOffset
     : Math.ceil(viewport.zoom) + zoomOffset;
-  if (Number.isFinite(minZoom) && z < minZoom) {
+  if (typeof minZoom === 'number' && Number.isFinite(minZoom) && z < minZoom) {
     if (!extent) {
       return [];
     }
     z = minZoom;
   }
-  if (Number.isFinite(maxZoom) && z > maxZoom) {
+  if (typeof maxZoom === 'number' && Number.isFinite(maxZoom) && z > maxZoom) {
     z = maxZoom;
   }
   let transformedExtent = extent;
@@ -210,6 +247,6 @@ export function getTileIndices({
 /**
  * Returns true if s is a valid URL template
  */
-export function isURLTemplate(s) {
+export function isURLTemplate(s: string): boolean {
   return /(?=.*{z})(?=.*{x})(?=.*({y}|{-y}))/.test(s);
 }