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

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

@@ -0,0 +1,39 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+/** Inclusive minimum and maximum elevation bounds used during tile selection. */
+export type ZRange = [minZ: number, maxZ: number];
+
+/** Axis-aligned bounding box represented as `[minX, minY, maxX, maxY]`. */
+export type Bounds = [minX: number, minY: number, maxX: number, maxY: number];
+
+/** Geographic tile bounds in longitude/latitude coordinates. */
+export type GeoBoundingBox = {west: number; north: number; east: number; south: number};
+
+/** Cartesian tile bounds in layer/world coordinates. */
+export type NonGeoBoundingBox = {left: number; top: number; right: number; bottom: number};
+
+/** Tile bounds for either geospatial or cartesian views. */
+export type TileBoundingBox = NonGeoBoundingBox | GeoBoundingBox;
+
+/** Tile coordinate in an x/y/z pyramid. */
+export type TileIndex = {x: number; y: number; z: number};
+
+/** Information passed to a tile loader for fetching tile content. */
+export type TileLoadProps = {
+  /** x/y/z tile coordinate. */
+  index: TileIndex;
+  /** Stable cache identifier for the tile. */
+  id: string;
+  /** Bounds covered by the tile in the active coordinate system. */
+  bbox: TileBoundingBox;
+  /** URL derived from a URL template, if applicable. */
+  url?: string | null;
+  /** Abort signal for cancelling an in-flight tile request. */
+  signal?: AbortSignal;
+  /** Optional application metadata associated with the tile. */
+  userData?: Record<string, any>;
+  /** Resolved zoom level used to request this tile. */
+  zoom?: number;
+};

package/src/tileset-2d.ts

@@ -0,0 +1,5 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+export * from './tileset-2d/index';

package/src/tileset-3d/common/indexed-archive-tileset-source.ts

