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

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
@@ -38,10 +274,12 @@ export class Tileset3DTraverser extends TilesetTraverser {
   }
 
   /**
-   * Starts an implicit subtree request only after culling, request-volume, and SSE eligibility.
+   * Starts an implicit subtree request after culling and request-volume 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
+   * The first subtree of an implicit hierarchy materializes independently of SSE because its
+   * placeholder has no render content. Deeper subtree boundaries remain SSE-gated. 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.
@@ -50,10 +288,11 @@ export class Tileset3DTraverser extends TilesetTraverser {
    * @param frameState - Current culling and LOD state.
    */
   updateChildTiles(tile: Tile3D, frameState: FrameState): void {
+    const isImplicitHierarchyRoot = tile.header.implicitSubtree?.coordinates.level === 0;
     if (
       tile.hasUnloadedChildren &&
       tile.isVisibleAndInRequestVolume &&
-      this.shouldRefine(tile, frameState)
+      (isImplicitHierarchyRoot || this.shouldRefine(tile, frameState))
     ) {
       const requestKey = `${frameState.viewport.id}:${tile.id}`;
       if (!this.pendingImplicitSubtrees.has(requestKey)) {

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)

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

@@ -4,7 +4,7 @@
 // See LICENSE.md and https://github.com/AnalyticalGraphicsInc/cesium/blob/master/LICENSE.md
 
 /* eslint-disable */
-import {Quaternion, Vector3, Matrix3, degrees} from '@math.gl/core';
+import {Quaternion, Vector3, Matrix3, Matrix4, degrees} from '@math.gl/core';
 import {BoundingSphere, OrientedBoundingBox} from '@math.gl/culling';
 import {Ellipsoid, makeOBBFromRegion} from '@math.gl/geospatial';
 import {assert} from '@loaders.gl/loader-utils';
@@ -18,6 +18,7 @@ function defined(x) {
 // const scratchMatrix = new Matrix3();
 const scratchPoint = new Vector3();
 const scratchScale = new Vector3();
+const identityTransform = new Matrix4();
 // const scratchRectangle = new Rectangle();
 // const scratchOrientedBoundingBox = new OrientedBoundingBox();
 // const scratchTransform = new Matrix4();
@@ -25,20 +26,39 @@ const scratchScale = new Vector3();
 /**
  * Create a bounding volume from the tile's bounding volume header.
  * @param {Object} boundingVolumeHeader The tile's bounding volume header.
- * @param {Matrix4} transform The transform to apply to the bounding volume.
+ * @param {Matrix4} transform The current computed tile transform, including application transforms.
  * @param [result] The object onto which to store the result.
+ * @param initialTransform The accumulated JSON tile transform, excluded from region transforms.
+ * Defaults to transform so callers without application transforms keep geospatial regions fixed.
  * @returns The modified result parameter or a new TileBoundingVolume instance if none was provided.
  */
-export function createBoundingVolume(boundingVolumeHeader, transform, result?) {
+export function createBoundingVolume(
+  boundingVolumeHeader,
+  transform: Matrix4,
+  result?,
+  initialTransform: Matrix4 = transform
+) {
   assert(boundingVolumeHeader, '3D Tile: boundingVolume must be defined');
 
   // boundingVolume schema:
   // https://github.com/AnalyticalGraphicsInc/3d-tiles/blob/master/specification/schema/boundingVolume.schema.json
   if (boundingVolumeHeader.box) {
-    return createBox(boundingVolumeHeader.box, transform, result);
+    // S2 cells and regions are geospatially anchored. Their conservative ECEF boxes are already
+    // world-space volumes and must not receive the tile/node transform a second time.
+    const boxTransform = boundingVolumeHeader.s2VolumeInfo ? identityTransform : transform;
+    return createBox(boundingVolumeHeader.box, boxTransform, result);
   }
   if (boundingVolumeHeader.region) {
-    return makeOBBFromRegion(boundingVolumeHeader.region);
+    const boundingVolume = makeOBBFromRegion(boundingVolumeHeader.region);
+    // Regions are already in world coordinates. Apply only the change from the JSON transform.
+    const regionTransform = transform.equals(initialTransform)
+      ? identityTransform
+      : transform.clone().multiplyRight(initialTransform.clone().invert());
+    return createBox(
+      [...boundingVolume.center, ...boundingVolume.halfAxes],
+      regionTransform,
+      result
+    );
   }
 
   if (boundingVolumeHeader.sphere) {
@@ -55,15 +75,17 @@ export type CartographicBounds = [min: number[], max: number[]];
  * Calculate the cartographic bounding box the tile's bounding volume.
  * @param {Object} boundingVolumeHeader The tile's bounding volume header.
  * @param {BoundingVolume} boundingVolume The bounding volume.
+ * @param isRegionTransformed Whether application transforms moved the region from its JSON bounds.
  * @returns {CartographicBounds}
  */
 export function getCartographicBounds(
   boundingVolumeHeader,
-  boundingVolume: OrientedBoundingBox | BoundingSphere
+  boundingVolume: OrientedBoundingBox | BoundingSphere,
+  isRegionTransformed = false
 ): CartographicBounds {
   // boundingVolume schema:
   // https://github.com/AnalyticalGraphicsInc/3d-tiles/blob/master/specification/schema/boundingVolume.schema.json
-  if (boundingVolumeHeader.box) {
+  if (boundingVolumeHeader.box || (boundingVolumeHeader.region && isRegionTransformed)) {
     return orientedBoundingBoxToCartographicBounds(boundingVolume as OrientedBoundingBox);
   }
   if (boundingVolumeHeader.region) {
@@ -142,61 +164,6 @@ function createBox(box, transform, result?) {
   return new OrientedBoundingBox(center, halfAxes);
 }
 
-/*
-function createBoxFromTransformedRegion(region, transform, initialTransform, result) {
-  const rectangle = Rectangle.unpack(region, 0, scratchRectangle);
-  const minimumHeight = region[4];
-  const maximumHeight = region[5];
-
-  const orientedBoundingBox = OrientedBoundingBox.fromRectangle(
-    rectangle,
-    minimumHeight,
-    maximumHeight,
-    Ellipsoid.WGS84,
-    scratchOrientedBoundingBox
-  );
-  const center = orientedBoundingBox.center;
-  const halfAxes = orientedBoundingBox.halfAxes;
-
-  // A region bounding volume is not transformed by the transform in the tileset JSON,
-  // but may be transformed by additional transforms applied in Cesium.
-  // This is why the transform is calculated as the difference between the initial transform and the current transform.
-  transform = Matrix4.multiplyTransformation(
-    transform,
-    Matrix4.inverseTransformation(initialTransform, scratchTransform),
-    scratchTransform
-  );
-  center = Matrix4.multiplyByPoint(transform, center, center);
-  const rotationScale = Matrix4.getRotation(transform, scratchMatrix);
-  halfAxes = Matrix3.multiply(rotationScale, halfAxes, halfAxes);
-
-  if (defined(result) && result instanceof TileOrientedBoundingBox) {
-    result.update(center, halfAxes);
-    return result;
-  }
-
-  return new TileOrientedBoundingBox(center, halfAxes);
-}
-
-function createRegion(region, transform, initialTransform, result) {
-  if (!Matrix4.equalsEpsilon(transform, initialTransform, CesiumMath.EPSILON8)) {
-    return createBoxFromTransformedRegion(region, transform, initialTransform, result);
-  }
-
-  if (defined(result)) {
-    return result;
-  }
-
-  const rectangleRegion = Rectangle.unpack(region, 0, scratchRectangle);
-
-  return new TileBoundingRegion({
-    rectangle: rectangleRegion,
-    minimumHeight: region[4],
-    maximumHeight: region[5]
-  });
-}
-*/
-
 function createSphere(sphere, transform, result?) {
   // Find the transformed center
   const center = new Vector3(sphere[0], sphere[1], sphere[2]);

package/src/tileset-3d/helpers/frame-state.ts

@@ -75,6 +75,10 @@ const cullingVolume = new CullingVolume([
 /**
  * Extracts a frame state appropriate for tile culling from a structural deck.gl viewport.
  *
+ * The viewport must describe the render camera, including its elevation. Geographic heights
+ * returned by `unprojectPosition` are used directly; adding a terrain offset only to traversal
+ * would make visibility, camera distances, and screen-space error disagree with rendering.
+ *
  * `options.timeSinceCameraMovement` can be supplied by a caller that retains camera pose across
  * calls. It defaults to a stationary camera so standalone callers do not defer requests.
  *
@@ -134,7 +138,7 @@ export function getFrameState(
   commonSpacePlanesToWGS84(viewport);
 
   const ViewportClass = viewport.constructor;
-  const {longitude, latitude, width, bearing, zoom} = viewport;
+  const {longitude, latitude, width, bearing, zoom, position} = viewport;
   // @ts-ignore
   const topDownViewport = new ViewportClass({
     longitude,
@@ -143,6 +147,7 @@ export function getFrameState(
     width,
     bearing,
     zoom,
+    position,
     pitch: 0
   });
 

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

@@ -0,0 +1,35 @@
+// loaders.gl
+// 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';
+
+/** Serialized S2 cell metadata used by 3D Tiles bounding-volume extensions. */
+export type S2VolumeInfo = {
+  /** S2 key or token. */
+  token: string;
+  /** Minimum height in meters. */
+  minimumHeight: number;
+  /** Maximum height in meters. */
+  maximumHeight: number;
+};
+
+/**
+ * Converts an S2 cell and its vertical range to the runtime oriented-box representation.
+ *
+ * @param s2VolumeInfo - S2 cell token and height range.
+ * @returns A twelve-component center/half-axis oriented bounding box.
+ */
+export function convertS2BoundingVolumeToOBB(s2VolumeInfo: S2VolumeInfo): number[] {
+  const [[west, south], [east, north]] = getS2Bounds(s2VolumeInfo.token);
+  const orientedBoundingBox = makeOBBFromRegion(
+    [west, south, east, north, s2VolumeInfo.minimumHeight, s2VolumeInfo.maximumHeight],
+    Ellipsoid.WGS84,
+    {units: 'degrees'}
+  );
+  return [...orientedBoundingBox.center, ...orientedBoundingBox.halfAxes];
+}

package/src/types.ts

@@ -46,6 +46,8 @@ export type GeospatialViewport = Viewport & {
   cameraDirection: [number, number, number];
   /** @todo This field is not represented in Deck.gl viewports. Can be removed in the next version */
   cameraUp: [number, number, number];
+  /** Camera target offset in meters from longitude/latitude, including elevation. */
+  position?: number[];
   longitude: number;
   latitude: number;
   bearing: number;