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

package/src/point-cloud/types.ts

@@ -0,0 +1,99 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import type {DataSource, DataSourceOptions} from '@loaders.gl/loader-utils';
+import type {MeshArrowTable} from '@loaders.gl/schema';
+import type {TilesetSpatialReference} from '../spatial/spatial-types';
+
+/**
+ * An accessor-like description for point cloud attributes.
+ */
+export type PointCloudAttribute = {
+  value: ArrayBufferView;
+  size: number;
+  normalized?: boolean;
+};
+
+/**
+ * deck.gl coordinate system string values accepted by point cloud tile content.
+ */
+export type PointCloudCoordinateSystem =
+  | 'default'
+  | 'lnglat'
+  | 'meter-offsets'
+  | 'lnglat-offsets'
+  | 'cartesian';
+
+/**
+ * A normalized point cloud tile content payload.
+ */
+export type PointCloudTileContent = {
+  data: MeshArrowTable;
+  pointCount: number;
+  cartographicOrigin: number[];
+  coordinateSystem: PointCloudCoordinateSystem;
+  constantRGBA?: number[];
+  modelMatrix?: number[] | Float32Array;
+  /** Spatial descriptor for returned points, origins, and bounds. */
+  spatialReference?: TilesetSpatialReference;
+  /** Content bound expressed in the selected spatial output frame. */
+  spatialBoundingVolume?: PointCloudBoundingVolume;
+};
+
+/**
+ * A cartographic bounding volume for a point cloud tile.
+ */
+export type PointCloudBoundingVolume = {
+  cartographicBounds: [min: number[], max: number[]];
+  /** True when the longitude interval crosses the antimeridian. */
+  wrapsDateline?: boolean;
+  /** True when the longitude interval covers the full globe. */
+  coversFullLongitude?: boolean;
+  center: number[];
+  radius: number;
+  /** Broad coordinate frame of `center` and `cartographicBounds`. */
+  coordinateFrame?: 'geographic' | 'cartesian';
+};
+
+/**
+ * A source-owned tile header used by the point cloud tileset.
+ */
+export type PointCloudTileHeader = {
+  id: string;
+  level: number;
+  pointCount: number;
+  geometricError: number;
+  boundingVolume: PointCloudBoundingVolume;
+  /** Bound expressed in the selected content/output frame; traversal retains geographic bounds. */
+  spatialBoundingVolume?: PointCloudBoundingVolume;
+  /** I3S LOD metric used to decide whether this node refines. */
+  lodSelectionMetricType?: 'maxScreenThresholdSQ' | 'density-threshold';
+  /** Source-provided LOD threshold for density or screen metrics. */
+  lodThreshold?: number;
+};
+
+/**
+ * Optional tileset view metadata.
+ */
+export type PointCloudTilesetViewState = {
+  cartographicCenter?: number[];
+  zoom?: number;
+  boundingVolume?: PointCloudBoundingVolume;
+};
+
+/**
+ * Structural contract for point cloud sources that can back a PointCloudTileset.
+ */
+export type PointCloudTilesetSource<
+  DataT = unknown,
+  OptionsT extends DataSourceOptions = DataSourceOptions
+> = DataSource<DataT, OptionsT> & {
+  isReady: boolean;
+  initialize(): Promise<void>;
+  getMetadata?(): Promise<unknown>;
+  getRootTile(): Promise<PointCloudTileHeader>;
+  getChildren(tile: PointCloudTileHeader): Promise<PointCloudTileHeader[]>;
+  loadTileContent(tile: PointCloudTileHeader): Promise<PointCloudTileContent | null>;
+  getViewState?(): Promise<PointCloudTilesetViewState> | PointCloudTilesetViewState;
+};

package/src/raster-set.ts

