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

package/src/tileset-2d/types.ts

@@ -0,0 +1,39 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+/** Inclusive minimum and maximum elevation bounds used during tile selection. */
+export type ZRange = [minZ: number, maxZ: number];
+
+/** Axis-aligned bounding box represented as `[minX, minY, maxX, maxY]`. */
+export type Bounds = [minX: number, minY: number, maxX: number, maxY: number];
+
+/** Geographic tile bounds in longitude/latitude coordinates. */
+export type GeoBoundingBox = {west: number; north: number; east: number; south: number};
+
+/** Cartesian tile bounds in layer/world coordinates. */
+export type NonGeoBoundingBox = {left: number; top: number; right: number; bottom: number};
+
+/** Tile bounds for either geospatial or cartesian views. */
+export type TileBoundingBox = NonGeoBoundingBox | GeoBoundingBox;
+
+/** Tile coordinate in an x/y/z pyramid. */
+export type TileIndex = {x: number; y: number; z: number};
+
+/** Information passed to a tile loader for fetching tile content. */
+export type TileLoadProps = {
+  /** x/y/z tile coordinate. */
+  index: TileIndex;
+  /** Stable cache identifier for the tile. */
+  id: string;
+  /** Bounds covered by the tile in the active coordinate system. */
+  bbox: TileBoundingBox;
+  /** URL derived from a URL template, if applicable. */
+  url?: string | null;
+  /** Abort signal for cancelling an in-flight tile request. */
+  signal?: AbortSignal;
+  /** Optional application metadata associated with the tile. */
+  userData?: Record<string, any>;
+  /** Resolved zoom level used to request this tile. */
+  zoom?: number;
+};

package/src/tileset-2d.ts

@@ -0,0 +1,5 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+export * from './tileset-2d/index';

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

