@math.gl/dggs 5.0.0-alpha.2

package/package.json

@@ -0,0 +1,80 @@
+{
+  "name": "@math.gl/dggs",
+  "description": "Lightweight cell geometry decoders for DGGS and DGGS-like systems",
+  "license": "MIT",
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "version": "5.0.0-alpha.2",
+  "keywords": [
+    "javascript",
+    "math",
+    "geospatial",
+    "dggs",
+    "a5",
+    "h3",
+    "s2",
+    "geohash",
+    "quadkey",
+    "plus-codes"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/visgl/math.gl.git"
+  },
+  "types": "dist/index.d.ts",
+  "main": "dist/index.cjs",
+  "module": "dist/index.js",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./a5": {
+      "types": "./dist/a5.d.ts",
+      "import": "./dist/a5.js",
+      "require": "./dist/a5.cjs"
+    },
+    "./geohash": {
+      "types": "./dist/geohash.d.ts",
+      "import": "./dist/geohash.js",
+      "require": "./dist/geohash.cjs"
+    },
+    "./h3": {
+      "types": "./dist/h3.d.ts",
+      "import": "./dist/h3.js",
+      "require": "./dist/h3.cjs"
+    },
+    "./plus-code": {
+      "types": "./dist/plus-code.d.ts",
+      "import": "./dist/plus-code.js",
+      "require": "./dist/plus-code.cjs"
+    },
+    "./quadkey": {
+      "types": "./dist/quadkey.d.ts",
+      "import": "./dist/quadkey.js",
+      "require": "./dist/quadkey.cjs"
+    },
+    "./s2": {
+      "types": "./dist/s2.d.ts",
+      "import": "./dist/s2.js",
+      "require": "./dist/s2.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "dependencies": {
+    "@math.gl/types": "5.0.0-alpha.2",
+    "a5-js": "^0.5.0",
+    "h3-js": "^4.2.1",
+    "open-location-code": "^1.0.3"
+  },
+  "devDependencies": {
+    "s2-geometry": "^1.2.10"
+  },
+  "gitHead": "1b21ecbe8872e604b1b362fe09ab59240bd5b41e"
+}

package/src/a5-decoder.ts

@@ -0,0 +1,42 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {cellToBoundary, cellToLonLat, hexToU64, u64ToHex} from 'a5-js';
+import {type Bounds2D} from '@math.gl/types';
+import {type DGGSCell, type DGGSDecoder, getDGGSCellBounds} from './dggs-decoder';
+
+/** Lightweight cell geometry decoder for the A5 pentagonal DGGS. */
+export const A5Decoder = {
+  name: 'a5',
+  hasNumericRepresentation: true,
+  cellColumnNames: [
+    'a5',
+    'a5Token',
+    'a5_token',
+    'a5Cell',
+    'a5_cell',
+    'a5CellId',
+    'a5_cell_id',
+    'pentagon'
+  ],
+  tokenToCell: (token: string): bigint => hexToU64(removeHexPrefix(token)),
+  cellToToken: (cell: DGGSCell): string =>
+    typeof cell === 'string' ? removeHexPrefix(cell) : u64ToHex(cell),
+  cellToLngLat: (cell: DGGSCell): [number, number] => cellToLonLat(getA5CellIndex(cell)),
+  cellToBoundary: (cell: DGGSCell): [number, number][] => getA5Boundary(cell),
+  cellToBoundaryFlat: (cell: DGGSCell): number[] => getA5Boundary(cell).flat(),
+  cellToBounds: (cell: DGGSCell): Bounds2D => getDGGSCellBounds(getA5Boundary(cell))
+} as const satisfies DGGSDecoder;
+
+function getA5CellIndex(cell: DGGSCell): bigint {
+  return typeof cell === 'bigint' ? cell : hexToU64(removeHexPrefix(cell));
+}
+
+function getA5Boundary(cell: DGGSCell): [number, number][] {
+  return cellToBoundary(getA5CellIndex(cell)).map(([longitude, latitude]) => [longitude, latitude]);
+}
+
+function removeHexPrefix(token: string): string {
+  return token.startsWith('0x') || token.startsWith('0X') ? token.slice(2) : token;
+}

