@deck.gl-community/geo-layers 9.2.0-beta.3

package/src/global-grid-systems/s2-geometry/s2-geometry.ts

@@ -0,0 +1,180 @@
+// math.gl
+// SPDX-License-Identifier: MIT and ISC
+// Copyright (c) vis.gl contributors
+
+// math.gl, MIT license
+/*
+Adapted from s2-geometry under ISC License (ISC)
+Copyright (c) 2012-2016, Jon Atkins <github@jonatkins.com>
+Copyright (c) 2016, AJ ONeal <aj@daplie.com>
+Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies.
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+*/
+
+export type S2Cell = {
+  face: number;
+  ij: [number, number];
+  level: number;
+};
+
+export function getS2Cell(s2Index: bigint): S2Cell {
+  const key = toHilbertQuadkey(s2Index);
+  const s2cell = fromHilbertQuadKey(key);
+  return s2cell;
+}
+
+//
+// Functional Style
+//
+const FACE_BITS = 3;
+const MAX_LEVEL = 30;
+const POS_BITS = 2 * MAX_LEVEL + 1; // 61 (60 bits of data, 1 bit lsb marker)
+const RADIAN_TO_DEGREE = 180 / Math.PI;
+
+/*
+  Original function taken from deck.gl doesn't support the case of (face <= 5)
+  It's fixed here.
+*/
+export function fromHilbertQuadKey(hilbertQuadkey: string): S2Cell {
+  const parts = hilbertQuadkey.split('/');
+  const face = parseInt(parts[0], 10);
+  const position = parts[1];
+  /*
+    Fix for the case of level==0 that corresponds to (face <= 5)
+    const maxLevel = position.length;
+    let level;
+  */
+  const maxLevel = face > 5 ? position.length : 0;
+  let level = 0;
+
+  const point = [0, 0] as [number, number];
+
+  for (let i = maxLevel - 1; i >= 0; i--) {
+    level = maxLevel - i;
+    const bit = position[i];
+    let rx = 0;
+    let ry = 0;
+    if (bit === '1') {
+      ry = 1;
+    } else if (bit === '2') {
+      rx = 1;
+      ry = 1;
+    } else if (bit === '3') {
+      rx = 1;
+    }
+
+    const val = Math.pow(2, level - 1);
+    rotateAndFlipQuadrant(val, point, rx, ry);
+
+    point[0] += val * rx;
+    point[1] += val * ry;
+  }
+
+  if (face % 2 === 1) {
+    const t = point[0];
+    point[0] = point[1];
+    point[1] = t;
+  }
+
+  return {face, ij: point, level};
+}
+
+export function toHilbertQuadkey(id: bigint): string {
+  let bin = id.toString(2);
+
+  while (bin.length < FACE_BITS + POS_BITS) {
+    // eslint-disable-next-line prefer-template
+    bin = '0' + bin;
+  }
+
+  // MUST come AFTER binstr has been left-padded with '0's
+  const lsbIndex = bin.lastIndexOf('1');
+  // substr(start, len)
+  // substring(start, end) // includes start, does not include end
+  const faceB = bin.substring(0, 3);
+  // posB will always be a multiple of 2 (or it's invalid)
+  const posB = bin.substring(3, lsbIndex);
+  const levelN = posB.length / 2;
+
+  const faceS = BigInt(`0b${faceB}`).toString(10);
+
+  /*
+    Here is a fix for the case when posB is an empty string that causes an exception in Long.fromString
+
+    let posS = Long.fromString(posB, true, 2).toString(4);
+  */
+  let posS = '0';
+  if (levelN !== 0) {
+    // posB is not an empty string< because levelN!==0
+    posS = BigInt(`0b${posB}`).toString(4);
+
+    while (posS.length < levelN) {
+      // eslint-disable-next-line prefer-template
+      posS = '0' + posS;
+    }
+  }
+  // Note, posS will be "0" for the level==0
+  // TODO: Is it ok?
+
+  return `${faceS}/${posS}`;
+}
+
+export function IJToST(
+  ij: [number, number],
+  order: number,
+  offsets: [number, number]
+): [number, number] {
+  const maxSize = 1 << order;
+
+  return [(ij[0] + offsets[0]) / maxSize, (ij[1] + offsets[1]) / maxSize];
+}
+
+function singleSTtoUV(st: number): number {
+  if (st >= 0.5) {
+    return (1 / 3.0) * (4 * st * st - 1);
+  }
+  return (1 / 3.0) * (1 - 4 * (1 - st) * (1 - st));
+}
+
+export function STToUV(st: [number, number]): [number, number] {
+  return [singleSTtoUV(st[0]), singleSTtoUV(st[1])];
+}
+
+export function FaceUVToXYZ(face: number, [u, v]: [number, number]): [number, number, number] {
+  switch (face) {
+    case 0:
+      return [1, u, v];
+    case 1:
+      return [-u, 1, v];
+    case 2:
+      return [-u, -v, 1];
+    case 3:
+      return [-1, -v, -u];
+    case 4:
+      return [v, -1, -u];
+    case 5:
+      return [v, u, -1];
+    default:
+      throw new Error('Invalid face');
+  }
+}
+
+export function XYZToLngLat([x, y, z]: [number, number, number]): [number, number] {
+  const lat = Math.atan2(z, Math.sqrt(x * x + y * y));
+  const lng = Math.atan2(y, x);
+
+  return [lng * RADIAN_TO_DEGREE, lat * RADIAN_TO_DEGREE];
+}
+
+function rotateAndFlipQuadrant(n: number, point: [number, number], rx: number, ry: number): void {
+  if (ry === 0) {
+    if (rx === 1) {
+      point[0] = n - 1 - point[0];
+      point[1] = n - 1 - point[1];
+    }
+
+    const x = point[0];
+    point[0] = point[1];
+    point[1] = x;
+  }
+}

