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

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

@@ -5,12 +5,65 @@
 // See LICENSE.md and https://github.com/AnalyticalGraphicsInc/cesium/blob/master/LICENSE.md
 import { Vector3, Matrix4 } from '@math.gl/core';
 import { CullingVolume } from '@math.gl/culling';
+import { getTile3DFeatureIdSets } from "./tile-3d-contracts.js";
 import { LOD_METRIC_TYPE, TILE_REFINEMENT, TILE_CONTENT_STATE, TILESET_TYPE } from "../../constants.js";
 import { createBoundingVolume, getCartographicBounds } from "../helpers/bounding-volume.js";
 import { getTiles3DScreenSpaceError } from "../helpers/tiles-3d-lod.js";
 import { getProjectedRadius } from "../helpers/i3s-lod.js";
 import { TilesetTraverser } from "./tileset-traverser.js";
+import { calculateFoveatedFactor, calculateTileRequestPriority, isFoveatedRequestDelayActive, isFoveatedRequestDeferred, isProgressiveResolutionPriority } from "../helpers/tiles-3d-request-priority.js";
 const scratchVector = new Vector3();
+/**
+ * Classifies render-content visibility across all content volumes owned by a tile.
+ *
+ * Content volumes form a union: one visible content entry keeps the tile renderable even when
+ * another entry is outside the frustum or clipping planes. The traversal volume is intentionally
+ * not used here except as a fallback when a tile has no content-specific volume. This separation
+ * keeps clipping render-only and prevents a tight content volume from pruning descendants.
+ *
+ * @param contentVolumes - Transformed content volumes in source order.
+ * @param fallbackVolume - Tile volume used when content does not declare its own volume.
+ * @param cullingVolume - Current view frustum.
+ * @param visibilityPlaneMask - Parent visibility mask optimization.
+ * @param clippingPlanes - Optional world-space planes applied to render content only.
+ * @returns Union visibility classification for the renderable content.
+ */
+export function getContentVisibility(contentVolumes, fallbackVolume, cullingVolume, visibilityPlaneMask, clippingPlanes = []) {
+    const volumes = contentVolumes.length ? contentVolumes : [fallbackVolume];
+    let visibleVolume = false;
+    let intersectingVolume = false;
+    for (const contentVolume of volumes) {
+        let visibility = 'inside';
+        if (visibilityPlaneMask !== CullingVolume.MASK_INSIDE) {
+            visibility = cullingVolume.computeVisibility(contentVolume);
+            if (visibility === 'outside') {
+                continue;
+            }
+        }
+        let clipped = false;
+        for (const clippingPlane of clippingPlanes) {
+            if (contentVolume.intersectPlane(clippingPlane) === 'outside') {
+                clipped = true;
+                break;
+            }
+        }
+        if (!clipped) {
+            visibleVolume = true;
+            intersectingVolume = intersectingVolume || visibility === 'intersecting';
+        }
+    }
+    if (!visibleVolume) {
+        return 'outside';
+    }
+    return intersectingVolume ? 'intersecting' : 'inside';
+}
+function isNestedTilesetPayload(payload) {
+    if (!payload || typeof payload !== 'object') {
+        return false;
+    }
+    const record = payload;
+    return record.shape === 'tileset3d' || record.type === 'tileset3d' || Boolean(record.tileset);
+}
 function defined(x) {
     return x !== undefined && x !== null;
 }