package/src/a5.ts

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

package/src/converters/s2-to-obb-points.ts

@@ -0,0 +1,78 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {getS2Cell} from '../s2-geometry/s2-geometry';
+import {getS2Region} from './s2-to-region';
+import {getS2IndexFromToken} from '../s2-geometry/s2-token';
+
+// import {OrientedBoundingBox, makeOrientedBoundingBoxFromPoints} from '@math.gl/culling';
+// import {Ellipsoid} from '@math.gl/geospatial';
+
+export type S2HeightInfo = {
+  minimumHeight: number;
+  maximumHeight: number;
+};
+
+/**
+ * Converts S2HeightInfo to corner points of an oriented bounding box
+ * Can be used to constuct an OrientedBoundingBox instance
+ *
+ * @param s2bv - s2 bounding volume to convert
+ * @param [result] Optional object onto which to store the result.
+ * @returns The modified result parameter or a new `OrientedBoundingBox` instance if not provided.
+ */
+export function getS2OrientedBoundingBoxCornerPoints(
+  s2token: string, // This can be an S2 key or token
+  heighInfo?: S2HeightInfo
+): number[][] {
+  const min: number = heighInfo?.minimumHeight || 0;
+  const max: number = heighInfo?.maximumHeight || 0;
+
+  const s2index = getS2IndexFromToken(s2token);
+  const s2cell = getS2Cell(s2index);
+  const region = getS2Region(s2cell);
+
+  // region is {lngWest, latSouth, lngEast, latNorth} in degrees
+  const W = region[0];
+  const S = region[1];
+  const E = region[2];
+  const N = region[3];
+
+  const points: number[][] = [];
+
+  points.push([W, N, min]);
+  points.push([E, N, min]);
+  points.push([E, S, min]);
+  points.push([W, S, min]);
+
+  points.push([W, N, max]);
+  points.push([E, N, max]);
+  points.push([E, S, max]);
+  points.push([W, S, max]);
+
+  return points;
+}
+
+/*
+function convertCartToXYZ(longitude, latitude, height, result?) {
+  const point = Ellipsoid.WGS84.cartographicToCartesian([longitude, latitude, height]);
+  return new Vector3(point[0], point[1], point[2]);
+}
+
+// Add a point that doesn't allow the box dive under the Earth
+  // This point is actually a center of a face that could be a tangent to the Earth surface if max==0
+  points.push(convertCartToXYZ((W + E) / 2.0, (S + N) / 2.0, max));
+
+  // points should be an array of Vector3 (XYZ)
+  // Passing result===null throws an exception from makeOrientedBoundingBoxFromPoints
+  const obb: OrientedBoundingBox = makeOrientedBoundingBoxFromPoints(
+    points,
+    result !== null ? result : undefined
+  );
+
+  const box: number[] = [...obb.center, ...obb.halfAxes];
+
+  return box;
+}
+*/

package/src/converters/s2-to-region.ts

@@ -0,0 +1,30 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {getS2GeoBoundsFromCell} from '../s2-geometry/s2-to-boundary';
+
+export function getS2Region(s2cell: {face: number; ij: [number, number]; level: number}): number[] {
+  const corners = getS2GeoBoundsFromCell(s2cell);
+  const region = getRegionFromS2Corners(corners);
+  return region;
+}
+
+function getRegionFromS2Corners(corners: Float64Array): number[] {
+  const longitudes: number[] = [];
+  const latitudes: number[] = [];
+  for (let i = 0; i < corners.length; i += 2) {
+    longitudes.push(corners[i]);
+    latitudes.push(corners[i + 1]);
+  }
+  longitudes.sort((a, b) => a - b);
+  latitudes.sort((a, b) => a - b);
+
+  // Return the region in degrees
+  return [
+    longitudes[0],
+    latitudes[0],
+    longitudes[longitudes.length - 1],
+    latitudes[latitudes.length - 1]
+  ];
+}

