@loaders.gl/wms 3.3.2 → 3.4.0-alpha.2

package/src/lib/parsers/csw/parse-exception-report.ts

@@ -0,0 +1,31 @@
+// loaders.gl, MIT license
+
+// import type {XMLLoaderOptions} from '@loaders.gl/xml';
+// import {XMLLoader} from '@loaders.gl/xml';
+
+/**
+ * Parses a typed data structure from raw XML for `GetDomain` response
+ * @note Error handlings is fairly weak
+ */
+export function parseExceptionReport(parsedXML: any): void {
+  // const parsedXML = XMLLoader.parseTextSync(text, {
+  //   ...options,
+  //   xml: {
+  //     ...options?.xml,
+  //     removeNSPrefix: true,
+  //     uncapitalizeKeys: true
+  //   }
+  // });
+
+  const exceptionReport: any = parsedXML.exceptionReport;
+  if (!exceptionReport) {
+    return;
+  }
+  const errorMessage =
+    exceptionReport.exception?.exceptionText ||
+    exceptionReport.exception?.exceptionCode ||
+    exceptionReport.exception?.locator ||
+    'server error';
+
+  throw new Error(`Catalog Server: ${errorMessage}`);
+}

package/src/lib/{wms/wms-types.ts → parsers/wms/parse-wms-capabilities.ts}