@@ -0,0 +1,205 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {BlobFile, HttpFile, path} from '@loaders.gl/loader-utils';
+import type {
+  CoreAPI,
+  LoaderOptions,
+  LoaderWithParser,
+  ReadableFile
+} from '@loaders.gl/loader-utils';
+import type {TilesetSourceResolver} from './tileset-source';
+
+/** Options for {@link IndexedArchiveTilesetSource}. */
+export type IndexedArchiveTilesetSourceOptions<ArchiveT> = {
+  /** Archive URL or Blob. */
+  data: string | Blob;
+  /** Filename to expose for Blob inputs that do not provide a name. */
+  fallbackFilename: string;
+  /** Archive file extension used as the URL path marker. */
+  archiveExtension: string;
+  /** Path to the root metadata resource inside the archive. */
+  rootPath: string;
+  /** Optional mode passed when loading the root metadata resource. */
+  rootMode?: string;
+  /** Parses an opened readable file into an indexed archive object. */
+  parseArchive: (file: ReadableFile) => Promise<ArchiveT>;
+  /** Loads one resource from the parsed archive. */
+  getFile: (archive: ArchiveT, pathInArchive: string, mode?: string) => Promise<ArrayBuffer>;
+  /** Returns the core API used for local file loading and nested resource parsing. */
+  getCoreApi: () => CoreAPI | undefined;
+  /** Error message to throw when the core API is required but unavailable. */
+  missingCoreApiMessage: string;
+};
+
+/**
+ * Tileset source resolver backed by an indexed archive such as 3TZ or SLPK.
+ *
+ * The source owns archive opening, archive caching, path resolution, and archive-backed `fetch`
+ * injection. Format-specific parsing and file lookup stay in the owning format module.
+ */
+export class IndexedArchiveTilesetSource<ArchiveT> implements TilesetSourceResolver {
+  /** URL exposed to the tileset source that owns this archive source. */
+  readonly sourceUrl: string;
+
+  private readonly options: IndexedArchiveTilesetSourceOptions<ArchiveT>;
+  private archivePromise?: Promise<ArchiveT>;
+
+  /**
+   * Creates an indexed archive tileset source.
+   * @param options Archive source options
+   */
+  constructor(options: IndexedArchiveTilesetSourceOptions<ArchiveT>) {
+    this.options = options;
+    this.sourceUrl = getArchiveSourceUrl(options.data, options.fallbackFilename);
+  }
+
+  /**
+   * Loads and parses the archive root metadata resource.
+   * @param url Root URL, ignored because the archive root path is configured explicitly
+   * @param loader Loader used to parse the root metadata
+   * @param loadOptions Loader options forwarded to parsing
+   */
+  async loadRoot<DataT>(
+    url: string,
+    loader: LoaderWithParser<DataT>,
+    loadOptions: LoaderOptions
+  ): Promise<DataT> {
+    return await this.parseArchiveResource(
+      url,
+      this.options.rootPath,
+      loader,
+      loadOptions,
+      this.options.rootMode
+    );
+  }
+
+  /**
+   * Loads and parses an archive resource relative to a requesting resource URL.
+   * @param url Resource URL
+   * @param loader Loader used to parse the resource
+   * @param loadOptions Loader options forwarded to parsing
+   */
+  async loadResource<DataT>(
+    url: string,
+    loader: LoaderWithParser<DataT>,
+    loadOptions: LoaderOptions
+  ): Promise<DataT> {
+    const pathInArchive = this.resolveArchivePath(url, url);
+    return await this.parseArchiveResource(url, pathInArchive, loader, loadOptions);
+  }
+
+  private async parseArchiveResource<DataT>(
+    resourceUrl: string,
+    pathInArchive: string,
+    loader: LoaderWithParser<DataT>,
+    loadOptions: LoaderOptions,
+    mode?: string
+  ): Promise<DataT> {
+    const coreApi = this.options.getCoreApi();
+    if (!coreApi) {
+      throw new Error(this.options.missingCoreApiMessage);
+    }
+
+    const data = await this.loadFile(pathInArchive, mode);
+    const archiveFetch = this.createArchiveFetch(resourceUrl);
+    return (await coreApi.parse(
+      data,
+      loader,
+      {
+        ...loadOptions,
+        fetch: archiveFetch
+      },
+      {
+        url: resourceUrl,
+        fetch: archiveFetch,
+        _parse: coreApi.parse,
+        loaders: [loader],
+        coreApi
+      } as any
+    )) as DataT;
+  }
+
+  private createArchiveFetch(contextUrl: string): typeof fetch {
+    return async (input: RequestInfo | URL): Promise<Response> => {
+      const requestUrl =
+        typeof input === 'string' ? input : input instanceof URL ? input.toString() : input.url;
+      const pathInArchive = this.resolveArchivePath(requestUrl, contextUrl);
+      const data = await this.loadFile(pathInArchive);
+      return new Response(data, {status: 200});
+    };
+  }
+
+  private async loadFile(pathInArchive: string, mode?: string): Promise<ArrayBuffer> {
+    this.archivePromise ||= this.openArchiveReadableFile().then(file =>
+      this.options.parseArchive(file)
+    );
+    const archive = await this.archivePromise;
+    return await this.options.getFile(archive, pathInArchive, mode);
+  }
+
+  private async openArchiveReadableFile(): Promise<ReadableFile> {
+    const {data} = this.options;
+    if (typeof data !== 'string') {
+      return new BlobFile(data);
+    }
+
+    if (/^https?:\/\//i.test(data)) {
+      return new HttpFile(data);
+    }
+
+    const coreApi = this.options.getCoreApi();
+    if (!coreApi) {
+      throw new Error(this.options.missingCoreApiMessage);
+    }
+    const response = await coreApi.fetchFile(data);
+    return new BlobFile(await response.arrayBuffer());
+  }
+
+  private resolveArchivePath(request: string, baseUrl: string): string {
+    const requestWithoutQuery = stripQueryString(request);
+    const archiveRoot = stripQueryString(this.sourceUrl);
+    const baseWithoutQuery = stripQueryString(baseUrl);
+    const basePath =
+      baseWithoutQuery === archiveRoot ? archiveRoot : path.dirname(baseWithoutQuery);
+    const markerExpression = new RegExp(`\\.${this.options.archiveExtension}/(.*)$`, 'i');
+    const markerMatch = requestWithoutQuery.match(markerExpression);
+    if (markerMatch?.[1]) {
+      return markerMatch[1];
+    }
+
+    const isAbsoluteRequest =
+      /^[a-z][a-z0-9+.-]*:/i.test(requestWithoutQuery) || requestWithoutQuery.startsWith('/');
+    const absoluteRequest = requestWithoutQuery.startsWith(archiveRoot)
+      ? requestWithoutQuery
+      : baseWithoutQuery === archiveRoot && !isAbsoluteRequest
+        ? `${archiveRoot}/${requestWithoutQuery}`
+        : path.resolve(basePath, requestWithoutQuery);
+
+    if (absoluteRequest === archiveRoot) {
+      return '';
+    }
+
+    if (absoluteRequest.startsWith(`${archiveRoot}/`)) {
+      return absoluteRequest.slice(archiveRoot.length + 1);
+    }
+
+    return absoluteRequest.replace(/^\/+/, '');
+  }
+}
+
+function getArchiveSourceUrl(data: string | Blob, fallbackFilename: string): string {
+  if (typeof data === 'string') {
+    return data;
+  }
+
+  const fileName =
+    'name' in data && typeof data.name === 'string' && data.name ? data.name : fallbackFilename;
+  return `memory://${fileName}`;
+}
+
+function stripQueryString(url: string): string {
+  const queryIndex = url.indexOf('?');
+  return queryIndex >= 0 ? url.slice(0, queryIndex) : url;
+}

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

