@loaders.gl/wms 3.4.0-alpha.3 → 4.0.0-alpha.6

package/src/lib/services/ogc/wms-service.ts

@@ -1,7 +1,6 @@
 // loaders.gl, MIT license
 
 /* eslint-disable camelcase */
-
 import type {ImageType} from '@loaders.gl/images';
 import {ImageLoader} from '@loaders.gl/images';
 import {mergeLoaderOptions} from '@loaders.gl/loader-utils';
@@ -21,68 +20,87 @@ import {WMSLayerDescriptionLoader} from '../../../wip/wms-layer-description-load
 import type {WMSLoaderOptions} from '../../../wms-error-loader';
 import {WMSErrorLoader} from '../../../wms-error-loader';
 
-/** Static WMS parameters (not viewport or selected pixel dependent) that can be provided as defaults */
+/**
+ * "Static" WMS parameters (not viewport or selected pixel dependent)
+ * These can be provided as defaults in the WMSService constructor
+ */
 export type WMSParameters = {
-  /** WMS version */
+  /** WMS version (all requests) */
   version?: '1.3.0' | '1.1.1';
-  /** Layers to render */
+  /** Layers to render (GetMap, GetFeatureInfo) */
   layers?: string[];
+  /** list of layers to query.. (GetFeatureInfo) */
+  query_layers?: string[];
+
   /** Coordinate Reference System (CRS) for the image (not the bounding box) */
   crs?: string;
-  /** Requested format for the return image */
+  /** Requested format for the return image (GetMap, GetLegendGraphic) */
   format?: 'image/png';
-  /** Requested MIME type of returned feature info */
+  /** Requested MIME type of returned feature info (GetFeatureInfo) */
   info_format?: 'text/plain' | 'application/geojson' | 'application/vnd.ogc.gml';
   /** Styling - Not yet supported */
   styles?: unknown;
-  /** Any additional parameters specific to this WMSService */
+  /** Any additional parameters specific to this WMSService (GetMap) */
   transparent?: boolean;
 };
 
