@math.gl/dggs 5.0.0-alpha.2

package/src/quadkey-decoder.ts

@@ -0,0 +1,98 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {type Bounds2D} from '@math.gl/types';
+import {type DGGSCell, type DGGSDecoder, getDGGSCellToken} from './dggs-decoder';
+
+const TILE_SIZE = 512;
+
+/** Decoder for the quadkey DGGS */
+export const QuadkeyDecoder = {
+  name: 'quadkey',
+  hasNumericRepresentation: false,
+  cellColumnNames: ['quadkey', 'quadkeyId', 'quadkey_id'],
+  cellToLngLat: (cell: DGGSCell): [number, number] =>
+    getQuadkeyLngLat(getDGGSCellToken(cell, 'Quadkey')),
+  cellToBoundary: (cell: DGGSCell): [number, number][] =>
+    getQuadkeyBoundary(getDGGSCellToken(cell, 'Quadkey')),
+  cellToBoundaryFlat: (cell: DGGSCell): number[] =>
+    getQuadkeyBoundaryFlat(getDGGSCellToken(cell, 'Quadkey')),
+  cellToBounds: (cell: DGGSCell): Bounds2D => getQuadkeyBounds(getDGGSCellToken(cell, 'Quadkey'))
+} as const satisfies DGGSDecoder;
+
+function getQuadkeyLngLat(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 getQuadkeyBoundary(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]
+  ];
+}
+
+function getQuadkeyBoundaryFlat(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];
+}
+
+function getQuadkeyBounds(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];
+}

package/src/quadkey.ts

@@ -0,0 +1,5 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+export {QuadkeyDecoder, quadkeyToWorldBounds} from './quadkey-decoder';

package/src/s2-decoder.ts

@@ -0,0 +1,87 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {type Bounds2D} from '@math.gl/types';
+import {type DGGSCell, type DGGSDecoder} from './dggs-decoder';
+
+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 S2Decoder = {
+  name: 's2',
+  hasNumericRepresentation: true,
+  cellColumnNames: ['s2', 's2Token', 's2_token', 's2Cell', 's2_cell', 's2CellId', 's2_cell_id'],
+  tokenToCell: (s2Token: string): bigint => getS2IndexFromToken(s2Token),
+  cellToToken: (cell: DGGSCell): string =>
+    typeof cell === 'string' ? cell : getS2TokenFromIndex(cell),
+  cellToLngLat: (cell: DGGSCell): [number, number] => getS2LngLat(cell),
+  cellToBoundary: (cell: DGGSCell): [number, number][] => getS2Boundary(cell),
+  cellToBoundaryFlat: (cell: DGGSCell): number[] => getS2BoundaryFlat(cell),
+  cellToBounds: (cell: DGGSCell): Bounds2D => getS2Bounds(cell)
+} as const satisfies DGGSDecoder;
+
+/**
+ * Retrieve S2 geometry center
+ */
+export function getS2LngLat(cell: DGGSCell): [number, number] {
+  const s2Index = getS2CellIndex(cell);
+  const s2Cell = getS2Cell(s2Index);
+
+  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 as [number, number];
+}
+
+/**
+ * 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
+ */
+export function getS2BoundaryFlat(cell: DGGSCell): number[] {
+  const s2Index = getS2CellIndex(cell);
+  const float64Array = getS2GeoBounds(s2Index);
+  // TODO - inefficient
+  return Array.from(float64Array);
+}
+
+function getS2Boundary(cell: DGGSCell): [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;
+}
+
+function getS2Bounds(cell: DGGSCell): 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]
+  ];
+}
+
+function getS2CellIndex(cell: DGGSCell): bigint {
+  return typeof cell === 'bigint' ? cell : getS2IndexFromToken(cell);
+}

package/src/s2-geometry/s2-geometry.ts

@@ -0,0 +1,166 @@
+// 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] || '';
+  const maxLevel = position.length;
+  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);
+
+  let posS = '';
+  if (levelN !== 0) {
+    posS = BigInt(`0b${posB}`).toString(4);
+
+    while (posS.length < levelN) {
+      // eslint-disable-next-line prefer-template
+      posS = '0' + posS;
+    }
+  }
+  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/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/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/s2.ts

@@ -0,0 +1,6 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+export {S2Decoder} from './s2-decoder';
+export {getS2ChildIndex} from './s2-geometry/s2-token';