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

package/src/pmtiles/raster.ts

@@ -0,0 +1,289 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {ImageWriter} from '@loaders.gl/images';
+import {
+  rasterCoordinateToPixel,
+  sampleRaster,
+  waitForPromiseWithSignal
+} from '@loaders.gl/core/loader-utils';
+import type {
+  NumericRasterData,
+  RasterBoundingBox,
+  RasterRegionSource
+} from '@loaders.gl/core/loader-utils';
+import {encodePMTiles} from './lib/encode-pmtiles';
+import type {PMTilesEncodeOptions, PMTilesTile} from './pmtiles-writer-types';
+
+/** Existing numeric region source; the exporter never takes ownership or finalizes it. */
+export type RasterPMTilesSource = Pick<RasterRegionSource, 'getMetadata' | 'getRasterForRegion'>;
+
+/** Bounded selected-tile PNG authoring from an existing georeferenced raster source. */
+export type RasterPMTilesOptions = {
+  /** Finite canonical XYZ selection; empty requests count against maxTiles. */
+  readonly tiles:
+    | Iterable<Pick<PMTilesTile, 'z' | 'x' | 'y'>>
+    | AsyncIterable<Pick<PMTilesTile, 'z' | 'x' | 'y'>>;
+  /** Square output tile width and height; default 256, maximum 1024. */
+  readonly tileSize?: number;
+  /** Source band indices in gray, gray/alpha, RGB or RGBA order; default all bands. */
+  readonly bands?: readonly number[];
+  /** Nonspatial source dimension selection, forwarded to region requests. */
+  readonly selection?: Readonly<Record<string, number>>;
+  /** Maximum returned region pixels, default 1,048,576. Also forwarded to the source. */
+  readonly maxSourcePixels?: number;
+  /** Budget for returned sample/mask buffers plus RGBA pixels, default 32 MiB. Forwarded to the source. */
+  readonly maxDecodedBytes?: number;
+  /** Archive budgets, cancellation, bounds, center and auxiliary metadata. */
+  readonly pmtiles?: Omit<PMTilesEncodeOptions, 'tileType' | 'tileCompression'>;
+};
+
+/** Web Mercator half-world extent in meters (EPSG:3857). */
+const HALF_WORLD = Math.PI * 6378137;
+
+/**
+ * Requests selected regions, samples byte-valued imagery into Web Mercator PNG tiles, and packages PMTiles v3.
+ * Longitude/latitude inputs are sampled at Mercator pixel centers; other CRSs require prior reprojection.
+ * Sampling uses raw bytes, validity masks and nodata. No styling or physical-value scaling is inferred.
+ * PNG encoding uses ImageWriter (browser canvas, or the application's installed Node image polyfill).
+ * Input region decoding, PNG encoding and archive allocation retain their own temporary allocations.
+ */
+export async function encodeRasterPMTiles(
+  source: RasterPMTilesSource,
+  options: RasterPMTilesOptions
+): Promise<ArrayBuffer> {
+  const configuration = {
+    ...options,
+    bands: options.bands?.slice(),
+    selection: options.selection ? {...options.selection} : undefined,
+    pmtiles: {...options.pmtiles}
+  };
+  const signal = configuration.pmtiles.signal;
+  signal?.throwIfAborted();
+  const tileSize = configuration.tileSize ?? 256;
+  const maxSourcePixels = configuration.maxSourcePixels ?? 1024 * 1024;
+  const maxDecodedBytes = configuration.maxDecodedBytes ?? 32 * 1024 * 1024;
+  const maxTiles = configuration.pmtiles.maxTiles ?? 100000;
+  if (
+    !Number.isSafeInteger(tileSize) ||
+    tileSize < 1 ||
+    tileSize > 1024 ||
+    !Number.isSafeInteger(maxSourcePixels) ||
+    maxSourcePixels < tileSize * tileSize ||
+    !Number.isSafeInteger(maxDecodedBytes) ||
+    maxDecodedBytes < tileSize * tileSize * 4 ||
+    !Number.isSafeInteger(maxTiles) ||
+    maxTiles < 1
+  )
+    throw new Error('Invalid raster PMTiles size or budget');
+  const metadata = await waitForPromiseWithSignal(source.getMetadata({signal}), signal);
+  signal?.throwIfAborted();
+  const sourceCRS = metadata.crs;
+  if (sourceCRS !== 'EPSG:3857' && sourceCRS !== 'EPSG:4326' && sourceCRS !== 'OGC:CRS84')
+    throw new Error('Raster PMTiles requires EPSG:3857, EPSG:4326 or OGC:CRS84');
+  const crs = sourceCRS;
+  if (!Number.isSafeInteger(metadata.bandCount) || metadata.bandCount < 1)
+    throw new Error('Invalid raster source band count');
+  const bands =
+    configuration.bands ??
+    Array.from({length: Math.min(metadata.bandCount, 5)}, (_, index) => index);
+  if (
+    ![1, 2, 3, 4].includes(bands.length) ||
+    new Set(bands).size !== bands.length ||
+    bands.some(band => !Number.isSafeInteger(band) || band < 0 || band >= metadata.bandCount)
+  )
+    throw new Error('Select one through four distinct raster bands');
+  const sampleOptions = {bands: bands.map((_band, index) => index)};
+  const archiveMetadata = {...configuration.pmtiles.metadata};
+  for (const name of [
+    'vector_layers',
+    'bounds',
+    'minzoom',
+    'maxzoom',
+    'center',
+    'tiles',
+    'tilestats'
+  ])
+    delete archiveMetadata[name];
+  return encodePMTiles(encodeTiles(), {
+    ...configuration.pmtiles,
+    metadata: archiveMetadata,
+    tileType: 'png',
+    tileCompression: 'none'
+  });
+
+  /** Acquires one bounded region at a time and closes selection iterators on failure/abort. */
+  async function* encodeTiles(): AsyncIterable<PMTilesTile> {
+    const seen = new Set<string>();
+    let requested = 0;
+    for await (const address of configuration.tiles) {
+      signal?.throwIfAborted();
+      const tile = {...address};
+      if (++requested > maxTiles) throw new Error('Raster PMTiles requested tile limit exceeded');
+      if (
+        !Number.isInteger(tile.z) ||
+        tile.z < 0 ||
+        tile.z > 26 ||
+        !Number.isInteger(tile.x) ||
+        !Number.isInteger(tile.y) ||
+        tile.x < 0 ||
+        tile.y < 0 ||
+        tile.x >= 2 ** tile.z ||
+        tile.y >= 2 ** tile.z
+      )
+        throw new Error('Invalid raster PMTiles selected XYZ address');
+      const key = `${tile.z}/${tile.x}/${tile.y}`;
+      if (seen.has(key)) throw new Error('Duplicate raster PMTiles selected XYZ address');
+      seen.add(key);
+      const scale = 2 ** tile.z;
+      const west = tile.x / scale;
+      const east = (tile.x + 1) / scale;
+      const north = tile.y / scale;
+      const south = (tile.y + 1) / scale;
+      const bounds: RasterBoundingBox =
+        crs === 'EPSG:3857'
+          ? [
+              [(2 * west - 1) * HALF_WORLD, (1 - 2 * south) * HALF_WORLD],
+              [(2 * east - 1) * HALF_WORLD, (1 - 2 * north) * HALF_WORLD]
+            ]
+          : [
+              [360 * west - 180, getLatitude(south)],
+              [360 * east - 180, getLatitude(north)]
+            ];
+      const raster = await waitForPromiseWithSignal(
+        source.getRasterForRegion({
+          bounds,
+          crs,
+          width: tileSize,
+          height: tileSize,
+          bands: bands.slice(),
+          selection: configuration.selection,
+          interleaved: false,
+          resampleMethod: 'nearest',
+          maxPixels: maxSourcePixels,
+          maxDecodedBytes,
+          signal
+        }),
+        signal
+      );
+      signal?.throwIfAborted();
+      validateRaster(raster, bands.length, tileSize, maxSourcePixels, maxDecodedBytes);
+      const pixels = new Uint8Array(tileSize * tileSize * 4);
+      let visible = false;
+      const firstX = bounds[0][0] + (bounds[1][0] - bounds[0][0]) / (2 * tileSize);
+      const lastX = bounds[1][0] - (bounds[1][0] - bounds[0][0]) / (2 * tileSize);
+      for (let row = 0; row < tileSize; row++) {
+        if (row % 32 === 0) {
+          signal?.throwIfAborted();
+          if (row) await new Promise<void>(resolve => setTimeout(resolve, 0));
+          signal?.throwIfAborted();
+        }
+        const normalizedY = north + (row + 0.5) / (tileSize * scale);
+        const sourceY =
+          crs === 'EPSG:3857' ? (1 - 2 * normalizedY) * HALF_WORLD : getLatitude(normalizedY);
+        const firstPixel = rasterCoordinateToPixel(raster, [firstX, sourceY], crs);
+        const lastPixel = rasterCoordinateToPixel(raster, [lastX, sourceY], crs);
+        for (let column = 0; column < tileSize; column++) {
+          const fraction = tileSize === 1 ? 0 : column / (tileSize - 1);
+          const sample = sampleRaster(
+            raster,
+            [
+              firstPixel[0] + (lastPixel[0] - firstPixel[0]) * fraction,
+              firstPixel[1] + (lastPixel[1] - firstPixel[1]) * fraction
+            ],
+            sampleOptions
+          );
+          if (!sample.valid.every(Boolean)) continue;
+          const values = sample.values as number[];
+          const offset = (row * tileSize + column) * 4;
+          const grayscale = values.length < 3;
+          pixels[offset] = values[0];
+          pixels[offset + 1] = grayscale ? values[0] : values[1];
+          pixels[offset + 2] = grayscale ? values[0] : values[2];
+          pixels[offset + 3] =
+            values.length === 2 ? values[1] : values.length === 4 ? values[3] : 255;
+          visible ||= pixels[offset + 3] > 0;
+        }
+      }
+      if (!visible) continue;
+      const data = await waitForPromiseWithSignal(
+        ImageWriter.encode(
+          {data: pixels, width: tileSize, height: tileSize},
+          {image: {mimeType: 'image/png'}}
+        ),
+        signal
+      );
+      signal?.throwIfAborted();
+      yield {...tile, data};
+    }
+  }
+}
+
+/** Converts north-origin normalized Web Mercator Y to latitude in degrees. */
+function getLatitude(normalizedY: number): number {
+  return (Math.atan(Math.sinh(Math.PI * (1 - 2 * normalizedY))) * 180) / Math.PI;
+}
+
+/** Rejects unsupported imagery and bounds returned buffers before allocating RGBA output. */
+function validateRaster(
+  raster: NumericRasterData,
+  bandCount: number,
+  tileSize: number,
+  maxPixels: number,
+  maxBytes: number
+): void {
+  const pixels = raster.width * raster.height;
+  if (
+    !Number.isSafeInteger(raster.width) ||
+    raster.width < 1 ||
+    !Number.isSafeInteger(raster.height) ||
+    raster.height < 1 ||
+    !Number.isSafeInteger(pixels) ||
+    pixels > maxPixels ||
+    raster.bandCount !== bandCount ||
+    raster.dtype !== 'uint8' ||
+    (raster.bands && raster.bands.length !== bandCount) ||
+    raster.bands?.some(
+      band => band.dtype !== 'uint8' || (band.scale ?? 1) !== 1 || (band.offset ?? 0) !== 0
+    )
+  )
+    throw new Error(
+      'Raster PMTiles requires bounded raw uint8 imagery with matching selected bands'
+    );
+  const buffers = Array.isArray(raster.data) ? raster.data : [raster.data];
+  const expectedLength = Array.isArray(raster.data) ? pixels : pixels * bandCount;
+  if (
+    (Array.isArray(raster.data) && buffers.length !== bandCount) ||
+    buffers.some(
+      buffer =>
+        (!(buffer instanceof Uint8Array) && !(buffer instanceof Uint8ClampedArray)) ||
+        buffer.length !== expectedLength
+    )
+  )
+    throw new Error('Invalid raster PMTiles sample buffers');
+  for (const mask of raster.validityMasks ?? []) {
+    const offset = mask.offset ?? 0;
+    const pixelStride = mask.pixelStride ?? 1;
+    const rowStride = mask.rowStride ?? mask.width;
+    if (
+      !(mask.data instanceof Uint8Array) ||
+      mask.width !== raster.width ||
+      mask.height !== raster.height ||
+      !Number.isSafeInteger(offset) ||
+      offset < 0 ||
+      !Number.isSafeInteger(pixelStride) ||
+      pixelStride < 1 ||
+      !Number.isSafeInteger(rowStride) ||
+      rowStride < 1 ||
+      offset + (mask.height - 1) * rowStride + (mask.width - 1) * pixelStride >= mask.data.length ||
+      (mask.band !== undefined &&
+        (!Number.isInteger(mask.band) || mask.band < 0 || mask.band >= bandCount))
+    )
+      throw new Error('Invalid raster PMTiles validity mask');
+  }
+  const bytes =
+    buffers.reduce((total, buffer) => total + buffer.byteLength, tileSize * tileSize * 4) +
+    (raster.validityMasks ?? []).reduce((total, mask) => total + mask.data.byteLength, 0);
+  if (bytes > maxBytes) throw new Error('Raster PMTiles decoded-byte budget exceeded');
+}

