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

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

@@ -1,10 +1,12 @@
+// SPDX-License-Identifier: Apache-2.0
+
 // This file is derived from the Cesium code base under Apache 2 license
 // See LICENSE.md and https://github.com/AnalyticalGraphicsInc/cesium/blob/master/LICENSE.md
 
 /* eslint-disable */
 import {Quaternion, Vector3, Matrix3, Matrix4, degrees} from '@math.gl/core';
 import {BoundingSphere, OrientedBoundingBox} from '@math.gl/culling';
-import {Ellipsoid} from '@math.gl/geospatial';
+import {Ellipsoid, makeOBBFromRegion} from '@math.gl/geospatial';
 import {assert} from '@loaders.gl/loader-utils';
 
 // const scratchProjectedBoundingSphere = new BoundingSphere();
@@ -16,12 +18,7 @@ function defined(x) {
 // const scratchMatrix = new Matrix3();
 const scratchPoint = new Vector3();
 const scratchScale = new Vector3();
-const scratchNorthWest = new Vector3();
-const scratchSouthEast = new Vector3();
-const scratchCenter = new Vector3();
-const scratchXAxis = new Vector3();
-const scratchYAxis = new Vector3();
-const scratchZAxis = new Vector3();
+const identityTransform = new Matrix4();
 // const scratchRectangle = new Rectangle();
 // const scratchOrientedBoundingBox = new OrientedBoundingBox();
 // const scratchTransform = new Matrix4();
@@ -29,20 +26,39 @@ const scratchZAxis = 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 createObbFromRegion(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) {
@@ -59,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) {
@@ -146,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]);
@@ -219,52 +182,6 @@ function createSphere(sphere, transform, result?) {
   return new BoundingSphere(center, radius);
 }
 
