@loaders.gl/wms 3.3.0-alpha.9 → 3.3.0

package/src/lib/data-sources/image-services/arcgis-image-service.ts

@@ -0,0 +1,136 @@
+// loaders.gl, MIT license
+
+import {ImageType} from '@loaders.gl/images';
+import type {ImageSourceMetadata, GetImageParameters} from '../image-source';
+import {ImageSource} from '../image-source';
+import {ImageServiceProps, mergeImageServiceProps, getFetchFunction} from './image-service';
+
+export class ArcGISImageService extends ImageSource {
+  static type: 'arcgis-image-server' = 'arcgis-image-server';
+  static testURL = (url: string): boolean => url.toLowerCase().includes('ImageServer');
+
+  props: Required<ImageServiceProps>;
+  fetch: (url: string, options?: RequestInit) => Promise<Response>;
+
+  constructor(props: ImageServiceProps) {
+    super();
+    this.props = mergeImageServiceProps(props);
+    this.fetch = getFetchFunction(this.props);
+  }
+
+  // ImageSource (normalized endpoints)
+
+  async getMetadata(): Promise<ImageSourceMetadata> {
+    return (await this.info()) as ImageSourceMetadata;
+    // TODO - normalize metadata
+  }
+
+  async getImage(parameters: GetImageParameters): Promise<ImageType> {
+    throw new Error('not implemented');
+    // TODO - Map generic parameters to ArcGIS specific parameters
+    // return await this.exportImage(parameters);
+  }
+
+  // ImageServer endpoints
+
+  async info(): Promise<unknown> {
+    // We just need a JSON parsing...
+    // return this.getUrl({path: '', ...options});
+    throw new Error('not implemented');
+  }
+
+  /** 
+   * Form a URL to an ESRI ImageServer
+   // https://sampleserver6.arcgisonline.com/arcgis/rest/services/NLCDLandCover2001/ImageServer/exportImage?bbox=${bounds[0]},${bounds[1]},${bounds[2]},${bounds[3]}&bboxSR=4326&size=${width},${height}&imageSR=102100&time=&format=jpgpng&pixelType=U8&noData=&noDataInterpretation=esriNoDataMatchAny&interpolation=+RSP_NearestNeighbor&compression=&compressionQuality=&bandIds=&mosaicRule=&renderingRule=&f=image`,
+   */
+  exportImage(options: {
+    boundingBox: [number, number, number, number];
+    boundingBoxSR?: string;
+    width: number;
+    height: number;
+    imageSR?: string;
+    time?: never;
+    format?: 'jpgpng';
+    pixelType?: 'U8';
+    noData?: never;
+    noDataInterpretation?: 'esriNoDataMatchAny';
+    interpolation?: '+RSP_NearestNeighbor';
+    compression?: never;
+    compressionQuality?: never;
+    bandIds?: never;
+    mosaicRule?: never;
+    renderingRule?: never;
+    f?: 'image';
+  }): Promise<ImageType> {
+    // See WMSService.getMap()
+    throw new Error('not implemented');
+  }
+
+  // URL creators
+
+  infoURL(options: {parameters?: Record<string, unknown>}): string {
+    return this.props.url;
+    // return this.getUrl({path: '', ...options});
+  }
+
+  /** 
+   * Form a URL to an ESRI ImageServer
+   // https://sampleserver6.arcgisonline.com/arcgis/rest/services/NLCDLandCover2001/ImageServer/exportImage?bbox=${bounds[0]},${bounds[1]},${bounds[2]},${bounds[3]}&bboxSR=4326&size=${width},${height}&imageSR=102100&time=&format=jpgpng&pixelType=U8&noData=&noDataInterpretation=esriNoDataMatchAny&interpolation=+RSP_NearestNeighbor&compression=&compressionQuality=&bandIds=&mosaicRule=&renderingRule=&f=image`,
+   */
+  exportImageURL(options: {
+    boundingBox: [number, number, number, number];
+    boundingBoxSR?: string;
+    width: number;
+    height: number;
+    imageSR?: string;
+    time?: never;
+    format?: 'jpgpng';
+    pixelType?: 'U8';
+    noData?: never;
+    noDataInterpretation?: 'esriNoDataMatchAny';
+    interpolation?: '+RSP_NearestNeighbor';
+    compression?: never;
+    compressionQuality?: never;
+    bandIds?: never;
+    mosaicRule?: never;
+    renderingRule?: never;
+    f?: 'image';
+  }): string {
+    // const {boundingBox} = options;
+    // const bbox = `bbox=${boundingBox[0]},${boundingBox[1]},${boundingBox[2]},${boundingBox[3]}`;
+    // const size = `size=${width},${height}`;
+    // return this.getUrl({path: 'exportImage'});
+    return this.props.url;
+  }
+
+  // INTERNAL METHODS
+
+  /**
+   * @note protected, since perhaps getWMSUrl may need to be overridden to handle certain backends?
+   * @note if override is common, maybe add a callback prop?
+   * */
+  protected getUrl(options: Record<string, unknown>, extra?: Record<string, unknown>): string {
+    let url = `${this.props.url}`;
+    let first = true;
+    for (const [key, value] of Object.entries(options)) {
+      url += first ? '?' : '&';
+      first = false;
+      if (Array.isArray(value)) {
+        url += `${key.toUpperCase()}=${value.join(',')}`;
+      } else {
+        url += `${key.toUpperCase()}=${value ? String(value) : ''}`;
+      }
+    }
+    return url;
+  }
+
+  /** Checks for and parses a WMS XML formatted ServiceError and throws an exception */
+  protected async checkResponse(response: Response) {
+    if (!response.ok) {
+      // } || response.headers['content-type'] === WMSErrorLoader.mimeTypes[0]) {
+      // const arrayBuffer = await response.arrayBuffer();
+      // const error = await WMSErrorLoader.parse(arrayBuffer, this.loadOptions);
+      throw new Error('error');
+    }
+  }
+}

