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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deck.gl-community/geo-layers",
-  "version": "9.2.8",
+  "version": "9.3.0-beta.2",
   "description": "Add-0n geospatial layers for deck.gl",
   "license": "MIT",
   "publishConfig": {
@@ -22,6 +22,11 @@
       "types": "./dist/index.d.ts",
       "require": "./dist/index.cjs",
       "import": "./dist/index.js"
+    },
+    "./tileset": {
+      "types": "./dist/tileset/index.d.ts",
+      "require": "./dist/tileset/index.cjs",
+      "import": "./dist/tileset/index.js"
     }
   },
   "files": [
@@ -33,21 +38,22 @@
     "test-watch": "vitest"
   },
   "dependencies": {
-    "@deck.gl/core": "~9.2.8",
-    "@deck.gl/geo-layers": "~9.2.8",
-    "@deck.gl/layers": "~9.2.8",
-    "@loaders.gl/loader-utils": "^4.2.0",
-    "@luma.gl/core": "~9.2.6",
-    "@luma.gl/engine": "~9.2.6",
-    "@luma.gl/shadertools": "~9.2.6",
+    "@deck.gl/core": "~9.3.0",
+    "@deck.gl/geo-layers": "~9.3.0",
+    "@deck.gl/layers": "~9.3.0",
+    "@loaders.gl/loader-utils": "^4.4.1",
+    "@luma.gl/core": "~9.3.2",
+    "@luma.gl/engine": "~9.3.2",
+    "@luma.gl/shadertools": "~9.3.2",
     "@math.gl/core": "^4.0.0",
+    "@probe.gl/stats": "^4.1.1",
     "a5-js": "^0.5.0",
     "h3-js": "^4.2.1"
   },
   "devDependencies": {
-    "@deck.gl/test-utils": "~9.2.8",
-    "@luma.gl/webgpu": "~9.2.6",
+    "@deck.gl/test-utils": "~9.3.0",
+    "@luma.gl/webgpu": "~9.3.2",
     "@probe.gl/test-utils": "^4.0.4"
   },
-  "gitHead": "9cb179aa3d1707f32116034150ab7130ce88b18c"
+  "gitHead": "82660b8a29be0958c81acd00669b3034375186ea"
 }

package/src/global-grid-layer/global-grid-cluster-layer.ts

@@ -34,7 +34,7 @@ export class GlobalGridClusterLayer<DataT = any, ExtraProps extends {} = {}> ext
     globalGrid: {type: 'object', compare: true, value: undefined!}
   } as const satisfies DefaultProps<GlobalGridClusterLayerProps>;
 
