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

package/dist/index.cjs

@@ -2495,6 +2495,10 @@ var DEFAULT_PROPS3 = {
   foveatedTimeDelay: 0.2,
   maximumScreenSpaceError: 8,
   skipLevelOfDetail: false,
+  baseScreenSpaceError: 1024,
+  skipScreenSpaceErrorFactor: 16,
+  skipLevels: 1,
+  immediatelyLoadDesiredLevelOfDetail: false,
   dynamicScreenSpaceError: true,
   dynamicScreenSpaceErrorDensity: 2e-4,
   dynamicScreenSpaceErrorFactor: 24,
@@ -3691,6 +3695,10 @@ var ManagedArray = class {
 var DEFAULT_PROPS4 = {
   loadSiblings: false,
   skipLevelOfDetail: false,
+  baseScreenSpaceError: 1024,
+  skipScreenSpaceErrorFactor: 16,
+  skipLevels: 1,
+  immediatelyLoadDesiredLevelOfDetail: false,
   updateTransforms: true,
   onTraversalEnd: () => {
   },
@@ -3699,6 +3707,8 @@ var DEFAULT_PROPS4 = {
 };
 var TilesetTraverser = class {
   options;
+  /** Whether loaded content has disabled skip-LOD traversal for this tileset. */
+  disableSkipLevelOfDetail = false;
   // fulfill in traverse call
   root = null;
   // tiles should be rendered
@@ -3724,6 +3734,10 @@ var TilesetTraverser = class {
   constructor(options) {
     this.options = { ...DEFAULT_PROPS4, ...options };
   }
+  /** Returns whether skip-LOD traversal is enabled and supported by the loaded content. */
+  isSkipLevelOfDetailEnabled() {
+    return this.options.skipLevelOfDetail && !this.disableSkipLevelOfDetail;
+  }
   // tiles should be visible
   traverse(root, frameState, options) {
     this.root = root;
@@ -3776,13 +3790,17 @@ var TilesetTraverser = class {
         this.selectTile(tile, frameState);
       } else if (tile.refine === TILE_REFINEMENT.REPLACE) {
         this.loadTile(tile, frameState);
-        if (stoppedRefining || this.options.skipLevelOfDetail) {
+        if (stoppedRefining || this.isSkipLevelOfDetailEnabled()) {
           this.selectTile(tile, frameState);
         }
       }
       this.touchTile(tile, frameState);
       tile._shouldRefine = shouldRefine && parentRefines;
     }
+    this.completeTraversal(frameState);
+  }
+  /** Notifies the owning tileset when traversal is complete or its debounce interval expires. */
+  completeTraversal(frameState) {
     const newTime = (/* @__PURE__ */ new Date()).getTime();
     if (this.traversalFinished(frameState) || newTime - this.lastUpdate > this.updateDebounceTime) {
       this.lastUpdate = newTime;
@@ -3797,7 +3815,8 @@ var TilesetTraverser = class {
   }
   /* eslint-disable complexity, max-statements */
   updateAndPushChildren(tile, frameState, stack, depth) {
-    const { loadSiblings, skipLevelOfDetail } = this.options;
+    const { loadSiblings } = this.options;
+    const skipLevelOfDetail = this.isSkipLevelOfDetailEnabled();
     const children = tile.children;
     children.sort(this.compareDistanceToCamera.bind(this));
     const checkRefines = tile.refine === TILE_REFINEMENT.REPLACE && tile.hasRenderContent && !skipLevelOfDetail;
@@ -4307,7 +4326,7 @@ var Tile3D = class {
   // eslint-disable-next-line complexity
   _calculateRequestPriority(allowUnloadedContent) {
     const traverser = this.tileset._traverser;
-    const { skipLevelOfDetail } = traverser.options;
+    const skipLevelOfDetail = traverser.options.skipLevelOfDetail && !traverser.disableSkipLevelOfDetail;
     const maySkipTile = this.refine === TILE_REFINEMENT.ADD || skipLevelOfDetail;
     if (maySkipTile && !this.isVisible && this._visible !== void 0) {
       return -1;
@@ -4523,9 +4542,11 @@ var Tile3D = class {
       return;
     }
     this._foveatedFactor = calculateFoveatedFactor(this.boundingVolume, frameState.camera);
+    const traverser = this.tileset._traverser;
+    const skipLevelOfDetail = traverser.options.skipLevelOfDetail && !traverser.disableSkipLevelOfDetail;
     const deferralEligible = isFoveatedRequestDeferred({
       refinement: this.refine,
-      skipLevelOfDetail: this.tileset._traverser.options.skipLevelOfDetail,
+      skipLevelOfDetail,
       foveatedScreenSpaceError: options.foveatedScreenSpaceError,
       foveatedConeSize: options.foveatedConeSize,
       minimumScreenSpaceErrorRelaxation: options.foveatedMinimumScreenSpaceErrorRelaxation,
@@ -4770,6 +4791,191 @@ var Tileset3DTraverser = class 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, frameState) {
+    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.
+   */
+  executeSkipTraversal(root, frameState) {
+    const stack = [root];
+    root._selectionDepth = root.parent ? root.parent._selectionDepth : 1;
+    while (stack.length > 0) {
+      const tile = stack.pop();
+      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.
+   */
+  updateAndPushSkipChildren(tile, frameState, stack) {
+    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.
+   */
+  isInBaseTraversal(tile, frameState) {
+    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.
+   */
+  hasReachedSkippingThreshold(tile, frameState) {
+    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.
+   */
+  findNearestRequestedOrLoadedAncestor(tile, frameState) {
+    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.
+   */
+  selectDesiredTile(tile, frameState) {
+    let fallbackTile = 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.
+   */
+  selectLoadedDescendants(root, frameState) {
+    const stack = [{ tile: root, depth: 0 }];
+    while (stack.length > 0) {
+      const { tile, depth } = stack.pop();
+      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) {
     return b._distanceToCamera === 0 && a._distanceToCamera === 0 ? b._centerZDepth - a._centerZDepth : b._distanceToCamera - a._distanceToCamera;
   }
@@ -6888,8 +7094,10 @@ var EMPTY_CONTENT_FORMATS2 = {
 var I3SSource = class {
   /** I3S format discriminator. */
   type = TILESET_TYPE.I3S;
-  /** Loader used for tile metadata and content requests. */
+  /** Primary I3S loader used for root and child metadata requests. */
   loader;
+  /** Worker-capable loader used for binary tile content when supplied by the format loader. */
+  contentLoader;
   /** Root I3S layer URL. */
   url;
   /** Base path used for relative tile resource resolution. */
@@ -6924,6 +7132,7 @@ var I3SSource = class {
     this.rootTileset = isTilesetRequest2(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_exports.dirname(request.url);
     this.resolver = request.resolver;
@@ -7040,7 +7249,7 @@ var I3SSource = class {
         isTileHeader: false
       }
     };
-    tile.content = await this.loadResourceData(contentUrl, options);
+    tile.content = await this.loadResourceData(contentUrl, options, this.contentLoader);
     return { loaded: true };
   }
   /**
@@ -7171,11 +7380,11 @@ var I3SSource = class {
   /**
    * Loads data through injected core APIs so this module stays independent from `@loaders.gl/core`.
    */
-  async loadWithCoreApi(url, options) {
+  async loadWithCoreApi(url, options, loader = this.loader) {
     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);
   }
   /**
    * Loads data through an injected resolver when present, otherwise through the injected core API.
@@ -7202,11 +7411,11 @@ var I3SSource = class {
   /**
    * Loads tile metadata or content through an injected resolver when present, otherwise through the injected core API.
    */
-  async loadResourceData(url, options) {
+  async loadResourceData(url, options, loader = this.loader) {
     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. */
   async transformTileHeader(header) {
@@ -7230,6 +7439,9 @@ var I3SSource = class {
     };
   }
 };
+function getI3SContentLoader(loader) {
+  return loader.contentLoader || loader;
+}
 function isTilesetRequest2(input) {
   return Boolean(input && typeof input === "object" && "url" in input && "loader" in input && !("type" in input));
 }