package/src/dggs-decoder.ts

@@ -0,0 +1,71 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {type Bounds2D} from '@math.gl/types';
+
+/** Cell identifiers used by the lightweight decoder API. */
+export type DGGSCell = string | bigint;
+
+/**
+ * A deliberately small common API for decoding DGGS and DGGS-like cell tokens.
+ * Decoder objects satisfy this interface so visualization code can use them interchangeably.
+ */
+export type DGGSDecoder = {
+  /** The name of the DGGS */
+  name: string;
+
+  /** Whether cells have a 64-bit numeric representation. */
+  hasNumericRepresentation: boolean;
+
+  /** Conventional data column names that identify cells in this grid. */
+  cellColumnNames: readonly string[];
+
+  /** Convert a string token to a binary cell index. */
+  tokenToCell?: (token: string) => bigint;
+  /** Convert a cell to its string token. */
+  cellToToken?: (cell: DGGSCell) => string;
+  /** Return the center of the cell as `[longitude, latitude]`. */
+  cellToLngLat: (cell: DGGSCell) => [number, number];
+  /** Return the closed cell boundary as longitude/latitude pairs. */
+  cellToBoundary: (cell: DGGSCell) => [number, number][];
+
+  /** @returns the boundary of the cell, as a flat array */
+  cellToBoundaryFlat: (cell: DGGSCell) => number[];
+  /** @returns the longitude/latitude bounds of the cell */
+  cellToBounds: (cell: DGGSCell) => Bounds2D;
+};
+
+/** A cell column and the decoder selected for it. */
+export type DGGSCellColumn = {
+  columnName: string;
+  decoder: DGGSDecoder;
+};
+
+/** Require a string cell identifier for string-only grids. */
+export function getDGGSCellToken(cell: DGGSCell, gridName: string): string {
+  if (typeof cell !== 'string') {
+    throw new Error(`${gridName} cell identifiers must be strings`);
+  }
+  return cell;
+}
+
+/** Calculate longitude/latitude bounds from a cell boundary. */
+export function getDGGSCellBounds(boundary: [number, number][]): Bounds2D {
+  let west = Infinity;
+  let south = Infinity;
+  let east = -Infinity;
+  let north = -Infinity;
+
+  for (const [longitude, latitude] of boundary) {
+    west = Math.min(west, longitude);
+    south = Math.min(south, latitude);
+    east = Math.max(east, longitude);
+    north = Math.max(north, latitude);
+  }
+
+  return [
+    [west, south],
+    [east, north]
+  ];
+}

package/src/geohash-decoder.ts

@@ -0,0 +1,99 @@
+// 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';
+
+/** Decoder for the geohash dggs */
+export const GeohashDecoder = {
+  name: 'geohash',
+  hasNumericRepresentation: false,
+  cellColumnNames: ['geohash', 'geohashId', 'geohash_id'],
+  cellToLngLat: (cell: DGGSCell): [number, number] =>
+    getGeohashLngLat(getDGGSCellToken(cell, 'GeoHash')),
+  cellToBoundary: (cell: DGGSCell): [number, number][] =>
+    getGeohashBoundary(getDGGSCellToken(cell, 'GeoHash')),
+  cellToBoundaryFlat: (cell: DGGSCell): number[] =>
+    getGeohashBoundaryFlat(getDGGSCellToken(cell, 'GeoHash')),
+  cellToBounds: (cell: DGGSCell): Bounds2D => getGeohashBounds(getDGGSCellToken(cell, 'GeoHash'))
+} as const satisfies DGGSDecoder;
+
+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 [[w, s], [e, n]] = 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 [[w, s], [e, n]] = getGeohashBounds(geohash);
+  return [
+    [e, n],
+    [e, s],
+    [w, s],
+    [w, n],
+    [e, n]
+  ];
+}
+
+/** Return boundary polygon of geohash cell as flat array */
+function getGeohashBoundaryFlat(geohash: string): number[] {
+  const [[w, s], [e, n]] = 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 [
+    [minLon, minLat],
+    [maxLon, maxLat]
+  ];
+}

