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

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

@@ -0,0 +1,236 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import type {Loader, LoaderContext, LoaderOptions, StrictLoaderOptions} from '../../loader-types';
+import type {BatchableDataType, DataType, SyncDataType} from '../../types';
+import type {ReadableFile} from '../files/file';
+import {mergeOptions} from '../option-utils/merge-options';
+import {resolvePath} from '../path-utils/file-aliases';
+import {log} from '../log-utils/log';
+import {getAuthenticatedFetch} from '../request-utils/request-credentials';
+import {resolveAuthenticationOptions} from '../request-utils/authentication';
+
+/** Common properties for all data sources */
+export type DataSourceOptions = StrictLoaderOptions & {
+  /** Removed in v5. Pass parser options directly in their loader namespaces. */
+  loadOptions?: never;
+  core?: StrictLoaderOptions['core'] & {
+    /** Allows application to specify which source should be selected. Matches `Source.type`. Defaults to 'auto' */
+    type?: string;
+    /** Any dataset attributions (in case underlying metadata does not include attributions) */
+    attributions?: string[];
+    /** Removed in v5. Move these options to `core` and the root loader namespaces. */
+    loadOptions?: never;
+    /** Make additional loaders available to the data source */
+    loaders?: Loader[];
+    /** Called when source-level initialization or metadata loading fails. */
+    onError?: (error: Error, source: DataSource<any, any>) => void;
+  };
+};
+
+/** Runtime hooks injected when a DataSource is created through an integration layer such as `@loaders.gl/core`. */
+export type CoreAPI = Readonly<{
+  fetchFile: (urlOrData: string | Blob, fetchOptions?: RequestInit) => Promise<Response>;
+  parse: (
+    data: DataType | Promise<DataType>,
+    loaders?: Loader | Loader[] | LoaderOptions,
+    options?: LoaderOptions,
+    context?: LoaderContext
+  ) => Promise<unknown>;
+  parseFile: (
+    file: ReadableFile,
+    loaders?: Loader | Loader[] | LoaderOptions,
+    options?: LoaderOptions,
+    context?: LoaderContext
+  ) => Promise<unknown>;
+  parseSync: (
+    data: SyncDataType,
+    loaders?: Loader | Loader[] | LoaderOptions,
+    options?: LoaderOptions,
+    context?: LoaderContext
+  ) => unknown;
+  parseInBatches: (
+    data: BatchableDataType,
+    loaders?: Loader | Loader[] | LoaderOptions,
+    options?: LoaderOptions,
+    context?: LoaderContext
+  ) => Promise<AsyncIterable<unknown> | Iterable<unknown>>;
+  load: (
+    url: string | DataType,
+    loaders?: Loader[] | LoaderOptions | Loader,
+    options?: LoaderOptions | LoaderContext,
+    context?: LoaderContext
+  ) => Promise<unknown>;
+  loadInBatches: (
+    files: string | File | Blob | Response | (string | File | Blob | Response)[] | FileList,
+    loaders?: Loader[] | LoaderOptions | Loader,
+    options?: LoaderOptions,
+    context?: LoaderContext
+  ) => Promise<AsyncIterable<unknown>> | Promise<AsyncIterable<unknown>>[];
+}>;
+
+const UNAVAILABLE_CORE_API: CoreAPI = {
+  fetchFile: unavailableCoreApiMethod('fetchFile'),
+  parse: unavailableCoreApiMethod('parse'),
+  parseFile: unavailableCoreApiMethod('parseFile'),
+  parseSync: unavailableCoreApiMethod('parseSync'),
+  parseInBatches: unavailableCoreApiMethod('parseInBatches'),
+  load: unavailableCoreApiMethod('load'),
+  loadInBatches: unavailableCoreApiMethod('loadInBatches')
+};
+
+/** base class of all data sources */
+export abstract class DataSource<DataT, OptionsT extends DataSourceOptions> {
+  static defaultOptions = {
+    core: {
+      type: 'auto',
+      attributions: [],
+      loaders: [],
+      onError: undefined!
+    }
+  } satisfies DataSourceOptions;
+
+  optionsType?: OptionsT & DataSourceOptions;
+  options: Required<OptionsT & DataSourceOptions>;
+  readonly data: DataT;
+  readonly url: string;
+
+  /** Shared parser options derived from the source options, excluding source-only core controls. */
+  loadOptions: StrictLoaderOptions;
+  /** A resolved fetch function extracted from the shared core options. */
+  fetch: (url: string, options?: RequestInit) => Promise<Response>;
+  /** Shared source-level runtime hooks, when supplied by the source factory. */
+  readonly coreApi: CoreAPI;
+  /** Whether a real CoreAPI instance was injected by the integration layer. */
+  readonly hasCoreApi: boolean;
+  _needsRefresh: boolean = true;
+
+  constructor(
+    data: DataT,
+    options: OptionsT,
+    defaultOptions?: Partial<OptionsT>,
+    coreApi?: CoreAPI
+  ) {
+    this.options = mergeOptions<DataSourceOptions>(
+      mergeOptions<DataSourceOptions>(DataSource.defaultOptions, defaultOptions || {}),
+      options
+    ) as Required<OptionsT & DataSourceOptions>;
+    this.data = data;
+    this.url = typeof data === 'string' ? resolvePath(data) : '';
+    const loadOptions = resolveAuthenticationOptions(getSourceLoaderOptions(this.options));
+    this.loadOptions = loadOptions;
+    const fetch = getFetchFunction(loadOptions);
+    this.coreApi = coreApi || UNAVAILABLE_CORE_API;
+    this.hasCoreApi = Boolean(coreApi);
+    this.fetch = fetch;
+  }
+
+  setProps(options: OptionsT) {
+    const mergedOptions = mergeOptions<DataSourceOptions>(this.options, options) as Required<
+      OptionsT & DataSourceOptions
+    >;
+    const loadOptions = resolveAuthenticationOptions(getSourceLoaderOptions(mergedOptions));
+    this.options = mergedOptions;
+    this.loadOptions = loadOptions;
+    this.fetch = getFetchFunction(loadOptions);
+    // TODO - add a shallow compare to avoid setting refresh if no change?
+    this.setNeedsRefresh();
+  }
+
+  /** Mark this data source as needing a refresh (redraw) */
+  setNeedsRefresh(): void {
+    this._needsRefresh = true;
+  }
+
+  /**
+   * Does this data source need refreshing?
+   * @note The specifics of the refresh mechanism depends on type of data source
+   */
+  getNeedsRefresh(clear: boolean = true) {
+    const needsRefresh = this._needsRefresh;
+    if (clear) {
+      this._needsRefresh = false;
+    }
+    return needsRefresh;
+  }
+
+  /** Reports a source-level failure through the configured callback or the shared logger. */
+  protected reportError(error: unknown, message: string): Error {
+    const normalizedError = normalizeError(error, message);
+    const callback = this.options.core?.onError;
+    if (callback) {
+      callback(normalizedError, this);
+    } else {
+      log.warn(`${this.constructor.name}: ${normalizedError.message}`)();
+    }
+    return normalizedError;
+  }
+}
+
+/**
+ * Gets the current fetch function from options
+ * @todo - move to loader-utils module
+ * @todo - use in core module counterpart
+ * @param options
+ * @param context
+ */
+export function getFetchFunction(options?: StrictLoaderOptions) {
+  return getAuthenticatedFetch(options);
+}
+
+/**
+ * Derives parser options from flat source options without forwarding source controls to workers.
+ * Removed option wrappers are rejected so JavaScript callers receive actionable migration guidance.
+ */
+export function getSourceLoaderOptions(options: DataSourceOptions): StrictLoaderOptions {
+  if (options.loadOptions !== undefined || options.core?.loadOptions !== undefined) {
+    throw new Error(
+      'Source loadOptions and core.loadOptions were removed. Use core and root loader namespaces directly.'
+    );
+  }
+  const loadOptions: LoaderOptions = {...options};
+  if (options?.core) {
+    loadOptions.core = {...options.core};
+    const parserCore = loadOptions.core as Record<string, unknown>;
+    for (const key of ['type', 'attributions', 'loaders', 'onError', 'loadOptions']) {
+      delete parserCore[key];
+    }
+    if (Object.keys(parserCore).length === 0) {
+      delete loadOptions.core;
+    }
+  }
+
+  const topLevelBaseUri = typeof loadOptions.baseUri === 'string' ? loadOptions.baseUri : undefined;
+  const topLevelBaseUrl = typeof loadOptions.baseUrl === 'string' ? loadOptions.baseUrl : undefined;
+
+  if (topLevelBaseUri !== undefined || topLevelBaseUrl !== undefined) {
+    loadOptions.core ||= {};
+    if (loadOptions.core.baseUrl === undefined) {
+      loadOptions.core.baseUrl = topLevelBaseUrl ?? topLevelBaseUri;
+    }
+    delete loadOptions.baseUri;
+    delete loadOptions.baseUrl;
+  }
+
+  return loadOptions as StrictLoaderOptions;
+}
+
+/** Normalizes arbitrary thrown values to `Error` instances for source-level reporting. */
+function normalizeError(error: unknown, message: string): Error {
+  if (error instanceof Error) {
+    return error;
+  }
+  if (typeof error === 'string') {
+    return new Error(error);
+  }
+  return new Error(message);
+}
+
+function unavailableCoreApiMethod(methodName: keyof CoreAPI) {
+  return () => {
+    throw new Error(
+      `CoreAPI.${methodName} is unavailable. Use @loaders.gl/core.createDataSource().`
+    );
+  };
+}

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

