@loaders.gl/tiles 5.0.0-alpha.10 → 5.0.0-alpha.12

package/src/tileset-2d.ts

@@ -2,4 +2,28 @@
 // SPDX-License-Identifier: MIT
 // Copyright (c) vis.gl contributors
 
-export * from './tileset-2d/index';
+export {
+  SharedTile2DHeader,
+  Tileset2D,
+  STRATEGY_DEFAULT,
+  STRATEGY_NEVER,
+  STRATEGY_REPLACE
+} from './tileset-2d/index';
+export type {
+  Bounds,
+  GeoBoundingBox,
+  NonGeoBoundingBox,
+  TileBoundingBox,
+  TileIndex,
+  TileLoadProps,
+  ZRange,
+  Tileset2DAdapter,
+  Tileset2DTileContext,
+  Tileset2DTraversalContext,
+  Tile2DLoadDataProps,
+  RefinementStrategy,
+  RefinementStrategyFunction,
+  Tileset2DBaseProps,
+  Tileset2DProps,
+  Tile2DListener
+} from './tileset-2d/index';

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

@@ -41,6 +41,8 @@ import {
 export type {TilesetJSON} from './tileset-source';
 
 export type Tileset3DProps = {
+  /** Format options forwarded to I3S content requests, including source-coordinate decoding. */
+  i3s?: Record<string, unknown>;
   throttleRequests?: boolean;
   maxRequests?: number;
   loadOptions?: LoaderOptions;
@@ -73,7 +75,7 @@ export type Tileset3DProps = {
   /**
    * Enables replacement traversal that may skip hierarchy levels while retaining ready ancestors
    * as coverage. This trades temporary overdraw for faster refinement on deep trees.
-   * @default false
+   * Defaults to `true` for 3D Tiles and `false` for I3S. Set to `false` to request every level.
    */
   skipLevelOfDetail?: boolean;
   /**
@@ -393,7 +395,8 @@ export class Tileset3D {
   _cache = new TilesetCache();
   _requestScheduler: RequestScheduler;
 
-  private _heldTiles: Set<string> = new Set();
+  /** Drawn fallback instances retained independently for each viewport tree. */
+  private _heldTiles: Set<Tile3D> = new Set();
   private updatePromise: Promise<number> | null = null;
   tilesetInitializationPromise: Promise<void>;
 
@@ -425,6 +428,7 @@ export class Tileset3D {
       ...suppliedOptions,
       cacheBytes,
       maximumCacheOverflowBytes,
+      skipLevelOfDetail: suppliedOptions.skipLevelOfDetail ?? source.type === TILESET_TYPE.TILES3D,
       memoryAdjustedScreenSpaceError:
         suppliedOptions.memoryAdjustedScreenSpaceError ?? usesTiles3DCacheDefaults
     };
@@ -782,28 +786,50 @@ export class Tileset3D {
 
     this.selectedTiles = this.options.onTraversalComplete(this.selectedTiles);
 
-    const selectedIds = new Set(this.selectedTiles.map(tile => tile.id));
+    const selectedTiles = new Set(this.selectedTiles);
     const hasUndrawnTiles = this.selectedTiles.some(tile => !tile.tileDrawn);
 
     let heldBackCount = 0;
     if (hasUndrawnTiles) {
-      for (const tileId of selectedIds) {
-        this._heldTiles.add(tileId);
+      const activeRoots = new Set(
+        Object.keys(this.frameStateData).map(viewportId => this.roots[viewportId])
+      );
+      const descendantReadiness = new Map<Tile3D, boolean>();
+      for (const tile of this.selectedTiles) {
+        for (let ancestor = tile.parent; ancestor; ancestor = ancestor.parent) {
+          descendantReadiness.set(
+            ancestor,
+            (descendantReadiness.get(ancestor) ?? true) && tile.tileDrawn
+          );
+        }
       }
-      for (const tileId of this._heldTiles) {
-        if (selectedIds.has(tileId)) continue;
-
-        const tile = this._tiles[tileId];
-        if (tile && tile.contentAvailable) {
+      // Drawing can finish between traversals. Promote only previously selected
+      // geometry that actually drew; pending tiles cannot provide visible fallback.
+      for (const tile of previousSelectedTiles) {
+        if (tile.tileDrawn) this._heldTiles.add(tile);
+      }
+      for (const tile of this._heldTiles) {
+        let root = tile;
+        while (root.parent) root = root.parent;
+        // Removed viewport trees cannot contribute fallback to the remaining views.
+        if (!activeRoots.has(root)) {
+          this._heldTiles.delete(tile);
+          continue;
+        }
+        if (selectedTiles.has(tile)) continue;
+        if (
+          tile.contentAvailable &&
+          !this._hasDrawnReplacement(tile, selectedTiles, descendantReadiness)
+        ) {
           tile._selectedFrame = this._frameNumber;
           this.selectedTiles.push(tile);
           heldBackCount++;
         } else {
-          this._heldTiles.delete(tileId);
+          this._heldTiles.delete(tile);
         }
       }
     } else {
-      this._heldTiles = selectedIds;
+      this._heldTiles = selectedTiles;
     }
 
     if (heldBackCount > 0) {
@@ -825,6 +851,24 @@ export class Tileset3D {
     }
   }
 
+  /**
+   * Releases fallback geometry once its own selected replacement has drawn.
+   * Unrelated pending branches must not delay this region's handoff. When no related
+   * replacement is selected, retain the fallback until the complete selection has drawn.
+   */
+  private _hasDrawnReplacement(
+    tile: Tile3D,
+    selectedTiles: Set<Tile3D>,
+    descendantReadiness: Map<Tile3D, boolean>
+  ): boolean {
+    for (let ancestor = tile.parent; ancestor; ancestor = ancestor.parent) {
+      if (selectedTiles.has(ancestor)) {
+        return ancestor.tileDrawn;
+      }
+    }
+    return descendantReadiness.get(tile) === true;
+  }
+
   _tilesChanged(oldSelectedTiles: Tile3D[], selectedTiles: Tile3D[]): boolean {
     if (oldSelectedTiles.length !== selectedTiles.length) {
       return true;

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

@@ -236,11 +236,9 @@ export class TilesetTraverser {
         } else {
           childRefines = child.contentAvailable;
         }
+        // Readiness controls replacement, not discovery. Visit every sibling so
+        // one unavailable child cannot serialize requests or hide ready siblings.
         refines = refines && childRefines;
-
-        if (!refines) {
-          return false;
-        }
       }
     }
 

package/src/tileset-3d/format-3d-tiles/implicit-tiling.ts

@@ -3,9 +3,6 @@
 // Copyright vis.gl contributors
 
 import {LOD_METRIC_TYPE, TILE_REFINEMENT, TILE_TYPE} from '../../constants';
-// TypeScript's legacy `node` resolution does not inspect package `exports`, but this public
-// subpath is resolved by the package at runtime and avoids loading unrelated DGGS decoders.
-// @ts-expect-error Conditional package subpath exports require a modern module resolver.
 import {getS2DescendantIndex, getS2IndexFromToken, getS2TokenFromIndex} from '@math.gl/dggs/s2';
 import {convertS2BoundingVolumeToOBB, type S2VolumeInfo} from '../helpers/s2-bounding-volume';
 

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

@@ -70,7 +70,9 @@ export class Tileset3DTraverser extends TilesetTraverser {
       if (!tile.hasRenderContent) {
         this.emptyTiles[tile.id] = tile;
         this.loadTile(tile, frameState);
-        if (stoppedRefining) {
+        // A known empty terminal branch needs no fallback geometry. Lazy child groups still
+        // report hasChildren while unresolved, so they retain coverage until materialized.
+        if (stoppedRefining && (!tile.hasEmptyContent || tile.hasChildren)) {
           this.selectDesiredTile(tile, frameState);
         }
       } else if (tile.refine === TILE_REFINEMENT.ADD) {
@@ -121,7 +123,7 @@ export class Tileset3DTraverser extends TilesetTraverser {
       if (child.isVisibleAndInRequestVolume) {
         stack.push(child);
         hasVisibleChild = true;
-      } else if (this.options.loadSiblings) {
+      } else if (this.options.loadSiblings && child._inRequestVolume) {
         this.loadTile(child, frameState);
         this.touchTile(child, frameState);
       }
@@ -234,6 +236,11 @@ export class Tileset3DTraverser extends TilesetTraverser {
     while (fallbackTile) {
       if (this.shouldSelectTile(fallbackTile, frameState)) {
         this.selectTile(fallbackTile, frameState);
+        if (fallbackTile !== tile) {
+          // On zoom-out the desired coarse level may still be unavailable. Preserve
+          // nearby detail that already drew while the ancestor fills uncovered pixels.
+          this.selectLoadedDescendants(tile, frameState, true);
+        }
         return;
       }
       fallbackTile = fallbackTile.parent;
@@ -246,8 +253,13 @@ export class Tileset3DTraverser extends TilesetTraverser {
    *
    * @param root - Unavailable tile whose descendants are searched.
    * @param frameState - Current culling state.
+   * @param drawnOnly - Reuse drawn detail without starting obsolete GPU work.
    */
-  private selectLoadedDescendants(root: Tile3D, frameState: FrameState): void {
+  private selectLoadedDescendants(
+    root: Tile3D,
+    frameState: FrameState,
+    drawnOnly: boolean = false
+  ): 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};
@@ -256,7 +268,7 @@ export class Tileset3DTraverser extends TilesetTraverser {
         if (!child.isVisibleAndInRequestVolume) {
           continue;
         }
-        if (child.contentAvailable) {
+        if (this.shouldSelectTile(child, frameState) && (!drawnOnly || child.tileDrawn)) {
           this.selectTile(child, frameState);
           this.touchTile(child, frameState);
         } else if (depth < 1) {

package/src/tileset-3d/helpers/s2-bounding-volume.ts

@@ -2,9 +2,6 @@
 // SPDX-License-Identifier: MIT
 // Copyright vis.gl contributors
 
-// TypeScript's legacy `node` resolution does not inspect package `exports`, but this public
-// subpath is resolved by the package at runtime and avoids loading unrelated DGGS decoders.
-// @ts-expect-error Conditional package subpath exports require a modern module resolver.
 import {getS2Bounds} from '@math.gl/dggs/s2';
 import {Ellipsoid, makeOBBFromRegion} from '@math.gl/geospatial';