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

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

@@ -0,0 +1,114 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {Tile3D} from './tile-3d';
+import type {Tileset3D} from './tileset-3d';
+import type {TileContentLoadResult} from './tileset-source';
+import type {Tile3DContent} from './tile-3d-contracts';
+import {TILESET_TYPE} from '../../constants';
+
+/** Options for complete camera-independent tileset content traversal. */
+export interface TraverseTilesetContentsOptions {
+  /** Cancel traversal and stop issuing further source requests. */
+  readonly signal?: AbortSignal;
+  /**
+   * Unload content loaded by this traversal when iteration advances or closes, including on error.
+   * Defaults to false. Preloaded content is retained. Use a runtime dedicated to this traversal;
+   * consume payloads before advancing and do not retain them or update the runtime concurrently.
+   */
+  readonly unloadContent?: boolean;
+}
+
+/** One tile placement and its ordered content entries from a completed source read. */
+export interface TilesetContentTraversalItem {
+  /** Runtime tile placement. Shared content resources are yielded once per placement. */
+  readonly tile: Tile3D;
+  /** Ordered content entries, including multiple contents declared by a single tile. */
+  readonly contents: readonly Tile3DContent[];
+}
+
+/**
+ * Walks every declared tile placement and its loaded content without a camera or visibility test.
+ *
+ * Source implementations remain responsible for lazy subtree and node-page resolution. Children
+ * are visited in declaration order, nested tilesets are installed by the source before descent,
+ * and repeated resource URLs are not deduplicated because each placement can have a distinct
+ * transform. Content stays attached unless `unloadContent` is enabled. In that mode, newly loaded
+ * payloads are valid until iteration advances or closes. Tile placements and children remain
+ * available; callers still own the tileset, source, and archive lifetime.
+ *
+ * @param tileset - Initialized or initializing source-backed tileset runtime.
+ * @param options - Cancellation and decoded-content lifetime options.
+ * @returns One item for each visited tile placement in deterministic depth-first order.
+ */
+export async function* traverseTilesetContents(
+  tileset: Tileset3D,
+  options: TraverseTilesetContentsOptions = {}
+): AsyncGenerator<TilesetContentTraversalItem> {
+  await tileset.tilesetInitializationPromise;
+  throwIfAborted(options.signal);
+  if (!tileset.root) {
+    throw new Error('Tileset initialization completed without a root tile');
+  }
+
+  const stack: Tile3D[] = [tileset.root];
+  const visitedTiles = new Set<Tile3D>();
+  while (stack.length > 0) {
+    throwIfAborted(options.signal);
+    const tile = stack.pop() as Tile3D;
+    if (visitedTiles.has(tile)) {
+      continue;
+    }
+    visitedTiles.add(tile);
+
+    if (tile.header.implicitSubtree && tile.childrenState !== 'ready') {
+      const loadChildren = tileset.source.loadTileChildrenForTraversal;
+      if (!loadChildren) {
+        throw new Error('Tileset source does not support camera-independent subtree loading');
+      }
+      const result = await loadChildren.call(tileset.source, tile, options.signal);
+      if (!result.loaded) {
+        throw new Error(`Unable to load implicit subtree for tile ${tile.id}`);
+      }
+      tile.childrenState = 'ready';
+    }
+
+    if (tileset.type === TILESET_TYPE.I3S && tileset.source.loadTileChildrenForTraversal) {
+      const result = await tileset.source.loadTileChildrenForTraversal(tile, options.signal);
+      if (!result.loaded) {
+        throw new Error(`Unable to load I3S child nodes for tile ${tile.id}`);
+      }
+    }
+
+    throwIfAborted(options.signal);
+    const loadsContent = tile.contentUrls.length > 0 && !tile.content;
+    try {
+      if (loadsContent) {
+        const loadResult: TileContentLoadResult = await tile.loadContentForTraversal();
+        throwIfAborted(options.signal);
+        if (!loadResult.loaded) {
+          throw new Error(`Unable to load tile content for tile ${tile.id}`);
+        }
+        tileset.source.onTileLoaded?.(tileset, tile, loadResult);
+      }
+
+      yield {tile, contents: tile.contentEntries};
+    } finally {
+      if (options.unloadContent && loadsContent) {
+        tile.unloadContent();
+      }
+    }
+
+    for (let childIndex = tile.children.length - 1; childIndex >= 0; childIndex--) {
+      stack.push(tile.children[childIndex]);
+    }
+  }
+}
+
+/** Throws the signal reason when traversal is cancelled. */
+function throwIfAborted(signal?: AbortSignal): void {
+  if (signal?.aborted) {
+    throw signal.reason ?? new DOMException('The operation was aborted', 'AbortError');
+  }
+}

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

@@ -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}.
@@ -68,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. */
@@ -218,6 +221,17 @@ export interface Tileset3DSource {
    */
   loadTileChildren?(tile: Tile3D, frameState: FrameState): Promise<TileChildrenLoadResult>;
 
+  /**
+   * Loads all source-managed child headers without requiring camera or visibility state.
+   *
+   * This hook is used by complete dataset operations such as conversion. Implementations retain
+   * ownership of implicit subtrees, node pages, archive resolution, and query inheritance.
+   */
+  loadTileChildrenForTraversal?(
+    tile: Tile3D,
+    signal?: AbortSignal
+  ): Promise<TileChildrenLoadResult>;
+
   /**
    * Resolves a tile-relative path to the final request URL.
    */
@@ -236,7 +250,11 @@ export interface Tileset3DSource {
   /**
    * Loads child tile metadata on demand for formats that do not expose the full tree up front.
    */
-  loadChildTileHeader?(parentTile: Tile3D, childId: string, frameState: FrameState): Promise<any>;
+  loadChildTileHeader?(
+    parentTile: Tile3D,
+    childId: string,
+    frameState: FrameState | null
+  ): Promise<any>;
 
   /**
    * Updates source-managed bookkeeping after a tile finishes loading.

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

@@ -219,9 +219,10 @@ export class TilesetTraverser {
         }
         stack.push(child);
         hasVisibleChild = true;
-      } else if (checkRefines || loadSiblings) {
-        // Keep non-visible children loaded since they are still needed before the parent can refine.
-        // Or loadSiblings is true so always load tiles regardless of visibility.
+      } else if ((checkRefines || loadSiblings) && child._inRequestVolume) {
+        // Keep non-visible children loaded when they are inside their viewer request volume;
+        // they may still be needed before a replacement parent can refine. The request-volume
+        // check intentionally applies to sibling loading as well, preventing off-volume work.
         this.loadTile(child, frameState);
         this.touchTile(child, frameState);
       }