-type WMSCommonParameters = {
+/** Parameters for GetCapabilities */
+export type WMSGetCapabilitiesParameters = {
   /** In case the endpoint supports multiple WMS versions */
   version?: '1.3.0' | '1.1.1';
 };
 
-/** Parameters for GetCapabilities */
-export type WMSGetCapabilitiesParameters = WMSCommonParameters;
-
 /** Parameters for GetMap */
-export type WMSGetMapParameters = WMSCommonParameters & {
-  /** Layers to render */
-  layers: string | string[];
+export type WMSGetMapParameters = {
+  /** In case the endpoint supports multiple WMS versions */
+  version?: '1.3.0' | '1.1.1';
   /** bounding box of the requested map image */
   bbox: [number, number, number, number];
   /** pixel width of returned image */
   width: number;
   /** pixels */
   height: number;
-  /** Coordinate Reference System for the image (not the bounding box). */
+  /** Layers to render - can be provided in service constructor */
+  layers?: string | string[];
+  /** Coordinate Reference System for the image (not bounding box). can be provided in service constructor. */
   crs?: string;
-  /** Styling */
+  /** Styling. can be provided in service constructor */
   styles?: unknown;
-  /** Don't render background when no data */
+  /** Don't render background when no data. can be provided in service constructor */
   transparent?: boolean;
-  /** requested format for the return image */
+  /** requested format for the return image. can be provided in service constructor */
   format?: 'image/png';
 };
 
+/** GetMap parameters that are specific to the current view */
+export type WMSGetMapViewParameters = {
+  /** pixel width of returned image */
+  width: number;
+  /** pixels */
+  height: number;
+  /** bounding box of the requested map image */
+  bbox: [number, number, number, number];
+  /** Coordinate Reference System for the image (not bounding box). can be provided in service constructor. */
+  crs?: string;
+};
+
 /**
  * Parameters for GetFeatureInfo
  * @see https://imagery.pasda.psu.edu/arcgis/services/pasda/UrbanTreeCanopy_Landcover/MapServer/WmsServer?SERVICE=WMS&
  */
-export type WMSGetFeatureInfoParameters = WMSCommonParameters & {
+export type WMSGetFeatureInfoParameters = {
+  /** In case the endpoint supports multiple WMS versions */
+  version?: '1.3.0' | '1.1.1';
   /** 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[];
-  /** Requested MIME type of returned feature info */
+  /** MIME type of returned feature info. Can be specified in service constructor */
   info_format?: 'text/plain' | 'application/geojson' | 'application/vnd.ogc.gml';
-
-  /** Layers to render */
-  layers: string[];
+  /** list of layers to query. Required but can be specified in service constructor. */
+  query_layers?: string[];
+  /** Layers to render. Required, but can be specified in service constructor */
+  layers?: string[];
   /** Styling */
   styles?: unknown;
   /** bounding box of the requested map image */
@@ -92,16 +110,36 @@ export type WMSGetFeatureInfoParameters = WMSCommonParameters & {
   /** pixels */
   height: number;
   /** srs for the image (not the bounding box) */
-  srs?: string;
-  /** requested format for the return image */
-  format?: 'image/png';
+  crs?: string;
+};
+
+/** GetMap parameters that are specific to the current view */
+export type WMSGetFeatureInfoViewParameters = {
+  /** x coordinate for the feature info request */
+  x: number;
+  /** y coordinate for the feature info request */
+  y: number;
+  /** pixel width of returned image */
+  width: number;
+  /** pixels */
+  height: number;
+  /** bounding box of the requested map image */
+  bbox: [number, number, number, number];
+  /** srs for the image (not the bounding box) */
+  crs?: string;
 };
 
 /** Parameters for DescribeLayer */
-export type WMSDescribeLayerParameters = WMSCommonParameters;
+export type WMSDescribeLayerParameters = {
+  /** In case the endpoint supports multiple WMS versions */
+  version?: '1.3.0' | '1.1.1';
+};
 
 /** Parameters for GetLegendGraphic */
-export type WMSGetLegendGraphicParameters = WMSCommonParameters;
+export type WMSGetLegendGraphicParameters = {
+  /** In case the endpoint supports multiple WMS versions */
+  version?: '1.3.0' | '1.1.1';
+};
 
 //
 
@@ -109,6 +147,9 @@ export type WMSGetLegendGraphicParameters = WMSCommonParameters;
 export type WMSServiceProps = ImageSourceProps & {
   /** Base URL to the service */
   url: string;
+  /** In 1.3.0, replaces references to EPSG:4326 with CRS:84 */
+  substituteCRS84?: boolean;
+
   /** Default WMS parameters. If not provided here, must be provided in the various request */
   wmsParameters?: WMSParameters;
   /** Any additional service specific parameters */
@@ -122,11 +163,18 @@ export type WMSServiceProps = ImageSourceProps & {
  * - implements the ImageService interface
  * @note Only the URL parameter conversion is supported. XML posts are not supported.
  */
-export class WMSService extends ImageSource {
+export class WMSService extends ImageSource<WMSServiceProps> {
   static type: 'wms' = 'wms';
   static testURL = (url: string): boolean => url.toLowerCase().includes('wms');
 
+  /** Base URL to the service */
   readonly url: string;
+
+  /** In WMS 1.3.0, replaces references to EPSG:4326 with CRS:84. But not always supported. Default: false */
+  substituteCRS84: boolean;
+  /** In WMS 1.3.0, flips x,y (lng, lat) coordinates for the supplied coordinate systems. Default: ['ESPG:4326'] */
+  flipCRS: string[];
+
   /** Default static WMS parameters */
   wmsParameters: Required<WMSParameters>;
   /** Default static vendor parameters */
@@ -153,8 +201,12 @@ export class WMSService extends ImageSource {
 
     this.url = props.url;
 
+    this.substituteCRS84 = props.substituteCRS84 ?? false;
+    this.flipCRS = ['EPSG:4326'];
+
     this.wmsParameters = {
       layers: undefined!,
+      query_layers: undefined!,
       styles: undefined,
       version: '1.3.0',
       crs: 'EPSG:4326',
@@ -174,10 +226,7 @@ export class WMSService extends ImageSource {
   }
 
   async getImage(parameters: GetImageParameters): Promise<ImageType> {
-    // WMS 1.3.0 renamed SRS to CRS (sigh...)
-    const wmsParameters = {...parameters, crs: parameters.srs};
-    delete wmsParameters.srs;
-    return await this.getMap(wmsParameters);
+    return await this.getMap(parameters);
   }
 
   normalizeMetadata(capabilities: WMSCapabilities): ImageSourceMetadata {
@@ -288,16 +337,17 @@ export class WMSService extends ImageSource {
     wmsParameters: WMSGetMapParameters,
     vendorParameters?: Record<string, unknown>
   ): string {
+    wmsParameters = this._getWMS130Parameters(wmsParameters);
     const options: Required<WMSGetMapParameters> = {
       version: this.wmsParameters.version,
-      // layers: [],
+      format: this.wmsParameters.format,
+      transparent: this.wmsParameters.transparent,
+      layers: this.wmsParameters.layers,
+      styles: this.wmsParameters.styles,
+      crs: this.wmsParameters.crs,
       // bbox: [-77.87304, 40.78975, -77.85828, 40.80228],
       // width: 1200,
       // height: 900,
-      styles: this.wmsParameters.styles,
-      crs: this.wmsParameters.crs,
-      format: this.wmsParameters.format,
-      transparent: this.wmsParameters.transparent,
       ...wmsParameters
     };
     return this._getWMSUrl('GetMap', options, vendorParameters);
@@ -310,17 +360,18 @@ export class WMSService extends ImageSource {
   ): string {
     const options: Required<WMSGetFeatureInfoParameters> = {
       version: this.wmsParameters.version,
-      // layers: this.props.layers,
+      // query_layers: [],
+      // format: this.wmsParameters.format,
+      info_format: this.wmsParameters.info_format,
+      layers: this.wmsParameters.layers,
+      query_layers: this.wmsParameters.query_layers,
+      styles: this.wmsParameters.styles,
+      crs: this.wmsParameters.crs,
       // bbox: [-77.87304, 40.78975, -77.85828, 40.80228],
       // width: 1200,
       // height: 900,
       // x: undefined!,
       // y: undefined!,
-      // query_layers: [],
-      srs: this.wmsParameters.crs,
-      format: this.wmsParameters.format,
-      info_format: this.wmsParameters.info_format,
-      styles: this.wmsParameters.styles,
       ...wmsParameters
     };
     return this._getWMSUrl('GetFeatureInfo', options, vendorParameters);
@@ -372,7 +423,7 @@ export class WMSService extends ImageSource {
    * */
   protected _getWMSUrl(
     request: string,
-    wmsParameters: WMSCommonParameters & {[key: string]: unknown},
+    wmsParameters: {version?: '1.3.0' | '1.1.1'; [key: string]: unknown},
     vendorParameters?: Record<string, unknown>
   ): string {
     let url = this.url;
@@ -394,34 +445,88 @@ export class WMSService extends ImageSource {
       if (key !== 'transparent' || value) {
         url += first ? '?' : '&';
         first = false;
-        url += this._getParameterValue(wmsParameters.version!, key, value);
+        url += this._getURLParameter(key, value, wmsParameters);
       }
     }
 
     return encodeURI(url);
   }
 
-  _getParameterValue(version: string, key: string, value: unknown): string {
-    // SRS parameter changed to CRS in 1.3.0, in non-backwards compatible way (sigh...)
-    if (key === 'crs' && version !== '1.3.0') {
-      key = 'srs';
+  _getWMS130Parameters<ParametersT extends {crs?: string; srs?: string}>(
+    wmsParameters: ParametersT
+  ): ParametersT {
+    const newParameters = {...wmsParameters};
+    if (newParameters.srs) {
+      newParameters.crs = newParameters.crs || newParameters.srs;
+      delete newParameters.srs;
     }
+    return newParameters;
+  }
 
-    key = key.toUpperCase();
+  // eslint-disable-complexity
+  _getURLParameter(key: string, value: unknown, wmsParameters: WMSParameters): string {
+    // Substitute by key
+    switch (key) {
+      case 'crs':
+        // CRS was called SRS before WMS 1.3.0
+        if (wmsParameters.version !== '1.3.0') {
+          key = 'srs';
+        } else if (this.substituteCRS84 && value === 'EPSG:4326') {
+          /** In 1.3.0, replaces references to 'EPSG:4326' with the new backwards compatible CRS:84 */
+          // Substitute by value
+          value = 'CRS:84';
+        }
+        break;
+
+      case 'srs':
+        // CRS was called SRS before WMS 1.3.0
+        if (wmsParameters.version === '1.3.0') {
+          key = 'crs';
+        }
+        break;
+
+      case 'bbox':
+        // Coordinate order is flipped for certain CRS in WMS 1.3.0
+        const bbox = this._flipBoundingBox(value, wmsParameters);
+        if (bbox) {
+          value = bbox;
+        }
+        break;
+
+      default:
+      // do nothing
+    }
 
-    // TODO - in v1.3.0 only, the order of parameters for BBOX depends on whether the CRS definition has flipped axes
-    // You will see this in the GetCapabilities request at 1.3.0 - the response should show the flipped axes.
-    // BBOX=xmin,ymin,xmax,ymax NON-FLIPPED
-    // BBOX=ymin,xmin,ymax,xmax FLIPPED
-    // / EPSG:4326 needs to have flipped axes. 4326 1 WGS 84 Latitude North Longitude East
-    // In WMS 1.1.1 EPSG:4326 is wrongly defined as having long/lat coordinate axes. In WMS 1.3.0 the correct axes lat/long are used. CRS:84 is defined by OGC as having the same datum as EPSG:4326 (that is the World Geodetic System 1984 datum ~ EPSG::6326) but axis order of long/lat.
-    // CRS:84 was introduced with the publication of the WMS 1.3.0 specification, to overcome this issue.
+    key = key.toUpperCase();
 
     return Array.isArray(value)
       ? `${key}=${value.join(',')}`
       : `${key}=${value ? String(value) : ''}`;
   }
 
+  /** Coordinate order is flipped for certain CRS in WMS 1.3.0 */
+  _flipBoundingBox(
+    bboxValue: unknown,
+    wmsParameters: WMSParameters
+  ): [number, number, number, number] | null {
+    // Sanity checks
+    if (!Array.isArray(bboxValue) || bboxValue.length !== 4) {
+      return null;
+    }
+
+    const flipCoordinates =
+      // Only affects WMS 1.3.0
+      wmsParameters.version === '1.3.0' &&
+      // Flip if we are dealing with a CRS that was flipped in 1.3.0
+      this.flipCRS.includes(wmsParameters.crs || '') &&
+      // Don't flip if we are subsituting EPSG:4326 with CRS:84
+      !(this.substituteCRS84 && wmsParameters.crs === 'EPSG:4326');
+
+    const bbox = bboxValue as [number, number, number, number];
+    return flipCoordinates ? [bbox[1], bbox[0], bbox[3], bbox[2]] : bbox;
+  }
+
+  /** Fetches an array buffer and checks the response (boilerplate reduction) */
   protected async _fetchArrayBuffer(url: string): Promise<ArrayBuffer> {
     const response = await this.fetch(url);
     const arrayBuffer = await response.arrayBuffer();

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

@@ -8,16 +8,43 @@ export type DataSourceProps = {
 };
 
 /** base class of all data sources */
-export abstract class DataSource {
+export abstract class DataSource<PropsT extends DataSourceProps> {
   /** A resolved fetch function extracted from loadOptions prop */
   fetch: (url: string, options?: RequestInit) => Promise<Response>;
   /** The actual load options, if calling a loaders.gl loader */
   loadOptions: LoaderOptions;
+  _needsRefresh: boolean = true;
 
-  constructor(props: DataSourceProps) {
+  props: PropsT;
+
+  constructor(props: PropsT) {
+    this.props = {...props};
     this.loadOptions = {...props.loadOptions};
     this.fetch = getFetchFunction(this.loadOptions);
   }
+
+  setProps(props: PropsT) {
+    this.props = Object.assign(this.props, props);
+    // TODO - add a shallow compare to avoid setting refresh if no change?
+    this.setNeedsRefresh();
+  }
+
+  /** Mark this data source as needing a refresh (redraw) */
+  setNeedsRefresh(): void {
+    this._needsRefresh = true;
+  }
+
+  /**
+   * Does this data source need refreshing?
+   * @note The specifics of the refresh mechanism depends on type of data source
+   */
+  getNeedsRefresh(clear: boolean = true) {
+    const needsRefresh = this._needsRefresh;
+    if (clear) {
+      this._needsRefresh = false;
+    }
+    return needsRefresh;
+  }
 }
 
 /**

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

@@ -21,7 +21,7 @@ export type ImageSourceMetadata = {
 export type ImageSourceLayer = {
   name?: string;
   title?: string;
-  srs?: string[];
+  crs?: string[];
   boundingBox?: [number, number, number, number];
   layers?: ImageSourceLayer[];
 };
@@ -37,8 +37,8 @@ export type GetImageParameters = {
   width: number;
   /** pixels */
   height: number;
-  /** srs for the image (not the bounding box) */
-  srs?: string;
+  /** crs for the image (not the bounding box) */
+  crs?: string;
   /** requested format for the return image */
   format?: 'image/png';
 };
@@ -61,8 +61,8 @@ export type ImageFormat = {
   width: number;
   /** pixels */
   height: number;
-  /** srs for the image (not the bounding box) */
-  srs?: string;
+  /** crs for the image (not the bounding box) */
+  crs?: string;
   /** requested format for the return image */
   format?: 'image/png';
 };
@@ -74,7 +74,7 @@ export type ImageSourceProps = DataSourceProps;
  * @note
  * - If geospatial, bounding box is expected to be in web mercator coordinates
  */
-export abstract class ImageSource extends DataSource {
+export abstract class ImageSource<PropsT extends ImageSourceProps> extends DataSource<PropsT> {
   abstract getMetadata(): Promise<ImageSourceMetadata>;
   abstract getImage(parameters: GetImageParameters): Promise<ImageType>;
 }

package/src/lib/sources/tile-source.ts

@@ -1,7 +1,7 @@
 // loaders.gl, MIT license
 
 import type {ImageType} from '@loaders.gl/images';
-import {DataSource} from './data-source';
+import {DataSource, DataSourceProps} from './data-source';
 
 /**
  * Normalized capabilities of an Image service
@@ -48,12 +48,14 @@ export type GetTileParameters = {
   format?: 'image/png';
 };
 
+type TileSourceProps = DataSourceProps;
+
 /**
  * MapTileSource - 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 TileSource extends DataSource {
+export abstract class TileSource<PropsT extends TileSourceProps> extends DataSource<PropsT> {
   abstract getMetadata(): Promise<TileSourceMetadata>;
   abstract getTile(parameters: GetTileParameters): Promise<ImageType>;
 }

package/src/lib/wfs/parse-wfs.ts

@@ -0,0 +1,34 @@
+// loaders.gl, MIT license
+
+import {XMLLoader} from '@loaders.gl/xml';
+
+export type WFSCapabilities = {};
+
+/**
+ * Parses a typed data structure from raw XML for `GetCapabilities` response
+ * @note Error handlings is fairly weak
+ */
+export function parseWFSCapabilities(text: string, options): WFSCapabilities {
+  // Remove namespaces in XML
+  options = {...options, xml: {...options?.xml, removeNSPrefix: true}};
+  const parsedXML = XMLLoader.parseTextSync?.(text, options);
+  const xmlCapabilities: any = parsedXML.Capabilities || parsedXML;
+  return uncapitalizeKeys(xmlCapabilities);
+}
+
+/** Uncapitalize all keys of an object */
+function uncapitalizeKeys(object: any): any {
+  if (object && typeof object === 'object') {
+    const newObject = {};
+    for (const [key, value] of Object.entries(object)) {
+      newObject[uncapitalize(key)] = uncapitalizeKeys(value);
+    }
+    return newObject;
+  }
+  return object;
+}
+
+/** Uncapitalize first letter of a string */
+function uncapitalize(str: string): string {
+  return typeof str === 'string' ? str.charAt(0).toLowerCase() + str.slice(1) : str;
+}

package/src/lib/wmts/parse-wmts.ts

@@ -0,0 +1,37 @@
+// loaders.gl, MIT license
+
+import {XMLLoader} from '@loaders.gl/xml';
+
+export type WMTSCapabilities = {};
+
+/**
+ * Parses a typed data structure from raw XML for `GetCapabilities` response
+ * @note Error handlings is fairly weak
+ */
+export function parseWMTSCapabilities(text: string, options): WMTSCapabilities {
+  // Remove namespaces in XML
+  options = {...options, xml: {...options?.xml, removeNSPrefix: true}};
+  const parsedXML = XMLLoader.parseTextSync?.(text, options);
+  const xmlCapabilities: any = parsedXML.Capabilities || parsedXML;
+  return uncapitalizeKeys(xmlCapabilities);
+}
+
+function uncapitalizeKeys(object: any): any {
+  if (object && typeof object === 'object') {
+    const newObject = {};
+    for (const [key, value] of Object.entries(object)) {
+      newObject[uncapitalize(key)] = uncapitalizeKeys(value);
+    }
+    return newObject;
+  }
+  return object;
+}
+
+/**
+ * Uncapitalize first letter of a string
+ * @param {string} str
+ * @returns {string}
+ */
+function uncapitalize(str: string): string {
+  return typeof str === 'string' ? str.charAt(0).toLowerCase() + str.slice(1) : str;
+}

package/src/wip/lib/wcs/parse-wcs-capabilities.ts

@@ -83,7 +83,7 @@ export type WCSCapabilities = {
  * @note Error handlings is fairly weak
  */
 export function parseWCSCapabilities(text: string, options): WCSCapabilities {
-  const parsedXML = XMLLoader.parseTextSync(text, {...options, xml: {...options?.xml, removeNSPrefix: true}});
+  const parsedXML = XMLLoader.parseTextSync?.(text, {...options, xml: {...options?.xml, removeNSPrefix: true}});
   const xmlCapabilities: any = parsedXML.Capabilities || parsedXML;
   return xmlCapabilities;
 }

package/src/wip/lib/wfs/parse-wfs-capabilities.ts

@@ -83,7 +83,7 @@ export type WFSCapabilities = {
  * @note Error handlings is fairly weak
  */
 export function parseWFSCapabilities(text: string, options): WFSCapabilities {
-  const parsedXML = XMLLoader.parseTextSync(text, {...options, xml: {
+  const parsedXML = XMLLoader.parseTextSync?.(text, {...options, xml: {
     ...options?.xml, 
     removeNSPrefix: true,
     uncapitalizeKeys: true

package/src/wip/lib/wmts/parse-wmts-capabilities.ts

@@ -90,7 +90,7 @@ export type WMTSTileMatrixSet = {
  * @note Error handlings is fairly weak
  */
 export function parseWMTSCapabilities(text: string, options): WMTSCapabilities {
-  const parsedXML = XMLLoader.parseTextSync(text, {...options, xml: {
+  const parsedXML = XMLLoader.parseTextSync?.(text, {...options, xml: {
     ...options?.xml, 
     removeNSPrefix: true,
     uncapitalizeKeys: true

package/dist/es5/lib/services/generic/tile-service.js

@@ -1,2 +0,0 @@
-"use strict";
-//# sourceMappingURL=tile-service.js.map

package/dist/es5/lib/services/generic/tile-service.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"tile-service.js","names":[],"sources":["../../../../../src/lib/services/generic/tile-service.ts"],"sourcesContent":[""],"mappings":""}

package/dist/esm/lib/services/generic/tile-service.js

@@ -1,2 +0,0 @@
-
-//# sourceMappingURL=tile-service.js.map

package/dist/esm/lib/services/generic/tile-service.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"tile-service.js","names":[],"sources":["../../../../../src/lib/services/generic/tile-service.ts"],"sourcesContent":[""],"mappings":""}

package/dist/lib/services/generic/tile-service.d.ts

@@ -1 +0,0 @@
-//# sourceMappingURL=tile-service.d.ts.map

package/dist/lib/services/generic/tile-service.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"tile-service.d.ts","sourceRoot":"","sources":["../../../../src/lib/services/generic/tile-service.ts"],"names":[],"mappings":""}

package/dist/lib/services/generic/tile-service.js

@@ -1 +0,0 @@
-"use strict";