@loaders.gl/tiles 4.0.0-alpha.4 → 4.0.0-alpha.6

package/src/tileset/format-i3s/i3s-tile-manager.ts

@@ -0,0 +1,101 @@
+import {FrameState} from '../helpers/frame-state';
+import {I3SPendingTilesRegister} from './i3s-pending-tiles-register';
+
+const STATUS = {
+  REQUESTED: 'REQUESTED',
+  COMPLETED: 'COMPLETED',
+  ERROR: 'ERROR'
+};
+
+// A helper class to manage tile metadata fetching
+export class I3STileManager {
+  private _statusMap: object;
+  private pendingTilesRegister = new I3SPendingTilesRegister();
+
+  constructor() {
+    this._statusMap = {};
+  }
+
+  /**
+   * Add request to map
+   * @param request - node metadata request
+   * @param key - unique key
+   * @param callback - callback after request completed
+   * @param frameState - frameState data
+   */
+  add(request, key, callback, frameState: FrameState) {
+    if (!this._statusMap[key]) {
+      const {
+        frameNumber,
+        viewport: {id}
+      } = frameState;
+      this._statusMap[key] = {request, callback, key, frameState, status: STATUS.REQUESTED};
+      // Register pending request for the frameNumber
+      this.pendingTilesRegister.register(id, frameNumber);
+      request()
+        .then((data) => {
+          this._statusMap[key].status = STATUS.COMPLETED;
+          const {
+            frameNumber: actualFrameNumber,
+            viewport: {id}
+          } = this._statusMap[key].frameState;
+          // Deregister pending request for the frameNumber
+          this.pendingTilesRegister.deregister(id, actualFrameNumber);
+          this._statusMap[key].callback(data, frameState);
+        })
+        .catch((error) => {
+          this._statusMap[key].status = STATUS.ERROR;
+          const {
+            frameNumber: actualFrameNumber,
+            viewport: {id}
+          } = this._statusMap[key].frameState;
+          // Deregister pending request for the frameNumber
+          this.pendingTilesRegister.deregister(id, actualFrameNumber);
+          callback(error);
+        });
+    }
+  }
+
+  /**
+   * Update request if it is still actual for the new frameState
+   * @param key - unique key
+   * @param frameState - frameState data
+   */
+  update(key, frameState: FrameState) {
+    if (this._statusMap[key]) {
+      // Deregister pending request for the old frameNumber
+      const {
+        frameNumber,
+        viewport: {id}
+      } = this._statusMap[key].frameState;
+      this.pendingTilesRegister.deregister(id, frameNumber);
+
+      // Register pending request for the new frameNumber
+      const {
+        frameNumber: newFrameNumber,
+        viewport: {id: newViewportId}
+      } = frameState;
+      this.pendingTilesRegister.register(newViewportId, newFrameNumber);
+      this._statusMap[key].frameState = frameState;
+    }
+  }
+
+  /**
+   * Find request in the map
+   * @param key - unique key
+   * @returns
+   */
+  find(key) {
+    return this._statusMap[key];
+  }
+
+  /**
+   * Check it there are pending tile headers for the particular frameNumber
+   * @param viewportId
+   * @param frameNumber
+   * @returns
+   */
+  hasPendingTiles(viewportId: string, frameNumber: number): boolean {
+    return !this.pendingTilesRegister.isZero(viewportId, frameNumber);
+  }
+}

package/src/tileset/{traversers → format-i3s}/i3s-tileset-traverser.ts

@@ -1,11 +1,12 @@
 import {load} from '@loaders.gl/core';
-import TilesetTraverser from './tileset-traverser';
+import {TilesetTraverser} from '../tileset-traverser';
 
-import {lodJudge} from '../helpers/i3s-lod';
-import TileHeader from '../tile-3d';
-import I3STileManager from './i3s-tile-manager';
+import {getLodStatus} from '../helpers/i3s-lod';
+import {Tile3D} from '../tile-3d';
+import {I3STileManager} from './i3s-tile-manager';
+import {FrameState} from '../helpers/frame-state';
 
