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

package/src/mlt/mlt-format.ts

@@ -0,0 +1,19 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import type {Format} from '@loaders.gl/core/loader-utils';
+
+/**
+ * Loader format descriptor for the MapLibre Tile (MLT) format
+ */
+export const MLTFormat = {
+  name: 'MapLibre Tile',
+  id: 'mlt',
+  module: 'tiles',
+  encoding: 'binary',
+  format: 'mlt',
+  extensions: ['mlt'],
+  mimeTypes: ['application/vnd.maplibre-tile'],
+  category: 'geometry'
+} as const satisfies Format;

package/src/mlt/mlt-loader-with-parser.ts

@@ -0,0 +1,57 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import type {Loader, LoaderWithParser, LoaderOptions} from '@loaders.gl/core/loader-utils';
+import type {GeoArrowEncodingPreference} from '@loaders.gl/core/schema';
+import {parseMLT} from './lib/parse-mlt';
+import {MLTWorkerLoader as MLTWorkerLoaderMetadata} from './mlt-loader';
+import {MLTLoader as MLTLoaderMetadata} from './mlt-loader';
+
+const {preload: _MLTWorkerLoaderPreload, ...MLTWorkerLoaderMetadataWithoutPreload} =
+  MLTWorkerLoaderMetadata;
+const {preload: _MLTLoaderPreload, ...MLTLoaderMetadataWithoutPreload} = MLTLoaderMetadata;
+
+export type MLTLoaderOptions = LoaderOptions & {
+  /** Preferred encoding for Arrow geometry output. */
+  geoarrow?: {encodingPreference?: GeoArrowEncodingPreference};
+  mlt?: {
+    /** Shape of returned data */
+    shape?: 'geojson-table' | 'binary-geometry' | 'arrow-table';
+    /** `wgs84`: coordinates in longitude/latitude. `local` coordinates are `0-1` from tile origin */
+    coordinates?: 'wgs84' | 'local';
+    /** An object containing tile index values (`x`, `y`, `z`) to reproject features' coordinates into WGS84. Mandatory with `wgs84` coordinates option. */
+    tileIndex?: {x: number; y: number; z: number};
+    /** If provided, the layer name of each feature is added to `feature.properties[layerProperty]`. */
+    layerProperty?: string;
+    /** Layer filter. If provided, only features belonging to the named layers will be included; otherwise features from all layers are returned. */
+    layers?: string[];
+    /** Preferred encoding for Arrow geometry output. */
+    geoarrow?: {encodingPreference?: GeoArrowEncodingPreference};
+  };
+};
+
+/** Default options for the MLT loader */
+export const MLT_DEFAULT_OPTIONS = {
+  shape: 'arrow-table' as const,
+  coordinates: 'local' as const,
+  layerProperty: 'layerName' as const
+};
+
+/**
+ * Worker loader for the MapLibre Tile (MLT) format
+ */
+export const MLTWorkerLoaderWithParser = {
+  ...MLTWorkerLoaderMetadataWithoutPreload
+} as const satisfies Loader<any, never, MLTLoaderOptions>;
+
+/**
+ * Loader for the MapLibre Tile (MLT) format
+ */
+export const MLTLoaderWithParser = {
+  ...MLTLoaderMetadataWithoutPreload,
+  parse: async (arrayBuffer: ArrayBuffer, options?: MLTLoaderOptions) =>
+    parseMLT(arrayBuffer, options),
+  parseSync: (arrayBuffer: ArrayBuffer, options?: MLTLoaderOptions) =>
+    parseMLT(arrayBuffer, options)
+} as const satisfies LoaderWithParser<any, never, MLTLoaderOptions>;

package/src/mlt/mlt-loader.ts

