@loaders.gl/services 5.0.0-alpha.3

package/src/arcgis/arcgis-feature-server-source-loader.ts

@@ -0,0 +1,342 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import type {DataType, Schema, GeoJSONTable} from '@loaders.gl/schema';
+import {
+  convertFeaturesToWKBArrowTable,
+  convertGeojsonToBinaryFeatureCollection
+} from '@loaders.gl/gis';
+import type {
+  CoreAPI,
+  DataSourceOptions,
+  VectorSourceMetadata,
+  GetFeaturesParameters,
+  VectorSource,
+  VectorSourceData
+} from '@loaders.gl/loader-utils';
+import type {SourceLoader} from '@loaders.gl/loader-utils';
+import {DataSource} from '@loaders.gl/loader-utils';
+import {buildArcGISResourceURL} from './arcgis-url-utils';
+
+/** Parameters for ArcGIS FeatureServer query requests. */
+export type ArcGISFeatureServiceQueryOptions = {
+  /** Include feature geometries in the response. */
+  returnGeometry?: boolean;
+  /** SQL where clause. */
+  where?: string;
+  /** Output spatial reference. */
+  outSR?: string | number;
+  /** Output fields. */
+  outFields?: string | string[];
+  /** Input spatial reference for supplied geometry. */
+  inSR?: string | number;
+  /** Filter geometry as an ArcGIS REST geometry string. */
+  geometry?: string;
+  /** Filter geometry type. */
+  geometryType?:
+    | 'esriGeometryEnvelope'
+    | 'esriGeometryPoint'
+    | 'esriGeometryPolyline'
+    | 'esriGeometryPolygon';
+  /** Spatial relationship for geometry filters. */
+  spatialRel?:
+    | 'esriSpatialRelIntersects'
+    | 'esriSpatialRelContains'
+    | 'esriSpatialRelCrosses'
+    | 'esriSpatialRelEnvelopeIntersects'
+    | 'esriSpatialRelIndexIntersects'
+    | 'esriSpatialRelOverlaps'
+    | 'esriSpatialRelTouches'
+    | 'esriSpatialRelWithin';
+  /** Geometry precision. */
+  geometryPrecision?: number;
+  /** Query result type. */
+  resultType?: 'none' | 'standard' | 'tile';
+  /** ArcGIS response format. */
+  f?: 'geojson' | 'json' | 'pjson';
+};
+
+/** Options for the ArcGIS FeatureServer source. */
+export type ArcGISFeatureServerSourceLoaderOptions = DataSourceOptions & {
+  'arcgis-feature-server'?: {
+    /** Default ArcGIS query request parameters. */
+    queryParameters?: Partial<ArcGISFeatureServiceQueryOptions>;
+  };
+};
+
+/**
+ * @see https://developers.arcgis.com/rest/services-reference/enterprise/feature-service.htm
+ */
+export const ArcGISFeatureServerSourceLoader = {
+  dataType: null as unknown as ArcGISVectorSource,
+  batchType: null as never,
+  name: 'ArcGISFeatureServer',
+  id: 'arcgis-feature-server',
+  module: 'services',
+  version: '0.0.0',
+  extensions: [],
+  mimeTypes: [],
+  type: 'arcgis-feature-server',
+  fromUrl: true,
+  fromBlob: false,
+
+  options: {
+    url: undefined!,
+    'arcgis-feature-server': {}
+  },
+
+  defaultOptions: {
+    url: undefined!,
+    'arcgis-feature-server': {}
+  },
+
+  testURL: (url: string): boolean => url.toLowerCase().includes('featureserver'),
+  createDataSource: (
+    url: string,
+    options: ArcGISFeatureServerSourceLoaderOptions,
+    coreApi?: CoreAPI
+  ): ArcGISVectorSource => new ArcGISVectorSource(url, options, coreApi)
+} as const satisfies SourceLoader<ArcGISVectorSource>;
+
+/**
+ * ArcGIS FeatureServer
+ * Note - exports a big API, that could be exposed here if there is a use case
+ * @see https://developers.arcgis.com/rest/services-reference/enterprise/feature-service.htm
+ */
+export class ArcGISVectorSource
+  extends DataSource<string, ArcGISFeatureServerSourceLoaderOptions>
+  implements VectorSource
+{
+  /** Cached ArcGIS FeatureServer metadata request. */
+  protected formatSpecificMetadata: Promise<any> | null = null;
+
+  constructor(url: string, options: ArcGISFeatureServerSourceLoaderOptions, coreApi?: CoreAPI) {
+    super(url, options, ArcGISFeatureServerSourceLoader.defaultOptions, coreApi);
+  }
+
+  /** Returns a schema inferred from ArcGIS FeatureServer metadata fields. */
+  async getSchema(): Promise<Schema> {
+    const metadata = await this.getFormatSpecificMetadata();
+    return parseArcGISFeatureServerSchema(metadata);
+  }
+
+  /** Returns normalized VectorSource metadata. */
+  async getMetadata(
+    options: {formatSpecificMetadata?: boolean} = {}
+  ): Promise<VectorSourceMetadata> {
+    // Wait for raw metadata to load
+    const formatSpecificMetadata = await this.getFormatSpecificMetadata();
+
+    const metadata = parseArcGISFeatureServerMetadata(formatSpecificMetadata);
+
+    // Only add the big blob of source metadata if explicitly requested
+    if (options.formatSpecificMetadata) {
+      metadata.formatSpecificMetadata = formatSpecificMetadata;
+    }
+    return metadata;
+  }
+
+  /** Requests features from the ArcGIS FeatureServer query endpoint. */
+  async getFeatures(parameters: GetFeaturesParameters): Promise<VectorSourceData> {
+    const url = this.getFeaturesURL(parameters);
+    const response = await this.fetch(
+      url,
+      parameters.signal ? {signal: parameters.signal} : undefined
+    );
+    await this.checkResponse(response);
+    const geoJsonTable = parseGeoJSONTable(await response.json());
+    const format = parameters.format || 'arrow';
+
+    switch (format) {
+      case 'binary':
+        return convertGeojsonToBinaryFeatureCollection(geoJsonTable.features);
+      case 'geojson':
+        return geoJsonTable;
+      case 'arrow':
+      default:
+        return convertFeaturesToWKBArrowTable(geoJsonTable.features);
+    }
+  }
+
+  /** Requests the raw ArcGIS FeatureServer metadata document. */
+  protected async _getFormatSpecificMetadata() {
+    // PJSON is formatted by a bit slower than JSON
+    const url = this.metadataURL();
+    const response = await this.fetch(url);
+    await this.checkResponse(response);
+    return await response.json();
+  }
+
+  /** Loads and caches the raw ArcGIS FeatureServer metadata. */
+  protected async getFormatSpecificMetadata(): Promise<any> {
+    this.formatSpecificMetadata ||= this._getFormatSpecificMetadata();
+    return await this.formatSpecificMetadata;
+  }
+
+  /** Builds a metadata URL for the ArcGIS FeatureServer endpoint. */
+  metadataURL(options?: {parameters?: Record<string, unknown>}): string {
+    return this.getUrl('', {f: 'pjson', ...options?.parameters});
+  }
+
+  /** Builds a query URL from generic vector source parameters. */
+  getFeaturesURL(parameters: GetFeaturesParameters): string {
+    const defaultParameters = this.options['arcgis-feature-server']?.queryParameters || {};
+    const spatialReference = normalizeArcGISSpatialReference(parameters.crs) || 4326;
+    const queryParameters: ArcGISFeatureServiceQueryOptions = {
+      returnGeometry: true,
+      where: '1=1',
+      outFields: '*',
+      outSR: spatialReference,
+      inSR: spatialReference,
+      f: 'geojson',
+      ...defaultParameters
+    };
+
+    if (parameters.boundingBox) {
+      queryParameters.geometry = [
+        parameters.boundingBox[0][0],
+        parameters.boundingBox[0][1],
+        parameters.boundingBox[1][0],
+        parameters.boundingBox[1][1]
+      ].join(',');
+      queryParameters.geometryType = 'esriGeometryEnvelope';
+      queryParameters.spatialRel ||= 'esriSpatialRelIntersects';
+    }
+
+    const layer = Array.isArray(parameters.layers) ? parameters.layers[0] : parameters.layers;
+    const isLayerEndpoint = /\/FeatureServer\/\d+\/?(?:\?|$)/i.test(this.url);
+    const resourcePath = isLayerEndpoint || !layer ? 'query' : `${layer}/query`;
+    return this.getUrl(resourcePath, queryParameters);
+  }
+
+  /** Builds an ArcGIS FeatureServer URL. */
+  protected getUrl(
+    path: string,
+    options: Record<string, unknown>,
+    extra?: Record<string, unknown>
+  ): string {
+    return buildArcGISResourceURL(this.url, path, {...options, ...extra});
+  }
+
+  /** Checks an ArcGIS FeatureServer response. */
+  protected async checkResponse(response: Response): Promise<void> {
+    if (!response.ok) {
+      throw new Error(
+        response.statusText || `ArcGIS FeatureServer request failed: ${response.status}`
+      );
+    }
+  }
+}
+
+function parseArcGISFeatureServerMetadata(json: any): VectorSourceMetadata {
+  const layers: VectorSourceMetadata['layers'] = [];
+  for (const layer of json.layers || []) {
+    const extent = layer.extent;
+    const spatialReference = layer.spatialReference || extent?.spatialReference;
+    layers.push({
+      name: layer.id === undefined ? layer.name : String(layer.id),
+      title: layer.name,
+      crs: getArcGISCoordinateReferenceSystems(spatialReference),
+      boundingBox: normalizeArcGISExtent(extent)
+    });
+  }
+
+  if (!layers.length && (json.id !== undefined || json.name)) {
+    const extent = json.extent;
+    layers.push({
+      name: json.id === undefined ? json.name : String(json.id),
+      title: json.name,
+      crs: getArcGISCoordinateReferenceSystems(json.spatialReference || extent?.spatialReference),
+      boundingBox: normalizeArcGISExtent(extent)
+    });
+  }
+
+  return {
+    // version: json.currentVersion || '',
+    title: json.serviceDescription || '',
+    name: json.serviceDescription || '',
+    abstract: json.description || '',
+    keywords: [],
+    // attrribution: json.copyrightText || ''.
+    // crs: 'EPSG:4326',
+    layers
+  };
+}
+
+/** Normalizes an ArcGIS spatial reference to a one-element CRS list. */
+function getArcGISCoordinateReferenceSystems(
+  spatialReference: {wkid?: number; latestWkid?: number} | undefined
+): string[] | undefined {
+  const wellKnownIdentifier = spatialReference?.latestWkid || spatialReference?.wkid;
+  return wellKnownIdentifier ? [`EPSG:${wellKnownIdentifier}`] : undefined;
+}
+
+/** Normalizes an ArcGIS extent to the loaders.gl two-corner shape. */
+function normalizeArcGISExtent(
+  extent: {xmin?: number; ymin?: number; xmax?: number; ymax?: number} | undefined
+): [[number, number], [number, number]] | undefined {
+  return extent && [extent.xmin, extent.ymin, extent.xmax, extent.ymax].every(Number.isFinite)
+    ? [
+        [extent.xmin!, extent.ymin!],
+        [extent.xmax!, extent.ymax!]
+      ]
+    : undefined;
+}
+
+/** Normalizes EPSG-prefixed CRS strings to ArcGIS WKID values. */
+function normalizeArcGISSpatialReference(
+  spatialReference: string | number | undefined
+): string | number | undefined {
+  if (typeof spatialReference === 'string') {
+    const match = /^EPSG:(\d+)$/i.exec(spatialReference);
+    if (match) {
+      return match[1];
+    }
+  }
+  return spatialReference;
+}
+
+/** Builds a schema from ArcGIS FeatureServer metadata fields. */
+function parseArcGISFeatureServerSchema(json: any): Schema {
+  const fields = Array.isArray(json.fields)
+    ? json.fields.map((field: any) => ({
+        name: field.name,
+        type: getSchemaTypeFromArcGISFieldType(field.type),
+        nullable: field.nullable
+      }))
+    : [];
+
+  return {metadata: {}, fields};
+}
+
+/** Maps common ArcGIS field types to loaders.gl schema type strings. */
+function getSchemaTypeFromArcGISFieldType(type: string): DataType {
+  switch (type) {
+    case 'esriFieldTypeDouble':
+      return 'float64';
+    case 'esriFieldTypeSingle':
+      return 'float32';
+    case 'esriFieldTypeInteger':
+    case 'esriFieldTypeSmallInteger':
+    case 'esriFieldTypeOID':
+      return 'int32';
+    case 'esriFieldTypeDate':
+      return 'timestamp-millisecond';
+    default:
+      return 'utf8';
+  }
+}
+
+/** Parses a GeoJSON FeatureCollection into the loaders.gl GeoJSON table shape. */
+function parseGeoJSONTable(json: any): GeoJSONTable {
+  if (json?.type === 'FeatureCollection' && Array.isArray(json.features)) {
+    return {
+      shape: 'geojson-table',
+      type: 'FeatureCollection',
+      features: json.features
+    };
+  }
+
+  throw new Error('ArcGIS FeatureServer query did not return a GeoJSON FeatureCollection');
+}