-  declare state: {
+  state = null as unknown as {
     polygons: {polygon: number[][][]}[];
   };
 

package/src/index.ts

@@ -4,6 +4,20 @@
 
 export type {TileSourceLayerProps} from './tile-source-layer/tile-source-layer';
 export {TileSourceLayer} from './tile-source-layer/tile-source-layer';
+export type {
+  SharedTile2DLayerProps,
+  SharedTile2DLayerPickingInfo
+} from './shared-tile-2d-layer/index';
+export {SharedTile2DLayer, sharedTile2DDeckAdapter} from './shared-tile-2d-layer/index';
+export type {SharedTileset2DProps, SharedTileset2DBaseProps} from './tileset/index';
+export type {
+  SharedTileset2DAdapter,
+  SharedTileset2DTraversalContext,
+  SharedTileset2DTileContext
+} from './tileset/index';
+export {SharedTileset2D, SharedTile2DHeader} from './tileset/index';
+export type {TileGridLayerProps} from './tile-grid-layer/tile-grid-layer';
+export {TileGridLayer} from './tile-grid-layer/tile-grid-layer';
 
 export {GlobalGridLayer, type GlobalGridLayerProps} from './global-grid-layer/global-grid-layer';
 

package/src/shared-tile-2d-layer/deck-tile-traversal.ts

@@ -0,0 +1,247 @@
+// deck.gl-community
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {Viewport, WebMercatorViewport, _GlobeViewport} from '@deck.gl/core';
+import {
+  CullingVolume,
+  Plane,
+  AxisAlignedBoundingBox,
+  makeOrientedBoundingBoxFromPoints
+} from '@math.gl/culling';
+import {lngLatToWorld} from '@math.gl/web-mercator';
+import type {Bounds, TileIndex, ZRange} from '../tileset/types';
+import {osmTile2lngLat} from './deck-tileset-adapter';
+
+const TILE_SIZE = 512;
+const MAX_MAPS = 3;
+const REF_POINTS_5 = [
+  [0.5, 0.5],
+  [0, 0],
+  [0, 1],
+  [1, 0],
+  [1, 1]
+];
+const REF_POINTS_9 = REF_POINTS_5.concat([
+  [0, 0.5],
+  [0.5, 0],
+  [1, 0.5],
+  [0.5, 1]
+]);
+const REF_POINTS_11 = REF_POINTS_9.concat([
+  [0.25, 0.5],
+  [0.75, 0.5]
+]);
+
+class OSMNode {
+  x: number;
+  y: number;
+  z: number;
+
+  private childVisible?: boolean;
+  private selected?: boolean;
+  private _children?: OSMNode[];
+
+  constructor(x: number, y: number, z: number) {
+    this.x = x;
+    this.y = y;
+    this.z = z;
+  }
+
+  get children(): OSMNode[] {
+    if (!this._children) {
+      const x = this.x * 2;
+      const y = this.y * 2;
+      const z = this.z + 1;
+      this._children = [
+        new OSMNode(x, y, z),
+        new OSMNode(x, y + 1, z),
+        new OSMNode(x + 1, y, z),
+        new OSMNode(x + 1, y + 1, z)
+      ];
+    }
+    return this._children;
+  }
+
+  update(params: {
+    viewport: Viewport;
+    project: ((xyz: number[]) => number[]) | null;
+    cullingVolume: CullingVolume;
+    elevationBounds: ZRange;
+    minZ: number;
+    maxZ: number;
+    bounds?: Bounds;
+    offset: number;
+  }): boolean {
+    const {viewport, cullingVolume, elevationBounds, minZ, maxZ, bounds, offset, project} = params;
+    const boundingVolume = this.getBoundingVolume(elevationBounds, offset, project);
+
+    if (bounds && !this.insideBounds(bounds)) {
+      return false;
+    }
+
+    const isInside = cullingVolume.computeVisibility(boundingVolume);
+    if (isInside < 0) {
+      return false;
+    }
+
+    if (!this.childVisible) {
+      let {z} = this;
+      if (z < maxZ && z >= minZ) {
+        const distance =
+          (boundingVolume.distanceTo(viewport.cameraPosition) * viewport.scale) / viewport.height;
+        z += Math.floor(Math.log2(distance));
+      }
+      if (z >= maxZ) {
+        this.selected = true;
+        return true;
+      }
+    }
+
+    this.selected = false;
+    this.childVisible = true;
+    for (const child of this.children) {
+      child.update(params);
+    }
+    return true;
+  }
+
+  getSelected(result: OSMNode[] = []): OSMNode[] {
+    if (this.selected) {
+      result.push(this);
+    }
+    if (this._children) {
+      for (const node of this._children) {
+        node.getSelected(result);
+      }
+    }
+    return result;
+  }
+
+  insideBounds([minX, minY, maxX, maxY]: Bounds): boolean {
+    const scale = Math.pow(2, this.z);
+    const extent = TILE_SIZE / scale;
+
+    return (
+      this.x * extent < maxX &&
+      this.y * extent < maxY &&
+      (this.x + 1) * extent > minX &&
+      (this.y + 1) * extent > minY
+    );
+  }
+
+  getBoundingVolume(
+    zRange: ZRange,
+    worldOffset: number,
+    project: ((xyz: number[]) => number[]) | null
+  ) {
+    if (project) {
+      const refPoints = this.z < 1 ? REF_POINTS_11 : this.z < 2 ? REF_POINTS_9 : REF_POINTS_5;
+      const refPointPositions: number[][] = [];
+      for (const p of refPoints) {
+        const lngLat: number[] = osmTile2lngLat(this.x + p[0], this.y + p[1], this.z);
+        lngLat[2] = zRange[0];
+        refPointPositions.push(project(lngLat));
+
+        if (zRange[0] !== zRange[1]) {
+          lngLat[2] = zRange[1];
+          refPointPositions.push(project(lngLat));
+        }
+      }
+
+      return makeOrientedBoundingBoxFromPoints(refPointPositions);
+    }
+
+    const scale = Math.pow(2, this.z);
+    const extent = TILE_SIZE / scale;
+    const originX = this.x * extent + worldOffset * TILE_SIZE;
+    const originY = TILE_SIZE - (this.y + 1) * extent;
+
+    return new AxisAlignedBoundingBox(
+      [originX, originY, zRange[0]],
+      [originX + extent, originY + extent, zRange[1]]
+    );
+  }
+}
+
+/** deck.gl-specific OSM tile traversal for geospatial viewports. */
+export function getOSMTileIndices(
+  viewport: Viewport,
+  maxZ: number,
+  zRange: ZRange | null,
+  bounds?: Bounds
+): TileIndex[] {
+  const project: ((xyz: number[]) => number[]) | null =
+    viewport instanceof _GlobeViewport && viewport.resolution
+      ? (xyz) => viewport.projectPosition(xyz)
+      : null;
+
+  const planes: Plane[] = Object.values(viewport.getFrustumPlanes()).map(
+    ({normal, distance}) => new Plane(normal.clone().negate(), distance)
+  );
+  const cullingVolume = new CullingVolume(planes);
+
+  const unitsPerMeter = viewport.distanceScales.unitsPerMeter[2];
+  const elevationMin = (zRange && zRange[0] * unitsPerMeter) || 0;
+  const elevationMax = (zRange && zRange[1] * unitsPerMeter) || 0;
+  const minZ = viewport instanceof WebMercatorViewport && viewport.pitch <= 60 ? maxZ : 0;
+
+  if (bounds) {
+    const [minLng, minLat, maxLng, maxLat] = bounds;
+    const topLeft = lngLatToWorld([minLng, maxLat]);
+    const bottomRight = lngLatToWorld([maxLng, minLat]);
+    bounds = [topLeft[0], TILE_SIZE - topLeft[1], bottomRight[0], TILE_SIZE - bottomRight[1]];
+  }
+
+  const root = new OSMNode(0, 0, 0);
+  const traversalParams = {
+    viewport,
+    project,
+    cullingVolume,
+    elevationBounds: [elevationMin, elevationMax] as ZRange,
+    minZ,
+    maxZ,
+    bounds,
+    offset: 0
+  };
+
+  root.update(traversalParams);
+  updateWrappedWorldCopies(root, traversalParams, viewport);
+
+  return root.getSelected();
+}
+
+function updateWrappedWorldCopies(
+  root: OSMNode,
+  traversalParams: Parameters<OSMNode['update']>[0],
+  viewport: Viewport
+): void {
+  if (
+    !(viewport instanceof WebMercatorViewport) ||
+    !viewport.subViewports ||
+    viewport.subViewports.length <= 1
+  ) {
+    return;
+  }
+
+  sweepOffsets(root, traversalParams, -1, -MAX_MAPS);
+  sweepOffsets(root, traversalParams, 1, MAX_MAPS);
+}
+
+function sweepOffsets(
+  root: OSMNode,
+  traversalParams: Parameters<OSMNode['update']>[0],
+  startOffset: number,
+  limit: number
+): void {
+  traversalParams.offset = startOffset;
+  while (root.update(traversalParams)) {
+    traversalParams.offset += Math.sign(startOffset);
+    if (
+      (startOffset < 0 && traversalParams.offset < limit) ||
+      (startOffset > 0 && traversalParams.offset > limit)
+    ) {
+      break;
+    }
+  }
+}

package/src/shared-tile-2d-layer/deck-tileset-adapter.ts

@@ -0,0 +1,262 @@
+// deck.gl-community
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import type {Viewport} from '@deck.gl/core';
+import {Matrix4} from '@math.gl/core';
+import type {Bounds, GeoBoundingBox, TileBoundingBox, TileIndex, ZRange} from '../tileset/types';
+import type {
+  SharedTileset2DAdapter,
+  SharedTileset2DTileContext,
+  SharedTileset2DTraversalContext
+} from '../tileset/adapter';
+import {getOSMTileIndices} from './deck-tile-traversal';
+
+const TILE_SIZE = 512;
+const DEFAULT_EXTENT: Bounds = [-Infinity, -Infinity, Infinity, Infinity];
+
+/** deck.gl viewport type used by the shared tile layer adapter. */
+export type SharedTile2DDeckViewState = Viewport;
+
+/** Applies a model transform to an axis-aligned bounding box. */
+export function transformBox(bbox: Bounds, modelMatrix: Matrix4): Bounds {
+  const transformedCoords = [
+    modelMatrix.transformAsPoint([bbox[0], bbox[1]]),
+    modelMatrix.transformAsPoint([bbox[2], bbox[1]]),
+    modelMatrix.transformAsPoint([bbox[0], bbox[3]]),
+    modelMatrix.transformAsPoint([bbox[2], bbox[3]])
+  ];
+  return [
+    Math.min(...transformedCoords.map((i) => i[0])),
+    Math.min(...transformedCoords.map((i) => i[1])),
+    Math.max(...transformedCoords.map((i) => i[0])),
+    Math.max(...transformedCoords.map((i) => i[1]))
+  ];
+}
+
+function getBoundingBox(viewport: Viewport, zRange: number[] | null, extent: Bounds): Bounds {
+  let bounds;
+  if (zRange && zRange.length === 2) {
+    const [minZ, maxZ] = zRange;
+    const bounds0 = viewport.getBounds({z: minZ});
+    const bounds1 = viewport.getBounds({z: maxZ});
+    bounds = [
+      Math.min(bounds0[0], bounds1[0]),
+      Math.min(bounds0[1], bounds1[1]),
+      Math.max(bounds0[2], bounds1[2]),
+      Math.max(bounds0[3], bounds1[3])
+    ];
+  } else {
+    bounds = viewport.getBounds();
+  }
+  if (!viewport.isGeospatial) {
+    return [
+      Math.max(Math.min(bounds[0], extent[2]), extent[0]),
+      Math.max(Math.min(bounds[1], extent[3]), extent[1]),
+      Math.min(Math.max(bounds[2], extent[0]), extent[2]),
+      Math.min(Math.max(bounds[3], extent[1]), extent[3])
+    ];
+  }
+  return [
+    Math.max(bounds[0], extent[0]),
+    Math.max(bounds[1], extent[1]),
+    Math.min(bounds[2], extent[2]),
+    Math.min(bounds[3], extent[3])
+  ];
+}
+
+/** Computes cull bounds in projected/world coordinates for one deck viewport. */
+export function getCullBounds({
+  viewport,
+  z,
+  cullRect
+}: {
+  viewport: Viewport;
+  z: ZRange | number | null;
+  cullRect: {x: number; y: number; width: number; height: number};
+}): [number, number, number, number][] {
+  const subViewports = viewport.subViewports || [viewport];
+  return subViewports.map((v) => getCullBoundsInViewport(v, z || 0, cullRect));
+}
+
+function getCullBoundsInViewport(
+  viewport: Viewport,
+  z: ZRange | number,
+  cullRect: {x: number; y: number; width: number; height: number}
+): [number, number, number, number] {
+  if (!Array.isArray(z)) {
+    const x = cullRect.x - viewport.x;
+    const y = cullRect.y - viewport.y;
+    const {width, height} = cullRect;
+    const unprojectOption = {targetZ: z};
+
+    const topLeft = viewport.unproject([x, y], unprojectOption);
+    const topRight = viewport.unproject([x + width, y], unprojectOption);
+    const bottomLeft = viewport.unproject([x, y + height], unprojectOption);
+    const bottomRight = viewport.unproject([x + width, y + height], unprojectOption);
+
+    return [
+      Math.min(topLeft[0], topRight[0], bottomLeft[0], bottomRight[0]),
+      Math.min(topLeft[1], topRight[1], bottomLeft[1], bottomRight[1]),
+      Math.max(topLeft[0], topRight[0], bottomLeft[0], bottomRight[0]),
+      Math.max(topLeft[1], topRight[1], bottomLeft[1], bottomRight[1])
+    ];
+  }
+
+  const bounds0 = getCullBoundsInViewport(viewport, z[0], cullRect);
+  const bounds1 = getCullBoundsInViewport(viewport, z[1], cullRect);
+
+  return [
+    Math.min(bounds0[0], bounds1[0]),
+    Math.min(bounds0[1], bounds1[1]),
+    Math.max(bounds0[2], bounds1[2]),
+    Math.max(bounds0[3], bounds1[3])
+  ];
+}
+
+function getIndexingCoords(
+  bbox: Bounds,
+  scale: number,
+  modelMatrixInverse?: Matrix4 | null
+): Bounds {
+  if (modelMatrixInverse) {
+    return transformBox(bbox, modelMatrixInverse).map((i) => (i * scale) / TILE_SIZE) as Bounds;
+  }
+  return bbox.map((i) => (i * scale) / TILE_SIZE) as Bounds;
+}
+
+function getScale(z: number, tileSize: number): number {
+  return (Math.pow(2, z) * TILE_SIZE) / tileSize;
+}
+
+/** Converts an OSM tile coordinate to longitude/latitude. */
+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;
+  const lat = (180 / Math.PI) * Math.atan(0.5 * (Math.exp(n) - Math.exp(-n)));
+  return [lng, lat];
+}
+
+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];
+}
+
+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);
+    return {west, north, east, south};
+  }
+  const [left, top] = tile2XY(x, y, z, tileSize);
+  const [right, bottom] = tile2XY(x + 1, y + 1, z, tileSize);
+  return {left, top, right, bottom};
+}
+
+function getIdentityTileIndices(
+  viewport: Viewport,
+  z: number,
+  tileSize: number,
+  extent: Bounds,
+  modelMatrixInverse?: Matrix4 | null
+): TileIndex[] {
+  const bbox = getBoundingBox(viewport, null, extent);
+  const scale = getScale(z, tileSize);
+  const [minX, minY, maxX, maxY] = getIndexingCoords(bbox, scale, modelMatrixInverse);
+  const indices: TileIndex[] = [];
+
+  for (let x = Math.floor(minX); x < maxX; x++) {
+    for (let y = Math.floor(minY); y < maxY; y++) {
+      indices.push({x, y, z});
+    }
+  }
+  return indices;
+}
+
+function getTileZoomForViewport(viewport: Viewport, tileSize: number, zoomOffset: number): number {
+  return viewport.isGeospatial
+    ? Math.round(viewport.zoom + Math.log2(TILE_SIZE / tileSize)) + zoomOffset
+    : Math.ceil(viewport.zoom) + zoomOffset;
+}
+
+function applyZoomBounds(
+  z: number,
+  minZoom: number | undefined,
+  maxZoom: number | undefined,
+  extent?: Bounds | null
+): number | null {
+  if (typeof minZoom === 'number' && Number.isFinite(minZoom) && z < minZoom) {
+    if (!extent) {
+      return null;
+    }
+    z = minZoom;
+  }
+  if (typeof maxZoom === 'number' && Number.isFinite(maxZoom) && z > maxZoom) {
+    z = maxZoom;
+  }
+  return z;
+}
+
+function getDeckTileIndices(context: SharedTileset2DTraversalContext<Viewport>): TileIndex[] {
+  const {
+    viewState: viewport,
+    maxZoom,
+    minZoom,
+    zRange = null,
+    extent,
+    tileSize = TILE_SIZE,
+    modelMatrix,
+    modelMatrixInverse,
+    zoomOffset = 0
+  } = context;
+  let z = getTileZoomForViewport(viewport, tileSize, zoomOffset);
+  z = applyZoomBounds(z, minZoom, maxZoom, extent);
+  if (z === null) {
+    return [];
+  }
+
+  let transformedExtent = extent || undefined;
+  if (modelMatrix && modelMatrixInverse && extent && !viewport.isGeospatial) {
+    transformedExtent = transformBox(extent, modelMatrix);
+  }
+
+  return viewport.isGeospatial
+    ? getOSMTileIndices(viewport, z, zRange, extent || undefined)
+    : getIdentityTileIndices(
+        viewport,
+        z,
+        tileSize,
+        transformedExtent || DEFAULT_EXTENT,
+        modelMatrixInverse
+      );
+}
+
+function getDeckTileBoundingBox(
+  context: SharedTileset2DTileContext<Viewport>,
+  index: TileIndex
+): TileBoundingBox {
+  return tileToBoundingBox(context.viewState, index.x, index.y, index.z, context.tileSize);
+}
+
+/** Deck.gl adapter used by {@link SharedTile2DLayer} to drive a generic {@link SharedTileset2D}. */
+export const sharedTile2DDeckAdapter: SharedTileset2DAdapter<Viewport> = {
+  getTileIndices: getDeckTileIndices,
+  getTileBoundingBox: getDeckTileBoundingBox
+};
+
+/** Type guard for geographic tile bounds. */
+export function isGeoBoundingBox(v: any): v is GeoBoundingBox {
+  return (
+    Number.isFinite(v.west) &&
+    Number.isFinite(v.north) &&
+    Number.isFinite(v.east) &&
+    Number.isFinite(v.south)
+  );
+}

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

@@ -0,0 +1,7 @@
+// deck.gl-community
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+export {SharedTile2DLayer} from './shared-tile-2d-layer';
+export type {SharedTile2DLayerProps, SharedTile2DLayerPickingInfo} from './shared-tile-2d-layer';
+export {sharedTile2DDeckAdapter} from './deck-tileset-adapter';