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

package/src/global-grid-systems/grids/geohash-grid.ts

@@ -0,0 +1,105 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {type Bounds2D} from '@math.gl/types';
+import {type GlobalGrid} from './global-grid';
+
+/** Decoder for the geohash global grid system */
+export const GeohashGrid = {
+  name: 'geohash',
+  hasNumericRepresentation: false,
+
+  cellToLngLat: (geohash: string | bigint): [number, number] =>
+    getGeohashLngLat(getString(geohash)),
+  cellToBoundary: (geohash: string | bigint): [number, number][] =>
+    getGeohashBoundary(getString(geohash))
+  // cellToBoundaryPolygonFlat: (geohash: bigint): number[] => getGeohashBoundaryFlat(geohash),
+  // cellToBounds: (geohash: bigint): Bounds2D => getGeohashBounds(geohash)
+} as const satisfies GlobalGrid;
+
+const getString = (geohash: string | bigint): string => {
+  if (typeof geohash !== 'string') {
+    throw new Error('geohash must be a string');
+  }
+  return geohash;
+};
+
+const BASE32_CODES = '0123456789bcdefghjkmnpqrstuvwxyz';
+const BASE32_CODES_DICT: Record<string, number> = {};
+for (let i = 0; i < BASE32_CODES.length; i++) {
+  BASE32_CODES_DICT[BASE32_CODES.charAt(i)] = i;
+}
+
+const MIN_LAT = -90;
+const MAX_LAT = 90;
+const MIN_LON = -180;
+const MAX_LON = 180;
+
+/** Return center lng,lat of geohash cell */
+function getGeohashLngLat(geohash: string): [number, number] {
+  const [[s, w], [n, e]] = getGeohashBounds(geohash);
+  return [(e + w) / 2, (n + s) / 2];
+}
+
+/** Return boundary polygon of geohash cell as lng,lat array */
+function getGeohashBoundary(geohash: string): [number, number][] {
+  const [[s, w], [n, e]] = getGeohashBounds(geohash);
+  return [
+    [e, n],
+    [e, s],
+    [w, s],
+    [w, n],
+    [e, n]
+  ];
+}
+
+/** Return boundary polygon of geohash cell as flat array */
+export function getGeohashBoundaryFlat(geohash: string): number[] {
+  const [[s, w], [n, e]] = getGeohashBounds(geohash);
+  return [e, n, e, s, w, s, w, n, e, n];
+}
+
+/**
+ * @note Adapted from ngeohash decode_bbox
+ */
+/* eslint-disable max-depth */
+export function getGeohashBounds(geohash: string): Bounds2D {
+  let isLon = true;
+  let maxLat = MAX_LAT;
+  let minLat = MIN_LAT;
+  let maxLon = MAX_LON;
+  let minLon = MIN_LON;
+  let mid: number;
+
+  let hashValue = 0;
+  for (let i = 0, l = geohash.length; i < l; i++) {
+    const code = geohash[i].toLowerCase();
+    hashValue = BASE32_CODES_DICT[code];
+
+    for (let bits = 4; bits >= 0; bits--) {
+      const bit = (hashValue >> bits) & 1;
+      if (isLon) {
+        mid = (maxLon + minLon) / 2;
+        if (bit === 1) {
+          minLon = mid;
+        } else {
+          maxLon = mid;
+        }
+      } else {
+        mid = (maxLat + minLat) / 2;
+        if (bit === 1) {
+          minLat = mid;
+        } else {
+          maxLat = mid;
+        }
+      }
+      isLon = !isLon;
+    }
+  }
+
+  return [
+    [minLat, minLon],
+    [maxLat, maxLon]
+  ];
+}

package/src/global-grid-systems/grids/global-grid.ts

