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

package/src/tileset-3d/format-3d-tiles/implicit-tiling.ts

@@ -23,8 +23,12 @@ export type ImplicitTileCoordinates = {
 export type ImplicitTilingDescriptor = {
   /** Absolute template URL for render content, or an empty string for a contentless hierarchy. */
   contentUrlTemplate: string;
+  /** Absolute templates for every implicit content stream, in source order. */
+  contentUrlTemplates?: string[];
   /** Non-URI content metadata inherited by each available implicit content resource. */
   contentHeader?: Record<string, any>;
+  /** Metadata inherited by every implicit content stream, in source order. */
+  contentHeaders?: Array<Record<string, any>>;
   /** Absolute template URL for subtree availability files. */
   subtreesUrlTemplate: string;
   /** Spatial subdivision used by the hierarchy. */
@@ -66,12 +70,20 @@ export type ParsedImplicitSubtree = {
   /** Availability of tiles inside this subtree. */
   tileAvailability: ImplicitAvailability;
   /**
-   * Availability of tile content; only the first multiple-content stream is currently used.
+   * Availability of tile content. Array entries correspond to content templates in source order.
    * Omitted availability denotes a metadata-only subtree with no render content.
    */
   contentAvailability?: ImplicitAvailability | ImplicitAvailability[];
   /** Availability of subtree roots immediately below this subtree. */
   childSubtreeAvailability: ImplicitAvailability;
+  /** Property-table payloads referenced by subtree metadata declarations. */
+  propertyTables?: unknown;
+  /** Property-table reference for metadata attached to each available tile. */
+  tileMetadata?: unknown;
+  /** Property-table references for metadata attached to each content stream. */
+  contentMetadata?: unknown;
+  /** Metadata entity attached to the subtree itself. */
+  subtreeMetadata?: unknown;
 };
 
 /** Runtime header produced for an available implicit tile. */
@@ -82,6 +94,20 @@ export type ImplicitTileHeader = Record<string, any> & {
   children: ImplicitTileHeader[];
   /** Optional lazy reference when this tile begins a child subtree. */
   implicitSubtree?: ImplicitSubtreeReference;
+  /** Raw subtree metadata references preserved for application-level interpretation. */
+  implicitMetadata?: ImplicitSubtreeMetadata;
+};
+
+/** Metadata references inherited by generated implicit tile headers. */
+export type ImplicitSubtreeMetadata = {
+  /** Property tables declared by the subtree. */
+  propertyTables?: unknown;
+  /** Tile-level metadata property-table reference. */
+  tileMetadata?: unknown;
+  /** Content-level metadata property-table references in content order. */
+  contentMetadata?: unknown;
+  /** Subtree-level metadata entity. */
+  subtreeMetadata?: unknown;
 };
 
 /** Result of materializing exactly one subtree resource. */
@@ -198,8 +224,8 @@ function materializeAvailableTile(
   }
 
   counters.tileCount++;
-  const contentAvailable = getAvailabilityValue(
-    getPrimaryContentAvailability(subtree.contentAvailability),
+  const contentAvailability = getContentAvailability(
+    subtree.contentAvailability,
     availabilityIndex
   );
   const children: ImplicitTileHeader[] = [];
@@ -235,7 +261,7 @@ function materializeAvailableTile(
             childIndex,
             descriptor.subdivisionScheme
           );
-          children.push(createLazyImplicitTileHeader(descriptor, childCoordinates));
+          children.push(createLazyImplicitTileHeader(subtree, descriptor, childCoordinates));
           counters.childSubtreeCount++;
         }
       }
@@ -243,10 +269,11 @@ function materializeAvailableTile(
   }
 
   return formatImplicitTileHeader(
+    subtree,
     descriptor,
     reference,
     globalCoordinates,
-    contentAvailable,
+    contentAvailability,
     children
   );
 }