package/src/pmtiles/source-info.ts

@@ -0,0 +1,25 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {Schema} from '@loaders.gl/core/schema';
+
+export type SourceInfo = VectorSourceInfo | ImageSourceInfo;
+
+/** Information about a vector source */
+export type VectorSourceInfo = {
+  shape: 'vector-source';
+  /** List of geospatial tables */
+  layers: {name: string; schema: Schema}[];
+  /** List of nongeospatial tables */
+  tables: {name: string; schema: Schema}[];
+  /** Format specific metadata */
+  formatSpecificMetadata?: Record<string, any>;
+};
+
+/** Information about an image source */
+export type ImageSourceInfo = {
+  shape: 'image-source';
+  /** Format specific metadata */
+  formatSpecificMetadata?: Record<string, any>;
+};

package/src/pmtiles/unbundled.ts

@@ -0,0 +1,6 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+export type {PMTilesLoaderOptions} from './pmtiles-loader';
+export {PMTilesLoader as _PMTilesLoader} from './pmtiles-loader';

package/src/raster-set.ts

@@ -8,8 +8,8 @@ import type {
   RasterData,
   RasterSource,
   RasterSourceMetadata
-} from '@loaders.gl/loader-utils';
-import {waitForPromiseWithSignals} from '@loaders.gl/loader-utils';
+} from '@loaders.gl/core/loader-utils';
+import {waitForPromiseWithSignals} from '@loaders.gl/core/loader-utils';
 
 /** Accepted raster request currently retained by {@link RasterSet}. */
 export type RasterSetRequest<