@@ -0,0 +1,504 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+
+import type {
+  GetRasterParameters,
+  NumericRasterData,
+  RasterData,
+  RasterSource,
+  RasterSourceMetadata
+} from '@loaders.gl/loader-utils';
+import {waitForPromiseWithSignals} from '@loaders.gl/loader-utils';
+
+/** Accepted raster request currently retained by {@link RasterSet}. */
+export type RasterSetRequest<
+  DataT extends NumericRasterData = RasterData,
+  ParametersT extends object = GetRasterParameters
+> = {
+  /** Unique request id assigned by the manager. */
+  requestId: number;
+  /** Raster request parameters that produced the accepted raster payload. */
+  parameters: ParametersT;
+  /** Raster retained as the current output. */
+  raster: DataT;
+};
+
+/** Arguments supplied to {@link RasterSetBaseProps.shouldRefetch}. */
+export type RasterSetShouldRefetchArgs<
+  DataT extends NumericRasterData = RasterData,
+  ParametersT extends object = GetRasterParameters,
+  MetadataT extends RasterSourceMetadata = RasterSourceMetadata
+> = {
+  /** Current accepted request retained by the raster manager, if any. */
+  currentRequest: RasterSetRequest<DataT, ParametersT> | null;
+  /** Source metadata resolved by {@link RasterSet.loadMetadata}, if available. */
+  metadata: MetadataT | null;
+  /** Candidate raster request parameters under evaluation. */
+  nextParameters: ParametersT;
+};
+
+/** Configuration shared by all {@link RasterSet} instances. */
+export type RasterSetBaseProps<
+  DataT extends NumericRasterData = RasterData,
+  ParametersT extends object = GetRasterParameters,
+  MetadataT extends RasterSourceMetadata = RasterSourceMetadata
+> = {
+  /** Callback used to load source metadata. */
+  getMetadata: (options?: {
+    /** Metadata request cancellation. */ signal?: AbortSignal;
+  }) => Promise<MetadataT>;
+  /** Callback used to load raster data for a viewport-derived request. */
+  getRaster: (parameters: ParametersT) => Promise<DataT>;
+  /** Debounce interval applied before issuing raster requests. */
+  debounceTime?: number;
+  /** Optional policy callback that can skip redundant raster requests. */
+  shouldRefetch?: (args: RasterSetShouldRefetchArgs<DataT, ParametersT, MetadataT>) => boolean;
+};
+
+/** Options for creating a {@link RasterSet}. */
+export type RasterSetProps<
+  DataT extends NumericRasterData = RasterData,
+  ParametersT extends object = GetRasterParameters,
+  MetadataT extends RasterSourceMetadata = RasterSourceMetadata
+> = Partial<RasterSetBaseProps<DataT, ParametersT, MetadataT>> & {
+  /** Optional loaders.gl raster source backing this manager. */
+  rasterSource?: RasterSource<DataT, ParametersT & GetRasterParameters, MetadataT> | null;
+};
+
+/** Subscription callbacks emitted by {@link RasterSet}. */
+export type RasterSetListener<
+  DataT extends NumericRasterData = RasterData,
+  ParametersT extends object = GetRasterParameters,
+  MetadataT extends RasterSourceMetadata = RasterSourceMetadata
+> = {
+  /** Fired when metadata/raster loading starts or stops. */
+  onLoadingStateChange?: (isLoading: boolean) => void;
+  /** Fired when source metadata resolves successfully. */
+  onMetadataLoad?: (metadata: MetadataT) => void;
+  /** Fired when metadata loading fails. */
+  onMetadataLoadError?: (error: Error) => void;
+  /** Fired when a new raster request is issued. */
+  onRasterLoadStart?: (requestId: number, parameters: ParametersT) => void;
+  /** Fired when a raster request resolves and becomes current. */
+  onRasterLoad?: (request: RasterSetRequest<DataT, ParametersT>) => void;
+  /** Fired when a raster request fails. */
+  onRasterLoadError?: (requestId: number, error: Error, parameters: ParametersT) => void;
+  /** Fired when metadata or the current raster changes. */
+  onUpdate?: () => void;
+};
+
+const DEFAULT_RASTERSET_PROPS: Required<Omit<RasterSetProps, 'rasterSource'>> = {
+  getMetadata: async () => ({
+    width: 0,
+    height: 0,
+    bandCount: 0,
+    dtype: 'uint8'
+  }),
+  getRaster: async () =>
+    ({
+      data: new Uint8Array(0),
+      width: 0,
+      height: 0,
+      bandCount: 0,
+      dtype: 'uint8'
+    }) as never,
+  debounceTime: 0,
+  shouldRefetch: () => true
+};
+
+/**
+ * Shared raster request manager used by viewport-driven raster examples and layers.
+ *
+ * @typeParam DataT Raster payload retained by the manager.
+ * @typeParam ParametersT Request parameters accepted by the source.
+ * @typeParam MetadataT Metadata returned by the source.
+ */
+export class RasterSet<
+  DataT extends NumericRasterData = RasterData,
+  ParametersT extends object = GetRasterParameters,
+  MetadataT extends RasterSourceMetadata = RasterSourceMetadata
+> {
+  /** Cached metadata returned by the backing source, if any. */
+  metadata: MetadataT | null = null;
+
+  private _opts: Required<RasterSetProps<DataT, ParametersT, MetadataT>>;
+  private _listeners = new Set<RasterSetListener<DataT, ParametersT, MetadataT>>();
+  private _currentRequest: RasterSetRequest<DataT, ParametersT> | null = null;
+  private _nextRequestId = 0;
+  private _loadCounter = 0;
+  private _timeoutId: ReturnType<typeof setTimeout> | null = null;
+  private _abortController: AbortController | null = null;
+  /** Controller owned by the newest metadata request. */
+  private _metadataAbortController: AbortController | null = null;
+  private _finalized = false;
+  /** Generation invalidates metadata from replaced sources. */
+  private _sourceGeneration = 0;
+  /** Monotonic metadata request identity. */
+  private _metadataRequestId = 0;
+
+  /** Creates a raster manager from a source or direct callbacks. */
+  constructor(opts: RasterSetProps<DataT, ParametersT, MetadataT>) {
+    this._opts = this._normalizeOptions(opts);
+    if (!this._opts.rasterSource && (!opts.getRaster || !opts.getMetadata)) {
+      throw new Error(
+        'RasterSet requires either `rasterSource` or both `getRaster` and `getMetadata`.'
+      );
+    }
+  }
+
+  /** Convenience factory for wrapping a loaders.gl {@link RasterSource}. */
+  static fromRasterSource<
+    DataT extends NumericRasterData = RasterData,
+    ParametersT extends GetRasterParameters = GetRasterParameters,
+    MetadataT extends RasterSourceMetadata = RasterSourceMetadata
+  >(
+    rasterSource: RasterSource<DataT, ParametersT, MetadataT>,
+    opts: Omit<
+      RasterSetProps<DataT, ParametersT, MetadataT>,
+      'rasterSource' | 'getRaster' | 'getMetadata'
+    > = {}
+  ): RasterSet<DataT, ParametersT, MetadataT> {
+    return new RasterSet<DataT, ParametersT, MetadataT>({...opts, rasterSource});
+  }
+
+  /** Convenience factory for sources whose requests are not viewport-shaped. */
+  static fromCallbacks<
+    DataT extends NumericRasterData = RasterData,
+    ParametersT extends object = GetRasterParameters,
+    MetadataT extends RasterSourceMetadata = RasterSourceMetadata
+  >(
+    opts: RasterSetBaseProps<DataT, ParametersT, MetadataT>
+  ): RasterSet<DataT, ParametersT, MetadataT> {
+    return new RasterSet<DataT, ParametersT, MetadataT>(opts);
+  }
+
+  /** Whether the manager has no requests in flight and a current raster. */
+  get isLoaded(): boolean {
+    return this._loadCounter === 0 && Boolean(this._currentRequest);
+  }
+
+  /** Current accepted raster, if any. */
+  get raster(): DataT | null {
+    return this._currentRequest?.raster || null;
+  }
+
+  /** Current accepted request and raster payload, if any. */
+  get currentRequest(): RasterSetRequest<DataT, ParametersT> | null {
+    return this._currentRequest;
+  }
+
+  /** Backing raster source when constructed from one. */
+  get rasterSource(): RasterSource<DataT, ParametersT & GetRasterParameters, MetadataT> | null {
+    return this._opts.rasterSource;
+  }
+
+  /** Subscribes to metadata and raster lifecycle events. */
+  subscribe(listener: RasterSetListener<DataT, ParametersT, MetadataT>): () => void {
+    this._listeners.add(listener);
+    return () => this._listeners.delete(listener);
+  }
+
+  /** Updates source callbacks or debounce settings, resetting state when the source changes. */
+  setOptions(opts: RasterSetProps<DataT, ParametersT, MetadataT>): void {
+    const previousRasterSource = this._opts.rasterSource;
+    const mergedOptions: RasterSetProps<DataT, ParametersT, MetadataT> = {...this._opts, ...opts};
+    if (opts.rasterSource && opts.rasterSource !== previousRasterSource) {
+      mergedOptions.getRaster = opts.getRaster;
+      mergedOptions.getMetadata = opts.getMetadata;
+    }
+    const nextOptions = this._normalizeOptions(mergedOptions);
+    const sourceChanged =
+      previousRasterSource !== nextOptions.rasterSource ||
+      this._opts.getRaster !== nextOptions.getRaster ||
+      this._opts.getMetadata !== nextOptions.getMetadata;
+
+    this._opts = nextOptions;
+
+    if (sourceChanged) {
+      this._cancelScheduledRaster();
+      this._abortActiveRequest();
+      this._metadataAbortController?.abort();
+      this._sourceGeneration++;
+      this.metadata = null;
+      this._currentRequest = null;
+
+      this._emitUpdate();
+    }
+  }
+
+  /** Loads metadata from the current raster source or callbacks. */
+  async loadMetadata(
+    options: {/** Caller cancellation for metadata. */ signal?: AbortSignal} = {}
+  ): Promise<MetadataT> {
+    if (this._finalized) throw new Error('RasterSet is finalized');
+    options.signal?.throwIfAborted();
+    this._metadataAbortController?.abort();
+    const abortController = new AbortController();
+    this._metadataAbortController = abortController;
+    const abortFromCaller = () => abortController.abort(options.signal?.reason);
+    options.signal?.addEventListener('abort', abortFromCaller, {once: true});
+    const metadataRequestId = ++this._metadataRequestId;
+    const generation = this._sourceGeneration;
+    try {
+      this._startLoading();
+      abortController.signal.throwIfAborted();
+      const metadata = await waitForPromiseWithSignals(
+        signal => this._opts.getMetadata({signal}),
+        [abortController.signal]
+      );
+      abortController.signal.throwIfAborted();
+      if (
+        this._finalized ||
+        generation !== this._sourceGeneration ||
+        metadataRequestId !== this._metadataRequestId
+      ) {
+        return metadata;
+      }
+      this.metadata = metadata;
+      for (const listener of this._listeners) {
+        listener.onMetadataLoad?.(metadata);
+      }
+      this._emitUpdate();
+      return metadata;
+    } catch (error) {
+      if (abortController.signal.aborted) throw abortController.signal.reason;
+      if (isAbortError(error)) throw error;
+      const normalizedError = normalizeRasterSetError(error, 'Raster metadata request failed');
+      if (
+        !this._finalized &&
+        generation === this._sourceGeneration &&
+        metadataRequestId === this._metadataRequestId
+      ) {
+        for (const listener of this._listeners) {
+          listener.onMetadataLoadError?.(normalizedError);
+        }
+      }
+      throw normalizedError;
+    } finally {
+      options.signal?.removeEventListener('abort', abortFromCaller);
+      if (this._metadataAbortController === abortController) this._metadataAbortController = null;
+      this._finishLoading();
+    }
+  }
+
+  /** Debounces and issues a new raster request for the supplied parameters. */
+  requestRaster(parameters: ParametersT, debounceTime = this._opts.debounceTime): number {
+    if (this._finalized) return -1;
+    if (!this.shouldRefetchRaster(parameters)) {
+      this._cancelScheduledRaster();
+      this._abortActiveRequest();
+      this._nextRequestId++;
+      return this._currentRequest?.requestId ?? -1;
+    }
+
+    const requestId = this._nextRequestId++;
+    this._cancelScheduledRaster();
+    this._abortActiveRequest();
+
+    if (debounceTime > 0) {
+      this._timeoutId = setTimeout(() => {
+        this._timeoutId = null;
+        void this._loadRaster(requestId, parameters);
+      }, debounceTime);
+    } else {
+      void this._loadRaster(requestId, parameters);
+    }
+
+    return requestId;
+  }
+
+  /** Returns `true` when the supplied parameters warrant a new raster fetch. */
+  shouldRefetchRaster(parameters: ParametersT): boolean {
+    return this._opts.shouldRefetch({
+      currentRequest: this._currentRequest,
+      metadata: this.metadata,
+      nextParameters: parameters
+    });
+  }
+
+  /** Clears timers and listeners held by the manager. */
+  finalize(): void {
+    this._finalized = true;
+    this._cancelScheduledRaster();
+    this._abortActiveRequest();
+    this._metadataAbortController?.abort();
+    this._metadataAbortController = null;
+    this._loadCounter = 0;
+    this._listeners.clear();
+  }
+
+  /** Loads a raster immediately and accepts it only if it is the newest completed request. */
+  private async _loadRaster(requestId: number, parameters: ParametersT): Promise<void> {
+    if (this._finalized) {
+      return;
+    }
+
+    const callerSignal = (parameters as {signal?: AbortSignal}).signal;
+    if (callerSignal?.aborted) return;
+    const abortController = new AbortController();
+    this._abortController = abortController;
+    const abortFromCaller = () => abortController.abort(callerSignal?.reason);
+    callerSignal?.addEventListener('abort', abortFromCaller, {once: true});
+    this._startLoading();
+    try {
+      abortController.signal.throwIfAborted();
+      for (const listener of this._listeners) listener.onRasterLoadStart?.(requestId, parameters);
+      abortController.signal.throwIfAborted();
+      const raster = await waitForPromiseWithSignals(
+        signal => this._opts.getRaster(withAbortSignal(parameters, signal)),
+        [abortController.signal]
+      );
+      if (
+        this._finalized ||
+        abortController.signal.aborted ||
+        requestId !== this._nextRequestId - 1
+      ) {
+        return;
+      }
+
+      this._currentRequest = {requestId, parameters, raster};
+
+      for (const listener of this._listeners) {
+        listener.onRasterLoad?.(this._currentRequest);
+      }
+      this._emitUpdate();
+    } catch (error) {
+      if (abortController.signal.aborted || isAbortError(error)) {
+        return;
+      }
+      const normalizedError = normalizeRasterSetError(error, 'Raster request failed');
+      if (!this._finalized && requestId === this._nextRequestId - 1) {
+        for (const listener of this._listeners) {
+          listener.onRasterLoadError?.(requestId, normalizedError, parameters);
+        }
+      }
+    } finally {
+      callerSignal?.removeEventListener('abort', abortFromCaller);
+      if (this._abortController === abortController) this._abortController = null;
+      this._finishLoading();
+    }
+  }
+
+  /** Resolves current options from either a source or direct callbacks. */
+  private _normalizeOptions(
+    opts: RasterSetProps<DataT, ParametersT, MetadataT>
+  ): Required<RasterSetProps<DataT, ParametersT, MetadataT>> {
+    const rasterSource = opts.rasterSource || null;
+    return {
+      ...DEFAULT_RASTERSET_PROPS,
+      ...opts,
+      rasterSource,
+      getMetadata:
+        opts.getMetadata ||
+        (options => {
+          if (rasterSource) {
+            return rasterSource.getMetadata(options);
+          }
+          return DEFAULT_RASTERSET_PROPS.getMetadata() as Promise<MetadataT>;
+        }),
+      getRaster:
+        opts.getRaster ||
+        ((parameters: ParametersT) => {
+          if (rasterSource) {
+            return rasterSource.getRaster(parameters as ParametersT & GetRasterParameters);
+          }
+          return DEFAULT_RASTERSET_PROPS.getRaster(
+            parameters as GetRasterParameters
+          ) as Promise<DataT>;
+        }),
+      debounceTime: opts.debounceTime ?? DEFAULT_RASTERSET_PROPS.debounceTime,
+      shouldRefetch:
+        (opts.shouldRefetch as
+          | ((args: RasterSetShouldRefetchArgs<DataT, ParametersT, MetadataT>) => boolean)
+          | undefined) ||
+        ((args: RasterSetShouldRefetchArgs<DataT, ParametersT, MetadataT>) =>
+          DEFAULT_RASTERSET_PROPS.shouldRefetch(args as RasterSetShouldRefetchArgs))
+    };
+  }
+
+  /** Emits one generic update notification to all subscribers. */
+  private _emitUpdate(): void {
+    if (this._finalized) return;
+    for (const listener of this._listeners) {
+      listener.onUpdate?.();
+    }
+  }
+
+  /** Emits one loading-state transition to all subscribers. */
+  private _emitLoadingStateChange(isLoading: boolean): void {
+    if (this._finalized) return;
+    for (const listener of this._listeners) {
+      listener.onLoadingStateChange?.(isLoading);
+    }
+  }
+
+  /** Increments the active load count and emits loading-state transitions. */
+  private _startLoading(): void {
+    const wasLoading = this._loadCounter > 0;
+    this._loadCounter++;
+    if (!wasLoading) {
+      this._emitLoadingStateChange(true);
+      this._emitUpdate();
+    }
+  }
+
+  /** Decrements the active load count and emits loading-state transitions. */
+  private _finishLoading(): void {
+    const wasLoading = this._loadCounter > 0;
+    this._loadCounter = Math.max(0, this._loadCounter - 1);
+    if (wasLoading && this._loadCounter === 0) {
+      this._emitLoadingStateChange(false);
+      this._emitUpdate();
+    }
+  }
+
+  /** Clears any pending debounced raster request before it hits the network. */
+  private _cancelScheduledRaster(): void {
+    if (this._timeoutId !== null) {
+      clearTimeout(this._timeoutId);
+      this._timeoutId = null;
+    }
+  }
+
+  /** Aborts the currently active raster request, if one exists. */
+  private _abortActiveRequest(): void {
+    this._abortController?.abort();
+    this._abortController = null;
+  }
+}
+
+/** Adds cancellation to a request while preserving its array/prototype shape. */
+function withAbortSignal<ParametersT extends object>(
+  parameters: ParametersT,
+  signal: AbortSignal
+): ParametersT {
+  const descriptors = Object.getOwnPropertyDescriptors(parameters);
+  delete descriptors.signal;
+  const request = Array.isArray(parameters)
+    ? Object.defineProperties(parameters.slice(), descriptors)
+    : Object.create(Object.getPrototypeOf(parameters), descriptors);
+  Object.defineProperty(request, 'signal', {
+    configurable: true,
+    enumerable: true,
+    value: signal,
+    writable: true
+  });
+  return request as ParametersT;
+}
+
+/** Normalizes arbitrary thrown values to `Error` instances for raster-set callbacks. */
+function normalizeRasterSetError(error: unknown, message: string): Error {
+  if (error instanceof Error) {
+    return error;
+  }
+  if (typeof error === 'string') {
+    return new Error(error);
+  }
+  return new Error(message);
+}
+
+/** Returns true when an error came from an aborted request. */
+function isAbortError(error: unknown): boolean {
+  return error instanceof Error && error.name === 'AbortError';
+}