@loaders.gl/tiles 5.0.0-alpha.10 → 5.0.0-alpha.11

package/src/spatial/spatial-coordinate-transformer.ts

@@ -6,8 +6,8 @@ import type {Geoid} from '@math.gl/geoid';
 import {Vector3} from '@math.gl/core';
 import {Ellipsoid} from '@math.gl/geospatial';
 import type {ReadonlyCRSDefinition} from '@math.gl/crs';
-import {Projection} from '@math.gl/projection';
-import {getGeoidModel} from './spatial-resource-registry';
+import type {Projection} from '@math.gl/projection';
+import {getGeoidModel, getSpatialProjectionEngine} from './spatial-resource-registry';
 import {
   normalizeCrsIdentifier,
   WGS84_GEOCENTRIC_CRS,
@@ -64,6 +64,7 @@ export class SpatialCoordinateTransformer {
    */
   constructor(spatialReference: TilesetSpatialReference, options: TilesetSpatialOptions = {}) {
     this.spatialReference = spatialReference;
+    const projectionEngine = getSpatialProjectionEngine();
     validateTransformRequest(spatialReference);
     const outputCrs = spatialReference.targetCrs || spatialReference.sourceCrs;
     this.sourceIsGeocentric = isWgs84Geocentric(spatialReference.sourceCrs);
@@ -77,7 +78,7 @@ export class SpatialCoordinateTransformer {
       !this.sourceIsGeocentric &&
       !this.outputIsGeocentric
     ) {
-      this.horizontalProjection = new Projection({
+      this.horizontalProjection = projectionEngine.createProjection({
         from: getHorizontalProjectionDefinition(spatialReference.sourceCrs),
         to: getHorizontalProjectionDefinition(spatialReference.targetCrs),
         enforceAxis: false
@@ -90,14 +91,14 @@ export class SpatialCoordinateTransformer {
       this.outputIsGeocentric
     ) {
       if (!this.sourceIsGeographic && !this.sourceIsGeocentric) {
-        this.geographicProjection = new Projection({
+        this.geographicProjection = projectionEngine.createProjection({
           from: getHorizontalProjectionDefinition(spatialReference.sourceCrs),
           to: WGS84_GEOGRAPHIC_CRS,
           enforceAxis: false
         });
       }
       if (!this.outputIsGeographic && !this.outputIsGeocentric) {
-        this.heightOutputProjection = new Projection({
+        this.heightOutputProjection = projectionEngine.createProjection({
           from: WGS84_GEOGRAPHIC_CRS,
           to: getHorizontalProjectionDefinition(outputCrs),
           enforceAxis: false
@@ -153,7 +154,7 @@ export class SpatialCoordinateTransformer {
     }
 
     if (this.horizontalProjection) {
-      const projected = this.horizontalProjection.project(result.slice(0, 3));
+      const projected = this.horizontalProjection.projectSync(result.slice(0, 3));
       result.splice(0, projected.length, ...projected);
     }
     return result;
@@ -220,7 +221,7 @@ export class SpatialCoordinateTransformer {
     if (this.sourceIsGeographic) {
       return coordinate.slice(0, 3);
     }
-    return this.geographicProjection!.project(coordinate.slice(0, 3));
+    return this.geographicProjection!.projectSync(coordinate.slice(0, 3));
   }
 
   /** Convert one conventional WGS84 geographic coordinate to the selected output CRS. */
@@ -231,7 +232,7 @@ export class SpatialCoordinateTransformer {
     if (this.outputIsGeographic) {
       return coordinate.slice(0, 3);
     }
-    return this.heightOutputProjection!.project(coordinate.slice(0, 3));
+    return this.heightOutputProjection!.projectSync(coordinate.slice(0, 3));
   }
 }
 

package/src/spatial/spatial-resource-registry.ts

@@ -3,10 +3,19 @@
 // Copyright (c) vis.gl contributors
 
 import {Geoid, parsePGM} from '@math.gl/geoid';
-import {Projection} from '@math.gl/projection';
+import {FullProjectionEngine, parseNTv2Grid} from '@math.gl/projection';
+import type {DatumGrid, ProjectionEngine} from '@math.gl/projection';
 import type {ReadonlyCRSDefinition} from '@math.gl/crs';
 
 const geoidModels = new Map<string, Geoid>();
+const projectionAliases: Record<string, ReadonlyCRSDefinition> = {};
+const datumGrids: Record<string, DatumGrid> = {};
+let spatialProjectionEngine: ProjectionEngine = new FullProjectionEngine();
+
+/** Returns the projection engine containing application-registered spatial resources. */
+export function getSpatialProjectionEngine(): ProjectionEngine {
+  return spatialProjectionEngine;
+}
 
 /**
  * Registers an application-supplied CRS alias for deterministic coordinate transformations.
@@ -18,7 +27,8 @@ const geoidModels = new Map<string, Geoid>();
  */
 export function registerSpatialCrs(name: string, definition: ReadonlyCRSDefinition): void {
   validateResourceName(name, 'CRS');
-  Projection.defineProjectionAliases({[name]: definition});
+  projectionAliases[name] = definition;
+  spatialProjectionEngine = new FullProjectionEngine({aliases: projectionAliases, datumGrids});
 }
 
 /**
@@ -29,7 +39,8 @@ export function registerSpatialCrs(name: string, definition: ReadonlyCRSDefiniti
  */
 export function registerSpatialDatumGrid(name: string, data: ArrayBuffer): void {
   validateResourceName(name, 'datum grid');
-  Projection.registerDatumGrid(name, data);
+  datumGrids[name] = parseNTv2Grid(data);
+  spatialProjectionEngine = new FullProjectionEngine({aliases: projectionAliases, datumGrids});
 }
 
 /**

package/src/spatial/tiles-3d-spatial-transformer.ts

@@ -3,9 +3,7 @@
 // Copyright (c) vis.gl contributors
 
 import {SpatialCoordinateTransformer} from './spatial-coordinate-transformer';
-import {getSpatialCoordinateFrame} from './get-spatial-coordinate-frame';
 import {Matrix4} from '@math.gl/core';
-import {Ellipsoid} from '@math.gl/geospatial';
 import type {TilesetSpatialOptions, TilesetSpatialReference} from './spatial-types';
 
 /** Structural 3D Tiles volume shape used by the source adapter. */
@@ -80,16 +78,6 @@ export class Tiles3DSpatialTransformer {
 
   /** Transforms one WGS84 region sample into the selected output frame. */
   private transformRegionSample(sample: number[]): number[] {
-    const [longitudeDegrees, latitudeDegrees, height] = sample;
-    const targetCrs = this.spatialReference.targetCrs || this.spatialReference.sourceCrs;
-    if (targetCrs && getSpatialCoordinateFrame(targetCrs) === 'geocentric') {
-      const cartesian = Ellipsoid.WGS84.cartographicToCartesian([
-        longitudeDegrees,
-        latitudeDegrees,
-        height
-      ]);
-      return Array.from(cartesian);
-    }
     return this.geographicCoordinateTransformer.transformPosition(sample);
   }
 }

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

@@ -73,7 +73,7 @@ export type Tileset3DProps = {
   /**
    * 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
+   * Defaults to `true` for 3D Tiles and `false` for I3S. Set to `false` to request every level.
    */
   skipLevelOfDetail?: boolean;
   /**
@@ -393,7 +393,8 @@ export class Tileset3D {
   _cache = new TilesetCache();
   _requestScheduler: RequestScheduler;
 
-  private _heldTiles: Set<string> = new Set();
+  /** Drawn fallback instances retained independently for each viewport tree. */
+  private _heldTiles: Set<Tile3D> = new Set();
   private updatePromise: Promise<number> | null = null;
   tilesetInitializationPromise: Promise<void>;
 
@@ -425,6 +426,7 @@ export class Tileset3D {
       ...suppliedOptions,
       cacheBytes,
       maximumCacheOverflowBytes,
+      skipLevelOfDetail: suppliedOptions.skipLevelOfDetail ?? source.type === TILESET_TYPE.TILES3D,
       memoryAdjustedScreenSpaceError:
         suppliedOptions.memoryAdjustedScreenSpaceError ?? usesTiles3DCacheDefaults
     };
@@ -782,28 +784,50 @@ export class Tileset3D {
 
     this.selectedTiles = this.options.onTraversalComplete(this.selectedTiles);
 
-    const selectedIds = new Set(this.selectedTiles.map(tile => tile.id));
+    const selectedTiles = new Set(this.selectedTiles);
     const hasUndrawnTiles = this.selectedTiles.some(tile => !tile.tileDrawn);
 
     let heldBackCount = 0;
     if (hasUndrawnTiles) {
-      for (const tileId of selectedIds) {
-        this._heldTiles.add(tileId);
+      const activeRoots = new Set(
+        Object.keys(this.frameStateData).map(viewportId => this.roots[viewportId])
+      );
+      const descendantReadiness = new Map<Tile3D, boolean>();
+      for (const tile of this.selectedTiles) {
+        for (let ancestor = tile.parent; ancestor; ancestor = ancestor.parent) {
+          descendantReadiness.set(
+            ancestor,
+            (descendantReadiness.get(ancestor) ?? true) && tile.tileDrawn
+          );
+        }
       }
-      for (const tileId of this._heldTiles) {
-        if (selectedIds.has(tileId)) continue;
-
-        const tile = this._tiles[tileId];
-        if (tile && tile.contentAvailable) {
+      // Drawing can finish between traversals. Promote only previously selected
+      // geometry that actually drew; pending tiles cannot provide visible fallback.
+      for (const tile of previousSelectedTiles) {
+        if (tile.tileDrawn) this._heldTiles.add(tile);
+      }
+      for (const tile of this._heldTiles) {
+        let root = tile;
+        while (root.parent) root = root.parent;
+        // Removed viewport trees cannot contribute fallback to the remaining views.
+        if (!activeRoots.has(root)) {
+          this._heldTiles.delete(tile);
+          continue;
+        }
+        if (selectedTiles.has(tile)) continue;
+        if (
+          tile.contentAvailable &&
+          !this._hasDrawnReplacement(tile, selectedTiles, descendantReadiness)
+        ) {
           tile._selectedFrame = this._frameNumber;
           this.selectedTiles.push(tile);
           heldBackCount++;
         } else {
-          this._heldTiles.delete(tileId);
+          this._heldTiles.delete(tile);
         }
       }
     } else {
-      this._heldTiles = selectedIds;
+      this._heldTiles = selectedTiles;
     }
 
     if (heldBackCount > 0) {
@@ -825,6 +849,24 @@ export class Tileset3D {
     }
   }
 
+  /**
+   * Releases fallback geometry once its own selected replacement has drawn.
+   * Unrelated pending branches must not delay this region's handoff. When no related
+   * replacement is selected, retain the fallback until the complete selection has drawn.
+   */
+  private _hasDrawnReplacement(
+    tile: Tile3D,
+    selectedTiles: Set<Tile3D>,
+    descendantReadiness: Map<Tile3D, boolean>
+  ): boolean {
+    for (let ancestor = tile.parent; ancestor; ancestor = ancestor.parent) {
+      if (selectedTiles.has(ancestor)) {
+        return ancestor.tileDrawn;
+      }
+    }
+    return descendantReadiness.get(tile) === true;
+  }
+
   _tilesChanged(oldSelectedTiles: Tile3D[], selectedTiles: Tile3D[]): boolean {
     if (oldSelectedTiles.length !== selectedTiles.length) {
       return true;

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

@@ -236,11 +236,9 @@ export class TilesetTraverser {
         } else {
           childRefines = child.contentAvailable;
         }
+        // Readiness controls replacement, not discovery. Visit every sibling so
+        // one unavailable child cannot serialize requests or hide ready siblings.
         refines = refines && childRefines;
-
-        if (!refines) {
-          return false;
-        }
       }
     }
 

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

@@ -70,7 +70,9 @@ export class Tileset3DTraverser extends TilesetTraverser {
       if (!tile.hasRenderContent) {
         this.emptyTiles[tile.id] = tile;
         this.loadTile(tile, frameState);
-        if (stoppedRefining) {
+        // A known empty terminal branch needs no fallback geometry. Lazy child groups still
+        // report hasChildren while unresolved, so they retain coverage until materialized.
+        if (stoppedRefining && (!tile.hasEmptyContent || tile.hasChildren)) {
           this.selectDesiredTile(tile, frameState);
         }
       } else if (tile.refine === TILE_REFINEMENT.ADD) {
@@ -121,7 +123,7 @@ export class Tileset3DTraverser extends TilesetTraverser {
       if (child.isVisibleAndInRequestVolume) {
         stack.push(child);
         hasVisibleChild = true;
-      } else if (this.options.loadSiblings) {
+      } else if (this.options.loadSiblings && child._inRequestVolume) {
         this.loadTile(child, frameState);
         this.touchTile(child, frameState);
       }
@@ -234,6 +236,11 @@ export class Tileset3DTraverser extends TilesetTraverser {
     while (fallbackTile) {
       if (this.shouldSelectTile(fallbackTile, frameState)) {
         this.selectTile(fallbackTile, frameState);
+        if (fallbackTile !== tile) {
+          // On zoom-out the desired coarse level may still be unavailable. Preserve
+          // nearby detail that already drew while the ancestor fills uncovered pixels.
+          this.selectLoadedDescendants(tile, frameState, true);
+        }
         return;
       }
       fallbackTile = fallbackTile.parent;
@@ -246,8 +253,13 @@ export class Tileset3DTraverser extends TilesetTraverser {
    *
    * @param root - Unavailable tile whose descendants are searched.
    * @param frameState - Current culling state.
+   * @param drawnOnly - Reuse drawn detail without starting obsolete GPU work.
    */
-  private selectLoadedDescendants(root: Tile3D, frameState: FrameState): void {
+  private selectLoadedDescendants(
+    root: Tile3D,
+    frameState: FrameState,
+    drawnOnly: boolean = false
+  ): void {
     const stack: Array<{tile: Tile3D; depth: number}> = [{tile: root, depth: 0}];
     while (stack.length > 0) {
       const {tile, depth} = stack.pop() as {tile: Tile3D; depth: number};
@@ -256,7 +268,7 @@ export class Tileset3DTraverser extends TilesetTraverser {
         if (!child.isVisibleAndInRequestVolume) {
           continue;
         }
-        if (child.contentAvailable) {
+        if (this.shouldSelectTile(child, frameState) && (!drawnOnly || child.tileDrawn)) {
           this.selectTile(child, frameState);
           this.touchTile(child, frameState);
         } else if (depth < 1) {