@loaders.gl/tiles 4.4.2 → 5.0.0-alpha.1

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.

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

@@ -0,0 +1,234 @@
+// 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;
+};
+
+/**
+ * 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>;
+
+  /**
+   * 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>;
+
+  /**
+   * 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;

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

@@ -0,0 +1,379 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {path} from '@loaders.gl/loader-utils';
+import {Ellipsoid} from '@math.gl/geospatial';
+import {Vector3} from '@math.gl/core';
+import type {CoreAPI, LoaderOptions, LoaderWithParser} from '@loaders.gl/loader-utils';
+import type {Tile3D} from '../common/tile-3d';
+import {Tileset3DTraverser} from './tileset-3d-traverser';
+import type {Tileset3D} from '../common/tileset-3d';
+import type {
+  TileContentLoadResult,
+  TilesetContentFormats,
+  TilesetJSON,
+  Tileset3DSource,
+  TilesetSourceInput,
+  TilesetSourceMetadata,
+  TilesetSourceRequest,
+  TilesetSourceResolver,
+  TilesetSourceViewState
+} from '../common/tileset-source';
+import {Tile3D as Tile3DNode} from '../common/tile-3d';
+import {getZoomFromBoundingVolume} from '../helpers/zoom';
+import {TILESET_TYPE} from '../../constants';
+import type {TilesetTraverser, TilesetTraverserProps} from '../common/tileset-traverser';
+
+const EMPTY_CONTENT_FORMATS: TilesetContentFormats = {
+  draco: false,
+  meshopt: false,
+  dds: false,
+  ktx2: false
+};
+
+/**
+ * {@link Tileset3DSource} implementation for 3D Tiles datasets.
+ */
+export class Tiles3DSource implements Tileset3DSource {
+  /** 3D Tiles format discriminator. */
+  readonly type = TILESET_TYPE.TILES3D;
+  /** Loader used for tile content requests. */
+  readonly loader: LoaderWithParser;
+  /** Root tileset URL. */
+  readonly url: string;
+  /** Base path used for relative tile resource resolution. */
+  readonly basePath: string;
+  /** Parsed root tileset payload. */
+  tileset: TilesetJSON | null = null;
+  /** Loader options forwarded to content requests. */
+  readonly loadOptions: LoaderOptions;
+  /** Core API used for root and tile-content loads when injected by the caller. */
+  coreApi?: CoreAPI;
+  /** Aggregate content-format flags discovered during streaming. */
+  readonly contentFormats: TilesetContentFormats = {...EMPTY_CONTENT_FORMATS};
+
+  /** Top-level 3D Tiles asset metadata. */
+  asset?: Record<string, any>;
+  /** Top-level per-feature properties metadata. */
+  properties?: any;
+  /** Top-level application-specific metadata. */
+  extras?: any;
+  /** Source-provided attribution metadata. */
+  credits?: any;
+  /** Normalized source metadata after initialization. */
+  metadata?: TilesetSourceMetadata;
+
+  private readonly queryParams: Record<string, string> = {};
+  private readonly extensionsUsed: string[] = [];
+  private readonly resolver?: TilesetSourceResolver;
+  private rootTileset: TilesetJSON;
+
+  /**
+   * Creates a 3D Tiles source.
+   * @param input Root metadata request, or preloaded root metadata for tests and internal callers.
+   * @param loadOptions Loader options forwarded to tile requests.
+   */
+  constructor(input: TilesetSourceInput, loadOptions: LoaderOptions = {}) {
+    const request = normalizeTiles3DRequest(input);
+    this.rootTileset = isTilesetRequest(input) ? null : input;
+    this.tileset = this.rootTileset;
+    this.loader = request.loader;
+    this.url = request.url;
+    this.basePath = request.basePath || path.dirname(request.url);
+    this.resolver = request.resolver;
+    this.coreApi = request.coreApi;
+    this.loadOptions = loadOptions;
+  }
+
+  /**
+   * Fetches and validates top-level metadata, then normalizes common fields used by {@link Tileset3D}.
+   */
+  async initialize(): Promise<void> {
+    if (!this.rootTileset) {
+      const loaderOptions = (this.loadOptions[this.loader.id] as Record<string, unknown>) || {};
+      this.rootTileset = await this.loadRootData(this.url, {
+        ...this.loadOptions,
+        [this.loader.id]: {
+          ...loaderOptions,
+          isTileset: true
+        }
+      });
+    }
+    this.tileset = this.rootTileset;
+
+    if (this.rootTileset.queryString) {
+      const searchParams = new URLSearchParams(this.rootTileset.queryString);
+      Object.assign(this.queryParams, Object.fromEntries(searchParams.entries()));
+    }
+
+    this.asset = this.rootTileset.asset;
+    if (!this.asset) {
+      throw new Error('Tileset must have an asset property.');
+    }
+    if (
+      this.asset.version !== '0.0' &&
+      this.asset.version !== '1.0' &&
+      this.asset.version !== '1.1'
+    ) {
+      throw new Error('The tileset must be 3D Tiles version either 0.0 or 1.0 or 1.1.');
+    }
+
+    if ('tilesetVersion' in this.asset) {
+      this.queryParams.v = this.asset.tilesetVersion;
+    }
+
+    this.properties = this.rootTileset.properties;
+    this.extras = this.rootTileset.extras;
+    this.credits = {attributions: []};
+    this.extensionsUsed.splice(
+      0,
+      this.extensionsUsed.length,
+      ...(this.rootTileset.extensionsUsed || [])
+    );
+    this.metadata = {
+      type: this.type,
+      loader: this.loader,
+      url: this.url,
+      basePath: this.basePath,
+      tileset: this.rootTileset,
+      lodMetricType: this.rootTileset.lodMetricType,
+      lodMetricValue: this.rootTileset.lodMetricValue,
+      refine: this.rootTileset.root?.refine
+    };
+  }
+
+  /**
+   * Returns normalized source metadata after initialization.
+   */
+  getMetadata(): TilesetSourceMetadata {
+    if (!this.metadata) {
+      throw new Error('Tiles3DSource has not been initialized');
+    }
+    return this.metadata;
+  }
+
+  /**
+   * Returns the root 3D Tiles payload.
+   */
+  async getRootTileset(): Promise<TilesetJSON> {
+    return this.getMetadata().tileset;
+  }
+
+  /**
+   * Builds the eager runtime tile tree for a 3D Tiles subtree.
+   */
+  initializeTileHeaders(
+    tileset: Tileset3D,
+    tilesetJson: TilesetJSON,
+    parentTile?: Tile3D | null
+  ): Tile3D {
+    const rootTile = new Tile3DNode(tileset, tilesetJson.root, parentTile || undefined);
+
+    if (parentTile) {
+      parentTile.children.push(rootTile);
+      rootTile.depth = parentTile.depth + 1;
+    }
+
+    const stack: Tile3D[] = [rootTile];
+    while (stack.length > 0) {
+      const tile = stack.pop() as Tile3D;
+      tileset.stats.get('Tiles In Tileset(s)').incrementCount();
+      const children = tile.header.children || [];
+      for (const childHeader of children) {
+        const childTile = new Tile3DNode(tileset, childHeader, tile);
+        if (childTile.contentUrl?.includes('?session=')) {
+          const url = new URL(childTile.contentUrl);
+          const session = url.searchParams.get('session');
+          if (session) {
+            this.queryParams.session = session;
+          }
+        }
+        tile.children.push(childTile);
+        childTile.depth = tile.depth + 1;
+        stack.push(childTile);
+      }
+    }
+
+    return rootTile;
+  }
+
+  /**
+   * Creates the standard 3D Tiles traverser.
+   */
+  createTraverser(options: TilesetTraverserProps): TilesetTraverser {
+    return new Tileset3DTraverser(options);
+  }
+
+  /**
+   * Loads binary content or nested tileset JSON for a runtime tile.
+   */
+  async loadTileContent(tile: Tile3D): Promise<TileContentLoadResult> {
+    const contentUrl = this.getTileUrl(tile.contentUrl);
+    const tilesetLoaderOptions =
+      (this.loadOptions[this.loader.id] as Record<string, unknown>) || {};
+    const options = {
+      ...this.loadOptions,
+      [this.loader.id]: {
+        ...tilesetLoaderOptions,
+        isTileset: tile.type === 'json',
+        assetGltfUpAxis: (this.asset && this.asset.gltfUpAxis) || 'Y'
+      }
+    };
+
+    const content = await this.loadResourceData(contentUrl, options);
+    tile.content = content;
+
+    return {
+      loaded: true,
+      nestedTileset: tile.contentUrl.includes('.json') ? content : undefined
+    };
+  }
+
+  /**
+   * Resolves a tile content URL with source-managed query parameters.
+   */
+  getTileUrl(tilePath: string): string {
+    if (tilePath.startsWith('data:')) {
+      return tilePath;
+    }
+
+    if (!Object.keys(this.queryParams).length) {
+      return tilePath;
+    }
+
+    const [pathWithoutQuery, existingQuery = ''] = tilePath.split('?');
+    const mergedQueryParams = new URLSearchParams(existingQuery);
+
+    for (const [key, value] of Object.entries(this.queryParams)) {
+      if (!mergedQueryParams.has(key)) {
+        mergedQueryParams.set(key, value);
+      }
+    }
+
+    const queryParams = mergedQueryParams.toString();
+    return queryParams ? `${pathWithoutQuery}?${queryParams}` : pathWithoutQuery;
+  }
+
+  /**
+   * Derives the default view state from the root bounding volume.
+   */
+  getViewState(rootTile: Tile3D | null): TilesetSourceViewState {
+    if (!rootTile) {
+      return {
+        asset: this.asset,
+        properties: this.properties,
+        extras: this.extras,
+        credits: this.credits
+      };
+    }
+
+    const {center} = rootTile.boundingVolume;
+    let cartographicCenter: Vector3;
+    if (center && (center[0] !== 0 || center[1] !== 0 || center[2] !== 0)) {
+      cartographicCenter = new Vector3();
+      Ellipsoid.WGS84.cartesianToCartographic(center, cartographicCenter);
+    } else {
+      cartographicCenter = new Vector3(0, 0, -Ellipsoid.WGS84.radii[0]);
+    }
+
+    return {
+      asset: this.asset,
+      properties: this.properties,
+      extras: this.extras,
+      credits: this.credits,
+      boundingVolume: rootTile.boundingVolume,
+      cartographicCenter,
+      cartesianCenter: center,
+      zoom: getZoomFromBoundingVolume(rootTile.boundingVolume, cartographicCenter)
+    };
+  }
+
+  /**
+   * Checks whether the root tileset declares the given extension.
+   */
+  hasExtension(extensionName: string): boolean {
+    return this.extensionsUsed.includes(extensionName);
+  }
+
+  /**
+   * Updates content-format flags and installs nested tileset subtrees.
+   */
+  onTileLoaded(tileset: Tileset3D, tile: Tile3D, loadResult: TileContentLoadResult): void {
+    const {extensionsRemoved = []} = tile.content?.gltf || {};
+    if (extensionsRemoved.includes('KHR_draco_mesh_compression')) {
+      this.contentFormats.draco = true;
+    }
+    if (extensionsRemoved.includes('EXT_meshopt_compression')) {
+      this.contentFormats.meshopt = true;
+    }
+    if (extensionsRemoved.includes('KHR_texture_basisu')) {
+      this.contentFormats.ktx2 = true;
+    }
+
+    if (loadResult.nestedTileset) {
+      tileset._initializeTileHeaders(loadResult.nestedTileset, tile);
+    }
+  }
+
+  /**
+   * Loads data through injected core APIs so this module stays independent from `@loaders.gl/core`.
+   */
+  private async loadWithCoreApi(url: string, options: LoaderOptions): Promise<any> {
+    if (!this.coreApi) {
+      throw new Error('Tiles3DSource requires an injected coreApi to load tileset data');
+    }
+
+    return await this.coreApi.load(url, this.loader, options);
+  }
+
+  /**
+   * Loads data through an injected resolver when present, otherwise through the injected core API.
+   */
+  private async loadRootData(url: string, options: LoaderOptions): Promise<any> {
+    if (this.resolver) {
+      return await this.resolver.loadRoot(url, this.loader, options);
+    }
+
+    return await this.loadWithCoreApi(url, options);
+  }
+
+  /**
+   * Loads tile content through an injected resolver when present, otherwise through the injected core API.
+   */
+  private async loadResourceData(url: string, options: LoaderOptions): Promise<any> {
+    if (this.resolver) {
+      return await this.resolver.loadResource(url, this.loader, options);
+    }
+
+    return await this.loadWithCoreApi(url, options);
+  }
+}
+
+function isTilesetRequest(input: TilesetSourceInput): input is TilesetSourceRequest {
+  return Boolean(
+    input && typeof input === 'object' && 'url' in input && 'loader' in input && !('type' in input)
+  );
+}
+
+/**
+ * Normalizes constructor input into a URL request descriptor.
+ * @param input Constructor input for {@link Tiles3DSource}.
+ * @returns A normalized request with a resolved base path.
+ */
+function normalizeTiles3DRequest(input: TilesetSourceInput): TilesetSourceRequest {
+  if (isTilesetRequest(input)) {
+    return {
+      ...input,
+      basePath: input.basePath || path.dirname(input.url)
+    };
+  }
+
+  return {
+    url: input.url,
+    loader: input.loader,
+    basePath: input.basePath || path.dirname(input.url),
+    resolver: (input as TilesetSourceRequest).resolver,
+    coreApi: (input as TilesetSourceRequest).coreApi
+  };
+}

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

@@ -6,7 +6,7 @@
 // See LICENSE.md and https://github.com/AnalyticalGraphicsInc/cesium/blob/master/LICENSE.md
 
 import {TILE3D_OPTIMIZATION_HINT, TILE_REFINEMENT} from '../../constants';
-import {TilesetTraverser} from '../tileset-traverser';
+import {TilesetTraverser} from '../common/tileset-traverser';
 
 export class Tileset3DTraverser extends TilesetTraverser {
   compareDistanceToCamera(a, b) {