@loaders.gl/tiles 4.4.5 → 5.0.0-alpha.2

package/src/tileset-3d/format-3d-tiles/tileset-3d-traverser.ts

@@ -0,0 +1,140 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+// 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 {TILE3D_OPTIMIZATION_HINT, TILE_REFINEMENT} from '../../constants';
+import {TilesetTraverser} from '../common/tileset-traverser';
+import type {Tile3D} from '../common/tile-3d';
+import type {FrameState} from '../helpers/frame-state';
+
+export class Tileset3DTraverser extends TilesetTraverser {
+  /** Pending implicit subtree requests keyed by viewport and tile identity. */
+  private readonly pendingImplicitSubtrees: Map<string, number> = new Map();
+
+  /**
+   * Reports whether every implicit subtree request started by this viewport traversal has settled.
+   *
+   * @param frameState - Traversal frame whose completion callback is being considered.
+   * @returns `true` when no matching subtree metadata request remains pending.
+   */
+  protected traversalFinished(frameState: FrameState): boolean {
+    const viewportPrefix = `${frameState.viewport.id}:`;
+    for (const [requestKey, frameNumber] of this.pendingImplicitSubtrees) {
+      if (requestKey.startsWith(viewportPrefix) && frameNumber === frameState.frameNumber) {
+        return false;
+      }
+    }
+    return true;
+  }
+
+  compareDistanceToCamera(a, b) {
+    // Sort by farthest child first since this is going on a stack
+    return b._distanceToCamera === 0 && a._distanceToCamera === 0
+      ? b._centerZDepth - a._centerZDepth
+      : b._distanceToCamera - a._distanceToCamera;
+  }
+
+  /**
+   * Starts an implicit subtree request only after culling, request-volume, and SSE eligibility.
+   *
+   * The current parent remains the traversal boundary while metadata is loading, which preserves
+   * REPLACE coverage and ADD accumulation. Request scheduling reads the tile's existing
+   * progressive-resolution and foveated metrics, so subtree metadata follows the same priority
+   * policy as render content. A completion notification lets the owning tileset publish the newly
+   * materialized traversal result on the next update.
+   *
+   * @param tile - Tile whose existing or lazy children should be updated.
+   * @param frameState - Current culling and LOD state.
+   */
+  updateChildTiles(tile: Tile3D, frameState: FrameState): void {
+    if (
+      tile.hasUnloadedChildren &&
+      tile.isVisibleAndInRequestVolume &&
+      this.shouldRefine(tile, frameState)
+    ) {
+      const requestKey = `${frameState.viewport.id}:${tile.id}`;
+      if (!this.pendingImplicitSubtrees.has(requestKey)) {
+        this.pendingImplicitSubtrees.set(requestKey, frameState.frameNumber);
+        void tile.tileset._loadTileChildren(tile, frameState).finally(() => {
+          this.handleImplicitSubtreeLoad(tile, frameState, requestKey);
+        });
+      }
+    }
+    super.updateChildTiles(tile, frameState);
+  }
+
+  /**
+   * Resumes the same traversal frame after one lazy subtree request settles.
+   *
+   * Successful materialization traverses the new headers immediately. Failed or scheduler-cancelled
+   * requests finish the current traversal without retrying in a tight loop; a later application
+   * update may retry them.
+   *
+   * @param tile - Subtree-root tile whose request settled.
+   * @param frameState - Frame that started the request.
+   * @param requestKey - Viewport-scoped pending-request identity.
+   */
+  private handleImplicitSubtreeLoad(
+    tile: Tile3D,
+    frameState: FrameState,
+    requestKey: string
+  ): void {
+    this.pendingImplicitSubtrees.delete(requestKey);
+    if (this._frameNumber !== frameState.frameNumber) {
+      return;
+    }
+    if (tile.childrenState === 'ready') {
+      this.executeTraversal(tile, frameState);
+    } else if (this.traversalFinished(frameState)) {
+      this.options.onTraversalEnd(frameState);
+    }
+  }
+
+  updateTileVisibility(tile, frameState) {
+    super.updateTileVisibility(tile, frameState);
+
+    //  Optimization - if none of the tile's children are visible then this tile isn't visible
+    if (!tile.isVisibleAndInRequestVolume) {
+      return;
+    }
+
+    const hasChildren = tile.children.length > 0;
+    if (tile.hasTilesetContent && hasChildren) {
+      // Use the root tile's visibility instead of this tile's visibility.
+      // The root tile may be culled by the children bounds optimization in which
+      // case this tile should also be culled.
+      const firstChild = tile.children[0];
+      this.updateTileVisibility(firstChild, frameState);
+      tile._visible = firstChild._visible;
+      return;
+    }
+
+    if (this.meetsScreenSpaceErrorEarly(tile, frameState)) {
+      tile._visible = false;
+      return;
+    }
+
+    const replace = tile.refine === TILE_REFINEMENT.REPLACE;
+    const useOptimization =
+      tile._optimChildrenWithinParent === TILE3D_OPTIMIZATION_HINT.USE_OPTIMIZATION;
+    if (replace && useOptimization && hasChildren) {
+      if (!this.anyChildrenVisible(tile, frameState)) {
+        tile._visible = false;
+        return;
+      }
+    }
+  }
+
+  meetsScreenSpaceErrorEarly(tile, frameState) {
+    const {parent} = tile;
+    if (!parent || parent.hasTilesetContent || parent.refine !== TILE_REFINEMENT.ADD) {
+      return false;
+    }
+
+    // Use parent's geometric error with child's box to see if the tile already meet the SSE
+    return !this.shouldRefine(tile, frameState, true);
+  }
+}