@@ -259,6 +286,7 @@ function materializeAvailableTile(
  * @returns Header that participates in culling and SSE before its subtree is requested.
  */
 function createLazyImplicitTileHeader(
+  subtree: ParsedImplicitSubtree,
   descriptor: ImplicitTilingDescriptor,
   coordinates: ImplicitTileCoordinates
 ): ImplicitTileHeader {
@@ -276,7 +304,8 @@ function createLazyImplicitTileHeader(
     lodMetricType: descriptor.lodMetricType,
     lodMetricValue: descriptor.rootLodMetricValue / 2 ** coordinates.level,
     refine: descriptor.refine,
-    type: TILE_TYPE.EMPTY
+    type: TILE_TYPE.EMPTY,
+    implicitMetadata: getImplicitSubtreeMetadata(subtree)
   };
 }
 
@@ -286,28 +315,48 @@ function createLazyImplicitTileHeader(
  * @param descriptor - Shared implicit hierarchy description.
  * @param reference - Current subtree reference used to build stable IDs.
  * @param coordinates - Global tile coordinates.
- * @param contentAvailable - Whether the subtree declares render content for this tile.
+ * @param contentAvailability - Availability for each content stream in source order.
  * @param children - Materialized or lazy child headers.
  * @returns Runtime tile header.
  */
 function formatImplicitTileHeader(
+  subtree: ParsedImplicitSubtree,
   descriptor: ImplicitTilingDescriptor,
   reference: ImplicitSubtreeReference,
   coordinates: ImplicitTileCoordinates,
-  contentAvailable: boolean,
+  contentAvailability: boolean[],
   children: ImplicitTileHeader[]
 ): ImplicitTileHeader {
-  const contentUrl =
-    contentAvailable && descriptor.contentUrlTemplate
-      ? replaceImplicitUrlTemplate(descriptor.contentUrlTemplate, coordinates)
-      : undefined;
+  const contentUrlTemplates = descriptor.contentUrlTemplates?.length
+    ? descriptor.contentUrlTemplates
+    : [descriptor.contentUrlTemplate];
+  const contentEntries = contentUrlTemplates
+    .map((templateUrl, contentIndex) => {
+      if (!contentAvailability[contentIndex] || !templateUrl) {
+        return null;
+      }
+      return {
+        contentIndex,
+        contentUrl: replaceImplicitUrlTemplate(templateUrl, coordinates)
+      };
+    })
+    .filter((entry): entry is {contentIndex: number; contentUrl: string} => Boolean(entry));
+  const availableContentUrls = contentEntries.map(entry => entry.contentUrl);
+  const content = contentEntries.map(({contentIndex, contentUrl}) => ({
+    ...(descriptor.contentHeaders?.[contentIndex] ||
+      (contentIndex === 0 ? descriptor.contentHeader : {}) ||
+      {}),
+    uri: contentUrl
+  }));
+  const contentUrl = availableContentUrls[0];
   const lodMetricValue = descriptor.rootLodMetricValue / 2 ** coordinates.level;
 
   return {
     id: getImplicitTileId(reference, coordinates),
     children,
     contentUrl,
-    content: contentUrl ? {...descriptor.contentHeader, uri: contentUrl} : undefined,
+    content: content.length > 1 ? content : content[0],
+    contentUrls: availableContentUrls,
     refine: descriptor.refine,
     type: getImplicitTileType(contentUrl),
     lodMetricType: descriptor.lodMetricType,
@@ -317,7 +366,36 @@ function formatImplicitTileHeader(
       descriptor.rootBoundingVolume,
       coordinates,
       descriptor.subdivisionScheme
-    )
+    ),
+    implicitMetadata: getImplicitSubtreeMetadata(subtree)
+  };
+}
+
+/**
+ * Copies subtree metadata references without interpreting property-table schemas.
+ *
+ * Keeping the references on generated headers makes metadata available to applications while
+ * avoiding a false promise that the runtime has already decoded classes, enums, or values.
+ *
+ * @param subtree - Parsed subtree containing optional metadata declarations.
+ * @returns Metadata references, or `undefined` when the subtree declares none.
+ */
+function getImplicitSubtreeMetadata(
+  subtree: ParsedImplicitSubtree
+): ImplicitSubtreeMetadata | undefined {
+  if (
+    !subtree.propertyTables &&
+    subtree.tileMetadata === undefined &&
+    !subtree.contentMetadata &&
+    subtree.subtreeMetadata === undefined
+  ) {
+    return undefined;
+  }
+  return {
+    propertyTables: subtree.propertyTables,
+    tileMetadata: subtree.tileMetadata,
+    contentMetadata: subtree.contentMetadata,
+    subtreeMetadata: subtree.subtreeMetadata
   };
 }
 
@@ -356,17 +434,17 @@ function getAvailabilityValue(availability: ImplicitAvailability, index: number)
 }
 
 /**
- * Selects the first content availability stream until multiple contents are supported.
+ * Reads every content availability stream for one tile in descriptor/source order.
  *
  * @param availability - Single or multiple-content availability declaration.
- * @returns Primary content availability declaration.
+ * @returns Availability flags aligned with the content URL templates.
  */