package/src/arcgis/arcgis-image-server-source-loader.ts

@@ -0,0 +1,241 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import type {ImageType} from '@loaders.gl/images';
+import {ImageLoader} from '@loaders.gl/images';
+import type {
+  CoreAPI,
+  SourceLoader,
+  DataSourceOptions,
+  ImageSourceMetadata,
+  GetImageParameters
+} from '@loaders.gl/loader-utils';
+import {DataSource, ImageSource} from '@loaders.gl/loader-utils';
+import type {LERCData} from '@loaders.gl/lerc';
+import {LERCLoader} from '@loaders.gl/lerc';
+import {buildArcGISResourceURL} from './arcgis-url-utils';
+
+/** Options for the ArcGIS ImageServer source. */
+export type ArcGISImageSourceLoaderProps = DataSourceOptions & {
+  'arcgis-image-server'?: {
+    /** Default ArcGIS exportImage request parameters. */
+    exportImageParameters?: Partial<ArcGISExportImageParameters>;
+  };
+};
+
+/** Parameters for ArcGIS ImageServer exportImage requests. */
+export type ArcGISExportImageParameters = {
+  /** Bounding box of the requested image. */
+  bbox: [number, number, number, number];
+  /** Spatial reference of the supplied bbox. */
+  bboxSR?: string | number;
+  /** Pixel width of returned image. */
+  width: number;
+  /** Pixel height of returned image. */
+  height: number;
+  /** Spatial reference of the returned image. */
+  imageSR?: string | number;
+  /** Requested image format. */
+  format?: 'jpgpng' | 'png' | 'png8' | 'png24' | 'jpg' | 'bmp' | 'gif' | 'tiff' | 'png32' | 'lerc';
+  /** Requested pixel type. */
+  pixelType?: 'U1' | 'U2' | 'U4' | 'U8' | 'S8' | 'U16' | 'S16' | 'U32' | 'S32' | 'F32' | 'F64';
+  /** NoData pixel value. */
+  noData?: string | number;
+  /** NoData interpretation mode. */
+  noDataInterpretation?: 'esriNoDataMatchAny' | 'esriNoDataMatchAll';
+  /** Resampling interpolation. */
+  interpolation?: string;
+  /** Compression type. */
+  compression?: string;
+  /** Compression quality. */
+  compressionQuality?: number;
+  /** Band ids to export. */
+  bandIds?: string | number[];
+  /** Mosaic rule JSON string or object. */
+  mosaicRule?: string | Record<string, unknown>;
+  /** Rendering rule JSON string or object. */
+  renderingRule?: string | Record<string, unknown>;
+  /** ArcGIS response format. */
+  f?: 'image' | 'json' | 'pjson';
+};
+
+export const ArcGISImageServerSourceLoader = {
+  dataType: null as unknown as ArcGISImageSource,
+  batchType: null as never,
+  name: 'ArcGISImageServer',
+  id: 'arcgis-image-server',
+  module: 'services',
+  version: '0.0.0',
+  extensions: [],
+  mimeTypes: [],
+  type: 'arcgis-image-server',
+  fromUrl: true,
+  fromBlob: false,
+
+  options: {
+    'arcgis-image-server': {
+      // TODO - add options here
+    }
+  },
+
+  defaultOptions: {
+    'arcgis-image-server': {
+      // TODO - add options here
+    }
+  },
+
+  testURL: (url: string): boolean => url.toLowerCase().includes('imageserver'),
+  createDataSource: (
+    url: string,
+    props: ArcGISImageSourceLoaderProps,
+    coreApi?: CoreAPI
+  ): ArcGISImageSource => new ArcGISImageSource(url, props, coreApi)
+} as const satisfies SourceLoader<ArcGISImageSource>;
+
+/**
+ * ArcGIS ImageServer
+ * Note - exports a big API, that could be exposed here if there is a use case
+ * @see https://developers.arcgis.com/rest/services-reference/enterprise/image-service.htm
+ */
+export class ArcGISImageSource
+  extends DataSource<string, ArcGISImageSourceLoaderProps>
+  implements ImageSource
+{
+  constructor(url: string, props: ArcGISImageSourceLoaderProps, coreApi?: CoreAPI) {
+    super(url, props, ArcGISImageServerSourceLoader.defaultOptions, coreApi);
+  }
+
+  /** Returns normalized ImageSource metadata. */
+  async getMetadata(): Promise<ImageSourceMetadata> {
+    return normalizeArcGISImageServerMetadata(await this.metadata());
+  }
+
+  /** Requests an image from generic ImageSource parameters. */
+  async getImage(parameters: GetImageParameters): Promise<ImageType> {
+    const {boundingBox, bbox, width, height, crs, format, signal} = parameters;
+    const spatialReference = normalizeArcGISSpatialReference(crs) || '4326';
+    const imageParameters: ArcGISExportImageParameters = {
+      bbox: boundingBox ? [...boundingBox[0], ...boundingBox[1]] : bbox!,
+      bboxSR: spatialReference,
+      imageSR: spatialReference,
+      width,
+      height,
+      format: format === 'image/png' ? 'png' : undefined
+    };
+    return await this.exportImage(imageParameters, signal);
+  }
+
+  /** Requests the ArcGIS ImageServer metadata document. */
+  async metadata(): Promise<unknown> {
+    const response = await this.fetch(this.metadataURL());
+    await this.checkResponse(response);
+    return await response.json();
+  }
+
+  /** Requests an exported image from the ArcGIS ImageServer endpoint. */
+  async exportImage(
+    options: ArcGISExportImageParameters,
+    signal?: AbortSignal
+  ): Promise<ImageType> {
+    const response = await this.fetch(this.exportImageURL(options), signal ? {signal} : undefined);
+    await this.checkResponse(response);
+    const arrayBuffer = await response.arrayBuffer();
+    return (await this.coreApi.parse(arrayBuffer, ImageLoader, this.loadOptions)) as ImageType;
+  }
+
+  /** Requests an analytical LERC raster from the ArcGIS ImageServer endpoint. */
+  async exportRaster(
+    options: ArcGISExportImageParameters,
+    signal?: AbortSignal
+  ): Promise<LERCData> {
+    const response = await this.fetch(
+      this.exportImageURL({...options, format: 'lerc'}),
+      signal ? {signal} : undefined
+    );
+    await this.checkResponse(response);
+    return (await this.coreApi.parse(
+      await response.arrayBuffer(),
+      LERCLoader,
+      this.loadOptions
+    )) as LERCData;
+  }
+
+  /** Builds a metadata URL for the ArcGIS ImageServer endpoint. */
+  metadataURL(options?: {parameters?: Record<string, unknown>}): string {
+    return this.getUrl('', {f: 'pjson', ...options?.parameters});
+  }
+
+  /** Builds an exportImage URL for the ArcGIS ImageServer endpoint. */
+  exportImageURL(options: ArcGISExportImageParameters): string {
+    const defaultParameters = this.options['arcgis-image-server']?.exportImageParameters || {};
+    const {width, height, ...parameters} = {...defaultParameters, ...options};
+    return this.getUrl('exportImage', {
+      ...parameters,
+      bbox: parameters.bbox,
+      size: [width, height],
+      f: parameters.f || 'image'
+    });
+  }
+
+  /** Builds an ArcGIS ImageServer URL. */
+  protected getUrl(
+    path: string,
+    options: Record<string, unknown>,
+    extra?: Record<string, unknown>
+  ): string {
+    return buildArcGISResourceURL(this.url, path, {...options, ...extra});
+  }
+
+  /** Checks an ArcGIS ImageServer response. */
+  protected async checkResponse(response: Response): Promise<void> {
+    if (!response.ok) {
+      throw new Error(
+        response.statusText || `ArcGIS ImageServer request failed: ${response.status}`
+      );
+    }
+  }
+}
+
+/** Normalizes EPSG-prefixed CRS strings to ArcGIS WKID values. */
+function normalizeArcGISSpatialReference(
+  spatialReference: string | number | undefined
+): string | number | undefined {
+  if (typeof spatialReference === 'string') {
+    const match = /^EPSG:(\d+)$/i.exec(spatialReference);
+    if (match) {
+      return match[1];
+    }
+  }
+  return spatialReference;
+}
+
+/** Normalizes ArcGIS ImageServer metadata to the generic ImageSource metadata shape. */
+function normalizeArcGISImageServerMetadata(metadata: unknown): ImageSourceMetadata {
+  const arcgisMetadata = metadata as any;
+  const extent = arcgisMetadata.fullExtent || arcgisMetadata.extent;
+  const spatialReference = arcgisMetadata.spatialReference || extent?.spatialReference;
+  const wellKnownIdentifier = spatialReference?.latestWkid || spatialReference?.wkid;
+  const boundingBox =
+    extent && [extent.xmin, extent.ymin, extent.xmax, extent.ymax].every(Number.isFinite)
+      ? ([
+          [extent.xmin, extent.ymin],
+          [extent.xmax, extent.ymax]
+        ] as [[number, number], [number, number]])
+      : undefined;
+  const name = arcgisMetadata.name || arcgisMetadata.serviceDescription || '';
+  return {
+    name,
+    title: name,
+    abstract: arcgisMetadata.description || arcgisMetadata.serviceDescription || '',
+    keywords: Array.isArray(arcgisMetadata.keywords) ? arcgisMetadata.keywords : [],
+    layers: [
+      {
+        name,
+        title: name,
+        crs: wellKnownIdentifier ? [`EPSG:${wellKnownIdentifier}`] : undefined,
+        boundingBox
+      }
+    ]
+  };
+}