@@ -8,22 +8,20 @@
 import {Vector3, Matrix4} from '@math.gl/core';
 import {CullingVolume} from '@math.gl/culling';
 
-import {load} from '@loaders.gl/core';
-
 // Note: circular dependency
 import type {Tileset3D} from './tileset-3d';
-import type {DoublyLinkedListNode} from '../utils/doubly-linked-list-node';
-import {TILE_REFINEMENT, TILE_CONTENT_STATE, TILESET_TYPE} from '../constants';
+import type {DoublyLinkedListNode} from '../../utils/doubly-linked-list-node';
+import {LOD_METRIC_TYPE, TILE_REFINEMENT, TILE_CONTENT_STATE, TILESET_TYPE} from '../../constants';
+import type {TileContentLoadResult} from './tileset-source';
 
-import {FrameState} from './helpers/frame-state';
+import {FrameState} from '../helpers/frame-state';
 import {
   createBoundingVolume,
   getCartographicBounds,
   CartographicBounds
-} from './helpers/bounding-volume';
-import {getTiles3DScreenSpaceError} from './helpers/tiles-3d-lod';
-import {getProjectedRadius} from './helpers/i3s-lod';
-import {get3dTilesOptions} from './helpers/3d-tiles-options';
+} from '../helpers/bounding-volume';
+import {getTiles3DScreenSpaceError} from '../helpers/tiles-3d-lod';
+import {getProjectedRadius} from '../helpers/i3s-lod';
 import {TilesetTraverser} from './tileset-traverser';
 
 const scratchVector = new Vector3();
