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

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, Loader, LoaderOptions, 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: Loader<DataT>,
+    loadOptions: LoaderOptions
+  ): Promise<DataT> {
+    // Resolve root-relative URIs inside the archive rather than beside its download URL.
+    const resourceUrl = this.options.rootPath
+      ? `${stripQueryString(this.sourceUrl)}/${this.options.rootPath}`
+      : url;
+    return await this.parseArchiveResource(
+      resourceUrl,
+      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: Loader<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: Loader<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}`
+        : /^[a-z][a-z0-9+.-]*:\/\//i.test(baseWithoutQuery)
+          ? new URL(requestWithoutQuery, baseWithoutQuery).href
+          : 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 {
+  return url.split(/[?#]/, 1)[0];
+}

package/src/tileset-3d/common/tile-3d-contracts.ts

@@ -0,0 +1,115 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+/** Structural subset implemented by math.gl bounding volumes used by tile renderers. */
+export type Tile3DBoundingVolume = {
+  distanceSquaredTo?(point: unknown): number;
+  intersectPlane?(plane: unknown): number;
+};
+
+/** Renderer-neutral description of one ordered tile content entry. */
+export type Tile3DContent = {
+  /** Zero-based source order, stable across loading and unloading. */
+  index: number;
+  /** Resolved content URI when declared by the tileset. */
+  uri?: string;
+  /** Tileset group index declared by this content entry. */
+  group?: number;
+  /** Normalized tile content kind, when detected. */
+  type?: string;
+  /** Decoded payload, or null while unloaded/failed. */
+  payload: unknown;
+  /** Raw content metadata reference. */
+  metadata: Record<string, unknown> | null;
+  /** Transformed content volume, with tile-volume fallback. */
+  boundingVolume: Tile3DBoundingVolume | null;
+  /** Normalized feature-id declarations for this content. */
+  featureIds: Tile3DFeatureIdSet[];
+  /** Whether the payload can currently be rendered. */
+  renderable: boolean;
+};
+
+/** Renderer-neutral feature-id declaration from a tile content payload. */
+export type Tile3DFeatureIdSet = {
+  /** Source of the feature identifiers. */
+  source: 'attribute' | 'property-table' | 'constant' | 'texture' | 'implicit';
+  /** glTF attribute name for attribute-backed identifiers. */
+  attribute?: string;
+  /** Structural-metadata property-table index. */
+  propertyTable?: number;
+  /** Constant feature identifier. */
+  constant?: number;
+  /** Texture-backed identifier declaration, when present. */
+  texture?: Record<string, unknown>;
+  /** Implicit identifier declaration, when present. */
+  implicit?: Record<string, unknown>;
+  /** Decoded identifier values, when supplied by a content loader. */
+  values?: Uint32Array | Uint16Array | Uint8Array;
+  /** Unrecognized source fields preserved for forward compatibility. */
+  details?: Record<string, unknown>;
+};
+
+/** Raw metadata references inherited by a tile and its contents. */
+export type Tile3DMetadataContext = {
+  /** Tileset-level metadata entity. */
+  tileset?: Record<string, unknown> | null;
+  /** Group metadata entity selected for the tile's primary content. */
+  group?: Record<string, unknown> | null;
+  /** All tileset groups, used to resolve a selected content entry's group. */
+  groups?: readonly (Record<string, unknown> | null)[];
+  /** Tile metadata entity. */
+  tile?: Record<string, unknown> | null;
+  /** Content metadata entity. */
+  content?: Record<string, unknown> | null;
+  /** Implicit-subtree metadata entity. */
+  subtree?: Record<string, unknown> | null;
+};
+
+/** Extracts mesh-feature declarations from a decoded glTF-like payload. */
+export function getTile3DFeatureIdSets(payload: unknown): Tile3DFeatureIdSet[] {
+  const featureIdSets: Tile3DFeatureIdSet[] = [];
+  const visited = new Set<object>();
+  const visit = (value: unknown): void => {
+    if (!value || typeof value !== 'object') {
+      return;
+    }
+    if (visited.has(value as object)) {
+      return;
+    }
+    visited.add(value as object);
+    const record = value as Record<string, any>;
+    const declarations = record.extensions?.EXT_mesh_features?.featureIds;
+    if (Array.isArray(declarations)) {
+      for (const declaration of declarations) {
+        if (!declaration || typeof declaration !== 'object') {
+          continue;
+        }
+        const source = declaration.texture
+          ? 'texture'
+          : declaration.implicit
+            ? 'implicit'
+            : declaration.attribute !== undefined
+              ? 'attribute'
+              : declaration.propertyTable !== undefined
+                ? 'property-table'
+                : 'constant';
+        featureIdSets.push({
+          source,
+          attribute: declaration.attribute,
+          propertyTable: declaration.propertyTable,
+          constant: declaration.constant,
+          texture: declaration.texture,
+          implicit: declaration.implicit,
+          values: declaration.values,
+          details: declaration
+        });
+      }
+    }
+    for (const child of Object.values(record)) {
+      visit(child);
+    }
+  };
+  visit(payload);
+  return featureIdSets;
+}