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

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 {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,11 +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};
@@ -82,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;
@@ -115,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}`;
    */
@@ -126,7 +135,7 @@ export default class TileHeader {
   constructor(
     tileset: Tileset3D,
     header: {[key: string]: any},
-    parentHeader?: TileHeader,
+    parentHeader?: Tile3D,
     extendedId = ''
   ) {
     // PUBLIC MEMBERS
@@ -206,6 +215,7 @@ export default class TileHeader {
     // TODO Cesium 3d tiles specific
     this._expireDate = null;
     this._expiredContent = null;
+    this.implicitTiling = null;
 
     Object.seal(this);
   }
@@ -285,6 +295,31 @@ 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) {
@@ -298,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.
@@ -749,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':

package/src/tileset/tileset-3d.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
 
@@ -46,15 +48,19 @@ import {
   LoaderWithParser,
   LoaderOptions
 } from '@loaders.gl/loader-utils';
-import TilesetCache from './tileset-cache';
+import {TilesetCache} from './tileset-cache';
 import {calculateTransformProps} from './helpers/transform-utils';
-import {FrameState, getFrameState} from './helpers/frame-state';
-import {getZoomFromBoundingVolume} from './helpers/zoom';
-import Tile3D from './tile-3d';
-import Tileset3DTraverser from './traversers/tileset-3d-traverser';
-import TilesetTraverser from './traversers/tileset-traverser';
-import I3SetTraverser from './traversers/i3s-tileset-traverser';
+import {FrameState, getFrameState, limitSelectedTiles} from './helpers/frame-state';
+import {getZoomFromBoundingVolume, getZoomFromExtent, getZoomFromFullExtent} from './helpers/zoom';
+import {Tile3D} from './tile-3d';
 import {TILESET_TYPE} from '../constants';
+import {GeospatialViewport, Viewport} from '../types';
+
+import {TilesetTraverser} from './tileset-traverser';
+
+// TODO - these should be moved into their respective modules
+import {Tileset3DTraverser} from './format-3d-tiles/tileset-3d-traverser';
+import {I3STilesetTraverser} from './format-i3s/i3s-tileset-traverser';
 
 export type Tileset3DProps = {
   // loading
@@ -64,6 +70,8 @@ export type Tileset3DProps = {
   loadTiles?: boolean;
   basePath?: string;
   maximumMemoryUsage?: number;
+  maximumTilesSelected?: number;
+  debounceTime?: number;
 
   // Metadata
   description?: string;
@@ -93,6 +101,8 @@ type Props = {
   modelMatrix: Matrix4;
   throttleRequests: boolean;
   maximumMemoryUsage: number;
+  maximumTilesSelected: number;
+  debounceTime: number;
   onTileLoad: (tile: Tile3D) => any;
   onTileUnload: (tile: Tile3D) => any;
   onTileError: (tile: Tile3D, message: string, url: string) => any;
@@ -124,6 +134,10 @@ const DEFAULT_PROPS: Props = {
   maxRequests: 64,
 
   maximumMemoryUsage: 32,
+  /** Maximum number limit of tiles selected for show. 0 means no limit */
+  maximumTilesSelected: 0,
+  /** Delay time before the tileset traversal. It prevents traversal requests spam.*/
+  debounceTime: 0,
 
   /**
    * Callback. Indicates this a tile's content was loaded
@@ -149,7 +163,6 @@ const DEFAULT_PROPS: Props = {
   // View distance scale modifier
   viewDistanceScale: 1.0,
 
-  // TODO CESIUM
   // The maximum screen space error used to drive level of detail refinement.
   maximumScreenSpaceError: 8,
 
@@ -174,10 +187,10 @@ const TILES_LOADED = 'Tiles Loaded';
 const TILES_LOADING = 'Tiles Loading';
 const TILES_UNLOADED = 'Tiles Unloaded';
 const TILES_LOAD_FAILED = 'Failed Tile Loads';
-const POINTS_COUNT = 'Points';
+const POINTS_COUNT = 'Points/Vertices';
 const TILES_GPU_MEMORY = 'Tile Memory Use';
 
-export default class Tileset3D {
+export class Tileset3D {
   // props: Tileset3DProps;
   options: Props;
   loadOptions: {[key: string]: any};
@@ -204,9 +217,14 @@ export default class Tileset3D {
 
   stats: Stats;
 
+  /** flags that contain information about data types in nested tiles */
+  contentFormats = {draco: false, meshopt: false, dds: false, ktx2: false};
+
   traverseCounter: number;
   geometricError: number;
   selectedTiles: Tile3D[];
+  private updatePromise: Promise<number> | null = null;
+  tilesetInitializationPromise: Promise<void>;
 
   cartographicCenter: Vector3 | null;
   cartesianCenter: Vector3 | null;
@@ -235,7 +253,7 @@ export default class Tileset3D {
   private _pendingCount: any;
 
   // HOLD TRAVERSAL RESULTS
-  private lastUpdatedVieports: any[] | null;
+  private lastUpdatedVieports: Viewport[] | Viewport | null;
   private _requestedTiles: any;
   private _emptyTiles: any;
   private frameStateData: any;
@@ -324,7 +342,7 @@ export default class Tileset3D {
     this.credits = {};
     this.description = this.options.description || '';
 
-    this._initializeTileSet(json);
+    this.tilesetInitializationPromise = this._initializeTileSet(json);
   }
 
   /** Release resources */
@@ -335,7 +353,7 @@ export default class Tileset3D {
   /** Is the tileset loaded (update needs to have been called at least once) */
   isLoaded(): boolean {
     // Check that `_frameNumber !== 0` which means that update was called at least once
-    return this._pendingCount === 0 && this._frameNumber !== 0;
+    return this._pendingCount === 0 && this._frameNumber !== 0 && this._requestedTiles.length === 0;
   }
 
   get tiles(): object[] {
@@ -382,31 +400,68 @@ export default class Tileset3D {
   /**
    * Update visible tiles relying on a list of viewports
    * @param viewports - list of viewports
+   * @deprecated
+   */
+  update(viewports: Viewport[] | Viewport | null = null) {
+    // eslint-disable-next-line @typescript-eslint/no-floating-promises
+    this.tilesetInitializationPromise.then(() => {
+      if (!viewports && this.lastUpdatedVieports) {
+        viewports = this.lastUpdatedVieports;
+      } else {
+        this.lastUpdatedVieports = viewports;
+      }
+      if (viewports) {
+        this.doUpdate(viewports);
+      }
+    });
+  }
+
+  /**
+   * Update visible tiles relying on a list of viewports.
+   * Do it with debounce delay to prevent update spam
+   * @param viewports viewports
+   * @returns Promise of new frameNumber
+   */
+  async selectTiles(viewports: Viewport[] | Viewport | null = null): Promise<number> {
+    await this.tilesetInitializationPromise;
+    if (viewports) {
+      this.lastUpdatedVieports = viewports;
+    }
+    if (!this.updatePromise) {
+      this.updatePromise = new Promise<number>((resolve) => {
+        setTimeout(() => {
+          if (this.lastUpdatedVieports) {
+            this.doUpdate(this.lastUpdatedVieports);
+          }
+          resolve(this._frameNumber);
+          this.updatePromise = null;
+        }, this.options.debounceTime);
+      });
+    }
+    return this.updatePromise;
+  }
+
+  /**
+   * Update visible tiles relying on a list of viewports
+   * @param viewports viewports
    */
   // eslint-disable-next-line max-statements, complexity
-  update(viewports: any[]): void {
+  private doUpdate(viewports: Viewport[] | Viewport): void {
     if ('loadTiles' in this.options && !this.options.loadTiles) {
       return;
     }
     if (this.traverseCounter > 0) {
       return;
     }
-    if (!viewports && this.lastUpdatedVieports) {
-      viewports = this.lastUpdatedVieports;
-    } else {
-      this.lastUpdatedVieports = viewports;
-    }
-    if (!(viewports instanceof Array)) {
-      viewports = [viewports];
-    }
+    const preparedViewports = viewports instanceof Array ? viewports : [viewports];
 
     this._cache.reset();
     this._frameNumber++;
-    this.traverseCounter = viewports.length;
+    this.traverseCounter = preparedViewports.length;
     const viewportsToTraverse: string[] = [];
     // First loop to decrement traverseCounter
-    for (const viewport of viewports) {
-      const id = viewport.id as string;
+    for (const viewport of preparedViewports) {
+      const id = viewport.id;
       if (this._needTraverse(id)) {
         viewportsToTraverse.push(id);
       } else {
@@ -415,8 +470,8 @@ export default class Tileset3D {
     }
 
     // Second loop to traverse
-    for (const viewport of viewports) {
-      const id = viewport.id as string;
+    for (const viewport of preparedViewports) {
+      const id = viewport.id;
       if (!this.roots[id]) {
         this.roots[id] = this._initializeTileHeaders(this.tileset, null);
       }
@@ -424,7 +479,7 @@ export default class Tileset3D {
       if (!viewportsToTraverse.includes(id)) {
         continue; // eslint-disable-line no-continue
       }
-      const frameState = getFrameState(viewport, this._frameNumber);
+      const frameState = getFrameState(viewport as GeospatialViewport, this._frameNumber);
       this._traverser.traverse(this.roots[id], frameState, this.options);
     }
   }
@@ -457,7 +512,16 @@ export default class Tileset3D {
     }
     const currentFrameStateData = this.frameStateData[id];
     const selectedTiles = Object.values(this._traverser.selectedTiles);
-    currentFrameStateData.selectedTiles = selectedTiles;
+    const [filteredSelectedTiles, unselectedTiles] = limitSelectedTiles(
+      selectedTiles,
+      frameState,
+      this.options.maximumTilesSelected
+    );
+    currentFrameStateData.selectedTiles = filteredSelectedTiles;
+    for (const tile of unselectedTiles) {
+      tile.unselect();
+    }
+
     currentFrameStateData._requestedTiles = Object.values(this._traverser.requestedTiles);
     currentFrameStateData._emptyTiles = Object.values(this._traverser.emptyTiles);
 
@@ -531,6 +595,9 @@ export default class Tileset3D {
         tilesRenderable++;
         if (tile.content.pointCount) {
           pointsRenderable += tile.content.pointCount;
+        } else {
+          // Calculate vertices for non point cloud tiles.
+          pointsRenderable += tile.content.vertexCount;
         }
       }
     }
@@ -540,37 +607,92 @@ export default class Tileset3D {
     this.stats.get(POINTS_COUNT).count = pointsRenderable;
   }
 
-  _initializeTileSet(tilesetJson) {
+  async _initializeTileSet(tilesetJson) {
+    if (this.type === TILESET_TYPE.I3S) {
+      this.calculateViewPropsI3S();
+      tilesetJson.root = await tilesetJson.root;
+    }
     this.root = this._initializeTileHeaders(tilesetJson, null);
 
-    // TODO CESIUM Specific
     if (this.type === TILESET_TYPE.TILES3D) {
-      this._initializeCesiumTileset(tilesetJson);
+      this._initializeTiles3DTileset(tilesetJson);
+      this.calculateViewPropsTiles3D();
     }
 
     if (this.type === TILESET_TYPE.I3S) {
       this._initializeI3STileset();
     }
-    // Calculate cartographicCenter & zoom props to help apps center view on tileset
-    this._calculateViewProps();
   }
 
-  // Called during initialize Tileset to initialize the tileset's cartographic center (longitude, latitude) and zoom.
-  _calculateViewProps() {
+  /**
+   * Called during initialize Tileset to initialize the tileset's cartographic center (longitude, latitude) and zoom.
+   * These metrics help apps center view on tileset
+   * For I3S there is extent (<1.8 version) or fullExtent (>=1.8 version) to calculate view props
+   * @returns
+   */
+  private calculateViewPropsI3S() {
+    // for I3S 1.8 try to calculate with fullExtent
+    const fullExtent = this.tileset.fullExtent;
+    if (fullExtent) {
+      const {xmin, xmax, ymin, ymax, zmin, zmax} = fullExtent;
+      this.cartographicCenter = new Vector3(
+        xmin + (xmax - xmin) / 2,
+        ymin + (ymax - ymin) / 2,
+        zmin + (zmax - zmin) / 2
+      );
+      this.cartesianCenter = Ellipsoid.WGS84.cartographicToCartesian(
+        this.cartographicCenter,
+        new Vector3()
+      );
+      this.zoom = getZoomFromFullExtent(fullExtent, this.cartographicCenter, this.cartesianCenter);
+      return;
+    }
+    // for I3S 1.6-1.7 try to calculate with extent
+    const extent = this.tileset.store?.extent;
+    if (extent) {
+      const [xmin, ymin, xmax, ymax] = extent;
+      this.cartographicCenter = new Vector3(xmin + (xmax - xmin) / 2, ymin + (ymax - ymin) / 2, 0);
+      this.cartesianCenter = Ellipsoid.WGS84.cartographicToCartesian(
+        this.cartographicCenter,
+        new Vector3()
+      );
+      this.zoom = getZoomFromExtent(extent, this.cartographicCenter, this.cartesianCenter);
+      return;
+    }
+    // eslint-disable-next-line no-console
+    console.warn('Extent is not defined in the tileset header');
+    this.cartographicCenter = new Vector3();
+    this.zoom = 1;
+    return;
+  }
+
+  /**
+   * Called during initialize Tileset to initialize the tileset's cartographic center (longitude, latitude) and zoom.
+   * These metrics help apps center view on tileset.
+   * For 3DTiles the root tile data is used to calculate view props.
+   * @returns
+   */
+  private calculateViewPropsTiles3D() {
     const root = this.root as Tile3D;
     assert(root);
     const {center} = root.boundingVolume;
     // TODO - handle all cases
     if (!center) {
-      // eslint-disable-next-line
+      // eslint-disable-next-line no-console
       console.warn('center was not pre-calculated for the root tile');
       this.cartographicCenter = new Vector3();
       this.zoom = 1;
       return;
     }
-    this.cartographicCenter = Ellipsoid.WGS84.cartesianToCartographic(center, new Vector3());
+
+    // cartographic coordinates are undefined at the center of the ellipsoid
+    if (center[0] !== 0 || center[1] !== 0 || center[2] !== 0) {
+      this.cartographicCenter = Ellipsoid.WGS84.cartesianToCartographic(center, new Vector3());
+    } else {
+      this.cartographicCenter = new Vector3(0, 0, -Ellipsoid.WGS84.radii[0]);
+    }
     this.cartesianCenter = center;
-    this.zoom = getZoomFromBoundingVolume(root.boundingVolume);
+    this.zoom = getZoomFromBoundingVolume(root.boundingVolume, this.cartographicCenter);
   }
 
   _initializeStats() {
@@ -582,7 +704,7 @@ export default class Tileset3D {
     this.stats.get(TILES_LOADED);
     this.stats.get(TILES_UNLOADED);
     this.stats.get(TILES_LOAD_FAILED);
-    this.stats.get(POINTS_COUNT, 'memory');
+    this.stats.get(POINTS_COUNT);
     this.stats.get(TILES_GPU_MEMORY, 'memory');
   }
 
@@ -600,7 +722,7 @@ export default class Tileset3D {
       rootTile.depth = parentTileHeader.depth + 1;
     }
 
-    // Cesium 3d tiles knows the hierarchy beforehand
+    // 3DTiles knows the hierarchy beforehand
     if (this.type === TILESET_TYPE.TILES3D) {
       const stack: Tile3D[] = [];
       stack.push(rootTile);
@@ -629,7 +751,7 @@ export default class Tileset3D {
         TraverserClass = Tileset3DTraverser;
         break;
       case TILESET_TYPE.I3S:
-        TraverserClass = I3SetTraverser;
+        TraverserClass = I3STilesetTraverser;
         break;
       default:
         TraverserClass = TilesetTraverser;
@@ -673,15 +795,55 @@ export default class Tileset3D {
       return;
     }
 
+    if (this.type === TILESET_TYPE.I3S) {
+      // We can't calculate tiles total in I3S in advance so we calculate it dynamically.
+      const nodesInNodePages = this.tileset?.nodePagesTile?.nodesInNodePages || 0;
+      this.stats.get(TILES_TOTAL).reset();
+      this.stats.get(TILES_TOTAL).addCount(nodesInNodePages);
+    }
+
     // add coordinateOrigin and modelMatrix to tile
     if (tile && tile.content) {
       calculateTransformProps(tile, tile.content);
     }
 
+    this.updateContentTypes(tile);
     this._addTileToCache(tile);
     this.options.onTileLoad(tile);
   }
 
+  /**
+   * Update information about data types in nested tiles
+   * @param tile instance of a nested Tile3D
+   */
+  private updateContentTypes(tile: Tile3D) {
+    if (this.type === TILESET_TYPE.I3S) {
+      if (tile.header.isDracoGeometry) {
+        this.contentFormats.draco = true;
+      }
+      switch (tile.header.textureFormat) {
+        case 'dds':
+          this.contentFormats.dds = true;
+          break;
+        case 'ktx2':
+          this.contentFormats.ktx2 = true;
+          break;
+        default:
+      }
+    } else if (this.type === TILESET_TYPE.TILES3D) {
+      const {extensionsRemoved = []} = tile.content?.gltf || {};
+      if (extensionsRemoved.includes('KHR_draco_mesh_compression')) {
+        this.contentFormats.draco = true;
+      }
+      if (extensionsRemoved.includes('EXT_meshopt_compression')) {
+        this.contentFormats.meshopt = true;
+      }
+      if (extensionsRemoved.includes('KHR_texture_basisu')) {
+        this.contentFormats.ktx2 = true;
+      }
+    }
+  }
+
   _onStartTileLoading() {
     this._pendingCount++;
     this.stats.get(TILES_LOADING).incrementCount();
@@ -759,7 +921,7 @@ export default class Tileset3D {
     tile.destroy();
   }
 
-  _initializeCesiumTileset(tilesetJson) {
+  _initializeTiles3DTileset(tilesetJson) {
     this.asset = tilesetJson.asset;
     if (!this.asset) {
       throw new Error('Tileset must have an asset property.');

package/src/tileset/tileset-cache.ts

@@ -1,7 +1,9 @@
+// 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 DoublyLinkedList from '../utils/doubly-linked-list';
+import {DoublyLinkedList} from '../utils/doubly-linked-list';
 
 function defined(x) {
   return x !== undefined && x !== null;
@@ -12,7 +14,7 @@ function defined(x) {
  *
  * @private
  */
-export default class TilesetCache {
+export class TilesetCache {
   private _list: DoublyLinkedList;
   private _sentinel: any;
   private _trimTiles: boolean;