package/src/global-grid-systems/s2-geometry/s2-to-boundary.ts

@@ -0,0 +1,76 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {IJToST, STToUV, FaceUVToXYZ, XYZToLngLat, getS2Cell} from './s2-geometry';
+
+const MAX_RESOLUTION = 100;
+
+export function getS2GeoBounds(s2Index: bigint): Float64Array {
+  const s2Cell = getS2Cell(s2Index);
+  return getS2GeoBoundsFromCell(s2Cell);
+}
+
+/**
+ * The S2 cell edge is curved: http://s2geometry.io/
+ * This is more prominent at lower levels
+ * resolution is the number of segments to generate per edge.
+ * We exponentially reduce resolution as level increases so it doesn't affect perf
+ * when there are a large number of cells
+ */
+// eslint-disable-next-line max-statements
+export function getS2GeoBoundsFromCell({
+  face,
+  ij,
+  level
+}: {
+  face: number;
+  ij: [number, number];
+  level: number;
+}): Float64Array {
+  const offsets = [
+    [0, 0],
+    [0, 1],
+    [1, 1],
+    [1, 0],
+    [0, 0]
+  ];
+
+  const resolution = Math.max(1, Math.ceil(MAX_RESOLUTION * Math.pow(2, -level)));
+  const result = new Float64Array(4 * resolution * 2 + 2);
+  let ptIndex = 0;
+  let prevLng = 0;
+
+  for (let i = 0; i < 4; i++) {
+    const offset = offsets[i].slice(0) as [number, number];
+    const nextOffset = offsets[i + 1];
+    const stepI = (nextOffset[0] - offset[0]) / resolution;
+    const stepJ = (nextOffset[1] - offset[1]) / resolution;
+
+    for (let j = 0; j < resolution; j++) {
+      offset[0] += stepI;
+      offset[1] += stepJ;
+      // Cell can be represented by coordinates IJ, ST, UV, XYZ
+      // http://s2geometry.io/devguide/s2cell_hierarchy#coordinate-systems
+      const st = IJToST(ij, level, offset);
+      const uv = STToUV(st);
+      const xyz = FaceUVToXYZ(face, uv);
+      const lngLat = XYZToLngLat(xyz);
+
+      // Adjust longitude for Web Mercator projection
+      if (Math.abs(lngLat[1]) > 89.999) {
+        lngLat[0] = prevLng;
+      }
+      const deltaLng = lngLat[0] - prevLng;
+      lngLat[0] += deltaLng > 180 ? -360 : deltaLng < -180 ? 360 : 0;
+
+      result[ptIndex++] = lngLat[0];
+      result[ptIndex++] = lngLat[1];
+      prevLng = lngLat[0];
+    }
+  }
+  // close the loop
+  result[ptIndex++] = result[0];
+  result[ptIndex++] = result[1];
+  return result;
+}