@@ -0,0 +1,40 @@
+// deck.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+/**
+ * Copy of same type in math.gl. They are structurally identical.
+ * This type declares a "standardized" API for accessing basic DGGS token decoding
+ * DGGS modules export objects that satisfy this "interface",
+ * allowing different DGGS systems can be used interchangeably.
+ */
+export type GlobalGrid = {
+  /** The name of the DGGS */
+  name: string;
+
+  /** Does this grid have a numeric representation of cells? */
+  hasNumericRepresentation: boolean;
+
+  /** Initialization function. Should be idempotent, i.e. it may be called multiple times */
+  initialize?: () => void;
+
+  /** Is the argument a valid index in this grid? */
+  isValidCell?: (cell: string | bigint) => boolean;
+
+  /** Convert a string token to a binary cell index */
+  tokenToCell?: (token: string) => bigint;
+  /** Convert a binary cell index to a token */
+  cellToToken?: (cell: string | bigint) => string;
+
+  /** Convert a long, lat to a cell */
+  lngLatToCell?: (lngLat: [number, number], resolution) => bigint;
+  /** Convert a long, lat to a string token (H3 index) */
+  lngLatToToken?: (lngLat: [number, number], resolution) => string;
+
+  /** @returns the center of the cell */
+  cellToLngLat: (cell: string | bigint) => [number, number];
+  /** @returns the boundary of the cell, as an array of coordinate arrays */
+  cellToBoundary: (cell: string | bigint) => [number, number][];
+  /** @returns the bounds of the cell */
+  cellsToBoundaryMultiPolygon?: (cells: string[] | bigint[]) => [number, number][][][];
+};

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

@@ -0,0 +1,45 @@
+// deck.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {type GlobalGrid} from './global-grid';
+import {
+  latLngToCell,
+  cellToBoundary,
+  cellToLatLng,
+  cellsToMultiPolygon,
+  h3IndexToBigInt
+} from '../h3-js-bigint/h3-js-bigint';
+
+/**
+ * "Standardized" API for working with H3 DGGS tokens.
+ * @note Inspired by similar work in math.gl. May replace by an import in the future.
+ */
+export const H3Grid = {
+  name: 'H3',
+  hasNumericRepresentation: true,
+
+  // See `main/bundle.ts`, installs a check for the H3 library.
+  initialize: () => {},
+
+  tokenToCell: (token: string) => h3IndexToBigInt(token),
+
+  lngLatToToken: (lngLat: [number, number], resolution: number) =>
+    latLngToCell(lngLat[1], lngLat[0], resolution),
+  lngLatToCell: (lngLat: [number, number], resolution: number) =>
+    h3IndexToBigInt(latLngToCell(lngLat[1], lngLat[0], resolution)),
+
+  cellToLngLat: (cell: string | bigint) => reverseLatLngInPlace(cellToLatLng(cell)),
+  cellToBoundary: (cell: string | bigint) => cellToBoundary(cell),
+  cellsToBoundaryMultiPolygon: (cells: string[] | bigint[]) => cellsToMultiPolygon(cells, true)
+} as const satisfies GlobalGrid;
+
+// HELPERS
+
+/** Reverse the latitude and longitude in place to avoid minting new arrays. */
+function reverseLatLngInPlace(latLng: [number, number]): [number, number] {
+  const temp = latLng[0];
+  latLng[0] = latLng[1];
+  latLng[1] = temp;
+  return latLng;
+}

package/src/global-grid-systems/grids/quadkey-grid.ts

