@loaders.gl/tiles 4.4.5 → 5.0.0-alpha.2

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

@@ -0,0 +1,311 @@
+// 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;
+  frameNumber: number; // TODO: This can be the same between updates, what number is unique for between updates?
+  sseDenominator: number; // Assumes fovy = 60 degrees
+  /** 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.
+ *
+ * `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} = viewport;
+  // @ts-ignore
+  const topDownViewport = new ViewportClass({
+    longitude,
+    latitude,
+    height,
+    width,
+    bearing,
+    zoom,
+    pitch: 0
+  });
+
+  // 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:
+        Number.isFinite(viewport.fovy) && Number(viewport.fovy) > 0
+          ? (Number(viewport.fovy) * Math.PI) / 180
+          : Math.PI / 3,
+      timeSinceMovement: options.timeSinceCameraMovement ?? Number.POSITIVE_INFINITY
+    },
+    viewport,
+    topDownViewport,
+    height,
+    cullingVolume,
+    frameNumber, // TODO: This can be the same between updates, what number is unique for between updates?
+    sseDenominator: 1.15, // Assumes fovy = 60 degrees
+    // 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,7 +25,7 @@ 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);

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

@@ -0,0 +1,370 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+// 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
+
+import {Matrix4, Quaternion, Vector3, clamp} from '@math.gl/core';
+import {Ellipsoid} from '@math.gl/geospatial';
+import type {Tile3D} from '../common/tile-3d';
+import type {FrameState} from './frame-state';
+
+/** Options that control the perspective dynamic screen-space error optimization. */
+export type DynamicScreenSpaceErrorOptions = {
+  /** Base fog density used to reduce distant, horizon-facing screen-space error. */
+  dynamicScreenSpaceErrorDensity: number;
+  /** Maximum number of logical pixels subtracted from perspective screen-space error. */
+  dynamicScreenSpaceErrorFactor: number;
+  /** Fraction of the tileset height at which the optimization begins to fade. */
+  dynamicScreenSpaceErrorHeightFalloff: number;
+};
+
+type TileBoundingVolumeHeader = {
+  box?: number[];
+  region?: number[];
+  sphere?: number[];
+};
+
+type TilesetHeightRange = {
+  cameraHeight: number;
+  minimumHeight: number;
+  maximumHeight: number;
+  cameraDirection: Vector3;
+  upDirection: Vector3;
+};
+
+const scratchPositionNormal = new Vector3();
+const scratchCartographic = new Vector3();
+const scratchCenter = new Vector3();
+const scratchPosition = new Vector3();
+const scratchDirection = new Vector3();
+const scratchBoxXAxis = new Vector3();
+const scratchBoxYAxis = new Vector3();
+const scratchBoxZAxis = new Vector3();
+const scratchBoxQuaternion = new Quaternion();
+const unitZDirection = new Vector3(0, 0, 1);
+
+/**
+ * Refreshes the root transform before calculating transform-dependent dynamic SSE density.
+ *
+ * Traversal normally updates transforms while visiting tile visibility, but density is calculated
+ * immediately before traversal. Performing the root update at that earlier boundary keeps local
+ * box and sphere height falloff synchronized with an animated tileset model matrix in the same
+ * frame. {@link Tile3D._updateTransform} also recalculates world-space geometric error from its raw
+ * source value, so repeated calls do not compound scale.
+ *
+ * @param root - Root tile whose computed transform feeds dynamic SSE height calculations.
+ * @param modelMatrix - Current tileset-to-world transform for this frame.
+ */
+export function updateRootTransformForDynamicScreenSpaceError(
+  root: Tile3D,
+  modelMatrix: Matrix4
+): void {
+  root._updateTransform(modelMatrix);
+}
+
+/**
+ * Calculates the effective dynamic screen-space error density for one viewport and frame.
+ *
+ * Dynamic SSE is a perspective-only optimization for street-level views. It reduces refinement
+ * for distant tiles near the horizon, where loading every geometric detail is expensive and has
+ * limited visual benefit. Density fades to zero as the camera rises above the tileset or points
+ * vertically. The returned value belongs to the supplied frame state; callers must not reuse it
+ * for another viewport because camera height and direction are view dependent.
+ *
+ * @param root - Root tile whose transform and source bounding volume define the tileset space.
+ * @param frameState - Current camera measurements in WGS84 and logical viewport space.
+ * @param options - Dynamic SSE density and height-falloff controls.
+ * @returns Effective fog density for this viewport, or zero when it cannot be calculated.
+ */
+export function calculateDynamicScreenSpaceErrorDensity(
+  root: Tile3D,
+  frameState: FrameState,
+  options: DynamicScreenSpaceErrorOptions
+): number {
+  if (
+    !Number.isFinite(options.dynamicScreenSpaceErrorDensity) ||
+    options.dynamicScreenSpaceErrorDensity <= 0
+  ) {
+    return 0;
+  }
+
+  const boundingVolumeHeader = getContentBoundingVolumeHeader(root);
+  const heightRange = boundingVolumeHeader.region
+    ? getRegionHeightRange(boundingVolumeHeader.region, frameState)
+    : getCartesianHeightRange(root, boundingVolumeHeader, frameState);
+
+  if (!heightRange) {
+    return 0;
+  }
+
+  const heightFalloff = clamp(options.dynamicScreenSpaceErrorHeightFalloff, 0, 1);
+  const heightClose =
+    heightRange.minimumHeight +
+    (heightRange.maximumHeight - heightRange.minimumHeight) * heightFalloff;
+  const heightSpan = heightRange.maximumHeight - heightClose;
+  const heightPercentage =
+    heightSpan > 0
+      ? clamp((heightRange.cameraHeight - heightClose) / heightSpan, 0, 1)
+      : heightRange.cameraHeight >= heightRange.maximumHeight
+        ? 1
+        : 0;
+
+  // A horizontal view has a dot product near zero and receives the strongest optimization.
+  // A vertical view has a dot product near one and keeps the unmodified perspective SSE.
+  const verticalAlignment = clamp(
+    Math.abs(heightRange.cameraDirection.dot(heightRange.upDirection)),
+    0,
+    1
+  );
+  const horizonFactor = (1 - verticalAlignment) * (1 - heightPercentage);
+
+  return options.dynamicScreenSpaceErrorDensity * horizonFactor;
+}
+
+/**
+ * Calculates exponential fog strength for a camera distance and density.
+ * @param distanceToCamera - Distance from the camera to the tile bounding volume in meters.
+ * @param density - Effective dynamic SSE density in inverse meters.
+ * @returns Unitless strength in the inclusive range from zero to one.
+ */
+export function getDynamicScreenSpaceErrorFog(distanceToCamera: number, density: number): number {
+  const scalar = distanceToCamera * density;
+  return 1 - Math.exp(-(scalar * scalar));
+}
+
+/**
+ * Calculates the perspective SSE reduction for a tile.
+ * @param distanceToCamera - Distance from the camera to the tile bounding volume in meters.
+ * @param density - View-dependent fog density calculated for the current frame.
+ * @param factor - Maximum reduction in logical/CSS pixels.
+ * @returns Number of logical pixels to subtract from perspective SSE.
+ */
+export function getDynamicScreenSpaceError(
+  distanceToCamera: number,
+  density: number,
+  factor: number
+): number {
+  if (density <= 0 || factor <= 0 || !Number.isFinite(density) || !Number.isFinite(factor)) {
+    return 0;
+  }
+
+  return getDynamicScreenSpaceErrorFog(distanceToCamera, density) * factor;
+}
+
+/**
+ * Calculates 3D Tiles screen-space error (SSE) for the current projection.
+ *
+ * Perspective SSE projects the tile's world-space geometric error through the existing viewport
+ * height and frustum denominator. Dynamic SSE may then reduce distant horizon refinement using
+ * the density calculated specifically for this frame and viewport. Orthographic projection has
+ * no perspective distance falloff, so its error is divided directly by the viewport's world-space
+ * meters per logical pixel and is never adjusted by perspective dynamic SSE.
+ *
+ * @param tile - Tile containing the transform-scaled geometric error and camera distance.
+ * @param frameState - Current camera and viewport measurements.
+ * @param useParentLodMetric - Whether request prioritization should use the parent's error.
+ * @param viewportHeightFraction - Fraction of viewport height represented by the priority pass.
+ * @returns Estimated error in logical/CSS pixels.
+ */
+export function getTiles3DScreenSpaceError(
+  tile: Tile3D,
+  frameState: FrameState,
+  useParentLodMetric: boolean,
+  viewportHeightFraction = 1
+): number {
+  const tileset = tile.tileset;
+  const parentLodMetricValue = (tile.parent && tile.parent.lodMetricValue) || tile.lodMetricValue;
+  const lodMetricValue = useParentLodMetric ? parentLodMetricValue : tile.lodMetricValue;
+
+  // Leaf tiles do not have any error so save the computation.
+  if (lodMetricValue === 0) {
+    return 0;
+  }
+
+  const {viewDistanceScale} = tileset.options;
+  const lodScale = viewDistanceScale || 1;
+  const heightFraction = Number.isFinite(viewportHeightFraction)
+    ? Math.max(viewportHeightFraction, 0)
+    : 1;
+  const orthographicError = getOrthographicScreenSpaceError(
+    lodMetricValue,
+    frameState,
+    lodScale,
+    heightFraction
+  );
+  if (orthographicError !== null) {
+    return orthographicError;
+  }
+
+  // Avoid divide by zero when viewer is inside the tile.
+  const distanceToCamera = Math.max(tile._distanceToCamera, 1e-7);
+  const {height, sseDenominator} = frameState;
+  let screenSpaceError =
+    (lodMetricValue * height * heightFraction * lodScale) / (distanceToCamera * sseDenominator);
+
+  if (tileset.options.dynamicScreenSpaceError && !frameState.viewport.orthographic) {
+    screenSpaceError -= getDynamicScreenSpaceError(
+      distanceToCamera,
+      frameState.dynamicScreenSpaceErrorDensity,
+      tileset.options.dynamicScreenSpaceErrorFactor
+    );
+  }
+
+  return screenSpaceError;
+}
+
+/**
+ * Calculates orthographic SSE when the viewport provides a valid logical-pixel scale.
+ *
+ * deck.gl viewport dimensions and `metersPerPixel` use logical/CSS pixels. Applying the browser's
+ * device pixel ratio again would therefore double-correct the result and select different LODs on
+ * otherwise identical displays. If a structural third-party viewport does not expose a usable
+ * scale, `null` tells the caller to retain the established perspective-compatible fallback.
+ *
+ * @param lodMetricValue - Transform-scaled geometric error in world-space meters.
+ * @param frameState - Current frame state containing the viewport.
+ * @param lodScale - Application refinement scale from `viewDistanceScale`.
+ * @param viewportHeightFraction - Fraction of logical viewport height represented by the pass.
+ * @returns SSE in logical pixels, or `null` when orthographic SSE cannot be calculated.
+ */
+function getOrthographicScreenSpaceError(
+  lodMetricValue: number,
+  frameState: FrameState,
+  lodScale: number,
+  viewportHeightFraction: number
+): number | null {
+  const viewport = frameState.viewport;
+  if (!viewport?.orthographic) {
+    return null;
+  }
+
+  const metersPerPixel = viewport.metersPerPixel;
+  if (!Number.isFinite(metersPerPixel) || !metersPerPixel || metersPerPixel <= 0) {
+    return null;
+  }
+
+  return (lodMetricValue * lodScale * viewportHeightFraction) / metersPerPixel;
+}
+
+/** Returns the content bounding volume header, falling back to the traversal volume. */
+function getContentBoundingVolumeHeader(root: Tile3D): TileBoundingVolumeHeader {
+  return root.header.content?.boundingVolume || root.header.boundingVolume;
+}
+
+/** Calculates camera and tileset heights for a geodetic region bounding volume. */
+function getRegionHeightRange(region: number[], frameState: FrameState): TilesetHeightRange {
+  const upDirection = scratchPositionNormal.copy(frameState.camera.position).normalize();
+  const cameraDirection = scratchDirection.copy(frameState.camera.direction).normalize();
+
+  return {
+    cameraHeight: frameState.camera.cartographicPosition[2],
+    minimumHeight: region[4],
+    maximumHeight: region[5],
+    cameraDirection,
+    upDirection
+  };
+}
+
+/**
+ * Calculates camera and tileset heights for box and sphere volumes.
+ *
+ * The root transform is inverted so that both camera height and source volume dimensions use the
+ * same coordinate system. Small coordinates are treated as local z-up. Earth-scale coordinates
+ * are treated as WGS84 and use cartographic height, matching Cesium's conservative approximation.
+ */
+function getCartesianHeightRange(
+  root: Tile3D,
+  boundingVolumeHeader: TileBoundingVolumeHeader,
+  frameState: FrameState
+): TilesetHeightRange | null {
+  const halfHeight = getBoundingVolumeCenterAndHalfHeight(boundingVolumeHeader, scratchCenter);
+  if (halfHeight === null) {
+    return null;
+  }
+
+  const localTransform = new Matrix4(root.computedTransform).invert();
+  const ellipsoid = root.tileset.ellipsoid as Ellipsoid;
+  const centerMagnitude = Math.hypot(scratchCenter[0], scratchCenter[1], scratchCenter[2]);
+
+  if (centerMagnitude > ellipsoid.minimumRadius) {
+    const centerCartographic = ellipsoid.cartesianToCartographic(
+      scratchCenter,
+      scratchCartographic
+    );
+    const upDirection = scratchPositionNormal.copy(frameState.camera.position).normalize();
+    const cameraDirection = scratchDirection.copy(frameState.camera.direction).normalize();
+
+    return {
+      cameraHeight: frameState.camera.cartographicPosition[2],
+      minimumHeight: 0,
+      maximumHeight: centerCartographic[2] * 2,
+      cameraDirection,
+      upDirection
+    };
+  }
+
+  localTransform.transformAsPoint(frameState.camera.position, scratchPosition);
+  localTransform.transformAsVector(frameState.camera.direction, scratchDirection);
+  scratchDirection.normalize();
+
+  return {
+    cameraHeight: scratchPosition[2],
+    minimumHeight: scratchCenter[2] - halfHeight,
+    maximumHeight: scratchCenter[2] + halfHeight,
+    cameraDirection: scratchDirection,
+    upDirection: unitZDirection
+  };
+}
+
+/**
+ * Copies the source volume center and returns its conservative z-up half-height.
+ * @param boundingVolumeHeader - Root content or traversal volume from tileset JSON.
+ * @param result - Scratch vector that receives the source-space center.
+ * @returns Half-height in source-space meters, or `null` for an unsupported volume.
+ */
+function getBoundingVolumeCenterAndHalfHeight(
+  boundingVolumeHeader: TileBoundingVolumeHeader,
+  result: Vector3
+): number | null {
+  if (boundingVolumeHeader.box) {
+    const box = boundingVolumeHeader.box;
+    result.set(box[0], box[1], box[2]);
+    return getBoxHalfHeight(box);
+  }
+
+  if (boundingVolumeHeader.sphere) {
+    const sphere = boundingVolumeHeader.sphere;
+    result.set(sphere[0], sphere[1], sphere[2]);
+    return sphere[3];
+  }
+
+  return null;
+}
+
+/**
+ * Returns the conservative source-z extent of an oriented box.
+ *
+ * A 12-component 3D Tiles box stores three half-axis vectors, so every vector can contribute to
+ * vertical height after rotation. The alternate 10-component representation stores half sizes and
+ * a quaternion; rotating its three scaled basis vectors produces the same sum of absolute z
+ * projections. Using only the nominal z axis would underestimate tilted volumes and fade dynamic
+ * SSE too early while the camera is still within the tileset's height range.
+ *
+ * @param box - Source-space oriented box in half-axis or half-size/quaternion form.
+ * @returns Conservative source-z half-height in the box coordinate system's distance units.
+ */
+function getBoxHalfHeight(box: number[]): number {
+  if (box.length === 10) {
+    scratchBoxQuaternion.fromArray(box, 6);
+    scratchBoxXAxis.set(box[3], 0, 0).transformByQuaternion(scratchBoxQuaternion);
+    scratchBoxYAxis.set(0, box[4], 0).transformByQuaternion(scratchBoxQuaternion);
+    scratchBoxZAxis.set(0, 0, box[5]).transformByQuaternion(scratchBoxQuaternion);
+    return (
+      Math.abs(scratchBoxXAxis[2]) + Math.abs(scratchBoxYAxis[2]) + Math.abs(scratchBoxZAxis[2])
+    );
+  }
+
+  return Math.abs(box[5]) + Math.abs(box[8]) + Math.abs(box[11]);
+}