refactor(deck.gl-raster)!: Finish generalizing tile traversal (#394)

* Move morecantile to peer dep

* Make RasterTileset2D fully generic

* update cog-layer

* fix tests

Author: kylebarron

packages/deck.gl-geotiff/src/cog-layer.ts

@@ -20,7 +20,8 @@ import type {
 } from "@developmentseed/deck.gl-raster";
 import {
   RasterLayer,
-  TileMatrixSetTileset,
+  RasterTileset2D,
+  TileMatrixSetAdaptor,
 } from "@developmentseed/deck.gl-raster";
 import type { DecoderPool, GeoTIFF, Overview } from "@developmentseed/geotiff";
 import {
@@ -532,12 +533,15 @@ export class COGLayer<
     geotiff: GeoTIFF,
   ): TileLayer {
     // Create a factory class that wraps COGTileset2D with the metadata
-    class TileMatrixSetTilesetFactory extends TileMatrixSetTileset {
+    class TileMatrixSetTilesetFactory extends RasterTileset2D {
       constructor(opts: Tileset2DProps) {
-        super(opts, tms, {
+        const descriptor = new TileMatrixSetAdaptor(tms, {
           projectTo4326: forwardTo4326,
           projectTo3857: forwardTo3857,
         });
+        super(opts, descriptor, {
+          projectTo4326: forwardTo4326,
+        });
       }
     }
 

packages/deck.gl-raster/package.json

@@ -52,6 +52,7 @@
     "vitest": "^4.0.18"
   },
   "peerDependencies": {
+    "@developmentseed/morecantile": "workspace:^",
     "@deck.gl/core": "^9.2.7",
     "@deck.gl/geo-layers": "^9.2.7",
     "@deck.gl/layers": "^9.2.7",
@@ -61,7 +62,6 @@
   },
   "dependencies": {
     "@developmentseed/affine": "workspace:^",
-    "@developmentseed/morecantile": "workspace:^",
     "@developmentseed/proj": "workspace:^",
     "@developmentseed/raster-reproject": "workspace:^",
     "@math.gl/core": "^4.1.0",

packages/deck.gl-raster/src/index.ts

@@ -2,8 +2,7 @@ export type { RasterModule } from "./gpu-modules/types.js";
 export type { RasterLayerProps, RenderTileResult } from "./raster-layer.js";
 export { RasterLayer } from "./raster-layer.js";
 export type { TileMetadata } from "./raster-tileset/index.js";
-export { TileMatrixSetTileset } from "./raster-tileset/index.js";
-
-import { __TEST_EXPORTS as traversalTestExports } from "./raster-tileset/raster-tile-traversal.js";
-
-export const __TEST_EXPORTS = { ...traversalTestExports };
+export {
+  RasterTileset2D,
+  TileMatrixSetAdaptor,
+} from "./raster-tileset/index.js";

packages/deck.gl-raster/src/raster-tileset/index.ts

@@ -1,2 +1,3 @@
 export type { TileMetadata } from "./raster-tileset-2d.js";
-export { TileMatrixSetTileset } from "./raster-tileset-2d.js";
+export { RasterTileset2D } from "./raster-tileset-2d.js";
+export { TileMatrixSetAdaptor } from "./tile-matrix-set.js";

packages/deck.gl-raster/src/raster-tileset/raster-tile-traversal.ts

@@ -767,10 +767,3 @@ function bilerpPoint(
     p00[1] * w00 + p10[1] * w10 + p01[1] * w01 + p11[1] * w11,
   ];
 }
-
-/**
- * Exports only for use in testing
- */
-export const __TEST_EXPORTS = {
-  RasterTileNode,
-};

packages/deck.gl-raster/src/raster-tileset/raster-tileset-2d.ts

@@ -1,5 +1,6 @@
 /**
- * TileMatrixSetTileset - Improved Implementation with Frustum Culling
+ * RasterTileset2D - Generic tile traversal over a tile pyramid with Frustum
+ * Culling
  *
  * This version properly implements frustum culling and bounding volume calculations
  * following the pattern from deck.gl's OSM tile indexing.
@@ -11,12 +12,10 @@ import type {
   _Tileset2DProps as Tileset2DProps,
 } from "@deck.gl/geo-layers";
 import { _Tileset2D as Tileset2D } from "@deck.gl/geo-layers";
-import type { TileMatrixSet } from "@developmentseed/morecantile";
 import { transformBounds } from "@developmentseed/proj";
 import type { Matrix4 } from "@math.gl/core";
 import { getTileIndices } from "./raster-tile-traversal";
 import type { TilesetDescriptor } from "./tileset-interface";
-import { TileMatrixSetAdaptor } from "./tms-interface";
 import type {
   Bounds,
   Corners,
@@ -49,15 +48,11 @@ export type TileMetadata = {
 
   /**
    * Tile width in pixels.
-   *
-   * Note this may differ between levels in some TileMatrixSets.
    */
   tileWidth: number;
 
   /**
    * Tile height in pixels.
-   *
-   * Note this may differ between levels in some TileMatrixSets.
    */
   tileHeight: number;
 };
@@ -69,41 +64,27 @@ export type TileMetadata = {
  *
  * Handles tile lifecycle, caching, and viewport-based loading.
  */
-export class TileMatrixSetTileset extends Tileset2D {
-  private tms: TileMatrixSet;
+export class RasterTileset2D extends Tileset2D {
+  private descriptor: TilesetDescriptor;
   private wgs84Bounds: Bounds;
   private projectTo4326: ProjectionFunction;
-  private tilesetDescriptor: TilesetDescriptor;
 
   constructor(
     opts: Tileset2DProps,
-    tms: TileMatrixSet,
+    descriptor: TilesetDescriptor,
     {
       projectTo4326,
-      projectTo3857,
     }: {
       projectTo4326: ProjectionFunction;
-      projectTo3857: ProjectionFunction;
     },
   ) {
     super(opts);
-    this.tms = tms;
+    this.descriptor = descriptor;
     this.projectTo4326 = projectTo4326;
 
-    if (!tms.boundingBox) {
-      throw new Error(
-        "Bounding Box inference not yet implemented; should be provided on TileMatrixSet",
-      );
-    }
-
-    this.tilesetDescriptor = new TileMatrixSetAdaptor(tms, {
-      projectTo3857,
-      projectTo4326,
-    });
-
     this.wgs84Bounds = transformBounds(
       projectTo4326,
-      ...this.tilesetDescriptor.projectedBounds,
+      ...this.descriptor.projectedBounds,
     );
   }
 
@@ -121,14 +102,14 @@ export class TileMatrixSetTileset extends Tileset2D {
     modelMatrix?: Matrix4;
     modelMatrixInverse?: Matrix4;
   }): TileIndex[] {
-    const maxAvailableZ = this.tms.tileMatrices.length - 1;
+    const maxAvailableZ = this.descriptor.levels.length - 1;
 
     const maxZ =
       typeof opts.maxZoom === "number"
         ? Math.min(opts.maxZoom, maxAvailableZ)
         : maxAvailableZ;
 
-    const tileIndices = getTileIndices(this.tilesetDescriptor, {
+    const tileIndices = getTileIndices(this.descriptor, {
       viewport: opts.viewport,
       maxZ,
       zRange: opts.zRange ?? null,
@@ -148,21 +129,22 @@ export class TileMatrixSetTileset extends Tileset2D {
       return index;
     }
 
-    const currentOverview = this.tms.tileMatrices[index.z]!;
-    const parentOverview = this.tms.tileMatrices[index.z - 1]!;
+    const currentOverview = this.descriptor.levels[index.z]!;
+    const parentOverview = this.descriptor.levels[index.z - 1]!;
 
     // Decimation is the number of child tiles that fit across one parent tile.
     // Must use tile footprint (cellSize × tileWidth/Height), not cellSize alone,
     // because tileWidth can change between levels (e.g. the last Sentinel-2
     // overview doubles tileWidth while halving cellSize, giving a 1:1 spatial
     // mapping where decimation = 1).
-    const parentFootprintX = parentOverview.cellSize * parentOverview.tileWidth;
+    const parentFootprintX =
+      parentOverview.metersPerPixel * parentOverview.tileWidth;
     const parentFootprintY =
-      parentOverview.cellSize * parentOverview.tileHeight;
+      parentOverview.metersPerPixel * parentOverview.tileHeight;
     const currentFootprintX =
-      currentOverview.cellSize * currentOverview.tileWidth;
+      currentOverview.metersPerPixel * currentOverview.tileWidth;
     const currentFootprintY =
-      currentOverview.cellSize * currentOverview.tileHeight;
+      currentOverview.metersPerPixel * currentOverview.tileHeight;
 
     const decimationX = parentFootprintX / currentFootprintX;
     const decimationY = parentFootprintY / currentFootprintY;
@@ -180,7 +162,7 @@ export class TileMatrixSetTileset extends Tileset2D {
 
   override getTileMetadata(index: TileIndex): TileMetadata {
     const { x, y, z } = index;
-    const levelDescriptor = this.tilesetDescriptor.levels[z]!;
+    const levelDescriptor = this.descriptor.levels[z]!;
     const { tileHeight, tileWidth } = levelDescriptor;
     const { topLeft, topRight, bottomLeft, bottomRight } =
       levelDescriptor.projectedTileCorners(x, y);

…ster/src/raster-tileset/tms-interface.ts …er/src/raster-tileset/tile-matrix-set.tspackages/deck.gl-raster/src/raster-tileset/tms-interface.ts renamed to packages/deck.gl-raster/src/raster-tileset/tile-matrix-set.ts packages/deck.gl-raster/src/raster-tileset/tms-interface.ts renamed to packages/deck.gl-raster/src/raster-tileset/tile-matrix-set.ts

@@ -123,6 +123,10 @@ class TileMatrixAdaptor implements TilesetLevel {
   }
 }
 
+/**
+ * An adapter interface to use a TileMatrixSet as a TilesetDescriptor for raster
+ * tile traversal.
+ */
 export class TileMatrixSetAdaptor implements TilesetDescriptor {
   tms: TileMatrixSet;
   private _levels: TileMatrixAdaptor[];

packages/deck.gl-raster/src/raster-tileset/types.ts

@@ -25,23 +25,10 @@ export type ProjectedBoundingBox = {
   bottom: number;
 };
 
-export type TileBoundingBox = ProjectedBoundingBox | GeoBoundingBox;
-
-export type TileLoadProps = {
-  index: TileIndex;
-  id: string;
-  bbox: TileBoundingBox;
-  url?: string | null;
-  signal?: AbortSignal;
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  userData?: Record<string, any>;
-  zoom?: number;
-};
-
+/** A 2D point represented as [x, y] */
 export type Point = [number, number];
 
-type CRS = any;
-
+/** A function that projects coordinates from one CRS to another */
 export type ProjectionFunction = (x: number, y: number) => Point;
 
 /**
@@ -52,13 +39,6 @@ export type CornerBounds = {
   upperRight: Point;
 };
 
-/**
- * Minimum bounding rectangle surrounding a 2D resource in the CRS indicated elsewhere
- */
-export type TileMatrixSetBoundingBox = CornerBounds & {
-  crs?: CRS;
-};
-
 /**
  * Raster Tile Index
  *

packages/deck.gl-raster/tests/tileset-refinement.test.ts

@@ -9,7 +9,8 @@ import type { Viewport } from "@deck.gl/core";
 import type { _Tileset2DProps as Tileset2DProps } from "@deck.gl/geo-layers";
 import type { TileMatrixSet } from "@developmentseed/morecantile";
 import { describe, expect, it } from "vitest";
-import { TileMatrixSetTileset } from "../src/raster-tileset/raster-tileset-2d.js";
+import { RasterTileset2D } from "../src/raster-tileset/raster-tileset-2d.js";
+import { TileMatrixSetAdaptor } from "../src/raster-tileset/tile-matrix-set.js";
 import type { TileIndex } from "../src/raster-tileset/types.js";
 
 // ---------------------------------------------------------------------------
@@ -62,15 +63,15 @@ const identity = (x: number, y: number): [number, number] => [x, y];
 // "visible" at each simulated zoom level without needing a real Viewport.
 // ---------------------------------------------------------------------------
 
-class ControlledTileset extends TileMatrixSetTileset {
+class ControlledTileset extends RasterTileset2D {
   private _forcedIndices: TileIndex[] = [];
 
   setForcedIndices(indices: TileIndex[]) {
     this._forcedIndices = indices;
   }
 
   override getTileIndices(
-    _opts: Parameters<TileMatrixSetTileset["getTileIndices"]>[0],
+    _opts: Parameters<RasterTileset2D["getTileIndices"]>[0],
   ): TileIndex[] {
     return this._forcedIndices;
   }
@@ -101,8 +102,11 @@ function makeTileset(opts?: Partial<Tileset2DProps>): ControlledTileset {
       getTileData: () => new Promise(() => {}), // never resolves
       ...opts,
     },
-    MOCK_TMS,
-    { projectTo4326: identity, projectTo3857: identity },
+    new TileMatrixSetAdaptor(MOCK_TMS, {
+      projectTo4326: identity,
+      projectTo3857: identity,
+    }),
+    { projectTo4326: identity },
   );
 }
 
@@ -274,8 +278,11 @@ describe("TileMatrixSetTileset – best-available refinement", () => {
 
     const tileset = new ControlledTileset(
       { getTileData: () => new Promise(() => {}) },
-      sentinel2TMS as any,
-      { projectTo4326: identity, projectTo3857: identity },
+      new TileMatrixSetAdaptor(sentinel2TMS, {
+        projectTo4326: identity,
+        projectTo3857: identity,
+      }),
+      { projectTo4326: identity },
     );
 
     // Every z=4 tile should map 1:1 to the z=3 tile at the same x,y.