package/src/lib/data-sources/image-services/image-service.ts

@@ -0,0 +1,105 @@
+// loaders.gl, MIT license
+
+import {LoaderOptions} from '@loaders.gl/loader-utils';
+import type {ImageType} from '@loaders.gl/images';
+import {ImageLoader} from '@loaders.gl/images';
+
+import type {ImageSourceMetadata, GetImageParameters} from '../image-source';
+import {ImageSource} from '../image-source';
+
+/** Template URL string should contain `${width}` etc which will be substituted. */
+export type ImageServiceProps = {
+  /** Base URL to the service */
+  url: string;
+  /** Any load options to the loaders.gl Loaders used by the WMSService methods */
+  loadOptions?: LoaderOptions;
+};
+
+/**
+ * Quickly connect to "ad hoc" image sources without subclassing ImageSource.
+ * ImageSource allows template url strings to be used to ad hoc connect to arbitrary image data sources
+ * Accepts a template url string and builds requests URLs
+ */
+export class ImageService extends ImageSource {
+  static type: 'template' = 'template';
+  static testURL = (url: string): boolean => url.toLowerCase().includes('{');
+
+  props: Required<ImageServiceProps>;
+  fetch: (url: string, options?: RequestInit) => Promise<Response>;
+
+  constructor(props: ImageServiceProps) {
+    super();
+    this.props = mergeImageServiceProps(props);
+    this.fetch = getFetchFunction(props);
+  }
+
+  // IMAGE SOURCE API
+
+  async getMetadata(): Promise<ImageSourceMetadata> {
+    throw new Error('ImageSource.getMetadata not implemented');
+  }
+
+  async getImage(parameters: GetImageParameters): Promise<ImageType> {
+    const granularParameters = this.getGranularParameters(parameters);
+    const url = this.getURLFromTemplate(granularParameters);
+    const response = await this.fetch(url);
+    const arrayBuffer = await response.arrayBuffer();
+    return await ImageLoader.parse(arrayBuffer);
+  }
+
+  // HELPERS
+
+  /** Break up bounding box in east, north, south, west */
+  protected getGranularParameters(parameters: GetImageParameters): Record<string, unknown> {
+    const [east, north, west, south] = parameters.bbox;
+    return {...parameters, east, north, south, west};
+  }
+
+  /** Supports both ${} and {} notations */
+  protected getURLFromTemplate(parameters: Record<string, unknown>): string {
+    let url = this.props.url;
+    for (const [key, value] of Object.entries(parameters)) {
+      // TODO - parameter could be repeated
+      // const regex = new RegExp(`\${${key}}`, 'g');
+      url = url.replace(`\${${key}}`, String(value));
+      url = url.replace(`{${key}}`, String(value));
+    }
+    return url;
+  }
+}
+
+/**
+ * Gets the current fetch function from options
+ * @todo - move to loader-utils module
+ * @todo - use in core module counterpart
+ * @param options
+ * @param context
+ */
+export function getFetchFunction(options?: LoaderOptions) {
+  const fetchFunction = options?.fetch;
+
+  // options.fetch can be a function
+  if (fetchFunction && typeof fetchFunction === 'function') {
+    return (url: string, fetchOptions?: RequestInit) => fetchFunction(url, fetchOptions);
+  }
+
+  // options.fetch can be an options object, use global fetch with those options
+  const fetchOptions = options?.fetch;
+  if (fetchOptions && typeof fetchOptions !== 'function') {
+    return (url) => fetch(url, fetchOptions);
+  }
+
+  // else return the global fetch function
+  return (url) => fetch(url);
+}
+
+export function mergeImageServiceProps(props: ImageServiceProps): Required<ImageServiceProps> {
+  return {
+    // Default fetch
+    ...props,
+    loadOptions: {
+      ...props.loadOptions,
+      fetch: getFetchFunction(props.loadOptions)
+    }
+  };
+}

