@loaders.gl/tiles 5.0.0-alpha.5 → 5.0.0-alpha.7

package/src/tileset-3d/common/tile-3d.ts

@@ -8,6 +8,8 @@
 import {Vector3, Matrix4} from '@math.gl/core';
 import {CullingVolume} from '@math.gl/culling';
 import type {CullingResult} from '@math.gl/culling';
+import {getTile3DFeatureIdSets} from './tile-3d-contracts';
+import type {Tile3DContent, Tile3DFeatureIdSet, Tile3DMetadataContext} from './tile-3d-contracts';
 
 // Note: circular dependency
 import type {Tileset3D} from './tileset-3d';
@@ -85,6 +87,14 @@ export function getContentVisibility(
   return intersectingVolume ? 'intersecting' : 'inside';
 }
 
+function isNestedTilesetPayload(payload: unknown): boolean {
+  if (!payload || typeof payload !== 'object') {
+    return false;
+  }
+  const record = payload as Record<string, any>;
+  return record.shape === 'tileset3d' || record.type === 'tileset3d' || Boolean(record.tileset);
+}
+
 function defined(x) {
   return x !== undefined && x !== null;
 }
@@ -137,6 +147,9 @@ export class Tile3D {
    */
   private _unscaledLodMetricValue: number = 0;
 
+  /** Whether the source format defines geometric error in transform-local units. */
+  private _scaleGeometricError: boolean = true;
+
   /** @todo math.gl is not exporting BoundingVolume base type? */
   boundingVolume: any = null;
 
@@ -147,6 +160,14 @@ export class Tile3D {
   content: any = null;
   /** Loaded payloads in the same order as {@link contentUrls}; `content` remains the primary payload. */
   contents: any[] = [];
+  /** Ordered renderer-neutral descriptors for each source content entry. */
+  contentEntries: Tile3DContent[] = [];
+  /** Raw metadata references inherited by this tile and its content. */
+  metadataContext: Tile3DMetadataContext = {};
+  /** Feature-id declarations normalized from supported content extensions. */
+  featureIdSets: Tile3DFeatureIdSet[] = [];
+  /** Decoded 3D Tiles vector topology for the primary loaded content, when present. */
+  vectorContent: unknown = null;
   /**
    * Metadata entity attached to this tile in the source tileset, if present.
    *
@@ -228,6 +249,7 @@ export class Tile3D {
     return this._viewerRequestVolume;
   }
 
+  /** Accumulated tile transforms from the source JSON, excluding the tileset model matrix. */
   _initialTransform: Matrix4 = new Matrix4();
 
   // Used by traverser, cannot be marked private
@@ -283,11 +305,7 @@ export class Tile3D {
     this.type = header.type;
     this.contentUrl = header.contentUrl;
     this.contentUrls = header.contentUrls || (header.contentUrl ? [header.contentUrl] : []);
-    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);
+    this._initializeMetadata(header);
     this.childrenState = header.implicitSubtree ? 'unloaded' : 'ready';
 
     this._initializeLodMetric(header);
@@ -295,6 +313,7 @@ export class Tile3D {
     this._updateLodMetricScale();
     this._initializeBoundingVolumes(header);
     this._initializeContent(header);
+    this._initializeContentEntries(header);
     this._initializeRenderingState(header);
 
     Object.seal(this);
@@ -407,12 +426,16 @@ export class Tile3D {
   }
 
   /**
-   * 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(): CartographicBounds {
     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;
   }
@@ -495,7 +518,8 @@ export class Tile3D {
   // eslint-disable-next-line complexity
   private _calculateRequestPriority(allowUnloadedContent: boolean): number {
     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
@@ -584,6 +608,8 @@ export class Tile3D {
         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);
@@ -591,6 +617,7 @@ export class Tile3D {
 
       this.contentState = TILE_CONTENT_STATE.READY;
       this._onContentLoaded();
+      this._updateContentEntriesAfterLoad(loadResult);
       return loadResult;
     } catch (error) {
       // Tile is unloaded before the content finishes loading
@@ -664,34 +691,137 @@ export class Tile3D {
   /**
    * Replaces a contentless implicit placeholder with its materialized subtree-root header.
    *
-   * Transform state is intentionally preserved: the placeholder already owns the composed
-   * transform, and reapplying the root transform here would double-transform bounds and geometric
-   * error. Content and raw geometric error are reinitialized from the newly available 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: Record<string, any>): void {
     const existingTransform = this.header.transform;
     const existingTransformMatrix = this.header.transformMatrix;
+    const hasMaterializedTransform = materializedHeader.transform !== undefined;
     this.header = {
       ...this.header,
       ...materializedHeader,
-      transform: existingTransform,
-      transformMatrix: existingTransformMatrix,
+      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. */
+  private _initializeMetadata(header: Record<string, any>): void {
+    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: Tile3DMetadataContext = {
+      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. */
+  private _updateContentEntriesAfterLoad(loadResult: TileContentLoadResult): void {
+    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: number): Tile3DContent | null {
+    return this.contentEntries[index] || null;
+  }
+
+  /** Returns whether an ordered content entry currently has renderable payload. */
+  isContentRenderable(index: number): boolean {
+    return Boolean(this.contentEntries[index]?.renderable);
+  }
+
+  /** Initializes additive renderer-neutral descriptors from a normalized tile header. */
+  private _initializeContentEntries(tileHeader: Record<string, any>): void {
+    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. */
+  private _getFeatureIdSets(contentHeader: Record<string, any>): Tile3DFeatureIdSet[] {
+    return getTile3DFeatureIdSets(contentHeader);
   }
 
   // Unloads the tile's content.
@@ -703,6 +833,13 @@ export class Tile3D {
     }
     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();
     }
@@ -790,9 +927,12 @@ export class Tile3D {
     }
 
     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: this.tileset._traverser.options.skipLevelOfDetail,
+      skipLevelOfDetail,
       foveatedScreenSpaceError: options.foveatedScreenSpaceError,
       foveatedConeSize: options.foveatedConeSize,
       minimumScreenSpaceErrorRelaxation: options.foveatedMinimumScreenSpaceErrorRelaxation,
@@ -844,9 +984,15 @@ export class Tile3D {
    * @param frameState Current camera, culling, and optional clipping-plane state.
    * @returns The content visibility classification.
    */
-  contentVisibility(frameState: FrameState): CullingResult {
+  contentVisibility(frameState: FrameState, contentIndex?: number): CullingResult {
+    const contentVolumes =
+      contentIndex === undefined
+        ? this._contentBoundingVolumes
+        : this._contentBoundingVolumes[contentIndex]
+          ? [this._contentBoundingVolumes[contentIndex]]
+          : [];
     return getContentVisibility(
-      this._contentBoundingVolumes,
+      contentVolumes,
       this.boundingVolume,
       frameState.cullingVolume,
       this._visibilityPlaneMask,
@@ -909,6 +1055,10 @@ export class Tile3D {
 
   /** Initializes the tile's LOD metric from its header or its nearest available ancestor. */
   _initializeLodMetric(header: {[key: string]: any}): void {
+    this._scaleGeometricError =
+      typeof header._scaleGeometricError === 'boolean'
+        ? header._scaleGeometricError
+        : (this.parent?._scaleGeometricError ?? true);
     if ('lodMetricType' in header) {
       this.lodMetricType = header.lodMetricType;
     } else {
@@ -965,7 +1115,7 @@ export class Tile3D {
    * I3S `maxScreenThreshold` is already a screen-space metric and must not be transform-scaled.
    */
   _updateLodMetricScale(): void {
-    if (this.lodMetricType !== LOD_METRIC_TYPE.GEOMETRIC_ERROR) {
+    if (this.lodMetricType !== LOD_METRIC_TYPE.GEOMETRIC_ERROR || !this._scaleGeometricError) {
       this.lodMetricValue = this._unscaledLodMetricValue;
       return;
     }
@@ -1070,11 +1220,13 @@ export class Tile3D {
   }
 
   _updateBoundingVolume(header) {
+    this._boundingBox = undefined;
     // Update the bounding volumes
     this.boundingVolume = createBoundingVolume(
       header.boundingVolume,
       this.computedTransform,
-      this.boundingVolume
+      this.boundingVolume,
+      this._initialTransform
     );
 
     // Viewer request volumes constrain traversal, not just render content. A contentless implicit
@@ -1084,7 +1236,8 @@ export class Tile3D {
       this._viewerRequestVolume = createBoundingVolume(
         header.viewerRequestVolume,
         this.computedTransform,
-        this._viewerRequestVolume
+        this._viewerRequestVolume,
+        this._initialTransform
       );
     }
 
@@ -1102,7 +1255,12 @@ export class Tile3D {
     this._contentBoundingVolumes = contentHeaders.length
       ? contentHeaders.map(headerEntry =>
           headerEntry?.boundingVolume
-            ? createBoundingVolume(headerEntry.boundingVolume, this.computedTransform)
+            ? createBoundingVolume(
+                headerEntry.boundingVolume,
+                this.computedTransform,
+                undefined,
+                this._initialTransform
+              )
             : this.boundingVolume
         )
       : [this.boundingVolume];

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

@@ -7,7 +7,7 @@
 import {Matrix4, Vector3} from '@math.gl/core';
 import {Ellipsoid} from '@math.gl/geospatial';
 import {Stats} from '@probe.gl/stats';
-import {RequestScheduler, LoaderWithParser, LoaderOptions} from '@loaders.gl/loader-utils';
+import {RequestScheduler, Loader, LoaderOptions} from '@loaders.gl/loader-utils';
 import {TilesetCache} from './tileset-cache';
 import {calculateTransformProps} from '../helpers/transform-utils';
 import {getFrameState, limitSelectedTiles, updateCameraMotionState} from '../helpers/frame-state';
@@ -87,6 +87,26 @@ export type Tileset3DProps = {
    * @default false
    */
   skipLevelOfDetail?: boolean;
+  /**
+   * SSE above which tiles remain part of the non-skipping base traversal.
+   * @default 1024
+   */
+  baseScreenSpaceError?: number;
+  /**
+   * Required SSE reduction from the nearest requested or loaded ancestor before loading a tile.
+   * @default 16
+   */
+  skipScreenSpaceErrorFactor?: number;
+  /**
+   * Minimum hierarchy levels between requested tiles during skip-LOD traversal.
+   * @default 1
+   */
+  skipLevels?: number;
+  /**
+   * Requests only final tiles that meet the active SSE target when skip-LOD is enabled.
+   * @default false
+   */
+  immediatelyLoadDesiredLevelOfDetail?: boolean;
   /** Enables perspective dynamic SSE to reduce distant, horizon-facing refinement. */
   dynamicScreenSpaceError?: boolean;
   /** Base dynamic SSE fog density in inverse meters. */
@@ -154,6 +174,14 @@ type Props = {
   maximumScreenSpaceError: number;
   /** Whether replacement traversal may skip levels while retaining ancestor coverage. */
   skipLevelOfDetail: boolean;
+  /** SSE above which tiles remain part of the non-skipping base traversal. */
+  baseScreenSpaceError: number;
+  /** Required SSE reduction between requested skip-LOD tiles. */
+  skipScreenSpaceErrorFactor: number;
+  /** Minimum hierarchy levels between requested skip-LOD tiles. */
+  skipLevels: number;
+  /** Whether skip-LOD requests only the final desired tiles. */
+  immediatelyLoadDesiredLevelOfDetail: boolean;
   /** Whether perspective dynamic SSE is enabled. */
   dynamicScreenSpaceError: boolean;
   /** Base dynamic SSE fog density in inverse meters. */
@@ -282,6 +310,10 @@ const DEFAULT_PROPS: Props = {
   foveatedTimeDelay: 0.2,
   maximumScreenSpaceError: 8,
   skipLevelOfDetail: false,
+  baseScreenSpaceError: 1024,
+  skipScreenSpaceErrorFactor: 16,
+  skipLevels: 1,
+  immediatelyLoadDesiredLevelOfDetail: false,
   dynamicScreenSpaceError: true,
   dynamicScreenSpaceErrorDensity: 2.0e-4,
   dynamicScreenSpaceErrorFactor: 24,
@@ -322,7 +354,7 @@ export class Tileset3D {
 
   type: TILESET_TYPE;
   tileset: TilesetJSON | null;
-  loader: LoaderWithParser;
+  loader: Loader;
   url: string;
   basePath: string;
   modelMatrix: Matrix4;
@@ -485,6 +517,26 @@ export class Tileset3D {
     return this._frameNumber;
   }
 
+  /**
+   * Returns the tiles requested during the most recent completed traversal.
+   *
+   * A defensive copy makes request ordering deterministic for diagnostics and prevents callers
+   * from mutating the scheduler's working set.
+   */
+  get requestedTiles(): readonly Tile3D[] {
+    return this._requestedTiles.slice();
+  }
+
+  /**
+   * Returns empty tiles considered during the most recent completed traversal.
+   *
+   * Empty tiles can still be useful hierarchy placeholders, but their IDs are included in
+   * observability snapshots so applications can distinguish traversal work from render content.
+   */
+  get emptyTiles(): readonly Tile3D[] {
+    return this._emptyTiles.slice();
+  }
+
   /**
    * Gets or sets the soft target, in bytes, for cached tile content not needed this frame.
    *
@@ -630,6 +682,14 @@ export class Tileset3D {
       return;
     }
     const preparedViewports = viewports instanceof Array ? viewports : [viewports];
+    const activeViewportIds = new Set(preparedViewports.map(viewport => viewport.id));
+    // A viewport may be removed between frames. Discard its completed state before aggregating
+    // requested and selected tiles so observability reflects only the current traversal inputs.
+    for (const frameStateId of Object.keys(this.frameStateData)) {
+      if (!activeViewportIds.has(frameStateId)) {
+        delete this.frameStateData[frameStateId];
+      }
+    }
 
     this._cache.reset();
     this._frameNumber++;
@@ -877,7 +937,7 @@ export class Tileset3D {
       if (
         initialMetadata?.tileset?.root &&
         typeof initialMetadata.tileset.root.then !== 'function' &&
-        !this.source.prepareTileset
+        (!this.source.prepareTileset || this.spatialReference?.status === 'native')
       ) {
         this.root = this._initializeTileHeaders(initialMetadata.tileset, null);
         this._applyViewState();

package/src/tileset-3d/common/tileset-observability.ts

@@ -0,0 +1,100 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import type {Tileset3D} from './tileset-3d';
+import type {Tile3D} from './tile-3d';
+
+/**
+ * A deterministic, renderer-neutral snapshot of one {@link Tileset3D} traversal.
+ *
+ * Tile IDs are sorted so snapshots can be compared across runs even when child requests complete
+ * in a different order. Counts are reported for the completed traversal frame and cache values are
+ * expressed in bytes. This is an inspection contract; it does not alter traversal or request policy.
+ */
+export type Tileset3DTraversalSnapshot = {
+  /** Monotonically increasing traversal frame number. */
+  frameNumber: number;
+  /** IDs selected for rendering, sorted for stable comparisons. */
+  selectedTileIds: string[];
+  /** IDs whose content was requested, sorted for stable comparisons. */
+  requestedTileIds: string[];
+  /** IDs visited as hierarchy-only or empty tiles, sorted for stable comparisons. */
+  emptyTileIds: string[];
+  /** Number of selected tiles in the completed frame. */
+  visibleTileCount: number;
+  /** Number of selected tiles with renderable content. */
+  renderableTileCount: number;
+  /** Number of tile or subtree loads currently in flight. */
+  loadingTileCount: number;
+  /** Cumulative number of tiles loaded into the runtime cache. */
+  loadedTileCount: number;
+  /** Cumulative number of failed tile loads. */
+  failedTileCount: number;
+  /** Number of tiles currently retained in the runtime cache. */
+  cachedTileCount: number;
+  /** Estimated cached content bytes. */
+  cacheBytes: number;
+  /** Active memory-adjusted maximum SSE in logical/CSS pixels. */
+  maximumScreenSpaceError: number;
+  /** Source-specific implicit subtree counters, when the source exposes them. */
+  implicitTiling?: {
+    /** Number of subtree resources requested from the source. */
+    requestedSubtrees: number;
+    /** Number of subtree resources successfully materialized. */
+    loadedSubtrees: number;
+    /** Number of requests served by the parsed-subtree cache. */
+    cacheHits: number;
+    /** Number of parsed subtrees currently retained for reuse. */
+    cachedSubtrees: number;
+    /** Number of subtree requests currently in flight. */
+    pendingSubtrees: number;
+    /** Number of runtime tile headers created from materialized subtrees. */
+    materializedTiles: number;
+  };
+};
+
+/**
+ * Creates a stable observability snapshot from public {@link Tileset3D} state.
+ *
+ * The helper intentionally reads only public runtime fields and source diagnostics. It is safe to
+ * call from an instrumentation loop and does not retain tile or content references.
+ *
+ * @param tileset - Runtime whose most recent traversal should be inspected.
+ * @returns A serializable snapshot suitable for logs, regression fixtures, and benchmark output.
+ */
+export function getTileset3DTraversalSnapshot(tileset: Tileset3D): Tileset3DTraversalSnapshot {
+  const selectedTiles = tileset.selectedTiles.slice();
+  const requestedTiles = tileset.requestedTiles.slice();
+  const emptyTiles = tileset.emptyTiles.slice();
+
+  const getTileIds = (tiles: readonly Tile3D[]): string[] =>
+    tiles.map(tile => String(tile.id)).sort();
+
+  const getStatCount = (name: string): number => {
+    const count = tileset.stats.get(name).count;
+    return typeof count === 'number' && Number.isFinite(count) ? count : 0;
+  };
+
+  const implicitTilingSource = tileset.source as Tileset3D['source'] & {
+    getImplicitTilingStats?: () => Tileset3DTraversalSnapshot['implicitTiling'];
+  };
+  const implicitTiling = implicitTilingSource.getImplicitTilingStats?.();
+
+  return {
+    frameNumber: tileset.frameNumber,
+    selectedTileIds: getTileIds(selectedTiles),
+    requestedTileIds: getTileIds(requestedTiles),
+    emptyTileIds: getTileIds(emptyTiles),
+    visibleTileCount: selectedTiles.length,
+    renderableTileCount: selectedTiles.filter(
+      tile => tile.contentAvailable && Boolean(tile.content)
+    ).length,
+    loadingTileCount: getStatCount('Tiles Loading'),
+    loadedTileCount: getStatCount('Tiles Loaded'),
+    failedTileCount: getStatCount('Failed Tile Loads'),
+    cachedTileCount: getStatCount('Tiles In Memory'),
+    cacheBytes: tileset.gpuMemoryUsageInBytes,
+    maximumScreenSpaceError: tileset.memoryAdjustedScreenSpaceError,
+    ...(implicitTiling ? {implicitTiling} : {})
+  };
+}

package/src/tileset-3d/common/tileset-source.ts

@@ -2,7 +2,7 @@
 // SPDX-License-Identifier: MIT
 // Copyright (c) vis.gl contributors
 
-import type {CoreAPI, LoaderOptions, LoaderWithParser} from '@loaders.gl/loader-utils';
+import type {CoreAPI, Loader, LoaderOptions} from '@loaders.gl/loader-utils';
 import type {Vector3} from '@math.gl/core';
 import type {TilesetTraverser, TilesetTraverserProps} from './tileset-traverser';
 import type {Tile3D} from './tile-3d';
@@ -10,6 +10,7 @@ import type {Tileset3D} from './tileset-3d';
 import type {FrameState} from '../helpers/frame-state';
 import type {TILESET_TYPE} from '../../constants';
 import type {TilesetSpatialReference} from '../../spatial/spatial-types';
+import type {Tile3DContent} from './tile-3d-contracts';
 
 /**
  * Parsed top-level tileset payload consumed by {@link Tileset3D} or a {@link Tileset3DSource}.
@@ -24,18 +25,14 @@ export type TilesetSourceResolver = {
   /**
    * Loads and parses the root metadata resource for a source.
    */
-  loadRoot<DataT>(
-    url: string,
-    loader: LoaderWithParser<DataT>,
-    loadOptions: LoaderOptions
-  ): Promise<DataT>;
+  loadRoot<DataT>(url: string, loader: Loader<DataT>, loadOptions: LoaderOptions): Promise<DataT>;
 
   /**
    * Loads and parses an arbitrary source-relative resource.
    */
   loadResource<DataT>(
     url: string,
-    loader: LoaderWithParser<DataT>,
+    loader: Loader<DataT>,
     loadOptions: LoaderOptions
   ): Promise<DataT>;
 };
@@ -47,7 +44,7 @@ export type TilesetSourceRequest = {
   /** Absolute root metadata URL. */
   url: string;
   /** Loader used to fetch and parse the root metadata. */
-  loader: LoaderWithParser;
+  loader: Loader;
   /** Optional base path override for relative resources. */
   basePath?: string;
   /** Optional resource-loading strategy used for archive-backed datasets. */
@@ -72,6 +69,8 @@ export type TileContentLoadResult = {
   loaded: boolean;
   /** All payloads loaded for a tile, in source order. */
   contents?: any[];
+  /** Optional normalized renderer-neutral descriptors for each content entry. */
+  contentEntries?: Tile3DContent[];
   /** Nested tileset metadata to install below the loaded tile, if any. */
   nestedTileset?: TilesetJSON;
   /** Nested tilesets found among multiple content payloads. */
@@ -119,8 +118,8 @@ export type TilesetSourceViewState = {
 export type TilesetSourceMetadata = {
   /** Format discriminator. */
   type: TILESET_TYPE;
-  /** Loader used for metadata and content requests. */
-  loader: LoaderWithParser;
+  /** Primary format loader used for metadata and default content requests. */
+  loader: Loader;
   /** Absolute root metadata URL. */
   url: string;
   /** Base path used for relative resource resolution. */
@@ -143,8 +142,8 @@ export type TilesetSourceMetadata = {
 export interface Tileset3DSource {
   /** Tileset format discriminator. */
   readonly type: TILESET_TYPE;
-  /** Loader used for content and metadata requests. */
-  readonly loader: LoaderWithParser;
+  /** Primary format loader used for metadata and default content requests. */
+  readonly loader: Loader;
   /** Absolute URL of the root tileset resource. */
   readonly url: string;
   /** Base directory used for relative resource resolution. */