package/src/geohash.ts

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

package/src/h3-decoder.ts

@@ -0,0 +1,53 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {cellToBoundary, cellToLatLng} from 'h3-js';
+import {type Bounds2D} from '@math.gl/types';
+import {type DGGSCell, type DGGSDecoder, getDGGSCellBounds} from './dggs-decoder';
+
+/** Lightweight cell geometry decoder for the H3 hexagonal DGGS. */
+export const H3Decoder = {
+  name: 'h3',
+  hasNumericRepresentation: true,
+  cellColumnNames: [
+    'h3',
+    'h3Index',
+    'h3_index',
+    'h3Cell',
+    'h3_cell',
+    'h3CellId',
+    'h3_cell_id',
+    'hexagon'
+  ],
+  tokenToCell: (token: string): bigint => getBigIntFromHexToken(token),
+  cellToToken: (cell: DGGSCell): string => getH3Token(cell),
+  cellToLngLat: (cell: DGGSCell): [number, number] => getH3LngLat(cell),
+  cellToBoundary: (cell: DGGSCell): [number, number][] => getH3Boundary(cell),
+  cellToBoundaryFlat: (cell: DGGSCell): number[] => getH3Boundary(cell).flat(),
+  cellToBounds: (cell: DGGSCell): Bounds2D => getDGGSCellBounds(getH3Boundary(cell))
+} as const satisfies DGGSDecoder;
+
+function getH3Token(cell: DGGSCell): string {
+  return typeof cell === 'bigint' ? cell.toString(16) : removeHexPrefix(cell);
+}
+
+function getH3LngLat(cell: DGGSCell): [number, number] {
+  const [latitude, longitude] = cellToLatLng(getH3Token(cell));
+  return [longitude, latitude];
+}
+
+function getH3Boundary(cell: DGGSCell): [number, number][] {
+  return cellToBoundary(getH3Token(cell), true).map(([longitude, latitude]) => [
+    longitude,
+    latitude
+  ]);
+}
+
+function getBigIntFromHexToken(token: string): bigint {
+  return BigInt(`0x${removeHexPrefix(token)}`);
+}
+
+function removeHexPrefix(token: string): string {
+  return token.startsWith('0x') || token.startsWith('0X') ? token.slice(2) : token;
+}

package/src/h3.ts

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

package/src/index.ts

@@ -0,0 +1,61 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {type DGGSCell, type DGGSCellColumn, type DGGSDecoder} from './dggs-decoder';
+import {A5Decoder} from './a5-decoder';
+import {GeohashDecoder} from './geohash-decoder';
+import {H3Decoder} from './h3-decoder';
+import {PlusCodeDecoder} from './plus-code-decoder';
+import {QuadkeyDecoder} from './quadkey-decoder';
+import {S2Decoder} from './s2-decoder';
+
+export {type DGGSCell, type DGGSCellColumn, type DGGSDecoder};
+export {A5Decoder};
+export {GeohashDecoder};
+export {H3Decoder};
+export {PlusCodeDecoder};
+export {QuadkeyDecoder, quadkeyToWorldBounds} from './quadkey-decoder';
+export {S2Decoder};
+export {getS2ChildIndex} from './s2-geometry/s2-token';
+
+/** Lightweight decoders bundled with this module. */
+export const DGGS_DECODERS: readonly DGGSDecoder[] = [
+  A5Decoder,
+  GeohashDecoder,
+  H3Decoder,
+  PlusCodeDecoder,
+  QuadkeyDecoder,
+  S2Decoder
+];
+
+/**
+ * Finds a conventional DGGS cell column by name.
+ *
+ * Returns `null` when there is no match or when columns from more than one
+ * decoder match. Callers should ask the user to choose in the ambiguous case.
+ */
+export function findDGGSCellColumn(
+  columnNames: Iterable<string>,
+  decoders: readonly DGGSDecoder[] = DGGS_DECODERS
+): DGGSCellColumn | null {
+  const actualNames = new Map<string, string>();
+  for (const columnName of columnNames) {
+    actualNames.set(columnName.toLowerCase(), columnName);
+  }
+
+  let match: DGGSCellColumn | null = null;
+  for (const decoder of decoders) {
+    for (const candidate of decoder.cellColumnNames) {
+      const columnName = actualNames.get(candidate.toLowerCase());
+      if (!columnName) {
+        continue;
+      }
+      if (match && (match.decoder !== decoder || match.columnName !== columnName)) {
+        return null;
+      }
+      match = {columnName, decoder};
+    }
+  }
+  return match;
+}