@@ -1,4 +1,6 @@
-// loaders.gl, MIT licenses
+// loaders.gl, MIT license
+
+import {XMLLoader} from '@loaders.gl/xml';
 
 /** All capabilities of a WMS service - response to a WMS `GetCapabilities` data structure extracted from XML */
 export type WMSCapabilities = {
@@ -30,58 +32,6 @@ export type WMSRequest = {
   mimeTypes: string[];
 };
 
-// GetFeatureInfo
-
-/** WMS Feature info - response to a WMS `GetFeatureInfo` request */
-export type WMSFeatureInfo = {
-  features: WMSFeature[];
-};
-
-export type WMSFeature = {
-  attributes: Record<string, number | string>;
-  type: string;
-  bounds: {top: number; bottom: number; left: number; right: number};
-};
-
-// DescribeLayer
-
-/** Layer description - response to a WMS `DescribeLayer` request  */
-export type WMSLayerDescription = {
-  layers: {}[];
-};
-
-// // WIP
-
-// export type GetCapabilities = {
-//   request: 'GetCapabilities';
-//   format: string[];
-//   dcpType: unknown;
-// };
-
-// export type GetMap = {
-//   request: 'GetMap';
-//   format: string[];
-//   dcpType: unknown;
-// };
-
-// export type GetFeatureInfo = {
-//   request: 'GetFeatureInfo';
-//   format: string[];
-//   dcpType: unknown;
-// };
-
-// export type GetLegendGraphic = {
-//   request: 'GetLegendGraphic';
-//   format: string[];
-//   dcpType: unknown;
-// };
-
-// export type GetStyles = {
-//   request: 'GetStyles';
-//   format: string[];
-//   dcpType: unknown;
-// };
-
 /**
  * <EX_GeographicBoundingBox>
  *     <westBoundLongitude>-180</westBoundLongitude>
@@ -2051,3 +2001,72 @@ export type WMSService = {
 </Capability>
 </WMS_Capabilities>
 */
+
+/**
+ * Parses a typed data structure from raw XML for `GetCapabilities` response
+ * @note Error handlings is fairly weak
+ */
+export function parseWMSCapabilities(text: string, options): WMSCapabilities {
+  const parsedXML = XMLLoader.parseTextSync(text, options);
+  const xmlCapabilities: any =
+    parsedXML.WMT_MS_Capabilities || parsedXML.WMS_Capabilities || parsedXML;
+  return extractCapabilities(xmlCapabilities);
+}
+
+/** Extract typed capability data from XML */
+function extractCapabilities(xml: any): WMSCapabilities {
+  const capabilities: WMSCapabilities = {
+    name: xml.Service?.Name || 'unnamed',
+    title: xml.Service?.Title,
+    keywords: [],
+    requests: {},
+    layer: extractLayer(xml.Capability?.Layer),
+    raw: xml
+  };
+
+  for (const keyword of xml.Service?.KeywordList?.Keyword || []) {
+    capabilities.keywords.push(keyword);
+  }
+
+  for (const [name, xmlRequest] of Object.entries(xml.Capability?.Request || {})) {
+    capabilities.requests[name] = extractRequest(name, xmlRequest);
+  }
+
+  return capabilities;
+}
+
+/** Extract typed request data from XML */
+function extractRequest(name: string, xmlRequest: any): WMSRequest {
+  const format: string | string[] = xmlRequest?.Format;
+  const mimeTypes: string[] = Array.isArray(format) ? format : [format];
+  return {name, mimeTypes};
+}
+
+/** Extract request data */
+function extractLayer(xmlLayer: any): WMSLayer {
+  const layer: WMSLayer = {
+    name: xmlLayer?.Name,
+    title: xmlLayer?.Title,
+    srs: xmlLayer?.SRS || [],
+    layers: []
+  };
+
+  // Single layer is not represented as array in XML
+  const xmlLayers = getXMLArray(xmlLayer?.Layer);
+
+  for (const xmlSubLayer of xmlLayers) {
+    layer.layers?.push(extractLayer(xmlSubLayer));
+  }
+
+  return layer;
+}
+
+function getXMLArray(xmlValue: any) {
+  if (Array.isArray(xmlValue)) {
+    return xmlValue;
+  }
+  if (xmlValue) {
+    return [xmlValue];
+  }
+  return [];
+}

package/src/lib/parsers/wms/parse-wms-error.ts

@@ -0,0 +1,22 @@
+// loaders.gl, MIT license
+
+import {XMLLoader} from '@loaders.gl/xml';
+
+/**
+ * Extract an error message from WMS error response XML
+ * @param text
+ * @param options
+ * @returns a string with a human readable message
+ */
+export function parseWMSError(text: string, options): string {
+  const parsedXML = XMLLoader.parseTextSync?.(text, options);
+  const serviceExceptionXML =
+    parsedXML?.ServiceExceptionReport?.ServiceException ||
+    parsedXML?.['ogc:ServiceExceptionReport']?.['ogc:ServiceException'];
+  // Sigh, can be either a string or an object
+  const message =
+    typeof serviceExceptionXML === 'string'
+      ? serviceExceptionXML
+      : serviceExceptionXML.value || serviceExceptionXML.code || 'Unknown error';
+  return message;
+}

package/src/lib/parsers/wms/parse-wms-features.ts

@@ -0,0 +1,39 @@
+// loaders.gl, MIT license
+
+import {XMLLoader} from '@loaders.gl/xml';
+
+/** WMS Feature info - response to a WMS `GetFeatureInfo` request */
+export type WMSFeatureInfo = {
+  features: WMSFeature[];
+};
+
+export type WMSFeature = {
+  attributes: Record<string, number | string>;
+  type: string;
+  bounds: {top: number; bottom: number; left: number; right: number};
+};
+
+/**
+ * Parses a typed data structure from raw XML for `GetFeatureInfo` response
+ * @note Error handlings is fairly weak
+ */
+export function parseWMSFeatureInfo(text: string, options): WMSFeatureInfo {
+  const parsedXML = XMLLoader.parseTextSync(text, options);
+  const xmlFeatureInfo: any = parsedXML.FeatureInfoResponse?.FIELDS || [];
+
+  const xmlFeatures = Array.isArray(xmlFeatureInfo) ? xmlFeatureInfo : [xmlFeatureInfo];
+
+  return {
+    features: xmlFeatures.map((xmlFeature) => extractFeature(xmlFeature))
+  };
+}
+
+function extractFeature(xmlFeature: any) {
+  const xmlFields = xmlFeature || {};
+  // TODO - not correct
+  return {
+    attributes: xmlFields,
+    type: '',
+    bounds: {bottom: 0, top: 0, left: 0, right: 0}
+  };
+}

package/src/lib/parsers/wms/parse-wms-layer-description.ts

@@ -0,0 +1,18 @@
+// loaders.gl, MIT license
+
+import {XMLLoader} from '@loaders.gl/xml';
+
+/** Layer description - response to a WMS `DescribeLayer` request  */
+export type WMSLayerDescription = {
+  layers: {}[];
+};
+
+/**
+ * Parses a typed data structure from raw XML for `GetFeatureInfo` response
+ * @note Error handlings is fairly weak
+ */
+export function parseWMSLayerDescription(text: string, options): WMSLayerDescription {
+  const parsedXML = XMLLoader.parseTextSync(text, options);
+  // TODO - implement parser
+  return parsedXML as unknown as WMSLayerDescription;
+}

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

@@ -1,27 +1,34 @@
 // 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 {
+import type {ImageSourceMetadata, GetImageParameters} from '../../sources/image-source';
+import type {ImageSourceProps} from '../../sources/image-source';
+import {ImageSource} from '../../sources/image-source';
+
+export type ArcGISImageServerProps = ImageSourceProps & {
+  url: string;
+};
+
+/**
+ * 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 ArcGISImageServer 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>;
+  props: ArcGISImageServerProps;
 
-  constructor(props: ImageServiceProps) {
-    super();
-    this.props = mergeImageServiceProps(props);
-    this.fetch = getFetchFunction(this.props);
+  constructor(props: ArcGISImageServerProps) {
+    super(props);
+    this.props = props;
   }
 
   // ImageSource (normalized endpoints)
 
   async getMetadata(): Promise<ImageSourceMetadata> {
-    return (await this.info()) as ImageSourceMetadata;
+    return (await this.metadata()) as ImageSourceMetadata;
     // TODO - normalize metadata
   }
 
@@ -33,7 +40,7 @@ export class ArcGISImageService extends ImageSource {
 
   // ImageServer endpoints
 
-  async info(): Promise<unknown> {
+  async metadata(): Promise<unknown> {
     // We just need a JSON parsing...
     // return this.getUrl({path: '', ...options});
     throw new Error('not implemented');
@@ -68,18 +75,22 @@ export class ArcGISImageService extends ImageSource {
 
   // URL creators
 
-  infoURL(options: {parameters?: Record<string, unknown>}): string {
-    return this.props.url;
-    // return this.getUrl({path: '', ...options});
+  metadataURL(options: {parameters?: Record<string, unknown>}): string {
+    return `${this.props.url}?f=pjson`;
   }
 
   /** 
    * 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`,
+   // 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;
+    bbox: [number, number, number, number];
+    boxSR?: string;
     width: number;
     height: number;
     imageSR?: string;
@@ -96,11 +107,14 @@ export class ArcGISImageService extends ImageSource {
     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;
+    const bbox = `bbox=${options.bbox[0]},${options.bbox[1]},${options.bbox[2]},${options.bbox[3]}`;
+    const size = `size=${options.width},${options.height}`;
+    const arcgisOptions = {...options, bbox, size};
+    // @ts-expect-error
+    delete arcgisOptions.width;
+    // @ts-expect-error
+    delete arcgisOptions.height;
+    return this.getUrl('exportImage', arcgisOptions);
   }
 
   // INTERNAL METHODS
@@ -109,8 +123,12 @@ export class ArcGISImageService extends ImageSource {
    * @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}`;
+  protected getUrl(
+    path: string,
+    options: Record<string, unknown>,
+    extra?: Record<string, unknown>
+  ): string {
+    let url = `${this.props.url}/${path}`;
     let first = true;
     for (const [key, value] of Object.entries(options)) {
       url += first ? '?' : '&';

package/src/lib/services/arcgis/arcgis-server.ts

@@ -0,0 +1,59 @@
+// loaders.gl, MIT license
+
+export type Service = {name: string; type: string; url: string};
+
+type FetchLike = typeof fetch;
+
+/**
+ * (Recursively) load the service directory from an ArcGIS Server URL
+ * @param url
+ * @param fetchFile= Optional fetch function override
+ * @returns
+ */
+export async function getArcGISServices(
+  url: string,
+  fetchFile: FetchLike = fetch
+): Promise<Service[] | null> {
+  if (url.includes('rest/services')) {
+    const serverUrl = url.replace(/rest\/services.*$/i, 'rest/services');
+    return loadServiceDirectory(serverUrl, fetchFile, []);
+  }
+  return null;
+}
+
+async function loadServiceDirectory(
+  serverUrl: string,
+  fetch: FetchLike,
+  path: string[]
+): Promise<Service[]> {
+  const serviceUrl = `${serverUrl}/${path.join('/')}`;
+
+  const response = await fetch(`${serviceUrl}?f=pjson`);
+  const directory = await response.json();
+
+  const services = extractServices(directory, serviceUrl);
+
+  const folders = (directory.folders || []) as string[];
+  const promises = folders.map((folder) =>
+    loadServiceDirectory(`${serverUrl}`, fetch, [...path, folder])
+  );
+
+  for (const folderServices of await Promise.all(promises)) {
+    services.push(...folderServices);
+  }
+
+  return services;
+}
+
+function extractServices(directory: unknown, url: string): Service[] {
+  const arcgisServices = ((directory as any).services || []) as {name: string; type: string}[];
+  const services: Service[] = [];
+  for (const service of arcgisServices) {
+    services.push({
+      name: service.name,
+      type: `arcgis-${service.type.toLocaleLowerCase().replace('server', '-server')}`,
+      url: `${url}${service.name}/${service.type}`
+    });
+  }
+  return services;
+}

package/src/lib/{data-sources/adhoc-image-service.ts → services/generic/image-service.ts}

@@ -1,14 +1,18 @@
 // 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';
+import type {ImageSourceMetadata, GetImageParameters} from '../../sources/image-source';
+import {ImageSource} from '../../sources/image-source';
 
-export type AdHocImageServiceProps = {
-  /** Template URL string should contain `${width}` etc which will be substituted. */
-  templateUrl: string;
+/** 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;
 };
 
 /**
@@ -16,15 +20,15 @@ export type AdHocImageServiceProps = {
  * 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 AdHocImageService extends ImageSource {
+export class ImageService extends ImageSource {
   static type: 'template' = 'template';
   static testURL = (url: string): boolean => url.toLowerCase().includes('{');
 
-  templateUrl: string;
+  props: ImageServiceProps;
 
-  constructor(props: AdHocImageServiceProps) {
-    super();
-    this.templateUrl = props.templateUrl;
+  constructor(props: ImageServiceProps) {
+    super(props);
+    this.props = props;
   }
 
   // IMAGE SOURCE API
@@ -36,7 +40,7 @@ export class AdHocImageService extends ImageSource {
   async getImage(parameters: GetImageParameters): Promise<ImageType> {
     const granularParameters = this.getGranularParameters(parameters);
     const url = this.getURLFromTemplate(granularParameters);
-    const response = await fetch(url);
+    const response = await this.fetch(url);
     const arrayBuffer = await response.arrayBuffer();
     return await ImageLoader.parse(arrayBuffer);
   }
@@ -49,12 +53,14 @@ export class AdHocImageService extends ImageSource {
     return {...parameters, east, north, south, west};
   }
 
+  /** Supports both ${} and {} notations */
   protected getURLFromTemplate(parameters: Record<string, unknown>): string {
-    let url = this.templateUrl;
+    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;
   }