package/src/global-grid-systems/s2-geometry/s2-token.ts

@@ -0,0 +1,70 @@
+// math.gl
+// SPDX-License-Identifier: MIT and Apache-2.0
+// Copyright (c) vis.gl contributors
+
+// s2-geometry is a pure JavaScript port of Google/Niantic's S2 Geometry library
+// which is perfect since it works in the browser.
+
+// const MAXIMUM_TOKEN_LENGTH = 16;
+
+// INDEX CALCULATIONS
+
+/**
+ * Given an S2 token (String) this function convert the token to 64 bit id (Index)
+ * 'X' is the empty cell
+ * https://github.com/google/s2-geometry-library-java/blob/c04b68bf3197a9c34082327eeb3aec7ab7c85da1/src/com/google/common/geometry/S2CellId.java#L439
+ */
+export function getS2IndexFromToken(token: string): bigint {
+  if (token === 'X') {
+    token = '';
+  }
+  // pad token with zeros to make the length 16
+  const paddedToken = token.padEnd(16, '0');
+  return BigInt(`0x${paddedToken}`);
+}
+
+/**
+ * Convert a 64 bit number to a string token
+ * 'X' is the empty cell
+ */
+export function getS2TokenFromIndex(cellId: bigint): string {
+  if (cellId === 0n) {
+    return 'X';
+  }
+  let numZeroDigits = countTrailingZeros(cellId);
+
+  const remainder = numZeroDigits % 4;
+  numZeroDigits = (numZeroDigits - remainder) / 4;
+  const trailingZeroHexChars = numZeroDigits;
+  numZeroDigits *= 4;
+
+  const x = cellId >> BigInt(numZeroDigits);
+  const hexString = x.toString(16).replace(/0+$/, '');
+  const zeroString = Array(17 - trailingZeroHexChars - hexString.length).join('0');
+  return zeroString + hexString;
+}
+
+export function getS2ChildIndex(s2Index: bigint, index: number): bigint {
+  // Shift sentinel bit 2 positions to the right.
+  const newLsb = lsb(s2Index) >> 2n;
+  // Insert child index before the sentinel bit.
+  const childCellId: bigint = s2Index + BigInt(2 * index + 1 - 4) * newLsb;
+  return childCellId;
+}
+
+/**
+ * Return the lowest-numbered bit that is on for this cell id
+ * @private
+ */
+function lsb(cellId: bigint): bigint {
+  return cellId & (cellId + 1n); // eslint-disable-line
+}
+
+function countTrailingZeros(n: bigint): number {
+  let count = 0;
+  while (n % 2n === 0n) {
+    n /= 2n;
+    count++;
+  }
+  return count;
+}

package/src/global-grid-systems/utils/geometry-utils.ts

@@ -0,0 +1,28 @@
+// deck.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {type CoordPair} from '../h3-js-bigint/h3-js-bigint';
+
+// normalize longitudes w.r.t center (refLng), when not provided first vertex
+export function normalizeLongitudes(vertices: CoordPair[], refLng?: number): void {
+  refLng = refLng === undefined ? vertices[0][0] : refLng;
+  for (const pt of vertices) {
+    const deltaLng = pt[0] - refLng;
+    if (deltaLng > 180) {
+      pt[0] -= 360;
+    } else if (deltaLng < -180) {
+      pt[0] += 360;
+    }
+  }
+}
+
+export function flattenPolygon(vertices: number[][]): Float64Array {
+  const positions = new Float64Array(vertices.length * 2);
+  let i = 0;
+  for (const pt of vertices) {
+    positions[i++] = pt[0];
+    positions[i++] = pt[1];
+  }
+  return positions;
+}

package/src/global-grid-systems/utils/h3-utils.ts