@@ -0,0 +1,205 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {BlobFile, HttpFile, path} from '@loaders.gl/loader-utils';
+import type {
+  CoreAPI,
+  LoaderOptions,
+  LoaderWithParser,
+  ReadableFile
+} from '@loaders.gl/loader-utils';
+import type {TilesetSourceResolver} from './tileset-source';
+
+/** Options for {@link IndexedArchiveTilesetSource}. */
+export type IndexedArchiveTilesetSourceOptions<ArchiveT> = {
+  /** Archive URL or Blob. */
+  data: string | Blob;
+  /** Filename to expose for Blob inputs that do not provide a name. */
+  fallbackFilename: string;
+  /** Archive file extension used as the URL path marker. */
+  archiveExtension: string;
+  /** Path to the root metadata resource inside the archive. */
+  rootPath: string;
+  /** Optional mode passed when loading the root metadata resource. */
+  rootMode?: string;
+  /** Parses an opened readable file into an indexed archive object. */
+  parseArchive: (file: ReadableFile) => Promise<ArchiveT>;
+  /** Loads one resource from the parsed archive. */
+  getFile: (archive: ArchiveT, pathInArchive: string, mode?: string) => Promise<ArrayBuffer>;
+  /** Returns the core API used for local file loading and nested resource parsing. */
+  getCoreApi: () => CoreAPI | undefined;
+  /** Error message to throw when the core API is required but unavailable. */
+  missingCoreApiMessage: string;
+};
+
+/**
+ * Tileset source resolver backed by an indexed archive such as 3TZ or SLPK.
+ *
+ * The source owns archive opening, archive caching, path resolution, and archive-backed `fetch`
+ * injection. Format-specific parsing and file lookup stay in the owning format module.
+ */
+export class IndexedArchiveTilesetSource<ArchiveT> implements TilesetSourceResolver {
+  /** URL exposed to the tileset source that owns this archive source. */
+  readonly sourceUrl: string;
+
+  private readonly options: IndexedArchiveTilesetSourceOptions<ArchiveT>;
+  private archivePromise?: Promise<ArchiveT>;
+
+  /**
+   * Creates an indexed archive tileset source.
+   * @param options Archive source options
+   */
+  constructor(options: IndexedArchiveTilesetSourceOptions<ArchiveT>) {
+    this.options = options;
+    this.sourceUrl = getArchiveSourceUrl(options.data, options.fallbackFilename);
+  }
+
+  /**
+   * Loads and parses the archive root metadata resource.
+   * @param url Root URL, ignored because the archive root path is configured explicitly
+   * @param loader Loader used to parse the root metadata
+   * @param loadOptions Loader options forwarded to parsing
+   */
+  async loadRoot<DataT>(
+    url: string,
+    loader: LoaderWithParser<DataT>,
+    loadOptions: LoaderOptions
+  ): Promise<DataT> {
+    return await this.parseArchiveResource(
+      url,
+      this.options.rootPath,
+      loader,
+      loadOptions,
+      this.options.rootMode
+    );
+  }
+
+  /**
+   * Loads and parses an archive resource relative to a requesting resource URL.
+   * @param url Resource URL
+   * @param loader Loader used to parse the resource
+   * @param loadOptions Loader options forwarded to parsing
+   */
+  async loadResource<DataT>(
+    url: string,
+    loader: LoaderWithParser<DataT>,
+    loadOptions: LoaderOptions
+  ): Promise<DataT> {
+    const pathInArchive = this.resolveArchivePath(url, url);
+    return await this.parseArchiveResource(url, pathInArchive, loader, loadOptions);
+  }
+
+  private async parseArchiveResource<DataT>(
+    resourceUrl: string,
+    pathInArchive: string,
+    loader: LoaderWithParser<DataT>,
+    loadOptions: LoaderOptions,
+    mode?: string
+  ): Promise<DataT> {
+    const coreApi = this.options.getCoreApi();
+    if (!coreApi) {
+      throw new Error(this.options.missingCoreApiMessage);
+    }
+
+    const data = await this.loadFile(pathInArchive, mode);
+    const archiveFetch = this.createArchiveFetch(resourceUrl);
+    return (await coreApi.parse(
+      data,
+      loader,
+      {
+        ...loadOptions,
+        fetch: archiveFetch
+      },
+      {
+        url: resourceUrl,
+        fetch: archiveFetch,
+        _parse: coreApi.parse,
+        loaders: [loader],
+        coreApi
+      } as any
+    )) as DataT;
+  }
+
+  private createArchiveFetch(contextUrl: string): typeof fetch {
+    return async (input: RequestInfo | URL): Promise<Response> => {
+      const requestUrl =
+        typeof input === 'string' ? input : input instanceof URL ? input.toString() : input.url;
+      const pathInArchive = this.resolveArchivePath(requestUrl, contextUrl);
+      const data = await this.loadFile(pathInArchive);
+      return new Response(data, {status: 200});
+    };
+  }
+
+  private async loadFile(pathInArchive: string, mode?: string): Promise<ArrayBuffer> {
+    this.archivePromise ||= this.openArchiveReadableFile().then(file =>
+      this.options.parseArchive(file)
+    );
+    const archive = await this.archivePromise;
+    return await this.options.getFile(archive, pathInArchive, mode);
+  }
+
+  private async openArchiveReadableFile(): Promise<ReadableFile> {
+    const {data} = this.options;
+    if (typeof data !== 'string') {
+      return new BlobFile(data);
+    }
+
+    if (/^https?:\/\//i.test(data)) {
+      return new HttpFile(data);
+    }
+
+    const coreApi = this.options.getCoreApi();
+    if (!coreApi) {
+      throw new Error(this.options.missingCoreApiMessage);
+    }
+    const response = await coreApi.fetchFile(data);
+    return new BlobFile(await response.arrayBuffer());
+  }
+
+  private resolveArchivePath(request: string, baseUrl: string): string {
+    const requestWithoutQuery = stripQueryString(request);
+    const archiveRoot = stripQueryString(this.sourceUrl);
+    const baseWithoutQuery = stripQueryString(baseUrl);
+    const basePath =
+      baseWithoutQuery === archiveRoot ? archiveRoot : path.dirname(baseWithoutQuery);
+    const markerExpression = new RegExp(`\\.${this.options.archiveExtension}/(.*)$`, 'i');
+    const markerMatch = requestWithoutQuery.match(markerExpression);
+    if (markerMatch?.[1]) {
+      return markerMatch[1];
+    }
+
+    const isAbsoluteRequest =
+      /^[a-z][a-z0-9+.-]*:/i.test(requestWithoutQuery) || requestWithoutQuery.startsWith('/');
+    const absoluteRequest = requestWithoutQuery.startsWith(archiveRoot)
+      ? requestWithoutQuery
+      : baseWithoutQuery === archiveRoot && !isAbsoluteRequest
+        ? `${archiveRoot}/${requestWithoutQuery}`
+        : path.resolve(basePath, requestWithoutQuery);
+
+    if (absoluteRequest === archiveRoot) {
+      return '';
+    }
+
+    if (absoluteRequest.startsWith(`${archiveRoot}/`)) {
+      return absoluteRequest.slice(archiveRoot.length + 1);
+    }
+
+    return absoluteRequest.replace(/^\/+/, '');
+  }
+}
+
+function getArchiveSourceUrl(data: string | Blob, fallbackFilename: string): string {
+  if (typeof data === 'string') {
+    return data;
+  }
+
+  const fileName =
+    'name' in data && typeof data.name === 'string' && data.name ? data.name : fallbackFilename;
+  return `memory://${fileName}`;
+}
+
+function stripQueryString(url: string): string {
+  const queryIndex = url.indexOf('?');
+  return queryIndex >= 0 ? url.slice(0, queryIndex) : url;
+}