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

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

@@ -7,6 +7,7 @@
 
 import {Vector3, Matrix4} from '@math.gl/core';
 import {CullingVolume} from '@math.gl/culling';
+import type {CullingResult} from '@math.gl/culling';
 
 // Note: circular dependency
 import type {Tileset3D} from './tileset-3d';
@@ -33,6 +34,57 @@ import {
 
 const scratchVector = new Vector3();
 
+/**
+ * Classifies render-content visibility across all content volumes owned by a tile.
+ *
+ * Content volumes form a union: one visible content entry keeps the tile renderable even when
+ * another entry is outside the frustum or clipping planes. The traversal volume is intentionally
+ * not used here except as a fallback when a tile has no content-specific volume. This separation
+ * keeps clipping render-only and prevents a tight content volume from pruning descendants.
+ *
+ * @param contentVolumes - Transformed content volumes in source order.
+ * @param fallbackVolume - Tile volume used when content does not declare its own volume.
+ * @param cullingVolume - Current view frustum.
+ * @param visibilityPlaneMask - Parent visibility mask optimization.
+ * @param clippingPlanes - Optional world-space planes applied to render content only.
+ * @returns Union visibility classification for the renderable content.
+ */
+export function getContentVisibility(
+  contentVolumes: any[],
+  fallbackVolume: any,
+  cullingVolume: CullingVolume,
+  visibilityPlaneMask: number | undefined,
+  clippingPlanes: any[] = []
+): CullingResult {
+  const volumes = contentVolumes.length ? contentVolumes : [fallbackVolume];
+  let visibleVolume = false;
+  let intersectingVolume = false;
+  for (const contentVolume of volumes) {
+    let visibility: CullingResult = 'inside';
+    if (visibilityPlaneMask !== CullingVolume.MASK_INSIDE) {
+      visibility = cullingVolume.computeVisibility(contentVolume);
+      if (visibility === 'outside') {
+        continue;
+      }
+    }
+    let clipped = false;
+    for (const clippingPlane of clippingPlanes) {
+      if (contentVolume.intersectPlane(clippingPlane) === 'outside') {
+        clipped = true;
+        break;
+      }
+    }
+    if (!clipped) {
+      visibleVolume = true;
+      intersectingVolume = intersectingVolume || visibility === 'intersecting';
+    }
+  }
+  if (!visibleVolume) {
+    return 'outside';
+  }
+  return intersectingVolume ? 'intersecting' : 'inside';
+}
+
 function defined(x) {
   return x !== undefined && x !== null;
 }
@@ -69,6 +121,8 @@ export class Tile3D {
   refine: TILE_REFINEMENT;
   type: string;
   contentUrl: string;
+  /** Resolved render-content URLs in source order; empty for contentless tiles. */
+  contentUrls: string[] = [];
   /** Different refinement algorithms used by I3S and 3D tiles */
   lodMetricType = 'geometricError';
   /**
@@ -91,6 +145,17 @@ export class Tile3D {
    * not the content's metadata in the tileset JSON file.
    */
   content: any = null;
+  /** Loaded payloads in the same order as {@link contentUrls}; `content` remains the primary payload. */
+  contents: any[] = [];
+  /**
+   * Metadata entity attached to this tile in the source tileset, if present.
+   *
+   * This is the raw 3D Tiles metadata reference. The generic tiles runtime preserves it without
+   * decoding schema classes or binary property tables.
+   */
+  metadata: Record<string, any> | null = null;
+  /** Raw metadata entities attached to tile contents, in content source order. */
+  contentMetadata: Array<Record<string, any> | null> = [];
   contentState: number = TILE_CONTENT_STATE.UNLOADED;
   gpuMemoryUsageInBytes: number = 0;
 
@@ -143,8 +208,26 @@ export class Tile3D {
   private _visible: boolean | undefined = undefined;
 
   private _contentBoundingVolume: any;
+  private _contentBoundingVolumes: any[] = [];
+  /** Source content-volume headers retained after render content is unloaded. */
+  private _contentBoundingVolumeHeaders: any[] = [];
   private _viewerRequestVolume: any;
 
+  /** Bounding volume used to cull the tile's first renderable content entry. */
+  get contentBoundingVolume(): any {
+    return this._contentBoundingVolume;
+  }
+
+  /** All transformed render-content bounding volumes, including tile-volume fallbacks. */
+  get contentBoundingVolumes(): any[] {
+    return this._contentBoundingVolumes;
+  }
+
+  /** Bounding volume that limits when this tile may be requested, when declared. */
+  get viewerRequestVolume(): any {
+    return this._viewerRequestVolume;
+  }
+
   _initialTransform: Matrix4 = new Matrix4();
 
   // Used by traverser, cannot be marked private
@@ -199,6 +282,12 @@ export class Tile3D {
     this.refine = this._getRefine(header.refine);
     this.type = header.type;
     this.contentUrl = header.contentUrl;
+    this.contentUrls = header.contentUrls || (header.contentUrl ? [header.contentUrl] : []);
+    this.metadata = header.metadata || null;
+    const contentHeaders = Array.isArray(header.content) ? header.content : [header.content];
+    this.contentMetadata = contentHeaders
+      .filter(Boolean)
+      .map(contentHeader => contentHeader.metadata || null);
     this.childrenState = header.implicitSubtree ? 'unloaded' : 'ready';
 
     this._initializeLodMetric(header);
@@ -368,7 +457,11 @@ export class Tile3D {
    * Memory usage of tile on GPU
    */
   _getGpuMemoryUsageInBytes(): number {
-    return this.content.gpuMemoryUsageInBytes || this.content.byteLength || 0;
+    const contents = this.contents.length ? this.contents : [this.content];
+    return contents.reduce(
+      (total, content) => total + (content?.gpuMemoryUsageInBytes || content?.byteLength || 0),
+      0
+    );
   }
 
   /**
@@ -487,6 +580,11 @@ export class Tile3D {
     try {
       const loadResult = await this.tileset.source.loadTileContent(this);
 
+      if (loadResult.contents) {
+        this.contents = loadResult.contents;
+        this.content = this.contents[0] || null;
+      }
+
       if (this.tileset.options.contentLoader) {
         await this.tileset.options.contentLoader(this);
       }
@@ -585,6 +683,9 @@ export class Tile3D {
     this.refine = this._getRefine(materializedHeader.refine);
     this.type = materializedHeader.type;
     this.contentUrl = materializedHeader.contentUrl;
+    this.contentUrls =
+      materializedHeader.contentUrls ||
+      (materializedHeader.contentUrl ? [materializedHeader.contentUrl] : []);
     this._initializeLodMetric(materializedHeader);
     this._updateLodMetricScale();
     this._initializeBoundingVolumes(this.header);
@@ -595,9 +696,12 @@ export class Tile3D {
 
   // Unloads the tile's content.
   unloadContent() {
-    if (this.content && this.content.destroy) {
-      this.content.destroy();
+    for (const content of this.contents.length ? this.contents : [this.content]) {
+      if (content && content.destroy) {
+        content.destroy();
+      }
     }
+    this.contents = [];
     this.content = null;
     if (this.header.content && this.header.content.destroy) {
       this.header.content.destroy();
@@ -732,47 +836,22 @@ export class Tile3D {
     return cullingVolume.computeVisibilityWithPlaneMask(boundingVolume, parentVisibilityPlaneMask);
   }
 
-  // Assuming the tile's bounding volume intersects the culling volume, determines
-  // whether the tile's content's bounding volume intersects the culling volume.
-  // @param {FrameState} frameState The frame state.
-  // @returns {Intersect} The result of the intersection: the tile's content is completely outside, completely inside, or intersecting the culling volume.
-  contentVisibility() {
-    return true;
-
-    // TODO restore
-    /*
-    // Assumes the tile's bounding volume intersects the culling volume already, so
-    // just return Intersect.INSIDE if there is no content bounding volume.
-    if (!defined(this.contentBoundingVolume)) {
-      return Intersect.INSIDE;
-    }
-
-    if (this._visibilityPlaneMask === CullingVolume.MASK_INSIDE) {
-      // The tile's bounding volume is completely inside the culling volume so
-      // the content bounding volume must also be inside.
-      return Intersect.INSIDE;
-    }
-
-    // PERFORMANCE_IDEA: is it possible to burn less CPU on this test since we know the
-    // tile's (not the content's) bounding volume intersects the culling volume?
-    const cullingVolume = frameState.cullingVolume;
-    const boundingVolume = tile.contentBoundingVolume;
-
-    const tileset = this.tileset;
-    const clippingPlanes = tileset.clippingPlanes;
-    if (defined(clippingPlanes) && clippingPlanes.enabled) {
-      const intersection = clippingPlanes.computeIntersectionWithBoundingVolume(
-        boundingVolume,
-        tileset.clippingPlanesOriginMatrix
-      );
-      this._isClipped = intersection !== Intersect.INSIDE;
-      if (intersection === Intersect.OUTSIDE) {
-        return Intersect.OUTSIDE;
-      }
-    }
-
-    return cullingVolume.computeVisibility(boundingVolume);
-    */
+  /**
+   * Determines whether renderable content intersects the view and configured clipping planes.
+   *
+   * Clipping planes are render-only constraints; traversal continues to use the tile volume.
+   *
+   * @param frameState Current camera, culling, and optional clipping-plane state.
+   * @returns The content visibility classification.
+   */
+  contentVisibility(frameState: FrameState): CullingResult {
+    return getContentVisibility(
+      this._contentBoundingVolumes,
+      this.boundingVolume,
+      frameState.cullingVolume,
+      this._visibilityPlaneMask,
+      frameState.clippingPlanes
+    );
   }
 
   /**
@@ -898,6 +977,7 @@ export class Tile3D {
 
   _initializeBoundingVolumes(tileHeader) {
     this._contentBoundingVolume = null;
+    this._contentBoundingVolumeHeaders = [];
     this._viewerRequestVolume = null;
 
     this._updateBoundingVolume(tileHeader);
@@ -906,6 +986,7 @@ export class Tile3D {
   _initializeContent(tileHeader) {
     // Empty tile by default
     this.content = {_tileset: this.tileset, _tile: this};
+    this.contents = [];
     this.hasEmptyContent = true;
     this.contentState = TILE_CONTENT_STATE.UNLOADED;
 
@@ -913,7 +994,7 @@ export class Tile3D {
     // This is `false` until the tile's content is loaded.
     this.hasTilesetContent = false;
 
-    if (tileHeader.contentUrl) {
+    if (tileHeader.contentUrl || tileHeader.contentUrls?.length) {
       this.content = null;
       this.hasEmptyContent = false;
     }
@@ -961,18 +1042,23 @@ export class Tile3D {
    * `content`.
    */
   _isTileset(): boolean {
-    return this.content?.shape === 'tileset3d';
+    return (this.contents.length ? this.contents : [this.content]).some(
+      content => content?.shape === 'tileset3d'
+    );
   }
 
   _onContentLoaded() {
     // Vector and Geometry tile rendering do not support the skip LOD optimization.
-    switch (this.content && this.content.type) {
-      case 'vctr':
-      case 'geom':
-        // @ts-ignore
-        this.tileset._traverser.disableSkipLevelOfDetail = true;
-        break;
-      default:
+    const contents = this.contents.length ? this.contents : [this.content];
+    for (const content of contents) {
+      switch (content && content.type) {
+        case 'vctr':
+        case 'geom':
+          // @ts-ignore
+          this.tileset._traverser.disableSkipLevelOfDetail = true;
+          break;
+        default:
+      }
     }
 
     // The content may be tileset json
@@ -1003,23 +1089,24 @@ export class Tile3D {
     }
 
     const content = header.content;
-    if (!content) {
-      return;
-    }
-
-    // TODO Cesium specific
-    // Non-leaf tiles may have a content bounding-volume, which is a tight-fit bounding volume
-    // around only the features in the tile. This box is useful for culling for rendering,
-    // but not for culling for traversing the tree since it does not guarantee spatial coherence, i.e.,
-    // since it only bounds features in the tile, not the entire tile, children may be
-    // outside of this box.
-    if (content.boundingVolume) {
-      this._contentBoundingVolume = createBoundingVolume(
-        content.boundingVolume,
-        this.computedTransform,
-        this._contentBoundingVolume
-      );
+    if (content) {
+      this._contentBoundingVolumeHeaders = Array.isArray(content) ? content : [content];
     }
+    const contentHeaders = content
+      ? Array.isArray(content)
+        ? content
+        : [content]
+      : this._contentBoundingVolumeHeaders;
+    // Preserve source order: an unbounded content entry uses the tile volume at its
+    // corresponding index rather than being appended after bounded sibling entries.
+    this._contentBoundingVolumes = contentHeaders.length
+      ? contentHeaders.map(headerEntry =>
+          headerEntry?.boundingVolume
+            ? createBoundingVolume(headerEntry.boundingVolume, this.computedTransform)
+            : this.boundingVolume
+        )
+      : [this.boundingVolume];
+    this._contentBoundingVolume = this._contentBoundingVolumes[0] || null;
   }
 
   /**

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

@@ -22,6 +22,11 @@ import type {FoveatedInterpolationCallback} from '../helpers/tiles-3d-request-pr
 import type {GeospatialViewport, Viewport} from '../../types';
 import {Tile3D} from './tile-3d';
 import {TILESET_TYPE} from '../../constants';
+import type {TilesetSpatialOptions, TilesetSpatialReference} from '../../spatial/spatial-types';
+import {
+  applyTilesetSpatialOptions,
+  createTilesetSpatialReference
+} from '../../spatial/spatial-types';
 
 import {TilesetTraverser} from './tileset-traverser';
 import {
@@ -72,8 +77,16 @@ export type Tileset3DProps = {
 
   ellipsoid?: object;
   modelMatrix?: Matrix4;
+  /** Automatic CRS output options and expert source-metadata recovery overrides. */
+  spatial?: TilesetSpatialOptions;
 
   maximumScreenSpaceError?: number;
+  /**
+   * Enables replacement traversal that may skip hierarchy levels while retaining ready ancestors
+   * as coverage. This trades temporary overdraw for faster refinement on deep trees.
+   * @default false
+   */
+  skipLevelOfDetail?: boolean;
   /** Enables perspective dynamic SSE to reduce distant, horizon-facing refinement. */
   dynamicScreenSpaceError?: boolean;
   /** Base dynamic SSE fog density in inverse meters. */
@@ -139,6 +152,8 @@ type Props = {
   onTraversalComplete: (selectedTiles: Tile3D[]) => Tile3D[];
   onUpdate: () => void;
   maximumScreenSpaceError: number;
+  /** Whether replacement traversal may skip levels while retaining ancestor coverage. */
+  skipLevelOfDetail: boolean;
   /** Whether perspective dynamic SSE is enabled. */
   dynamicScreenSpaceError: boolean;
   /** Base dynamic SSE fog density in inverse meters. */
@@ -170,6 +185,8 @@ type Props = {
   basePath: string;
   contentLoader?: (tile: Tile3D) => Promise<void>;
   i3s: Record<string, any>;
+  /** Automatic CRS output options and expert source-metadata recovery overrides. */
+  spatial: TilesetSpatialOptions;
 };
 
 const BYTES_PER_MEBIBYTE = 1024 * 1024;
@@ -264,6 +281,7 @@ const DEFAULT_PROPS: Props = {
   foveatedInterpolationCallback: interpolateLinearly,
   foveatedTimeDelay: 0.2,
   maximumScreenSpaceError: 8,
+  skipLevelOfDetail: false,
   dynamicScreenSpaceError: true,
   dynamicScreenSpaceErrorDensity: 2.0e-4,
   dynamicScreenSpaceErrorFactor: 24,
@@ -275,7 +293,8 @@ const DEFAULT_PROPS: Props = {
   loadOptions: {fetch: {}},
   attributions: [],
   basePath: '',
-  i3s: {}
+  i3s: {},
+  spatial: {}
 };
 
 const TILES_TOTAL = 'Tiles In Tileset(s)';
@@ -314,6 +333,18 @@ export class Tileset3D {
   root: Tile3D | null = null;
   roots: Record<string, Tile3D> = {};
   asset: Record<string, any> = {};
+  /** Inline metadata schema declared by the source tileset, when present. */
+  schema: Record<string, any> | null = null;
+  /** External metadata schema URI declared by the source tileset, when present. */
+  schemaUri: string | null = null;
+  /** Metadata groups declared by the source tileset, in source order. */
+  groups: Array<Record<string, any>> = [];
+  /** Tileset-wide metadata entity, preserved without property-table decoding. */
+  metadata: Record<string, any> | null = null;
+  /** Tileset statistics metadata, preserved for application-level inspection. */
+  statistics: unknown = null;
+  /** Normalized source and target coordinate reference system metadata. */
+  spatialReference: TilesetSpatialReference = createTilesetSpatialReference({});
 
   description = '';
   properties: any;
@@ -422,6 +453,13 @@ export class Tileset3D {
     this.memoryAdjustedScreenSpaceError = this.options.maximumScreenSpaceError;
     this._cacheBytes = cacheBytes;
     this._maximumCacheOverflowBytes = maximumCacheOverflowBytes;
+    const metadata = this._getSourceMetadata();
+    if (metadata) {
+      this.spatialReference = applyTilesetSpatialOptions(
+        metadata.spatialReference,
+        this.options.spatial
+      );
+    }
 
     this.stats = new Stats({id: this.url});
     this._initializeStats();
@@ -812,10 +850,13 @@ export class Tileset3D {
     for (const tile of this.selectedTiles) {
       if (tile.contentAvailable && tile.content) {
         tilesRenderable++;
-        if (tile.content.pointCount) {
-          pointsRenderable += tile.content.pointCount;
-        } else {
-          pointsRenderable += tile.content.vertexCount;
+        const contents = tile.contents.length ? tile.contents : [tile.content];
+        for (const content of contents) {
+          if (content.pointCount) {
+            pointsRenderable += content.pointCount;
+          } else {
+            pointsRenderable += content.vertexCount || 0;
+          }
         }
       }
     }
@@ -835,7 +876,8 @@ export class Tileset3D {
       }
       if (
         initialMetadata?.tileset?.root &&
-        typeof initialMetadata.tileset.root.then !== 'function'
+        typeof initialMetadata.tileset.root.then !== 'function' &&
+        !this.source.prepareTileset
       ) {
         this.root = this._initializeTileHeaders(initialMetadata.tileset, null);
         this._applyViewState();
@@ -844,6 +886,7 @@ export class Tileset3D {
       await initializePromise;
       const metadata = this.source.getMetadata();
       this._syncSourceState(metadata);
+      await this.source.prepareTileset?.(this);
       if (!this.root) {
         this.root = this._initializeTileHeaders(metadata.tileset, null);
       }
@@ -1049,6 +1092,20 @@ export class Tileset3D {
     this.refine = metadata.refine;
     this.contentFormats = this.source.contentFormats;
     this.asset = this.source.asset || this.asset;
+    const tileset = metadata.tileset as Record<string, any>;
+    this.schema = tileset.schema || null;
+    this.schemaUri = tileset.schemaUri || null;
+    this.groups = tileset.groups || [];
+    this.metadata = tileset.metadata || null;
+    this.statistics = tileset.statistics ?? null;
+    const spatialReference = applyTilesetSpatialOptions(
+      metadata.spatialReference,
+      this.options.spatial
+    );
+    this.spatialReference = preserveTransformedSpatialReference(
+      this.spatialReference,
+      spatialReference
+    );
     this.properties = this.source.properties ?? this.properties;
     this.extras = this.source.extras ?? this.extras;
     if (this.options.attributions?.length) {
@@ -1085,3 +1142,17 @@ export class Tileset3D {
     }
   }
 }
+
+/** Preserve a completed runtime operation when asynchronous source metadata describes the same request. */
+function preserveTransformedSpatialReference(
+  current: TilesetSpatialReference,
+  next: TilesetSpatialReference
+): TilesetSpatialReference {
+  return current?.status === 'transformed' &&
+    current.sourceCrs === next.sourceCrs &&
+    current.targetCrs === next.targetCrs &&
+    current.targetHeightReference === next.targetHeightReference &&
+    current.outputCoordinates === next.outputCoordinates
+    ? current
+    : next;
+}

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

@@ -9,6 +9,7 @@ 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';
+import type {TilesetSpatialReference} from '../../spatial/spatial-types';
 
 /**
  * Parsed top-level tileset payload consumed by {@link Tileset3D} or a {@link Tileset3DSource}.
@@ -69,8 +70,12 @@ export type TilesetSourceInput = TilesetJSON | TilesetSourceRequest;
 export type TileContentLoadResult = {
   /** Whether the tile content request produced usable content. */
   loaded: boolean;
+  /** All payloads loaded for a tile, in source order. */
+  contents?: any[];
   /** Nested tileset metadata to install below the loaded tile, if any. */
   nestedTileset?: TilesetJSON;
+  /** Nested tilesets found among multiple content payloads. */
+  nestedTilesets?: TilesetJSON[];
 };
 
 /** Result of a source-managed lazy child-header request. */
@@ -128,6 +133,8 @@ export type TilesetSourceMetadata = {
   lodMetricValue: number;
   /** Root refinement mode used as fallback by runtime tiles. */
   refine: string;
+  /** Format-discovered coordinate reference system metadata. */
+  spatialReference?: TilesetSpatialReference;
 };
 
 /**
@@ -167,6 +174,14 @@ export interface Tileset3DSource {
    */
   initialize(): Promise<void>;
 
+  /**
+   * Prepares option-dependent asynchronous source state before runtime headers are constructed.
+   *
+   * I3S uses this hook to sample elevation surfaces for its root bound after `Tileset3D` has
+   * applied spatial options. Sources without asynchronous header preparation omit the hook.
+   */
+  prepareTileset?(tileset: Tileset3D): Promise<void>;
+
   /** Releases source-local caches and prevents late asynchronous work from mutating runtime tiles. */
   destroy?(): void;
 

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

@@ -140,7 +140,9 @@ export class TilesetTraverser {
         // Always load tiles in the base traversal
         // Select tiles that can't refine further
         this.loadTile(tile, frameState);
-        if (stoppedRefining) {
+        // Skip-LOD keeps a ready ancestor selected while descendants stream in. This prevents
+        // replacement holes when traversal jumps over one or more hierarchy levels.
+        if (stoppedRefining || this.options.skipLevelOfDetail) {
           this.selectTile(tile, frameState);
         }
       }
@@ -228,7 +230,7 @@ export class TilesetTraverser {
 
   // tile to render in the browser
   selectTile(tile: Tile3D, frameState: FrameState): void {
-    if (this.shouldSelectTile(tile)) {
+    if (this.shouldSelectTile(tile, frameState)) {
       // The tile can be selected right away and does not require traverseAndSelect
       tile._selectedFrame = frameState.frameNumber;
       this.selectedTiles[tile.id] = tile;
@@ -292,10 +294,13 @@ export class TilesetTraverser {
     return tile.hasUnloadedContent || tile.contentExpired;
   }
 
-  shouldSelectTile(tile: Tile3D): boolean {
-    // if select tile is in current frame
-    // and content available
-    return tile.contentAvailable && !this.options.skipLevelOfDetail;
+  /**
+   * Returns whether a tile's content is available and visible for rendering.
+   * @param tile Tile considered for rendering.
+   * @param frameState Current culling state.
+   */
+  shouldSelectTile(tile: Tile3D, frameState: FrameState): boolean {
+    return tile.contentAvailable && tile.contentVisibility(frameState) !== 'outside';
   }
 
   /** Decide if tile LoD (level of detail) is not sufficient under current viewport */