@@ -0,0 +1,52 @@
+// deck.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {lerp} from '@math.gl/core';
+import {
+  type CoordPair,
+  type H3IndexInput, // Either string or SplitLong
+  cellToBoundary,
+  cellToLatLng
+} from '../h3-js-bigint/h3-js-bigint';
+import {normalizeLongitudes} from './geometry-utils';
+
+// UTILITIES - TODO can these be generalized using the decoder?
+
+// scale polygon vertices w.r.t center (hexId)
+export function scalePolygon(hexId: H3IndexInput, vertices: CoordPair[], factor: number): void {
+  const [lat, lng] = cellToLatLng(hexId);
+  const actualCount = vertices.length;
+
+  // normalize with respect to center
+  normalizeLongitudes(vertices, lng);
+
+  // `cellToBoundary` returns same array object for first and last vertex (closed polygon),
+  // if so skip scaling the last vertex
+  const vertexCount = vertices[0] === vertices[actualCount - 1] ? actualCount - 1 : actualCount;
+  for (let i = 0; i < vertexCount; i++) {
+    vertices[i][0] = lerp(lng, vertices[i][0], factor);
+    vertices[i][1] = lerp(lat, vertices[i][1], factor);
+  }
+}
+
+// gets hexagon centroid
+export function getHexagonCentroid(getHexagon, object, objectInfo) {
+  const hexagonId = getHexagon(object, objectInfo);
+  const [lat, lng] = cellToLatLng(hexagonId);
+  return [lng, lat];
+}
+
+export function h3ToPolygon(hexId: H3IndexInput, coverage: number = 1): number[][] {
+  const vertices = cellToBoundary(hexId, true);
+
+  if (coverage !== 1) {
+    // scale and normalize vertices w.r.t to center
+    scalePolygon(hexId, vertices, coverage);
+  } else {
+    // normalize w.r.t to start vertex
+    normalizeLongitudes(vertices);
+  }
+
+  return vertices;
+}

package/src/global-grid-systems/utils/hex-utils.ts

@@ -0,0 +1,37 @@
+/**
+ * Converts a hexadecimal string (with or without “0x” prefix) to a bigint.
+ * @param hex - The hex string representation (e.g., "0x1a2b", "FF", "00ff")
+ * @returns The corresponding bigint value.
+ * @throws {Error} If the input is not a valid hex string.
+ */
+export function hexToBigInt(hex: string): bigint {
+  if (typeof hex !== 'string') {
+    throw new Error(`hexToBigInt: expected string, got ${typeof hex}`);
+  }
+
+  let s = hex.trim();
+  if (s.startsWith('0x') || s.startsWith('0X')) {
+    s = s.slice(2);
+  }
+
+  if (s === '') {
+    throw new Error(`hexToBigInt: empty hex string`);
+  }
+
+  // validate: only hex digits
+  if (!/^[0-9A-Fa-f]+$/.test(s)) {
+    throw new Error(`hexToBigInt: invalid hex string “${hex}”`);
+  }
+
+  // Optional: normalize even length by prepending a zero if odd
+  if (s.length % 2 === 1) {
+    s = `0${  s}`;
+  }
+
+  // Use BigInt conversion from string with 0x prefix
+  try {
+    return BigInt(`0x${  s}`);
+  } catch (e) {
+    throw new Error(`hexToBigInt: cannot convert hex string “${hex}” to bigint: ${(e as Error).message}`);
+  }
+}

package/src/index.ts

@@ -0,0 +1,15 @@
+// deck.gl-community
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+export type {TileSourceLayerProps} from './tile-source-layer/tile-source-layer';
+export {TileSourceLayer} from './tile-source-layer/tile-source-layer';
+
+export {GlobalGridLayer, type GlobalGridLayerProps} from './global-grid-layer/global-grid-layer';
+
+export {type GlobalGrid} from './global-grid-systems/grids/global-grid';
+export {A5Grid} from './global-grid-systems/grids/a5-grid';
+export {H3Grid} from './global-grid-systems/grids/h3-grid';
+export {S2Grid} from './global-grid-systems/grids/s2-grid';
+export {GeohashGrid} from './global-grid-systems/grids/geohash-grid';
+export {QuadkeyGrid} from './global-grid-systems/grids/quadkey-grid';

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

