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

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 {getLodStatus} from '../helpers/i3s-lod';
-import TileHeader from '../tile-3d';
-import I3STileManager from './i3s-tile-manager';
+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,12 +14,21 @@ export default class I3STilesetTraverser extends TilesetTraverser {
     this._tileManager = new I3STileManager();
   }
 
-  shouldRefine(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;
@@ -62,8 +72,7 @@ export default class I3STilesetTraverser extends TilesetTraverser {
       ...tileset.loadOptions,
       i3s: {
         ...tileset.loadOptions.i3s,
-        isTileHeader: true,
-        loadContent: false
+        isTileHeader: true
       }
     };
 
@@ -71,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.unprojectPosition(viewport.center);
   // 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);
+}

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

@@ -1,8 +1,18 @@
+// loaders.gl, MIT license
+
 import {Matrix4, Vector3} from '@math.gl/core';
 import {Ellipsoid} from '@math.gl/geospatial';
-import Tile3D from '../tile-3d';
+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.
@@ -36,45 +46,35 @@ export function getLodStatus(tile: Tile3D, frameState: FrameState): 'DIG' | 'OUT
  */
 // eslint-disable-next-line max-statements
 export function getProjectedRadius(tile: Tile3D, frameState: FrameState): number {
-  const originalViewport = frameState.viewport;
-  const ViewportClass = originalViewport.constructor;
-  const {longitude, latitude, height, width, bearing, zoom} = originalViewport;
-  // @ts-ignore
-  const viewport = new ViewportClass({longitude, latitude, height, width, bearing, zoom, pitch: 0});
+  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 mbsCenterCartesian = [...tile.boundingVolume.center];
   const cameraPositionCartographic = viewport.unprojectPosition(viewport.cameraPosition);
-  const cameraPositionCartesian = Ellipsoid.WGS84.cartographicToCartesian(
-    cameraPositionCartographic,
-    new Vector3()
-  );
+  Ellipsoid.WGS84.cartographicToCartesian(cameraPositionCartographic, cameraPositionCartesian);
 
   // ---------------------------
   // Calculate mbs border vertex
   // ---------------------------
-  const toEye = new Vector3(cameraPositionCartesian).subtract(mbsCenterCartesian).normalize();
+  toEye.copy(cameraPositionCartesian).subtract(mbsCenterCartesian).normalize();
   // Add extra vector to form plane
-  const enuToCartesianMatrix = new Matrix4();
   Ellipsoid.WGS84.eastNorthUpToFixedFrame(mbsCenterCartesian, enuToCartesianMatrix);
-  const cartesianToEnuMatrix = new Matrix4(enuToCartesianMatrix).invert();
-  const cameraPositionEnu = new Vector3(cameraPositionCartesian).transform(cartesianToEnuMatrix);
+  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];
-  const extraVertexEnu = new Vector3([cameraPositionEnu[0], cameraPositionEnu[1], extraZ]);
+  extraVertexEnu.copy([cameraPositionEnu[0], cameraPositionEnu[1], extraZ]);
   const extraVertexCartesian = extraVertexEnu.transform(enuToCartesianMatrix);
-  const extraVectorCartesian = new Vector3(extraVertexCartesian)
-    .subtract(mbsCenterCartesian)
-    .normalize();
+  const extraVectorCartesian = extraVertexCartesian.subtract(mbsCenterCartesian).normalize();
   // We need radius vector orthogonal to toEye vector
   const radiusVector = toEye.cross(extraVectorCartesian).normalize().scale(mbsR);
-  const sphereMbsBorderVertexCartesian = new Vector3(mbsCenterCartesian).add(radiusVector);
+  const sphereMbsBorderVertexCartesian = radiusVector.add(mbsCenterCartesian);
   const sphereMbsBorderVertexCartographic = Ellipsoid.WGS84.cartesianToCartographic(
     sphereMbsBorderVertexCartesian
   );
@@ -82,8 +82,11 @@ export function getProjectedRadius(tile: Tile3D, frameState: FrameState): number
 
   // Project center vertex and border vertex and calculate projected radius of MBS
   const projectedOrigin = viewport.project([mbsLon, mbsLat, mbsZ]);
-  const projectedMbsBorderVertex = viewport.project(sphereMbsBorderVertexCartographic);
-  const projectedRadius = new Vector3(projectedOrigin)
+  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);