-/**
- * Create OrientedBoundingBox instance from region 3D tiles bounding volume
- * @param region - region 3D tiles bounding volume
- * @returns OrientedBoundingBox instance
- */
-function createObbFromRegion(region: number[]): OrientedBoundingBox {
-  // [west, south, east, north, minimum height, maximum height]
-  // Latitudes and longitudes are in the WGS 84 datum as defined in EPSG 4979 and are in radians.
-  // Heights are in meters above (or below) the WGS 84 ellipsoid.
-  const [west, south, east, north, minHeight, maxHeight] = region;
-
-  const northWest = Ellipsoid.WGS84.cartographicToCartesian(
-    [degrees(west), degrees(north), minHeight],
-    scratchNorthWest
-  );
-  const southEast = Ellipsoid.WGS84.cartographicToCartesian(
-    [degrees(east), degrees(south), maxHeight],
-    scratchSouthEast
-  );
-  const centerInCartesian = new Vector3().addVectors(northWest, southEast).multiplyByScalar(0.5);
-  Ellipsoid.WGS84.cartesianToCartographic(centerInCartesian, scratchCenter);
-
-  Ellipsoid.WGS84.cartographicToCartesian(
-    [degrees(east), scratchCenter[1], scratchCenter[2]],
-    scratchXAxis
-  );
-  Ellipsoid.WGS84.cartographicToCartesian(
-    [scratchCenter[0], degrees(north), scratchCenter[2]],
-    scratchYAxis
-  );
-  Ellipsoid.WGS84.cartographicToCartesian(
-    [scratchCenter[0], scratchCenter[1], maxHeight],
-    scratchZAxis
-  );
-
-  return createBox(
-    [
-      ...centerInCartesian,
-      ...scratchXAxis.subtract(centerInCartesian),
-      ...scratchYAxis.subtract(centerInCartesian),
-      ...scratchZAxis.subtract(centerInCartesian)
-    ],
-    new Matrix4()
-  );
-}
-
 /**
  * Convert a bounding volume defined by OrientedBoundingBox to cartographic bounds
  * @returns {CartographicBounds}

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

@@ -0,0 +1,322 @@
+// 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';
+import {Ellipsoid} from '@math.gl/geospatial';
+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?
+  /** 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(),
+  new Plane(),
+  new Plane(),
+  new Plane(),
+  new Plane()
+]);
+
+/**
+ * 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 {cameraUp, height} = viewport;
+  const cameraDirection = viewport.cameraDirection as number[] | undefined;
+  const {metersPerUnit} = viewport.distanceScales;
+
+  // TODO - Ellipsoid.eastNorthUpToFixedFrame() breaks on raw array, create a Vector.
+  // TODO - Ellipsoid.eastNorthUpToFixedFrame() takes a cartesian, is that intuitive?
+  const viewportCenterCartesian = worldToCartesian(viewport, viewport.center);
+  const enuToFixedTransform = Ellipsoid.WGS84.eastNorthUpToFixedFrame(viewportCenterCartesian);
+
+  const cameraPositionCartographic = viewport.unprojectPosition(viewport.cameraPosition);
+  const cameraPositionCartesian = Ellipsoid.WGS84.cartographicToCartesian(
+    cameraPositionCartographic,
+    new Vector3()
+  );
+
+  // These should still be normalized as the transform has scale 1 (goes from meters to meters)
+  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))
+  ).normalize();
+
+  commonSpacePlanesToWGS84(viewport);
+
+  const ViewportClass = viewport.constructor;
+  const {longitude, latitude, width, bearing, zoom, position} = viewport;
+  // @ts-ignore
+  const topDownViewport = new ViewportClass({
+    longitude,
+    latitude,
+    height,
+    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,
+      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: 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)
+  };
+}
+
+/**
+ * Limit `tiles` array length with `maximumTilesSelected` number.
+ * The criteria for this filtering is distance of a tile center
+ * to the `frameState.viewport`'s longitude and latitude
+ * @param tiles - tiles array to filter
+ * @param frameState - frameState to calculate distances
+ * @param maximumTilesSelected - maximal amount of tiles in the output array
+ * @returns new tiles array
+ */
+export function limitSelectedTiles(
+  tiles: Tile3D[],
+  frameState: FrameState,
+  maximumTilesSelected: number
+): [Tile3D[], Tile3D[]] {
+  if (maximumTilesSelected === 0 || tiles.length <= maximumTilesSelected) {
+    return [tiles, []];
+  }
+  // Accumulate distances in couples array: [tileIndex: number, distanceToViewport: number]
+  const tuples: [number, number][] = [];
+  const {longitude: viewportLongitude, latitude: viewportLatitude} = frameState.viewport;
+  for (const [index, tile] of tiles.entries()) {
+    const [longitude, latitude] = tile.header.mbs;
+    const deltaLon = Math.abs(viewportLongitude - longitude);
+    const deltaLat = Math.abs(viewportLatitude - latitude);
+    const distance = Math.sqrt(deltaLat * deltaLat + deltaLon * deltaLon);
+    tuples.push([index, distance]);
+  }
+  const tuplesSorted = tuples.sort((a, b) => a[1] - b[1]);
+  const selectedTiles: Tile3D[] = [];
+  for (let i = 0; i < maximumTilesSelected; i++) {
+    selectedTiles.push(tiles[tuplesSorted[i][0]]);
+  }
+  const unselectedTiles: Tile3D[] = [];
+  for (let i = maximumTilesSelected; i < tuplesSorted.length; i++) {
+    unselectedTiles.push(tiles[tuplesSorted[i][0]]);
+  }
+
+  return [selectedTiles, unselectedTiles];
+}
+
+function commonSpacePlanesToWGS84(viewport) {
+  // Extract frustum planes based on current view.
+  const frustumPlanes = viewport.getFrustumPlanes();
+
+  // Get the near/far plane centers
+  const nearCenterCommon = closestPointOnPlane(frustumPlanes.near, viewport.cameraPosition);
+  const nearCenterCartesian = worldToCartesian(viewport, nearCenterCommon);
+  const cameraCartesian = worldToCartesian(viewport, viewport.cameraPosition, scratchPosition);
+
+  let i = 0;
+  cullingVolume.planes[i++].fromPointNormal(
+    nearCenterCartesian,
+    scratchVector.copy(nearCenterCartesian).subtract(cameraCartesian)
+  );
+
+  for (const dir in frustumPlanes) {
+    if (dir === 'near') {
+      continue; // eslint-disable-line no-continue
+    }
+    const plane = frustumPlanes[dir];
+    const posCommon = closestPointOnPlane(plane, nearCenterCommon, scratchPosition);
+    const cartesianPos = worldToCartesian(viewport, posCommon, scratchPosition);
+
+    cullingVolume.planes[i++].fromPointNormal(
+      cartesianPos,
+      // Want the normal to point into the frustum since that's what culling expects
+      scratchVector.copy(nearCenterCartesian).subtract(cartesianPos)
+    );
+  }
+}
+
+function closestPointOnPlane(
+  plane: {distance: number; normal: Vector3},
+  refPoint: number[] | Vector3,
+  out: Vector3 = new Vector3()
+): Vector3 {
+  const distanceToRef = plane.normal.dot(refPoint);
+  out
+    .copy(plane.normal)
+    .scale(plane.distance - distanceToRef)
+    .add(refPoint);
+  return out;
+}
+
+function worldToCartesian(
+  viewport: Viewport,
+  point: number[] | Vector3,
+  out: Vector3 = new Vector3()
+): Vector3 {
+  const cartographicPos = viewport.unprojectPosition(point);
+  return Ellipsoid.WGS84.cartographicToCartesian(cartographicPos, out);
+}

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

@@ -4,7 +4,7 @@
 
 import {Matrix4, Vector3} from '@math.gl/core';
 import {Ellipsoid} from '@math.gl/geospatial';
-import {Tile3D} from '../tile-3d';
+import {Tile3D} from '../common/tile-3d';
 import {FrameState} from './frame-state';
 
 const cameraPositionCartesian = new Vector3();
@@ -25,19 +25,32 @@ const cartesianToEnuMatrix = new Matrix4();
  * @returns 
  */
 export function getLodStatus(tile: Tile3D, frameState: FrameState): 'DIG' | 'OUT' | 'DRAW' {
-  if (tile.lodMetricValue === 0 || isNaN(tile.lodMetricValue)) {
+  if (tile.lodMetricValue === 0 || Number.isNaN(tile.lodMetricValue)) {
     return 'DIG';
   }
   const screenSize = 2 * getProjectedRadius(tile, frameState);
   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];
+}