package/src/open-location-code.d.ts

@@ -0,0 +1,19 @@
+declare module 'open-location-code' {
+  export type OpenLocationCodeArea = {
+    latitudeLo: number;
+    longitudeLo: number;
+    latitudeHi: number;
+    longitudeHi: number;
+    latitudeCenter: number;
+    longitudeCenter: number;
+    codeLength: number;
+  };
+
+  export class OpenLocationCode {
+    isFull(code: string): boolean;
+    decode(code: string): OpenLocationCodeArea;
+  }
+
+  const openLocationCodePackage: {OpenLocationCode: typeof OpenLocationCode};
+  export default openLocationCodePackage;
+}

package/src/plus-code-decoder.ts

@@ -0,0 +1,56 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import OpenLocationCodePackage, {type OpenLocationCodeArea} from 'open-location-code';
+import {type Bounds2D} from '@math.gl/types';
+import {type DGGSCell, type DGGSDecoder, getDGGSCellToken} from './dggs-decoder';
+
+const openLocationCode = new OpenLocationCodePackage.OpenLocationCode();
+
+/**
+ * Lightweight geometry decoder for full Google Plus Codes (Open Location Codes).
+ * Short codes require a reference location and are intentionally unsupported.
+ */
+export const PlusCodeDecoder = {
+  name: 'plus-code',
+  hasNumericRepresentation: false,
+  cellColumnNames: ['plusCode', 'plus_code', 'openLocationCode', 'open_location_code', 'olc'],
+  cellToLngLat: (cell: DGGSCell): [number, number] => getPlusCodeLngLat(cell),
+  cellToBoundary: (cell: DGGSCell): [number, number][] => getPlusCodeBoundary(decodePlusCode(cell)),
+  cellToBoundaryFlat: (cell: DGGSCell): number[] => {
+    const area = decodePlusCode(cell);
+    return getPlusCodeBoundary(area).flat();
+  },
+  cellToBounds: (cell: DGGSCell): Bounds2D => {
+    const area = decodePlusCode(cell);
+    return [
+      [area.longitudeLo, area.latitudeLo],
+      [area.longitudeHi, area.latitudeHi]
+    ];
+  }
+} as const satisfies DGGSDecoder;
+
+function getPlusCodeLngLat(cell: DGGSCell): [number, number] {
+  const area = decodePlusCode(cell);
+  return [area.longitudeCenter, area.latitudeCenter];
+}
+
+function decodePlusCode(cell: DGGSCell): OpenLocationCodeArea {
+  const code = getDGGSCellToken(cell, 'Plus Code');
+  if (!openLocationCode.isFull(code)) {
+    throw new Error(`Plus Code decoder requires a full code: ${code}`);
+  }
+  return openLocationCode.decode(code);
+}
+
+function getPlusCodeBoundary(area: OpenLocationCodeArea): [number, number][] {
+  const {longitudeLo: west, latitudeLo: south, longitudeHi: east, latitudeHi: north} = area;
+  return [
+    [east, north],
+    [east, south],
+    [west, south],
+    [west, north],
+    [east, north]
+  ];
+}

package/src/plus-code.ts

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