@loaders.gl/core 5.0.0-alpha.12 → 5.0.0-alpha.13

package/src/loader-utils/lib/sources/raster-source.ts

@@ -0,0 +1,344 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+
+import type {TileGrid} from './tile-source';
+import type {TypedArray} from '../../types';
+import type {CRSDefinition, CRSIdentifier} from '@math.gl/geospatial/crs';
+
+/**
+ * Numeric channel types supported by viewport-driven raster payloads.
+ */
+export type RasterChannelDataType =
+  | 'uint8'
+  | 'uint16'
+  | 'uint32'
+  | 'int8'
+  | 'int16'
+  | 'int32'
+  | 'float32'
+  | 'float64';
+
+/**
+ * Bounding box in source coordinates.
+ */
+export type RasterBoundingBox = [min: [x: number, y: number], max: [x: number, y: number]];
+
+/**
+ * Minimal viewport shape accepted by {@link RasterSource}.
+ *
+ * This shape is intentionally compatible with deck.gl style 2D viewports without
+ * introducing a dependency on deck.gl types into loader-utils.
+ */
+export type RasterViewport = {
+  /** Stable viewport identifier used by higher-level loading managers. */
+  id: string;
+  /** Viewport pixel width. */
+  width: number;
+  /** Viewport pixel height. */
+  height: number;
+  /** Viewport zoom level. */
+  zoom: number;
+  /** Viewport center in source coordinates. */
+  center: number[];
+  /** Optional coordinate reference system for the requested raster view. */
+  crs?: CRSIdentifier;
+  /** Optional explicit bounds in source coordinates. */
+  bounds?: RasterBoundingBox;
+  /** Optional callback used to derive bounds from a deck.gl compatible viewport. */
+  getBounds?: () => [west: number, south: number, east: number, north: number];
+  /** Project source coordinates into the viewport. */
+  project: (coordinates: number[]) => number[];
+  /** Unproject viewport coordinates into source coordinates. */
+  unprojectPosition: (position: number[]) => [number, number, number];
+};
+
+/**
+ * CPU-side raster payload that can be uploaded to a rendering texture.
+ */
+export type RasterData = {
+  /** Raster sample buffer(s). */
+  data: TypedArray | TypedArray[];
+  /** Raster width in pixels. */
+  width: number;
+  /** Raster height in pixels. */
+  height: number;
+  /** Number of bands represented by this payload. */
+  bandCount: number;
+  /** Numeric channel type. */
+  dtype: RasterChannelDataType;
+  /** `true` when multiple bands are interleaved into one typed array. */
+  interleaved?: boolean;
+  /** Source no-data value when defined. */
+  noData?: number | null;
+  /** Bounds covered by this payload in source coordinates. */
+  boundingBox?: RasterBoundingBox;
+  /** Coordinate reference system for the payload bounds. */
+  crs?: CRSDefinition;
+  /** Per-band raw-domain interpretation, in payload order. */
+  bands?: RasterBandMetadata[];
+  /** Affine [a, b, c, d, e, f]: x = a*column + b*row + c; y = d*column + e*row + f. */
+  transform?: RasterAffineTransform;
+  /** Area samples are centered at grid coordinates +0.5; point samples at integer coordinates. */
+  pixelRegistration?: 'area' | 'point';
+  /** Masks use zero for invalid samples; values do not override nodata. */
+  validityMasks?: RasterValidityMask[];
+  /** Actual selected native overview. */
+  overview?: number;
+  /** Effective source units per output pixel, on both axes. */
+  resolution?: [number, number];
+  /** Resolution of the selected native source overview, when available. */
+  nativeResolution?: [number, number];
+  /** Whether requested pixels are finer than the selected native overview. */
+  overzoom?: boolean;
+  /** Structured provenance without credentials or authorization headers. */
+  provenance?: {sourceType: string; revision?: string};
+  /** Computed statistics, separate from format-declared metadata. */
+  statistics?: RasterBandStatistics[];
+  /** Buffer ownership; sampling never mutates buffers. */
+  ownership?: 'borrowed' | 'owned' | 'transferred';
+  /** Format-specific metadata retained for styling or upload configuration. */
+  metadata?: Record<string, unknown>;
+};
+
+/**
+ * Named indices selected from non-spatial raster dimensions.
+ *
+ * Sources define the supported dimension names in their source-specific metadata.
+ */
+export type RasterSelection = Readonly<Record<string, number>>;
+
+/**
+ * Parameters for {@link RasterSource.getRaster}.
+ */
+export type GetRasterParameters = {
+  /** Requested output viewport. */
+  viewport: RasterViewport;
+  /** Optional named indices for non-spatial dimensions such as time or vertical level. */
+  selection?: RasterSelection;
+  /** Optional sample indices to request. */
+  bands?: number[];
+  /** Whether to interleave multi-band output. Defaults to `false`. */
+  interleaved?: boolean;
+  /** Optional resampling method supported by the source implementation. */
+  resampleMethod?: 'nearest' | 'bilinear';
+  /** Abort signal forwarded to the underlying request. */
+  signal?: AbortSignal;
+};
+
+/**
+ * Description of one available overview level.
+ */
+export type RasterOverview = {
+  /** Zero-based image index or resolution level. */
+  index: number;
+  /** Overview width in pixels. */
+  width: number;
+  /** Overview height in pixels. */
+  height: number;
+  /** Source resolution for the overview when available. */
+  resolution?: [x: number, y: number];
+};
+
+/**
+ * Normalized metadata exposed by a viewport-driven raster source.
+ */
+export type RasterSourceMetadata = {
+  /** Name of the raster dataset. */
+  name?: string;
+  /** Human-readable title for the dataset. */
+  title?: string;
+  /** Dataset description. */
+  abstract?: string;
+  /** Dataset keywords. */
+  keywords?: string[];
+  /** Attribution strings. */
+  attributions?: string[];
+  /** Source coordinate reference system. */
+  crs?: CRSDefinition;
+  /** Dataset bounds in source coordinates. */
+  boundingBox?: RasterBoundingBox;
+  /** Full-resolution raster width. */
+  width: number;
+  /** Full-resolution raster height. */
+  height: number;
+  /** Number of raster bands. */
+  bandCount: number;
+  /** Numeric sample type. */
+  dtype: RasterChannelDataType;
+  /** Original band interpretation in source order. */
+  bands?: RasterBandMetadata[];
+  /** Native source-grid affine, when known. */
+  transform?: RasterAffineTransform;
+  /** Native grid registration. */
+  pixelRegistration?: 'area' | 'point';
+  /** Whether explicit numeric region requests are available. */
+  supportsRegion?: boolean;
+  /** Native tile dimensions when the source is tiled. */
+  tileSize?: {width: number; height: number};
+  /** Native tiled overview geometry; matrix IDs are source image indices. Edge tiles may extend beyond raster bounds. */
+  tileGrid?: TileGrid;
+  /** Available overview levels. */
+  overviews?: RasterOverview[];
+  /** Source no-data value when defined. */
+  noData?: number | null;
+  /** Format-specific metadata. */
+  metadata?: Record<string, unknown>;
+};
+
+/**
+ * RasterSource - data sources that allow typed raster data to be queried by viewport.
+ *
+ * @typeParam DataT Raster payload returned by the source.
+ * @typeParam ParametersT Request parameters accepted by the source.
+ * @typeParam MetadataT Metadata returned by the source.
+ */
+export interface RasterSource<
+  DataT extends NumericRasterData = RasterData,
+  ParametersT extends GetRasterParameters = GetRasterParameters,
+  MetadataT extends RasterSourceMetadata = RasterSourceMetadata
+> {
+  /** Additive explicit region capability, absent on legacy sources. */
+  readonly supportsRegion?: boolean;
+  /** Returns normalized dataset metadata without loading raster samples. */
+  getMetadata(options?: {
+    /** Optional metadata transport cancellation. */ signal?: AbortSignal;
+  }): Promise<MetadataT>;
+  /** Loads raster samples for the supplied viewport request. */
+  getRaster(parameters: ParametersT): Promise<DataT>;
+}
+
+/**
+ * Resolves viewport bounds from the local raster viewport shape.
+ */
+export function getRasterViewportBoundingBox(viewport: RasterViewport): RasterBoundingBox {
+  if (viewport.bounds) {
+    return viewport.bounds;
+  }
+
+  if (viewport.getBounds) {
+    const [west, south, east, north] = viewport.getBounds();
+    return [
+      [west, south],
+      [east, north]
+    ];
+  }
+
+  throw new Error('Raster viewport must provide bounds or getBounds().');
+}
+
+/** Source grid to source-coordinate affine transform. */
+export type RasterAffineTransform = [number, number, number, number, number, number];
+
+/** Interpretation of one band, without modifying raw samples. */
+export type RasterBandMetadata = {
+  /** Original zero-based source index. */
+  index: number;
+  /** Actual array representation for this band. */
+  dtype: RasterChannelDataType;
+  /** Human-readable band name. */
+  name?: string;
+  /** Physical units. */
+  units?: string;
+  /** Raw-to-physical multiplier. */
+  scale?: number;
+  /** Raw-to-physical additive offset. */
+  offset?: number;
+  /** Raw-domain nodata value. */
+  noData?: number | null;
+  /** Source-declared statistics, separate from computed payload statistics. */
+  declaredStatistics?: RasterDeclaredBandStatistics;
+  /** Whether interpolation is inappropriate for this band. */
+  categorical?: boolean;
+};
+
+/** Explicit mask indexing: offset + row*rowStride + column*pixelStride. */
+export type RasterValidityMask = {
+  /** Mask bytes; zero means invalid. */
+  data: Uint8Array;
+  /** Payload band index, or all bands when omitted. */
+  band?: number;
+  /** Number of columns. */
+  width: number;
+  /** Number of rows. */
+  height: number;
+  /** Byte offset, default zero. */
+  offset?: number;
+  /** Byte stride between columns, default one. */
+  pixelStride?: number;
+  /** Byte stride between rows, default width. */
+  rowStride?: number;
+};
+
+/** Statistics over a bounded set of valid samples. */
+export type RasterBandStatistics = {
+  /** Original source band index. */
+  band: number;
+  /** Value interpretation. */
+  domain: 'raw' | 'physical';
+  /** Minimum valid value, absent for all-invalid samples. */
+  min?: number;
+  /** Maximum valid value, absent for all-invalid samples. */
+  max?: number;
+  /** Number of valid inspected samples. */
+  validCount: number;
+  /** Statistical scope. */
+  scope: 'payload';
+  /** Whether every pixel was inspected. */
+  method: 'exact' | 'sampled';
+};
+
+/** Source declarations whose domain or valid count may be unavailable. */
+export type RasterDeclaredBandStatistics = {
+  /** Original source band index. */
+  band: number;
+  /** Declared interpretation; unknown means callers must not assume raw or physical values. */
+  domain: 'raw' | 'physical' | 'unknown';
+  /** Finite declared minimum, when available. */
+  min?: number;
+  /** Finite declared maximum, when available. */
+  max?: number;
+  /** Declared valid sample count, omitted when unavailable; never inferred from rounded percentages. */
+  validCount?: number;
+  /** Scope of the declaration, independent of the returned payload window. */
+  scope: 'source' | 'overview';
+  /** Source-provided values; no assertion that this implementation computed exact extrema. */
+  method: 'declared';
+};
+
+/** Explicit non-wrapped source-coordinate request. */
+export type RasterRegionParameters = Omit<GetRasterParameters, 'viewport'> & {
+  /** Ordered finite bounds in canonical x/y order. */
+  bounds: RasterBoundingBox;
+  /** Explicit request CRS; conversion is the caller's responsibility. */
+  crs: CRSDefinition;
+  /** Positive integer output width. */
+  width: number;
+  /** Positive integer output height. */
+  height: number;
+  /** Maximum output pixels, default 16 million. */
+  maxPixels?: number;
+  /** Maximum decoded bytes, default 256 MiB. */
+  maxDecodedBytes?: number;
+};
+
+/** Additive region capability; sources without it retain their viewport contract. */
+export interface RasterRegionSource extends RasterSource {
+  /** Loads one independently georeferenced region. */
+  getRasterForRegion(parameters: RasterRegionParameters): Promise<NumericRasterData>;
+}
+
+/** Additive mixed-representation payload; every band retains its own typed array and dtype. */
+export type RasterMixedData = Omit<RasterData, 'data' | 'dtype' | 'interleaved' | 'bands'> & {
+  /** Separate arrays in payload band order. */
+  data: TypedArray[];
+  /** Discriminator; there is no common numeric representation. */
+  dtype: 'mixed';
+  /** Mixed representations cannot be interleaved. */
+  interleaved: false;
+  /** Required per-band interpretation describes each actual array representation. */
+  bands: RasterBandMetadata[];
+};
+
+/** Common or explicitly mixed numeric samples. */
+export type NumericRasterData = RasterData | RasterMixedData;

