@math.gl/dggs 5.0.0-alpha.2 → 5.0.0-alpha.20

package/src/dggs-decoder.ts

@@ -1,8 +1,17 @@
 // math.gl
 // SPDX-License-Identifier: MIT
-// Copyright (c) vis.gl contributors
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
 
-import {type Bounds2D} from '@math.gl/types';
+import {type Bounds2D} from '@math.gl/core/types';
+import {unwrapDGGSBoundary} from './unwrap-dggs-boundary';
+
+/** Optional continuous-longitude geometry output for DGGS decoders. */
+export type DGGSBoundaryOptions = {
+  /** Unwrap ordinary antimeridian crossings. Defaults to false. */
+  unwrap?: boolean;
+  /** Place the first longitude near this value, in degrees. Used only with unwrap. */
+  referenceLongitude?: number;
+};
 
 /** Cell identifiers used by the lightweight decoder API. */
 export type DGGSCell = string | bigint;
@@ -28,12 +37,12 @@ export type DGGSDecoder = {
   /** 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][];
+  cellToBoundary: (cell: DGGSCell, options?: DGGSBoundaryOptions) => [number, number][];
 
   /** @returns the boundary of the cell, as a flat array */
-  cellToBoundaryFlat: (cell: DGGSCell) => number[];
+  cellToBoundaryFlat: (cell: DGGSCell, options?: DGGSBoundaryOptions) => number[];
   /** @returns the longitude/latitude bounds of the cell */
-  cellToBounds: (cell: DGGSCell) => Bounds2D;
+  cellToBounds: (cell: DGGSCell, options?: DGGSBoundaryOptions) => Bounds2D;
 };
 
 /** A cell column and the decoder selected for it. */
@@ -69,3 +78,31 @@ export function getDGGSCellBounds(boundary: [number, number][]): Bounds2D {
     [east, north]
   ];
 }
+
+/** @internal Apply the shared opt-in geometry policy to a decoder. */
+export function withDGGSBoundaryOptions<T extends DGGSDecoder>(
+  decoder: T
+): Omit<T, 'cellToBoundary' | 'cellToBoundaryFlat' | 'cellToBounds'> &
+  Pick<DGGSDecoder, 'cellToBoundary' | 'cellToBoundaryFlat' | 'cellToBounds'> {
+  const cellToBoundary = (cell: DGGSCell, options?: DGGSBoundaryOptions): [number, number][] => {
+    const boundary = decoder.cellToBoundary(cell);
+    return options?.unwrap ? unwrapDGGSBoundary(boundary, options.referenceLongitude) : boundary;
+  };
+  return {
+    ...decoder,
+    cellToBoundary,
+    cellToBoundaryFlat: (cell, options) =>
+      options?.unwrap ? cellToBoundary(cell, options).flat() : decoder.cellToBoundaryFlat(cell),
+    cellToBounds: (cell, options) => {
+      const bounds = decoder.cellToBounds(cell);
+      if (!options?.unwrap || bounds[1][0] - bounds[0][0] >= 360) {
+        return bounds;
+      }
+      const unwrapped = getDGGSCellBounds(cellToBoundary(cell, options));
+      // Latitude extrema may occur inside the cell or along curved edges.
+      unwrapped[0][1] = bounds[0][1];
+      unwrapped[1][1] = bounds[1][1];
+      return unwrapped;
+    }
+  };
+}

package/src/expressions.ts

@@ -0,0 +1,37 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+/* eslint-disable @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-return */
+
+import {GeohashDecoder} from './geohash-decoder';
+import {QuadkeyDecoder, quadkeyToWorldBounds} from './quadkey-decoder';
+import {S2Decoder} from './s2-decoder';
+import {getS2ChildIndex} from './s2-geometry/s2-token';
+type ExpressionFunctionLibrary = Record<string, (...args: any[]) => any>;
+
+export const GEOHASH_FUNCTION_LIBRARY: ExpressionFunctionLibrary = {
+  getGeohashBoundary: GeohashDecoder.cellToBoundary,
+  getGeohashBoundaryFlat: GeohashDecoder.cellToBoundaryFlat,
+  getGeohashBounds: GeohashDecoder.cellToBounds,
+  getGeohashLngLat: GeohashDecoder.cellToLngLat
+};
+
+export const QUADKEY_FUNCTION_LIBRARY: ExpressionFunctionLibrary = {
+  getQuadkeyBoundary: QuadkeyDecoder.cellToBoundary,
+  getQuadkeyBoundaryFlat: QuadkeyDecoder.cellToBoundaryFlat,
+  getQuadkeyLngLat: QuadkeyDecoder.cellToLngLat,
+  quadkeyToWorldBounds
+};
+
+export const S2_FUNCTION_LIBRARY: ExpressionFunctionLibrary = {
+  getS2BoundaryFlat: S2Decoder.cellToBoundaryFlat,
+  getS2ChildIndex,
+  getS2IndexFromToken: S2Decoder.tokenToCell,
+  getS2TokenFromIndex: S2Decoder.cellToToken
+};
+
+export const DGGS_FUNCTION_LIBRARY: ExpressionFunctionLibrary = {
+  ...GEOHASH_FUNCTION_LIBRARY,
+  ...QUADKEY_FUNCTION_LIBRARY,
+  ...S2_FUNCTION_LIBRARY
+};

