@loaders.gl/tiles 4.4.5 → 5.0.0-alpha.2

package/src/{tileset → tileset-3d/common}/tileset-cache.ts

@@ -7,7 +7,7 @@
 
 import type {Tileset3D} from './tileset-3d';
 import type {Tile3D} from './tile-3d';
-import {DoublyLinkedList} from '../utils/doubly-linked-list';
+import {DoublyLinkedList} from '../../utils/doubly-linked-list';
 
 /**
  * Stores tiles with content loaded.
@@ -71,24 +71,32 @@ export class TilesetCache {
     }
   }
 
-  unloadTiles(tileset, unloadCallback): void {
+  /**
+   * Unloads least-recently-used tiles until the byte-native cache target is met.
+   *
+   * Tiles touched after the frame sentinel remain protected, so {@link Tileset3D.cacheBytes} is a
+   * soft target rather than a hard cap on the visible working set. Overflow headroom affects
+   * memory-adjusted SSE, not eviction of unused tiles.
+   *
+   * @param tileset - Tileset that owns the cache and reports estimated content memory.
+   * @param unloadCallback - Callback that releases content and decrements the memory estimate.
+   */
+  unloadTiles(
+    tileset: Tileset3D,
+    unloadCallback?: (tileset: Tileset3D, tile: Tile3D) => void
+  ): void {
     const trimTiles = this._trimTiles;
     this._trimTiles = false;
 
     const list = this._list;
 
-    const maximumMemoryUsageInBytes = tileset.maximumMemoryUsage * 1024 * 1024;
-
     // Traverse the list only to the sentinel since tiles/nodes to the
     // right of the sentinel were used this frame.
     // The sub-list to the left of the sentinel is ordered from LRU to MRU.
     const sentinel = this._sentinel;
     let node = list.head;
 
-    while (
-      node !== sentinel &&
-      (tileset.gpuMemoryUsageInBytes > maximumMemoryUsageInBytes || trimTiles)
-    ) {
+    while (node !== sentinel && (tileset.gpuMemoryUsageInBytes > tileset.cacheBytes || trimTiles)) {
       // @ts-expect-error
       const tile = node.item;
       // @ts-expect-error

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

@@ -0,0 +1,255 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import type {CoreAPI, LoaderOptions, LoaderWithParser} 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';
+import type {Tileset3D} from './tileset-3d';
+import type {FrameState} from '../helpers/frame-state';
+import type {TILESET_TYPE} from '../../constants';
+
+/**
+ * Parsed top-level tileset payload consumed by {@link Tileset3D} or a {@link Tileset3DSource}.
+ */
+export type TilesetJSON = any;
+
+/**
+ * Resource-loading strategy used by source implementations to fetch and parse root metadata
+ * and tile resources.
+ */
+export type TilesetSourceResolver = {
+  /**
+   * Loads and parses the root metadata resource for a source.
+   */
+  loadRoot<DataT>(
+    url: string,
+    loader: LoaderWithParser<DataT>,
+    loadOptions: LoaderOptions
+  ): Promise<DataT>;
+
+  /**
+   * Loads and parses an arbitrary source-relative resource.
+   */
+  loadResource<DataT>(
+    url: string,
+    loader: LoaderWithParser<DataT>,
+    loadOptions: LoaderOptions
+  ): Promise<DataT>;
+};
+
+/**
+ * URL-based source input used when a source is responsible for fetching root metadata.
+ */
+export type TilesetSourceRequest = {
+  /** Absolute root metadata URL. */
+  url: string;
+  /** Loader used to fetch and parse the root metadata. */
+  loader: LoaderWithParser;
+  /** Optional base path override for relative resources. */
+  basePath?: string;
+  /** Optional resource-loading strategy used for archive-backed datasets. */
+  resolver?: TilesetSourceResolver;
+  /** Optional core API implementation used for nested source loading. */
+  coreApi?: CoreAPI;
+};
+
+/**
+ * Constructor input accepted by explicit source implementations.
+ *
+ * Request descriptors are the public path. Preloaded metadata remains useful for tests and
+ * internal call sites that already own parsed root metadata.
+ */
+export type TilesetSourceInput = TilesetJSON | TilesetSourceRequest;
+
+/**
+ * Result of a source-managed tile content request.
+ */
+export type TileContentLoadResult = {
+  /** Whether the tile content request produced usable content. */
+  loaded: boolean;
+  /** Nested tileset metadata to install below the loaded tile, if any. */
+  nestedTileset?: TilesetJSON;
+};
+
+/** Result of a source-managed lazy child-header request. */
+export type TileChildrenLoadResult = {
+  /** Whether a subtree resource was loaded and installed. */
+  loaded: boolean;
+  /** Number of available tiles described by the subtree, including its existing root placeholder. */
+  tileCount: number;
+  /** Number of lazy child-subtree references installed at the new boundary. */
+  childSubtreeCount: number;
+};
+
+/**
+ * Flags describing compression and texture formats observed while streaming tile content.
+ */
+export type TilesetContentFormats = {
+  draco: boolean;
+  meshopt: boolean;
+  dds: boolean;
+  ktx2: boolean;
+};
+
+/**
+ * Optional view-state metadata exposed by a {@link Tileset3DSource} after initialization.
+ */
+export type TilesetSourceViewState = {
+  cartographicCenter?: Vector3 | null;
+  cartesianCenter?: Vector3 | null;
+  zoom?: number;
+  boundingVolume?: any;
+  description?: string;
+  properties?: any;
+  extras?: any;
+  credits?: any;
+  asset?: Record<string, any>;
+};
+
+/**
+ * Normalized source metadata consumed by {@link Tileset3D}.
+ */
+export type TilesetSourceMetadata = {
+  /** Format discriminator. */
+  type: TILESET_TYPE;
+  /** Loader used for metadata and content requests. */
+  loader: LoaderWithParser;
+  /** Absolute root metadata URL. */
+  url: string;
+  /** Base path used for relative resource resolution. */
+  basePath: string;
+  /** Parsed and normalized source payload. */
+  tileset: TilesetJSON;
+  /** Root lod metric type used as fallback by runtime tiles. */
+  lodMetricType: string;
+  /** Root lod metric value used as fallback by runtime tiles. */
+  lodMetricValue: number;
+  /** Root refinement mode used as fallback by runtime tiles. */
+  refine: string;
+};
+
+/**
+ * Format-specific adapter used by {@link Tileset3D} for initialization, loading, and metadata access.
+ */
+export interface Tileset3DSource {
+  /** Tileset format discriminator. */
+  readonly type: TILESET_TYPE;
+  /** Loader used for content and metadata requests. */
+  readonly loader: LoaderWithParser;
+  /** Absolute URL of the root tileset resource. */
+  readonly url: string;
+  /** Base directory used for relative resource resolution. */
+  readonly basePath: string;
+  /** Source-specific root tileset payload, when available. */
+  readonly tileset?: TilesetJSON | null;
+  /** Loader options forwarded to metadata and content requests. */
+  readonly loadOptions: LoaderOptions;
+  /** Core API used for source-managed loads, when injected by the caller. */
+  coreApi?: CoreAPI;
+  /** Accumulated content-format flags for the tileset. */
+  readonly contentFormats: TilesetContentFormats;
+  /** Format-specific asset metadata, if any. */
+  asset?: Record<string, any>;
+  /** Per-feature property schema, if any. */
+  properties?: any;
+  /** Application-specific root metadata, if any. */
+  extras?: any;
+  /** Attribution and credit metadata, if any. */
+  credits?: any;
+
+  /** Normalized source metadata after initialization. */
+  metadata?: TilesetSourceMetadata;
+
+  /**
+   * Initializes source state before traversal begins.
+   */
+  initialize(): Promise<void>;
+
+  /** Releases source-local caches and prevents late asynchronous work from mutating runtime tiles. */
+  destroy?(): void;
+
+  /**
+   * Returns normalized source metadata after initialization completes.
+   */
+  getMetadata(): TilesetSourceMetadata;
+
+  /**
+   * Returns the root tileset payload after source initialization completes.
+   */
+  getRootTileset(): Promise<TilesetJSON>;
+
+  /**
+   * Creates the runtime tile tree for a tileset payload or nested subtree.
+   */
+  initializeTileHeaders(
+    tileset: Tileset3D,
+    tilesetJson: TilesetJSON,
+    parentTile?: Tile3D | null
+  ): Tile3D;
+
+  /**
+   * Creates the traverser implementation appropriate for this source.
+   */
+  createTraverser(options: TilesetTraverserProps): TilesetTraverser;
+
+  /**
+   * Loads renderable content for a tile.
+   */
+  loadTileContent(tile: Tile3D): Promise<TileContentLoadResult>;
+
+  /**
+   * Loads and installs a complete lazy child-header group for a runtime tile.
+   *
+   * Sources that implement this hook retain ownership of resource parsing, caching, query
+   * inheritance, and archive resolution. Traversal calls it only after visibility and LOD checks.
+   */
+  loadTileChildren?(tile: Tile3D, frameState: FrameState): Promise<TileChildrenLoadResult>;
+
+  /**
+   * Resolves a tile-relative path to the final request URL.
+   */
+  getTileUrl(tilePath: string): string;
+
+  /**
+   * Returns tileset-level view metadata derived from the loaded source.
+   */
+  getViewState(rootTile: Tile3D | null): TilesetSourceViewState;
+
+  /**
+   * Checks whether the source declares a specific extension.
+   */
+  hasExtension?(extensionName: string): boolean;
+
+  /**
+   * 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>;
+
+  /**
+   * Updates source-managed bookkeeping after a tile finishes loading.
+   */
+  onTileLoaded?(tileset: Tileset3D, tile: Tile3D, loadResult: TileContentLoadResult): void;
+
+  /**
+   * Returns the total known tile count for stats, if available.
+   */
+  getTilesTotalCount?(): number | null;
+}
+
+/**
+ * Type guard for distinguishing a source-backed constructor input from other runtime values.
+ * @param value Value to test.
+ * @returns `true` when the value implements the {@link Tileset3DSource} contract.
+ */
+export function isTileset3DSource(value: unknown): value is Tileset3DSource {
+  return Boolean(
+    value &&
+      typeof value === 'object' &&
+      'initialize' in value &&
+      'getRootTileset' in value &&
+      'initializeTileHeaders' in value &&
+      'loadTileContent' in value
+  );
+}

package/src/{tileset → tileset-3d/common}/tileset-traverser.ts

@@ -3,9 +3,9 @@
 // Copyright (c) vis.gl contributors
 
 import type {Tile3D} from './tile-3d';
-import {ManagedArray} from '../utils/managed-array';
-import {TILE_REFINEMENT} from '../constants';
-import {FrameState} from './helpers/frame-state';
+import {ManagedArray} from '../../utils/managed-array';
+import {TILE_REFINEMENT} from '../../constants';
+import {FrameState} from '../helpers/frame-state';
 
 export type TilesetTraverserProps = {
   loadSiblings?: boolean;
@@ -35,6 +35,8 @@ export class TilesetTraverser {
   selectedTiles: Record<string, Tile3D> = {};
   // tiles should be loaded from server
   requestedTiles: Record<string, Tile3D> = {};
+  /** Tiles intentionally held until the camera has remained still for the configured delay. */
+  deferredTiles: Record<string, Tile3D> = {};
   // tiles does not have render content
   emptyTiles: Record<string, Tile3D> = {};
 
@@ -73,6 +75,7 @@ export class TilesetTraverser {
 
   reset() {
     this.requestedTiles = {};
+    this.deferredTiles = {};
     this.selectedTiles = {};
     this.emptyTiles = {};
     this._traversalStack.reset();
@@ -235,12 +238,30 @@ export class TilesetTraverser {
   // tile to load from server
   loadTile(tile: Tile3D, frameState: FrameState): void {
     if (this.shouldLoadTile(tile)) {
+      if (this.shouldDeferTileRequest(tile)) {
+        this.deferredTiles[tile.id] = tile;
+        return;
+      }
       tile._requestedFrame = frameState.frameNumber;
       tile._priority = tile._getPriority();
       this.requestedTiles[tile.id] = tile;
     }
   }
 
+  /**
+   * Returns whether an eligible peripheral request should wait for camera motion to settle.
+   *
+   * Eligibility and the current time window are calculated together when tile visibility updates.
+   * Keeping the active state on the tile also lets a queued scheduler callback cancel work that
+   * became deferred after its original traversal.
+   *
+   * @param tile - Tile considered for loading.
+   * @returns `true` when the request should be retried after the remaining delay.
+   */
+  shouldDeferTileRequest(tile: Tile3D): boolean {
+    return tile.priorityDeferred;
+  }
+
   // cache tile
   touchTile(tile: Tile3D, frameState: FrameState): void {
     tile.tileset._cache.touch(tile);
@@ -323,6 +344,7 @@ export class TilesetTraverser {
   // Ignores visibility.
   executeEmptyTraversal(root: Tile3D, frameState: FrameState): boolean {
     let allDescendantsLoaded = true;
+    let hasPendingLazyChildren = false;
     const stack = this._emptyTraversalStack;
     stack.push(root);
 
@@ -331,6 +353,12 @@ export class TilesetTraverser {
 
       const traverse = !tile.hasRenderContent && this.canTraverse(tile, frameState);
       const emptyLeaf = !tile.hasRenderContent && tile.children.length === 0;
+      if (tile.header.implicitSubtree) {
+        // An unresolved implicit boundary is not a proven empty leaf. Treating it as loaded would
+        // allow REPLACE traversal to drop its ancestor before availability and content are known.
+        hasPendingLazyChildren = true;
+        allDescendantsLoaded = false;
+      }
 
       // Traversal stops but the tile does not have content yet
       // There will be holes if the parent tries to refine to its children, so don't refine
@@ -353,6 +381,6 @@ export class TilesetTraverser {
         }
       }
     }
-    return root.hasEmptyContent || allDescendantsLoaded;
+    return (root.hasEmptyContent && !hasPendingLazyChildren) || allDescendantsLoaded;
   }
 }