package/src/loader-utils/lib/sources/service-capabilities.ts

@@ -0,0 +1,50 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+/** Protocol-neutral service families understood by geospatial service sources. */
+export type GeoServiceType =
+  | 'wms'
+  | 'wmts'
+  | 'wfs'
+  | 'csw'
+  | 'arcgis-map-server'
+  | 'arcgis-vector-tile-server'
+  | 'arcgis-image-server'
+  | 'arcgis-feature-server'
+  | 'arcgis-scene-server'
+  | 'unknown';
+
+/** A normalized description of a discoverable geospatial service. */
+export type ServiceCapabilities = {
+  /** Stable service URL. */
+  url?: string;
+  /** Protocol or vendor service family. */
+  type: GeoServiceType;
+  /** Machine-readable service identifier. */
+  name: string;
+  /** Human-readable service title. */
+  title?: string;
+  /** Service description. */
+  abstract?: string;
+  /** Supported coordinate reference systems. */
+  crs: string[];
+  /** Advertised response formats. */
+  formats: string[];
+  /** Named layers or feature types. */
+  layers: Array<{
+    name: string;
+    title?: string;
+    crs?: string[];
+    bounds?: number[];
+    id?: string;
+    url?: string;
+    profile?: string;
+    layerType?: string;
+    version?: string;
+  }>;
+  /** Supported request names, when advertised. */
+  operations: string[];
+  /** Original protocol-specific capability document. */
+  formatSpecificMetadata?: Record<string, unknown>;
+};

