@math.gl/dggs 5.0.0-alpha.4 → 5.0.0-alpha.6

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

@@ -11,6 +11,8 @@ Permission to use, copy, modify, and/or distribute this software for any purpose
 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.
 */
 
+import {isS2IndexValid} from './s2-token';
+
 export type S2Cell = {
   face: number;
   ij: [number, number];
@@ -18,6 +20,9 @@ export type S2Cell = {
 };
 
 export function getS2Cell(s2Index: bigint): S2Cell {
+  if (!isS2IndexValid(s2Index)) {
+    throw new Error(`Invalid S2 index: ${s2Index}`);
+  }
   const key = toHilbertQuadkey(s2Index);
   const s2cell = fromHilbertQuadKey(key);
   return s2cell;
@@ -31,11 +36,46 @@ 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;
 
+type HilbertOrientation = 'a' | 'b' | 'c' | 'd';
+
+const HILBERT_MAP: Record<
+  HilbertOrientation,
+  readonly (readonly [position: number, orientation: HilbertOrientation])[]
+> = {
+  a: [
+    [0, 'd'],
+    [1, 'a'],
+    [3, 'b'],
+    [2, 'a']
+  ],
+  b: [
+    [2, 'b'],
+    [1, 'b'],
+    [3, 'a'],
+    [0, 'c']
+  ],
+  c: [
+    [2, 'c'],
+    [3, 'd'],
+    [1, 'c'],
+    [0, 'b']
+  ],
+  d: [
+    [0, 'a'],
+    [3, 'c'],
+    [1, 'd'],
+    [2, 'd']
+  ]
+};
+
 /*
   Original function taken from deck.gl doesn't support the case of (face <= 5)
   It's fixed here.
 */
 export function fromHilbertQuadKey(hilbertQuadkey: string): S2Cell {
+  if (!/^[0-5]\/[0-3]{0,30}$/.test(hilbertQuadkey)) {
+    throw new Error(`Invalid S2 Hilbert quadkey: ${hilbertQuadkey}`);
+  }
   const parts = hilbertQuadkey.split('/');
   const face = parseInt(parts[0], 10);
   const position = parts[1] || '';
@@ -75,6 +115,9 @@ export function fromHilbertQuadKey(hilbertQuadkey: string): S2Cell {
 }
 
 export function toHilbertQuadkey(id: bigint): string {
+  if (!isS2IndexValid(id)) {
+    throw new Error(`Invalid S2 index: ${id}`);
+  }
   let bin = id.toString(2);
 
   while (bin.length < FACE_BITS + POS_BITS) {
@@ -105,6 +148,86 @@ export function toHilbertQuadkey(id: bigint): string {
   return `${faceS}/${posS}`;
 }
 
+/**
+ * Converts face-local integer coordinates into an S2 cell index.
+ *
+ * @param s2Cell - Face, `(i, j)` coordinates, and level of an S2 cell.
+ * @returns The corresponding 64-bit S2 cell index.
+ */
+export function getS2IndexFromCell(s2Cell: S2Cell): bigint {
+  const {face, ij, level} = s2Cell;
+  if (!Number.isInteger(face) || face < 0 || face > 5) {
+    throw new Error(`Invalid S2 face: ${face}`);
+  }
+  if (!Number.isInteger(level) || level < 0 || level > MAX_LEVEL) {
+    throw new Error(`Invalid S2 level: ${level}`);
+  }
+  const maximumCoordinate = 2 ** level;
+  if (
+    !Number.isInteger(ij[0]) ||
+    !Number.isInteger(ij[1]) ||
+    ij[0] < 0 ||
+    ij[1] < 0 ||
+    ij[0] >= maximumCoordinate ||
+    ij[1] >= maximumCoordinate
+  ) {
+    throw new Error(`Invalid S2 IJ coordinates: ${ij[0]}, ${ij[1]}`);
+  }
+
+  const positions = getHilbertQuadList(ij[0], ij[1], level, face);
+  let s2Index = BigInt(face) << 61n;
+  for (let positionIndex = 0; positionIndex < positions.length; positionIndex++) {
+    const bitOffset = 59 - positionIndex * 2;
+    s2Index |= BigInt(positions[positionIndex]) << BigInt(bitOffset);
+  }
+  s2Index |= 1n << BigInt(60 - level * 2);
+  return s2Index;
+}
+
+/**
+ * Returns a spatially addressed descendant of an S2 cell.
+ *
+ * Unlike {@link getS2ChildIndex}, `x` and `y` address the descendant along increasing face-local
+ * `i` and `j` axes. This accounts for Hilbert orientation changes across faces and levels.
+ *
+ * @param rootIndex - Valid S2 cell index at the root of the relative grid.
+ * @param relativeLevel - Number of subdivision levels below the root.
+ * @param x - Descendant coordinate along the root cell's increasing `i` axis.
+ * @param y - Descendant coordinate along the root cell's increasing `j` axis.
+ * @returns The descendant S2 cell index.
+ */
+export function getS2DescendantIndex(
+  rootIndex: bigint,
+  relativeLevel: number,
+  x: number,
+  y: number
+): bigint {
+  const rootCell = getS2Cell(rootIndex);
+  if (
+    !Number.isInteger(relativeLevel) ||
+    relativeLevel < 0 ||
+    rootCell.level + relativeLevel > MAX_LEVEL
+  ) {
+    throw new Error(`Invalid S2 relative level: ${relativeLevel}`);
+  }
+  const divisionCount = 2 ** relativeLevel;
+  if (
+    !Number.isInteger(x) ||
+    !Number.isInteger(y) ||
+    x < 0 ||
+    y < 0 ||
+    x >= divisionCount ||
+    y >= divisionCount
+  ) {
+    throw new Error(`Invalid S2 descendant coordinates: ${x}, ${y}`);
+  }
+  return getS2IndexFromCell({
+    face: rootCell.face,
+    ij: [rootCell.ij[0] * divisionCount + x, rootCell.ij[1] * divisionCount + y],
+    level: rootCell.level + relativeLevel
+  });
+}
+
 export function IJToST(
   ij: [number, number],
   order: number,
@@ -164,3 +287,17 @@ function rotateAndFlipQuadrant(n: number, point: [number, number], rx: number, r
     point[1] = x;
   }
 }
+
+function getHilbertQuadList(x: number, y: number, level: number, face: number): number[] {
+  let orientation: HilbertOrientation = face % 2 === 1 ? 'd' : 'a';
+  const positions: number[] = [];
+  for (let bit = level - 1; bit >= 0; bit--) {
+    const mask = 1 << bit;
+    const quadrantX = (x & mask) !== 0 ? 1 : 0;
+    const quadrantY = (y & mask) !== 0 ? 1 : 0;
+    const [position, nextOrientation] = HILBERT_MAP[orientation][quadrantX * 2 + quadrantY];
+    positions.push(position);
+    orientation = nextOrientation;
+  }
+  return positions;
+}

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

@@ -5,7 +5,10 @@
 // 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;
+const MAXIMUM_TOKEN_LENGTH = 16;
+const MAXIMUM_S2_INDEX = (1n << 64n) - 1n;
+const VALID_LOWEST_ON_BITS = 0x1555555555555555n;
+const MAXIMUM_LEVEL = 30;
 
 // INDEX CALCULATIONS
 
@@ -16,10 +19,13 @@
  */
 export function getS2IndexFromToken(token: string): bigint {
   if (token === 'X') {
-    token = '';
+    return 0n;
+  }
+  if (!isS2TokenValid(token)) {
+    throw new Error(`Invalid S2 token: ${token}`);
   }
   // pad token with zeros to make the length 16
-  const paddedToken = token.padEnd(16, '0');
+  const paddedToken = token.padEnd(MAXIMUM_TOKEN_LENGTH, '0');
   return BigInt(`0x${paddedToken}`);
 }
 
@@ -31,6 +37,9 @@ export function getS2TokenFromIndex(cellId: bigint): string {
   if (cellId === 0n) {
     return 'X';
   }
+  if (!isS2IndexValid(cellId)) {
+    throw new Error(`Invalid S2 index: ${cellId}`);
+  }
   let numZeroDigits = countTrailingZeros(cellId);
 
   const remainder = numZeroDigits % 4;
@@ -44,7 +53,67 @@ export function getS2TokenFromIndex(cellId: bigint): string {
   return zeroString + hexString;
 }
 
+/**
+ * Returns whether a value is a valid non-empty 64-bit S2 cell index.
+ *
+ * @param s2Index - Candidate S2 cell index.
+ * @returns `true` when the face and level marker encode a valid S2 cell.
+ */
+export function isS2IndexValid(s2Index: unknown): s2Index is bigint {
+  if (typeof s2Index !== 'bigint' || s2Index <= 0n || s2Index > MAXIMUM_S2_INDEX) {
+    return false;
+  }
+  const face = s2Index >> 61n;
+  const lowestOnBit = s2Index & -s2Index;
+  return face < 6n && (lowestOnBit & VALID_LOWEST_ON_BITS) !== 0n;
+}
+
+/**
+ * Returns whether a string is a canonical token for a non-empty S2 cell.
+ *
+ * The empty-cell sentinel `X` is supported by the conversion functions but is not a valid cell.
+ *
+ * @param token - Candidate hexadecimal S2 token.
+ * @returns `true` when the token canonically encodes a valid S2 cell.
+ */
+export function isS2TokenValid(token: unknown): token is string {
+  if (typeof token !== 'string' || !/^[0-9a-fA-F]{1,16}$/.test(token) || token.endsWith('0')) {
+    return false;
+  }
+  const paddedToken = token.padEnd(MAXIMUM_TOKEN_LENGTH, '0');
+  return isS2IndexValid(BigInt(`0x${paddedToken}`));
+}
+
+/**
+ * Returns the subdivision level encoded by an S2 cell index.
+ *
+ * @param s2Index - Valid non-empty S2 cell index.
+ * @returns The S2 level in the range `[0, 30]`.
+ */
+export function getS2Level(s2Index: bigint): number {
+  if (!isS2IndexValid(s2Index)) {
+    throw new Error(`Invalid S2 index: ${s2Index}`);
+  }
+  return (60 - countTrailingZeros(s2Index)) / 2;
+}
+
+/**
+ * Returns one of the four Hilbert-ordered children of an S2 cell.
+ *
+ * @param s2Index - Valid S2 cell index below level 30.
+ * @param index - Hilbert child position in the range `[0, 3]`.
+ * @returns The child S2 cell index.
+ */
 export function getS2ChildIndex(s2Index: bigint, index: number): bigint {
+  if (!isS2IndexValid(s2Index)) {
+    throw new Error(`Invalid S2 index: ${s2Index}`);
+  }
+  if (!Number.isInteger(index) || index < 0 || index > 3) {
+    throw new Error(`Invalid S2 child index: ${index}`);
+  }
+  if (getS2Level(s2Index) === MAXIMUM_LEVEL) {
+    throw new Error('Cannot subdivide an S2 leaf cell');
+  }
   // Shift sentinel bit 2 positions to the right.
   const newLsb = lsb(s2Index) >> 2n;
   // Insert child index before the sentinel bit.
@@ -57,7 +126,7 @@ export function getS2ChildIndex(s2Index: bigint, index: number): bigint {
  * @private
  */
 function lsb(cellId: bigint): bigint {
-  return cellId & (cellId + 1n); // eslint-disable-line
+  return cellId & -cellId; // eslint-disable-line
 }
 
 function countTrailingZeros(n: bigint): number {

package/src/s2.ts

@@ -2,5 +2,14 @@
 // SPDX-License-Identifier: MIT
 // Copyright (c) vis.gl contributors
 
-export {S2Decoder} from './s2-decoder';
-export {getS2ChildIndex} from './s2-geometry/s2-token';
+export {S2Decoder, getS2Bounds, getS2LngLat, getS2BoundaryFlat} from './s2-decoder';
+export {
+  getS2ChildIndex,
+  getS2IndexFromToken,
+  getS2Level,
+  getS2TokenFromIndex,
+  isS2IndexValid,
+  isS2TokenValid
+} from './s2-geometry/s2-token';
+export {getS2DescendantIndex, getS2IndexFromCell} from './s2-geometry/s2-geometry';
+export type {S2Cell} from './s2-geometry/s2-geometry';