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

package/src/tileset-3d/common/tileset-source.ts

@@ -2,7 +2,7 @@
 // SPDX-License-Identifier: MIT
 // Copyright (c) vis.gl contributors
 
-import type {CoreAPI, LoaderOptions, LoaderWithParser} from '@loaders.gl/loader-utils';
+import type {CoreAPI, Loader, LoaderOptions} from '@loaders.gl/loader-utils';
 import type {Vector3} from '@math.gl/core';
 import type {TilesetTraverser, TilesetTraverserProps} from './tileset-traverser';
 import type {Tile3D} from './tile-3d';
@@ -24,18 +24,14 @@ export type TilesetSourceResolver = {
   /**
    * Loads and parses the root metadata resource for a source.
    */
-  loadRoot<DataT>(
-    url: string,
-    loader: LoaderWithParser<DataT>,
-    loadOptions: LoaderOptions
-  ): Promise<DataT>;
+  loadRoot<DataT>(url: string, loader: Loader<DataT>, loadOptions: LoaderOptions): Promise<DataT>;
 
   /**
    * Loads and parses an arbitrary source-relative resource.
    */
   loadResource<DataT>(
     url: string,
-    loader: LoaderWithParser<DataT>,
+    loader: Loader<DataT>,
     loadOptions: LoaderOptions
   ): Promise<DataT>;
 };