package/src/lib/data-sources/image-services/wms-service.ts

@@ -0,0 +1,351 @@
+// loaders.gl, MIT license
+
+/* eslint-disable camelcase */
+
+import type {ImageType} from '@loaders.gl/images';
+import {ImageLoader} from '@loaders.gl/images';
+
+import type {ImageSourceMetadata, GetImageParameters} from '../image-source';
+import {ImageSource} from '../image-source';
+import {ImageServiceProps, getFetchFunction, mergeImageServiceProps} from './image-service';
+
+import type {WMSCapabilities, WMSFeatureInfo, WMSLayerDescription} from '../../wms/wms-types';
+import {WMSCapabilitiesLoader} from '../../../wms-capabilities-loader';
+import {WMSFeatureInfoLoader} from '../../../wip/wms-feature-info-loader';
+import {WMSLayerDescriptionLoader} from '../../../wip/wms-layer-description-loader';
+import {WMSErrorLoader} from '../../../wms-error-loader';
+
+type WMSCommonParameters = {
+  /** In case the endpoint supports multiple services */
+  service?: 'WMS';
+  /** In case the endpoint supports multiple WMS versions */
+  version?: '1.1.1' | '1.3.0';
+};
+
+export type WMSGetCapabilitiesParameters = WMSCommonParameters & {
+  /** Request type */
+  request?: 'GetCapabilities';
+};
+
+export type WMSGetMapParameters = WMSCommonParameters & {
+  /** Request type */
+  request?: 'GetMap';
+  /** Layers to render */
+  layers: string | string[];
+  /** Styling */
+  styles?: unknown;
+  /** bounding box of the requested map image */
+  bbox: [number, number, number, number];
+  /** pixel width of returned image */
+  width: number;
+  /** pixels */
+  height: number;
+  /** srs for the image (not the bounding box) */
+  srs?: string;
+  /** requested format for the return image */
+  format?: 'image/png';
+};
+
+// https://imagery.pasda.psu.edu/arcgis/services/pasda/UrbanTreeCanopy_Landcover/MapServer/WmsServer?SERVICE=WMS&
+export type WMSGetFeatureInfoParameters = WMSCommonParameters & {
+  /** Request type */
+  request?: 'GetFeatureInfo';
+
+  /** x coordinate for the feature info request */
+  x: number;
+  /** y coordinate for the feature info request */
+  y: number;
+  /** list of layers to query (could be different from rendered layers) */
+  query_layers: string[];
+  /** MIME type of returned feature info */
+  info_format?: 'text/plain' | 'application/vnd.ogc.gml';
+
+  /** Layers to render */
+  layers: string[];
+  /** Styling */
+  styles?: unknown;
+  /** bounding box of the requested map image */
+  bbox: [number, number, number, number];
+  /** pixel width of returned image */
+  width: number;
+  /** pixels */
+  height: number;
+  /** srs for the image (not the bounding box) */
+  srs?: string;
+  /** requested format for the return image */
+  format?: 'image/png';
+};
+
+export type WMSDescribeLayerParameters = WMSCommonParameters & {
+  /** Request type */
+  request?: 'DescribeLayer';
+};
+
+export type WMSGetLegendGraphicParameters = WMSCommonParameters & {
+  /** Request type */
+  request?: 'GetLegendGraphic';
+};
+
+/**
+ * The WMSService class provides
+ * - provides type safe methods to form URLs to a WMS service
+ * - provides type safe methods to query and parse results (and errors) from a WMS service
+ * - implements the ImageService interface
+ * @note Only the URL parameter conversion is supported. XML posts are not supported.
+ */
+export class WMSService extends ImageSource {
+  static type: 'wms' = 'wms';
+  static testURL = (url: string): boolean => url.toLowerCase().includes('wms');
+
+  props: Required<ImageServiceProps>;
+  fetch: (url: string, options?: RequestInit) => Promise<Response>;
+  capabilities: WMSCapabilities | null = null;
+
+  /** A list of loaders used by the WMSService methods */
+  readonly loaders = [
+    ImageLoader,
+    WMSErrorLoader,
+    WMSCapabilitiesLoader,
+    WMSFeatureInfoLoader,
+    WMSLayerDescriptionLoader
+  ];
+
+  /** Create a WMSService */
+  constructor(props: ImageServiceProps) {
+    super();
+    this.props = mergeImageServiceProps(props);
+    this.fetch = getFetchFunction(this.props);
+    this.props.loadOptions = {
+      ...this.props.loadOptions,
+      // We want error responses to throw exceptions, the WMSErrorLoader can do this
+      wms: {...this.props.loadOptions?.wms, throwOnError: true}
+    };
+  }
+
+  // ImageSource implementation
+  getMetadata(): Promise<ImageSourceMetadata> {
+    return this.getCapabilities();
+  }
+
+  getImage(parameters: GetImageParameters): Promise<ImageType> {
+    return this.getMap(parameters);
+  }
+
+  // WMS Service API Stubs
+
+  /** Get Capabilities */
+  async getCapabilities(
+    wmsParameters?: WMSGetCapabilitiesParameters,
+    vendorParameters?: Record<string, unknown>
+  ): Promise<WMSCapabilities> {
+    const url = this.getCapabilitiesURL(wmsParameters, vendorParameters);
+    const response = await this.fetch(url);
+    const arrayBuffer = await response.arrayBuffer();
+    this._checkResponse(response, arrayBuffer);
+    const capabilities = await WMSCapabilitiesLoader.parse(arrayBuffer, this.props.loadOptions);
+    this.capabilities = capabilities;
+    return capabilities;
+  }
+
+  /** Get a map image */
+  async getMap(
+    options: WMSGetMapParameters,
+    vendorParameters?: Record<string, unknown>
+  ): Promise<ImageType> {
+    const url = this.getMapURL(options, vendorParameters);
+    const response = await this.fetch(url);
+    const arrayBuffer = await response.arrayBuffer();
+    this._checkResponse(response, arrayBuffer);
+    try {
+      return await ImageLoader.parse(arrayBuffer, this.props.loadOptions);
+    } catch {
+      throw this._parseError(arrayBuffer);
+    }
+  }
+
+  /** Get Feature Info for a coordinate */
+  async getFeatureInfo(
+    options: WMSGetFeatureInfoParameters,
+    vendorParameters?: Record<string, unknown>
+  ): Promise<WMSFeatureInfo> {
+    const url = this.getFeatureInfoURL(options, vendorParameters);
+    const response = await this.fetch(url);
+    const arrayBuffer = await response.arrayBuffer();
+    this._checkResponse(response, arrayBuffer);
+    return await WMSFeatureInfoLoader.parse(arrayBuffer, this.props.loadOptions);
+  }
+
+  /** Get Feature Info for a coordinate */
+  async getFeatureInfoText(
+    options: WMSGetFeatureInfoParameters,
+    vendorParameters?: Record<string, unknown>
+  ): Promise<string> {
+    options = {...options, info_format: 'text/plain'};
+    const url = this.getFeatureInfoURL(options, vendorParameters);
+    const response = await this.fetch(url);
+    const arrayBuffer = await response.arrayBuffer();
+    this._checkResponse(response, arrayBuffer);
+    return new TextDecoder().decode(arrayBuffer);
+  }
+
+  /** Get more information about a layer */
+  async describeLayer(
+    options: WMSDescribeLayerParameters,
+    vendorParameters?: Record<string, unknown>
+  ): Promise<WMSLayerDescription> {
+    const url = this.describeLayerURL(options, vendorParameters);
+    const response = await this.fetch(url);
+    const arrayBuffer = await response.arrayBuffer();
+    this._checkResponse(response, arrayBuffer);
+    return await WMSLayerDescriptionLoader.parse(arrayBuffer, this.props.loadOptions);
+  }
+
+  /** Get an image with a semantic legend */
+  async getLegendGraphic(
+    options: WMSGetLegendGraphicParameters,
+    vendorParameters?: Record<string, unknown>
+  ): Promise<ImageType> {
+    const url = this.getLegendGraphicURL(options, vendorParameters);
+    const response = await this.fetch(url);
+    const arrayBuffer = await response.arrayBuffer();
+    this._checkResponse(response, arrayBuffer);
+    try {
+      return await ImageLoader.parse(arrayBuffer, this.props.loadOptions);
+    } catch {
+      throw this._parseError(arrayBuffer);
+    }
+  }
+
+  // Typed URL creators
+  // For applications that want full control of fetching and parsing
+
+  /** Generate a URL for the GetCapabilities request */
+  getCapabilitiesURL(
+    wmsParameters?: WMSGetCapabilitiesParameters,
+    vendorParameters?: Record<string, unknown>
+  ): string {
+    const options: Required<WMSGetCapabilitiesParameters> = {
+      service: 'WMS',
+      version: '1.1.1',
+      request: 'GetCapabilities',
+      ...wmsParameters,
+      ...vendorParameters
+    };
+    return this._getWMSUrl(options, vendorParameters);
+  }
+
+  /** Generate a URL for the GetMap request */
+  getMapURL(
+    wmsParameters: WMSGetMapParameters,
+    vendorParameters?: Record<string, unknown>
+  ): string {
+    const options: Required<WMSGetMapParameters> = {
+      service: 'WMS',
+      version: '1.1.1',
+      request: 'GetMap',
+      // layers: [],
+      // bbox: [-77.87304, 40.78975, -77.85828, 40.80228],
+      // width: 1200,
+      // height: 900,
+      styles: undefined,
+      srs: 'EPSG:4326',
+      format: 'image/png',
+      ...wmsParameters,
+      ...vendorParameters
+    };
+    return this._getWMSUrl(options, vendorParameters);
+  }
+
+  /** Generate a URL for the GetFeatureInfo request */
+  getFeatureInfoURL(
+    wmsParameters: WMSGetFeatureInfoParameters,
+    vendorParameters?: Record<string, unknown>
+  ): string {
+    const options: Required<WMSGetFeatureInfoParameters> = {
+      service: 'WMS',
+      version: '1.1.1',
+      request: 'GetFeatureInfo',
+      // layers: [],
+      // bbox: [-77.87304, 40.78975, -77.85828, 40.80228],
+      // width: 1200,
+      // height: 900,
+      // x: undefined!,
+      // y: undefined!,
+      // query_layers: [],
+      srs: 'EPSG:4326',
+      format: 'image/png',
+      info_format: 'text/plain',
+      styles: undefined,
+      ...wmsParameters,
+      ...vendorParameters
+    };
+    return this._getWMSUrl(options, vendorParameters);
+  }
+
+  /** Generate a URL for the GetFeatureInfo request */
+  describeLayerURL(
+    wmsParameters: WMSDescribeLayerParameters,
+    vendorParameters?: Record<string, unknown>
+  ): string {
+    const options: Required<WMSDescribeLayerParameters> = {
+      service: 'WMS',
+      version: '1.1.1',
+      request: 'DescribeLayer',
+      ...wmsParameters,
+      ...vendorParameters
+    };
+    return this._getWMSUrl(options, vendorParameters);
+  }
+
+  getLegendGraphicURL(
+    wmsParameters: WMSGetLegendGraphicParameters,
+    vendorParameters?: Record<string, unknown>
+  ): string {
+    const options: Required<WMSGetLegendGraphicParameters> = {
+      service: 'WMS',
+      version: '1.1.1',
+      request: 'GetLegendGraphic',
+      ...wmsParameters,
+      ...vendorParameters
+    };
+    return this._getWMSUrl(options, vendorParameters);
+  }
+
+  // INTERNAL METHODS
+
+  /**
+   * @note case _getWMSUrl may need to be overridden to handle certain backends?
+   * */
+  protected _getWMSUrl(
+    options: Record<string, unknown>,
+    vendorParameters?: Record<string, unknown>
+  ): string {
+    let url = this.props.url;
+    let first = true;
+    for (const [key, value] of Object.entries(options)) {
+      url += first ? '?' : '&';
+      first = false;
+      if (Array.isArray(value)) {
+        url += `${key.toUpperCase()}=${value.join(',')}`;
+      } else {
+        url += `${key.toUpperCase()}=${value ? String(value) : ''}`;
+      }
+    }
+    return encodeURI(url);
+  }
+
+  /** Checks for and parses a WMS XML formatted ServiceError and throws an exception */
+  protected _checkResponse(response: Response, arrayBuffer: ArrayBuffer): void {
+    const contentType = response.headers['content-type'];
+    if (!response.ok || WMSErrorLoader.mimeTypes.includes(contentType)) {
+      const error = WMSErrorLoader.parseSync(arrayBuffer, this.props.loadOptions);
+      throw new Error(error);
+    }
+  }
+
+  /** Error situation detected */
+  protected _parseError(arrayBuffer: ArrayBuffer): Error {
+    const error = WMSErrorLoader.parseSync(arrayBuffer, this.props.loadOptions);
+    return new Error(error);
+  }
+}

