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

package/dist/tileset-3d/common/tileset-3d.d.ts

@@ -2,7 +2,8 @@ import { Matrix4, Vector3 } from '@math.gl/core';
 import { Stats } from '@probe.gl/stats';
 import { RequestScheduler, LoaderWithParser, LoaderOptions } from '@loaders.gl/loader-utils';
 import { TilesetCache } from "./tileset-cache.js";
-import { FrameState } from "../helpers/frame-state.js";
+import type { FrameState } from "../helpers/frame-state.js";
+import type { FoveatedInterpolationCallback } from "../helpers/tiles-3d-request-priority.js";
 import type { Viewport } from "../../types.js";
 import { Tile3D } from "./tile-3d.js";
 import { TILESET_TYPE } from "../../constants.js";
@@ -15,7 +16,28 @@ export type Tileset3DProps = {
     loadOptions?: LoaderOptions;
     loadTiles?: boolean;
     basePath?: string;
+    /**
+     * Soft target, in bytes, for cached tile content that is not required by the current frame.
+     * The listed default applies to 3D Tiles; I3S retains its existing 32 MiB default.
+     * @default 536870912
+     */
+    cacheBytes?: number;
+    /**
+     * Additional bytes that the current-frame working set may use before memory-adjusted SSE rises.
+     * The listed default applies to 3D Tiles; I3S retains its existing 1 MiB default.
+     * @default 536870912
+     */
+    maximumCacheOverflowBytes?: number;
+    /**
+     * Soft cache target in mebibytes.
+     * @deprecated Use {@link Tileset3DProps.cacheBytes}; when both are supplied, `cacheBytes` wins.
+     */
     maximumMemoryUsage?: number;
+    /**
+     * Cache overflow headroom in mebibytes.
+     * @deprecated Use {@link Tileset3DProps.maximumCacheOverflowBytes}; when both are supplied, the
+     * byte-native option wins.
+     */
     memoryCacheOverflow?: number;
     maximumTilesSelected?: number;
     debounceTime?: number;
@@ -24,10 +46,34 @@ export type Tileset3DProps = {
     ellipsoid?: object;
     modelMatrix?: Matrix4;
     maximumScreenSpaceError?: number;
+    /** Enables perspective dynamic SSE to reduce distant, horizon-facing refinement. */
+    dynamicScreenSpaceError?: boolean;
+    /** Base dynamic SSE fog density in inverse meters. */
+    dynamicScreenSpaceErrorDensity?: number;
+    /** Maximum dynamic SSE reduction in logical/CSS pixels. */
+    dynamicScreenSpaceErrorFactor?: number;
+    /** Fraction of tileset height at which dynamic SSE begins to fade, clamped to `[0, 1]`. */
+    dynamicScreenSpaceErrorHeightFalloff?: number;
+    /**
+     * Enables adaptive LOD reduction when estimated tile memory exceeds the overflow ceiling.
+     * Defaults to `true` for 3D Tiles and retains the existing `false` default for I3S.
+     */
     memoryAdjustedScreenSpaceError?: boolean;
     viewportTraversersMap?: any;
     updateTransforms?: boolean;
     viewDistanceScale?: number;
+    /** Reduced viewport-height fraction used to prioritize coarse initial coverage; `0` disables it. */
+    progressiveResolutionHeightFraction?: number;
+    /** Whether requests nearer the center of a perspective viewport receive higher priority. */
+    foveatedScreenSpaceError?: boolean;
+    /** Fraction of the perspective field of view that receives no foveated SSE relaxation. */
+    foveatedConeSize?: number;
+    /** Minimum logical-pixel SSE relaxation immediately outside the foveated cone. */
+    foveatedMinimumScreenSpaceErrorRelaxation?: number;
+    /** Function that increases SSE relaxation from the foveated cone toward the viewport edge. */
+    foveatedInterpolationCallback?: FoveatedInterpolationCallback;
+    /** Seconds peripheral requests may wait after the camera moves. */
+    foveatedTimeDelay?: number;
     onTileLoad?: (tile: Tile3D) => any;
     onTileUnload?: (tile: Tile3D) => any;
     onTileError?: (tile: Tile3D, message: string, url: string) => any;
@@ -45,7 +91,13 @@ type Props = {
     modelMatrix: Matrix4;
     throttleRequests: boolean;
     maxRequests: number;
+    /** Soft target, in bytes, for evictable cached tile content. */
+    cacheBytes: number;
+    /** Current-frame headroom, in bytes, before memory-adjusted SSE rises. */
+    maximumCacheOverflowBytes: number;
+    /** @deprecated Byte-native code should use `cacheBytes`. */
     maximumMemoryUsage: number;
+    /** @deprecated Byte-native code should use `maximumCacheOverflowBytes`. */
     memoryCacheOverflow: number;
     maximumTilesSelected: number;
     debounceTime: number;
@@ -57,6 +109,15 @@ type Props = {
     onTraversalComplete: (selectedTiles: Tile3D[]) => Tile3D[];
     onUpdate: () => void;
     maximumScreenSpaceError: number;
+    /** Whether perspective dynamic SSE is enabled. */
+    dynamicScreenSpaceError: boolean;
+    /** Base dynamic SSE fog density in inverse meters. */
+    dynamicScreenSpaceErrorDensity: number;
+    /** Maximum dynamic SSE reduction in logical/CSS pixels. */
+    dynamicScreenSpaceErrorFactor: number;
+    /** Fraction of tileset height at which dynamic SSE begins to fade. */
+    dynamicScreenSpaceErrorHeightFalloff: number;
+    /** Whether cache pressure may adapt the active SSE threshold. */
     memoryAdjustedScreenSpaceError: boolean;
     viewportTraversersMap: Record<string, any> | null;
     attributions: string[];
@@ -64,6 +125,18 @@ type Props = {
     loadOptions: LoaderOptions;
     updateTransforms: boolean;
     viewDistanceScale: number;
+    /** Reduced viewport-height fraction used to prioritize coarse initial coverage. */
+    progressiveResolutionHeightFraction: number;
+    /** Whether perspective requests are prioritized around the viewport center. */
+    foveatedScreenSpaceError: boolean;
+    /** Fraction of the perspective field of view with no foveated SSE relaxation. */
+    foveatedConeSize: number;
+    /** Minimum logical-pixel SSE relaxation outside the foveated cone. */
+    foveatedMinimumScreenSpaceErrorRelaxation: number;
+    /** Function used to interpolate foveated SSE relaxation. */
+    foveatedInterpolationCallback: FoveatedInterpolationCallback;
+    /** Seconds eligible peripheral requests wait after camera movement. */
+    foveatedTimeDelay: number;
     basePath: string;
     contentLoader?: (tile: Tile3D) => Promise<void>;
     i3s: Record<string, any>;
@@ -102,12 +175,14 @@ export declare class Tileset3D {
     cartesianCenter: Vector3 | null;
     zoom: number;
     boundingVolume: any;
+    /** Effective dynamic SSE density calculated for the most recently traversed viewport. */
     dynamicScreenSpaceErrorComputedDensity: number;
-    maximumMemoryUsage: number;
+    /** Estimated bytes currently retained by loaded tile content. */
     gpuMemoryUsageInBytes: number;
+    /** Active SSE threshold after optional cache-pressure adjustment, in logical/CSS pixels. */
     memoryAdjustedScreenSpaceError: number;
     private _cacheBytes;
-    private _cacheOverflowBytes;
+    private _maximumCacheOverflowBytes;
     _frameNumber: number;
     private _tiles;
     private _pendingCount;
@@ -118,6 +193,10 @@ export declare class Tileset3D {
     private _requestedTiles;
     private _emptyTiles;
     private frameStateData;
+    /** Last camera pose retained independently for each viewport. */
+    private _cameraMotionStates;
+    /** Pending traversal that releases requests after camera motion settles. */
+    private _deferredTraversalTimeout;
     _traverser: TilesetTraverser;
     _cache: TilesetCache;
     _requestScheduler: RequestScheduler;
@@ -134,14 +213,65 @@ export declare class Tileset3D {
     isLoaded(): boolean;
     get tiles(): object[];
     get frameNumber(): number;
+    /**
+     * Gets or sets the soft target, in bytes, for cached tile content not needed this frame.
+     *
+     * Current-frame tiles remain protected even when their estimated memory exceeds this target.
+     * Reducing the value makes unused least-recently-used tiles eligible for eviction on the next
+     * traversal.
+     * @default 536870912 for 3D Tiles; 33554432 for I3S
+     */
+    get cacheBytes(): number;
+    set cacheBytes(value: number);
+    /**
+     * Gets or sets the additional current-frame headroom, in bytes, before memory-adjusted SSE rises.
+     *
+     * The pressure ceiling is `cacheBytes + maximumCacheOverflowBytes`. This value does not change
+     * the base target used to evict tiles that were not touched in the current frame.
+     * @default 536870912 for 3D Tiles; 1048576 for I3S
+     */
+    get maximumCacheOverflowBytes(): number;
+    set maximumCacheOverflowBytes(value: number);
+    /**
+     * Gets or sets the soft cache target in mebibytes.
+     * @deprecated Use {@link Tileset3D.cacheBytes}. Assignments remain synchronized for compatibility.
+     */
+    get maximumMemoryUsage(): number;
+    set maximumMemoryUsage(value: number);
     get queryParams(): string;
+    /**
+     * Updates traversal and runtime options, synchronizing byte-native and deprecated cache values.
+     *
+     * For each budget, the byte-native option takes precedence when both unit forms are supplied.
+     * Unspecified budgets retain their current byte values, avoiding repeated MiB conversion.
+     *
+     * @param props - Partial runtime options to apply.
+     */
     setProps(props: Tileset3DProps): void;
     getTileUrl(tilePath: string): string;
     hasExtension(extensionName: string): boolean;
     update(viewports?: Viewport[] | Viewport | null): void;
     selectTiles(viewports?: Viewport[] | Viewport | null): Promise<number>;
+    /**
+     * Moves the active LOD threshold toward the configured SSE or away from cache pressure.
+     *
+     * Usage below {@link Tileset3D.cacheBytes} restores quality in two-percent steps. Usage above
+     * `cacheBytes + maximumCacheOverflowBytes` reduces refinement in two-percent steps. Values in
+     * the overflow window leave the threshold unchanged, preventing rapid load/evict oscillation.
+     */
     adjustScreenSpaceError(): void;
     private doUpdate;
+    /**
+     * Schedules one follow-up traversal when the moving-camera deferral window expires.
+     *
+     * Replacing an existing timer ensures continuing camera movement pushes the retry window forward
+     * instead of creating a queue of redundant traversals.
+     *
+     * @param delayInSeconds - Remaining stationary delay before deferred requests become eligible.
+     */
+    private _scheduleDeferredTraversal;
+    /** Clears a pending moving-camera follow-up traversal. */
+    private _clearDeferredTraversal;
     _needTraverse(viewportId: string): boolean;
     _onTraversalEnd(frameState: FrameState): void;
     _updateTiles(): void;
@@ -155,6 +285,16 @@ export declare class Tileset3D {
     _initializeTraverser(): TilesetTraverser;
     _destroyTileHeaders(parentTile: Tile3D): void;
     _loadTile(tile: Tile3D): Promise<void>;
+    /**
+     * Loads a source-managed lazy child-header group and reports failures through tile callbacks.
+     *
+     * Subtree metadata shares the normal loading counters but is not reported as render content and
+     * is not added to the GPU cache. Traversal is notified separately after the promise settles.
+     *
+     * @param tile - Runtime tile that owns the lazy subtree reference.
+     * @param frameState - View state that made the subtree eligible for refinement.
+     */
+    _loadTileChildren(tile: Tile3D, frameState: FrameState): Promise<void>;
     _onTileLoadError(tile: Tile3D, error: Error): void;
     _onSourceError(error: Error, tile?: Tile3D | null): void;
     _onTilesetError(error: Error): void;

package/dist/tileset-3d/common/tileset-3d.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tileset-3d.d.ts","sourceRoot":"","sources":["../../../src/tileset-3d/common/tileset-3d.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"tileset-3d.d.ts","sourceRoot":"","sources":["../../../src/tileset-3d/common/tileset-3d.ts"],"names":[],"mappings":"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"}

package/dist/tileset-3d/common/tileset-3d.js

@@ -8,16 +8,76 @@ import { Stats } from '@probe.gl/stats';
 import { RequestScheduler } from '@loaders.gl/loader-utils';
 import { TilesetCache } from "./tileset-cache.js";
 import { calculateTransformProps } from "../helpers/transform-utils.js";
-import { getFrameState, limitSelectedTiles } from "../helpers/frame-state.js";
+import { getFrameState, limitSelectedTiles, updateCameraMotionState } from "../helpers/frame-state.js";
+import { calculateDynamicScreenSpaceErrorDensity, updateRootTransformForDynamicScreenSpaceError } from "../helpers/tiles-3d-lod.js";
+import { interpolateLinearly } from "../helpers/tiles-3d-request-priority.js";
+import { TILESET_TYPE } from "../../constants.js";
 import { isTileset3DSource } from "./tileset-source.js";
+const BYTES_PER_MEBIBYTE = 1024 * 1024;
+const DEFAULT_CACHE_BYTES = 512 * BYTES_PER_MEBIBYTE;
+const DEFAULT_MAXIMUM_CACHE_OVERFLOW_BYTES = 512 * BYTES_PER_MEBIBYTE;
+const DEFAULT_I3S_CACHE_BYTES = 32 * BYTES_PER_MEBIBYTE;
+const DEFAULT_I3S_MAXIMUM_CACHE_OVERFLOW_BYTES = BYTES_PER_MEBIBYTE;
+/**
+ * Validates a byte-based tile-cache budget.
+ *
+ * Fractions are accepted because JavaScript memory estimates are numbers, but negative, infinite,
+ * and `NaN` values cannot define a stable cache threshold.
+ *
+ * @param value - Proposed cache budget in bytes.
+ * @param optionName - Public option name used in an actionable error message.
+ * @returns The validated byte budget.
+ */
+function validateCacheByteLength(value, optionName) {
+    if (!Number.isFinite(value) || value < 0) {
+        throw new Error(`${optionName} must be a finite number greater than or equal to 0`);
+    }
+    return value;
+}
+/**
+ * Resolves the base cache target from byte-native or deprecated mebibyte options.
+ *
+ * The byte-native option takes precedence so mixed migration configurations are deterministic.
+ * The fallback is already expressed in bytes and is used for both construction and runtime updates.
+ *
+ * @param options - Options that may contain byte-native or deprecated cache values.
+ * @param fallbackCacheBytes - Existing or default cache target in bytes.
+ * @returns The resolved and validated cache target in bytes.
+ */
+function resolveCacheBytes(options, fallbackCacheBytes) {
+    const cacheBytes = options.cacheBytes ??
+        (options.maximumMemoryUsage !== undefined
+            ? options.maximumMemoryUsage * BYTES_PER_MEBIBYTE
+            : fallbackCacheBytes);
+    return validateCacheByteLength(cacheBytes, 'cacheBytes');
+}
+/**
+ * Resolves cache overflow headroom from byte-native or deprecated mebibyte options.
+ *
+ * The byte-native option takes precedence so callers can migrate the two cache controls
+ * independently without unit ambiguity.
+ *
+ * @param options - Options that may contain byte-native or deprecated overflow values.
+ * @param fallbackOverflowBytes - Existing or default overflow headroom in bytes.
+ * @returns The resolved and validated overflow headroom in bytes.
+ */
+function resolveMaximumCacheOverflowBytes(options, fallbackOverflowBytes) {
+    const maximumCacheOverflowBytes = options.maximumCacheOverflowBytes ??
+        (options.memoryCacheOverflow !== undefined
+            ? options.memoryCacheOverflow * BYTES_PER_MEBIBYTE
+            : fallbackOverflowBytes);
+    return validateCacheByteLength(maximumCacheOverflowBytes, 'maximumCacheOverflowBytes');
+}
 const DEFAULT_PROPS = {
     description: '',
     ellipsoid: Ellipsoid.WGS84,
     modelMatrix: new Matrix4(),
     throttleRequests: true,
     maxRequests: 64,
-    maximumMemoryUsage: 32,
-    memoryCacheOverflow: 1,
+    cacheBytes: DEFAULT_CACHE_BYTES,
+    maximumCacheOverflowBytes: DEFAULT_MAXIMUM_CACHE_OVERFLOW_BYTES,
+    maximumMemoryUsage: DEFAULT_CACHE_BYTES / BYTES_PER_MEBIBYTE,
+    memoryCacheOverflow: DEFAULT_MAXIMUM_CACHE_OVERFLOW_BYTES / BYTES_PER_MEBIBYTE,
     maximumTilesSelected: 0,
     debounceTime: 0,
     onTileLoad: () => { },
@@ -29,8 +89,18 @@ const DEFAULT_PROPS = {
     onUpdate: () => { },
     contentLoader: undefined,
     viewDistanceScale: 1.0,
+    progressiveResolutionHeightFraction: 0.3,
+    foveatedScreenSpaceError: true,
+    foveatedConeSize: 0.1,
+    foveatedMinimumScreenSpaceErrorRelaxation: 0,
+    foveatedInterpolationCallback: interpolateLinearly,
+    foveatedTimeDelay: 0.2,
     maximumScreenSpaceError: 8,
-    memoryAdjustedScreenSpaceError: false,
+    dynamicScreenSpaceError: true,
+    dynamicScreenSpaceErrorDensity: 2.0e-4,
+    dynamicScreenSpaceErrorFactor: 24,
+    dynamicScreenSpaceErrorHeightFalloff: 0.25,
+    memoryAdjustedScreenSpaceError: true,
     loadTiles: true,
     updateTransforms: true,
     viewportTraversersMap: null,
@@ -84,12 +154,14 @@ export class Tileset3D {
     cartesianCenter = null;
     zoom = 1;
     boundingVolume = null;
-    dynamicScreenSpaceErrorComputedDensity = 0.0;
-    maximumMemoryUsage = 32;
+    /** Effective dynamic SSE density calculated for the most recently traversed viewport. */
+    dynamicScreenSpaceErrorComputedDensity = 0;
+    /** Estimated bytes currently retained by loaded tile content. */
     gpuMemoryUsageInBytes = 0;
+    /** Active SSE threshold after optional cache-pressure adjustment, in logical/CSS pixels. */
     memoryAdjustedScreenSpaceError = 0.0;
-    _cacheBytes = 0;
-    _cacheOverflowBytes = 0;
+    _cacheBytes = DEFAULT_CACHE_BYTES;
+    _maximumCacheOverflowBytes = DEFAULT_MAXIMUM_CACHE_OVERFLOW_BYTES;
     _frameNumber = 0;
     _tiles = {};
     _pendingCount = 0;
@@ -100,6 +172,10 @@ export class Tileset3D {
     _requestedTiles = [];
     _emptyTiles = [];
     frameStateData = {};
+    /** Last camera pose retained independently for each viewport. */
+    _cameraMotionStates = {};
+    /** Pending traversal that releases requests after camera motion settles. */
+    _deferredTraversalTimeout = null;
     _traverser;
     _cache = new TilesetCache();
     _requestScheduler;
@@ -112,11 +188,29 @@ export class Tileset3D {
      * @param options Traversal and runtime options.
      */
     constructor(source, options) {
-        this.options = { ...DEFAULT_PROPS, ...options };
-        this.loadOptions = this.options.loadOptions || {};
         if (!isTileset3DSource(source)) {
             throw new Error('Tileset3D requires a Tileset3DSource instance');
         }
+        const suppliedOptions = options || {};
+        const usesTiles3DCacheDefaults = source.type === TILESET_TYPE.TILES3D;
+        const defaultCacheBytes = usesTiles3DCacheDefaults
+            ? DEFAULT_PROPS.cacheBytes
+            : DEFAULT_I3S_CACHE_BYTES;
+        const defaultMaximumCacheOverflowBytes = usesTiles3DCacheDefaults
+            ? DEFAULT_PROPS.maximumCacheOverflowBytes
+            : DEFAULT_I3S_MAXIMUM_CACHE_OVERFLOW_BYTES;
+        const cacheBytes = resolveCacheBytes(suppliedOptions, defaultCacheBytes);
+        const maximumCacheOverflowBytes = resolveMaximumCacheOverflowBytes(suppliedOptions, defaultMaximumCacheOverflowBytes);
+        this.options = {
+            ...DEFAULT_PROPS,
+            ...suppliedOptions,
+            cacheBytes,
+            maximumCacheOverflowBytes,
+            maximumMemoryUsage: cacheBytes / BYTES_PER_MEBIBYTE,
+            memoryCacheOverflow: maximumCacheOverflowBytes / BYTES_PER_MEBIBYTE,
+            memoryAdjustedScreenSpaceError: suppliedOptions.memoryAdjustedScreenSpaceError ?? usesTiles3DCacheDefaults
+        };
+        this.loadOptions = this.options.loadOptions || {};
         this.source = source;
         this.tileset = null;
         this.loader = this.source.loader;
@@ -135,13 +229,15 @@ export class Tileset3D {
             maxRequests: this.options.maxRequests
         });
         this.memoryAdjustedScreenSpaceError = this.options.maximumScreenSpaceError;
-        this._cacheBytes = this.options.maximumMemoryUsage * 1024 * 1024;
-        this._cacheOverflowBytes = this.options.memoryCacheOverflow * 1024 * 1024;
+        this._cacheBytes = cacheBytes;
+        this._maximumCacheOverflowBytes = maximumCacheOverflowBytes;
         this.stats = new Stats({ id: this.url });
         this._initializeStats();
         this.tilesetInitializationPromise = this._initializeTileSet();
     }
     destroy() {
+        this._clearDeferredTraversal();
+        this.source.destroy?.();
         this._destroy();
     }
     isLoaded() {
@@ -153,13 +249,73 @@ export class Tileset3D {
     get frameNumber() {
         return this._frameNumber;
     }
+    /**
+     * Gets or sets the soft target, in bytes, for cached tile content not needed this frame.
+     *
+     * Current-frame tiles remain protected even when their estimated memory exceeds this target.
+     * Reducing the value makes unused least-recently-used tiles eligible for eviction on the next
+     * traversal.
+     * @default 536870912 for 3D Tiles; 33554432 for I3S
+     */
+    get cacheBytes() {
+        return this._cacheBytes;
+    }
+    set cacheBytes(value) {
+        this._cacheBytes = validateCacheByteLength(value, 'cacheBytes');
+        this.options.cacheBytes = this._cacheBytes;
+        this.options.maximumMemoryUsage = this._cacheBytes / BYTES_PER_MEBIBYTE;
+    }
+    /**
+     * Gets or sets the additional current-frame headroom, in bytes, before memory-adjusted SSE rises.
+     *
+     * The pressure ceiling is `cacheBytes + maximumCacheOverflowBytes`. This value does not change
+     * the base target used to evict tiles that were not touched in the current frame.
+     * @default 536870912 for 3D Tiles; 1048576 for I3S
+     */
+    get maximumCacheOverflowBytes() {
+        return this._maximumCacheOverflowBytes;
+    }
+    set maximumCacheOverflowBytes(value) {
+        this._maximumCacheOverflowBytes = validateCacheByteLength(value, 'maximumCacheOverflowBytes');
+        this.options.maximumCacheOverflowBytes = this._maximumCacheOverflowBytes;
+        this.options.memoryCacheOverflow = this._maximumCacheOverflowBytes / BYTES_PER_MEBIBYTE;
+    }
+    /**
+     * Gets or sets the soft cache target in mebibytes.
+     * @deprecated Use {@link Tileset3D.cacheBytes}. Assignments remain synchronized for compatibility.
+     */
+    get maximumMemoryUsage() {
+        return this.cacheBytes / BYTES_PER_MEBIBYTE;
+    }
+    set maximumMemoryUsage(value) {
+        this.cacheBytes = validateCacheByteLength(value * BYTES_PER_MEBIBYTE, 'maximumMemoryUsage');
+    }
     get queryParams() {
         const rootUrl = this.source.getTileUrl(this.url);
         const queryIndex = rootUrl.indexOf('?');
         return queryIndex >= 0 ? rootUrl.slice(queryIndex + 1) : '';
     }
+    /**
+     * Updates traversal and runtime options, synchronizing byte-native and deprecated cache values.
+     *
+     * For each budget, the byte-native option takes precedence when both unit forms are supplied.
+     * Unspecified budgets retain their current byte values, avoiding repeated MiB conversion.
+     *
+     * @param props - Partial runtime options to apply.
+     */
     setProps(props) {
-        this.options = { ...this.options, ...props };
+        const cacheBytes = resolveCacheBytes(props, this.cacheBytes);
+        const maximumCacheOverflowBytes = resolveMaximumCacheOverflowBytes(props, this.maximumCacheOverflowBytes);
+        this.options = {
+            ...this.options,
+            ...props,
+            cacheBytes,
+            maximumCacheOverflowBytes,
+            maximumMemoryUsage: cacheBytes / BYTES_PER_MEBIBYTE,
+            memoryCacheOverflow: maximumCacheOverflowBytes / BYTES_PER_MEBIBYTE
+        };
+        this._cacheBytes = cacheBytes;
+        this._maximumCacheOverflowBytes = maximumCacheOverflowBytes;
     }
     getTileUrl(tilePath) {
         return this.source.getTileUrl(tilePath);
@@ -198,11 +354,18 @@ export class Tileset3D {
         }
         return this.updatePromise;
     }
+    /**
+     * Moves the active LOD threshold toward the configured SSE or away from cache pressure.
+     *
+     * Usage below {@link Tileset3D.cacheBytes} restores quality in two-percent steps. Usage above
+     * `cacheBytes + maximumCacheOverflowBytes` reduces refinement in two-percent steps. Values in
+     * the overflow window leave the threshold unchanged, preventing rapid load/evict oscillation.
+     */
     adjustScreenSpaceError() {
-        if (this.gpuMemoryUsageInBytes < this._cacheBytes) {
+        if (this.gpuMemoryUsageInBytes < this.cacheBytes) {
             this.memoryAdjustedScreenSpaceError = Math.max(this.memoryAdjustedScreenSpaceError / 1.02, this.options.maximumScreenSpaceError);
         }
-        else if (this.gpuMemoryUsageInBytes > this._cacheBytes + this._cacheOverflowBytes) {
+        else if (this.gpuMemoryUsageInBytes > this.cacheBytes + this.maximumCacheOverflowBytes) {
             this.memoryAdjustedScreenSpaceError *= 1.02;
         }
     }
@@ -217,6 +380,8 @@ export class Tileset3D {
         this._cache.reset();
         this._frameNumber++;
         this.traverseCounter = preparedViewports.length;
+        const currentTime = Date.now();
+        let minimumDeferredTraversalDelay = Number.POSITIVE_INFINITY;
         const viewportsToTraverse = [];
         for (const viewport of preparedViewports) {
             const id = viewport.id;
@@ -236,7 +401,57 @@ export class Tileset3D {
                 continue;
             }
             const frameState = getFrameState(viewport, this._frameNumber);
-            this._traverser.traverse(this.roots[id], frameState, this.options);
+            const root = this.roots[id];
+            const cameraMotionUpdate = updateCameraMotionState(this._cameraMotionStates[id], frameState.camera.position, frameState.camera.direction, currentTime);
+            this._cameraMotionStates[id] = cameraMotionUpdate.state;
+            frameState.camera.timeSinceMovement = cameraMotionUpdate.timeSinceMovement;
+            // Dynamic SSE reads the root's inverse computed transform before traversal updates tile
+            // visibility. Refresh it from the current tileset model matrix here so animated local
+            // box/sphere tilesets never calculate their height falloff one transform behind the frame.
+            updateRootTransformForDynamicScreenSpaceError(root, this.modelMatrix);
+            frameState.dynamicScreenSpaceErrorDensity =
+                this.type === TILESET_TYPE.TILES3D &&
+                    this.options.dynamicScreenSpaceError &&
+                    !frameState.viewport.orthographic
+                    ? calculateDynamicScreenSpaceErrorDensity(root, frameState, this.options)
+                    : 0;
+            // Keep the legacy diagnostic field, but traversal reads the per-viewport frame value above.
+            this.dynamicScreenSpaceErrorComputedDensity = frameState.dynamicScreenSpaceErrorDensity;
+            this._traverser.traverse(root, frameState, this.options);
+            if (Object.keys(this._traverser.deferredTiles).length > 0) {
+                minimumDeferredTraversalDelay = Math.min(minimumDeferredTraversalDelay, Math.max(this.options.foveatedTimeDelay - cameraMotionUpdate.timeSinceMovement, 0));
+            }
+        }
+        if (Number.isFinite(minimumDeferredTraversalDelay)) {
+            this._scheduleDeferredTraversal(minimumDeferredTraversalDelay);
+        }
+        else {
+            this._clearDeferredTraversal();
+        }
+    }
+    /**
+     * Schedules one follow-up traversal when the moving-camera deferral window expires.
+     *
+     * Replacing an existing timer ensures continuing camera movement pushes the retry window forward
+     * instead of creating a queue of redundant traversals.
+     *
+     * @param delayInSeconds - Remaining stationary delay before deferred requests become eligible.
+     */
+    _scheduleDeferredTraversal(delayInSeconds) {
+        this._clearDeferredTraversal();
+        this._deferredTraversalTimeout = setTimeout(() => {
+            this._deferredTraversalTimeout = null;
+            this.selectTiles().catch((error) => {
+                const traversalError = error instanceof Error ? error : new Error(String(error));
+                this._onTilesetError(traversalError);
+            });
+        }, Math.max(delayInSeconds * 1000, 0));
+    }
+    /** Clears a pending moving-camera follow-up traversal. */
+    _clearDeferredTraversal() {
+        if (this._deferredTraversalTimeout !== null) {
+            clearTimeout(this._deferredTraversalTimeout);
+            this._deferredTraversalTimeout = null;
         }
     }
     _needTraverse(viewportId) {
@@ -337,6 +552,9 @@ export class Tileset3D {
     }
     _unloadTiles() {
         this._cache.unloadTiles(this, (tileset, tile) => tileset._unloadTile(tile));
+        if (this.options.memoryAdjustedScreenSpaceError) {
+            this.adjustScreenSpaceError();
+        }
     }
     _updateStats() {
         let tilesRenderable = 0;
@@ -425,6 +643,29 @@ export class Tileset3D {
             this._onTileLoad(tile, loadResult);
         }
     }
+    /**
+     * Loads a source-managed lazy child-header group and reports failures through tile callbacks.
+     *
+     * Subtree metadata shares the normal loading counters but is not reported as render content and
+     * is not added to the GPU cache. Traversal is notified separately after the promise settles.
+     *
+     * @param tile - Runtime tile that owns the lazy subtree reference.
+     * @param frameState - View state that made the subtree eligible for refinement.
+     */
+    async _loadTileChildren(tile, frameState) {
+        try {
+            this._onStartTileLoading();
+            await tile.loadChildren(frameState);
+        }
+        catch (error) {
+            const tileError = error instanceof Error ? error : new Error('subtree load failed');
+            this._onSourceError(tileError, tile);
+            this._onTileLoadError(tile, tileError);
+        }
+        finally {
+            this._onEndTileLoading();
+        }
+    }
     _onTileLoadError(tile, error) {
         this.stats.get(TILES_LOAD_FAILED).incrementCount();
         const message = error.message || error.toString();