-function getPrimaryContentAvailability(
-  availability: ImplicitAvailability | ImplicitAvailability[] | undefined
-): ImplicitAvailability {
-  return Array.isArray(availability)
-    ? availability[0] || {constant: 0}
-    : availability || {constant: 0};
+function getContentAvailability(
+  availability: ImplicitAvailability | ImplicitAvailability[] | undefined,
+  index: number
+): boolean[] {
+  const streams = Array.isArray(availability) ? availability : [availability];
+  return streams.map(stream => getAvailabilityValue(stream || {constant: 0}, index));
 }
 
 /**

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

@@ -2,7 +2,7 @@
 // SPDX-License-Identifier: MIT
 // Copyright (c) vis.gl contributors
 
-import {path} from '@loaders.gl/loader-utils';
+import {path, RequestCache} 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';
@@ -26,6 +26,7 @@ import {getZoomFromBoundingVolume} from '../helpers/zoom';
 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 {
   materializeImplicitSubtree,
   type ImplicitSubtreeReference,
@@ -92,12 +93,8 @@ 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();
-  /** Parsed subtree promises keyed by final source URL for request deduplication and LRU reuse. */
-  private readonly implicitSubtreeCache: Map<string, Promise<ParsedImplicitSubtree>> = new Map();
-  /** URLs whose subtree resource requests have not settled. */
-  private readonly pendingImplicitSubtreeUrls: Set<string> = new Set();
-  /** Maximum number of settled parsed subtrees retained by this source. */
-  private readonly maximumCachedSubtrees: number;
+  /** 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}. */
   private readonly implicitTilingStats: Omit<
     ImplicitTilingStats,
@@ -132,9 +129,10 @@ export class Tiles3DSource implements Tileset3DSource {
     const maximumCachedSubtrees = Number(
       (loadOptions['3d-tiles'] as Record<string, unknown> | undefined)?.maximumCachedSubtrees
     );
-    this.maximumCachedSubtrees = Number.isFinite(maximumCachedSubtrees)
+    const maximumCacheEntries = Number.isFinite(maximumCachedSubtrees)
       ? Math.max(0, Math.floor(maximumCachedSubtrees))
       : DEFAULT_MAXIMUM_CACHED_SUBTREES;
+    this.implicitSubtreeCache = new RequestCache({maxEntries: maximumCacheEntries});
   }
 
   /**
@@ -147,7 +145,6 @@ export class Tiles3DSource implements Tileset3DSource {
     this.destroyed = true;
     this.tileUrlCache.clear();
     this.implicitSubtreeCache.clear();
-    this.pendingImplicitSubtreeUrls.clear();
   }
 
   /**
@@ -205,7 +202,8 @@ export class Tiles3DSource implements Tileset3DSource {
       tileset: this.rootTileset,
       lodMetricType: this.rootTileset.lodMetricType,
       lodMetricValue: this.rootTileset.lodMetricValue,
-      refine: this.rootTileset.root?.refine
+      refine: this.rootTileset.root?.refine,
+      spatialReference: get3DTilesSpatialReference(this.rootTileset)
     };
   }
 
@@ -275,7 +273,7 @@ export class Tiles3DSource implements Tileset3DSource {
    * Loads binary content or nested tileset JSON for a runtime tile.
    */
   async loadTileContent(tile: Tile3D): Promise<TileContentLoadResult> {
-    const contentUrl = this.getTileUrl(tile.contentUrl);
+    const contentUrls = (tile.contentUrls || [tile.contentUrl]).filter(Boolean);
     const tilesetLoaderOptions =
       (this.loadOptions[this.loader.id] as Record<string, unknown>) || {};
     const options = {
@@ -289,12 +287,18 @@ export class Tiles3DSource implements Tileset3DSource {
       }
     };
 
-    const content = await this.loadResourceData(contentUrl, options);
-    tile.content = content;
+    const contents = await Promise.all(
+      contentUrls.map(contentUrl => this.loadResourceData(this.getTileUrl(contentUrl), options))
+    );
+    tile.contents = contents;
+    tile.content = contents[0] || null;
+    const nestedTilesets = contents.filter(content => content?.shape === 'tileset3d');
 
     return {
       loaded: true,
-      nestedTileset: content?.shape === 'tileset3d' ? content : undefined
+      contents,
+      nestedTileset: nestedTilesets[0],
+      nestedTilesets
     };
   }
 
@@ -350,8 +354,8 @@ export class Tiles3DSource implements Tileset3DSource {
   getImplicitTilingStats(): ImplicitTilingStats {
     return {
       ...this.implicitTilingStats,
-      cachedSubtrees: this.implicitSubtreeCache.size - this.pendingImplicitSubtreeUrls.size,
-      pendingSubtrees: this.pendingImplicitSubtreeUrls.size
+      cachedSubtrees: this.implicitSubtreeCache.size - this.implicitSubtreeCache.pendingSize,
+      pendingSubtrees: this.implicitSubtreeCache.pendingSize
     };
   }
 
@@ -458,7 +462,8 @@ export class Tiles3DSource implements Tileset3DSource {
    * Updates content-format flags and installs nested tileset subtrees.
    */
   onTileLoaded(tileset: Tileset3D, tile: Tile3D, loadResult: TileContentLoadResult): void {
-    const {extensionsRemoved = []} = tile.content?.gltf || {};
+    const contents = tile.contents.length ? tile.contents : [tile.content];
+    const extensionsRemoved = contents.flatMap(content => content?.gltf?.extensionsRemoved || []);
     if (extensionsRemoved.includes('KHR_draco_mesh_compression')) {
       this.contentFormats.draco = true;
     }
@@ -469,8 +474,10 @@ export class Tiles3DSource implements Tileset3DSource {
       this.contentFormats.ktx2 = true;
     }
 
-    if (loadResult.nestedTileset) {
-      tileset._initializeTileHeaders(loadResult.nestedTileset, tile);
+    const nestedTilesets =
+      loadResult.nestedTilesets || (loadResult.nestedTileset ? [loadResult.nestedTileset] : []);
+    for (const nestedTileset of nestedTilesets) {
+      tileset._initializeTileHeaders(nestedTileset, tile);
     }
   }
 
@@ -525,33 +532,21 @@ export class Tiles3DSource implements Tileset3DSource {
     const cachedSubtree = this.implicitSubtreeCache.get(subtreeUrl);
     if (cachedSubtree) {
       this.implicitTilingStats.cacheHits++;
-      this.implicitSubtreeCache.delete(subtreeUrl);
-      this.implicitSubtreeCache.set(subtreeUrl, cachedSubtree);
       return await cachedSubtree;
     }
 
     this.implicitTilingStats.requestedSubtrees++;
-    this.pendingImplicitSubtreeUrls.add(subtreeUrl);
     const loaderOptions = (this.loadOptions[this.loader.id] as Record<string, unknown>) || {};
-    const subtreePromise = this.loadResourceData(subtreeUrl, {
-      ...this.loadOptions,
-      [this.loader.id]: {
-        ...loaderOptions,
-        isTileset: false,
-        isSubtree: true
-      }
-    }) as Promise<ParsedImplicitSubtree>;
-    this.implicitSubtreeCache.set(subtreeUrl, subtreePromise);
-
-    try {
-      return await subtreePromise;
-    } catch (error) {
-      this.implicitSubtreeCache.delete(subtreeUrl);
-      throw error;
-    } finally {
-      this.pendingImplicitSubtreeUrls.delete(subtreeUrl);
-      this.trimImplicitSubtreeCache();
-    }
+    return await this.implicitSubtreeCache.getOrLoad(subtreeUrl, async () => {
+      return (await this.loadResourceData(subtreeUrl, {
+        ...this.loadOptions,
+        [this.loader.id]: {
+          ...loaderOptions,
+          isTileset: false,
+          isSubtree: true
+        }
+      })) as ParsedImplicitSubtree;
+    });
   }
 
   /**
@@ -586,21 +581,6 @@ export class Tiles3DSource implements Tileset3DSource {
     }
     return materializedTileCount;
   }
-
-  /** Evicts least-recently-used settled subtree entries until the configured bound is met. */
-  private trimImplicitSubtreeCache(): void {
-    if (this.implicitSubtreeCache.size <= this.maximumCachedSubtrees) {
-      return;
-    }
-    for (const subtreeUrl of this.implicitSubtreeCache.keys()) {
-      if (!this.pendingImplicitSubtreeUrls.has(subtreeUrl)) {
-        this.implicitSubtreeCache.delete(subtreeUrl);
-      }
-      if (this.implicitSubtreeCache.size <= this.maximumCachedSubtrees) {
-        break;
-      }
-    }
-  }
 }
 
 function isTilesetRequest(input: TilesetSourceInput): input is TilesetSourceRequest {

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

@@ -25,6 +25,8 @@ import type {
 import {getZoomFromExtent, getZoomFromFullExtent} from '../helpers/zoom';
 import {TILESET_TYPE} from '../../constants';
 import type {TilesetTraverser, TilesetTraverserProps} from '../common/tileset-traverser';
+import {getI3SSpatialReference} from '../../spatial/format-spatial-reference';
+import {I3SSpatialTransformer} from '../../spatial/i3s-spatial-transformer';
 
 const EMPTY_CONTENT_FORMATS: TilesetContentFormats = {
   draco: false,
@@ -63,6 +65,10 @@ export class I3SSource implements Tileset3DSource {
   private readonly queryParams: Record<string, string> = {};
   private readonly resolver?: TilesetSourceResolver;
   private rootTileset: TilesetJSON;
+  /** Spatial adapter created lazily after Tileset3D applies target options. */
+  private spatialTransformer?: I3SSpatialTransformer;
+  /** Root header prepared after asynchronous elevation sampling. */
+  private preparedRootHeader?: any;
 
   /**
    * Creates an I3S source.
@@ -79,6 +85,7 @@ export class I3SSource implements Tileset3DSource {
     this.resolver = request.resolver;
     this.coreApi = request.coreApi;
     this.loadOptions = loadOptions;
+    this.initializeQueryParams(loadOptions);
   }
 
   /**
@@ -86,7 +93,7 @@ export class I3SSource implements Tileset3DSource {
    */
   async initialize(): Promise<void> {
     if (!this.rootTileset) {
-      this.rootTileset = await this.loadRootData(this.url, this.loadOptions);
+      this.rootTileset = await this.loadRootData(this.getTileUrl(this.url), this.loadOptions);
     }
     this.tileset = this.rootTileset;
 
@@ -94,14 +101,6 @@ export class I3SSource implements Tileset3DSource {
       this.rootTileset.root = await this.rootTileset.root;
     }
 
-    const i3sOptions = this.loadOptions.i3s;
-    if (i3sOptions && typeof i3sOptions === 'object' && 'token' in i3sOptions) {
-      const token = (i3sOptions as Record<string, unknown>).token;
-      if (typeof token === 'string') {
-        this.queryParams.token = token;
-      }
-    }
-
     this.metadata = {
       type: this.type,
       loader: this.loader,
@@ -110,7 +109,8 @@ export class I3SSource implements Tileset3DSource {
       tileset: this.rootTileset,
       lodMetricType: this.rootTileset.lodMetricType,
       lodMetricValue: this.rootTileset.lodMetricValue,
-      refine: this.rootTileset.root?.refine
+      refine: this.rootTileset.root?.refine,
+      spatialReference: getI3SSpatialReference(this.rootTileset)
     };
   }
 
@@ -131,6 +131,26 @@ export class I3SSource implements Tileset3DSource {
     return this.getMetadata().tileset;
   }
 
+  /** Prepare option-dependent spatial state and the asynchronously placed root bound. */
+  async prepareTileset(tileset: Tileset3D): Promise<void> {
+    const spatialReference = tileset.spatialReference;
+    if (spatialReference.status === 'unresolved') {
+      throw new Error(
+        spatialReference.warnings[0] ||
+          'I3S spatial operations cannot be resolved from the supplied metadata and options'
+      );
+    }
+    if (spatialReference.status !== 'transformable' && spatialReference.status !== 'transformed') {
+      return;
+    }
+    this.spatialTransformer ||= new I3SSpatialTransformer(
+      spatialReference,
+      tileset.options.spatial
+    );
+    tileset.spatialReference = this.spatialTransformer.spatialReference;
+    this.preparedRootHeader = await this.transformTileHeader(this.getMetadata().tileset.root);
+  }
+
   /**
    * Creates the runtime root tile for an I3S subtree.
    */
@@ -139,7 +159,11 @@ export class I3SSource 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;
+    if (this.spatialTransformer && !this.preparedRootHeader) {
+      throw new Error('I3S spatial root header was not prepared before tile initialization');
+    }
+    const rootTile = new Tile3DNode(tileset, rootHeader, parentTile || undefined);
     if (parentTile) {
       parentTile.children.push(rootTile);
       rootTile.depth = parentTile.depth + 1;
@@ -170,16 +194,22 @@ export class I3SSource implements Tileset3DSource {
         _tileOptions: {
           attributeUrls: tile.header.attributeUrls,
           textureUrl: tile.header.textureUrl,
+          textureUrls: tile.header.textureUrls,
           textureFormat: tile.header.textureFormat,
           textureLoaderOptions: tile.header.textureLoaderOptions,
           materialDefinition: tile.header.materialDefinition,
+          layerType: tile.header.layerType,
+          pointRenderer: tile.header.pointRenderer,
+          pointSymbol: tile.header.pointSymbol,
           isDracoGeometry: tile.header.isDracoGeometry,
           mbs: tile.header.mbs
         },
         _tilesetOptions: {
           store: metadata.tileset.store,
           attributeStorageInfo: metadata.tileset.attributeStorageInfo,
-          fields: metadata.tileset.fields
+          fields: metadata.tileset.fields,
+          spatialReference: tile.tileset.spatialReference,
+          spatialOptions: tile.tileset.options.spatial
         },
         isTileHeader: false
       }
@@ -198,8 +228,9 @@ export class I3SSource implements Tileset3DSource {
     _frameState: FrameState
   ): Promise<any> {
     const metadata = this.getMetadata();
-    if (metadata.tileset.nodePages) {
-      return await metadata.tileset.nodePagesTile.formTileFromNodePages(childId);
+    if (metadata.tileset.nodePages || metadata.tileset.pointNodePages) {
+      const header = await metadata.tileset.nodePagesTile.formTileFromNodePages(childId);
+      return await this.transformTileHeader(header);
     }
 
     const nodeUrl = this.getTileUrl(`${this.url}/nodes/${childId}`);
@@ -215,7 +246,8 @@ export class I3SSource implements Tileset3DSource {
       }
     };
 
-    return await this.loadResourceData(nodeUrl, options);
+    const header = await this.loadResourceData(nodeUrl, options);
+    return await this.transformTileHeader(header);
   }
 
   /**
@@ -230,14 +262,48 @@ export class I3SSource implements Tileset3DSource {
       return tilePath;
     }
 
-    const queryParams = new URLSearchParams(this.queryParams).toString();
-    return `${tilePath}${tilePath.includes('?') ? '&' : '?'}${queryParams}`;
+    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 queryParams = new URLSearchParams();
+    for (const [key, value] of Object.entries(this.queryParams)) {
+      if (!existingQueryKeys.has(key)) {
+        queryParams.set(key, value);
+      }
+    }
+
+    const queryString = queryParams.toString();
+    return queryString ? `${tilePath}${existingQuery ? '&' : ''}${queryString}` : tilePath;
   }
 
   /**
    * Derives the default view state from full extent or store extent metadata.
    */
-  getViewState(_rootTile: Tile3D | null): TilesetSourceViewState {
+  getViewState(rootTile: Tile3D | null): TilesetSourceViewState {
+    if (this.spatialTransformer && rootTile) {
+      const center = new Vector3(rootTile.boundingVolume.center);
+      const cartographicCenter = new Vector3(rootTile.header.i3sLodMbs.slice(0, 3));
+      if (this.spatialTransformer.targetCoordinateFrame === 'geographic') {
+        return {
+          boundingVolume: rootTile.boundingVolume,
+          cartographicCenter,
+          cartesianCenter: center,
+          zoom: 1
+        };
+      }
+      return {
+        boundingVolume: rootTile.boundingVolume,
+        cartographicCenter,
+        cartesianCenter: center,
+        zoom: 1
+      };
+    }
     const metadata = this.getMetadata();
     const fullExtent = metadata.tileset.fullExtent;
     if (fullExtent) {
@@ -325,6 +391,20 @@ export class I3SSource implements Tileset3DSource {
     return await this.loadWithCoreApi(url, options);
   }
 
+  /**
+   * Initializes query parameters before any URL-backed resource is requested.
+   * @param loadOptions Loader options that may contain an ArcGIS token.
+   */
+  private initializeQueryParams(loadOptions: LoaderOptions): void {
+    const i3sOptions = loadOptions.i3s;
+    if (i3sOptions && typeof i3sOptions === 'object' && 'token' in i3sOptions) {
+      const token = (i3sOptions as Record<string, unknown>).token;
+      if (typeof token === 'string') {
+        this.queryParams.token = token;
+      }
+    }
+  }
+
   /**
    * Loads tile metadata or content through an injected resolver when present, otherwise through the injected core API.
    */
@@ -335,6 +415,27 @@ export class I3SSource implements Tileset3DSource {
 
     return await this.loadWithCoreApi(url, options);
   }
+
+  /** Transform one I3S header bound after target options and elevation providers are available. */
+  private async transformTileHeader(header: any): Promise<any> {
+    if (!this.spatialTransformer) {
+      return header;
+    }
+    const sourceBounds = {
+      mbs: header.mbs,
+      obb: header.obb,
+      normalReferenceFrame: this.getMetadata().tileset.store?.normalReferenceFrame
+    };
+    const transformedBounds = await this.spatialTransformer.transformBoundsAsync(sourceBounds);
+    return {
+      ...header,
+      // Tileset3D traversal and culling operate in WGS84 ECEF independently of content output.
+      boundingVolume: transformedBounds.boundingVolume,
+      // Preserve the renderer/output-frame bound for applications and content coordination.
+      spatialBoundingVolume: transformedBounds.spatialBoundingVolume,
+      i3sLodMbs: transformedBounds.i3sLodMbs
+    };
+  }
 }
 
 function isTilesetRequest(input: TilesetSourceInput): input is TilesetSourceRequest {