package/src/tile-matrix.ts

@@ -0,0 +1,138 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {
+  getTileBounds,
+  getTileRange,
+  isTileIndexInRange,
+  selectTileMatrix
+} from '@math.gl/geospatial/tile-matrix';
+import type {
+  TileMatrix,
+  TileMatrixBounds,
+  TileMatrixLimits,
+  TileMatrixSet
+} from '@math.gl/geospatial/tile-matrix';
+import type {NonGeoBoundingBox, TileIndex} from './tileset-2d/types';
+import type {GetTileDataParameters} from '@loaders.gl/core/loader-utils';
+
+/** Renderer-independent view frame, already expressed in the grid's canonical X/Y coordinates. */
+export type TileMatrixViewFrame = {
+  /** Exact grid CRS identifier; no identifier equivalence or reprojection is inferred. */
+  crs: string;
+  /** Ordered finite [minimumX, minimumY, maximumX, maximumY] extent in grid coordinates. */
+  extent: TileMatrixBounds;
+  /** Positive coordinate units per pixel; both axes must meet this target. */
+  resolution: number;
+};
+
+/** The geometry and coverage subset of TileGrid needed for selection. */
+export type TileMatrixSelectionGrid = {
+  /** Complete native geometry; absence is rejected rather than inferred from partial fields. */
+  tileMatrixSet?: TileMatrixSet;
+  /** Optional inclusive per-matrix coverage; an empty list means no available tiles. */
+  limits?: readonly (TileMatrixLimits & {
+    /** Native matrix identifier addressed by this coverage rectangle. */
+    tileMatrix: string;
+  })[];
+};
+
+/** A native tile request; its Cartesian bbox stays in crs, including for geographic grids. */
+export type TileMatrixTile = {
+  /** Native column/row and compatibility z equal to the selected matrix's array position. */
+  index: TileIndex;
+  /** Stable source/grid-scoped identifier, independent of numeric z or matrix ordering. */
+  id: string;
+  /** Required native matrix identifier; numeric index.z is not a substitute. */
+  tileMatrix: string;
+  /** Cartesian native-coordinate bounds, with no automatic geographic reinterpretation. */
+  bbox: NonGeoBoundingBox;
+  /** Native CRS of bbox; this is not necessarily a longitude/latitude bounding box. */
+  crs: string;
+  /** The selected level's logical width and height in pixels. */
+  tileSize: readonly [number, number];
+};
+
+/** Resource budget for an eager fixed-frame selection. */
+export type TileMatrixSelectionOptions = {
+  /** Maximum tiles returned, default 4096. Oversized selections throw before allocation. */
+  maximumTileCount?: number;
+};
+
+/**
+ * Selects regular-grid tiles for an explicit native-CRS frame, with source coverage applied.
+ * Uses math.gl's coarsest level meeting the target, or its finest available fallback. z is the
+ * matrix's array index for compatibility; tileMatrix is authoritative. Cache ids encode the CRS,
+ * native matrix id and column/row, and are scoped to this source/grid, not globally unique.
+ * Returns an empty array outside the grid or available coverage. Partial geometry, coalesced
+ * rows, mismatched CRS identifiers and invalid coverage reject rather than approximating XYZ.
+ * This does not infer parents, transform a viewport, reproject content or configure a renderer.
+ */
+export function selectTileMatrixTiles(
+  grid: TileMatrixSelectionGrid,
+  frame: TileMatrixViewFrame,
+  options: TileMatrixSelectionOptions = {}
+): TileMatrixTile[] {
+  const matrixSet = grid.tileMatrixSet;
+  if (!matrixSet || !matrixSet.crs || frame.crs !== matrixSet.crs) {
+    throw new Error('Tile selection requires complete geometry and a frame in the exact grid CRS.');
+  }
+  if (
+    frame.extent.length !== 4 ||
+    !frame.extent.every(Number.isFinite) ||
+    frame.extent[0] > frame.extent[2] ||
+    frame.extent[1] > frame.extent[3]
+  ) {
+    throw new RangeError('Tile frame extent must be finite and ordered.');
+  }
+  const maximumTileCount = options.maximumTileCount ?? 4096;
+  if (!Number.isSafeInteger(maximumTileCount) || maximumTileCount < 0) {
+    throw new RangeError('maximumTileCount must be a nonnegative safe integer.');
+  }
+  for (const matrix of matrixSet.matrices) {
+    // Newer math.gl models can describe coalescence; this selector deliberately accepts regular grids only.
+    const coalescenceBands = (matrix as TileMatrix & {variableMatrixWidths?: readonly unknown[]})
+      .variableMatrixWidths;
+    if (
+      coalescenceBands !== undefined &&
+      (!Array.isArray(coalescenceBands) || coalescenceBands.length > 0)
+    ) {
+      throw new Error('Regular-grid selection does not support variable-width rows.');
+    }
+  }
+  const selectedMatrix = selectTileMatrix(matrixSet, frame.resolution);
+  const coverage = new Map<string, NonNullable<TileMatrixSelectionGrid['limits']>[number]>();
+  for (const limit of grid.limits ?? []) {
+    const matrix = matrixSet.matrices.find(candidate => candidate.id === limit.tileMatrix);
+    if (!matrix || coverage.has(limit.tileMatrix)) {
+      throw new RangeError('Tile coverage must reference unique, known matrix ids.');
+    }
+    // math.gl validates every endpoint of the inclusive rectangle, not just these two indices.
+    isTileIndexInRange(matrix, limit.minTileColumn, limit.minTileRow, limit);
+    coverage.set(limit.tileMatrix, limit);
+  }
+  if (!selectedMatrix || (grid.limits !== undefined && !coverage.has(selectedMatrix.id))) return [];
+  const range = getTileRange(selectedMatrix, frame.extent, coverage.get(selectedMatrix.id));
+  if (!range) return [];
+  const width = range.maxTileColumn - range.minTileColumn + 1;
+  const height = range.maxTileRow - range.minTileRow + 1;
+  if (width > maximumTileCount / height)
+    throw new RangeError('Tile selection exceeds maximumTileCount.');
+  const matrixIndex = matrixSet.matrices.indexOf(selectedMatrix);
+  const tiles: TileMatrixTile[] = [];
+  for (let row = range.minTileRow; row <= range.maxTileRow; row++) {
+    for (let column = range.minTileColumn; column <= range.maxTileColumn; column++) {
+      const [left, bottom, right, top] = getTileBounds(selectedMatrix, column, row);
+      tiles.push({
+        index: {x: column, y: row, z: matrixIndex},
+        tileMatrix: selectedMatrix.id,
+        id: JSON.stringify([matrixSet.crs, selectedMatrix.id, column, row]),
+        bbox: {left, bottom, right, top},
+        crs: matrixSet.crs,
+        tileSize: [selectedMatrix.tileSize[0], selectedMatrix.tileSize[1]]
+      } satisfies TileMatrixTile & GetTileDataParameters);
+    }
+  }
+  return tiles;
+}