-export default class I3STilesetTraverser extends TilesetTraverser {
+export class I3STilesetTraverser extends TilesetTraverser {
   private _tileManager: I3STileManager;
 
   constructor(options) {
@@ -13,13 +14,21 @@ export default class I3STilesetTraverser extends TilesetTraverser {
     this._tileManager = new I3STileManager();
   }
 
-  shouldRefine(tile, frameState) {
-    // TODO refactor loaJudge
-    tile._lodJudge = lodJudge(tile, frameState);
+  /**
+   * Check if there are no penging tile header requests,
+   * that means the traversal is finished and we can call
+   * following-up callbacks.
+   */
+  traversalFinished(frameState: FrameState): boolean {
+    return !this._tileManager.hasPendingTiles(frameState.viewport.id, this._frameNumber || 0);
+  }
+
+  shouldRefine(tile, frameState: FrameState) {
+    tile._lodJudge = getLodStatus(tile, frameState);
     return tile._lodJudge === 'DIG';
   }
 
-  updateChildTiles(tile, frameState): boolean {
+  updateChildTiles(tile, frameState: FrameState): boolean {
     const children = tile.header.children || [];
     // children which are already fetched and constructed as Tile3D instances
     const childTiles = tile.children;
@@ -63,8 +72,7 @@ export default class I3STilesetTraverser extends TilesetTraverser {
       ...tileset.loadOptions,
       i3s: {
         ...tileset.loadOptions.i3s,
-        isTileHeader: true,
-        loadContent: false
+        isTileHeader: true
       }
     };
 
@@ -72,22 +80,26 @@ export default class I3STilesetTraverser extends TilesetTraverser {
   }
 
   /**
-   * The callback to init TileHeader instance after loading the tile JSON
+   * The callback to init Tile3D instance after loading the tile JSON
    * @param {Object} header - the tile JSON from a dataset
-   * @param {TileHeader} tile - the parent TileHeader instance
+   * @param {Tile3D} tile - the parent Tile3D instance
    * @param {string} extendedId - optional ID to separate copies of a tile for different viewports.
    *                              const extendedId = `${tile.id}-${frameState.viewport.id}`;
    * @return {void}
    */
   _onTileLoad(header, tile, extendedId) {
     // after child tile is fetched
-    const childTile = new TileHeader(tile.tileset, header, tile, extendedId);
+    const childTile = new Tile3D(tile.tileset, header, tile, extendedId);
     tile.children.push(childTile);
     const frameState = this._tileManager.find(childTile.id).frameState;
     this.updateTile(childTile, frameState);
 
     // after tile fetched, resume traversal if still in current update/traversal frame
-    if (this._frameNumber === frameState.frameNumber) {
+    if (
+      this._frameNumber === frameState.frameNumber &&
+      (this.traversalFinished(frameState) ||
+        new Date().getTime() - this.lastUpdate > this.updateDebounceTime)
+    ) {
       this.executeTraversal(childTile, frameState);
     }
   }

package/src/tileset/helpers/bounding-volume.ts

@@ -14,6 +14,7 @@ function defined(x) {
 }
 
 // const scratchMatrix = new Matrix3();
+const scratchPoint = new Vector3();
 const scratchScale = new Vector3();
 const scratchNorthWest = new Vector3();
 const scratchSouthEast = new Vector3();
@@ -68,6 +69,43 @@ export function createBoundingVolume(boundingVolumeHeader, transform, result) {
   throw new Error('3D Tile: boundingVolume must contain a sphere, region, or box');
 }
 
+/** [min, max] each in [longitude, latitude, altitude] */
+export type CartographicBounds = [min: number[], max: number[]];
+
+/**
+ * Calculate the cartographic bounding box the tile's bounding volume.
+ * @param {Object} boundingVolumeHeader The tile's bounding volume header.
+ * @param {BoundingVolume} boundingVolume The bounding volume.
+ * @returns {CartographicBounds}
+ */
+export function getCartographicBounds(
+  boundingVolumeHeader,
+  boundingVolume: OrientedBoundingBox | BoundingSphere
+): CartographicBounds {
+  // boundingVolume schema:
+  // https://github.com/AnalyticalGraphicsInc/3d-tiles/blob/master/specification/schema/boundingVolume.schema.json
+  if (boundingVolumeHeader.box) {
+    return orientedBoundingBoxToCartographicBounds(boundingVolume as OrientedBoundingBox);
+  }
+  if (boundingVolumeHeader.region) {
+    // [west, south, east, north, minimum height, maximum height]
+    // Latitudes and longitudes are in the WGS 84 datum as defined in EPSG 4979 and are in radians.
+    // Heights are in meters above (or below) the WGS 84 ellipsoid.
+    const [west, south, east, north, minHeight, maxHeight] = boundingVolumeHeader.region;
+
+    return [
+      [degrees(west), degrees(south), minHeight],
+      [degrees(east), degrees(north), maxHeight]
+    ];
+  }
+
+  if (boundingVolumeHeader.sphere) {
+    return boundingSphereToCartographicBounds(boundingVolume as BoundingSphere);
+  }
+
+  throw new Error('Unkown boundingVolume type');
+}
+
 function createBox(box, transform, result) {
   // https://math.gl/modules/culling/docs/api-reference/oriented-bounding-box
   // 1. A half-axes based representation.
@@ -197,3 +235,101 @@ function createSphere(sphere, transform, result?) {
 
   return new BoundingSphere(center, radius);
 }
+
+/**
+ * Convert a bounding volume defined by OrientedBoundingBox to cartographic bounds
+ * @returns {CartographicBounds}
+ */
+function orientedBoundingBoxToCartographicBounds(
+  boundingVolume: OrientedBoundingBox
+): CartographicBounds {
+  const result = emptyCartographicBounds();
+
+  const {halfAxes} = boundingVolume as OrientedBoundingBox;
+  const xAxis = new Vector3(halfAxes.getColumn(0));
+  const yAxis = new Vector3(halfAxes.getColumn(1));
+  const zAxis = new Vector3(halfAxes.getColumn(2));
+
+  // Test all 8 corners of the box
+  for (let x = 0; x < 2; x++) {
+    for (let y = 0; y < 2; y++) {
+      for (let z = 0; z < 2; z++) {
+        scratchPoint.copy(boundingVolume.center);
+        scratchPoint.add(xAxis);
+        scratchPoint.add(yAxis);
+        scratchPoint.add(zAxis);
+
+        addToCartographicBounds(result, scratchPoint);
+        zAxis.negate();
+      }
+      yAxis.negate();
+    }
+    xAxis.negate();
+  }
+  return result;
+}
+
+/**
+ * Convert a bounding volume defined by BoundingSphere to cartographic bounds
+ * @returns {CartographicBounds}
+ */
+function boundingSphereToCartographicBounds(boundingVolume: BoundingSphere): CartographicBounds {
+  const result = emptyCartographicBounds();
+
+  const {center, radius} = boundingVolume as BoundingSphere;
+  const point = Ellipsoid.WGS84.scaleToGeodeticSurface(center, scratchPoint);
+
+  let zAxis: Vector3;
+  if (point) {
+    zAxis = Ellipsoid.WGS84.geodeticSurfaceNormal(point) as Vector3;
+  } else {
+    zAxis = new Vector3(0, 0, 1);
+  }
+  let xAxis = new Vector3(zAxis[2], -zAxis[1], 0);
+  if (xAxis.len() > 0) {
+    xAxis.normalize();
+  } else {
+    xAxis = new Vector3(0, 1, 0);
+  }
+  const yAxis = xAxis.clone().cross(zAxis);
+
+  // Test 6 end points of the 3 axes
+  for (const axis of [xAxis, yAxis, zAxis]) {
+    scratchScale.copy(axis).scale(radius);
+    for (let dir = 0; dir < 2; dir++) {
+      scratchPoint.copy(center);
+      scratchPoint.add(scratchScale);
+      addToCartographicBounds(result, scratchPoint);
+      // Flip the axis
+      scratchScale.negate();
+    }
+  }
+  return result;
+}
+
+/**
+ * Create a new cartographic bounds that contains no points
+ * @returns {CartographicBounds}
+ */
+function emptyCartographicBounds(): CartographicBounds {
+  return [
+    [Infinity, Infinity, Infinity],
+    [-Infinity, -Infinity, -Infinity]
+  ];
+}
+
+/**
+ * Add a point to the target cartographic bounds
+ * @param {CartographicBounds} target
+ * @param {Vector3} cartesian coordinates of the point to add
+ */
+function addToCartographicBounds(target: CartographicBounds, cartesian: Readonly<Vector3>) {
+  Ellipsoid.WGS84.cartesianToCartographic(cartesian, scratchPoint);
+  target[0][0] = Math.min(target[0][0], scratchPoint[0]);
+  target[0][1] = Math.min(target[0][1], scratchPoint[1]);
+  target[0][2] = Math.min(target[0][2], scratchPoint[2]);
+
+  target[1][0] = Math.max(target[1][0], scratchPoint[0]);
+  target[1][1] = Math.max(target[1][1], scratchPoint[1]);
+  target[1][2] = Math.max(target[1][2], scratchPoint[2]);
+}

package/src/tileset/helpers/frame-state.ts

@@ -1,6 +1,8 @@
+import {Tile3D} from '@loaders.gl/tiles';
 import {Vector3} from '@math.gl/core';
 import {CullingVolume, Plane} from '@math.gl/culling';
 import {Ellipsoid} from '@math.gl/geospatial';
+import {GeospatialViewport, Viewport} from '../../types';
 
 export type FrameState = {
   camera: {
@@ -8,7 +10,8 @@ export type FrameState = {
     direction: number[];
     up: number[];
   };
-  viewport: {[key: string]: any};
+  viewport: GeospatialViewport;
+  topDownViewport: GeospatialViewport; // Use it to calculate projected radius for a tile
   height: number;
   cullingVolume: CullingVolume;
   frameNumber: number; // TODO: This can be the same between updates, what number is unique for between updates?
@@ -28,18 +31,15 @@ const cullingVolume = new CullingVolume([
 
 // Extracts a frame state appropriate for tile culling from a deck.gl viewport
 // TODO - this could likely be generalized and merged back into deck.gl for other culling scenarios
-export function getFrameState(viewport, frameNumber: number): FrameState {
+export function getFrameState(viewport: GeospatialViewport, frameNumber: number): FrameState {
+  // Traverse and and request. Update _selectedTiles so that we know what to render.
   // Traverse and and request. Update _selectedTiles so that we know what to render.
   const {cameraDirection, cameraUp, height} = viewport;
   const {metersPerUnit} = viewport.distanceScales;
 
-  const viewportCenterCartographic = [viewport.longitude, viewport.latitude, 0];
   // TODO - Ellipsoid.eastNorthUpToFixedFrame() breaks on raw array, create a Vector.
   // TODO - Ellipsoid.eastNorthUpToFixedFrame() takes a cartesian, is that intuitive?
-  const viewportCenterCartesian = Ellipsoid.WGS84.cartographicToCartesian(
-    viewportCenterCartographic,
-    new Vector3()
-  );
+  const viewportCenterCartesian = worldToCartesian(viewport, viewport.center);
   const enuToFixedTransform = Ellipsoid.WGS84.eastNorthUpToFixedFrame(viewportCenterCartesian);
 
   const cameraPositionCartographic = viewport.unprojectPosition(viewport.cameraPosition);
@@ -58,7 +58,20 @@ export function getFrameState(viewport, frameNumber: number): FrameState {
     enuToFixedTransform.transformAsVector(new Vector3(cameraUp).scale(metersPerUnit))
   ).normalize();
 
-  commonSpacePlanesToWGS84(viewport, viewportCenterCartesian);
+  commonSpacePlanesToWGS84(viewport);
+
+  const ViewportClass = viewport.constructor;
+  const {longitude, latitude, width, bearing, zoom} = viewport;
+  // @ts-ignore
+  const topDownViewport = new ViewportClass({
+    longitude,
+    latitude,
+    height,
+    width,
+    bearing,
+    zoom,
+    pitch: 0
+  });
 
   // TODO: make a file/class for frameState and document what needs to be attached to this so that traversal can function
   return {
@@ -68,6 +81,7 @@ export function getFrameState(viewport, frameNumber: number): FrameState {
       up: cameraUpCartesian
     },
     viewport,
+    topDownViewport,
     height,
     cullingVolume,
     frameNumber, // TODO: This can be the same between updates, what number is unique for between updates?
@@ -75,25 +89,95 @@ export function getFrameState(viewport, frameNumber: number): FrameState {
   };
 }
 
-function commonSpacePlanesToWGS84(viewport, viewportCenterCartesian) {
+/**
+ * Limit `tiles` array length with `maximumTilesSelected` number.
+ * The criteria for this filtering is distance of a tile center
+ * to the `frameState.viewport`'s longitude and latitude
+ * @param tiles - tiles array to filter
+ * @param frameState - frameState to calculate distances
+ * @param maximumTilesSelected - maximal amount of tiles in the output array
+ * @returns new tiles array
+ */
+export function limitSelectedTiles(
+  tiles: Tile3D[],
+  frameState: FrameState,
+  maximumTilesSelected: number
+): [Tile3D[], Tile3D[]] {
+  if (maximumTilesSelected === 0 || tiles.length <= maximumTilesSelected) {
+    return [tiles, []];
+  }
+  // Accumulate distances in couples array: [tileIndex: number, distanceToViewport: number]
+  const tuples: [number, number][] = [];
+  const {longitude: viewportLongitude, latitude: viewportLatitude} = frameState.viewport;
+  for (const [index, tile] of tiles.entries()) {
+    const [longitude, latitude] = tile.header.mbs;
+    const deltaLon = Math.abs(viewportLongitude - longitude);
+    const deltaLat = Math.abs(viewportLatitude - latitude);
+    const distance = Math.sqrt(deltaLat * deltaLat + deltaLon * deltaLon);
+    tuples.push([index, distance]);
+  }
+  const tuplesSorted = tuples.sort((a, b) => a[1] - b[1]);
+  const selectedTiles: Tile3D[] = [];
+  for (let i = 0; i < maximumTilesSelected; i++) {
+    selectedTiles.push(tiles[tuplesSorted[i][0]]);
+  }
+  const unselectedTiles: Tile3D[] = [];
+  for (let i = maximumTilesSelected; i < tuplesSorted.length; i++) {
+    unselectedTiles.push(tiles[tuplesSorted[i][0]]);
+  }
+
+  return [selectedTiles, unselectedTiles];
+}
+
+function commonSpacePlanesToWGS84(viewport) {
   // Extract frustum planes based on current view.
   const frustumPlanes = viewport.getFrustumPlanes();
+
+  // Get the near/far plane centers
+  const nearCenterCommon = closestPointOnPlane(frustumPlanes.near, viewport.cameraPosition);
+  const nearCenterCartesian = worldToCartesian(viewport, nearCenterCommon);
+  const cameraCartesian = worldToCartesian(viewport, viewport.cameraPosition, scratchPosition);
+
   let i = 0;
+  cullingVolume.planes[i++].fromPointNormal(
+    nearCenterCartesian,
+    scratchVector.copy(nearCenterCartesian).subtract(cameraCartesian)
+  );
+
   for (const dir in frustumPlanes) {
+    if (dir === 'near') {
+      continue; // eslint-disable-line no-continue
+    }
     const plane = frustumPlanes[dir];
-    const distanceToCenter = plane.normal.dot(viewport.center);
-    scratchPosition
-      .copy(plane.normal)
-      .scale(plane.distance - distanceToCenter)
-      .add(viewport.center);
-    const cartographicPos = viewport.unprojectPosition(scratchPosition);
-
-    const cartesianPos = Ellipsoid.WGS84.cartographicToCartesian(cartographicPos, new Vector3());
+    const posCommon = closestPointOnPlane(plane, nearCenterCommon, scratchPosition);
+    const cartesianPos = worldToCartesian(viewport, posCommon, scratchPosition);
 
     cullingVolume.planes[i++].fromPointNormal(
       cartesianPos,
       // Want the normal to point into the frustum since that's what culling expects
-      scratchVector.copy(viewportCenterCartesian).subtract(cartesianPos)
+      scratchVector.copy(nearCenterCartesian).subtract(cartesianPos)
     );
   }
 }
+
+function closestPointOnPlane(
+  plane: {distance: number; normal: Vector3},
+  refPoint: [number, number, number] | Vector3,
+  out: Vector3 = new Vector3()
+): Vector3 {
+  const distanceToRef = plane.normal.dot(refPoint);
+  out
+    .copy(plane.normal)
+    .scale(plane.distance - distanceToRef)
+    .add(refPoint);
+  return out;
+}
+
+function worldToCartesian(
+  viewport: Viewport,
+  point: number[] | Vector3,
+  out: Vector3 = new Vector3()
+): Vector3 {
+  const cartographicPos = viewport.unprojectPosition(point);
+  return Ellipsoid.WGS84.cartographicToCartesian(cartographicPos, out);
+}