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

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

@@ -8,10 +8,12 @@ import {Vector3} from '@math.gl/core';
 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 type {Tile3DContent} from '../common/tile-3d-contracts';
 import {I3STilesetTraverser} from './i3s-tileset-traverser';
 import type {Tileset3D} from '../common/tileset-3d';
 import type {FrameState} from '../helpers/frame-state';
 import type {
+  TileChildrenLoadResult,
   TileContentLoadResult,
   TilesetContentFormats,
   TilesetJSON,
@@ -219,7 +221,17 @@ export class I3SSource implements Tileset3DSource {
     };
 
     tile.content = await this.loadResourceData(contentUrl, options, this.contentLoader);
-    return {loaded: true};
+    const contentEntry: Tile3DContent = {
+      index: 0,
+      uri: tile.contentUrl,
+      type: tile.header.layerType,
+      payload: tile.content,
+      metadata: tile.header.metadata || null,
+      boundingVolume: tile.boundingVolume,
+      featureIds: tile.featureIdSets,
+      renderable: Boolean(tile.content)
+    };
+    return {loaded: true, contents: [tile.content], contentEntries: [contentEntry]};
   }
 
   /**
@@ -228,7 +240,7 @@ export class I3SSource implements Tileset3DSource {
   async loadChildTileHeader(
     _parentTile: Tile3D,
     childId: string,
-    _frameState: FrameState
+    _frameState: FrameState | null
   ): Promise<any> {
     const metadata = this.getMetadata();
     if (metadata.tileset.nodePages || metadata.tileset.pointNodePages) {
@@ -253,6 +265,50 @@ export class I3SSource implements Tileset3DSource {
     return await this.transformTileHeader(header);
   }
 
+  /** Loads all declared I3S child headers without camera or visibility state. */
+  async loadTileChildrenForTraversal(
+    parentTile: Tile3D,
+    signal?: AbortSignal
+  ): Promise<TileChildrenLoadResult> {
+    const childHeaders = parentTile.header.children || [];
+    let loadedChildren = 0;
+    const orderedChildren: Tile3D[] = [];
+
+    for (const childHeader of childHeaders) {
+      throwIfTraversalAborted(signal);
+      const childId = childHeader.id;
+      if (typeof childId !== 'string' && typeof childId !== 'number') {
+        throw new Error('I3S child header is missing its node ID');
+      }
+      const existingChild = parentTile.children.find(
+        tile => tile.id === String(childId) || tile.header?.id === childId
+      );
+      if (existingChild) {
+        orderedChildren.push(existingChild);
+        continue;
+      }
+
+      const childTileHeader = await this.loadChildTileHeader(parentTile, String(childId), null);
+      throwIfTraversalAborted(signal);
+      const childTile = new Tile3DNode(
+        parentTile.tileset,
+        childTileHeader,
+        parentTile,
+        String(childId)
+      );
+      orderedChildren.push(childTile);
+      loadedChildren++;
+    }
+
+    const orderedChildSet = new Set(orderedChildren);
+    parentTile.children = [
+      ...orderedChildren,
+      ...parentTile.children.filter(childTile => !orderedChildSet.has(childTile))
+    ];
+
+    return {loaded: true, tileCount: loadedChildren, childSubtreeCount: 0};
+  }
+
   /**
    * Resolves an I3S request URL with source-managed query parameters.
    */
@@ -265,24 +321,28 @@ export class I3SSource implements Tileset3DSource {
       return tilePath;
     }
 