package/src/tileset-2d/tile-2d-header.ts

@@ -3,7 +3,7 @@
 // Copyright (c) vis.gl contributors
 
 /* eslint-env browser */
-import {RequestScheduler} from '@loaders.gl/loader-utils';
+import {RequestScheduler} from '@loaders.gl/core/loader-utils';
 import type {TileBoundingBox, TileIndex, TileLoadProps} from './types';
 
 /** Parameters used by {@link SharedTile2DHeader.loadData}. */
@@ -129,8 +129,9 @@ export class SharedTile2DHeader<DataT = any> {
     onLoad,
     onError
   }: Tile2DLoadDataProps<DataT>): Promise<void> {
+    /** Publishes only the current, uncanceled request's content or error. */
     const completeLoad = (tileData: DataT | null, error: unknown, loaderId: number): void => {
-      if (loaderId !== this._loaderId) {
+      if (loaderId !== this._loaderId || this._isCancelled) {
         return;
       }
 
@@ -138,11 +139,6 @@ export class SharedTile2DHeader<DataT = any> {
       this.content = tileData;
       this.error = error ? normalizeTileError(error) : null;
 
-      if (this._isCancelled && !tileData) {
-        this._isLoaded = false;
-        return;
-      }
-
       this._isLoaded = true;
       this._isCancelled = false;
 
@@ -158,14 +154,17 @@ export class SharedTile2DHeader<DataT = any> {
 
     this._abortController = new AbortController();
     const {signal} = this._abortController;
-    const requestToken = await requestScheduler.scheduleRequest(this, () => 1);
+    // Reloads must not reuse the scheduler token of an aborted request for this tile.
+    const requestToken = await requestScheduler.scheduleRequest({tile: this, loaderId}, () =>
+      loaderId === this._loaderId && !this._isCancelled ? 1 : -1
+    );
 
-    if (!requestToken) {
-      this._isCancelled = true;
+    if (this._isCancelled || loaderId !== this._loaderId) {
+      requestToken?.done();
       return;
     }
-    if (this._isCancelled) {
-      requestToken.done();
+    if (!requestToken) {
+      this._isCancelled = true;
       return;
     }
 
@@ -202,12 +201,14 @@ export class SharedTile2DHeader<DataT = any> {
     this._needsReload = true;
   }
 
-  /** Cancels an in-flight tile request. */
+  /** Cancels a request and invalidates its result even if the loader ignores the abort signal. */
   abort(): void {
     if (this.isLoaded) {
       return;
     }
     this._isCancelled = true;
+    this._loaderId++;
+    this._loader = undefined;
     this._abortController?.abort();
   }
 }