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

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

@@ -2,10 +2,10 @@
 // SPDX-License-Identifier: MIT
 // Copyright (c) vis.gl contributors
 
-import {path, RequestCache} from '@loaders.gl/loader-utils';
+import {path, RequestCache, sliceArrayBuffer} 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 {Matrix4, Vector3} from '@math.gl/core';
+import type {CoreAPI, Loader, LoaderContext, LoaderOptions} 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';
@@ -27,6 +27,12 @@ import {TILESET_TYPE} from '../../constants';
 import type {TilesetTraverser, TilesetTraverserProps} from '../common/tileset-traverser';
 import type {FrameState} from '../helpers/frame-state';
 import {get3DTilesSpatialReference} from '../../spatial/format-spatial-reference';
+import {Tiles3DSpatialTransformer} from '../../spatial/tiles-3d-spatial-transformer';
+import {
+  applyTilesetSpatialOptions,
+  markTilesetSpatialReferenceTransformed
+} from '../../spatial/spatial-types';
+import type {TilesetSpatialReference} from '../../spatial/spatial-types';
 import {
   materializeImplicitSubtree,
   type ImplicitSubtreeReference,
@@ -42,6 +48,24 @@ const EMPTY_CONTENT_FORMATS: TilesetContentFormats = {
 
 const DEFAULT_MAXIMUM_CACHED_SUBTREES = 32;
 
+type PackageFile = {
+  name?: string;
+  mimeType: string;
+  uri?: string;
+  originalUri?: string;
+  data?: ArrayBuffer;
+  byteOffset: number;
+  byteLength: number;
+  bufferUri?: string;
+};
+
+type PackageResource = {fileIndex: number; files: PackageFile[]};
+
+type Tiles3DPackageLoaderContext = LoaderContext & {
+  /** Parent package records available while parsing an embedded tileset or subtree. */
+  _tiles3dPackageFiles: PackageFile[];
+};
+
 /** Diagnostics for source-managed implicit subtree loading. */
 export type ImplicitTilingStats = {
   /** Subtree resources requested from the resolver or core API. */
@@ -65,7 +89,7 @@ export class Tiles3DSource implements Tileset3DSource {
   /** 3D Tiles format discriminator. */
   readonly type = TILESET_TYPE.TILES3D;
   /** Loader used for tile content requests. */
-  readonly loader: LoaderWithParser;
+  readonly loader: Loader;
   /** Root tileset URL. */
   readonly url: string;
   /** Base path used for relative tile resource resolution. */
@@ -93,6 +117,12 @@ export class Tiles3DSource implements Tileset3DSource {
   private readonly queryParams: Record<string, string> = {};
   /** Final request URLs cached by unmodified tile content URL. */
   private readonly tileUrlCache: Map<string, string> = new Map();
+  /** Original content descriptors retained across {@link Tile3D.unloadContent} calls. */
+  private readonly tileContentHeaders = new WeakMap<Tile3D, Record<string, any>[]>();
+  /** Source-local namespaces assigned to distinct embedded glTF package file collections. */
+  private readonly packageNamespaces = new WeakMap<PackageFile[], number>();
+  /** Next source-local package namespace. */
+  private nextPackageNamespace = 0;
   /** Parsed subtree requests keyed by final source URL for deduplication and LRU reuse. */
   private readonly implicitSubtreeCache: RequestCache<ParsedImplicitSubtree>;
   /** Mutable counters exposed as a defensive snapshot through {@link getImplicitTilingStats}. */
@@ -110,6 +140,10 @@ export class Tiles3DSource implements Tileset3DSource {
   private readonly extensionsUsed: string[] = [];
   private readonly resolver?: TilesetSourceResolver;
   private rootTileset: TilesetJSON;
+  /** CRS transformer shared by this source's headers and decoded glTF content. */
+  private spatialTransformer?: Tiles3DSpatialTransformer;
+  /** Root header after composing source-frame transforms and rebuilding target bounds. */
+  private preparedRootHeader?: Record<string, any>;
 
   /**
    * Creates a 3D Tiles source.
@@ -175,11 +209,12 @@ export class Tiles3DSource implements Tileset3DSource {
       throw new Error('Tileset must have an asset property.');
     }
     if (
+      this.rootTileset.formatVersion !== '2.0-draft' &&
       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.');
+      throw new Error('The tileset must be 3D Tiles version 0.0, 1.0, 1.1, or 2.0-draft.');
     }
 
     if ('tilesetVersion' in this.asset) {
@@ -224,6 +259,29 @@ export class Tiles3DSource implements Tileset3DSource {
     return this.getMetadata().tileset;
   }
 
+  /** Prepare nonlinear CRS state before runtime headers are materialized. */
+  async prepareTileset(tileset: Tileset3D): Promise<void> {
+    const spatialReference = tileset.spatialReference;
+    if (spatialReference.status === 'unresolved') {
+      throw new Error(
+        spatialReference.warnings[0] ||
+          '3D Tiles spatial operations cannot be resolved from the supplied metadata and options'
+      );
+    }
+    if (spatialReference.status !== 'transformable' && spatialReference.status !== 'transformed') {
+      return;
+    }
+    this.spatialTransformer ||= new Tiles3DSpatialTransformer(
+      spatialReference,
+      tileset.options.spatial
+    );
+    tileset.spatialReference = markTilesetSpatialReferenceTransformed(spatialReference);
+    this.preparedRootHeader = this.transformTileHeader(
+      this.getMetadata().tileset.root,
+      new Matrix4()
+    );
+  }
+
   /**
    * Builds explicit runtime headers while leaving implicit subtree references lazy.
    */
@@ -232,7 +290,8 @@ export class Tiles3DSource implements Tileset3DSource {
     tilesetJson: TilesetJSON,
     parentTile?: Tile3D | null
   ): Tile3D {
-    const rootTile = new Tile3DNode(tileset, tilesetJson.root, parentTile || undefined);
+    const rootHeader = parentTile ? tilesetJson.root : this.preparedRootHeader || tilesetJson.root;
+    const rootTile = new Tile3DNode(tileset, rootHeader, parentTile || undefined);
 
     if (parentTile) {
       parentTile.children.push(rootTile);
@@ -274,6 +333,17 @@ export class Tiles3DSource implements Tileset3DSource {
    */
   async loadTileContent(tile: Tile3D): Promise<TileContentLoadResult> {
     const contentUrls = (tile.contentUrls || [tile.contentUrl]).filter(Boolean);
+    const cachedContentHeaders = this.tileContentHeaders.get(tile);
+    const contentHeaders: Record<string, any>[] =
+      cachedContentHeaders ||
+      (Array.isArray(tile.header?.content)
+        ? tile.header.content
+        : tile.header?.content
+          ? [tile.header.content]
+          : []);
+    if (!cachedContentHeaders) {
+      this.tileContentHeaders.set(tile, contentHeaders);
+    }
     const tilesetLoaderOptions =
       (this.loadOptions[this.loader.id] as Record<string, unknown>) || {};
     const options = {
@@ -283,12 +353,37 @@ export class Tiles3DSource implements Tileset3DSource {
         // Content bytes, rather than URL suffixes, distinguish external tilesets from renderable
         // payloads. This is required for signed and extensionless resources.
         isTileset: 'auto',
-        assetGltfUpAxis: (this.asset && this.asset.gltfUpAxis) || 'Y'
+        assetGltfUpAxis: (this.asset && this.asset.gltfUpAxis) || 'Y',
+        _tilesetOptions: {
+          spatialReference: tile.header?._spatialReference || tile.tileset?.spatialReference,
+          spatialOptions: tile.tileset?.options.spatial,
+          spatialTransform: tile.header?._spatialTransform
+        }
       }
     };
 
     const contents = await Promise.all(
-      contentUrls.map(contentUrl => this.loadResourceData(this.getTileUrl(contentUrl), options))
+      contentUrls.map((contentUrl, contentIndex) => {
+        const contentHeader = contentHeaders[contentIndex] || {};
+        const vectorExtension = contentHeader.extensions?.['3DTILES_content_gltf_vector'];
+        const vectorContent =
+          contentHeader._vectorContent ||
+          (vectorExtension?.vector === true ? {clip: vectorExtension.clip === true} : undefined);
+        const contentOptions = vectorContent
+          ? {
+              ...options,
+              [this.loader.id]: {
+                ...(options[this.loader.id] as Record<string, unknown>),
+                vectorContent
+              }
+            }
+          : options;
+        return this.loadContentResource(
+          this.getTileUrl(contentUrl),
+          contentHeader._resource,
+          contentOptions
+        );
+      })
     );
     tile.contents = contents;
     tile.content = contents[0] || null;
@@ -302,6 +397,72 @@ export class Tiles3DSource implements Tileset3DSource {
     };
   }
 
+  /** Transform a tile header and its eagerly declared descendants. */
+  private transformTileHeader(
+    header: Record<string, any>,
+    parentTransform: Matrix4 = new Matrix4()
+  ): Record<string, any> {
+    if (!this.spatialTransformer) {
+      return header;
+    }
+    return this.transformTileHeaderWithTransformer(
+      header,
+      this.spatialTransformer,
+      parentTransform
+    );
+  }
+
+  /** Rebuilds one header subtree using an explicitly selected CRS transformer. */
+  private transformTileHeaderWithTransformer(
+    header: Record<string, any>,
+    transformer: Tiles3DSpatialTransformer,
+    parentTransform: Matrix4,
+    spatialReference?: TilesetSpatialReference
+  ): Record<string, any> {
+    const localTransform = header.transform ? new Matrix4(header.transform) : new Matrix4();
+    const composedTransform = new Matrix4(parentTransform).multiplyRight(localTransform);
+    const content = Array.isArray(header.content)
+      ? header.content.map((entry: Record<string, any>) =>
+          this.transformContentHeader(entry, composedTransform, transformer)
+        )
+      : header.content
+        ? this.transformContentHeader(header.content, composedTransform, transformer)
+        : header.content;
+    return {
+      ...header,
+      transform: undefined,
+      boundingVolume: header.boundingVolume
+        ? transformer.transformBoundingVolume(header.boundingVolume, composedTransform)
+        : header.boundingVolume,
+      _spatialReference: spatialReference,
+      _spatialTransform: composedTransform.toArray(),
+      content,
+      children: Array.isArray(header.children)
+        ? header.children.map((child: Record<string, any>) =>
+            this.transformTileHeaderWithTransformer(
+              child,
+              transformer,
+              composedTransform,
+              spatialReference
+            )
+          )
+        : header.children
+    };
+  }
+
+  private transformContentHeader(
+    content: Record<string, any>,
+    composedTransform: Matrix4,
+    transformer: Tiles3DSpatialTransformer
+  ): Record<string, any> {
+    return {
+      ...content,
+      boundingVolume: content.boundingVolume
+        ? transformer.transformBoundingVolume(content.boundingVolume, composedTransform)
+        : content.boundingVolume
+    };
+  }
+
   /**
    * Loads, materializes, and installs exactly one implicit subtree.
    *
@@ -321,7 +482,7 @@ export class Tiles3DSource implements Tileset3DSource {
     }
 
     const subtreeUrl = this.getTileUrl(reference.subtreeUrl);
-    const subtree = await this.loadImplicitSubtreeResource(subtreeUrl);
+    const subtree = await this.loadImplicitSubtreeResource(subtreeUrl, reference.resource);
     if (this.destroyed || tile.isDestroyed()) {
       return {loaded: false, tileCount: 0, childSubtreeCount: 0};
     }
@@ -330,11 +491,25 @@ export class Tiles3DSource implements Tileset3DSource {
       subtreeUrl
     });
 
-    tile.applyImplicitSubtreeHeader(materializedSubtree.root);
+    const nestedSpatialReference = tile.header._spatialReference as
+      | TilesetSpatialReference
+      | undefined;
+    const subtreeTransformer = nestedSpatialReference
+      ? new Tiles3DSpatialTransformer(nestedSpatialReference, tile.tileset.options.spatial)
+      : this.spatialTransformer;
+    const materializedRoot = subtreeTransformer
+      ? this.transformTileHeaderWithTransformer(
+          materializedSubtree.root,
+          subtreeTransformer,
+          new Matrix4(),
+          nestedSpatialReference
+        )
+      : materializedSubtree.root;
+    tile.applyImplicitSubtreeHeader(materializedRoot);
     const materializedTileCount = this.initializeMaterializedChildren(
       tile.tileset,
       tile,
-      materializedSubtree.root.children
+      materializedRoot.children
     );
     this.implicitTilingStats.loadedSubtrees++;
     this.implicitTilingStats.materializedTiles += materializedTileCount;
@@ -477,17 +652,106 @@ export class Tiles3DSource implements Tileset3DSource {
     const nestedTilesets =
       loadResult.nestedTilesets || (loadResult.nestedTileset ? [loadResult.nestedTileset] : []);
     for (const nestedTileset of nestedTilesets) {
-      tileset._initializeTileHeaders(nestedTileset, tile);
+      tileset._initializeTileHeaders(this.prepareNestedTileset(tileset, nestedTileset), tile);
     }
   }
 
+  /**
+   * Resolves a nested tileset's CRS independently and adapts it to the owning tileset output frame.
+   *
+   * Nested resources may use a different source CRS from their parent. Their headers and glTF
+   * payloads must therefore use a transformer built from the nested descriptor, while the parent
+   * runtime continues to expose one requested output frame to traversal and rendering.
+   */
+  private prepareNestedTileset(tileset: Tileset3D, nestedTileset: TilesetJSON): TilesetJSON {
+    const nestedSpatialReference = nestedTileset.spatialMetadata;
+    const parentSpatialReference = tileset.spatialReference;
+
+    if (
+      nestedSpatialReference?.status === 'unresolved' ||
+      nestedSpatialReference?.crs.state === 'unknown'
+    ) {
+      throw new Error(
+        nestedSpatialReference.warnings[0] ||
+          'Nested 3D Tiles CRS is explicitly unresolved and cannot be placed in the parent frame'
+      );
+    }
+
+    if (!nestedSpatialReference || !nestedSpatialReference.sourceCrs) {
+      if (
+        this.spatialTransformer &&
+        (parentSpatialReference.status === 'transformable' ||
+          parentSpatialReference.status === 'transformed')
+      ) {
+        return {
+          ...nestedTileset,
+          spatialMetadata: parentSpatialReference,
+          root: this.transformTileHeaderWithTransformer(
+            nestedTileset.root,
+            this.spatialTransformer,
+            new Matrix4(),
+            parentSpatialReference
+          )
+        };
+      }
+      return addNestedSpatialReference(nestedTileset, parentSpatialReference);
+    }
+
+    const parentCoordinateEpoch = parentSpatialReference.coordinateEpoch;
+    const nestedCoordinateEpoch = nestedSpatialReference.coordinateEpoch;
+    if (
+      parentCoordinateEpoch !== undefined &&
+      nestedCoordinateEpoch !== undefined &&
+      parentCoordinateEpoch !== nestedCoordinateEpoch
+    ) {
+      throw new Error(
+        `Nested 3D Tiles coordinate epoch ${nestedCoordinateEpoch} differs from parent epoch ${parentCoordinateEpoch}; epoch-aware transformation is unavailable`
+      );
+    }
+
+    const outputCrs = parentSpatialReference.targetCrs || parentSpatialReference.sourceCrs;
+    if (!outputCrs) {
+      return addNestedSpatialReference(nestedTileset, nestedSpatialReference);
+    }
+
+    const nestedOutputReference = applyTilesetSpatialOptions(nestedSpatialReference, {
+      ...tileset.options.spatial,
+      outputCoordinates: 'target-crs',
+      targetCrs: outputCrs
+    });
+    if (nestedOutputReference.status === 'unresolved') {
+      throw new Error(
+        nestedOutputReference.warnings[0] ||
+          'Nested 3D Tiles CRS cannot be resolved in the parent output frame'
+      );
+    }
+    if (nestedOutputReference.status === 'native') {
+      return addNestedSpatialReference(nestedTileset, nestedOutputReference);
+    }
+
+    const nestedTransformer = new Tiles3DSpatialTransformer(
+      nestedOutputReference,
+      tileset.options.spatial
+    );
+    return {
+      ...nestedTileset,
+      spatialMetadata: nestedOutputReference,
+      root: this.transformTileHeaderWithTransformer(
+        nestedTileset.root,
+        nestedTransformer,
+        new Matrix4(),
+        nestedOutputReference
+      )
+    };
+  }
+
   /**
    * Loads data through injected core APIs so this module stays independent from `@loaders.gl/core`.
    */
   private async loadWithCoreApi(
     url: string,
     options: LoaderOptions,
-    loader: LoaderWithParser = this.loader
+    loader: Loader = this.loader
   ): Promise<any> {
     if (!this.coreApi) {
       throw new Error('Tiles3DSource requires an injected coreApi to load tileset data');
@@ -513,7 +777,7 @@ export class Tiles3DSource implements Tileset3DSource {
   private async loadResourceData(
     url: string,
     options: LoaderOptions,
-    loader: LoaderWithParser = this.loader
+    loader: Loader = this.loader
   ): Promise<any> {
     if (this.resolver) {
       return await this.resolver.loadResource(url, loader, options);
@@ -522,13 +786,102 @@ export class Tiles3DSource implements Tileset3DSource {
     return await this.loadWithCoreApi(url, options, loader);
   }
 
+  /** Loads a URL content reference or parses a buffer-view file retained from a glTF package. */
+  private async loadContentResource(
+    url: string,
+    packageResource: PackageResource | undefined,
+    options: LoaderOptions
+  ): Promise<any> {
+    if (!packageResource) {
+      return await this.loadResourceData(url, options);
+    }
+    const file = packageResource.files[packageResource.fileIndex];
+    if (!file) {
+      throw new Error(`3D Tiles package references missing file ${packageResource.fileIndex}`);
+    }
+    if (file.uri) {
+      return await this.loadResourceData(this.getTileUrl(file.uri), options);
+    }
+    if (!this.coreApi) {
+      throw new Error('Tiles3DSource requires an injected coreApi to parse embedded package data');
+    }
+
+    const data = await this.getPackageFileData(file);
+    const packageNamespace = this.getPackageNamespace(packageResource.files);
+    const packageRootUrl = `gltf-package://${packageNamespace}/${packageResource.fileIndex}`;
+    const fileName = file.name || 'content';
+    const directorySeparatorIndex = fileName.lastIndexOf('/');
+    const packageBaseUrl =
+      directorySeparatorIndex >= 0
+        ? `${packageRootUrl}/${fileName.slice(0, directorySeparatorIndex)}`
+        : packageRootUrl;
+    return await this.coreApi.parse(data, this.loader, options, {
+      url: `${packageRootUrl}/${fileName}`,
+      filename: fileName,
+      baseUrl: packageBaseUrl,
+      loaders: [this.loader],
+      coreApi: this.coreApi,
+      _parse: this.coreApi.parse,
+      _tiles3dPackageFiles: packageResource.files,
+      fetch: async (resource: string, init?: RequestInit) => {
+        const reference = resource.startsWith(`${packageRootUrl}/`)
+          ? resource.slice(packageRootUrl.length + 1)
+          : resource;
+        const referencedFile = packageResource.files.find(
+          packageFile => packageFile.name === reference || packageFile.originalUri === reference
+        );
+        if (!referencedFile) {
+          throw new Error(`3D Tiles glTF package does not contain file ${reference}`);
+        }
+        if (referencedFile.uri) {
+          return await this.coreApi!.fetchFile(this.getTileUrl(referencedFile.uri), init);
+        }
+        const referencedData = await this.getPackageFileData(referencedFile);
+        return new Response(referencedData, {
+          headers: {'content-type': referencedFile.mimeType}
+        });
+      }
+    } as Tiles3DPackageLoaderContext);
+  }
+
+  /** Returns a stable source-local namespace for one embedded glTF package file collection. */
+  private getPackageNamespace(files: PackageFile[]): number {
+    const existingNamespace = this.packageNamespaces.get(files);
+    if (existingNamespace !== undefined) {
+      return existingNamespace;
+    }
+    const packageNamespace = this.nextPackageNamespace++;
+    this.packageNamespaces.set(files, packageNamespace);
+    return packageNamespace;
+  }
+
+  /** Resolves a retained package-file byte range without eagerly copying other package files. */
+  private async getPackageFileData(file: PackageFile): Promise<ArrayBuffer> {
+    if (file.data) {
+      return sliceArrayBuffer(file.data, file.byteOffset, file.byteLength);
+    }
+    if (file.bufferUri && this.coreApi) {
+      const response = await this.coreApi.fetchFile(this.getTileUrl(file.bufferUri));
+      if (!response.ok) {
+        throw new Error(`Failed to fetch 3D Tiles package buffer: HTTP ${response.status}`);
+      }
+      const buffer = await response.arrayBuffer();
+      return sliceArrayBuffer(buffer, file.byteOffset, file.byteLength);
+    }
+    throw new Error('3D Tiles package file has no available byte source');
+  }
+
   /**
    * Returns a parsed subtree from the LRU cache or starts one source-managed request.
    *
    * @param subtreeUrl - Final subtree URL after query inheritance.
+   * @param packageResource - Optional glTF package file satisfying the subtree reference.
    * @returns Parsed subtree availability data.
    */
-  private async loadImplicitSubtreeResource(subtreeUrl: string): Promise<ParsedImplicitSubtree> {
+  private async loadImplicitSubtreeResource(
+    subtreeUrl: string,
+    packageResource?: PackageResource
+  ): Promise<ParsedImplicitSubtree> {
     const cachedSubtree = this.implicitSubtreeCache.get(subtreeUrl);
     if (cachedSubtree) {
       this.implicitTilingStats.cacheHits++;
@@ -538,14 +891,17 @@ export class Tiles3DSource implements Tileset3DSource {
     this.implicitTilingStats.requestedSubtrees++;
     const loaderOptions = (this.loadOptions[this.loader.id] as Record<string, unknown>) || {};
     return await this.implicitSubtreeCache.getOrLoad(subtreeUrl, async () => {
-      return (await this.loadResourceData(subtreeUrl, {
+      const options = {
         ...this.loadOptions,
         [this.loader.id]: {
           ...loaderOptions,
           isTileset: false,
           isSubtree: true
         }
-      })) as ParsedImplicitSubtree;
+      };
+      return (await (packageResource
+        ? this.loadContentResource(subtreeUrl, packageResource, options)
+        : this.loadResourceData(subtreeUrl, options))) as ParsedImplicitSubtree;
     });
   }
 
@@ -610,3 +966,20 @@ function normalizeTiles3DRequest(input: TilesetSourceInput): TilesetSourceReques
     coreApi: (input as TilesetSourceRequest).coreApi
   };
 }
+
+/** Adds a nested CRS descriptor to each header without changing its native placement. */
+function addNestedSpatialReference(
+  nestedTileset: TilesetJSON,
+  spatialReference: TilesetSpatialReference
+): TilesetJSON {
+  const addToHeader = (header: Record<string, any>): Record<string, any> => ({
+    ...header,
+    _spatialReference: spatialReference,
+    children: Array.isArray(header.children) ? header.children.map(addToHeader) : header.children
+  });
+  return {
+    ...nestedTileset,
+    spatialMetadata: spatialReference,
+    root: addToHeader(nestedTileset.root)
+  };
+}