-    const queryDelimiterIndex = tilePath.indexOf('?');
-    if (queryDelimiterIndex === -1) {
-      return `${tilePath}?${new URLSearchParams(this.queryParams).toString()}`;
-    }
-
-    const existingQuery = tilePath.slice(queryDelimiterIndex + 1);
-    const existingQueryKeys = new Set(
-      existingQuery.split('&').map(parameter => parameter.split('=', 1)[0])
-    );
+    const hashIndex = tilePath.indexOf('#');
+    const hash = hashIndex >= 0 ? tilePath.slice(hashIndex) : '';
+    const tilePathWithoutHash = hashIndex >= 0 ? tilePath.slice(0, hashIndex) : tilePath;
+    const queryDelimiterIndex = tilePathWithoutHash.indexOf('?');
+    const path =
+      queryDelimiterIndex === -1
+        ? tilePathWithoutHash
+        : tilePathWithoutHash.slice(0, queryDelimiterIndex);
+    const existingQuery =
+      queryDelimiterIndex === -1 ? '' : tilePathWithoutHash.slice(queryDelimiterIndex + 1);
+    const existingQueryParams = new URLSearchParams(existingQuery);
     const queryParams = new URLSearchParams();
     for (const [key, value] of Object.entries(this.queryParams)) {
-      if (!existingQueryKeys.has(key)) {
+      if (!existingQueryParams.has(key)) {
         queryParams.set(key, value);
       }
     }
 
     const queryString = queryParams.toString();
-    return queryString ? `${tilePath}${existingQuery ? '&' : ''}${queryString}` : tilePath;
+    return `${path}${existingQuery ? `?${existingQuery}` : ''}${
+      queryString ? `${existingQuery ? '&' : '?'}${queryString}` : ''
+    }${hash}`;
   }
 
   /**
@@ -403,6 +463,10 @@ export class I3SSource implements Tileset3DSource {
    * @param loadOptions Loader options that may contain an ArcGIS token.
    */
   private initializeQueryParams(loadOptions: LoaderOptions): void {
+    for (const [key, value] of Object.entries(loadOptions.searchParams || {})) {
+      this.queryParams[key] = String(value);
+    }
+
     const i3sOptions = loadOptions.i3s;
     if (i3sOptions && typeof i3sOptions === 'object' && 'token' in i3sOptions) {
       const token = (i3sOptions as Record<string, unknown>).token;
@@ -449,6 +513,13 @@ export class I3SSource implements Tileset3DSource {
   }
 }
 
+/** Throws a cancellation reason before or after source-managed traversal work. */
+function throwIfTraversalAborted(signal?: AbortSignal): void {
+  if (signal?.aborted) {
+    throw signal.reason ?? new DOMException('The operation was aborted', 'AbortError');
+  }
+}
+
 /** 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;

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

@@ -38,7 +38,8 @@ export class I3STilesetTraverser extends TilesetTraverser {
     for (const child of children) {
       const extendedId = `${child.id}-${frameState.viewport.id}`;
       // if child tile is not fetched
-      const childTile = childTiles && childTiles.find(t => t.id === extendedId);
+      const childTile =
+        childTiles && childTiles.find(t => t.id === extendedId || t.header?.id === child.id);
       if (!childTile) {
         const request = () => this._loadTile(tile, child.id, frameState);
         const cachedRequest = this._tileManager.find(extendedId);

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

@@ -30,7 +30,8 @@ export type FrameState = {
   /** Optional world-space clipping planes applied to render-content culling. */
   clippingPlanes?: Plane[];
   frameNumber: number; // TODO: This can be the same between updates, what number is unique for between updates?
-  sseDenominator: number; // Assumes fovy = 60 degrees
+  /** Perspective projection factor: twice the tangent of half the vertical field of view. */
+  sseDenominator: number;
   /** View-dependent density used by perspective dynamic screen-space error for this traversal. */
   dynamicScreenSpaceErrorDensity: number;
 };
@@ -75,6 +76,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 +139,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,9 +148,15 @@ export function getFrameState(
     width,
     bearing,
     zoom,
+    position,
     pitch: 0
   });
 
+  const verticalFieldOfView =
+    Number.isFinite(viewport.fovy) && Number(viewport.fovy) > 0 && Number(viewport.fovy) < 180
+      ? (Number(viewport.fovy) * Math.PI) / 180
+      : Math.PI / 3;
+
   // TODO: make a file/class for frameState and document what needs to be attached to this so that traversal can function
   return {
     camera: {
@@ -153,10 +164,7 @@ export function getFrameState(
       direction: cameraDirectionCartesian,
       up: cameraUpCartesian,
       cartographicPosition: cameraPositionCartographic,
-      verticalFieldOfView:
-        Number.isFinite(viewport.fovy) && Number(viewport.fovy) > 0
-          ? (Number(viewport.fovy) * Math.PI) / 180
-          : Math.PI / 3,
+      verticalFieldOfView,
       timeSinceMovement: options.timeSinceCameraMovement ?? Number.POSITIVE_INFINITY
     },
     viewport,
@@ -165,7 +173,7 @@ export function getFrameState(
     cullingVolume,
     clippingPlanes: viewport.clippingPlanes,
     frameNumber, // TODO: This can be the same between updates, what number is unique for between updates?
-    sseDenominator: 1.15, // Assumes fovy = 60 degrees
+    sseDenominator: 2 * Math.tan(verticalFieldOfView / 2),
     // Tileset3D fills this immediately before traversal because it depends on the root volume.
     dynamicScreenSpaceErrorDensity: 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;