@@ -0,0 +1,156 @@
+// deck.gl-community
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {CompositeLayer, Layer} from '@deck.gl/core';
+import type {TileLayerProps} from '@deck.gl/geo-layers';
+import {TileLayer} from '@deck.gl/geo-layers';
+import {BitmapLayer, GeoJsonLayer, PathLayer} from '@deck.gl/layers';
+import type {TileSource} from '@loaders.gl/loader-utils';
+
+/* global window */
+const devicePixelRatio = (typeof window !== 'undefined' && window.devicePixelRatio) || 1;
+
+export type TileSourceLayerProps = TileLayerProps & {
+  tileSource: TileSource<any>;
+  showTileBorders?: boolean;
+};
+
+/**
+ * A Deck.gl layer that renders a tile source
+ * Autodiscovers type of content (vector tile, bitmap, ...)
+ * Can render debug borders around tiles
+ * TODO - Change debug border color based on zoom level
+ */
+export class TileSourceLayer extends CompositeLayer<TileSourceLayerProps> {
+  static layerName = 'TileSourceLayer';
+  static defaultProps = {
+    ...TileLayer.defaultProps,
+    showTileBorders: true
+  };
+
+  state: {
+    tileSource: TileSource<any> | null;
+  } = undefined!;
+
+  initializeState() {
+    this.setState({
+      tileSource: null
+    });
+  }
+
+  updateState({props, changeFlags}) {
+    this.setState({
+      tileSource: props.tileSource
+    });
+  }
+
+  renderLayers() {
+    const {tileSource, showTileBorders, metadata, onTilesLoad} = this.props as any;
+    const minZoom = metadata?.minZoom || 0;
+    const maxZoom = metadata?.maxZoom || 30;
+
+    return [
+      new TileLayer({
+        // HACK: Trigger new layer via id prop to force clear tile cache
+        id: String(tileSource.url),
+        getTileData: tileSource.getTileData,
+        // Assume the pmtiles file support HTTP/2, so we aren't limited by the browser to a certain number per domain.
+        maxRequests: 20,
+
+        pickable: true,
+        onViewportLoad: onTilesLoad,
+        autoHighlight: showTileBorders,
+        highlightColor: [60, 60, 60, 40],
+        minZoom,
+        maxZoom,
+        tileSize: 256,
+        // TOOD - why is this needed?
+        zoomOffset: devicePixelRatio === 1 ? -1 : 0,
+        renderSubLayers: renderSubLayers as any,
+
+        // Custom prop
+        tileSource,
+        showTileBorders
+      })
+    ];
+  }
+}
+
+function renderSubLayers(
+  props: TileSourceLayerProps & {tile: {index; bbox: {west; south; east; north}}}
+) {
+  const {
+    tileSource,
+    showTileBorders,
+    minZoom,
+    maxZoom,
+    tile: {
+      index: {z: zoom},
+      bbox: {west, south, east, north}
+    }
+  } = props as any;
+
+  const layers: Layer[] = [];
+
+  const borderColor = zoom <= minZoom || zoom >= maxZoom ? [255, 0, 0, 255] : [0, 0, 255, 255];
+
+  switch (tileSource.mimeType) {
+    case 'application/vnd.mapbox-vector-tile':
+      layers.push(
+        new GeoJsonLayer({
+          id: `${props.id}-geojson`,
+          data: props.data as any,
+          pickable: true,
+          getFillColor: [0, 190, 80, 255],
+          lineWidthScale: 500,
+          lineWidthMinPixels: 0.5
+        })
+      );
+      break;
+
+    case 'image/png':
+    case 'image/jpeg':
+    case 'image/webp':
+    case 'image/avif':
+      layers.push(
+        new BitmapLayer(
+          props as any,
+          {
+            data: null,
+            image: props.data,
+            bounds: [west, south, east, north],
+            pickable: true
+          } as any
+        )
+      );
+      break;
+
+    default:
+      // eslint-disable-next-line no-console
+      console.error('Unknown tile mimeType', tileSource?.mimeType);
+  }
+
+  // Debug tile borders
+  if (showTileBorders) {
+    layers.push(
+      new PathLayer({
+        id: `${props.id}-border`,
+        data: [
+          [
+            [west, north],
+            [west, south],
+            [east, south],
+            [east, north],
+            [west, north]
+          ]
+        ],
+        getPath: (d) => d,
+        getColor: borderColor as any,
+        widthMinPixels: 4
+      })
+    );
+  }
+
+  return layers;
+}