@@ -0,0 +1,64 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import type {Loader, LoaderOptions} from '@loaders.gl/core/loader-utils';
+import type {GeoArrowEncodingPreference} from '@loaders.gl/core/schema';
+import {MLTFormat} from './mlt-format';
+
+// __VERSION__ is injected by babel-plugin-version-inline
+// @ts-ignore TS2304: Cannot find name '__VERSION__'.
+const VERSION = typeof __VERSION__ !== 'undefined' ? __VERSION__ : 'latest';
+
+export type MLTLoaderOptions = LoaderOptions & {
+  /** Preferred encoding for Arrow geometry output. */
+  geoarrow?: {encodingPreference?: GeoArrowEncodingPreference};
+  mlt?: {
+    /** Shape of returned data */
+    shape?: 'geojson-table' | 'binary-geometry' | 'arrow-table';
+    /** `wgs84`: coordinates in longitude/latitude. `local` coordinates are `0-1` from tile origin */
+    coordinates?: 'wgs84' | 'local';
+    /** An object containing tile index values (`x`, `y`, `z`) to reproject features' coordinates into WGS84. Mandatory with `wgs84` coordinates option. */
+    tileIndex?: {x: number; y: number; z: number};
+    /** If provided, the layer name of each feature is added to `feature.properties[layerProperty]`. */
+    layerProperty?: string;
+    /** Layer filter. If provided, only features belonging to the named layers will be included; otherwise features from all layers are returned. */
+    layers?: string[];
+    /** Preferred encoding for Arrow geometry output. */
+    geoarrow?: {encodingPreference?: GeoArrowEncodingPreference};
+  };
+};
+
+/** Default options for the MLT loader */
+export const MLT_DEFAULT_OPTIONS = {
+  shape: 'arrow-table' as const,
+  coordinates: 'local' as const,
+  layerProperty: 'layerName' as const
+};
+
+/** Preloads the parser-bearing MLT loader implementation. */
+async function preload() {
+  const {MLTLoaderWithParser} = await import('./mlt-loader-with-parser');
+  return MLTLoaderWithParser;
+}
+
+/** Metadata-only worker loader for the MapLibre Tile (MLT) format. */
+export const MLTLoader = {
+  ...MLTFormat,
+  dataType: null as any,
+  batchType: null as never,
+  version: VERSION,
+  worker: false,
+  binary: true,
+  options: {
+    mlt: {
+      ...MLT_DEFAULT_OPTIONS,
+      layers: undefined!,
+      tileIndex: undefined!
+    }
+  },
+  preload
+} as const satisfies Loader<any, never, MLTLoaderOptions>;
+
+/** @deprecated Use MLTLoader. */
+export const MLTWorkerLoader = MLTLoader;

package/src/mlt/mlt-source-loader.ts

