@loaders.gl/3d-tiles 3.3.2 → 3.4.0-alpha.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@loaders.gl/3d-tiles",
-  "version": "3.3.2",
+  "version": "3.4.0-alpha.2",
   "description": "3D Tiles, an open standard for streaming massive heterogeneous 3D geospatial datasets.",
   "license": "MIT",
   "publishConfig": {
@@ -34,16 +34,17 @@
     "build-bundle": "esbuild src/bundle.ts --bundle --outfile=dist/dist.min.js"
   },
   "dependencies": {
-    "@loaders.gl/draco": "3.3.2",
-    "@loaders.gl/gltf": "3.3.2",
-    "@loaders.gl/loader-utils": "3.3.2",
-    "@loaders.gl/math": "3.3.2",
-    "@loaders.gl/tiles": "3.3.2",
+    "@loaders.gl/draco": "3.4.0-alpha.2",
+    "@loaders.gl/gltf": "3.4.0-alpha.2",
+    "@loaders.gl/loader-utils": "3.4.0-alpha.2",
+    "@loaders.gl/math": "3.4.0-alpha.2",
+    "@loaders.gl/tiles": "3.4.0-alpha.2",
     "@math.gl/core": "^3.5.1",
-    "@math.gl/geospatial": "^3.5.1"
+    "@math.gl/geospatial": "^3.5.1",
+    "long": "^5.2.1"
   },
   "peerDependencies": {
     "@loaders.gl/core": "^3.2.0"
   },
-  "gitHead": "a37b0af509ca05468aec6e5667d6a427b9c15d29"
+  "gitHead": "f1c00c124d8d0c41a138ff40afb0d1a00711bf2e"
 }

package/src/cesium-ion-loader.ts

