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

package/src/tileset/helpers/i3s-lod.ts

@@ -1,52 +1,33 @@
-import {toRadians} from '@math.gl/core';
-
-const WGS84_RADIUS_X = 6378137.0;
-// use this to bias the lod switching  (1+ results in increasing the LOD quality)
-const qualityFactor = Math.PI / 2; // empirical derived bias factor
-/* eslint-disable max-statements */
-export function lodJudge(tile, frameState) {
-  const viewport = frameState.viewport;
-  const metersPerPixel = viewport.metersPerPixel;
-
-  const mbsLat = tile.header.mbs[1];
-  const mbsLon = tile.header.mbs[0];
-  const mbsZ = tile.header.mbs[2];
-  const mbsR = tile.header.mbs[3];
-
-  const {height, width, latitude, longitude} = viewport;
-
-  const viewportCenter = [longitude, latitude];
-  const mbsCenter = [mbsLon, mbsLat, mbsZ];
-  const mbsLatProjected = [longitude, mbsLat];
-  const mbsLonProjected = [mbsLon, latitude];
-
-  const diagonalInMeters = Math.sqrt(height * height + width * width) * metersPerPixel[0];
-  const distanceInMeters = getDistanceFromLatLon(viewportCenter, mbsCenter);
-
-  const visibleHeight = height * 0.5 + mbsR / WGS84_RADIUS_X;
-  const visibleWidth = width * 0.5 + mbsR / WGS84_RADIUS_X;
-
-  if (distanceInMeters > diagonalInMeters + mbsR / WGS84_RADIUS_X) {
-    return 'OUT';
-  }
-  if (getDistanceFromLatLon(viewportCenter, mbsLatProjected) > visibleHeight) {
-    return 'OUT';
-  }
-  if (getDistanceFromLatLon(viewportCenter, mbsLonProjected) > visibleWidth) {
-    return 'OUT';
-  }
-
-  if (tile.lodMetricValue === 0) {
+// loaders.gl, MIT license
+
+import {Matrix4, Vector3} from '@math.gl/core';
+import {Ellipsoid} from '@math.gl/geospatial';
+import {Tile3D} from '../tile-3d';
+import {FrameState} from './frame-state';
+
+const cameraPositionCartesian = new Vector3();
+const toEye = new Vector3();
+const cameraPositionEnu = new Vector3();
+const extraVertexEnu = new Vector3();
+const projectedOriginVector = new Vector3();
+const enuToCartesianMatrix = new Matrix4();
+const cartesianToEnuMatrix = new Matrix4();
+
+/**
+ * For the maxScreenThreshold error metric, maxError means that you should replace the node with it's children
+   as soon as the nodes bounding sphere has a screen radius larger than maxError pixels.
+   In this sense a value of 0 means you should always load it's children,
+   or if it's a leaf node, you should always display it.
+ * @param tile 
+ * @param frameState 
+ * @returns 
+ */
+export function getLodStatus(tile: Tile3D, frameState: FrameState): 'DIG' | 'OUT' | 'DRAW' {
+  if (tile.lodMetricValue === 0 || isNaN(tile.lodMetricValue)) {
     return 'DIG';
   }
-
-  // For the maxScreenThreshold error metric, maxError means that you should replace the node with it's children
-  // as soon as the nodes bounding sphere has a screen radius larger than maxError pixels.
-  // In this sense a value of 0 means you should always load it's children,
-  // or if it's a leaf node, you should always display it.
-  let screenSize = getI3ScreenSize(tile, frameState); // in pixels
-  screenSize *= qualityFactor;
-  if (screenSize < 0.5) {
+  const screenSize = 2 * getProjectedRadius(tile, frameState);
+  if (screenSize < 2) {
     return 'OUT';
   }
   if (!tile.header.children || screenSize <= tile.lodMetricValue) {
@@ -57,58 +38,56 @@ export function lodJudge(tile, frameState) {
   return 'OUT';
 }
 
-/* eslint-enable max-statements */
-
-function projectVertexToSphere([x, y, z]) {
-  const azim = toRadians(x);
-  const incl = toRadians(y);
-  const radius = 1.0 + z / WGS84_RADIUS_X;
-  const radCosInc = radius * Math.cos(incl);
-  x = radCosInc * Math.cos(azim);
-  y = radCosInc * Math.sin(azim);
-  z = radius * Math.sin(incl);
-  return [x, y, z];
-}
-
-function getDistanceFromLatLon(observer: number[], center: number[]) {
-  const [observerLon, observerLat, observerZ = 0.0] = observer;
-  const [centerLon, centerLat, centerZ = 0.0] = center;
-
-  const projectedCenter = projectVertexToSphere([centerLon, centerLat, centerZ]);
-  const projectedObserver = projectVertexToSphere([observerLon, observerLat, observerZ]);
-  const dx = projectedObserver[0] - projectedCenter[0];
-  const dy = projectedObserver[1] - projectedCenter[1];
-  const dz = projectedObserver[2] - projectedCenter[2];
-  return dx * dx + dy * dy + dz * dz;
-}
-
-export function getI3ScreenSize(tile, frameState) {
-  const viewport = frameState.viewport;
+/**
+ * Calculate size of MBS radius projected on the screen plane
+ * @param tile
+ * @param frameState
+ * @returns
+ */
+// eslint-disable-next-line max-statements
+export function getProjectedRadius(tile: Tile3D, frameState: FrameState): number {
+  const {topDownViewport: viewport} = frameState;
   const mbsLat = tile.header.mbs[1];
   const mbsLon = tile.header.mbs[0];
   const mbsZ = tile.header.mbs[2];
   const mbsR = tile.header.mbs[3];
-
-  const mbsCenter = [mbsLon, mbsLat, mbsZ];
+  const mbsCenterCartesian = [...tile.boundingVolume.center];
   const cameraPositionCartographic = viewport.unprojectPosition(viewport.cameraPosition);
-  const dSquared = getDistanceFromLatLon(cameraPositionCartographic, mbsCenter);
-  const mbsRNormalized = mbsR / WGS84_RADIUS_X;
-  const d = dSquared - mbsRNormalized * mbsRNormalized;
-  const fltMax = 3.4028235e38; // convert from 0x7f7fffff which is the maximum
-  if (d <= 0.0) {
-    return 0.5 * fltMax;
-  }
-  // https://stackoverflow.com/questions/21648630/radius-of-projected-sphere-in-screen-space
-  // There is a formula there to calculate projected radius:
-  // return 1.0 / Math.tan(fov) * r / Math.sqrt(d * d - r * r); // Right
-  // Hack: 300 is a Magic number to get the correct LoD. Possibly, d and r are calculated in a wrong way.
-  const screenSizeFactor =
-    ((getTanOfHalfVFAngle(frameState) * mbsRNormalized) / Math.sqrt(d)) * 300;
-  return screenSizeFactor;
-}
-
-function getTanOfHalfVFAngle(frameState) {
-  const {projectionMatrix} = frameState.viewport;
-  const t = projectionMatrix[5];
-  return t;
+  Ellipsoid.WGS84.cartographicToCartesian(cameraPositionCartographic, cameraPositionCartesian);
+
+  // ---------------------------
+  // Calculate mbs border vertex
+  // ---------------------------
+  toEye.copy(cameraPositionCartesian).subtract(mbsCenterCartesian).normalize();
+  // Add extra vector to form plane
+  Ellipsoid.WGS84.eastNorthUpToFixedFrame(mbsCenterCartesian, enuToCartesianMatrix);
+  cartesianToEnuMatrix.copy(enuToCartesianMatrix).invert();
+  cameraPositionEnu.copy(cameraPositionCartesian).transform(cartesianToEnuMatrix);
+  // Mean Proportionals in Right Triangles - Altitude rule
+  // https://mathbitsnotebook.com/Geometry/RightTriangles/RTmeanRight.html
+  const projection = Math.sqrt(
+    cameraPositionEnu[0] * cameraPositionEnu[0] + cameraPositionEnu[1] * cameraPositionEnu[1]
+  );
+  const extraZ = (projection * projection) / cameraPositionEnu[2];
+  extraVertexEnu.copy([cameraPositionEnu[0], cameraPositionEnu[1], extraZ]);
+  const extraVertexCartesian = extraVertexEnu.transform(enuToCartesianMatrix);
+  const extraVectorCartesian = extraVertexCartesian.subtract(mbsCenterCartesian).normalize();
+  // We need radius vector orthogonal to toEye vector
+  const radiusVector = toEye.cross(extraVectorCartesian).normalize().scale(mbsR);
+  const sphereMbsBorderVertexCartesian = radiusVector.add(mbsCenterCartesian);
+  const sphereMbsBorderVertexCartographic = Ellipsoid.WGS84.cartesianToCartographic(
+    sphereMbsBorderVertexCartesian
+  );
+  // ---------------------------
+
+  // Project center vertex and border vertex and calculate projected radius of MBS
+  const projectedOrigin = viewport.project([mbsLon, mbsLat, mbsZ]);
+  const projectedMbsBorderVertex = viewport.project(
+    sphereMbsBorderVertexCartographic as [number, number, number]
+  );
+  const projectedRadius = projectedOriginVector
+    .copy(projectedOrigin)
+    .subtract(projectedMbsBorderVertex)
+    .magnitude();
+  return projectedRadius;
 }

package/src/tileset/helpers/tiles-3d-lod.ts

@@ -1,3 +1,5 @@
+// loaders.gl, MIT license
+
 // This file is derived from the Cesium code base under Apache 2 license
 // See LICENSE.md and https://github.com/AnalyticalGraphicsInc/cesium/blob/master/LICENSE.md
 

package/src/tileset/helpers/transform-utils.ts

@@ -1,3 +1,5 @@
+// loaders.gl, MIT license
+
 import {Ellipsoid} from '@math.gl/geospatial';
 import {Matrix4, Vector3} from '@math.gl/core';
 import {assert} from '@loaders.gl/loader-utils';

package/src/tileset/helpers/zoom.ts

@@ -1,4 +1,9 @@
+// loaders.gl, MIT license
+
 import {Vector3} from '@math.gl/core';
+import {BoundingSphere, OrientedBoundingBox} from '@math.gl/culling';
+import {Ellipsoid} from '@math.gl/geospatial';
+import {BoundingRectangle} from '../../types';
 
 const WGS84_RADIUS_X = 6378137.0;
 const WGS84_RADIUS_Y = 6378137.0;
@@ -8,22 +13,29 @@ const scratchVector = new Vector3();
 
 /**
  * Calculate appropriate zoom value for a particular boundingVolume
- * @param {BoundingSphere, OrientedBoundingBox} boundingVolume - the instance of bounding volume
+ * @param boundingVolume - the instance of bounding volume
+ * @param cartorgraphicCenter - cartographic center of the bounding volume
  * @returns {number} - zoom value
  */
-export function getZoomFromBoundingVolume(boundingVolume) {
-  const {halfAxes, radius, width, height} = boundingVolume;
-
-  if (halfAxes) {
+export function getZoomFromBoundingVolume(
+  boundingVolume: BoundingSphere | OrientedBoundingBox | BoundingRectangle,
+  cartorgraphicCenter: Vector3
+) {
+  if (boundingVolume instanceof OrientedBoundingBox) {
     // OrientedBoundingBox
+    const {halfAxes} = boundingVolume;
     const obbSize = getObbSize(halfAxes);
     // Use WGS84_RADIUS_Z to allign with BoundingSphere algorithm
-    return Math.log2(WGS84_RADIUS_Z / obbSize);
-  } else if (radius) {
+    // Add the tile elevation value for correct zooming to elevated tiles
+    return Math.log2(WGS84_RADIUS_Z / (obbSize + cartorgraphicCenter[2]));
+  } else if (boundingVolume instanceof BoundingSphere) {
     // BoundingSphere
-    return Math.log2(WGS84_RADIUS_Z / radius);
-  } else if (height && width) {
+    const {radius} = boundingVolume;
+    // Add the tile elevation value for correct zooming to elevated tiles
+    return Math.log2(WGS84_RADIUS_Z / (radius + cartorgraphicCenter[2]));
+  } else if (boundingVolume.width && boundingVolume.height) {
     // BoundingRectangle
+    const {width, height} = boundingVolume;
     const zoomX = Math.log2(WGS84_RADIUS_X / width);
     const zoomY = Math.log2(WGS84_RADIUS_Y / height);
 
@@ -33,6 +45,69 @@ export function getZoomFromBoundingVolume(boundingVolume) {
   return 1;
 }
 
+/**
+ * Calculate initial zoom for the tileset from 3D `fullExtent` defined in
+ * the tileset metadata
+ * @param fullExtent - 3D extent of the tileset
+ * @param fullExtent.xmin - minimal longitude in decimal degrees
+ * @param fullExtent.xmax - maximal longitude in decimal degrees
+ * @param fullExtent.ymin - minimal latitude in decimal degrees
+ * @param fullExtent.ymax - maximal latitude in decimal degrees
+ * @param fullExtent.zmin - minimal elevation in meters
+ * @param fullExtent.zmax - maximal elevation in meters
+ * @param cartorgraphicCenter - tileset center in cartographic coordinate system
+ * @param cartesianCenter - tileset center in cartesian coordinate system
+ * @returns - initial zoom for the tileset
+ */
+export function getZoomFromFullExtent(
+  fullExtent: {
+    xmin: number;
+    xmax: number;
+    ymin: number;
+    ymax: number;
+    zmin: number;
+    zmax: number;
+  },
+  cartorgraphicCenter: Vector3,
+  cartesianCenter: Vector3
+) {
+  const extentVertex = Ellipsoid.WGS84.cartographicToCartesian(
+    [fullExtent.xmax, fullExtent.ymax, fullExtent.zmax],
+    new Vector3()
+  );
+  const extentSize = Math.sqrt(
+    Math.pow(extentVertex[0] - cartesianCenter[0], 2) +
+      Math.pow(extentVertex[1] - cartesianCenter[1], 2) +
+      Math.pow(extentVertex[2] - cartesianCenter[2], 2)
+  );
+  return Math.log2(WGS84_RADIUS_Z / (extentSize + cartorgraphicCenter[2]));
+}
+
+/**
+ * Calculate initial zoom for the tileset from 2D `extent` defined in
+ * the tileset metadata
+ * @param extent - 2D extent of the tileset. It is array of 4 elements [xmin, ymin, xmax, ymax]
+ * @param extent[0] - minimal longitude in decimal degrees
+ * @param extent[1] - minimal latitude in decimal degrees
+ * @param extent[2] - maximal longitude in decimal degrees
+ * @param extent[3] - maximal latitude in decimal degrees
+ * @param cartorgraphicCenter - tileset center in cartographic coordinate system
+ * @param cartesianCenter - tileset center in cartesian coordinate system
+ * @returns - initial zoom for the tileset
+ */
+export function getZoomFromExtent(
+  extent: [number, number, number, number],
+  cartorgraphicCenter: Vector3,
+  cartesianCenter: Vector3
+) {
+  const [xmin, ymin, xmax, ymax] = extent;
+  return getZoomFromFullExtent(
+    {xmin, xmax, ymin, ymax, zmin: 0, zmax: 0},
+    cartorgraphicCenter,
+    cartesianCenter
+  );
+}
+
 function getObbSize(halfAxes) {
   halfAxes.getColumn(0, scratchVector);
   const axeY = halfAxes.getColumn(1);

package/src/tileset/tile-3d.ts

@@ -1,20 +1,27 @@
+// loaders.gl, MIT license
+
 // This file is derived from the Cesium code base under Apache 2 license
 // See LICENSE.md and https://github.com/AnalyticalGraphicsInc/cesium/blob/master/LICENSE.md
+
 import {Vector3, Matrix4} from '@math.gl/core';
 import {CullingVolume} from '@math.gl/culling';
 
 import {load} from '@loaders.gl/core';
+
+// Note: circular dependency
+import type {Tileset3D} from './tileset-3d';
 import {TILE_REFINEMENT, TILE_CONTENT_STATE, TILESET_TYPE} from '../constants';
 
 import {FrameState} from './helpers/frame-state';
-import {createBoundingVolume} from './helpers/bounding-volume';
+import {
+  createBoundingVolume,
+  getCartographicBounds,
+  CartographicBounds
+} from './helpers/bounding-volume';
 import {getTiles3DScreenSpaceError} from './helpers/tiles-3d-lod';
-import {getI3ScreenSize} from './helpers/i3s-lod';
+import {getProjectedRadius} from './helpers/i3s-lod';
 import {get3dTilesOptions} from './helpers/3d-tiles-options';
-import TilesetTraverser from './traversers/tileset-traverser';
-
-// Note: circular dependency
-import type Tileset3D from './tileset-3d';
+import {TilesetTraverser} from './tileset-traverser';
 
 const scratchVector = new Vector3();
 
@@ -25,14 +32,14 @@ function defined(x) {
 /**
  * @param tileset - Tileset3D instance
  * @param header - tile header - JSON loaded from a dataset
- * @param parentHeader - parent TileHeader instance
+ * @param parentHeader - parent Tile3D instance
  * @param extendedId - optional ID to separate copies of a tile for different viewports.
  *                              const extendedId = `${tile.id}-${frameState.viewport.id}`;
  */
-export type TileHeaderProps = {
+export type Tile3DProps = {
   tileset: Tileset3D;
   header: Object;
-  parentHeader: TileHeader;
+  parentHeader: Tile3D;
   extendedId: string;
 };
 
@@ -41,12 +48,12 @@ export type TileHeaderProps = {
  * the content is loaded on-demand when needed based on the view.
  * Do not construct this directly, instead access tiles through {@link Tileset3D#tileVisible}.
  */
-export default class TileHeader {
+export class Tile3D {
   tileset: Tileset3D;
   header: any;
   id: string;
   url: string;
-  parent: TileHeader;
+  parent: Tile3D;
   refine: number;
   type: string;
   contentUrl: string;
@@ -56,10 +63,12 @@ export default class TileHeader {
   content: any;
   contentState: any;
   gpuMemoryUsageInBytes: number;
-  children: TileHeader[];
+  children: Tile3D[];
   depth: number;
   viewportIds: any[];
   transform: Matrix4;
+  extensions: any;
+  implicitTiling?: any;
 
   // Container to store application specific data
   userData: {[key: string]: any};
@@ -81,9 +90,10 @@ export default class TileHeader {
   // @ts-ignore
   private _shouldRefine: boolean;
 
+  private _boundingBox?: CartographicBounds;
+
   // Members this are updated every frame for tree traversal and rendering optimizations:
-  // @ts-ignore
-  private _distanceToCamera: number;
+  public _distanceToCamera: number;
   // @ts-ignore
   private _centerZDepth: number;
   private _screenSpaceError: number;
@@ -114,10 +124,10 @@ export default class TileHeader {
 
   /**
    * @constructs
-   * Create a TileHeader instance
+   * Create a Tile3D instance
    * @param tileset - Tileset3D instance
    * @param header - tile header - JSON loaded from a dataset
-   * @param parentHeader - parent TileHeader instance
+   * @param parentHeader - parent Tile3D instance
    * @param extendedId - optional ID to separate copies of a tile for different viewports.
    *    const extendedId = `${tile.id}-${frameState.viewport.id}`;
    */
@@ -125,7 +135,7 @@ export default class TileHeader {
   constructor(
     tileset: Tileset3D,
     header: {[key: string]: any},
-    parentHeader?: TileHeader,
+    parentHeader?: Tile3D,
     extendedId = ''
   ) {
     // PUBLIC MEMBERS
@@ -168,6 +178,7 @@ export default class TileHeader {
 
     // Container to store application specific data
     this.userData = {};
+    this.extensions = null;
 
     // PRIVATE MEMBERS
     this._priority = 0;
@@ -204,6 +215,7 @@ export default class TileHeader {
     // TODO Cesium 3d tiles specific
     this._expireDate = null;
     this._expiredContent = null;
+    this.implicitTiling = null;
 
     Object.seal(this);
   }
@@ -283,11 +295,36 @@ export default class TileHeader {
     return this.contentState === TILE_CONTENT_STATE.FAILED;
   }
 
+  /**
+   * Distance from the tile's bounding volume center to the camera
+   */
+  get distanceToCamera(): number {
+    return this._distanceToCamera;
+  }
+
+  /**
+   * Screen space error for LOD selection
+   */
+  get screenSpaceError(): number {
+    return this._screenSpaceError;
+  }
+
+  /**
+   * Get bounding box in cartographic coordinates
+   * @returns [min, max] each in [longitude, latitude, altitude]
+   */
+  get boundingBox(): CartographicBounds {
+    if (!this._boundingBox) {
+      this._boundingBox = getCartographicBounds(this.header.boundingVolume, this.boundingVolume);
+    }
+    return this._boundingBox;
+  }
+
   /** Get the tile's screen space error. */
   getScreenSpaceError(frameState, useParentLodMetric) {
     switch (this.tileset.type) {
       case TILESET_TYPE.I3S:
-        return getI3ScreenSize(this, frameState);
+        return getProjectedRadius(this, frameState);
       case TILESET_TYPE.TILES3D:
         return getTiles3DScreenSpaceError(this, frameState, useParentLodMetric);
       default:
@@ -296,6 +333,14 @@ export default class TileHeader {
     }
   }
 
+  /**
+   * Make tile unselected than means it won't be shown
+   * but it can be still loaded in memory
+   */
+  unselect(): void {
+    this._selectedFrame = 0;
+  }
+
   /*
    * If skipLevelOfDetail is off try to load child tiles as soon as possible so that their parent can refine sooner.
    * Tiles are prioritized by screen space error.
@@ -747,8 +792,20 @@ export default class TileHeader {
       case 'i3s':
         return {
           ...this.tileset.options.i3s,
-          tile: this.header,
-          tileset: this.tileset.tileset,
+          _tileOptions: {
+            attributeUrls: this.header.attributeUrls,
+            textureUrl: this.header.textureUrl,
+            textureFormat: this.header.textureFormat,
+            textureLoaderOptions: this.header.textureLoaderOptions,
+            materialDefinition: this.header.materialDefinition,
+            isDracoGeometry: this.header.isDracoGeometry,
+            mbs: this.header.mbs
+          },
+          _tilesetOptions: {
+            store: this.tileset.tileset.store,
+            attributeStorageInfo: this.tileset.tileset.attributeStorageInfo,
+            fields: this.tileset.tileset.fields
+          },
           isTileHeader: false
         };
       case '3d-tiles':