package/src/geohash-decoder.ts

@@ -1,12 +1,17 @@
 // math.gl
 // SPDX-License-Identifier: MIT
-// Copyright (c) vis.gl contributors
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
 
-import {type Bounds2D} from '@math.gl/types';
-import {type DGGSCell, type DGGSDecoder, getDGGSCellToken} from './dggs-decoder';
+import {type Bounds2D} from '@math.gl/core/types';
+import {
+  withDGGSBoundaryOptions,
+  type DGGSCell,
+  type DGGSDecoder,
+  getDGGSCellToken
+} from './dggs-decoder';
 
 /** Decoder for the geohash dggs */
-export const GeohashDecoder = {
+export const GeohashDecoder = withDGGSBoundaryOptions({
   name: 'geohash',
   hasNumericRepresentation: false,
   cellColumnNames: ['geohash', 'geohashId', 'geohash_id'],
@@ -17,7 +22,7 @@ export const GeohashDecoder = {
   cellToBoundaryFlat: (cell: DGGSCell): number[] =>
     getGeohashBoundaryFlat(getDGGSCellToken(cell, 'GeoHash')),
   cellToBounds: (cell: DGGSCell): Bounds2D => getGeohashBounds(getDGGSCellToken(cell, 'GeoHash'))
-} as const satisfies DGGSDecoder;
+} as const satisfies DGGSDecoder);
 
 const BASE32_CODES = '0123456789bcdefghjkmnpqrstuvwxyz';
 const BASE32_CODES_DICT: Record<string, number> = {};

package/src/geohash.ts

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

package/src/h3-decoder.ts

@@ -1,13 +1,18 @@
 // math.gl
 // SPDX-License-Identifier: MIT
-// Copyright (c) vis.gl contributors
+// SPDX-FileCopyrightText: 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';
+import {type Bounds2D} from '@math.gl/core/types';
+import {
+  withDGGSBoundaryOptions,
+  type DGGSCell,
+  type DGGSDecoder,
+  getDGGSCellBounds
+} from './dggs-decoder';
 
 /** Lightweight cell geometry decoder for the H3 hexagonal DGGS. */
-export const H3Decoder = {
+export const H3Decoder = withDGGSBoundaryOptions({
   name: 'h3',
   hasNumericRepresentation: true,
   cellColumnNames: [
@@ -26,7 +31,7 @@ export const H3Decoder = {
   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;
+} as const satisfies DGGSDecoder);
 
 function getH3Token(cell: DGGSCell): string {
   return typeof cell === 'bigint' ? cell.toString(16) : removeHexPrefix(cell);

package/src/h3.ts

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

package/src/index.ts

@@ -1,6 +1,6 @@
 // math.gl
 // SPDX-License-Identifier: MIT
-// Copyright (c) vis.gl contributors
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
 
 import {type DGGSCell, type DGGSCellColumn, type DGGSDecoder} from './dggs-decoder';
 import {A5Decoder} from './a5-decoder';
@@ -10,14 +10,25 @@ import {PlusCodeDecoder} from './plus-code-decoder';
 import {QuadkeyDecoder} from './quadkey-decoder';
 import {S2Decoder} from './s2-decoder';
 
+export {type DGGSBoundaryOptions} from './dggs-decoder';
 export {type DGGSCell, type DGGSCellColumn, type DGGSDecoder};
+export {unwrapDGGSBoundary} from './unwrap-dggs-boundary';
 export {A5Decoder};
 export {GeohashDecoder};
 export {H3Decoder};
 export {PlusCodeDecoder};
 export {QuadkeyDecoder, quadkeyToWorldBounds} from './quadkey-decoder';
-export {S2Decoder};
-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';
 
 /** Lightweight decoders bundled with this module. */
 export const DGGS_DECODERS: readonly DGGSDecoder[] = [

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

@@ -1,3 +1,6 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
 declare module 'open-location-code' {
   export type OpenLocationCodeArea = {
     latitudeLo: number;

package/src/plus-code-decoder.ts

@@ -1,10 +1,15 @@
 // math.gl
 // SPDX-License-Identifier: MIT
-// Copyright (c) vis.gl contributors
+// SPDX-FileCopyrightText: 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';
+import {type Bounds2D} from '@math.gl/core/types';
+import {
+  withDGGSBoundaryOptions,
+  type DGGSCell,
+  type DGGSDecoder,
+  getDGGSCellToken
+} from './dggs-decoder';
 
 const openLocationCode = new OpenLocationCodePackage.OpenLocationCode();
 
@@ -12,7 +17,7 @@ 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 = {
+export const PlusCodeDecoder = withDGGSBoundaryOptions({
   name: 'plus-code',
   hasNumericRepresentation: false,
   cellColumnNames: ['plusCode', 'plus_code', 'openLocationCode', 'open_location_code', 'olc'],
@@ -29,7 +34,7 @@ export const PlusCodeDecoder = {
       [area.longitudeHi, area.latitudeHi]
     ];
   }
-} as const satisfies DGGSDecoder;
+} as const satisfies DGGSDecoder);
 
 function getPlusCodeLngLat(cell: DGGSCell): [number, number] {
   const area = decodePlusCode(cell);

package/src/plus-code.ts

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

package/src/quadkey-decoder.ts

@@ -1,14 +1,19 @@
 // math.gl
 // SPDX-License-Identifier: MIT
-// Copyright (c) vis.gl contributors
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
 
-import {type Bounds2D} from '@math.gl/types';
-import {type DGGSCell, type DGGSDecoder, getDGGSCellToken} from './dggs-decoder';
+import {type Bounds2D} from '@math.gl/core/types';
+import {
+  withDGGSBoundaryOptions,
+  type DGGSCell,
+  type DGGSDecoder,
+  getDGGSCellToken
+} from './dggs-decoder';
 
 const TILE_SIZE = 512;
 
 /** Decoder for the quadkey DGGS */
-export const QuadkeyDecoder = {
+export const QuadkeyDecoder = withDGGSBoundaryOptions({
   name: 'quadkey',
   hasNumericRepresentation: false,
   cellColumnNames: ['quadkey', 'quadkeyId', 'quadkey_id'],
@@ -19,7 +24,7 @@ export const QuadkeyDecoder = {
   cellToBoundaryFlat: (cell: DGGSCell): number[] =>
     getQuadkeyBoundaryFlat(getDGGSCellToken(cell, 'Quadkey')),
   cellToBounds: (cell: DGGSCell): Bounds2D => getQuadkeyBounds(getDGGSCellToken(cell, 'Quadkey'))
-} as const satisfies DGGSDecoder;
+} as const satisfies DGGSDecoder);
 
 function getQuadkeyLngLat(quadkey: string): [number, number] {
   const [topLeft, bottomRight] = quadkeyToWorldBounds(quadkey);

package/src/quadkey.ts

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

package/src/s2-decoder.ts

@@ -1,27 +1,26 @@
 // math.gl
 // SPDX-License-Identifier: MIT
-// Copyright (c) vis.gl contributors
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
 
-import {type Bounds2D} from '@math.gl/types';
-import {type DGGSCell, type DGGSDecoder} from './dggs-decoder';
+import {type Bounds2D} from '@math.gl/core/types';
+import {withDGGSBoundaryOptions, 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 = {
+export const S2Decoder = withDGGSBoundaryOptions({
   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),
+  cellToToken: (cell: DGGSCell): string => getS2TokenFromIndex(getS2CellIndex(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;
+} as const satisfies DGGSDecoder);
 
 /**
  * Retrieve S2 geometry center
@@ -60,28 +59,99 @@ function getS2Boundary(cell: DGGSCell): [number, number][] {
   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;
+/**
+ * Returns conservative longitude/latitude bounds for an S2 cell.
+ *
+ * Longitudes are unwrapped so `east >= west`; either endpoint may lie outside `[-180, 180]` for
+ * antimeridian cells. The two level-zero polar faces span a complete 360-degree longitude range.
+ *
+ * @param cell - S2 token or 64-bit cell index.
+ * @returns Bounds in `[[west, south], [east, north]]` order and degrees.
+ */
+export function getS2Bounds(cell: DGGSCell): Bounds2D {
+  const s2Cell = getS2Cell(getS2CellIndex(cell));
+  if (s2Cell.level === 0) {
+    return getS2RootBounds(s2Cell.face);
+  }
 
-  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;
+  // For non-root S2 cells, latitude and longitude extrema occur at vertices. Root cells require
+  // the special cases above because their curved edges or interiors contain the extrema.
+  // https://github.com/google/s2geometry/blob/master/src/s2/s2cell.cc
+  const offsets: readonly [number, number][] = [
+    [0, 0],
+    [0, 1],
+    [1, 1],
+    [1, 0]
+  ];
+  let west = Infinity;
+  let south = Infinity;
+  let east = -Infinity;
+  let north = -Infinity;
+  let previousLongitude: number | undefined;
+  for (const offset of offsets) {
+    const st = IJToST(s2Cell.ij, s2Cell.level, offset);
+    const uv = STToUV(st);
+    const [x, y, z] = FaceUVToXYZ(s2Cell.face, uv);
+    let [longitude, latitude] = XYZToLngLat([x, y, z]);
+    if (x === 0 && y === 0 && previousLongitude !== undefined) {
+      longitude = previousLongitude;
+    }
+    if (previousLongitude !== undefined) {
+      const longitudeDelta = longitude - previousLongitude;
+      longitude += longitudeDelta > 180 ? -360 : longitudeDelta < -180 ? 360 : 0;
+    }
+    previousLongitude = longitude;
+    west = Math.min(west, longitude);
+    south = Math.min(south, latitude);
+    east = Math.max(east, longitude);
+    north = Math.max(north, latitude);
   }
 
+  const angularEpsilon = (2 * Number.EPSILON * 180) / Math.PI;
   return [
-    [xmin, ymin],
-    [xmax, ymax]
+    [west - angularEpsilon, Math.max(-90, south - angularEpsilon)],
+    [east + angularEpsilon, Math.min(90, north + angularEpsilon)]
   ];
 }
 
 function getS2CellIndex(cell: DGGSCell): bigint {
   return typeof cell === 'bigint' ? cell : getS2IndexFromToken(cell);
 }
+
+function getS2RootBounds(face: number): Bounds2D {
+  const polarLatitude = (Math.asin(Math.sqrt(1 / 3)) * 180) / Math.PI;
+  switch (face) {
+    case 0:
+      return [
+        [-45, -45],
+        [45, 45]
+      ];
+    case 1:
+      return [
+        [45, -45],
+        [135, 45]
+      ];
+    case 2:
+      return [
+        [-180, polarLatitude],
+        [180, 90]
+      ];
+    case 3:
+      return [
+        [135, -45],
+        [225, 45]
+      ];
+    case 4:
+      return [
+        [-135, -45],
+        [-45, 45]
+      ];
+    case 5:
+      return [
+        [-180, -90],
+        [180, -polarLatitude]
+      ];
+    default:
+      throw new Error(`Invalid S2 face: ${face}`);
+  }
+}

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

@@ -1,6 +1,9 @@
 // math.gl
-// SPDX-License-Identifier: MIT and ISC
-// Copyright (c) vis.gl contributors
+// SPDX-License-Identifier: MIT AND ISC
+// SPDX-FileCopyrightText: Copyright (c) 2012-2016, Jon Atkins <github@jonatkins.com>
+// SPDX-FileCopyrightText: Copyright (c) 2016, AJ ONeal <aj@daplie.com>
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+// SPDX-FileComment: Adapted from s2-geometry. Original ISC notice retained below.
 
 // math.gl, MIT license
 /*
@@ -11,6 +14,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 +23,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 +39,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 +118,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 +151,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 +290,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-to-boundary.ts

@@ -1,6 +1,6 @@
 // math.gl
 // SPDX-License-Identifier: MIT
-// Copyright (c) vis.gl contributors
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
 
 import {IJToST, STToUV, FaceUVToXYZ, XYZToLngLat, getS2Cell} from './s2-geometry';