@@ -33,6 +33,7 @@ export const CesiumIonLoader: LoaderWithParser = {
   },
   options: {
     'cesium-ion': {
+      // @ts-expect-error
       ...Tiles3DLoader.options['3d-tiles'],
       accessToken: null
     }

package/src/lib/parsers/helpers/parse-3d-implicit-tiles.ts

@@ -2,6 +2,11 @@ import type {Availability, BoundingVolume, Subtree} from '../../../types';
 import {Tile3DSubtreeLoader} from '../../../tile-3d-subtree-loader';
 import {load} from '@loaders.gl/core';
 
+import {getS2CellIdFromToken, getS2ChildCellId, getS2TokenFromCellId} from '../../utils/s2/index';
+import type {S2VolumeInfo} from '../../utils/obb/s2-corners-to-obb';
+import {convertS2BoundingVolumetoOBB} from '../../utils/obb/s2-corners-to-obb';
+import Long from 'long';
+
 const QUADTREE_DEVISION_COUNT = 4;
 const OCTREE_DEVISION_COUNT = 8;
 
@@ -10,6 +15,59 @@ const SUBDIVISION_COUNT_MAP = {
   OCTREE: OCTREE_DEVISION_COUNT
 };
 
+/**
+ *  S2VolumeBox is an extention of BoundingVolume of type "box"
+ */
+export type S2VolumeBox = {
+  /** BoundingVolume of type "box" has the "box" field. S2VolumeBox contains it as well. */
+  box: number[];
+  /** s2VolumeInfo provides additional info about the box - specifically the token, min and max height */
+  s2VolumeInfo: S2VolumeInfo;
+};
+
+function getChildS2VolumeBox(
+  s2VolumeBox: S2VolumeBox | undefined,
+  index: number,
+  subdivisionScheme: string
+): S2VolumeBox | undefined {
+  if (s2VolumeBox?.box) {
+    // Check if the BoundingVolume is of type "box"
+    const cellId: Long = getS2CellIdFromToken(s2VolumeBox.s2VolumeInfo.token);
+    const childCellId = getS2ChildCellId(cellId, index);
+    const childToken = getS2TokenFromCellId(childCellId);
+
+    // Clone object. Note, s2VolumeInfo is a plain object that doesn't contain any nested object.
+    // So, we can use the Spread Operator to make a shallow copy of the object.
+    const s2ChildVolumeInfo: S2VolumeInfo = {...s2VolumeBox.s2VolumeInfo};
+    s2ChildVolumeInfo.token = childToken; // replace the token with the child's one
+
+    // In case of QUADTREE the sizeZ should NOT be changed!
+    // https://portal.ogc.org/files/102132
+    // A quadtree divides space only on the x and y dimensions.
+    // It divides each tile into 4 smaller tiles where the x and y dimensions are halved.
+    // The quadtree z minimum and maximum remain unchanged.
+    switch (subdivisionScheme) {
+      case 'OCTREE':
+        const s2VolumeInfo: S2VolumeInfo = s2VolumeBox.s2VolumeInfo;
+        const delta = s2VolumeInfo.maximumHeight - s2VolumeInfo.minimumHeight;
+        const sizeZ: number = delta / 2.0; // It's a next level (a child)
+        const midZ: number = s2VolumeInfo.minimumHeight + delta / 2.0;
+        s2VolumeInfo.minimumHeight = midZ - sizeZ;
+        s2VolumeInfo.maximumHeight = midZ + sizeZ;
+        break;
+      default:
+        break;
+    }
+    const box = convertS2BoundingVolumetoOBB(s2ChildVolumeInfo);
+    const childS2VolumeBox: S2VolumeBox = {
+      box,
+      s2VolumeInfo: s2ChildVolumeInfo
+    };
+    return childS2VolumeBox;
+  }
+  return undefined;
+}
+
 /**
  * Recursively parse implicit tiles tree
  * Spec - https://github.com/CesiumGS/3d-tiles/tree/main/extensions/3DTILES_implicit_tiling
@@ -30,6 +88,7 @@ export async function parseImplicitTiles(params: {
   childIndex?: number;
   level?: number;
   globalData?: {level: number; mortonIndex: number; x: number; y: number; z: number};
+  s2VolumeBox?: S2VolumeBox;
 }) {
   const {
     options,
@@ -46,7 +105,8 @@ export async function parseImplicitTiles(params: {
       x: 0,
       y: 0,
       z: 0
-    }
+    },
+    s2VolumeBox
   } = params;
   let {subtree, level = 0} = params;
   const {
@@ -129,19 +189,33 @@ export async function parseImplicitTiles(params: {
   const pData = {mortonIndex: childTileMortonIndex, x: childTileX, y: childTileY, z: childTileZ};
 
   for (let index = 0; index < childrenPerTile; index++) {
-    const currentTile = await parseImplicitTiles({
+    const childS2VolumeBox: S2VolumeBox | undefined = getChildS2VolumeBox(
+      s2VolumeBox,
+      index,
+      subdivisionScheme
+    );
+
+    // Recursive calling...
+    const childTileParsed = await parseImplicitTiles({
       subtree,
       options,
       parentData: pData,
       childIndex: index,
       level: childTileLevel,
-      globalData
+      globalData,
+      s2VolumeBox: childS2VolumeBox
     });
 
-    if (currentTile.contentUrl || currentTile.children.length) {
+    if (childTileParsed.contentUrl || childTileParsed.children.length) {
       const globalLevel = lev + 1;
       const childCoordinates = {childTileX, childTileY, childTileZ};
-      const formattedTile = formatTileData(currentTile, globalLevel, childCoordinates, options);
+      const formattedTile = formatTileData(
+        childTileParsed,
+        globalLevel,
+        childCoordinates,
+        options,
+        s2VolumeBox
+      );
       // @ts-ignore
       tile.children.push(formattedTile);
     }
@@ -174,7 +248,8 @@ function formatTileData(
   tile,
   level: number,
   childCoordinates: {childTileX: number; childTileY: number; childTileZ: number},
-  options: any
+  options: any,
+  s2VolumeBox?: S2VolumeBox
 ) {
   const {
     basePath,
@@ -187,9 +262,14 @@ function formatTileData(
   } = options;
   const uri = tile.contentUrl && tile.contentUrl.replace(`${basePath}/`, '');
   const lodMetricValue = rootLodMetricValue / 2 ** level;
-  const boundingVolume = calculateBoundingVolumeForChildTile(
+
+  const boundingVolume: BoundingVolume = s2VolumeBox?.box
+    ? {box: s2VolumeBox.box}
+    : rootBoundingVolume;
+
+  const boundingVolumeForChildTile = calculateBoundingVolumeForChildTile(
     level,
-    rootBoundingVolume,
+    boundingVolume,
     childCoordinates
   );
 
@@ -204,7 +284,7 @@ function formatTileData(
     lodMetricValue,
     geometricError: lodMetricValue,
     transform: tile.transform,
-    boundingVolume
+    boundingVolume: boundingVolumeForChildTile
   };
 }
 
@@ -219,7 +299,7 @@ function calculateBoundingVolumeForChildTile(
   level: number,
   rootBoundingVolume: BoundingVolume,
   childCoordinates: {childTileX: number; childTileY: number; childTileZ: number}
-): BoundingVolume | null {
+): BoundingVolume {
   if (rootBoundingVolume.region) {
     const {childTileX, childTileY, childTileZ} = childCoordinates;
     const [west, south, east, north, minimumHeight, maximumHeight] = rootBoundingVolume.region;
@@ -227,6 +307,13 @@ function calculateBoundingVolumeForChildTile(
 
     const sizeX = (east - west) / boundingVolumesCount;
     const sizeY = (north - south) / boundingVolumesCount;
+
+    // TODO : Why is the subdivisionScheme not being checked here?
+
+    // In case of QUADTREE the sizeZ should NOT be changed!
+    // https://portal.ogc.org/files/102132
+    // A quadtree divides space only on the x and y dimensions. It divides each tile into 4 smaller tiles where the x and y dimensions are halved. The quadtree z minimum and maximum remain unchanged.
+
     const sizeZ = (maximumHeight - minimumHeight) / boundingVolumesCount;
 
     const [childWest, childEast] = [west + sizeX * childTileX, west + sizeX * (childTileX + 1)];
@@ -241,9 +328,11 @@ function calculateBoundingVolumeForChildTile(
     };
   }
 
-  // eslint-disable-next-line no-console
-  console.warn('Unsupported bounding volume type: ', rootBoundingVolume);
-  return null;
+  if (rootBoundingVolume.box) {
+    return rootBoundingVolume;
+  }
+
+  throw new Error(`Unsupported bounding volume type ${rootBoundingVolume}`);
 }
 
 /**

package/src/lib/parsers/parse-3d-tile-header.ts

@@ -3,7 +3,10 @@ import {Tile3DSubtreeLoader} from '../../tile-3d-subtree-loader';
 import {load} from '@loaders.gl/core';
 import {Tileset3D, LOD_METRIC_TYPE, TILE_REFINEMENT, TILE_TYPE, Tile3D} from '@loaders.gl/tiles';
 import {ImplicitTilingExtension, Subtree} from '../../types';
+import type {S2VolumeBox} from './helpers/parse-3d-implicit-tiles';
 import {parseImplicitTiles, replaceContentUrlTemplate} from './helpers/parse-3d-implicit-tiles';
+import type {S2VolumeInfo} from '../utils/obb/s2-corners-to-obb';
+import {convertS2BoundingVolumetoOBB} from '../utils/obb/s2-corners-to-obb';
 
 function getTileType(tile) {
   if (!tile.contentUrl) {
@@ -141,6 +144,15 @@ export async function normalizeImplicitTileHeaders(
   const refine = tileset?.root?.refine;
   // @ts-ignore
   const rootLodMetricValue = tile.geometricError;
+
+  // Replace tile.boundingVolume with the the bounding volume specified by the extensions['3DTILES_bounding_volume_S2']
+  const s2VolumeInfo: S2VolumeInfo = tile.boundingVolume.extensions?.['3DTILES_bounding_volume_S2'];
+  if (s2VolumeInfo) {
+    const box = convertS2BoundingVolumetoOBB(s2VolumeInfo);
+    const s2VolumeBox: S2VolumeBox = {box, s2VolumeInfo};
+    tile.boundingVolume = s2VolumeBox;
+  }
+
   const rootBoundingVolume = tile.boundingVolume;
 
   const implicitOptions = {
@@ -177,7 +189,11 @@ export async function normalizeImplicitTileData(tile, rootSubtree: Subtree, opti
   tile.lodMetricValue = tile.geometricError;
   tile.transformMatrix = tile.transform;
 
-  const {children, contentUrl} = await parseImplicitTiles({subtree: rootSubtree, options});
+  const {children, contentUrl} = await parseImplicitTiles({
+    subtree: rootSubtree,
+    options,
+    s2VolumeBox: tile
+  });
 
   if (contentUrl) {
     tile.contentUrl = contentUrl;

package/src/lib/utils/obb/s2-corners-to-obb.ts

@@ -0,0 +1,51 @@
+import {Vector3} from '@math.gl/core';
+import {OrientedBoundingBox, makeOrientedBoundingBoxFromPoints} from '@math.gl/culling';
+
+import type {S2HeightInfo} from '../../utils/s2/index';
+import {getS2OrientedBoundingBoxCornerPoints} from '../../utils/s2/index';
+
+import {getS2LngLat} from '../../utils/s2/index';
+import {Ellipsoid} from '@math.gl/geospatial';
+
+export type S2VolumeInfo = {
+  /** S2 key or token */
+  token: string;
+  /** minimum height in meters */
+  minimumHeight: number;
+  /** maximum height in meters */
+  maximumHeight: number;
+};
+
+/**
+ * Converts S2VolumeInfo to OrientedBoundingBox
+ * @param {S2VolumeInfo} s2VolumeInfo - s2 volume to convert
+ * @returns Oriented Bounding Box of type Box
+ */
+export function convertS2BoundingVolumetoOBB(s2VolumeInfo: S2VolumeInfo): number[] {
+  const token: string = s2VolumeInfo.token;
+  const heightInfo: S2HeightInfo = {
+    minimumHeight: s2VolumeInfo.minimumHeight,
+    maximumHeight: s2VolumeInfo.maximumHeight
+  };
+
+  const corners: Vector3[] = getS2OrientedBoundingBoxCornerPoints(token, heightInfo);
+
+  // Add a point that doesn't allow the box dive under the Earth
+
+  const center = getS2LngLat(token);
+  const centerLng: number = center[0];
+  const centerLat: number = center[1];
+  const point = Ellipsoid.WGS84.cartographicToCartesian([
+    centerLng,
+    centerLat,
+    heightInfo.maximumHeight
+  ]);
+  const centerPointAdditional = new Vector3(point[0], point[1], point[2]);
+  corners.push(centerPointAdditional);
+
+  // corners should be an array of Vector3 (XYZ)
+  const obb: OrientedBoundingBox = makeOrientedBoundingBoxFromPoints(corners);
+  const box: number[] = [...obb.center, ...obb.halfAxes];
+
+  return box;
+}