@@ -0,0 +1,66 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+// TODO - can we import from schema?
+import type {ImageType} from './utils/image-type';
+import type {CRSIdentifier} from '@math.gl/geospatial/crs';
+// TODO - remove (this breaks WMS layer)
+
+/**
+ * ImageSource - data sources that allow images to be queried by (geospatial) extents
+ */
+export interface ImageSource {
+  getMetadata(): Promise<ImageSourceMetadata>;
+  getImage(parameters: GetImageParameters): Promise<ImageType>;
+}
+
+// PARAMETER TYPES
+
+/**
+ * Normalized capabilities of an Image service
+ * @example
+ *  The WMSSourceLoader will normalize the response to the WMS `GetCapabilities`
+ *  data structure extracted from WMS XML response into an ImageSourceMetadata.
+ */
+export type ImageSourceMetadata = {
+  name: string;
+  title?: string;
+  abstract?: string;
+  keywords: string[];
+  layers: ImageSourceLayer[];
+};
+
+/** Description of one data layer in the image source */
+export type ImageSourceLayer = {
+  /** Name of this layer */
+  name?: string;
+  /** Human readable title of this layer */
+  title?: string;
+  /** Coordinate systems supported by this layer */
+  crs?: CRSIdentifier[];
+  /** layer limits in unspecified CRS:84-like lng/lat, for quick access w/o CRS calculations. */
+  boundingBox?: [min: [x: number, y: number], max: [x: number, y: number]];
+  /** Sub layers of this layer */
+  layers?: ImageSourceLayer[];
+};
+
+/** Generic parameters for requesting an image from an image source */
+export type GetImageParameters = {
+  /** Layers to render */
+  layers: string | string[];
+  /** Styling */
+  styles?: unknown;
+  /** bounding box of the requested map image */
+  boundingBox: [min: [x: number, y: number], max: [x: number, y: number]];
+  /** pixel width of returned image */
+  width: number;
+  /** pixels */
+  height: number;
+  /** crs for the image (not the bounding box) */
+  crs?: CRSIdentifier;
+  /** requested format for the return image */
+  format?: 'image/png';
+  /** Abort signal for canceling in-flight requests. */
+  signal?: AbortSignal;
+};

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

