@loaders.gl/3d-tiles 4.0.0-alpha.5 → 4.0.0-alpha.7

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

@@ -10,14 +10,28 @@ import Tile3DBatchTable from '../classes/tile-3d-batch-table';
 import {parse3DTileHeaderSync} from './helpers/parse-3d-tile-header';
 import {parse3DTileTablesHeaderSync, parse3DTileTablesSync} from './helpers/parse-3d-tile-tables';
 import {parse3DTileGLTFViewSync, extractGLTF} from './helpers/parse-3d-tile-gltf-view';
-
-export async function parseInstancedModel3DTile(tile, arrayBuffer, byteOffset, options, context) {
+import {Tiles3DLoaderOptions} from '../../tiles-3d-loader';
+import {LoaderContext} from '@loaders.gl/loader-utils';
+
+export async function parseInstancedModel3DTile(
+  tile,
+  arrayBuffer: ArrayBuffer,
+  byteOffset: number,
+  options: Tiles3DLoaderOptions,
+  context: LoaderContext
+): Promise<number> {
   byteOffset = parseInstancedModel(tile, arrayBuffer, byteOffset, options, context);
   await extractGLTF(tile, tile.gltfFormat, options, context);
   return byteOffset;
 }
 
-function parseInstancedModel(tile, arrayBuffer, byteOffset, options, context) {
+function parseInstancedModel(
+  tile,
+  arrayBuffer: ArrayBuffer,
+  byteOffset: number,
+  options: Tiles3DLoaderOptions,
+  context: LoaderContext
+): number {
   byteOffset = parse3DTileHeaderSync(tile, arrayBuffer, byteOffset);
   if (tile.version !== 1) {
     throw new Error(`Instanced 3D Model version ${tile.version} is not supported`);

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

@@ -12,8 +12,16 @@ import {parse3DTileTablesHeaderSync, parse3DTileTablesSync} from './helpers/pars
 import {normalize3DTileColorAttribute} from './helpers/normalize-3d-tile-colors';
 import {normalize3DTileNormalAttribute} from './helpers/normalize-3d-tile-normals';
 import {normalize3DTilePositionAttribute} from './helpers/normalize-3d-tile-positions';
-
-export async function parsePointCloud3DTile(tile, arrayBuffer, byteOffset, options, context) {
+import {Tiles3DLoaderOptions} from '../../tiles-3d-loader';
+import {LoaderContext} from '@loaders.gl/loader-utils';
+
+export async function parsePointCloud3DTile(
+  tile,
+  arrayBuffer: ArrayBuffer,
+  byteOffset: number,
+  options: Tiles3DLoaderOptions,
+  context: LoaderContext
+): Promise<number> {
   byteOffset = parse3DTileHeaderSync(tile, arrayBuffer, byteOffset);
   byteOffset = parse3DTileTablesHeaderSync(tile, arrayBuffer, byteOffset);
   byteOffset = parse3DTileTablesSync(tile, arrayBuffer, byteOffset, options);
@@ -24,13 +32,14 @@ export async function parsePointCloud3DTile(tile, arrayBuffer, byteOffset, optio
   await parseDraco(tile, featureTable, batchTable, options, context);
 
   parsePositions(tile, featureTable, options);
+  // @ts-expect-error TODO - do we need to assert on the batch table?
   parseColors(tile, featureTable, batchTable);
   parseNormals(tile, featureTable);
 
   return byteOffset;
 }
 
-function initializeTile(tile) {
+function initializeTile(tile): void {
   // Initialize point cloud tile defaults
   tile.attributes = {
     positions: null,
@@ -44,7 +53,10 @@ function initializeTile(tile) {
   tile.isOctEncoded16P = false;
 }
 
-function parsePointCloudTables(tile) {
+function parsePointCloudTables(tile): {
+  featureTable: Tile3DFeatureTable;
+  batchTable: Tile3DBatchTable | null;
+} {
   const featureTable = new Tile3DFeatureTable(tile.featureTableJson, tile.featureTableBinary);
 
   const pointsLength = featureTable.getGlobalProperty('POINTS_LENGTH');
@@ -64,7 +76,11 @@ function parsePointCloudTables(tile) {
   return {featureTable, batchTable};
 }
 
-function parsePositions(tile, featureTable, options) {
+function parsePositions(
+  tile,
+  featureTable: Tile3DFeatureTable,
+  options: Tiles3DLoaderOptions
+): void {
   if (!tile.attributes.positions) {
     if (featureTable.hasProperty('POSITION')) {
       tile.attributes.positions = featureTable.getPropertyArray('POSITION', GL.FLOAT, 3);
@@ -101,7 +117,7 @@ function parsePositions(tile, featureTable, options) {
   }
 }
 
-function parseColors(tile, featureTable, batchTable) {
+function parseColors(tile, featureTable: Tile3DFeatureTable, batchTable: Tile3DBatchTable): void {
   if (!tile.attributes.colors) {
     let colors = null;
     if (featureTable.hasProperty('RGBA')) {
@@ -122,7 +138,7 @@ function parseColors(tile, featureTable, batchTable) {
   }
 }
 
-function parseNormals(tile, featureTable) {
+function parseNormals(tile, featureTable: Tile3DFeatureTable): void {
   if (!tile.attributes.normals) {
     let normals = null;
     if (featureTable.hasProperty('NORMAL')) {
@@ -136,7 +152,7 @@ function parseNormals(tile, featureTable) {
   }
 }
 
-function parseBatchIds(tile, featureTable) {
+function parseBatchIds(tile, featureTable: Tile3DFeatureTable): Tile3DBatchTable | null {
   let batchTable: Tile3DBatchTable | null = null;
   if (!tile.batchIds && featureTable.hasProperty('BATCH_ID')) {
     tile.batchIds = featureTable.getPropertyArray('BATCH_ID', GL.UNSIGNED_SHORT, 1);
@@ -154,7 +170,13 @@ function parseBatchIds(tile, featureTable) {
 }
 
 // eslint-disable-next-line complexity
-async function parseDraco(tile, featureTable, batchTable, options, context) {
+async function parseDraco(
+  tile,
+  featureTable: Tile3DFeatureTable,
+  batchTable,
+  options: Tiles3DLoaderOptions,
+  context: LoaderContext
+) {
   let dracoBuffer;
   let dracoFeatureTableProperties;
   let dracoBatchTableProperties;
@@ -202,7 +224,12 @@ async function parseDraco(tile, featureTable, batchTable, options, context) {
 }
 
 // eslint-disable-next-line complexity, max-statements
-export async function loadDraco(tile, dracoData, options, context) {
+export async function loadDraco(
+  tile,
+  dracoData,
+  options: Tiles3DLoaderOptions,
+  context: LoaderContext
+) {
   const {parse} = context;
   const dracoOptions = {
     ...options,

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);
+}