package/src/lib/utils/s2/converters/s2-to-boundary.ts

@@ -0,0 +1,67 @@
+import type {S2Cell} from '../s2geometry/s2-geometry';
+import {IJToST, STToUV, FaceUVToXYZ, XYZToLngLat} from '../s2geometry/s2-geometry';
+
+const MAX_RESOLUTION = 100;
+
+/**
+ * Get a polygon with corner coordinates for an S2 cell
+ * @param s2cell {S2Cell} S2 cell
+ * @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
+ */
+// eslint-disable-next-line max-statements
+export function getS2BoundaryFlatFromS2Cell(s2cell: S2Cell): Float64Array {
+  const {face, ij, level} = s2cell;
+  const offsets = [
+    [0, 0],
+    [0, 1],
+    [1, 1],
+    [1, 0],
+    [0, 0]
+  ];
+
+  // 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
+  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/lib/utils/s2/converters/s2-to-obb-points.ts

@@ -0,0 +1,46 @@
+import {getS2Cell} from '../s2geometry/s2-cell-utils';
+import {getS2Region} from './s2-to-region';
+import {Vector3} from '@math.gl/core';
+
+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 tokenOrKey {string} A string that is the cell's hex token or the Hilbert quad key (containing /)
+ * @param heightInfo {S2HeightInfo} min and max height of the box
+ * @returns corner points of the oriented bounding box
+ */
+export function getS2OrientedBoundingBoxCornerPoints(
+  tokenOrKey: string, // This can be an S2 key or token
+  heightInfo?: S2HeightInfo
+): Vector3[] {
+  const min: number = heightInfo?.minimumHeight || 0;
+  const max: number = heightInfo?.maximumHeight || 0;
+
+  const s2cell = getS2Cell(tokenOrKey);
+  const region = getS2Region(s2cell);
+
+  // region lng/lat are in degrees
+  const W = region.west;
+  const S = region.south;
+  const E = region.east;
+  const N = region.north;
+
+  const points: Vector3[] = [];
+
+  points.push(new Vector3(W, N, min));
+  points.push(new Vector3(E, N, min));
+  points.push(new Vector3(E, S, min));
+  points.push(new Vector3(W, S, min));
+
+  points.push(new Vector3(W, N, max));
+  points.push(new Vector3(E, N, max));
+  points.push(new Vector3(E, S, max));
+  points.push(new Vector3(W, S, max));
+
+  return points;
+}

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

@@ -0,0 +1,69 @@
+import type {S2Cell} from '../s2geometry/s2-geometry';
+import {getS2BoundaryFlatFromS2Cell} from './s2-to-boundary';
+import {getS2Cell} from '../s2geometry/s2-cell-utils';
+
+/**
+ * Converts S2 cell to the 2D region
+ * @param s2cell {S2Cell} S2 cell to convert to 2D region
+ * @returns 2D region as an object containing: west, north, east, south in degrees
+ */
+export function getS2Region(s2cell: S2Cell): {
+  west: number;
+  east: number;
+  north: number;
+  south: number;
+} {
+  let region;
+  if (s2cell.face === 2 || s2cell.face === 5) {
+    //    let corners: Float64Array;
+    let corners: any = null;
+    let len = 0;
+    for (let i = 0; i < 4; i++) {
+      const key = `${s2cell.face}/${i}`;
+      const cell = getS2Cell(key);
+      const corns: Float64Array = getS2BoundaryFlatFromS2Cell(cell);
+      if (typeof corners === 'undefined' || corners === null)
+        corners = new Float64Array(4 * corns.length);
+      corners.set(corns, len);
+      len += corns.length;
+    }
+    region = get2DRegionFromS2Corners(corners);
+  } else {
+    const corners: Float64Array = getS2BoundaryFlatFromS2Cell(s2cell);
+    region = get2DRegionFromS2Corners(corners);
+  }
+  return region;
+}
+
+/**
+ * Converts the S2 cell defined by its corners to the 2D region
+ * @param corners {Float64Array} - a simple polygon in flat array format: [lng0, lat0, lng1, lat1, ...]
+ * @returns 2D region as an object containing: west, north, east, south in degrees
+ */
+function get2DRegionFromS2Corners(corners: Float64Array): {
+  west: number;
+  east: number;
+  north: number;
+  south: number;
+} {
+  if (corners.length % 2 !== 0) {
+    throw new Error('Invalid corners');
+  }
+  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 {
+    west: longitudes[0],
+    east: longitudes[longitudes.length - 1],
+    north: latitudes[latitudes.length - 1],
+    south: latitudes[0]
+  };
+}

package/src/lib/utils/s2/index.ts

@@ -0,0 +1,17 @@
+// math.gl MIT license
+
+export {getS2CellIdFromToken, getS2TokenFromCellId, getS2ChildCellId} from './s2-token-functions';
+export {getS2BoundaryFlat, getS2LngLat} from './s2-geometry-functions';
+
+export {getS2Cell, getS2QuadKey} from './s2geometry/s2-cell-utils';
+export {
+  getS2QuadkeyFromCellId,
+  getS2CellFromQuadKey,
+  getS2CellIdFromQuadkey,
+  getS2LngLatFromS2Cell
+} from './s2geometry/s2-geometry';
+
+export {getS2Region} from './converters/s2-to-region';
+
+export type {S2HeightInfo} from './converters/s2-to-obb-points';
+export {getS2OrientedBoundingBoxCornerPoints} from './converters/s2-to-obb-points';

package/src/lib/utils/s2/s2-geometry-functions.ts

@@ -0,0 +1,28 @@
+// math.gl, MIT license
+
+import {getS2BoundaryFlatFromS2Cell} from './converters/s2-to-boundary';
+import {getS2LngLatFromS2Cell} from './s2geometry/s2-geometry';
+import {getS2Cell} from './s2geometry/s2-cell-utils';
+
+// GEOMETRY
+
+/**
+ * Retrieve S2 geometry center
+ * @param s2Token {string} A string that is the cell's hex token
+ * @returns {[number, number]} Longitude and Latitude coordinates of the S2 cell's center
+ */
+export function getS2LngLat(s2Token: string): [number, number] {
+  const s2cell = getS2Cell(s2Token);
+  return getS2LngLatFromS2Cell(s2cell);
+}
+
+/**
+ * Get a polygon with corner coordinates for an s2 cell
+ * @param tokenOrKey {string} A string that is the cell's hex token or the Hilbert quad key (containing /)
+ * @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(tokenOrKey: string): Float64Array {
+  const s2cell = getS2Cell(tokenOrKey);
+  return getS2BoundaryFlatFromS2Cell(s2cell);
+}

package/src/lib/utils/s2/s2-token-functions.ts

@@ -0,0 +1,67 @@
+// loaders.gl, MIT license
+
+import Long from 'long';
+
+const MAXIMUM_TOKEN_LENGTH = 16;
+
+/**
+ * Convert the S2 token to the S2 cell ID
+ * @param token {string} A string that is the cell's hex token. Zero cell ID is represented as 'X'.
+ * @returns {Long} Cell id that is a 64-bit encoding of a face and a Hilbert curve parameter on that face.
+ * See {@link https://github.com/google/s2-geometry-library-java/blob/c04b68bf3197a9c34082327eeb3aec7ab7c85da1/src/com/google/common/geometry/S2CellId.java#L439} for more information
+ */
+export function getS2CellIdFromToken(token: string): Long {
+  if (token === 'X') {
+    token = '';
+  }
+  // pad token with zeros to make the length 16 that is defined in MAXIMUM_TOKEN_LENGTH
+  const paddedToken = token.padEnd(MAXIMUM_TOKEN_LENGTH, '0');
+  return Long.fromString(paddedToken, true, 16); // Hex base
+}
+
+/**
+ * Convert the S2 cell ID to the S2 token
+ * @param cellId {Long} A 64-bit encoding of a face and a Hilbert curve parameter on that face.
+ * @returns {string} A string that is the cell's hex token. Zero cell ID is represented as 'X'.
+ */
+export function getS2TokenFromCellId(cellId: Long): string {
+  if (cellId.isZero()) {
+    return 'X';
+  }
+  let numZeroDigits = cellId.countTrailingZeros();
+
+  const remainder = numZeroDigits % 4;
+  numZeroDigits = (numZeroDigits - remainder) / 4;
+  const trailingZeroHexChars = numZeroDigits;
+  numZeroDigits *= 4;
+
+  const x = cellId.shiftRightUnsigned(numZeroDigits);
+  const hexString = x.toString(16).replace(/0+$/, '');
+  const zeroString = Array(17 - trailingZeroHexChars - hexString.length).join('0');
+  return zeroString + hexString;
+}
+
+/**
+ * Get one of four S2 cell's children.
+ * @param cellId {Long} A 64-bit encoding of a face and a Hilbert curve parameter on that face.
+ * The cell must NOT be a leaf one. So, the cell's level is in the range [0-29].
+ * @param index {number} Child index defines one of four S2 cell's children. Must be in the range [0-3].
+ * @returns The ID of the cell's child.
+ */
+export function getS2ChildCellId(cellId: Long, index: number): Long {
+  // Shift sentinel bit 2 positions to the right.
+  const newLsb = lsb(cellId).shiftRightUnsigned(2);
+  // Insert child index before the sentinel bit.
+  const childCellId: Long = cellId.add(Long.fromNumber(2 * index + 1 - 4).multiply(newLsb));
+  return childCellId;
+}
+
+/**
+ * Return the lowest-numbered bit that is on for this cell id.
+ * @private
+ * @param cellId {Long} Cell id.
+ * @returns {Long} The lowest-numbered bit that is on for this cell id.
+ */
+function lsb(cellId: Long): Long {
+  return cellId.and(cellId.not().add(1)); // eslint-disable-line
+}

package/src/lib/utils/s2/s2geometry/s2-cell-utils.ts

@@ -0,0 +1,33 @@
+// math.gl, MIT license
+
+import type {S2Cell} from './s2-geometry';
+import {getS2CellFromQuadKey, getS2QuadkeyFromCellId} from './s2-geometry';
+import {getS2CellIdFromToken} from '../s2-token-functions';
+
+import Long from 'long';
+
+/**
+ * Return the S2Cell from the cell's hex token or the Hilbert quad key
+ * @param tokenOrKey {string} A string that is the cell's hex token or the Hilbert quad key (containing /)
+ * @returns {@link S2Cell}
+ */
+export function getS2Cell(tokenOrKey: string): S2Cell {
+  const key = getS2QuadKey(tokenOrKey);
+  const s2cell = getS2CellFromQuadKey(key);
+  return s2cell;
+}
+
+/**
+ * Get the underlying Hilbert quad key
+ * @param tokenOrKey {string} A string that is the cell's hex token or the Hilbert quad key (containing /)
+ * @returns Hilbert quad key
+ */
+export function getS2QuadKey(tokenOrKey: string): string {
+  if (tokenOrKey.indexOf('/') > 0) {
+    // is Hilbert quad key
+    return tokenOrKey;
+  }
+  // is S2 cell's hex token
+  const id: Long = getS2CellIdFromToken(tokenOrKey);
+  return getS2QuadkeyFromCellId(id);
+}