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

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

@@ -1,3 +1,7 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
 import type {Tile3D} from '../common/tile-3d';
 import {Vector3} from '@math.gl/core';
 import {CullingVolume, Plane} from '@math.gl/culling';
@@ -6,20 +10,60 @@ import {GeospatialViewport, Viewport} from '../../types';
 
 export type FrameState = {
   camera: {
+    /** Camera position in WGS84 Cartesian meters. */
     position: number[];
+    /** Normalized camera direction in WGS84 Cartesian coordinates. */
     direction: number[];
+    /** Normalized camera up direction in WGS84 Cartesian coordinates. */
     up: number[];
+    /** Camera position as `[longitude, latitude, height]`, with height in meters. */
+    cartographicPosition: [number, number, number];
+    /** Perspective vertical field of view in radians. */
+    verticalFieldOfView: number;
+    /** Elapsed seconds since camera position or direction last changed. */
+    timeSinceMovement: number;
   };
   viewport: GeospatialViewport;
   topDownViewport: GeospatialViewport; // Use it to calculate projected radius for a tile
   height: number;
   cullingVolume: CullingVolume;
+  /** 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;
+};
+
+/** Optional camera and projection measurements supplied when constructing a frame state. */
+export type GetFrameStateOptions = {
+  /** Elapsed seconds since camera position or direction last changed. */
+  timeSinceCameraMovement?: number;
+};
+
+/** Camera pose and timestamp retained between traversal frames. */
+export type CameraMotionState = {
+  /** Last observed Earth-centered, Earth-fixed camera position. */
+  position: number[];
+  /** Last observed normalized Earth-centered, Earth-fixed camera direction. */
+  direction: number[];
+  /** Timestamp in milliseconds of the last observed pose change. */
+  lastMovementTime: number;
+};
+
+/** Updated camera state and elapsed stationary time for a traversal frame. */
+export type CameraMotionUpdate = {
+  /** Camera pose to retain for the next traversal. */
+  state: CameraMotionState;
+  /** Elapsed seconds since the camera pose last changed. */
+  timeSinceMovement: number;
 };
 
 const scratchVector = new Vector3();
 const scratchPosition = new Vector3();
+const CAMERA_POSITION_EPSILON = 1e-5;
+const CAMERA_DIRECTION_EPSILON = 1e-7;
 const cullingVolume = new CullingVolume([
   new Plane(),
   new Plane(),
@@ -29,12 +73,30 @@ const cullingVolume = new CullingVolume([
   new Plane()
 ]);
 
-// Extracts a frame state appropriate for tile culling from a deck.gl viewport
-// TODO - this could likely be generalized and merged back into deck.gl for other culling scenarios
-export function getFrameState(viewport: GeospatialViewport, frameNumber: number): FrameState {
+/**
+ * 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.
+ *
+ * @param viewport - Geospatial viewport supplying camera and projection measurements.
+ * @param frameNumber - Current tileset traversal frame number.
+ * @param options - Additional camera and projection measurements for traversal.
+ * @returns Frame state used for visibility, SSE, and request-priority calculations.
+ */
+export function getFrameState(
+  viewport: GeospatialViewport,
+  frameNumber: number,
+  options: GetFrameStateOptions = {}
+): FrameState {
   // Traverse and and request. Update _selectedTiles so that we know what to render.
   // Traverse and and request. Update _selectedTiles so that we know what to render.
-  const {cameraDirection, cameraUp, height} = viewport;
+  const {cameraUp, height} = viewport;
+  const cameraDirection = viewport.cameraDirection as number[] | undefined;
   const {metersPerUnit} = viewport.distanceScales;
 
   // TODO - Ellipsoid.eastNorthUpToFixedFrame() breaks on raw array, create a Vector.
@@ -49,10 +111,26 @@ export function getFrameState(viewport: GeospatialViewport, frameNumber: number)
   );
 
   // These should still be normalized as the transform has scale 1 (goes from meters to meters)
-  const cameraDirectionCartesian = new Vector3(
-    // @ts-ignore
-    enuToFixedTransform.transformAsVector(new Vector3(cameraDirection).scale(metersPerUnit))
-  ).normalize();
+  let cameraDirectionCartesian: Vector3;
+  if (cameraDirection) {
+    cameraDirectionCartesian = new Vector3(
+      // @ts-ignore
+      enuToFixedTransform.transformAsVector(new Vector3(cameraDirection).scale(metersPerUnit))
+    ).normalize();
+  } else {
+    // Concrete deck.gl viewports do not expose the legacy structural cameraDirection field.
+    // The near-plane center is on the view axis, so its world-space direction is equivalent and
+    // works for perspective foveation without coupling loaders.gl to deck.gl internals.
+    // getFrustumPlanes is required by traversal but omitted from the minimal structural Viewport
+    // type for compatibility with existing application-side declarations.
+    // @ts-expect-error Runtime geospatial viewports provide getFrustumPlanes.
+    const nearPlane = viewport.getFrustumPlanes().near;
+    const nearCenterCommon = closestPointOnPlane(nearPlane, viewport.cameraPosition);
+    const nearCenterCartesian = worldToCartesian(viewport, nearCenterCommon);
+    cameraDirectionCartesian = new Vector3(nearCenterCartesian)
+      .subtract(cameraPositionCartesian)
+      .normalize();
+  }
   const cameraUpCartesian = new Vector3(
     // @ts-ignore
     enuToFixedTransform.transformAsVector(new Vector3(cameraUp).scale(metersPerUnit))
@@ -61,7 +139,7 @@ export function getFrameState(viewport: GeospatialViewport, frameNumber: number)
   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,
@@ -70,22 +148,83 @@ export function getFrameState(viewport: GeospatialViewport, frameNumber: number)
     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: {
       position: cameraPositionCartesian,
       direction: cameraDirectionCartesian,
-      up: cameraUpCartesian
+      up: cameraUpCartesian,
+      cartographicPosition: cameraPositionCartographic,
+      verticalFieldOfView,
+      timeSinceMovement: options.timeSinceCameraMovement ?? Number.POSITIVE_INFINITY
     },
     viewport,
     topDownViewport,
     height,
     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
+  };
+}
+
+/**
+ * Updates retained camera motion state and calculates how long the current pose has been stable.
+ *
+ * The first observation is treated as stationary so initial tileset loading is never delayed.
+ * Position and direction are both compared because orbiting in place changes request relevance
+ * without necessarily changing the viewport's camera position.
+ *
+ * @param previousState - Pose retained from the preceding traversal for this viewport.
+ * @param position - Current Earth-centered, Earth-fixed camera position.
+ * @param direction - Current normalized Earth-centered, Earth-fixed camera direction.
+ * @param currentTime - Current monotonic-enough wall-clock time in milliseconds.
+ * @returns Updated pose and elapsed stationary time.
+ */
+export function updateCameraMotionState(
+  previousState: CameraMotionState | undefined,
+  position: number[] | Vector3,
+  direction: number[] | Vector3,
+  currentTime: number
+): CameraMotionUpdate {
+  const positionArray = Array.from(position);
+  const directionArray = Array.from(direction);
+  const positionChanged = previousState
+    ? positionArray.length !== previousState.position.length ||
+      positionArray.some(
+        (value, index) => Math.abs(value - previousState.position[index]) > CAMERA_POSITION_EPSILON
+      )
+    : false;
+  const directionChanged = previousState
+    ? directionArray.length !== previousState.direction.length ||
+      directionArray.some(
+        (value, index) =>
+          Math.abs(value - previousState.direction[index]) > CAMERA_DIRECTION_EPSILON
+      )
+    : false;
+  const lastMovementTime =
+    positionChanged || directionChanged
+      ? currentTime
+      : (previousState?.lastMovementTime ?? Number.NEGATIVE_INFINITY);
+
+  return {
+    state: {
+      position: positionArray,
+      direction: directionArray,
+      lastMovementTime
+    },
+    timeSinceMovement: Math.max((currentTime - lastMovementTime) / 1000, 0)
   };
 }
 
@@ -162,7 +301,7 @@ function commonSpacePlanesToWGS84(viewport) {
 
 function closestPointOnPlane(
   plane: {distance: number; normal: Vector3},
-  refPoint: [number, number, number] | Vector3,
+  refPoint: number[] | Vector3,
   out: Vector3 = new Vector3()
 ): Vector3 {
   const distanceToRef = plane.normal.dot(refPoint);

package/src/tileset-3d/helpers/i3s-lod.ts

@@ -32,12 +32,25 @@ export function getLodStatus(tile: Tile3D, frameState: FrameState): 'DIG' | 'OUT
   if (screenSize < 2) {
     return 'OUT';
   }
-  if (!tile.header.children || screenSize <= tile.lodMetricValue) {
+  if (!tile.header.children) {
     return 'DRAW';
-  } else if (tile.header.children) {
-    return 'DIG';
   }
-  return 'OUT';
+
+  switch (tile.lodMetricType) {
+    case 'screenSpaceRelative': {
+      const viewportHeight = frameState.topDownViewport.height || 1;
+      return screenSize / viewportHeight <= tile.lodMetricValue ? 'DRAW' : 'DIG';
+    }
+    case 'distanceRangeFromDefaultCamera':
+      return tile.distanceToTile(frameState) >= tile.lodMetricValue ? 'DRAW' : 'DIG';
+    case 'maxScreenThresholdSQ': {
+      const diameterThreshold = Math.sqrt(tile.lodMetricValue / (Math.PI * 0.25));
+      return screenSize <= diameterThreshold ? 'DRAW' : 'DIG';
+    }
+    case 'maxScreenThreshold':
+    default:
+      return screenSize <= tile.lodMetricValue ? 'DRAW' : 'DIG';
+  }
 }
 
 /**
@@ -49,10 +62,11 @@ export function getLodStatus(tile: Tile3D, frameState: FrameState): 'DIG' | 'OUT
 // eslint-disable-next-line max-statements
 export function getProjectedRadius(tile: Tile3D, frameState: FrameState): number {
   const {topDownViewport: viewport} = frameState;
-  const mbsLat = tile.header.mbs[1];
-  const mbsLon = tile.header.mbs[0];
-  const mbsZ = tile.header.mbs[2];
-  const mbsR = tile.header.mbs[3];
+  const mbs = tile.header.i3sLodMbs || tile.header.mbs;
+  const mbsLat = mbs[1];
+  const mbsLon = mbs[0];
+  const mbsZ = mbs[2];
+  const mbsR = mbs[3];
   const mbsCenterCartesian = [...tile.boundingVolume.center];
   const cameraPositionCartographic = viewport.unprojectPosition(viewport.cameraPosition);
   Ellipsoid.WGS84.cartographicToCartesian(cameraPositionCartographic, cameraPositionCartesian);

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];
+}