@@ -0,0 +1,22 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import type {ImageType} from './utils/image-type';
+import type {
+  TileSourceProps,
+  TileSourceMetadata,
+  GetTileParameters,
+  TileSource
+} from './tile-source';
+
+export type ImageTileSourceProps = TileSourceProps;
+
+/**
+ * MapTileSource - data sources that allow data to be queried by (geospatial) tile
+ * @note If geospatial, bounding box is expected to be in web mercator coordinates
+ */
+export interface ImageTileSource extends TileSource {
+  getMetadata(): Promise<TileSourceMetadata>;
+  getImageTile(parameters: GetTileParameters): Promise<ImageType | null>;
+}

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

@@ -0,0 +1,92 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+
+import type {NumericRasterData, RasterRegionParameters} from './raster-source';
+
+/** Identity and interpretation used to qualify accepted coverage reuse. */
+export type RasterCoverageIdentity = {
+  /** Borrowed source instance identity. */
+  source: object;
+  /** Source revision token. */
+  revision?: unknown;
+  /** Opaque authorization identity; never exported in raster provenance. */
+  authorization?: unknown;
+  /** Caller-defined nodata/scaling interpretation identity. */
+  interpretation?: unknown;
+  /** Caller-defined service parameter identity. */
+  serviceParameters?: unknown;
+};
+
+/** Reuses one accepted axis-aligned payload only when identity, selection and both resolutions qualify. */
+export function canReuseRasterCoverage(
+  raster: NumericRasterData,
+  accepted: RasterRegionParameters,
+  candidate: RasterRegionParameters,
+  acceptedIdentity: RasterCoverageIdentity,
+  candidateIdentity: RasterCoverageIdentity,
+  maximumStretch = 1
+): boolean {
+  if (!Number.isFinite(maximumStretch) || maximumStretch < 1) return false;
+  for (const key of [
+    'source',
+    'revision',
+    'authorization',
+    'interpretation',
+    'serviceParameters'
+  ] as const) {
+    if (acceptedIdentity[key] !== candidateIdentity[key]) return false;
+  }
+  if (
+    accepted.crs !== candidate.crs ||
+    raster.crs !== candidate.crs ||
+    accepted.interleaved !== candidate.interleaved ||
+    accepted.resampleMethod !== candidate.resampleMethod
+  )
+    return false;
+  if (JSON.stringify(accepted.bands) !== JSON.stringify(candidate.bands)) return false;
+  const selectionKeys = new Set([
+    ...Object.keys(accepted.selection || {}),
+    ...Object.keys(candidate.selection || {})
+  ]);
+  for (const key of selectionKeys)
+    if (accepted.selection?.[key] !== candidate.selection?.[key]) return false;
+  const bounds = raster.boundingBox;
+  const resolution = raster.resolution;
+  if (
+    !bounds ||
+    !resolution ||
+    !raster.transform ||
+    raster.transform[1] !== 0 ||
+    raster.transform[3] !== 0
+  )
+    return false;
+  if (
+    !Number.isSafeInteger(candidate.width) ||
+    !Number.isSafeInteger(candidate.height) ||
+    candidate.width <= 0 ||
+    candidate.height <= 0
+  )
+    return false;
+  for (let axis = 0; axis < 2; axis++) {
+    const minimum = candidate.bounds[0][axis];
+    const maximum = candidate.bounds[1][axis];
+    if (
+      !Number.isFinite(minimum) ||
+      !Number.isFinite(maximum) ||
+      minimum >= maximum ||
+      minimum < bounds[0][axis] ||
+      maximum > bounds[1][axis]
+    )
+      return false;
+    const requestedResolution =
+      (maximum - minimum) / (axis === 0 ? candidate.width : candidate.height);
+    if (
+      !Number.isFinite(resolution[axis]) ||
+      resolution[axis] <= 0 ||
+      resolution[axis] > requestedResolution * maximumStretch
+    )
+      return false;
+  }
+  return true;
+}

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

