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

package/dist/dist.dev.js

@@ -7063,6 +7063,10 @@ var __exports__ = (() => {
     foveatedTimeDelay: 0.2,
     maximumScreenSpaceError: 8,
     skipLevelOfDetail: false,
+    baseScreenSpaceError: 1024,
+    skipScreenSpaceErrorFactor: 16,
+    skipLevels: 1,
+    immediatelyLoadDesiredLevelOfDetail: false,
     dynamicScreenSpaceError: true,
     dynamicScreenSpaceErrorDensity: 2e-4,
     dynamicScreenSpaceErrorFactor: 24,
@@ -8295,6 +8299,10 @@ var __exports__ = (() => {
   var DEFAULT_PROPS4 = {
     loadSiblings: false,
     skipLevelOfDetail: false,
+    baseScreenSpaceError: 1024,
+    skipScreenSpaceErrorFactor: 16,
+    skipLevels: 1,
+    immediatelyLoadDesiredLevelOfDetail: false,
     updateTransforms: true,
     onTraversalEnd: () => {
     },
@@ -8303,6 +8311,8 @@ var __exports__ = (() => {
   };
   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
@@ -8328,6 +8338,10 @@ var __exports__ = (() => {
     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;
@@ -8385,13 +8399,17 @@ var __exports__ = (() => {
           this.selectTile(tile, frameState);
         } else if (tile.refine === 2 /* 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;
@@ -8406,7 +8424,8 @@ var __exports__ = (() => {
     }
     /* 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 === 2 /* REPLACE */ && tile.hasRenderContent && !skipLevelOfDetail;
@@ -8928,7 +8947,7 @@ var __exports__ = (() => {
     // 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 === 1 /* ADD */ || skipLevelOfDetail;
       if (maySkipTile && !this.isVisible && this._visible !== void 0) {
         return -1;
@@ -9158,9 +9177,11 @@ var __exports__ = (() => {
         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,
@@ -9424,6 +9445,196 @@ var __exports__ = (() => {
       }
       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 === 1 /* ADD */) {
+          this.loadTile(tile, frameState);
+          this.selectDesiredTile(tile, frameState);
+        } else if (tile.refine === 2 /* 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;
     }
@@ -21015,8 +21226,10 @@ var __exports__ = (() => {
   var I3SSource = class {
     /** I3S format discriminator. */
     type = "I3S" /* 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. */
@@ -21051,6 +21264,7 @@ var __exports__ = (() => {
       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;
@@ -21171,7 +21385,7 @@ var __exports__ = (() => {
           isTileHeader: false
         }
       };
-      tile.content = await this.loadResourceData(contentUrl, options);
+      tile.content = await this.loadResourceData(contentUrl, options, this.contentLoader);
       return { loaded: true };
     }
     /**
@@ -21306,11 +21520,11 @@ var __exports__ = (() => {
     /**
      * 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.
@@ -21337,11 +21551,11 @@ var __exports__ = (() => {
     /**
      * 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) {
@@ -21364,6 +21578,9 @@ var __exports__ = (() => {
       };
     }
   };
+  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)