package/src/{tileset → tileset-3d}/format-i3s/i3s-pending-tiles-register.ts

@@ -1,3 +1,7 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
 /**
  * Counter to register pending tile headers for the particular frameNumber
  * Until all tiles are loaded we won't call `onTraversalEnd` callback

package/src/tileset-3d/format-i3s/i3s-source.ts

@@ -0,0 +1,366 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {path} from '@loaders.gl/loader-utils';
+import {Ellipsoid} from '@math.gl/geospatial';
+import {Vector3} from '@math.gl/core';
+import type {CoreAPI, LoaderOptions, LoaderWithParser} from '@loaders.gl/loader-utils';
+import type {Tile3D} from '../common/tile-3d';
+import {Tile3D as Tile3DNode} from '../common/tile-3d';
+import {I3STilesetTraverser} from './i3s-tileset-traverser';
+import type {Tileset3D} from '../common/tileset-3d';
+import type {FrameState} from '../helpers/frame-state';
+import type {
+  TileContentLoadResult,
+  TilesetContentFormats,
+  TilesetJSON,
+  Tileset3DSource,
+  TilesetSourceInput,
+  TilesetSourceMetadata,
+  TilesetSourceRequest,
+  TilesetSourceResolver,
+  TilesetSourceViewState
+} from '../common/tileset-source';
+import {getZoomFromExtent, getZoomFromFullExtent} from '../helpers/zoom';
+import {TILESET_TYPE} from '../../constants';
+import type {TilesetTraverser, TilesetTraverserProps} from '../common/tileset-traverser';
+
+const EMPTY_CONTENT_FORMATS: TilesetContentFormats = {
+  draco: false,
+  meshopt: false,
+  dds: false,
+  ktx2: false
+};
+
+/**
+ * {@link Tileset3DSource} implementation for I3S datasets.
+ */
+export class I3SSource implements Tileset3DSource {
+  /** I3S format discriminator. */
+  readonly type = TILESET_TYPE.I3S;
+  /** Loader used for tile metadata and content requests. */
+  readonly loader: LoaderWithParser;
+  /** Root I3S layer URL. */
+  readonly url: string;
+  /** Base path used for relative tile resource resolution. */
+  readonly basePath: string;
+  /** Parsed I3S layer metadata. */
+  tileset: TilesetJSON | null = null;
+  /** Loader options forwarded to tile requests. */
+  readonly loadOptions: LoaderOptions;
+  /** Core API used for metadata and tile-content loads when injected by the caller. */
+  coreApi?: CoreAPI;
+  /** Aggregate content-format flags discovered during streaming. */
+  readonly contentFormats: TilesetContentFormats = {...EMPTY_CONTENT_FORMATS};
+
+  asset?: Record<string, any>;
+  properties?: any;
+  extras?: any;
+  credits?: any;
+  metadata?: TilesetSourceMetadata;
+
+  private readonly queryParams: Record<string, string> = {};
+  private readonly resolver?: TilesetSourceResolver;
+  private rootTileset: TilesetJSON;
+
+  /**
+   * Creates an I3S source.
+   * @param input Root metadata request, or preloaded root metadata for tests and internal callers.
+   * @param loadOptions Loader options forwarded to tile requests.
+   */
+  constructor(input: TilesetSourceInput, loadOptions: LoaderOptions = {}) {
+    const request = normalizeI3SRequest(input);
+    this.rootTileset = isTilesetRequest(input) ? null : input;
+    this.tileset = this.rootTileset;
+    this.loader = request.loader;
+    this.url = request.url;
+    this.basePath = request.basePath || path.dirname(request.url);
+    this.resolver = request.resolver;
+    this.coreApi = request.coreApi;
+    this.loadOptions = loadOptions;
+  }
+
+  /**
+   * Fetches and normalizes root I3S metadata for runtime consumption.
+   */
+  async initialize(): Promise<void> {
+    if (!this.rootTileset) {
+      this.rootTileset = await this.loadRootData(this.url, this.loadOptions);
+    }
+    this.tileset = this.rootTileset;
+
+    if (this.rootTileset.root && typeof this.rootTileset.root.then === 'function') {
+      this.rootTileset.root = await this.rootTileset.root;
+    }
+
+    const i3sOptions = this.loadOptions.i3s;
+    if (i3sOptions && typeof i3sOptions === 'object' && 'token' in i3sOptions) {
+      const token = (i3sOptions as Record<string, unknown>).token;
+      if (typeof token === 'string') {
+        this.queryParams.token = token;
+      }
+    }
+
+    this.metadata = {
+      type: this.type,
+      loader: this.loader,
+      url: this.url,
+      basePath: this.basePath,
+      tileset: this.rootTileset,
+      lodMetricType: this.rootTileset.lodMetricType,
+      lodMetricValue: this.rootTileset.lodMetricValue,
+      refine: this.rootTileset.root?.refine
+    };
+  }
+
+  /**
+   * Returns normalized source metadata after initialization.
+   */
+  getMetadata(): TilesetSourceMetadata {
+    if (!this.metadata) {
+      throw new Error('I3SSource has not been initialized');
+    }
+    return this.metadata;
+  }
+
+  /**
+   * Returns the initialized I3S root metadata.
+   */
+  async getRootTileset(): Promise<TilesetJSON> {
+    return this.getMetadata().tileset;
+  }
+
+  /**
+   * Creates the runtime root tile for an I3S subtree.
+   */
+  initializeTileHeaders(
+    tileset: Tileset3D,
+    tilesetJson: TilesetJSON,
+    parentTile?: Tile3D | null
+  ): Tile3D {
+    const rootTile = new Tile3DNode(tileset, tilesetJson.root, parentTile || undefined);
+    if (parentTile) {
+      parentTile.children.push(rootTile);
+      rootTile.depth = parentTile.depth + 1;
+    }
+    return rootTile;
+  }
+
+  /**
+   * Creates the standard I3S traverser.
+   */
+  createTraverser(options: TilesetTraverserProps): TilesetTraverser {
+    return new I3STilesetTraverser(options);
+  }
+
+  /**
+   * Loads renderable content for an I3S tile.
+   */
+  async loadTileContent(tile: Tile3D): Promise<TileContentLoadResult> {
+    const contentUrl = this.getTileUrl(tile.contentUrl);
+    const loaderId = this.loader.id;
+    const loaderOptions = (this.loadOptions[loaderId] as Record<string, unknown>) || {};
+    const metadata = this.getMetadata();
+    const options = {
+      ...this.loadOptions,
+      [loaderId]: {
+        ...loaderOptions,
+        ...tile.tileset.options.i3s,
+        _tileOptions: {
+          attributeUrls: tile.header.attributeUrls,
+          textureUrl: tile.header.textureUrl,
+          textureFormat: tile.header.textureFormat,
+          textureLoaderOptions: tile.header.textureLoaderOptions,
+          materialDefinition: tile.header.materialDefinition,
+          isDracoGeometry: tile.header.isDracoGeometry,
+          mbs: tile.header.mbs
+        },
+        _tilesetOptions: {
+          store: metadata.tileset.store,
+          attributeStorageInfo: metadata.tileset.attributeStorageInfo,
+          fields: metadata.tileset.fields
+        },
+        isTileHeader: false
+      }
+    };
+
+    tile.content = await this.loadResourceData(contentUrl, options);
+    return {loaded: true};
+  }
+
+  /**
+   * Loads child tile metadata on demand from node pages or `/nodes/{id}` resources.
+   */
+  async loadChildTileHeader(
+    _parentTile: Tile3D,
+    childId: string,
+    _frameState: FrameState
+  ): Promise<any> {
+    const metadata = this.getMetadata();
+    if (metadata.tileset.nodePages) {
+      return await metadata.tileset.nodePagesTile.formTileFromNodePages(childId);
+    }
+
+    const nodeUrl = this.getTileUrl(`${this.url}/nodes/${childId}`);
+    const i3sLoaderOptions =
+      this.loadOptions.i3s && typeof this.loadOptions.i3s === 'object'
+        ? (this.loadOptions.i3s as Record<string, unknown>)
+        : {};
+    const options = {
+      ...this.loadOptions,
+      i3s: {
+        ...i3sLoaderOptions,
+        isTileHeader: true
+      }
+    };
+
+    return await this.loadResourceData(nodeUrl, options);
+  }
+
+  /**
+   * Resolves an I3S request URL with source-managed query parameters.
+   */
+  getTileUrl(tilePath: string): string {
+    if (tilePath.startsWith('data:')) {
+      return tilePath;
+    }
+
+    if (!Object.keys(this.queryParams).length) {
+      return tilePath;
+    }
+
+    const queryParams = new URLSearchParams(this.queryParams).toString();
+    return `${tilePath}${tilePath.includes('?') ? '&' : '?'}${queryParams}`;
+  }
+
+  /**
+   * Derives the default view state from full extent or store extent metadata.
+   */
+  getViewState(_rootTile: Tile3D | null): TilesetSourceViewState {
+    const metadata = this.getMetadata();
+    const fullExtent = metadata.tileset.fullExtent;
+    if (fullExtent) {
+      const {xmin, xmax, ymin, ymax, zmin, zmax} = fullExtent;
+      const cartographicCenter = new Vector3(
+        xmin + (xmax - xmin) / 2,
+        ymin + (ymax - ymin) / 2,
+        zmin + (zmax - zmin) / 2
+      );
+      const cartesianCenter = new Vector3();
+      Ellipsoid.WGS84.cartographicToCartesian(cartographicCenter, cartesianCenter);
+      return {
+        cartographicCenter,
+        cartesianCenter,
+        zoom: getZoomFromFullExtent(fullExtent, cartographicCenter, cartesianCenter)
+      };
+    }
+
+    const extent = metadata.tileset.store?.extent;
+    if (extent) {
+      const [xmin, ymin, xmax, ymax] = extent;
+      const cartographicCenter = new Vector3(xmin + (xmax - xmin) / 2, ymin + (ymax - ymin) / 2, 0);
+      const cartesianCenter = new Vector3();
+      Ellipsoid.WGS84.cartographicToCartesian(cartographicCenter, cartesianCenter);
+      return {
+        cartographicCenter,
+        cartesianCenter,
+        zoom: getZoomFromExtent(extent, cartographicCenter, cartesianCenter)
+      };
+    }
+
+    console.warn('Extent is not defined in the tileset header');
+    return {
+      cartographicCenter: new Vector3(),
+      zoom: 1
+    };
+  }
+
+  /**
+   * Updates content-format flags after tile content loads.
+   */
+  onTileLoaded(_tileset: Tileset3D, tile: Tile3D): void {
+    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:
+    }
+  }
+
+  /**
+   * Returns the total number of known tiles when node pages metadata is available.
+   */
+  getTilesTotalCount(): number | null {
+    const metadata = this.getMetadata();
+    return metadata.tileset?.nodePagesTile?.nodesInNodePages || null;
+  }
+
+  /**
+   * Loads data through injected core APIs so this module stays independent from `@loaders.gl/core`.
+   */
+  private async loadWithCoreApi(url: string, options: LoaderOptions): Promise<any> {
+    if (!this.coreApi) {
+      throw new Error('I3SSource requires an injected coreApi to load tileset data');
+    }
+
+    return await this.coreApi.load(url, this.loader, options);
+  }
+
+  /**
+   * Loads data through an injected resolver when present, otherwise through the injected core API.
+   */
+  private async loadRootData(url: string, options: LoaderOptions): Promise<any> {
+    if (this.resolver) {
+      return await this.resolver.loadRoot(url, this.loader, options);
+    }
+
+    return await this.loadWithCoreApi(url, options);
+  }
+
+  /**
+   * Loads tile metadata or content through an injected resolver when present, otherwise through the injected core API.
+   */
+  private async loadResourceData(url: string, options: LoaderOptions): Promise<any> {
+    if (this.resolver) {
+      return await this.resolver.loadResource(url, this.loader, options);
+    }
+
+    return await this.loadWithCoreApi(url, options);
+  }
+}
+
+function isTilesetRequest(input: TilesetSourceInput): input is TilesetSourceRequest {
+  return Boolean(
+    input && typeof input === 'object' && 'url' in input && 'loader' in input && !('type' in input)
+  );
+}
+
+/**
+ * Normalizes constructor input into a URL request descriptor.
+ * @param input Constructor input for {@link I3SSource}.
+ * @returns A normalized request with a resolved base path.
+ */
+function normalizeI3SRequest(input: TilesetSourceInput): TilesetSourceRequest {
+  if (isTilesetRequest(input)) {
+    return {
+      ...input,
+      basePath: input.basePath || path.dirname(input.url)
+    };
+  }
+
+  return {
+    url: input.url,
+    loader: input.loader,
+    basePath: input.basePath || path.dirname(input.url),
+    resolver: (input as TilesetSourceRequest).resolver,
+    coreApi: (input as TilesetSourceRequest).coreApi
+  };
+}