package/src/lib/data-sources/image-source.ts

@@ -0,0 +1,82 @@
+// loaders.gl, MIT license
+
+import type {ImageType} from '@loaders.gl/images';
+
+/**
+ * Normalized capabilities of an Image service
+ * @example
+ *  The WMSService will normalize the response to the WMS `GetCapabilities` data structure extracted from WMS XML response
+ *  into an ImageSourceMetadata.
+ */
+export type ImageSourceMetadata = {
+  name: string;
+  title?: string;
+  abstract?: string;
+  keywords: string[];
+  layer: {
+    name: string;
+    title?: string;
+    srs?: string[];
+    boundingBox?: [number, number, number, number];
+    layers: ImageSourceLayer[];
+  };
+};
+
+export type ImageSourceLayer = {
+  name: string;
+  title?: string;
+  srs?: string[];
+  boundingBox?: [number, number, number, number];
+  layers: ImageSourceLayer[];
+};
+
+export type GetImageParameters = {
+  /** Layers to render */
+  layers: string | string[];
+  /** Styling */
+  styles?: unknown;
+  /** bounding box of the requested map image */
+  bbox: [number, number, number, number];
+  /** pixel width of returned image */
+  width: number;
+  /** pixels */
+  height: number;
+  /** srs for the image (not the bounding box) */
+  srs?: string;
+  /** requested format for the return image */
+  format?: 'image/png';
+};
+
+// Attempt to break down GetImageParameters
+export type ImageFilters = {
+  /** Layers to render */
+  layers: string | string[];
+  /** Styling */
+  styles?: unknown;
+};
+
+export type ImageRegion = {
+  /** bounding box of the requested map image */
+  bbox: [number, number, number, number];
+};
+
+export type ImageFormat = {
+  /** pixel width of returned image */
+  width: number;
+  /** pixels */
+  height: number;
+  /** srs for the image (not the bounding box) */
+  srs?: string;
+  /** requested format for the return image */
+  format?: 'image/png';
+};
+
+/**
+ * MapImageSource - data sources that allow data to be queried by (geospatial) extents
+ * @note
+ * - If geospatial, bounding box is expected to be in web mercator coordinates
+ */
+export abstract class ImageSource {
+  abstract getMetadata(): Promise<ImageSourceMetadata>;
+  abstract getImage(parameters: GetImageParameters): Promise<ImageType>;
+}