@@ -0,0 +1,190 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {type Bounds2D} from '@math.gl/types';
+import {type GlobalGrid} from './global-grid';
+
+const TILE_SIZE = 512;
+
+/** Decoder for the quadkey DGGS */
+export const QuadkeyGrid = {
+  name: 'quadkey',
+  hasNumericRepresentation: true,
+
+  // cellToToken: (cell: bigint): string => quadkeyCellToToken(cell),
+  // tokenToCell: (cell: string): bigint => quadKeyToBigint(cell),
+
+  cellToLngLat: (cell: string | bigint): [number, number] => quadkeyCellToLngLat(getString(cell)),
+  cellToBoundary: (cell: string | bigint): [number, number][] =>
+    quadkeyCellToBoundary(getString(cell))
+
+  // cellToBoundaryPolygonFlat: (cell: string | bigint): number[] => getQuadkeyBoundaryFlat(cell),
+  // cellToBounds: (cell: string | bigint): Bounds2D => getQuadkeyBounds(cell)
+} as const satisfies GlobalGrid;
+
+/** Quadkey only supports strings */
+const getString = (cell: string | bigint): string => {
+  if (typeof cell !== 'string') {
+    throw new Error('geohash must be a string');
+  }
+  return cell;
+};
+
+function quadkeyCellToLngLat(quadkey: string): [number, number] {
+  const [topLeft, bottomRight] = quadkeyToWorldBounds(quadkey);
+  const [w, n] = worldToLngLat(topLeft);
+  const [e, s] = worldToLngLat(bottomRight);
+  return [(e + w) / 2, (s + n) / 2];
+}
+
+function quadkeyCellToBoundary(quadkey: string): [number, number][] {
+  const [topLeft, bottomRight] = quadkeyToWorldBounds(quadkey);
+  const [w, n] = worldToLngLat(topLeft);
+  const [e, s] = worldToLngLat(bottomRight);
+  return [
+    [e, n],
+    [e, s],
+    [w, s],
+    [w, n],
+    [e, n]
+  ];
+}
+
+export function quadkeyCellToBoundaryFlat(quadkey: string): number[] {
+  const [topLeft, bottomRight] = quadkeyToWorldBounds(quadkey);
+  const [w, n] = worldToLngLat(topLeft);
+  const [e, s] = worldToLngLat(bottomRight);
+  return [e, n, e, s, w, s, w, n, e, n];
+}
+
+export function quadkeyCellToBounds(quadkey: string): Bounds2D {
+  const [topLeft, bottomRight] = quadkeyToWorldBounds(quadkey);
+  const [w, n] = worldToLngLat(topLeft);
+  const [e, s] = worldToLngLat(bottomRight);
+  return [
+    [w, s],
+    [e, n]
+  ];
+}
+
+export function quadkeyToWorldBounds(quadkey: string): [[number, number], [number, number]] {
+  let x = 0;
+  let y = 0;
+  let mask = 1 << quadkey.length;
+  const scale = mask / TILE_SIZE;
+
+  for (let i = 0; i < quadkey.length; i++) {
+    mask >>= 1;
+    const q = parseInt(quadkey[i], 10);
+    if (q % 2) x |= mask;
+    if (q > 1) y |= mask;
+  }
+  return [
+    [x / scale, TILE_SIZE - y / scale],
+    [(x + 0.99) / scale, TILE_SIZE - (y + 0.99) / scale]
+  ];
+}
+
+// CONSTANTS
+const PI = Math.PI;
+const PI_4 = PI / 4;
+const RADIANS_TO_DEGREES = 180 / PI;
+
+/**
+ * Unproject world point [x,y] on map onto {lat, lon} on sphere
+ *
+ * @param xy - array with [x,y] members
+ *  representing point on projected map plane
+ * @return - array with [x,y] of point on sphere.
+ *   Has toArray method if you need a GeoJSON Array.
+ *   Per cartographic tradition, lat and lon are specified as degrees.
+ */
+function worldToLngLat(xy: number[]): [number, number] {
+  const [x, y] = xy;
+  const lambda2 = (x / TILE_SIZE) * (2 * PI) - PI;
+  const phi2 = 2 * (Math.atan(Math.exp((y / TILE_SIZE) * (2 * PI) - PI)) - PI_4);
+  return [lambda2 * RADIANS_TO_DEGREES, phi2 * RADIANS_TO_DEGREES];
+}
+
+// EXPERIMENTAL BIGINT ENCODING FOR QUADKEYS
+
+/**
+ * Encodes a QuadKey string into a bigint.
+ * @param quadkey - The QuadKey string.
+ * @returns The bigint representation of the QuadKey.
+ */
+export function quadKeyToBigint(quadkey: string): bigint {
+  let result = 0n;
+  for (const digit of quadkey) {
+    const value = BigInt(parseInt(digit, 4));
+    result = (result << 2n) | value;
+  }
+  const zoom = quadkey.length;
+  // Shift the result to align with the most significant bits
+  const shift = 64 - 5 - zoom * 2; // Reserve 5 bits for zoom level
+  result = result << BigInt(shift);
+  // Append the zoom level in the least significant 5 bits
+  return result | BigInt(zoom);
+}
+
+/**
+ * Decodes a bigint-encoded QuadKey back into its string representation.
+ * @param encoded - The bigint representation of the QuadKey with embedded zoom level.
+ * @returns The decoded QuadKey string.
+ */
+export function bigintToQuadKey(encoded: bigint): string {
+  const zoom = Number(encoded & 0b11111n); // Extract the last 5 bits for zoom level
+  const shift = BigInt(64 - 5 - zoom * 2); // Calculate the shift to align the QuadKey bits
+  const quadkeyBits = (encoded >> shift) & ((1n << BigInt(zoom * 2)) - 1n); // Extract QuadKey bits
+  let quadkey = '';
+  for (let i = zoom - 1; i >= 0; i--) {
+    const digit = Number((quadkeyBits >> BigInt(i * 2)) & 0b11n);
+    quadkey += digit.toString();
+  }
+  return quadkey;
+}
+
+/**
+ * Checks if the child QuadKey is contained within the parent QuadKey.
+ * @param parent - The bigint representation of the parent QuadKey.
+ * @param child - The bigint representation of the child QuadKey.
+ * @returns True if the child is contained within the parent; otherwise, false.
+ */
+export function isContained(parent: bigint, child: bigint): boolean {
+  const parentZoom = Number(parent & 0b11111n); // Extract zoom level from parent
+  const childZoom = Number(child & 0b11111n); // Extract zoom level from child
+
+  if (parentZoom >= childZoom) return false;
+
+  const parentShift = BigInt(64 - 5 - parentZoom * 2);
+  const childShift = BigInt(64 - 5 - childZoom * 2);
+
+  const parentPrefix = (parent >> parentShift) & ((1n << BigInt(parentZoom * 2)) - 1n);
+  const childPrefix = (child >> childShift) & ((1n << BigInt(parentZoom * 2)) - 1n);
+
+  return parentPrefix === childPrefix;
+}
+
+/**
+ * Decodes a bigint-encoded QuadKey into tile X, tile Y, and zoom level.
+ * @param encoded - The bigint representation of the QuadKey with embedded zoom level.
+ * @returns An object containing tileX, tileY, and zoom.
+ */
+export function decodeBigintQuadKey(encoded: bigint): {tileX: number; tileY: number; zoom: number} {
+  const zoom = Number(encoded & 0b11111n); // Extract the last 5 bits for zoom level
+  const quadKeyBits = encoded >> 5n; // Remove the zoom level bits
+
+  let tileX = 0;
+  let tileY = 0;
+
+  for (let i = 0; i < zoom; i++) {
+    const shift = BigInt((zoom - i - 1) * 2);
+    const digit = Number((quadKeyBits >> shift) & 0b11n);
+    const mask = 1 << (zoom - i - 1);
+    if (digit & 1) tileX |= mask;
+    if (digit & 2) tileY |= mask;
+  }
+
+  return {tileX, tileY, zoom};
+}

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

