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

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
     };
@@ -552,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;
   }
 
   /**
@@ -569,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 {
@@ -591,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.
    */
@@ -608,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;

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-source.ts

@@ -221,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.
    */
@@ -239,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/format-3d-tiles/tiles-3d-source.ts

@@ -521,6 +521,17 @@ export class Tiles3DSource implements Tileset3DSource {
     };
   }
 
+  /** Loads an implicit subtree for dataset traversal without camera state. */
+  async loadTileChildrenForTraversal(
+    tile: Tile3D,
+    signal?: AbortSignal
+  ): Promise<TileChildrenLoadResult> {
+    throwIfTraversalAborted(signal);
+    const result = await this.loadTileChildren(tile, {} as FrameState);
+    throwIfTraversalAborted(signal);
+    return result;
+  }
+
   /**
    * Returns a snapshot of implicit-subtree request, cache, and materialization counters.
    *
@@ -939,6 +950,13 @@ export class Tiles3DSource implements Tileset3DSource {
   }
 }
 
+/** Throws a cancellation reason before or after source-managed traversal work. */
+function throwIfTraversalAborted(signal?: AbortSignal): void {
+  if (signal?.aborted) {
+    throw signal.reason ?? new DOMException('The operation was aborted', 'AbortError');
+  }
+}
+
 function isTilesetRequest(input: TilesetSourceInput): input is TilesetSourceRequest {
   return Boolean(
     input && typeof input === 'object' && 'url' in input && 'loader' in input && !('type' in input)

package/src/tileset-3d/format-i3s/i3s-source.ts

@@ -8,10 +8,12 @@ import {Vector3} from '@math.gl/core';
 import type {CoreAPI, Loader, LoaderOptions} from '@loaders.gl/loader-utils';
 import type {Tile3D} from '../common/tile-3d';
 import {Tile3D as Tile3DNode} from '../common/tile-3d';
+import type {Tile3DContent} from '../common/tile-3d-contracts';
 import {I3STilesetTraverser} from './i3s-tileset-traverser';
 import type {Tileset3D} from '../common/tileset-3d';
 import type {FrameState} from '../helpers/frame-state';
 import type {
+  TileChildrenLoadResult,
   TileContentLoadResult,
   TilesetContentFormats,
   TilesetJSON,
@@ -219,7 +221,17 @@ export class I3SSource implements Tileset3DSource {
     };
 
     tile.content = await this.loadResourceData(contentUrl, options, this.contentLoader);
-    return {loaded: true};
+    const contentEntry: Tile3DContent = {
+      index: 0,
+      uri: tile.contentUrl,
+      type: tile.header.layerType,
+      payload: tile.content,
+      metadata: tile.header.metadata || null,
+      boundingVolume: tile.boundingVolume,
+      featureIds: tile.featureIdSets,
+      renderable: Boolean(tile.content)
+    };
+    return {loaded: true, contents: [tile.content], contentEntries: [contentEntry]};
   }
 
   /**
@@ -228,7 +240,7 @@ export class I3SSource implements Tileset3DSource {
   async loadChildTileHeader(
     _parentTile: Tile3D,
     childId: string,
-    _frameState: FrameState
+    _frameState: FrameState | null
   ): Promise<any> {
     const metadata = this.getMetadata();
     if (metadata.tileset.nodePages || metadata.tileset.pointNodePages) {
@@ -253,6 +265,50 @@ export class I3SSource implements Tileset3DSource {
     return await this.transformTileHeader(header);
   }
 
+  /** Loads all declared I3S child headers without camera or visibility state. */
+  async loadTileChildrenForTraversal(
+    parentTile: Tile3D,
+    signal?: AbortSignal
+  ): Promise<TileChildrenLoadResult> {
+    const childHeaders = parentTile.header.children || [];
+    let loadedChildren = 0;
+    const orderedChildren: Tile3D[] = [];
+
+    for (const childHeader of childHeaders) {
+      throwIfTraversalAborted(signal);
+      const childId = childHeader.id;
+      if (typeof childId !== 'string' && typeof childId !== 'number') {
+        throw new Error('I3S child header is missing its node ID');
+      }
+      const existingChild = parentTile.children.find(
+        tile => tile.id === String(childId) || tile.header?.id === childId
+      );
+      if (existingChild) {
+        orderedChildren.push(existingChild);
+        continue;
+      }
+
+      const childTileHeader = await this.loadChildTileHeader(parentTile, String(childId), null);
+      throwIfTraversalAborted(signal);
+      const childTile = new Tile3DNode(
+        parentTile.tileset,
+        childTileHeader,
+        parentTile,
+        String(childId)
+      );
+      orderedChildren.push(childTile);
+      loadedChildren++;
+    }
+
+    const orderedChildSet = new Set(orderedChildren);
+    parentTile.children = [
+      ...orderedChildren,
+      ...parentTile.children.filter(childTile => !orderedChildSet.has(childTile))
+    ];
+
+    return {loaded: true, tileCount: loadedChildren, childSubtreeCount: 0};
+  }
+
   /**
    * Resolves an I3S request URL with source-managed query parameters.
    */
@@ -265,24 +321,28 @@ export class I3SSource implements Tileset3DSource {
       return tilePath;
     }
 
-    const queryDelimiterIndex = tilePath.indexOf('?');
-    if (queryDelimiterIndex === -1) {
-      return `${tilePath}?${new URLSearchParams(this.queryParams).toString()}`;
-    }
-
-    const existingQuery = tilePath.slice(queryDelimiterIndex + 1);
-    const existingQueryKeys = new Set(
-      existingQuery.split('&').map(parameter => parameter.split('=', 1)[0])
-    );
+    const hashIndex = tilePath.indexOf('#');
+    const hash = hashIndex >= 0 ? tilePath.slice(hashIndex) : '';
+    const tilePathWithoutHash = hashIndex >= 0 ? tilePath.slice(0, hashIndex) : tilePath;
+    const queryDelimiterIndex = tilePathWithoutHash.indexOf('?');
+    const path =
+      queryDelimiterIndex === -1
+        ? tilePathWithoutHash
+        : tilePathWithoutHash.slice(0, queryDelimiterIndex);
+    const existingQuery =
+      queryDelimiterIndex === -1 ? '' : tilePathWithoutHash.slice(queryDelimiterIndex + 1);
+    const existingQueryParams = new URLSearchParams(existingQuery);
     const queryParams = new URLSearchParams();
     for (const [key, value] of Object.entries(this.queryParams)) {
-      if (!existingQueryKeys.has(key)) {
+      if (!existingQueryParams.has(key)) {
         queryParams.set(key, value);
       }
     }
 
     const queryString = queryParams.toString();
-    return queryString ? `${tilePath}${existingQuery ? '&' : ''}${queryString}` : tilePath;
+    return `${path}${existingQuery ? `?${existingQuery}` : ''}${
+      queryString ? `${existingQuery ? '&' : '?'}${queryString}` : ''
+    }${hash}`;
   }
 
   /**
@@ -403,6 +463,10 @@ export class I3SSource implements Tileset3DSource {
    * @param loadOptions Loader options that may contain an ArcGIS token.
    */
   private initializeQueryParams(loadOptions: LoaderOptions): void {
+    for (const [key, value] of Object.entries(loadOptions.searchParams || {})) {
+      this.queryParams[key] = String(value);
+    }
+
     const i3sOptions = loadOptions.i3s;
     if (i3sOptions && typeof i3sOptions === 'object' && 'token' in i3sOptions) {
       const token = (i3sOptions as Record<string, unknown>).token;
@@ -449,6 +513,13 @@ export class I3SSource implements Tileset3DSource {
   }
 }
 
+/** Throws a cancellation reason before or after source-managed traversal work. */
+function throwIfTraversalAborted(signal?: AbortSignal): void {
+  if (signal?.aborted) {
+    throw signal.reason ?? new DOMException('The operation was aborted', 'AbortError');
+  }
+}
+
 /** Returns the format-provided binary content loader, falling back for custom legacy loaders. */
 function getI3SContentLoader(loader: Loader): Loader {
   return (loader as Loader & {contentLoader?: Loader}).contentLoader || loader;

package/src/tileset-3d/format-i3s/i3s-tileset-traverser.ts

@@ -38,7 +38,8 @@ export class I3STilesetTraverser extends TilesetTraverser {
     for (const child of children) {
       const extendedId = `${child.id}-${frameState.viewport.id}`;
       // if child tile is not fetched
-      const childTile = childTiles && childTiles.find(t => t.id === extendedId);
+      const childTile =
+        childTiles && childTiles.find(t => t.id === extendedId || t.header?.id === child.id);
       if (!childTile) {
         const request = () => this._loadTile(tile, child.id, frameState);
         const cachedRequest = this._tileManager.find(extendedId);

package/src/tileset-3d/helpers/frame-state.ts

@@ -30,7 +30,8 @@ export type FrameState = {
   /** Optional world-space clipping planes applied to render-content culling. */
   clippingPlanes?: Plane[];
   frameNumber: number; // TODO: This can be the same between updates, what number is unique for between updates?
-  sseDenominator: number; // Assumes fovy = 60 degrees
+  /** Perspective projection factor: twice the tangent of half the vertical field of view. */
+  sseDenominator: number;
   /** View-dependent density used by perspective dynamic screen-space error for this traversal. */
   dynamicScreenSpaceErrorDensity: number;
 };
@@ -151,6 +152,11 @@ export function getFrameState(
     pitch: 0
   });
 
+  const verticalFieldOfView =
+    Number.isFinite(viewport.fovy) && Number(viewport.fovy) > 0 && Number(viewport.fovy) < 180
+      ? (Number(viewport.fovy) * Math.PI) / 180
+      : Math.PI / 3;
+
   // TODO: make a file/class for frameState and document what needs to be attached to this so that traversal can function
   return {
     camera: {
@@ -158,10 +164,7 @@ export function getFrameState(
       direction: cameraDirectionCartesian,
       up: cameraUpCartesian,
       cartographicPosition: cameraPositionCartographic,
-      verticalFieldOfView:
-        Number.isFinite(viewport.fovy) && Number(viewport.fovy) > 0
-          ? (Number(viewport.fovy) * Math.PI) / 180
-          : Math.PI / 3,
+      verticalFieldOfView,
       timeSinceMovement: options.timeSinceCameraMovement ?? Number.POSITIVE_INFINITY
     },
     viewport,
@@ -170,7 +173,7 @@ export function getFrameState(
     cullingVolume,
     clippingPlanes: viewport.clippingPlanes,
     frameNumber, // TODO: This can be the same between updates, what number is unique for between updates?
-    sseDenominator: 1.15, // Assumes fovy = 60 degrees
+    sseDenominator: 2 * Math.tan(verticalFieldOfView / 2),
     // Tileset3D fills this immediately before traversal because it depends on the root volume.
     dynamicScreenSpaceErrorDensity: 0
   };