@@ -0,0 +1,266 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import type {
+  CoreAPI,
+  SourceLoader,
+  VectorTileSource,
+  GetTileParameters,
+  GetTileDataParameters
+} from '@loaders.gl/core/loader-utils';
+import type {
+  ArrowTable,
+  BinaryFeatureCollection,
+  Feature,
+  Schema,
+  GeoArrowEncodingPreference
+} from '@loaders.gl/core/schema';
+import {TileSourceMetadata, DataSource, DataSourceOptions} from '@loaders.gl/core/loader-utils';
+import type {MLTLoaderOptions} from './mlt-loader';
+import {MLTFormat} from './mlt-format';
+
+export type MLTSourceLoaderOptions = DataSourceOptions &
+  MLTLoaderOptions & {
+    /** Preferred encoding for Arrow geometry output. */
+    geoarrow?: {encodingPreference?: GeoArrowEncodingPreference};
+    mlt?: {
+      /** Optional metadata URL. */
+      metadataUrl?: string | null;
+      /** Override file extension (default: `.mlt`). */
+      extension?: string;
+      /** Coordinates for parsed tile geometries. */
+      coordinates?: 'wgs84' | 'local';
+      /** Shape of returned data. */
+      shape?: 'geojson-table' | 'binary-geometry' | 'arrow-table';
+      /** Optional layer filter. */
+      layers?: string[];
+    };
+  };
+
+/**
+ * Source factory for MapLibre Tile (`.mlt`) tiles
+ */
+export const MLTSourceLoader = {
+  dataType: null as unknown as MLTTileSource,
+  batchType: null as never,
+  ...MLTFormat,
+  name: 'MLTTileSource',
+  version: '0.0.0',
+  type: 'mlt',
+  fromUrl: true,
+  fromBlob: false,
+
+  options: {
+    mlt: {
+      extension: '.mlt',
+      metadataUrl: null,
+      coordinates: 'wgs84',
+      shape: 'arrow-table',
+      layers: undefined!
+    }
+  },
+
+  defaultOptions: {
+    mlt: {
+      extension: '.mlt',
+      metadataUrl: null,
+      coordinates: 'wgs84',
+      shape: 'arrow-table',
+      layers: undefined!
+    }
+  },
+
+  testURL: (url: string): boolean =>
+    url.endsWith('.mlt') || url.endsWith('/plain') || isURLTemplate(url),
+  createDataSource: (
+    url: string,
+    options: MLTSourceLoaderOptions,
+    coreApi?: CoreAPI
+  ): MLTTileSource => new MLTTileSource(url, options, coreApi)
+} as const satisfies SourceLoader<MLTTileSource>;
+
+/**
+ * Vector tile source for MapLibre Tile files served by `z/x/y` tile services.
+ */
+export class MLTTileSource
+  extends DataSource<string, MLTSourceLoaderOptions>
+  implements VectorTileSource
+{
+  readonly metadataUrl: string | null;
+  schema: 'tms' | 'xyz' | 'template' = 'tms';
+  metadata: Promise<TileSourceMetadata>;
+  extension: string;
+  mimeType = 'application/vnd.maplibre-tile';
+
+  constructor(url: string, options: MLTSourceLoaderOptions, coreApi?: CoreAPI) {
+    super(url, options, MLTSourceLoader.defaultOptions, coreApi);
+    this.metadataUrl = this.options.mlt?.metadataUrl || null;
+    this.extension = this.options.mlt?.extension || '.mlt';
+
+    this.getTileData = this.getTileData.bind(this);
+    this.metadata = this.getMetadata();
+
+    if (isURLTemplate(this.url)) {
+      this.schema = 'template';
+    }
+  }
+
+  async getSchema(): Promise<Schema> {
+    return {fields: [], metadata: {}};
+  }
+
+  async getMetadata(): Promise<TileSourceMetadata> {
+    const attributions = this.options.core?.attributions || [];
+
+    if (!this.metadataUrl) {
+      return {minZoom: 0, maxZoom: 30, attributions};
+    }
+
+    try {
+      const response = await this.fetch(this.metadataUrl);
+      if (!response.ok) {
+        this.reportError(
+          new Error(`${response.status} ${response.statusText}`),
+          `Failed to fetch metadata from ${this.metadataUrl}`
+        );
+        return {minZoom: 0, maxZoom: 30, attributions};
+      }
+
+      const metadataText = await response.text();
+      const metadataJson = JSON.parse(metadataText) as Record<string, unknown>;
+      const minZoom = Number.isFinite(metadataJson?.minZoom as number)
+        ? (metadataJson.minZoom as number)
+        : Number.isFinite(metadataJson?.minzoom as number)
+          ? (metadataJson.minzoom as number)
+          : 0;
+      const maxZoom = Number.isFinite(metadataJson?.maxZoom as number)
+        ? (metadataJson.maxZoom as number)
+        : Number.isFinite(metadataJson?.maxzoom as number)
+          ? (metadataJson.maxzoom as number)
+          : 30;
+      return {
+        ...metadataJson,
+        minZoom,
+        maxZoom,
+        attributions: [...attributions, ...((metadataJson?.attributions as string[]) || [])]
+      };
+    } catch (error) {
+      this.reportError(error, `Failed to fetch metadata from ${this.metadataUrl}`);
+      return {minZoom: 0, maxZoom: 30, attributions};
+    }
+  }
+
+  async getTile(parameters: GetTileParameters): Promise<ArrayBuffer | null> {
+    const tileUrl = this.getTileURL(parameters.x, parameters.y, parameters.z);
+    const response = await this.fetch(tileUrl);
+    if (!response.ok) {
+      this.reportError(
+        new Error(`${response.status} ${response.statusText}`),
+        `Failed to fetch tile ${tileUrl} ${JSON.stringify(parameters)}`
+      );
+      return null;
+    }
+    return response.arrayBuffer();
+  }
+
+  async getTileData(
+    parameters: GetTileDataParameters
+  ): Promise<Feature[] | BinaryFeatureCollection | ArrowTable | null> {
+    const {index} = parameters;
+    return this.getVectorTile({x: index.x, y: index.y, z: index.z, layers: []});
+  }
+
+  async getVectorTile(
+    tileParameters: GetTileParameters
+  ): Promise<Feature[] | BinaryFeatureCollection | ArrowTable | null> {
+    const tileData = await this.getTile(tileParameters);
+    return tileData ? this._parseTile(tileData, tileParameters) : null;
+  }
+
+  protected async _parseTile(
+    arrayBuffer: ArrayBuffer,
+    tileParameters: GetTileParameters
+  ): Promise<Feature[] | BinaryFeatureCollection | ArrowTable | null> {
+    const options: MLTSourceLoaderOptions = this.options;
+    const coordinates = options.mlt?.coordinates || 'wgs84';
+    const shape = options.mlt?.shape || 'arrow-table';
+    const tileIndex =
+      coordinates === 'wgs84'
+        ? {x: tileParameters.x, y: tileParameters.y, z: tileParameters.z}
+        : undefined;
+    const loadOptions: MLTLoaderOptions = {
+      ...this.loadOptions,
+      mlt: {
+        ...(this.loadOptions as MLTLoaderOptions).mlt,
+        shape,
+        coordinates,
+        layers: options.mlt?.layers,
+        tileIndex
+      },
+      geoarrow: options.geoarrow ?? (this.loadOptions as MLTLoaderOptions).geoarrow
+    };
+
+    // Keep the package root and writer usable without eagerly evaluating the decoder.
+    const {MLTLoaderWithParser} = await import('./mlt-loader-with-parser');
+    const parsed = await MLTLoaderWithParser.parse(arrayBuffer, loadOptions);
+    if (shape === 'geojson-table') {
+      return (parsed as {features: Feature[]}).features || null;
+    }
+
+    if (shape === 'binary-geometry' || shape === 'arrow-table') {
+      return parsed as BinaryFeatureCollection | ArrowTable;
+    }
+    return (parsed as {features: Feature[]}).features || null;
+  }
+
+  getTileURL(x: number, y: number, z: number) {
+    switch (this.schema) {
+      case 'xyz':
+        return `${this.url}/${x}/${y}/${z}${this.extension}`;
+      case 'tms':
+        return `${this.url}/${z}/${x}/${y}${this.extension}`;
+      case 'template':
+        return getURLFromTemplate(this.url, x, y, z, this.extension);
+      default:
+        throw new Error(`Unknown tile schema: ${this.schema}`);
+    }
+  }
+}
+
+export function isURLTemplate(s: string): boolean {
+  return /(?=.*\{z\})(?=.*\{x\})(?=.*(\{y\}|\{\-y\}))|(?=.*\{x\})(?=.*(\{y\}|\{\-y\})(?=.*\{z\}))/i.test(
+    s
+  );
+}
+
+export function getURLFromTemplate(
+  template: string,
+  x: number,
+  y: number,
+  z: number,
+  extension: string = ''
+): string {
+  const id = `${x}-${y}-${z}`;
+  const url = template
+    .replace(/\{x\}/g, x.toString())
+    .replace(/\{-y\}/g, String((1 << z) - 1 - y))
+    .replace(/\{y\}/g, y.toString())
+    .replace(/\{z\}/g, z.toString())
+    .replace(/\{id\}/g, id);
+
+  if (!extension || url.endsWith(extension)) {
+    return url;
+  }
+
+  // If template already contains an extension (e.g. ".mvt"), don't double-append.
+  const separatorIndex = url.search(/[?#]/);
+  const path = separatorIndex < 0 ? url : url.slice(0, separatorIndex);
+  const suffix = separatorIndex < 0 ? '' : url.slice(separatorIndex);
+  const file = path.split('/').pop() || '';
+  if (/\.[a-z0-9]+$/i.test(file)) {
+    return url;
+  }
+
+  return `${path}${extension}${suffix}`;
+}

package/src/mlt/mlt-writer.ts

@@ -0,0 +1,47 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import type {WriterOptions, WriterWithEncoder} from '@loaders.gl/core/loader-utils';
+import type {Table} from 'apache-arrow';
+import type {ArrowTable} from '@loaders.gl/core/schema';
+import {encodeMLT} from './lib/encode-mlt';
+import {MLTFormat} from './mlt-format';
+
+/** Controls single-layer MLT v1 encoding of tile-local GeoArrow WKB. */
+export type MLTWriterOptions = WriterOptions & {
+  /** MLT layer and column selection. */
+  mlt?: {
+    /** Nonempty layer name; defaults to features. */
+    layerName?: string;
+    /** GeoArrow WKB column, inferred from metadata when omitted. */
+    geometryColumn?: string;
+    /** Scalar attribute columns; defaults to all non-geometry columns. */
+    propertyColumns?: readonly string[];
+    /** Optional nonnegative safe integer feature IDs. */
+    idColumn?: string;
+    /** Integer tile extent; defaults to 4096. */
+    extent?: number;
+    /** Normalized local coordinates or integer tile grid coordinates. */
+    coordinates?: 'local' | 'tile';
+    /** Maximum input rows per tile; defaults to 100,000. */
+    maxFeatures?: number;
+  };
+};
+
+// __VERSION__ is injected by babel-plugin-version-inline.
+// @ts-ignore TS2304: Cannot find name '__VERSION__'.
+const VERSION = typeof __VERSION__ !== 'undefined' ? __VERSION__ : 'latest';
+
+/** Browser-portable MLT v1 writer for GeoArrow tiles produced by the existing tiler. */
+export const MLTWriter = {
+  ...MLTFormat,
+  name: 'MLT Writer',
+  version: VERSION,
+  binary: true,
+  options: {mlt: {}},
+  /** Encodes a materialized tile asynchronously for the core writer API. */
+  encode: async (data: ArrowTable | Table, options?: MLTWriterOptions) => encodeMLT(data, options),
+  /** Encodes one tile synchronously. */
+  encodeSync: encodeMLT
+} as const satisfies WriterWithEncoder<ArrowTable | Table, never, MLTWriterOptions>;

package/src/mlt/unbundled.ts

@@ -0,0 +1,6 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+export type {MLTLoaderOptions} from './mlt-loader';
+export {MLTLoader, MLTWorkerLoader} from './mlt-loader';

package/src/mvt/arrow-table-tile-source-loader-types.ts

@@ -0,0 +1,55 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import type {CoreAPI, SourceLoader} from '@loaders.gl/core/loader-utils';
+import type {ArrowTableVectorTileSource} from './arrow-table-tile-source-loader';
+import {
+  ARROW_TABLE_TILE_SOURCE_DEFAULT_OPTIONS,
+  type ArrowTableTileSourceInput,
+  type ArrowTableTileSourceLoaderOptions
+} from './arrow-table-tile-source-types';
+
+// __VERSION__ is injected by babel-plugin-version-inline
+// @ts-ignore TS2304: Cannot find name '__VERSION__'.
+const VERSION = typeof __VERSION__ !== 'undefined' ? __VERSION__ : 'latest';
+
+/** Loads the Arrow tiler runtime from its explicit package subpath. */
+async function preloadArrowTableTileSourceLoader(): Promise<
+  SourceLoader<ArrowTableVectorTileSource>
+> {
+  const {ArrowTableTileSourceLoaderWithParser} = await import(
+    '@loaders.gl/tiles/mvt/arrow-table-tile-source-loader'
+  );
+  return ArrowTableTileSourceLoaderWithParser;
+}
+
+/** Lightweight Arrow tiler metadata; use async load() or the explicit runtime subpath. */
+export const ArrowTableTileSourceLoader = {
+  dataType: null as unknown as ArrowTableVectorTileSource,
+  batchType: null as never,
+  name: 'ArrowTableTiler',
+  id: 'arrow-table-tiler',
+  module: 'tiles',
+  version: VERSION,
+  extensions: [],
+  mimeTypes: [],
+  type: 'table',
+  fromUrl: true,
+  fromBlob: true,
+  /** Selection is explicit because any Arrow-producing loader can supply the input. */
+  testURL: () => false,
+  options: ARROW_TABLE_TILE_SOURCE_DEFAULT_OPTIONS,
+  defaultOptions: ARROW_TABLE_TILE_SOURCE_DEFAULT_OPTIONS,
+  preload: preloadArrowTableTileSourceLoader,
+  /** Direct construction requires the runtime loader rather than metadata. */
+  createDataSource(
+    _input: string | Blob | ArrowTableTileSourceInput | Promise<ArrowTableTileSourceInput>,
+    _options: ArrowTableTileSourceLoaderOptions = {},
+    _coreApi?: CoreAPI
+  ): ArrowTableVectorTileSource {
+    throw new Error(
+      'ArrowTableTileSourceLoader requires async load() or an explicit @loaders.gl/tiles/mvt/arrow-table-tile-source-loader import'
+    );
+  }
+} as const satisfies SourceLoader<ArrowTableVectorTileSource>;