@@ -0,0 +1,35 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+
+import type {RasterBoundingBox} from './raster-source';
+
+/** Validates canonical region geometry and bounds the estimated decoded allocation. */
+export function validateRasterRegion(
+  bounds: RasterBoundingBox,
+  width: number,
+  height: number,
+  bytesPerPixel: number,
+  maxPixels = 16_000_000,
+  maxDecodedBytes = 256 * 1024 * 1024
+): number {
+  if (
+    !bounds.flat().every(Number.isFinite) ||
+    bounds[0][0] >= bounds[1][0] ||
+    bounds[0][1] >= bounds[1][1]
+  )
+    throw new Error('Raster bounds must be finite, ordered and non-wrapped');
+  if (![maxPixels, maxDecodedBytes].every(value => Number.isSafeInteger(value) && value > 0))
+    throw new Error('Raster budgets must be positive finite integers');
+  const pixels = width * height;
+  if (
+    ![width, height].every(value => Number.isSafeInteger(value) && value > 0) ||
+    !Number.isFinite(bytesPerPixel) ||
+    bytesPerPixel <= 0 ||
+    !Number.isSafeInteger(pixels) ||
+    pixels > maxPixels ||
+    pixels * bytesPerPixel > maxDecodedBytes
+  )
+    throw new Error('Raster dimensions exceed pixel or decoded-byte budget');
+  return pixels;
+}

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