@@ -47,7 +43,7 @@ export type TilesetSourceRequest = {
   /** Absolute root metadata URL. */
   url: string;
   /** Loader used to fetch and parse the root metadata. */
-  loader: LoaderWithParser;
+  loader: Loader;
   /** Optional base path override for relative resources. */
   basePath?: string;
   /** Optional resource-loading strategy used for archive-backed datasets. */
@@ -119,8 +115,8 @@ export type TilesetSourceViewState = {
 export type TilesetSourceMetadata = {
   /** Format discriminator. */
   type: TILESET_TYPE;
-  /** Loader used for metadata and content requests. */
-  loader: LoaderWithParser;
+  /** Primary format loader used for metadata and default content requests. */
+  loader: Loader;
   /** Absolute root metadata URL. */
   url: string;
   /** Base path used for relative resource resolution. */
@@ -143,8 +139,8 @@ export type TilesetSourceMetadata = {
 export interface Tileset3DSource {
   /** Tileset format discriminator. */
   readonly type: TILESET_TYPE;
-  /** Loader used for content and metadata requests. */
-  readonly loader: LoaderWithParser;
+  /** Primary format loader used for metadata and default content requests. */
+  readonly loader: Loader;
   /** Absolute URL of the root tileset resource. */
   readonly url: string;
   /** Base directory used for relative resource resolution. */

package/src/tileset-3d/common/tileset-traverser.ts

@@ -10,6 +10,14 @@ import {FrameState} from '../helpers/frame-state';
 export type TilesetTraverserProps = {
   loadSiblings?: boolean;
   skipLevelOfDetail?: boolean;
+  /** SSE above which tiles remain part of the non-skipping base traversal. */
+  baseScreenSpaceError?: number;
+  /** Required SSE reduction from the nearest requested or loaded ancestor before loading a tile. */
+  skipScreenSpaceErrorFactor?: number;
+  /** Minimum hierarchy levels between requested tiles during skip-LOD traversal. */
+  skipLevels?: number;
+  /** Requests only final tiles that meet the active SSE target when skip-LOD is enabled. */
+  immediatelyLoadDesiredLevelOfDetail?: boolean;
   updateTransforms?: boolean;
   onTraversalEnd?: (frameState) => any;
   viewportTraversersMap?: Record<string, any>;
@@ -19,6 +27,10 @@ export type TilesetTraverserProps = {
 export const DEFAULT_PROPS: Required<TilesetTraverserProps> = {
   loadSiblings: false,
   skipLevelOfDetail: false,
+  baseScreenSpaceError: 1024,
+  skipScreenSpaceErrorFactor: 16,
+  skipLevels: 1,
+  immediatelyLoadDesiredLevelOfDetail: false,
   updateTransforms: true,
   onTraversalEnd: () => {},
   viewportTraversersMap: {},
@@ -28,6 +40,9 @@ export const DEFAULT_PROPS: Required<TilesetTraverserProps> = {
 export class TilesetTraverser {
   options: Required<TilesetTraverserProps>;
 
+  /** Whether loaded content has disabled skip-LOD traversal for this tileset. */
+  disableSkipLevelOfDetail: boolean = false;
+
   // fulfill in traverse call
   root: any = null;
 
@@ -58,6 +73,11 @@ export class TilesetTraverser {
     this.options = {...DEFAULT_PROPS, ...options};
   }
 
+  /** Returns whether skip-LOD traversal is enabled and supported by the loaded content. */
+  isSkipLevelOfDetailEnabled(): boolean {
+    return this.options.skipLevelOfDetail && !this.disableSkipLevelOfDetail;
+  }
+
   // tiles should be visible
   traverse(root, frameState, options) {
     this.root = root; // for root screen space error
@@ -142,7 +162,7 @@ export class TilesetTraverser {
         this.loadTile(tile, frameState);
         // Skip-LOD keeps a ready ancestor selected while descendants stream in. This prevents
         // replacement holes when traversal jumps over one or more hierarchy levels.
-        if (stoppedRefining || this.options.skipLevelOfDetail) {
+        if (stoppedRefining || this.isSkipLevelOfDetailEnabled()) {
           this.selectTile(tile, frameState);
         }
       }
@@ -154,6 +174,11 @@ export class TilesetTraverser {
       tile._shouldRefine = shouldRefine && parentRefines;
     }
 
+    this.completeTraversal(frameState);
+  }
+
+  /** Notifies the owning tileset when traversal is complete or its debounce interval expires. */
+  protected completeTraversal(frameState: FrameState): void {
     const newTime = new Date().getTime();
     if (this.traversalFinished(frameState) || newTime - this.lastUpdate > this.updateDebounceTime) {
       this.lastUpdate = newTime;
@@ -170,7 +195,8 @@ export class TilesetTraverser {
 
   /* eslint-disable complexity, max-statements */
   updateAndPushChildren(tile: Tile3D, frameState: FrameState, stack, depth): boolean {
-    const {loadSiblings, skipLevelOfDetail} = this.options;
+    const {loadSiblings} = this.options;
+    const skipLevelOfDetail = this.isSkipLevelOfDetailEnabled();
 
     const children = tile.children;
 

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

@@ -5,7 +5,7 @@
 import {path, RequestCache} 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 {CoreAPI, Loader, LoaderOptions} from '@loaders.gl/loader-utils';
 import type {Tile3D} from '../common/tile-3d';
 import {Tileset3DTraverser} from './tileset-3d-traverser';
 import type {Tileset3D} from '../common/tileset-3d';
@@ -65,7 +65,7 @@ export class Tiles3DSource implements Tileset3DSource {
   /** 3D Tiles format discriminator. */
   readonly type = TILESET_TYPE.TILES3D;
   /** Loader used for tile content requests. */
-  readonly loader: LoaderWithParser;
+  readonly loader: Loader;
   /** Root tileset URL. */
   readonly url: string;
   /** Base path used for relative tile resource resolution. */
@@ -487,7 +487,7 @@ export class Tiles3DSource implements Tileset3DSource {
   private async loadWithCoreApi(
     url: string,
     options: LoaderOptions,
-    loader: LoaderWithParser = this.loader
+    loader: Loader = this.loader
   ): Promise<any> {
     if (!this.coreApi) {
       throw new Error('Tiles3DSource requires an injected coreApi to load tileset data');
@@ -513,7 +513,7 @@ export class Tiles3DSource implements Tileset3DSource {
   private async loadResourceData(
     url: string,
     options: LoaderOptions,
-    loader: LoaderWithParser = this.loader
+    loader: Loader = this.loader
   ): Promise<any> {
     if (this.resolver) {
       return await this.resolver.loadResource(url, loader, options);

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

@@ -30,6 +30,242 @@ export class Tileset3DTraverser extends TilesetTraverser {
     return true;
   }
 
+  /**
+   * Runs normal replacement traversal or the dedicated skip-LOD traversal selected by options.
+   *
+   * @param root - Root of the runtime subtree to traverse.
+   * @param frameState - Current culling and LOD state.
+   */
+  executeTraversal(root: Tile3D, frameState: FrameState): void {
+    if (!this.isSkipLevelOfDetailEnabled()) {
+      super.executeTraversal(root, frameState);
+      return;
+    }
+    this.executeSkipTraversal(root, frameState);
+  }
+
+  /**
+   * Traverses visible replacement branches without requesting skipped intermediate content.
+   *
+   * Base-traversal tiles establish coarse coverage. Below that base, only final desired tiles and
+   * tiles that cross the configured depth/SSE thresholds are requested. Already available
+   * ancestors remain selectable while those requests stream in.
+   *
+   * @param root - Root of the runtime subtree to traverse.
+   * @param frameState - Current culling and LOD state.
+   */
+  private executeSkipTraversal(root: Tile3D, frameState: FrameState): void {
+    const stack: Tile3D[] = [root];
+    root._selectionDepth = root.parent ? root.parent._selectionDepth : 1;
+
+    while (stack.length > 0) {
+      const tile = stack.pop() as Tile3D;
+      const parentRefines = !tile.parent || tile.parent._shouldRefine;
+      const shouldRefine =
+        this.canTraverse(tile, frameState) &&
+        this.updateAndPushSkipChildren(tile, frameState, stack) &&
+        parentRefines;
+      const stoppedRefining = !shouldRefine && parentRefines;
+
+      if (!tile.hasRenderContent) {
+        this.emptyTiles[tile.id] = tile;
+        this.loadTile(tile, frameState);
+        if (stoppedRefining) {
+          this.selectDesiredTile(tile, frameState);
+        }
+      } else if (tile.refine === TILE_REFINEMENT.ADD) {
+        this.loadTile(tile, frameState);
+        this.selectDesiredTile(tile, frameState);
+      } else if (tile.refine === TILE_REFINEMENT.REPLACE) {
+        if (this.isInBaseTraversal(tile, frameState)) {
+          this.loadTile(tile, frameState);
+          if (stoppedRefining) {
+            this.selectDesiredTile(tile, frameState);
+          }
+        } else if (stoppedRefining) {
+          this.loadTile(tile, frameState);
+          this.selectDesiredTile(tile, frameState);
+        } else if (this.hasReachedSkippingThreshold(tile, frameState)) {
+          this.loadTile(tile, frameState);
+        }
+      }
+
+      this.touchTile(tile, frameState);
+      tile._shouldRefine = shouldRefine;
+    }
+
+    this.completeTraversal(frameState);
+  }
+
+  /**
+   * Updates and pushes visible children for skip traversal without requiring sibling readiness.
+   *
+   * @param tile - Parent whose children are considered.
+   * @param frameState - Current culling and LOD state.
+   * @param stack - Depth-first traversal stack.
+   * @returns `true` when at least one visible child continues refinement.
+   */
+  private updateAndPushSkipChildren(
+    tile: Tile3D,
+    frameState: FrameState,
+    stack: Tile3D[]
+  ): boolean {
+    this.updateChildTiles(tile, frameState);
+    tile.children.sort(this.compareDistanceToCamera.bind(this));
+
+    let hasVisibleChild = false;
+    for (const child of tile.children) {
+      child._selectionDepth = tile.hasRenderContent
+        ? tile._selectionDepth + 1
+        : tile._selectionDepth;
+      if (child.isVisibleAndInRequestVolume) {
+        stack.push(child);
+        hasVisibleChild = true;
+      } else if (this.options.loadSiblings) {
+        this.loadTile(child, frameState);
+        this.touchTile(child, frameState);
+      }
+    }
+    return hasVisibleChild;
+  }
+
+  /**
+   * Determines whether a tile belongs to the coarse non-skipping portion of the traversal.
+   *
+   * @param tile - Tile considered for loading.
+   * @param frameState - Current traversal frame.
+   * @returns `true` when the tile should always be requested for fallback coverage.
+   */
+  private isInBaseTraversal(tile: Tile3D, frameState: FrameState): boolean {
+    if (this.options.immediatelyLoadDesiredLevelOfDetail) {
+      return false;
+    }
+    if (!this.findNearestRequestedOrLoadedAncestor(tile, frameState)) {
+      return true;
+    }
+
+    const configuredBaseScreenSpaceError = Number.isFinite(this.options.baseScreenSpaceError)
+      ? Math.max(this.options.baseScreenSpaceError, 0)
+      : 1024;
+    const baseScreenSpaceError = Math.max(
+      configuredBaseScreenSpaceError,
+      tile.tileset.memoryAdjustedScreenSpaceError
+    );
+    if (tile._screenSpaceError === 0 && tile.parent) {
+      return tile.parent._screenSpaceError > baseScreenSpaceError;
+    }
+    return tile._screenSpaceError > baseScreenSpaceError;
+  }
+
+  /**
+   * Determines whether a skipped branch has crossed its configured request threshold.
+   *
+   * @param tile - Tile considered for loading.
+   * @param frameState - Current traversal frame.
+   * @returns `true` when the tile must be requested instead of skipped.
+   */
+  private hasReachedSkippingThreshold(tile: Tile3D, frameState: FrameState): boolean {
+    if (this.options.immediatelyLoadDesiredLevelOfDetail) {
+      return false;
+    }
+    const progressiveResolutionLeaf =
+      tile._priorityProgressiveResolution &&
+      tile._screenSpaceErrorProgressiveResolution <= tile.tileset.memoryAdjustedScreenSpaceError &&
+      Boolean(
+        tile.parent &&
+          tile.parent._screenSpaceErrorProgressiveResolution >
+            tile.tileset.memoryAdjustedScreenSpaceError
+      );
+    if (progressiveResolutionLeaf) {
+      return true;
+    }
+
+    const ancestor = this.findNearestRequestedOrLoadedAncestor(tile, frameState);
+    if (!ancestor) {
+      return false;
+    }
+    const skipScreenSpaceErrorFactor =
+      Number.isFinite(this.options.skipScreenSpaceErrorFactor) &&
+      this.options.skipScreenSpaceErrorFactor > 0
+        ? this.options.skipScreenSpaceErrorFactor
+        : 16;
+    const skipLevels = Number.isFinite(this.options.skipLevels)
+      ? Math.max(Math.floor(this.options.skipLevels), 0)
+      : 1;
+    return (
+      tile._screenSpaceError < ancestor._screenSpaceError / skipScreenSpaceErrorFactor &&
+      tile.depth > ancestor.depth + skipLevels
+    );
+  }
+
+  /**
+   * Finds the nearest ancestor whose render content is loaded, loading, or requested this frame.
+   *
+   * @param tile - Descendant whose request threshold needs an anchor.
+   * @param frameState - Current traversal frame.
+   * @returns The nearest request anchor, or `null` when none exists.
+   */
+  private findNearestRequestedOrLoadedAncestor(
+    tile: Tile3D,
+    frameState: FrameState
+  ): Tile3D | null {
+    let ancestor = tile.parent;
+    while (ancestor) {
+      const contentIsUsableAnchor =
+        ancestor.hasRenderContent &&
+        !ancestor.contentFailed &&
+        (!ancestor.hasUnloadedContent || ancestor._requestedFrame === frameState.frameNumber);
+      if (contentIsUsableAnchor) {
+        return ancestor;
+      }
+      ancestor = ancestor.parent;
+    }
+    return null;
+  }
+
+  /**
+   * Selects the desired tile, its nearest ready ancestor, or nearby ready descendants.
+   *
+   * @param tile - Tile that ended the desired refinement branch.
+   * @param frameState - Current culling state.
+   */
+  private selectDesiredTile(tile: Tile3D, frameState: FrameState): void {
+    let fallbackTile: Tile3D | null = tile;
+    while (fallbackTile) {
+      if (this.shouldSelectTile(fallbackTile, frameState)) {
+        this.selectTile(fallbackTile, frameState);
+        return;
+      }
+      fallbackTile = fallbackTile.parent;
+    }
+    this.selectLoadedDescendants(tile, frameState);
+  }
+
+  /**
+   * Selects ready descendants near an unavailable desired tile to reduce temporary empty regions.
+   *
+   * @param root - Unavailable tile whose descendants are searched.
+   * @param frameState - Current culling state.
+   */
+  private selectLoadedDescendants(root: Tile3D, frameState: FrameState): void {
+    const stack: Array<{tile: Tile3D; depth: number}> = [{tile: root, depth: 0}];
+    while (stack.length > 0) {
+      const {tile, depth} = stack.pop() as {tile: Tile3D; depth: number};
+      for (const child of tile.children) {
+        this.updateTile(child, frameState);
+        if (!child.isVisibleAndInRequestVolume) {
+          continue;
+        }
+        if (child.contentAvailable) {
+          this.selectTile(child, frameState);
+          this.touchTile(child, frameState);
+        } else if (depth < 1) {
+          stack.push({tile: child, depth: depth + 1});
+        }
+      }
+    }
+  }
+
   compareDistanceToCamera(a, b) {
     // Sort by farthest child first since this is going on a stack
     return b._distanceToCamera === 0 && a._distanceToCamera === 0

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

@@ -5,7 +5,7 @@
 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 {CoreAPI, Loader, LoaderOptions} 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';
@@ -41,8 +41,10 @@ const EMPTY_CONTENT_FORMATS: TilesetContentFormats = {
 export class I3SSource implements Tileset3DSource {
   /** I3S format discriminator. */
   readonly type = TILESET_TYPE.I3S;
-  /** Loader used for tile metadata and content requests. */
-  readonly loader: LoaderWithParser;
+  /** Primary I3S loader used for root and child metadata requests. */
+  readonly loader: Loader;
+  /** Worker-capable loader used for binary tile content when supplied by the format loader. */
+  readonly contentLoader: Loader;
   /** Root I3S layer URL. */
   readonly url: string;
   /** Base path used for relative tile resource resolution. */
@@ -80,6 +82,7 @@ export class I3SSource implements Tileset3DSource {
     this.rootTileset = isTilesetRequest(input) ? null : input;
     this.tileset = this.rootTileset;
     this.loader = request.loader;
+    this.contentLoader = getI3SContentLoader(request.loader);
     this.url = request.url;
     this.basePath = request.basePath || path.dirname(request.url);
     this.resolver = request.resolver;
@@ -215,7 +218,7 @@ export class I3SSource implements Tileset3DSource {
       }
     };
 
-    tile.content = await this.loadResourceData(contentUrl, options);
+    tile.content = await this.loadResourceData(contentUrl, options, this.contentLoader);
     return {loaded: true};
   }
 
@@ -372,12 +375,16 @@ export class I3SSource implements Tileset3DSource {
   /**
    * Loads data through injected core APIs so this module stays independent from `@loaders.gl/core`.
    */
-  private async loadWithCoreApi(url: string, options: LoaderOptions): Promise<any> {
+  private async loadWithCoreApi(
+    url: string,
+    options: LoaderOptions,
+    loader: Loader = this.loader
+  ): 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);
+    return await this.coreApi.load(url, loader, options);
   }
 
   /**
@@ -408,12 +415,16 @@ export class I3SSource implements Tileset3DSource {
   /**
    * 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> {
+  private async loadResourceData(
+    url: string,
+    options: LoaderOptions,
+    loader: Loader = this.loader
+  ): Promise<any> {
     if (this.resolver) {
-      return await this.resolver.loadResource(url, this.loader, options);
+      return await this.resolver.loadResource(url, loader, options);
     }
 
-    return await this.loadWithCoreApi(url, options);
+    return await this.loadWithCoreApi(url, options, loader);
   }
 
   /** Transform one I3S header bound after target options and elevation providers are available. */
@@ -438,6 +449,11 @@ export class I3SSource implements Tileset3DSource {
   }
 }
 
+/** Returns the format-provided binary content loader, falling back for custom legacy loaders. */
+function getI3SContentLoader(loader: Loader): Loader {
+  return (loader as Loader & {contentLoader?: Loader}).contentLoader || loader;
+}
+
 function isTilesetRequest(input: TilesetSourceInput): input is TilesetSourceRequest {
   return Boolean(
     input && typeof input === 'object' && 'url' in input && 'loader' in input && !('type' in input)