@loaders.gl/tiles 4.4.5 → 5.0.0-alpha.2

package/src/point-cloud/types.ts

@@ -0,0 +1,82 @@
+// 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';
+
+/**
+ * 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;
+};
+
+/**
+ * A cartographic bounding volume for a point cloud tile.
+ */
+export type PointCloudBoundingVolume = {
+  cartographicBounds: [min: number[], max: number[]];
+  center: number[];
+  radius: number;
+};
+
+/**
+ * A source-owned tile header used by the point cloud tileset.
+ */
+export type PointCloudTileHeader = {
+  id: string;
+  level: number;
+  pointCount: number;
+  geometricError: number;
+  boundingVolume: PointCloudBoundingVolume;
+};
+
+/**
+ * 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,412 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import type {
+  GetRasterParameters,
+  RasterData,
+  RasterSource,
+  RasterSourceMetadata
+} from '@loaders.gl/loader-utils';
+
+/** Accepted raster request currently retained by {@link RasterSet}. */
+export type RasterSetRequest<
+  DataT extends RasterData = RasterData,
+  ParametersT extends GetRasterParameters = 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 RasterData = RasterData,
+  ParametersT extends GetRasterParameters = 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 RasterData = RasterData,
+  ParametersT extends GetRasterParameters = GetRasterParameters,
+  MetadataT extends RasterSourceMetadata = RasterSourceMetadata
+> = {
+  /** Callback used to load source metadata. */
+  getMetadata: () => 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 RasterData = RasterData,
+  ParametersT extends GetRasterParameters = GetRasterParameters,
+  MetadataT extends RasterSourceMetadata = RasterSourceMetadata
+> = Partial<RasterSetBaseProps<DataT, ParametersT, MetadataT>> & {
+  /** Optional loaders.gl raster source backing this manager. */
+  rasterSource?: RasterSource<DataT, ParametersT, MetadataT> | null;
+};
+
+/** Subscription callbacks emitted by {@link RasterSet}. */
+export type RasterSetListener<
+  DataT extends RasterData = RasterData,
+  ParametersT extends GetRasterParameters = 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 RasterData = RasterData,
+  ParametersT extends GetRasterParameters = 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 _lastAcceptedRequestId = -1;
+  private _nextRequestId = 0;
+  private _loadCounter = 0;
+  private _timeoutId: ReturnType<typeof setTimeout> | null = null;
+  private _abortController: AbortController | null = null;
+  private _finalized = false;
+
+  /** 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 RasterData = 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});
+  }
+
+  /** 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, 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 nextOptions = this._normalizeOptions({...this._opts, ...opts});
+    const sourceChanged =
+      previousRasterSource !== nextOptions.rasterSource ||
+      this._opts.getRaster !== nextOptions.getRaster ||
+      this._opts.getMetadata !== nextOptions.getMetadata;
+
+    this._opts = nextOptions;
+
+    if (sourceChanged) {
+      this._cancelScheduledRaster();
+      this.metadata = null;
+      this._currentRequest = null;
+      this._lastAcceptedRequestId = -1;
+      this._nextRequestId = 0;
+      this._emitUpdate();
+    }
+  }
+
+  /** Loads metadata from the current raster source or callbacks. */
+  async loadMetadata(): Promise<MetadataT> {
+    this._startLoading();
+    try {
+      const metadata = await this._opts.getMetadata();
+      if (this._finalized) {
+        return metadata;
+      }
+      this.metadata = metadata;
+      for (const listener of this._listeners) {
+        listener.onMetadataLoad?.(metadata);
+      }
+      this._emitUpdate();
+      return metadata;
+    } catch (error) {
+      const normalizedError = normalizeRasterSetError(error, 'Raster metadata request failed');
+      if (!this._finalized) {
+        for (const listener of this._listeners) {
+          listener.onMetadataLoadError?.(normalizedError);
+        }
+      }
+      throw normalizedError;
+    } finally {
+      this._finishLoading();
+    }
+  }
+
+  /** Debounces and issues a new raster request for the supplied parameters. */
+  requestRaster(parameters: ParametersT, debounceTime = this._opts.debounceTime): number {
+    if (!this.shouldRefetchRaster(parameters)) {
+      return this._currentRequest?.requestId ?? -1;
+    }
+
+    const requestId = this._nextRequestId++;
+    this._cancelScheduledRaster();
+
+    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._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;
+    }
+
+    this._startLoading();
+    for (const listener of this._listeners) {
+      listener.onRasterLoadStart?.(requestId, parameters);
+    }
+
+    try {
+      const abortController = new AbortController();
+      this._abortController = abortController;
+      const raster = await this._opts.getRaster({...parameters, signal: abortController.signal});
+      if (
+        this._finalized ||
+        abortController.signal.aborted ||
+        requestId <= this._lastAcceptedRequestId
+      ) {
+        return;
+      }
+
+      this._lastAcceptedRequestId = requestId;
+      this._currentRequest = {requestId, parameters, raster};
+
+      for (const listener of this._listeners) {
+        listener.onRasterLoad?.(this._currentRequest);
+      }
+      this._emitUpdate();
+    } catch (error) {
+      if (isAbortError(error)) {
+        return;
+      }
+      const normalizedError = normalizeRasterSetError(error, 'Raster request failed');
+      if (!this._finalized) {
+        for (const listener of this._listeners) {
+          listener.onRasterLoadError?.(requestId, normalizedError, parameters);
+        }
+      }
+    } finally {
+      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 ||
+        (() => {
+          if (rasterSource) {
+            return rasterSource.getMetadata();
+          }
+          return DEFAULT_RASTERSET_PROPS.getMetadata() as Promise<MetadataT>;
+        }),
+      getRaster:
+        opts.getRaster ||
+        ((parameters: ParametersT) => {
+          if (rasterSource) {
+            return rasterSource.getRaster(parameters);
+          }
+          return DEFAULT_RASTERSET_PROPS.getRaster(parameters) 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 {
+    for (const listener of this._listeners) {
+      listener.onUpdate?.();
+    }
+  }
+
+  /** Emits one loading-state transition to all subscribers. */
+  private _emitLoadingStateChange(isLoading: boolean): void {
+    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;
+  }
+}
+
+/** 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';
+}

package/src/tileset-2d/adapter.ts

@@ -0,0 +1,47 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import type {Matrix4} from '@math.gl/core';
+import type {Bounds, TileBoundingBox, TileIndex, ZRange} from './types';
+
+/** Traversal inputs required by a {@link Tileset2DAdapter}. */
+export type Tileset2DTraversalContext<ViewStateT> = {
+  /** Consumer-defined view state used by the adapter. */
+  viewState: ViewStateT;
+  /** Tile size in pixels. */
+  tileSize: number;
+  /** Bounding box limiting tile generation. */
+  extent?: Bounds | null;
+  /** Minimum zoom level to request. */
+  minZoom?: number;
+  /** Maximum zoom level to request. */
+  maxZoom?: number;
+  /** Integer zoom offset applied during tile selection. */
+  zoomOffset?: number;
+  /** Elevation range used during geospatial tile selection. */
+  zRange?: ZRange | null;
+  /** Optional model matrix applied by the surrounding layer stack. */
+  modelMatrix?: Matrix4 | null;
+  /** Inverse of the current model matrix. */
+  modelMatrixInverse?: Matrix4 | null;
+};
+
+/** Minimal tile metadata inputs required by a {@link Tileset2DAdapter}. */
+export type Tileset2DTileContext<ViewStateT> = {
+  /** Consumer-defined view state used by the adapter. */
+  viewState: ViewStateT;
+  /** Tile size in pixels. */
+  tileSize: number;
+};
+
+/** Adapter used by {@link Tileset2D} to compute traversal and tile bounds. */
+export type Tileset2DAdapter<ViewStateT> = {
+  /** Returns tile indices that should be selected for one traversal context. */
+  getTileIndices: (context: Tileset2DTraversalContext<ViewStateT>) => TileIndex[];
+  /** Returns the structured bounding box for one tile index. */
+  getTileBoundingBox: (
+    context: Tileset2DTileContext<ViewStateT>,
+    index: TileIndex
+  ) => TileBoundingBox;
+};

package/src/tileset-2d/index.ts

@@ -0,0 +1,33 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+export type {
+  Bounds,
+  GeoBoundingBox,
+  NonGeoBoundingBox,
+  TileBoundingBox,
+  TileIndex,
+  TileLoadProps,
+  ZRange
+} from './types';
+export type {
+  Tileset2DAdapter,
+  Tileset2DTileContext,
+  Tileset2DTraversalContext
+} from './adapter';
+export type {Tile2DLoadDataProps} from './tile-2d-header';
+export {SharedTile2DHeader} from './tile-2d-header';
+export type {
+  RefinementStrategy,
+  RefinementStrategyFunction,
+  Tileset2DBaseProps,
+  Tileset2DProps,
+  Tile2DListener
+} from './tileset-2d';
+export {
+  Tileset2D,
+  STRATEGY_DEFAULT,
+  STRATEGY_NEVER,
+  STRATEGY_REPLACE
+} from './tileset-2d';