@@ -0,0 +1,86 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {type Bounds2D} from '@math.gl/types';
+import {type GlobalGrid} from './global-grid';
+
+import {getS2IndexFromToken, getS2TokenFromIndex} from '../s2-geometry/s2-token';
+import {getS2GeoBounds} from '../s2-geometry/s2-to-boundary';
+import {getS2Cell, IJToST, STToUV, FaceUVToXYZ, XYZToLngLat} from '../s2-geometry/s2-geometry';
+
+/** Decoder for the S2 DGGS */
+export const S2Grid = {
+  name: 'S2',
+  hasNumericRepresentation: true,
+
+  tokenToCell: (cell: string): bigint => getS2IndexFromToken(cell),
+  cellToToken: (cell: string | bigint): string => getS2TokenFromIndex(getBigInt(cell)),
+  cellToLngLat: (cell: string | bigint): [number, number] => getS2LngLat(getBigInt(cell)),
+  cellToBoundary: (cell: string | bigint): [number, number][] => getS2Boundary(getBigInt(cell))
+
+  // cellToBoundaryPolygonFlat: (cell: bigint): number[] => getS2BoundaryFlat(cell),
+  // cellToBounds: (cell: bigint): Bounds2D => getS2Bounds(cell)
+} as const satisfies GlobalGrid;
+
+/** S2 functions operate on bigints */
+const getBigInt = (value: string | bigint): bigint => {
+  return typeof value === 'string' ? getS2IndexFromToken(value) : value;
+};
+
+/**
+ * Retrieve S2 geometry center
+ */
+export function getS2LngLat(cell: bigint): [number, number] {
+  const s2Cell = getS2Cell(cell);
+
+  const st = IJToST(s2Cell.ij, s2Cell.level, [0.5, 0.5]);
+  const uv = STToUV(st);
+  const xyz = FaceUVToXYZ(s2Cell.face, uv);
+  const lngLat = XYZToLngLat(xyz);
+
+  return lngLat;
+}
+
+/**
+ * Get a polygon with corner coordinates for an s2 cell
+ * @param - This can be an S2 key or token
+ * @return {Float64Array} - a simple polygon in flat array format: [lng0, lat0, lng1, lat1, ...]
+ *   - the polygon is closed, i.e. last coordinate is a copy of the first coordinate
+ */
+function getS2BoundaryFlat(cell: bigint): number[] {
+  const float64Array = getS2GeoBounds(cell);
+  // TODO - inefficient
+  return Array.from(float64Array);
+}
+
+function getS2Boundary(cell: bigint): [number, number][] {
+  const flatBoundary = getS2BoundaryFlat(cell);
+  const boundary: [number, number][] = [];
+  for (let i = 0; i < flatBoundary.length; i += 2) {
+    boundary.push([flatBoundary[i], flatBoundary[i + 1]]);
+  }
+  return boundary;
+}
+
+export function getS2Bounds(cell: bigint): Bounds2D {
+  const flatBoundary = getS2Boundary(cell);
+
+  // We know that we have at least one point, no Infinity will be returned.
+  let xmin = Infinity;
+  let ymin = Infinity;
+  let xmax = -Infinity;
+  let ymax = -Infinity;
+
+  for (const [x, y] of flatBoundary) {
+    if (x < xmin) xmin = x;
+    if (x > xmax) xmax = x;
+    if (y < ymin) ymin = y;
+    if (y > ymax) ymax = y;
+  }
+
+  return [
+    [xmin, ymin],
+    [xmax, ymax]
+  ];
+}