@@ -0,0 +1,213 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+
+import type {CRSDefinition} from '@math.gl/geospatial/crs';
+import type {NumericRasterData, RasterBandStatistics} from './raster-source';
+
+/** Options for synchronous sample-center-index sampling. */
+export type RasterSampleOptions = {
+  /** Payload band indices; defaults to all bands. */
+  bands?: number[];
+  /** Sampling method; bilinear requires every contributing neighbor valid. */
+  method?: 'nearest' | 'bilinear';
+  /** Raw samples by default; physical applies scale and offset once. */
+  domain?: 'raw' | 'physical';
+};
+
+/** An explicit miss or values with per-band validity. */
+export type RasterSample = {
+  /** Whether the coordinate falls outside the payload. */
+  miss: boolean;
+  /** Invalid values are undefined. */
+  values: (number | undefined)[];
+  /** Validity in requested band order. */
+  valid: boolean[];
+  /** Original source band indices. */
+  bands: number[];
+  /** Displayed native overview. */
+  overview?: number;
+  /** Source provenance. */
+  provenance?: NumericRasterData['provenance'];
+};
+
+/** Reads a raw sample without modifying the payload. */
+function readRasterValue(
+  raster: NumericRasterData,
+  column: number,
+  row: number,
+  band: number
+): number {
+  const index = row * raster.width + column;
+  if (Array.isArray(raster.data)) return Number(raster.data[band]?.[index]);
+  return Number(
+    raster.data[
+      raster.interleaved
+        ? index * raster.bandCount + band
+        : band * raster.width * raster.height + index
+    ]
+  );
+}
+
+/** Evaluates masks, raw nodata and non-finite samples in the same order for every layout. */
+export function isRasterSampleValid(
+  raster: NumericRasterData,
+  column: number,
+  row: number,
+  band: number
+): boolean {
+  if (
+    !Number.isInteger(column) ||
+    !Number.isInteger(row) ||
+    column < 0 ||
+    row < 0 ||
+    column >= raster.width ||
+    row >= raster.height ||
+    !Number.isInteger(band) ||
+    band < 0 ||
+    band >= raster.bandCount
+  )
+    return false;
+  const value = readRasterValue(raster, column, row, band);
+  if (!Number.isFinite(value)) return false;
+  const metadata = raster.bands?.[band];
+  const noData = metadata?.noData === undefined ? raster.noData : metadata.noData;
+  if (
+    noData !== undefined &&
+    noData !== null &&
+    value === ((metadata?.dtype ?? raster.dtype) === 'float32' ? Math.fround(noData) : noData)
+  )
+    return false;
+  return (raster.validityMasks || []).every(mask => {
+    if (mask.band !== undefined && mask.band !== band) return true;
+    if (column >= mask.width || row >= mask.height) return false;
+    const index =
+      (mask.offset ?? 0) + row * (mask.rowStride ?? mask.width) + column * (mask.pixelStride ?? 1);
+    return (
+      index >= 0 &&
+      index < mask.data.length &&
+      mask.data[index] !== undefined &&
+      mask.data[index] !== 0
+    );
+  });
+}
+
+/** Samples fractional sample-center indices; bilinear never blends categorical bands. */
+export function sampleRaster(
+  raster: NumericRasterData,
+  pixel: [number, number],
+  options: RasterSampleOptions = {}
+): RasterSample {
+  const bands = options.bands ?? Array.from({length: raster.bandCount}, (_, index) => index);
+  if (bands.some(band => !Number.isInteger(band) || band < 0 || band >= raster.bandCount))
+    throw new Error('Invalid raster band index');
+  const [column, row] = pixel;
+  const nearestColumn = Math.floor(column + 0.5);
+  const nearestRow = Math.floor(row + 0.5);
+  const miss =
+    !Number.isFinite(column) ||
+    !Number.isFinite(row) ||
+    nearestColumn < 0 ||
+    nearestRow < 0 ||
+    nearestColumn >= raster.width ||
+    nearestRow >= raster.height;
+  const values = bands.map(band => {
+    if (miss) return undefined;
+    let value = 0;
+    const metadata = raster.bands?.[band];
+    if (options.method !== 'bilinear' || metadata?.categorical) {
+      if (!isRasterSampleValid(raster, nearestColumn, nearestRow, band)) return undefined;
+      value = readRasterValue(raster, nearestColumn, nearestRow, band);
+    } else {
+      const left = Math.floor(column);
+      const top = Math.floor(row);
+      for (let vertical = 0; vertical < 2; vertical++) {
+        for (let horizontal = 0; horizontal < 2; horizontal++) {
+          const weight =
+            (horizontal ? column - left : 1 - column + left) *
+            (vertical ? row - top : 1 - row + top);
+          if (weight === 0) continue;
+          if (!isRasterSampleValid(raster, left + horizontal, top + vertical, band))
+            return undefined;
+          value += weight * readRasterValue(raster, left + horizontal, top + vertical, band);
+        }
+      }
+    }
+    const result =
+      options.domain === 'physical'
+        ? value * (metadata?.scale ?? 1) + (metadata?.offset ?? 0)
+        : value;
+    return Number.isFinite(result) ? result : undefined;
+  });
+  return {
+    miss,
+    values,
+    valid: values.map(value => value !== undefined),
+    bands: bands.map(band => raster.bands?.[band]?.index ?? band),
+    overview: raster.overview,
+    provenance: raster.provenance
+  };
+}
+
+/** Inverts an explicit affine in the matching CRS, normalizing area registration to sample centers. */
+export function rasterCoordinateToPixel(
+  raster: NumericRasterData,
+  coordinate: [number, number],
+  crs: CRSDefinition
+): [number, number] {
+  if (!raster.crs || raster.crs !== crs)
+    throw new Error('Raster coordinate CRS must match payload CRS');
+  if (!raster.transform) throw new Error('Raster affine transform is unavailable');
+  const [columnScale, rowShear, originX, columnShear, rowScale, originY] = raster.transform;
+  const determinant = columnScale * rowScale - rowShear * columnShear;
+  if (
+    !raster.transform.every(Number.isFinite) ||
+    !Number.isFinite(determinant) ||
+    determinant === 0
+  )
+    throw new Error('Singular or invalid raster affine transform');
+  const deltaX = coordinate[0] - originX;
+  const deltaY = coordinate[1] - originY;
+  const shift = raster.pixelRegistration === 'point' ? 0 : 0.5;
+  return [
+    (rowScale * deltaX - rowShear * deltaY) / determinant - shift + 0,
+    (columnScale * deltaY - columnShear * deltaX) / determinant - shift + 0
+  ];
+}
+
+/** Computes bounded deterministic statistics; sampled ranges are not exact extrema. */
+export function computeRasterStatistics(
+  raster: NumericRasterData,
+  sampleBudget: number,
+  domain: 'raw' | 'physical' = 'raw'
+): RasterBandStatistics[] {
+  if (!Number.isSafeInteger(sampleBudget) || sampleBudget <= 0)
+    throw new Error('Statistics sample budget must be a positive integer');
+  const pixelCount = raster.width * raster.height;
+  const count = Math.min(pixelCount, sampleBudget);
+  return Array.from({length: raster.bandCount}, (_, band) => {
+    let minimumValue = Infinity;
+    let maximumValue = -Infinity;
+    let validCount = 0;
+    for (let sample = 0; sample < count; sample++) {
+      const index = Math.floor((sample * pixelCount) / count);
+      const value = sampleRaster(raster, [index % raster.width, Math.floor(index / raster.width)], {
+        bands: [band],
+        domain
+      }).values[0];
+      if (value === undefined || !Number.isFinite(value)) continue;
+      minimumValue = Math.min(minimumValue, value);
+      maximumValue = Math.max(maximumValue, value);
+      validCount++;
+    }
+    return {
+      band: raster.bands?.[band]?.index ?? band,
+      domain,
+      min: validCount ? minimumValue : undefined,
+      max: validCount ? maximumValue : undefined,
+      validCount,
+      scope: 'payload',
+      method: count === pixelCount ? 'exact' : 'sampled'
+    };
+  });
+}