@@ -29,6 +82,8 @@ export class Tile3D {
     refine;
     type;
     contentUrl;
+    /** Resolved render-content URLs in source order; empty for contentless tiles. */
+    contentUrls = [];
     /** Different refinement algorithms used by I3S and 3D tiles */
     lodMetricType = 'geometricError';
     /**
@@ -41,6 +96,8 @@ export class Tile3D {
      * separate ensures transform updates never compound an already-scaled geometric error.
      */
     _unscaledLodMetricValue = 0;
+    /** Whether the source format defines geometric error in transform-local units. */
+    _scaleGeometricError = true;
     /** @todo math.gl is not exporting BoundingVolume base type? */
     boundingVolume = null;
     /**
@@ -48,10 +105,31 @@ export class Tile3D {
      * not the content's metadata in the tileset JSON file.
      */
     content = null;
+    /** Loaded payloads in the same order as {@link contentUrls}; `content` remains the primary payload. */
+    contents = [];
+    /** Ordered renderer-neutral descriptors for each source content entry. */
+    contentEntries = [];
+    /** Raw metadata references inherited by this tile and its content. */
+    metadataContext = {};
+    /** Feature-id declarations normalized from supported content extensions. */
+    featureIdSets = [];
+    /** Decoded 3D Tiles vector topology for the primary loaded content, when present. */
+    vectorContent = null;
+    /**
+     * Metadata entity attached to this tile in the source tileset, if present.
+     *
+     * This is the raw 3D Tiles metadata reference. The generic tiles runtime preserves it without
+     * decoding schema classes or binary property tables.
+     */
+    metadata = null;
+    /** Raw metadata entities attached to tile contents, in content source order. */
+    contentMetadata = [];
     contentState = TILE_CONTENT_STATE.UNLOADED;
     gpuMemoryUsageInBytes = 0;
     /** The tile's children - an array of Tile3D objects. */
     children = [];
+    /** Current lifecycle state for a lazy implicit subtree rooted at this tile. */
+    childrenState = 'ready';
     depth = 0;
     viewportIds = [];
     transform = new Matrix4();
@@ -70,14 +148,40 @@ export class Tile3D {
     // TODO Cesium 3d tiles specific
     _expireDate = null;
     _expiredContent = null;
+    /** In-flight source request shared by repeated traversal frames. */
+    _childrenPromise = null;
     _boundingBox = undefined;
     /** updated every frame for tree traversal and rendering optimizations: */
     _distanceToCamera = 0;
     _screenSpaceError = 0;
+    /** SSE calculated at the reduced viewport height used to prioritize coarse coverage. */
+    _screenSpaceErrorProgressiveResolution = 0;
+    /** Whether this tile should be promoted into the progressive-resolution request pass. */
+    _priorityProgressiveResolution = false;
+    /** Angular distance from the camera view axis used to prioritize center tiles. */
+    _foveatedFactor = 0;
+    /** Whether this peripheral request is currently inside the camera-motion deferral window. */
+    priorityDeferred = false;
     _visibilityPlaneMask;
     _visible = undefined;
     _contentBoundingVolume;
+    _contentBoundingVolumes = [];
+    /** Source content-volume headers retained after render content is unloaded. */
+    _contentBoundingVolumeHeaders = [];
     _viewerRequestVolume;
+    /** Bounding volume used to cull the tile's first renderable content entry. */
+    get contentBoundingVolume() {
+        return this._contentBoundingVolume;
+    }
+    /** All transformed render-content bounding volumes, including tile-volume fallbacks. */
+    get contentBoundingVolumes() {
+        return this._contentBoundingVolumes;
+    }
+    /** Bounding volume that limits when this tile may be requested, when declared. */
+    get viewerRequestVolume() {
+        return this._viewerRequestVolume;
+    }
+    /** Accumulated tile transforms from the source JSON, excluding the tileset model matrix. */
     _initialTransform = new Matrix4();
     // Used by traverser, cannot be marked private
     _priority = 0;
@@ -122,11 +226,15 @@ export class Tile3D {
         this.refine = this._getRefine(header.refine);
         this.type = header.type;
         this.contentUrl = header.contentUrl;
+        this.contentUrls = header.contentUrls || (header.contentUrl ? [header.contentUrl] : []);
+        this._initializeMetadata(header);
+        this.childrenState = header.implicitSubtree ? 'unloaded' : 'ready';
         this._initializeLodMetric(header);
         this._initializeTransforms(header);
         this._updateLodMetricScale();
         this._initializeBoundingVolumes(header);
         this._initializeContent(header);
+        this._initializeContentEntries(header);
         this._initializeRenderingState(header);
         Object.seal(this);
     }
@@ -151,7 +259,18 @@ export class Tile3D {
     }
     /** Returns true if tile has children */
     get hasChildren() {
-        return this.children.length > 0 || (this.header.children && this.header.children.length > 0);
+        return (this.children.length > 0 ||
+            (this.header.children && this.header.children.length > 0) ||
+            Boolean(this.header.implicitSubtree && this.childrenState !== 'ready'));
+    }
+    /** Returns whether traversal may request an unresolved lazy child-header group. */
+    get hasUnloadedChildren() {
+        return Boolean(this.header.implicitSubtree &&
+            (this.childrenState === 'unloaded' || this.childrenState === 'failed'));
+    }
+    /** Returns whether a lazy child-header request is currently in flight. */
+    get childrenLoading() {
+        return this.childrenState === 'loading';
     }
     /**
      * Determines if the tile's content is ready. This is automatically `true` for
@@ -203,22 +322,32 @@ export class Tile3D {
         return this._screenSpaceError;
     }
     /**
-     * Get bounding box in cartographic coordinates
+     * Get the current world-space bounding volume in cartographic coordinates.
      * @returns [min, max] each in [longitude, latitude, altitude]
      */
     get boundingBox() {
         if (!this._boundingBox) {
-            this._boundingBox = getCartographicBounds(this.header.boundingVolume, this.boundingVolume);
+            this._boundingBox = getCartographicBounds(this.header.boundingVolume, this.boundingVolume, !this.computedTransform.equals(this._initialTransform));
         }
         return this._boundingBox;
     }
-    /** Get the tile's screen space error. */
-    getScreenSpaceError(frameState, useParentLodMetric) {
+    /**
+     * Gets the tile's screen-space error for normal refinement or a reduced-height priority pass.
+     *
+     * I3S already supplies a screen-oriented LOD metric and intentionally ignores the optional 3D
+     * Tiles progressive-resolution height fraction.
+     *
+     * @param frameState - Current camera and viewport measurements.
+     * @param useParentLodMetric - Whether to substitute the parent LOD metric.
+     * @param viewportHeightFraction - Fraction of viewport height represented by the priority pass.
+     * @returns Screen-space LOD error for the current tileset format.
+     */
+    getScreenSpaceError(frameState, useParentLodMetric, viewportHeightFraction = 1) {
         switch (this.tileset.type) {
             case TILESET_TYPE.I3S:
                 return getProjectedRadius(this, frameState);
             case TILESET_TYPE.TILES3D:
-                return getTiles3DScreenSpaceError(this, frameState, useParentLodMetric);
+                return getTiles3DScreenSpaceError(this, frameState, useParentLodMetric, viewportHeightFraction);
             default:
                 // eslint-disable-next-line
                 throw new Error('Unsupported tileset type');
@@ -235,16 +364,39 @@ export class Tile3D {
      * Memory usage of tile on GPU
      */
     _getGpuMemoryUsageInBytes() {
-        return this.content.gpuMemoryUsageInBytes || this.content.byteLength || 0;
+        const contents = this.contents.length ? this.contents : [this.content];
+        return contents.reduce((total, content) => total + (content?.gpuMemoryUsageInBytes || content?.byteLength || 0), 0);
     }
-    /*
-     * If skipLevelOfDetail is off try to load child tiles as soon as possible so that their parent can refine sooner.
-     * Tiles are prioritized by screen space error.
+    /**
+     * Returns scheduler priority for render-content requests.
+     *
+     * @returns Numeric priority, or a negative value when the queued request should be cancelled.
      */
-    // eslint-disable-next-line complexity
     _getPriority() {
+        return this._calculateRequestPriority(false);
+    }
+    /**
+     * Returns scheduler priority for lazy child-header requests.
+     *
+     * Contentless implicit placeholders intentionally retain `UNLOADED` content state, so metadata
+     * scheduling skips only that render-content cancellation check and preserves every visibility,
+     * recency, progressive, foveated, and motion-deferral rule.
+     *
+     * @returns Numeric priority, or a negative value when the queued request should be cancelled.
+     */
+    _getChildrenPriority() {
+        return this._calculateRequestPriority(true);
+    }
+    /**
+     * Calculates the common scheduler priority for content or hierarchy metadata.
+     *
+     * @param allowUnloadedContent - Whether an empty placeholder may request child metadata.
+     * @returns Numeric priority, or a negative value when the queued request should be cancelled.
+     */
+    // eslint-disable-next-line complexity
+    _calculateRequestPriority(allowUnloadedContent) {
         const traverser = this.tileset._traverser;
-        const { skipLevelOfDetail } = traverser.options;
+        const skipLevelOfDetail = traverser.options.skipLevelOfDetail && !traverser.disableSkipLevelOfDetail;
         /*
          * Tiles that are outside of the camera's frustum could be skipped if we are in 'ADD' mode
          * or if we are using 'Skip Traversal' in 'REPLACE' mode.
@@ -260,7 +412,13 @@ export class Tile3D {
         if (this.tileset._frameNumber - this._touchedFrame >= 1) {
             return -1;
         }
-        if (this.contentState === TILE_CONTENT_STATE.UNLOADED) {
+        // RequestScheduler re-evaluates this callback before a queued request receives a slot. A
+        // negative priority cancels work that became deferred after it was queued; the scheduled
+        // follow-up traversal submits it again after the motion delay expires.
+        if (this.priorityDeferred) {
+            return -1;
+        }
+        if (!allowUnloadedContent && this.contentState === TILE_CONTENT_STATE.UNLOADED) {
             return -1;
         }
         // Based on the priority function `getPriorityReverseScreenSpaceError` in CesiumJS. Scheduling priority is based on the parent's screen space error when possible.
@@ -270,8 +428,15 @@ export class Tile3D {
             ? parent._screenSpaceError
             : this._screenSpaceError;
         const rootScreenSpaceError = traverser.root ? traverser.root._screenSpaceError : 0.0;
-        // Map higher SSE to lower values (e.g. root tile is highest priority)
-        return Math.max(rootScreenSpaceError - screenSpaceError, 0);
+        // Map higher SSE to lower values (e.g. root tile is highest priority), then combine the
+        // existing order with independent progressive and foveated priority bands.
+        const reverseScreenSpaceError = Math.max(rootScreenSpaceError - screenSpaceError, 0);
+        return calculateTileRequestPriority({
+            priorityProgressiveResolution: this._priorityProgressiveResolution,
+            foveatedFactor: this._foveatedFactor,
+            reverseScreenSpaceError,
+            rootScreenSpaceError
+        });
     }
     /**
      *  Requests the tile's content.
@@ -297,13 +462,7 @@ export class Tile3D {
             return { loaded: false };
         }
         try {
-            const loadResult = await this.tileset.source.loadTileContent(this);
-            if (this.tileset.options.contentLoader) {
-                await this.tileset.options.contentLoader(this);
-            }
-            this.contentState = TILE_CONTENT_STATE.READY;
-            this._onContentLoaded();
-            return loadResult;
+            return await this._loadContentFromSource();
         }
         catch (error) {
             // Tile is unloaded before the content finishes loading
@@ -314,12 +473,235 @@ export class Tile3D {
             requestToken.done();
         }
     }
+    /** Loads content for complete dataset operations without viewport-based request priority. */
+    async loadContentForTraversal() {
+        if (this.hasEmptyContent) {
+            return { loaded: false };
+        }
+        if (this.content) {
+            return { loaded: true, contents: this.contents };
+        }
+        this.contentState = TILE_CONTENT_STATE.LOADING;
+        try {
+            return await this._loadContentFromSource();
+        }
+        catch (error) {
+            this.contentState = TILE_CONTENT_STATE.FAILED;
+            throw error;
+        }
+    }
+    /** Loads source content and updates the tile's renderer-neutral payload state. */
+    async _loadContentFromSource() {
+        const loadResult = await this.tileset.source.loadTileContent(this);
+        if (loadResult.contents) {
+            this.contents = loadResult.contents;
+            this.content = this.contents[0] || null;
+        }
+        this.vectorContent =
+            this.contents.find(content => Boolean(content?.vectorContent))?.vectorContent || null;
+        if (this.tileset.options.contentLoader) {
+            await this.tileset.options.contentLoader(this);
+        }
+        this.contentState = TILE_CONTENT_STATE.READY;
+        this._onContentLoaded();
+        this._updateContentEntriesAfterLoad(loadResult);
+        return loadResult;
+    }
+    /**
+     * Requests and installs this tile's lazy child-header group through its source.
+     *
+     * The same request scheduler and SSE/foveated priority value used for render content are reused
+     * for subtree metadata. Repeated traversal frames share one promise, and scheduler cancellation
+     * restores the unloaded state so a later frame can retry.
+     *
+     * @param frameState - View state that made the subtree eligible for refinement.
+     * @returns Source load result, or an unloaded result if scheduling was cancelled.
+     */
+    async loadChildren(frameState) {
+        if (!this.header.implicitSubtree || this.childrenState === 'ready') {
+            return { loaded: false, tileCount: 0, childSubtreeCount: 0 };
+        }
+        if (this._childrenPromise) {
+            return await this._childrenPromise;
+        }
+        if (!this.tileset.source.loadTileChildren) {
+            throw new Error('Tileset source does not support lazy tile children');
+        }
+        this.childrenState = 'loading';
+        this._childrenPromise = this._loadChildrenWithScheduler(frameState);
+        try {
+            return await this._childrenPromise;
+        }
+        finally {
+            this._childrenPromise = null;
+        }
+    }
+    /**
+     * Runs one lazy child-header load after obtaining a scheduler token.
+     *
+     * @param frameState - View state forwarded to the source implementation.
+     * @returns Source load result.
+     */
+    async _loadChildrenWithScheduler(frameState) {
+        const requestToken = await this.tileset._requestScheduler.scheduleRequest(`${this.id}:implicit-subtree`, this._getChildrenPriority.bind(this));
+        if (!requestToken) {
+            this.childrenState = 'unloaded';
+            return { loaded: false, tileCount: 0, childSubtreeCount: 0 };
+        }
+        try {
+            const loadResult = await this.tileset.source.loadTileChildren(this, frameState);
+            this.childrenState = loadResult.loaded ? 'ready' : 'unloaded';
+            return loadResult;
+        }
+        catch (error) {
+            this.childrenState = 'failed';
+            throw error;
+        }
+        finally {
+            requestToken.done();
+        }
+    }
+    /**
+     * Replaces a contentless implicit placeholder with its materialized subtree-root header.
+     *
+     * The placeholder transform is preserved when the subtree omits a root transform. An explicit
+     * subtree-root transform replaces it and is recomposed against the runtime parent. Content,
+     * metadata, bounds, and raw geometric error are reinitialized from the available header.
+     *
+     * @param materializedHeader - Available root header produced from one subtree resource.
+     */
+    applyImplicitSubtreeHeader(materializedHeader) {
+        const existingTransform = this.header.transform;
+        const existingTransformMatrix = this.header.transformMatrix;
+        const hasMaterializedTransform = materializedHeader.transform !== undefined;
+        this.header = {
+            ...this.header,
+            ...materializedHeader,
+            transform: hasMaterializedTransform ? materializedHeader.transform : existingTransform,
+            transformMatrix: hasMaterializedTransform
+                ? materializedHeader.transformMatrix
+                : existingTransformMatrix,
+            implicitSubtree: undefined
+        };
+        if (hasMaterializedTransform) {
+            this._initializeTransforms(this.header);
+        }
+        this.refine = this._getRefine(materializedHeader.refine);
+        this.type = materializedHeader.type;
+        this.contentUrl = materializedHeader.contentUrl;
+        this.contentUrls =
+            materializedHeader.contentUrls ||
+                (materializedHeader.contentUrl ? [materializedHeader.contentUrl] : []);
+        this._initializeMetadata(this.header);
+        this._initializeLodMetric(materializedHeader);
+        this._updateLodMetricScale();
+        this._initializeBoundingVolumes(this.header);
+        this._boundingBox = undefined;
+        // Use the merged header so inherited viewer-request-volume metadata remains available when a
+        // materialized implicit tile has no render content of its own.
+        this._initializeContent(this.header);
+        this._initializeContentEntries(this.header);
+    }
+    /** Refreshes tile and content metadata from a source or materialized tile header. */
+    _initializeMetadata(header) {
+        this.metadata = header.metadata || null;
+        const contentHeaders = Array.isArray(header.content) ? header.content : [header.content];
+        this.contentMetadata = contentHeaders
+            .filter(Boolean)
+            .map(contentHeader => contentHeader.metadata || null);
+        const firstContentHeader = contentHeaders.find(Boolean) || {};
+        const groupReference = firstContentHeader.group;
+        const group = typeof groupReference === 'number'
+            ? this.tileset.groups?.[groupReference] || null
+            : groupReference || null;
+        const metadataContext = {
+            tileset: this.tileset.metadata || null,
+            group,
+            tile: this.metadata,
+            content: this.contentMetadata[0] || null,
+            subtree: header.implicitMetadata || null
+        };
+        if (this.tileset.groups) {
+            metadataContext.groups = this.tileset.groups;
+        }
+        this.metadataContext = metadataContext;
+    }
+    /** Updates payload and renderability while retaining immutable metadata descriptors. */
+    _updateContentEntriesAfterLoad(loadResult) {
+        if (loadResult.contentEntries) {
+            this.contentEntries = loadResult.contentEntries.map((entry, index) => ({
+                ...entry,
+                index,
+                boundingVolume: entry.boundingVolume || this._contentBoundingVolumes[index] || this.boundingVolume,
+                payload: entry.payload ?? this.contents[index] ?? null,
+                featureIds: entry.featureIds?.length
+                    ? entry.featureIds
+                    : getTile3DFeatureIdSets(entry.payload ?? this.contents[index]),
+                renderable: Boolean(entry.renderable !== false &&
+                    (entry.payload ?? this.contents[index]) &&
+                    !isNestedTilesetPayload(entry.payload ?? this.contents[index]))
+            }));
+            this.featureIdSets = this.contentEntries.flatMap(entry => entry.featureIds);
+            return;
+        }
+        this.contentEntries = this.contentEntries.map((entry, index) => ({
+            ...entry,
+            payload: this.contents[index] ?? null,
+            featureIds: getTile3DFeatureIdSets(this.contents[index]),
+            renderable: Boolean(this.contents[index]) && !isNestedTilesetPayload(this.contents[index])
+        }));
+        this.featureIdSets = this.contentEntries.flatMap(entry => entry.featureIds);
+    }
+    /** Returns one ordered content descriptor, or null when the index is out of range. */
+    getContentEntry(index) {
+        return this.contentEntries[index] || null;
+    }
+    /** Returns whether an ordered content entry currently has renderable payload. */
+    isContentRenderable(index) {
+        return Boolean(this.contentEntries[index]?.renderable);
+    }
+    /** Initializes additive renderer-neutral descriptors from a normalized tile header. */
+    _initializeContentEntries(tileHeader) {
+        const headers = Array.isArray(tileHeader.content)
+            ? tileHeader.content
+            : tileHeader.content
+                ? [tileHeader.content]
+                : [];
+        this.contentEntries = headers.map((contentHeader, index) => {
+            const normalizedContentHeader = contentHeader || {};
+            return {
+                index,
+                uri: this.contentUrls[index] || normalizedContentHeader.uri || normalizedContentHeader.url,
+                group: normalizedContentHeader.group,
+                type: normalizedContentHeader.type,
+                payload: null,
+                metadata: normalizedContentHeader.metadata || null,
+                boundingVolume: this._contentBoundingVolumes[index] || this.boundingVolume,
+                featureIds: this._getFeatureIdSets(normalizedContentHeader),
+                renderable: false
+            };
+        });
+    }
+    /** Extracts renderer-neutral feature-id declarations without decoding property values. */
+    _getFeatureIdSets(contentHeader) {
+        return getTile3DFeatureIdSets(contentHeader);
+    }
     // Unloads the tile's content.
     unloadContent() {
-        if (this.content && this.content.destroy) {
-            this.content.destroy();
+        for (const content of this.contents.length ? this.contents : [this.content]) {
+            if (content && content.destroy) {
+                content.destroy();
+            }
         }
+        this.contents = [];
         this.content = null;
+        this.vectorContent = null;
+        this.contentEntries = this.contentEntries.map(entry => ({
+            ...entry,
+            payload: null,
+            renderable: false
+        }));
+        this.featureIdSets = this.contentEntries.flatMap(entry => entry.featureIds);
         if (this.header.content && this.header.content.destroy) {
             this.header.content.destroy();
         }
@@ -350,12 +732,61 @@ export class Tile3D {
         }
         this._distanceToCamera = this.distanceToTile(frameState);
         this._screenSpaceError = this.getScreenSpaceError(frameState, false);
+        this._updateRequestPriorityMetrics(frameState);
         this._visibilityPlaneMask = this.visibility(frameState, parentVisibilityPlaneMask); // Use parent's plane mask to speed up visibility test
         this._visible = this._visibilityPlaneMask !== CullingVolume.MASK_OUTSIDE;
         this._inRequestVolume = this.insideViewerRequestVolume(frameState);
         this._frameNumber = frameState.frameNumber;
         this.viewportIds = viewportIds;
     }
+    /**
+     * Updates progressive-resolution and foveated request metrics for a 3D Tiles traversal frame.
+     *
+     * I3S retains its format-specific screen-threshold ordering and is explicitly isolated from
+     * geometric-error scheduling. Orthographic viewports still receive progressive coverage, but
+     * angular foveation is disabled because an orthographic frustum has no perspective field of view.
+     *
+     * @param frameState - Current camera and viewport measurements.
+     */
+    _updateRequestPriorityMetrics(frameState) {
+        if (this.tileset.type !== TILESET_TYPE.TILES3D) {
+            this._screenSpaceErrorProgressiveResolution = this._screenSpaceError;
+            this._priorityProgressiveResolution = false;
+            this._foveatedFactor = 0;
+            this.priorityDeferred = false;
+            return;
+        }
+        const options = this.tileset.options;
+        const progressiveResolutionHeightFraction = options.progressiveResolutionHeightFraction;
+        this._screenSpaceErrorProgressiveResolution = this.getScreenSpaceError(frameState, false, progressiveResolutionHeightFraction);
+        this._priorityProgressiveResolution = isProgressiveResolutionPriority(this._screenSpaceErrorProgressiveResolution, this.parent?._screenSpaceErrorProgressiveResolution, this.tileset.memoryAdjustedScreenSpaceError, progressiveResolutionHeightFraction);
+        if (!options.foveatedScreenSpaceError ||
+            frameState.viewport?.orthographic ||
+            !frameState.camera?.position ||
+            !frameState.camera?.direction) {
+            this._foveatedFactor = 0;
+            this.priorityDeferred = false;
+            return;
+        }
+        this._foveatedFactor = calculateFoveatedFactor(this.boundingVolume, frameState.camera);
+        const traverser = this.tileset._traverser;
+        const skipLevelOfDetail = traverser.options.skipLevelOfDetail && !traverser.disableSkipLevelOfDetail;
+        const deferralEligible = isFoveatedRequestDeferred({
+            refinement: this.refine,
+            skipLevelOfDetail,
+            foveatedScreenSpaceError: options.foveatedScreenSpaceError,
+            foveatedConeSize: options.foveatedConeSize,
+            minimumScreenSpaceErrorRelaxation: options.foveatedMinimumScreenSpaceErrorRelaxation,
+            interpolationCallback: options.foveatedInterpolationCallback,
+            foveatedFactor: this._foveatedFactor,
+            verticalFieldOfView: frameState.camera.verticalFieldOfView,
+            screenSpaceError: this._screenSpaceError,
+            parentScreenSpaceError: this.parent?._screenSpaceError,
+            maximumScreenSpaceError: this.tileset.memoryAdjustedScreenSpaceError,
+            priorityProgressiveResolution: this._priorityProgressiveResolution
+        });
+        this.priorityDeferred = isFoveatedRequestDelayActive(deferralEligible, frameState.camera.timeSinceMovement, options.foveatedTimeDelay);
+    }
     // Determines whether the tile's bounding volume intersects the culling volume.
     // @param {FrameState} frameState The frame state.
     // @param {Number} parentVisibilityPlaneMask The parent's plane mask to speed up the visibility check.
@@ -378,46 +809,21 @@ export class Tile3D {
         // return cullingVolume.computeVisibilityWithPlaneMask(boundingVolume, parentVisibilityPlaneMask);
         return cullingVolume.computeVisibilityWithPlaneMask(boundingVolume, parentVisibilityPlaneMask);
     }
-    // Assuming the tile's bounding volume intersects the culling volume, determines
-    // whether the tile's content's bounding volume intersects the culling volume.
-    // @param {FrameState} frameState The frame state.
-    // @returns {Intersect} The result of the intersection: the tile's content is completely outside, completely inside, or intersecting the culling volume.
-    contentVisibility() {
-        return true;
-        // TODO restore
-        /*
-        // Assumes the tile's bounding volume intersects the culling volume already, so
-        // just return Intersect.INSIDE if there is no content bounding volume.
-        if (!defined(this.contentBoundingVolume)) {
-          return Intersect.INSIDE;
-        }
-    
-        if (this._visibilityPlaneMask === CullingVolume.MASK_INSIDE) {
-          // The tile's bounding volume is completely inside the culling volume so
-          // the content bounding volume must also be inside.
-          return Intersect.INSIDE;
-        }
-    
-        // PERFORMANCE_IDEA: is it possible to burn less CPU on this test since we know the
-        // tile's (not the content's) bounding volume intersects the culling volume?
-        const cullingVolume = frameState.cullingVolume;
-        const boundingVolume = tile.contentBoundingVolume;
-    
-        const tileset = this.tileset;
-        const clippingPlanes = tileset.clippingPlanes;
-        if (defined(clippingPlanes) && clippingPlanes.enabled) {
-          const intersection = clippingPlanes.computeIntersectionWithBoundingVolume(
-            boundingVolume,
-            tileset.clippingPlanesOriginMatrix
-          );
-          this._isClipped = intersection !== Intersect.INSIDE;
-          if (intersection === Intersect.OUTSIDE) {
-            return Intersect.OUTSIDE;
-          }
-        }
-    
-        return cullingVolume.computeVisibility(boundingVolume);
-        */
+    /**
+     * Determines whether renderable content intersects the view and configured clipping planes.
+     *
+     * Clipping planes are render-only constraints; traversal continues to use the tile volume.
+     *
+     * @param frameState Current camera, culling, and optional clipping-plane state.
+     * @returns The content visibility classification.
+     */
+    contentVisibility(frameState, contentIndex) {
+        const contentVolumes = contentIndex === undefined
+            ? this._contentBoundingVolumes
+            : this._contentBoundingVolumes[contentIndex]
+                ? [this._contentBoundingVolumes[contentIndex]]
+                : [];
+        return getContentVisibility(contentVolumes, this.boundingVolume, frameState.cullingVolume, this._visibilityPlaneMask, frameState.clippingPlanes);
     }
     /**
      * Computes the (potentially approximate) distance from the closest point of the tile's bounding volume to the camera.
@@ -465,6 +871,10 @@ export class Tile3D {
     // INTERNAL METHODS
     /** Initializes the tile's LOD metric from its header or its nearest available ancestor. */
     _initializeLodMetric(header) {
+        this._scaleGeometricError =
+            typeof header._scaleGeometricError === 'boolean'
+                ? header._scaleGeometricError
+                : (this.parent?._scaleGeometricError ?? true);
         if ('lodMetricType' in header) {
             this.lodMetricType = header.lodMetricType;
         }
@@ -512,7 +922,7 @@ export class Tile3D {
      * I3S `maxScreenThreshold` is already a screen-space metric and must not be transform-scaled.
      */
     _updateLodMetricScale() {
-        if (this.lodMetricType !== LOD_METRIC_TYPE.GEOMETRIC_ERROR) {
+        if (this.lodMetricType !== LOD_METRIC_TYPE.GEOMETRIC_ERROR || !this._scaleGeometricError) {
             this.lodMetricValue = this._unscaledLodMetricValue;
             return;
         }
@@ -522,18 +932,20 @@ export class Tile3D {
     }
     _initializeBoundingVolumes(tileHeader) {
         this._contentBoundingVolume = null;
+        this._contentBoundingVolumeHeaders = [];
         this._viewerRequestVolume = null;
         this._updateBoundingVolume(tileHeader);
     }
     _initializeContent(tileHeader) {
         // Empty tile by default
         this.content = { _tileset: this.tileset, _tile: this };
+        this.contents = [];
         this.hasEmptyContent = true;
         this.contentState = TILE_CONTENT_STATE.UNLOADED;
         // When `true`, the tile's content points to an external tileset.
         // This is `false` until the tile's content is loaded.
         this.hasTilesetContent = false;
-        if (tileHeader.contentUrl) {
+        if (tileHeader.contentUrl || tileHeader.contentUrls?.length) {
             this.content = null;
             this.hasEmptyContent = false;
         }
@@ -546,6 +958,10 @@ export class Tile3D {
         this._distanceToCamera = 0;
         this._centerZDepth = 0;
         this._screenSpaceError = 0;
+        this._screenSpaceErrorProgressiveResolution = 0;
+        this._priorityProgressiveResolution = false;
+        this._foveatedFactor = 0;
+        this.priorityDeferred = false;
         this._visibilityPlaneMask = CullingVolume.MASK_INDETERMINATE;
         this._visible = undefined;
         this._inRequestVolume = false;
@@ -562,18 +978,28 @@ export class Tile3D {
         // Inherit from parent tile if omitted.
         return refine || (this.parent && this.parent.refine) || TILE_REFINEMENT.REPLACE;
     }
+    /**
+     * Returns whether loaded content is an external tileset.
+     *
+     * Parsed shape is authoritative because valid external resources may be extensionless, signed,
+     * or use a misleading filename. This method is called only after source loading has populated
+     * `content`.
+     */
     _isTileset() {
-        return this.contentUrl.indexOf('.json') !== -1;
+        return (this.contents.length ? this.contents : [this.content]).some(content => content?.shape === 'tileset3d');
     }
     _onContentLoaded() {
         // Vector and Geometry tile rendering do not support the skip LOD optimization.
-        switch (this.content && this.content.type) {
-            case 'vctr':
-            case 'geom':
-                // @ts-ignore
-                this.tileset._traverser.disableSkipLevelOfDetail = true;
-                break;
-            default:
+        const contents = this.contents.length ? this.contents : [this.content];
+        for (const content of contents) {
+            switch (content && content.type) {
+                case 'vctr':
+                case 'geom':
+                    // @ts-ignore
+                    this.tileset._traverser.disableSkipLevelOfDetail = true;
+                    break;
+                default:
+            }
         }
         // The content may be tileset json
         if (this._isTileset()) {
@@ -584,24 +1010,32 @@ export class Tile3D {
         }
     }
     _updateBoundingVolume(header) {
+        this._boundingBox = undefined;
         // Update the bounding volumes
-        this.boundingVolume = createBoundingVolume(header.boundingVolume, this.computedTransform, this.boundingVolume);
-        const content = header.content;
-        if (!content) {
-            return;
-        }
-        // TODO Cesium specific
-        // Non-leaf tiles may have a content bounding-volume, which is a tight-fit bounding volume
-        // around only the features in the tile. This box is useful for culling for rendering,
-        // but not for culling for traversing the tree since it does not guarantee spatial coherence, i.e.,
-        // since it only bounds features in the tile, not the entire tile, children may be
-        // outside of this box.
-        if (content.boundingVolume) {
-            this._contentBoundingVolume = createBoundingVolume(content.boundingVolume, this.computedTransform, this._contentBoundingVolume);
-        }
+        this.boundingVolume = createBoundingVolume(header.boundingVolume, this.computedTransform, this.boundingVolume, this._initialTransform);
+        // Viewer request volumes constrain traversal, not just render content. A contentless implicit
+        // connector can still own an inherited request volume, so initialize it before the
+        // content-specific early return below.
         if (header.viewerRequestVolume) {
-            this._viewerRequestVolume = createBoundingVolume(header.viewerRequestVolume, this.computedTransform, this._viewerRequestVolume);
+            this._viewerRequestVolume = createBoundingVolume(header.viewerRequestVolume, this.computedTransform, this._viewerRequestVolume, this._initialTransform);
+        }
+        const content = header.content;
+        if (content) {
+            this._contentBoundingVolumeHeaders = Array.isArray(content) ? content : [content];
         }
+        const contentHeaders = content
+            ? Array.isArray(content)
+                ? content
+                : [content]
+            : this._contentBoundingVolumeHeaders;
+        // Preserve source order: an unbounded content entry uses the tile volume at its
+        // corresponding index rather than being appended after bounded sibling entries.
+        this._contentBoundingVolumes = contentHeaders.length
+            ? contentHeaders.map(headerEntry => headerEntry?.boundingVolume
+                ? createBoundingVolume(headerEntry.boundingVolume, this.computedTransform, undefined, this._initialTransform)
+                : this.boundingVolume)
+            : [this.boundingVolume];
+        this._contentBoundingVolume = this._contentBoundingVolumes[0] || null;
     }
     /**
      * Updates the tile's computed transform, world-space geometric error, and bounding volumes.