package/src/global-grid-systems/h3-js-bigint/h3-js-bigint.ts

@@ -0,0 +1,85 @@
+// deck.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+// A thin wrapper around h3-js that support BigInts
+// Note: incurs some overhead as we need to convert between BigInt and SplitLong
+
+import {
+  type CoordPair,
+  type SplitLong,
+  latLngToCell,
+  cellToBoundary as _cellToBoundary,
+  cellToLatLng as _cellToLatLng,
+  cellsToMultiPolygon as _cellsToMultiPolygon,
+  h3IndexToSplitLong as _h3IndexToSplitLong
+  // splitLongToH3Index as _splitLongToH3Index
+} from 'h3-js';
+
+export {type CoordPair, type SplitLong, latLngToCell};
+
+export type H3IndexInput = bigint | string | SplitLong;
+
+const scratchSplitLong: SplitLong = [0, 0];
+
+export function h3IndexToSplitLong(h3Index: H3IndexInput, target?: SplitLong): SplitLong {
+  if (typeof h3Index === 'bigint') {
+    return bigIntToSplitLong(h3Index, target ?? [0, 0]);
+  }
+  return _h3IndexToSplitLong(h3Index);
+}
+
+export function h3IndexToBigInt(h3Index: H3IndexInput): bigint {
+  if (typeof h3Index === 'bigint') {
+    return h3Index;
+  }
+  const splitLong = h3IndexToSplitLong(h3Index, scratchSplitLong);
+  return splitLongToBigInt(splitLong);
+}
+
+export function cellToLatLng(h3Index: H3IndexInput): [number, number] {
+  const splitLong = h3IndexToSplitLong(h3Index, scratchSplitLong);
+  const latLng = _cellToLatLng(splitLong);
+  return latLng;
+}
+
+export function cellToBoundary(h3Index: H3IndexInput, formatAsGeoJson?: boolean): CoordPair[] {
+  const splitLong = h3IndexToSplitLong(h3Index, scratchSplitLong);
+  const vertices = _cellToBoundary(splitLong, formatAsGeoJson);
+  return vertices;
+}
+
+export function cellsToMultiPolygon(
+  h3Indexes: H3IndexInput[],
+  formatAsGeoJson?: boolean
+): CoordPair[][][] {
+  const splitLongs = h3Indexes.map((h3Index) => h3IndexToSplitLong(h3Index));
+  const polygons = _cellsToMultiPolygon(splitLongs, formatAsGeoJson);
+  return polygons;
+}
+
+// HELPERS
+
+/**
+ * Splits a bigint into a 2-element array of 32-bit numbers.
+ * @param value - The bigint to split.
+ * @returns A 2-element array containing the high and low 32-bit numbers.
+ */
+function bigIntToSplitLong(value: bigint, target: SplitLong = [0, 0]): SplitLong {
+  // Mask lower 32 bits
+  target[0] = Number(value & 0xffffffffn); // BigInt & BigInt ⇒ BigInt :contentReference[oaicite:2]{index=2}
+  // Shift right to get upper 32 bits
+  target[1] = Number((value >> 32n) & 0xffffffffn); // BigInt >> BigInt ⇒ BigInt :contentReference[oaicite:3]{index=3}
+  return target;
+}
+
+/**
+ * Joins two 32-bit numbers into a bigint.
+ * @param high - The high 32-bit number.
+ * @param low - The low 32-bit number.
+ * @returns The combined bigint.
+ */
+function splitLongToBigInt([low, high]: SplitLong): bigint {
+  // Shift high half back and OR with low half
+  return (BigInt(high) << 32n) | BigInt(low); // BigInt << BigInt ⇒ BigInt; BigInt | BigInt ⇒ BigInt :contentReference[oaicite:4]{index=4}
+}