@loaders.gl/tiles 5.0.0-alpha.6 → 5.0.0-alpha.8

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;
   }
@@ -579,20 +602,7 @@ export class Tile3D {
     }
 
     try {
-      const loadResult = await this.tileset.source.loadTileContent(this);
-
-      if (loadResult.contents) {
-        this.contents = loadResult.contents;
-        this.content = this.contents[0] || null;
-      }
-
-      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
       this.contentState = TILE_CONTENT_STATE.FAILED;
@@ -602,6 +612,44 @@ export class Tile3D {
     }
   }
 
+  /** Loads content for complete dataset operations without viewport-based request priority. */
+  async loadContentForTraversal(): Promise<TileContentLoadResult> {
+    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. */
+  private async _loadContentFromSource(): Promise<TileContentLoadResult> {
+    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.
    *
@@ -665,34 +713,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.
@@ -704,6 +855,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();
     }
@@ -848,9 +1006,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,
@@ -913,6 +1077,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 {
@@ -969,7 +1137,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;
     }
@@ -1074,11 +1242,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
@@ -1088,7 +1258,8 @@ export class Tile3D {
       this._viewerRequestVolume = createBoundingVolume(
         header.viewerRequestVolume,
         this.computedTransform,
-        this._viewerRequestVolume
+        this._viewerRequestVolume,
+        this._initialTransform
       );
     }
 
@@ -1106,7 +1277,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

@@ -58,17 +58,6 @@ export type Tileset3DProps = {
    * @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;
 
@@ -158,10 +147,6 @@ type Props = {
   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;
   onTileLoad: (tile: Tile3D) => void;
@@ -241,31 +226,21 @@ function validateCacheByteLength(value: number, optionName: string): number {
 }
 
 /**
- * Resolves the base cache target from byte-native or deprecated mebibyte options.
+ * Resolves the base cache target from the byte-native option or its fallback.
  *
- * 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 options - Options that may contain a byte-native cache value.
  * @param fallbackCacheBytes - Existing or default cache target in bytes.
  * @returns The resolved and validated cache target in bytes.
  */
 function resolveCacheBytes(options: Tileset3DProps, fallbackCacheBytes: number): number {
-  const cacheBytes =
-    options.cacheBytes ??
-    (options.maximumMemoryUsage !== undefined
-      ? options.maximumMemoryUsage * BYTES_PER_MEBIBYTE
-      : fallbackCacheBytes);
+  const cacheBytes = options.cacheBytes ?? 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.
+ * Resolves cache overflow headroom from the byte-native option or its fallback.
  *
- * @param options - Options that may contain byte-native or deprecated overflow values.
+ * @param options - Options that may contain a byte-native overflow value.
  * @param fallbackOverflowBytes - Existing or default overflow headroom in bytes.
  * @returns The resolved and validated overflow headroom in bytes.
  */
@@ -273,11 +248,7 @@ function resolveMaximumCacheOverflowBytes(
   options: Tileset3DProps,
   fallbackOverflowBytes: number
 ): number {
-  const maximumCacheOverflowBytes =
-    options.maximumCacheOverflowBytes ??
-    (options.memoryCacheOverflow !== undefined
-      ? options.memoryCacheOverflow * BYTES_PER_MEBIBYTE
-      : fallbackOverflowBytes);
+  const maximumCacheOverflowBytes = options.maximumCacheOverflowBytes ?? fallbackOverflowBytes;
   return validateCacheByteLength(maximumCacheOverflowBytes, 'maximumCacheOverflowBytes');
 }
 
@@ -289,8 +260,6 @@ const DEFAULT_PROPS: Props = {
   maxRequests: 64,
   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: () => {},
@@ -456,8 +425,6 @@ export class Tileset3D {
       ...suppliedOptions,
       cacheBytes,
       maximumCacheOverflowBytes,
-      maximumMemoryUsage: cacheBytes / BYTES_PER_MEBIBYTE,
-      memoryCacheOverflow: maximumCacheOverflowBytes / BYTES_PER_MEBIBYTE,
       memoryAdjustedScreenSpaceError:
         suppliedOptions.memoryAdjustedScreenSpaceError ?? usesTiles3DCacheDefaults
     };
@@ -517,6 +484,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.
    *
@@ -532,7 +519,6 @@ export class Tileset3D {
   set cacheBytes(value: number) {
     this._cacheBytes = validateCacheByteLength(value, 'cacheBytes');
     this.options.cacheBytes = this._cacheBytes;
-    this.options.maximumMemoryUsage = this._cacheBytes / BYTES_PER_MEBIBYTE;
   }
 
   /**
@@ -549,19 +535,6 @@ export class Tileset3D {
   set maximumCacheOverflowBytes(value: number) {
     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(): number {
-    return this.cacheBytes / BYTES_PER_MEBIBYTE;
-  }
-
-  set maximumMemoryUsage(value: number) {
-    this.cacheBytes = validateCacheByteLength(value * BYTES_PER_MEBIBYTE, 'maximumMemoryUsage');
   }
 
   get queryParams(): string {
@@ -571,10 +544,7 @@ export class Tileset3D {
   }
 
   /**
-   * 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.
+   * Updates traversal and runtime options while retaining unspecified byte budgets.
    *
    * @param props - Partial runtime options to apply.
    */
@@ -588,9 +558,7 @@ export class Tileset3D {
       ...this.options,
       ...props,
       cacheBytes,
-      maximumCacheOverflowBytes,
-      maximumMemoryUsage: cacheBytes / BYTES_PER_MEBIBYTE,
-      memoryCacheOverflow: maximumCacheOverflowBytes / BYTES_PER_MEBIBYTE
+      maximumCacheOverflowBytes
     };
     this._cacheBytes = cacheBytes;
     this._maximumCacheOverflowBytes = maximumCacheOverflowBytes;
@@ -662,6 +630,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++;
@@ -909,7 +885,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();