package/src/loader-utils/lib/sources/tile-grid.ts

@@ -0,0 +1,162 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import type {GetTileParameters, TileGrid, TileGridMatrix} from './tile-source';
+import {validateTileMatrix} from '@math.gl/geospatial';
+import type {TileMatrix, TileMatrixSet} from '@math.gl/geospatial';
+
+/**
+ * Builds a tile grid from advertised per-level metadata. `tileMatrixSet` is set only when every
+ * level is complete and valid, and the grid-wide fields are then derived from it. Otherwise the
+ * grid-wide fields describe the advertised first level, and the aligned `resolutions` and
+ * `matrixSizes` arrays are set only when every level has a value.
+ */
+export function createTileGrid(crs: string | undefined, matrices: TileGridMatrix[]): TileGrid {
+  const tileMatrixSet = getTileMatrixSet(crs, matrices);
+  if (tileMatrixSet) {
+    const levels = tileMatrixSet.matrices;
+    return {
+      crs,
+      tileSize: [levels[0].tileSize[0], levels[0].tileSize[1]],
+      // The grid-wide origin is documented as top-left, so a bottom-left origin is per-level only.
+      origin:
+        levels[0].cornerOfOrigin === 'topLeft'
+          ? [levels[0].origin[0], levels[0].origin[1]]
+          : undefined,
+      resolutions: levels.map(matrix => matrix.resolution),
+      matrixIds: levels.map(matrix => matrix.id),
+      matrixSizes: levels.map(matrix => [matrix.matrixSize[0], matrix.matrixSize[1]]),
+      tileMatrixSet,
+      matrices
+    };
+  }
+  return {
+    crs,
+    tileSize: matrices[0]?.tileSize,
+    // The grid-wide origin is documented as top-left, so a bottom-left origin is per-level only.
+    origin: matrices[0]?.cornerOfOrigin === 'bottomLeft' ? undefined : matrices[0]?.origin,
+    ...(matrices.length && matrices.every(matrix => matrix.resolution !== undefined)
+      ? {resolutions: matrices.map(matrix => matrix.resolution!)}
+      : {}),
+    matrixIds: matrices.map(matrix => matrix.id),
+    matrixSizes: matrices.every(matrix => matrix.matrixSize)
+      ? matrices.map(matrix => matrix.matrixSize!)
+      : undefined,
+    matrices
+  };
+}
+
+/** Returns complete geometry for every level, or undefined when any level is incomplete or invalid. */
+function getTileMatrixSet(
+  crs: string | undefined,
+  matrices: TileGridMatrix[]
+): TileMatrixSet | undefined {
+  if (!crs || !matrices.length) return undefined;
+  const tileMatrices: TileMatrix[] = [];
+  for (const matrix of matrices) {
+    const tileMatrix = toTileMatrix(matrix);
+    if (!tileMatrix) return undefined;
+    tileMatrices.push(tileMatrix);
+  }
+  return {crs, matrices: tileMatrices};
+}
+
+/** Converts one advertised level to math.gl geometry, or null when it is incomplete or invalid. */
+function toTileMatrix(matrix: TileGridMatrix): TileMatrix | null {
+  const {id, resolution, resolutionY, origin, tileSize, matrixSize} = matrix;
+  if (resolution === undefined || !origin || !tileSize || !matrixSize) return null;
+  const tileMatrix: TileMatrix = {
+    id,
+    resolution,
+    ...(resolutionY !== undefined ? {resolutionY} : {}),
+    origin: [origin[0], origin[1]],
+    cornerOfOrigin: matrix.cornerOfOrigin ?? 'topLeft',
+    tileSize: [tileSize[0], tileSize[1]],
+    matrixSize: [matrixSize[0], matrixSize[1]]
+  };
+  try {
+    validateTileMatrix(tileMatrix);
+  } catch {
+    return null;
+  }
+  return tileMatrix;
+}
+
+/** Advertised fields of one tile matrix, in the service's own axis order. */
+export type TileMatrixFields = {
+  /** Advertised matrix identifier. */
+  id: string;
+  /** Coordinate units per pixel, when known. */
+  resolution?: number;
+  /** Vertical coordinate units per pixel; defaults to the horizontal resolution. */
+  resolutionY?: number;
+  /** Origin as advertised; swapped to XY when `swapAxes` is set. */
+  point?: number[];
+  /** Whether the advertised coordinates are Y first. */
+  swapAxes: boolean;
+  /** Corner located by the origin; defaults to top-left. */
+  cornerOfOrigin?: 'topLeft' | 'bottomLeft';
+  /** Advertised tile width in pixels. */
+  tileWidth?: number;
+  /** Advertised tile height in pixels. */
+  tileHeight?: number;
+  /** Advertised matrix width in tiles. */
+  matrixWidth?: number;
+  /** Advertised matrix height in tiles. */
+  matrixHeight?: number;
+};
+
+/** Builds one tile-grid level, keeping only the fields the service advertises. */
+export function createTileGridMatrix(fields: TileMatrixFields): TileGridMatrix {
+  const {point, tileWidth, tileHeight} = fields;
+  const tileGridMatrix: TileGridMatrix = {id: fields.id};
+  if (fields.resolution !== undefined) tileGridMatrix.resolution = fields.resolution;
+  if (fields.resolutionY !== undefined) tileGridMatrix.resolutionY = fields.resolutionY;
+  if (point && point.length >= 2) {
+    tileGridMatrix.origin = fields.swapAxes ? [point[1], point[0]] : [point[0], point[1]];
+  }
+  if (String(fields.cornerOfOrigin).toLowerCase() === 'bottomleft') {
+    tileGridMatrix.cornerOfOrigin = 'bottomLeft';
+  }
+  if (tileWidth !== undefined && tileHeight !== undefined) {
+    tileGridMatrix.tileSize = [tileWidth, tileHeight];
+  }
+  if (fields.matrixWidth !== undefined && fields.matrixHeight !== undefined) {
+    tileGridMatrix.matrixSize = [fields.matrixWidth, fields.matrixHeight];
+  }
+  return tileGridMatrix;
+}
+
+/**
+ * Returns the matrix a tile request addresses. An explicit `tileMatrix` identifier is matched
+ * exactly and throws when the set does not contain it. Without one, `z` selects the matrix whose
+ * identifier is that number, otherwise the matrix at index `z`, without rounding or clamping.
+ */
+export function getRequestedTileMatrix<MatrixT>(
+  matrices: readonly MatrixT[],
+  getId: (matrix: MatrixT) => string,
+  parameters: Pick<GetTileParameters, 'z' | 'tileMatrix'>
+): MatrixT | undefined {
+  if (parameters.tileMatrix !== undefined) {
+    const matrix = matrices.find(candidate => getId(candidate) === parameters.tileMatrix);
+    if (!matrix) throw new RangeError(`Unknown tile matrix "${parameters.tileMatrix}"`);
+    return matrix;
+  }
+  return matrices.find(matrix => getId(matrix) === String(parameters.z)) || matrices[parameters.z];
+}
+
+/**
+ * Returns the `{tileMatrix}` identifier for a request. With a known grid, the requested matrix
+ * must exist in it (see `getRequestedTileMatrix()`); a missing one throws instead of falling back
+ * to `z`. Without a grid, the explicit identifier is used verbatim, otherwise `z`.
+ */
+export function getTileGridMatrixId(
+  tileGrid: TileGrid | undefined,
+  parameters: Pick<GetTileParameters, 'z' | 'tileMatrix'>
+): string {
+  if (!tileGrid?.matrices) return parameters.tileMatrix ?? String(parameters.z);
+  const matrix = getRequestedTileMatrix(tileGrid.matrices, level => level.id, parameters);
+  if (!matrix) throw new RangeError(`No tile matrix for z ${parameters.z}`);
+  return matrix.id;
+}