package/src/{tileset → tileset-3d}/format-i3s/i3s-tile-manager.ts

@@ -1,3 +1,7 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
 import {FrameState} from '../helpers/frame-state';
 import {I3SPendingTilesRegister} from './i3s-pending-tiles-register';
 
@@ -33,7 +37,7 @@ export class I3STileManager {
       // Register pending request for the frameNumber
       this.pendingTilesRegister.register(id, frameNumber);
       request()
-        .then((data) => {
+        .then(data => {
           this._statusMap[key].status = STATUS.COMPLETED;
           const {
             frameNumber: actualFrameNumber,
@@ -43,7 +47,7 @@ export class I3STileManager {
           this.pendingTilesRegister.deregister(id, actualFrameNumber);
           this._statusMap[key].callback(data, frameState);
         })
-        .catch((error) => {
+        .catch(error => {
           this._statusMap[key].status = STATUS.ERROR;
           const {
             frameNumber: actualFrameNumber,

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

@@ -1,8 +1,11 @@
-import {load} from '@loaders.gl/core';
-import {TilesetTraverser} from '../tileset-traverser';
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {TilesetTraverser} from '../common/tileset-traverser';
 
 import {getLodStatus} from '../helpers/i3s-lod';
-import {Tile3D} from '../tile-3d';
+import {Tile3D} from '../common/tile-3d';
 import {I3STileManager} from './i3s-tile-manager';
 import {FrameState} from '../helpers/frame-state';
 
@@ -32,24 +35,18 @@ export class I3STilesetTraverser extends TilesetTraverser {
     const children = tile.header.children || [];
     // children which are already fetched and constructed as Tile3D instances
     const childTiles = tile.children;
-    const tileset = tile.tileset;
-
     for (const child of children) {
       const extendedId = `${child.id}-${frameState.viewport.id}`;
       // if child tile is not fetched
-      const childTile = childTiles && childTiles.find((t) => t.id === extendedId);
+      const childTile = childTiles && childTiles.find(t => t.id === extendedId);
       if (!childTile) {
-        let request = () => this._loadTile(child.id, tileset);
+        const request = () => this._loadTile(tile, child.id, frameState);
         const cachedRequest = this._tileManager.find(extendedId);
         if (!cachedRequest) {
-          // eslint-disable-next-line max-depth
-          if (tileset.tileset.nodePages) {
-            request = () => tileset.tileset.nodePagesTile.formTileFromNodePages(child.id);
-          }
           this._tileManager.add(
             request,
             extendedId,
-            (header) => this._onTileLoad(header, tile, extendedId),
+            header => this._onTileLoad(header, tile, extendedId),
             frameState
           );
         } else {
@@ -64,19 +61,12 @@ export class I3STilesetTraverser extends TilesetTraverser {
     return false;
   }
 
-  async _loadTile(nodeId, tileset) {
-    const {loader} = tileset;
-    const nodeUrl = tileset.getTileUrl(`${tileset.url}/nodes/${nodeId}`);
-    // load metadata
-    const options = {
-      ...tileset.loadOptions,
-      i3s: {
-        ...tileset.loadOptions.i3s,
-        isTileHeader: true
-      }
-    };
+  async _loadTile(tile, nodeId, frameState) {
+    if (!tile.tileset.source.loadChildTileHeader) {
+      throw new Error('I3S source does not support child tile header loading');
+    }
 
-    return await load(nodeUrl, loader, options);
+    return await tile.tileset.source.loadChildTileHeader(tile, nodeId, frameState);
   }
 
   /**
@@ -88,6 +78,11 @@ export class I3STilesetTraverser extends TilesetTraverser {
    * @return {void}
    */
   _onTileLoad(header, tile, extendedId) {
+    if (header instanceof Error) {
+      tile.tileset._onSourceError(header, tile);
+      return;
+    }
+
     // after child tile is fetched
     const childTile = new Tile3D(tile.tileset, header, tile, extendedId);
     tile.children.push(childTile);

package/src/{tileset → tileset-3d}/helpers/3d-tiles-options.ts

@@ -1,4 +1,8 @@
-import type {Tileset3D} from '../tileset-3d';
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import type {Tileset3D} from '../common/tileset-3d';
 
 export function get3dTilesOptions(tileset: Tileset3D): {assetGltfUpAxis: 'X' | 'Y' | 'Z'} {
   return {

package/src/{tileset → tileset-3d}/helpers/bounding-volume.ts

@@ -1,3 +1,5 @@
+// SPDX-License-Identifier: Apache-2.0
+
 // 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