@@ -62,10 +60,19 @@ export class Tile3D {
   type: string;
   contentUrl: string;
   /** Different refinement algorithms used by I3S and 3D tiles */
-  lodMetricType: 'geometricError' | 'maxScreenThreshold' = 'geometricError';
-  /** The error, in meters, introduced if this tile is rendered and its children are not. */
+  lodMetricType = 'geometricError';
+  /**
+   * The world-space geometric error, in meters, introduced if this tile is rendered and its
+   * children are not. For I3S this stores the format's unscaled screen-threshold metric instead.
+   */
   lodMetricValue: number = 0;
 
+  /**
+   * The source LOD metric before applying the tile's computed transform. Keeping the source value
+   * separate ensures transform updates never compound an already-scaled geometric error.
+   */
+  private _unscaledLodMetricValue: number = 0;
+
   /** @todo math.gl is not exporting BoundingVolume base type? */
   boundingVolume: any = null;
 
@@ -172,6 +179,7 @@ export class Tile3D {
 
     this._initializeLodMetric(header);
     this._initializeTransforms(header);
+    this._updateLodMetricScale();
     this._initializeBoundingVolumes(header);
     this._initializeContent(header);
     this._initializeRenderingState(header);
@@ -355,13 +363,13 @@ export class Tile3D {
    * The request may not be made if the Request Scheduler can't prioritize it.
    */
   // eslint-disable-next-line max-statements, complexity
-  async loadContent(): Promise<boolean> {
+  async loadContent(): Promise<TileContentLoadResult> {
     if (this.hasEmptyContent) {
-      return false;
+      return {loaded: false};
     }
 
     if (this.content) {
-      return true;
+      return {loaded: true};
     }
 
     const expired = this.contentExpired;
@@ -380,40 +388,19 @@ export class Tile3D {
     if (!requestToken) {
       // cancelled
       this.contentState = TILE_CONTENT_STATE.UNLOADED;
-      return false;
+      return {loaded: false};
     }
 
     try {
-      const contentUrl = this.tileset.getTileUrl(this.contentUrl);
-      // The content can be a binary tile ot a JSON tileset
-      const loader = this.tileset.loader;
-      const tilesetLoaderOptions =
-        (this.tileset.loadOptions[loader.id] as Record<string, unknown>) || {};
-      const options = {
-        ...this.tileset.loadOptions,
-        [loader.id]: {
-          ...tilesetLoaderOptions,
-          isTileset: this.type === 'json',
-          ...this._getLoaderSpecificOptions(loader.id)
-        } // TODO add typecheck - as const satisfies ...
-      };
-
-      this.content = await load(contentUrl, loader, options);
+      const loadResult = await this.tileset.source.loadTileContent(this);
 
       if (this.tileset.options.contentLoader) {
         await this.tileset.options.contentLoader(this);
       }
 
-      if (this._isTileset()) {
-        // Add tile headers for the nested tilset's subtree
-        // Async update of the tree should be fine since there would never be edits to the same node
-        // TODO - we need to capture the child tileset's URL
-        this.tileset._initializeTileHeaders(this.content, this);
-      }
-
       this.contentState = TILE_CONTENT_STATE.READY;
       this._onContentLoaded();
-      return true;
+      return loadResult;
     } catch (error) {
       // Tile is unloaded before the content finishes loading
       this.contentState = TILE_CONTENT_STATE.FAILED;
@@ -592,7 +579,8 @@ export class Tile3D {
 
   // INTERNAL METHODS
 
-  _initializeLodMetric(header) {
+  /** Initializes the tile's LOD metric from its header or its nearest available ancestor. */
+  _initializeLodMetric(header: {[key: string]: any}): void {
     if ('lodMetricType' in header) {
       this.lodMetricType = header.lodMetricType;
     } else {
@@ -603,15 +591,20 @@ export class Tile3D {
 
     // This is used to compute screen space error, i.e., the error measured in pixels.
     if ('lodMetricValue' in header) {
-      this.lodMetricValue = header.lodMetricValue;
+      this._unscaledLodMetricValue = header.lodMetricValue;
     } else {
-      this.lodMetricValue =
-        (this.parent && this.parent.lodMetricValue) || this.tileset.lodMetricValue;
+      // Inherit the source value, not the parent's world-space value. The child's complete
+      // transform will be applied after transform initialization below.
+      this._unscaledLodMetricValue = this.parent
+        ? this.parent._unscaledLodMetricValue
+        : this.tileset.lodMetricValue;
       // eslint-disable-next-line
       console.warn(
         '3D Tile: Required prop lodMetricValue is undefined. Using parent lodMetricValue'
       );
     }
+
+    this.lodMetricValue = this._unscaledLodMetricValue;
   }
 
   _initializeTransforms(tileHeader) {
@@ -632,6 +625,28 @@ export class Tile3D {
     this._initialTransform = new Matrix4(parentInitialTransform).multiplyRight(this.transform);
   }
 
+  /**
+   * Updates the world-space LOD metric from the source metric and the complete tile transform.
+   *
+   * 3D Tiles geometric error is a distance in the tile's local meters. Screen-space error (SSE)
+   * compares that distance with a world-space camera distance, so both quantities must use the
+   * same scale. For non-uniform transforms the largest axis scale is deliberately used: this is
+   * conservative and prevents refinement from stopping while any transformed dimension can still
+   * exceed the requested visual error. Rotation and translation do not affect the scale.
+   *
+   * I3S `maxScreenThreshold` is already a screen-space metric and must not be transform-scaled.
+   */
+  _updateLodMetricScale(): void {
+    if (this.lodMetricType !== LOD_METRIC_TYPE.GEOMETRIC_ERROR) {
+      this.lodMetricValue = this._unscaledLodMetricValue;
+      return;
+    }
+
+    const transformScale = this.computedTransform.getScale(scratchVector);
+    const maximumScale = Math.max(transformScale[0], transformScale[1], transformScale[2]);
+    this.lodMetricValue = this._unscaledLodMetricValue * maximumScale;
+  }
+
   _initializeBoundingVolumes(tileHeader) {
     this._contentBoundingVolume = null;
     this._viewerRequestVolume = null;
@@ -743,8 +758,11 @@ export class Tile3D {
     }
   }
 
-  // Update the tile's transform. The transform is applied to the tile's bounding volumes.
-  _updateTransform(parentTransform = new Matrix4()) {
+  /**
+   * Updates the tile's computed transform, world-space geometric error, and bounding volumes.
+   * @param parentTransform - Current computed transform of the parent tile or tileset.
+   */
+  _updateTransform(parentTransform = new Matrix4()): void {
     const computedTransform = parentTransform.clone().multiplyRight(this.transform);
     const didTransformChange = !computedTransform.equals(this.computedTransform);
 
@@ -754,35 +772,8 @@ export class Tile3D {
 
     this.computedTransform = computedTransform;
 
+    // Recalculate from the unscaled source metric so repeated model-matrix changes never compound.
+    this._updateLodMetricScale();
     this._updateBoundingVolume(this.header);
   }
-
-  // Get options which are applicable only for the particular loader
-  _getLoaderSpecificOptions(loaderId) {
-    switch (loaderId) {
-      case 'i3s':
-        return {
-          ...this.tileset.options.i3s,
-          _tileOptions: {
-            attributeUrls: this.header.attributeUrls,
-            textureUrl: this.header.textureUrl,
-            textureFormat: this.header.textureFormat,
-            textureLoaderOptions: this.header.textureLoaderOptions,
-            materialDefinition: this.header.materialDefinition,
-            isDracoGeometry: this.header.isDracoGeometry,
-            mbs: this.header.mbs
-          },
-          _tilesetOptions: {
-            store: this.tileset.tileset.store,
-            attributeStorageInfo: this.tileset.tileset.attributeStorageInfo,
-            fields: this.tileset.tileset.fields
-          },
-          isTileHeader: false
-        };
-      case '3d-tiles':
-      case 'cesium-ion':
-      default:
-        return get3dTilesOptions(this.tileset.tileset);
-    }
-  }
 }