package/src/loader-utils/lib/sources/tile-source-adapter.ts

@@ -0,0 +1,126 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {getTileBounds, isTileIndexInRange, validateTileMatrix} from '@math.gl/geospatial';
+import type {TileSource, GetTileParameters, GetTileDataParameters, TileGrid} from './tile-source';
+import type {ImageSource, ImageSourceMetadata} from './image-source';
+import {getRequestedTileMatrix} from './tile-grid';
+
+/** Converts image-window requests into tiles in a configured grid, or legacy geographic XYZ. */
+export class TileSourceAdapter<ImageSourceT extends ImageSource> implements TileSource {
+  /** Image-window source used to fulfill tile requests. */
+  readonly viewportSource: ImageSourceT;
+  /** Explicit geometry and availability; never inferred from image dataset bounds. */
+  readonly tileGrid?: TileGrid;
+
+  /** Wraps an image source, optionally using an authoritative matrix set. */
+  constructor(source: ImageSourceT, tileGrid?: TileGrid) {
+    if (
+      tileGrid &&
+      (!tileGrid.tileMatrixSet?.crs ||
+        !tileGrid.tileMatrixSet.matrices.length ||
+        new Set(tileGrid.tileMatrixSet.matrices.map(matrix => matrix.id)).size !==
+          tileGrid.tileMatrixSet.matrices.length)
+    )
+      throw new Error('TileSourceAdapter requires complete tile matrix geometry.');
+    for (const matrix of tileGrid?.tileMatrixSet?.matrices || []) validateTileMatrix(matrix);
+    this.viewportSource = source;
+    this.tileGrid = tileGrid;
+  }
+
+  /** Returns source metadata plus the explicitly configured tile grid. */
+  async getMetadata(): Promise<ImageSourceMetadata & {tileGrid?: TileGrid}> {
+    const metadata = await this.viewportSource.getMetadata();
+    return this.tileGrid ? {...metadata, tileGrid: this.tileGrid} : metadata;
+  }
+
+  /** Requests native matrix bounds and pixel dimensions without reprojection. */
+  getTile(parameters: GetTileParameters): Promise<unknown | null> {
+    let width = 512;
+    let height = 512;
+    let coordinateReferenceSystem = 'EPSG:4326';
+    const set = this.tileGrid?.tileMatrixSet;
+    if (set) {
+      if (parameters.crs && parameters.crs !== set.crs)
+        throw new Error('TileSourceAdapter does not support reprojection.');
+      const matrix = getRequestedTileMatrix(set.matrices, level => level.id, parameters);
+      if (!matrix) return Promise.resolve(null);
+      const limits = this.tileGrid?.limits?.find(limit => limit.tileMatrix === matrix.id);
+      if (
+        (this.tileGrid?.limits !== undefined && !limits) ||
+        !isTileIndexInRange(matrix, parameters.x, parameters.y, limits)
+      )
+        return Promise.resolve(null);
+      [width, height] = matrix.tileSize;
+      coordinateReferenceSystem = set.crs;
+    } else if (parameters.tileMatrix !== undefined) {
+      throw new RangeError('Explicit tile matrix selection requires a configured grid.');
+    }
+    const boundingBox = this.getTileBoundingBox(parameters);
+    return this.viewportSource.getImage({
+      boundingBox,
+      layers: parameters.layers || [],
+      width,
+      height,
+      crs: coordinateReferenceSystem,
+      styles: parameters.styles,
+      format: parameters.format,
+      signal: parameters.signal
+    });
+  }
+
+  /** Preserves matrix identity and cancellation from deck.gl-compatible requests. */
+  getTileData(parameters: GetTileDataParameters): Promise<unknown | null> {
+    return this.getTile({
+      ...parameters.index,
+      tileMatrix: parameters.tileMatrix,
+      signal: parameters.signal
+    });
+  }
+
+  /** Returns native configured bounds, or longitude/latitude bounds for legacy XYZ requests. */
+  protected getTileBoundingBox(
+    parameters: GetTileParameters
+  ): [min: [number, number], max: [number, number]] {
+    const set = this.tileGrid?.tileMatrixSet;
+    if (set) {
+      const matrix = getRequestedTileMatrix(set.matrices, level => level.id, parameters);
+      if (!matrix) throw new RangeError('No tile matrix for request.');
+      const [minimumX, minimumY, maximumX, maximumY] = getTileBounds(
+        matrix,
+        parameters.x,
+        parameters.y
+      );
+      return [
+        [minimumX, minimumY],
+        [maximumX, maximumY]
+      ];
+    }
+    if (parameters.crs && parameters.crs !== 'EPSG:4326')
+      throw new Error('Legacy XYZ image bounds require EPSG:4326.');
+    const {x, y, z} = parameters;
+    if (
+      !Number.isInteger(z) ||
+      z < 0 ||
+      z > 30 ||
+      !Number.isInteger(x) ||
+      !Number.isInteger(y) ||
+      x < 0 ||
+      y < 0 ||
+      x >= 2 ** z ||
+      y >= 2 ** z
+    )
+      throw new RangeError('Invalid XYZ tile index.');
+    return [this.getTileLowerLeftCorner(x, y, z), this.getTileLowerLeftCorner(x + 1, y - 1, z)];
+  }
+
+  /** Returns a longitude/latitude lower-left corner of a canonical XYZ tile. */
+  getTileLowerLeftCorner(x: number, y: number, zoom: number): [number, number] {
+    const count = 2 ** zoom;
+    return [
+      (x / count) * 360 - 180,
+      (180 / Math.PI) * Math.atan(Math.sinh(Math.PI * (1 - (2 * (y + 1)) / count)))
+    ];
+  }
+}