@loaders.gl/wms 4.0.0-alpha.6 → 4.0.0-alpha.8

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

@@ -73,6 +73,9 @@ export type WMSLayer = {
   // FeatureListURL
   // DataURL
 
+  /** any extra dimension such as time */
+  dimensions?: WMSDimension[];
+
   /** Whether queries can be performed on the layer */
   queryable?: boolean;
   /** `false` if layer has significant no-data areas that the client can display as transparent. */
@@ -105,6 +108,30 @@ export type WMSBoundingBox = {
   yResolution?: number;
 };
 
+/**
+ * An optional dimension that can be queried using the `name=...` parameter
+ * Note that layers that have at least one dimension without `default` value
+ * become unrenderable unless the dimension value is supplied to GetMap requests.
+ */
+export type WMSDimension = {
+  /** name of dimension, becomes a valid parameter key for this layer */
+  name: string;
+  /** Textual units for this dimensional axis */
+  units: string;
+  /** Unit symbol for this dimensional axis */
+  unitSymbol?: string;
+  /** Default value if no value is supplied. If dimension lacks defaultValue, requests fail if no value is supplied */
+  defaultValue?: string;
+  /** Can multiple values of the dimension be requested? */
+  multipleValues?: boolean;
+  /* Will nearest values will be substituted when out of range, if false exact values are required */
+  nearestValue?: boolean;
+  /** A special value "current" is supported, typically for time dimension */
+  current?: boolean;
+  /** Text content indicating available values for dimension */
+  extent: string;
+};
+
 /** Metadata about a supported WMS request  */
 export type WMSRequest = {
   /** MIMEtypes that can be returned by this request. */
@@ -116,7 +143,7 @@ export type WMSExceptions = {
   mimeTypes: string[];
 };
 
-export type parseWMSCapabilitiesOptions = {
+export type ParseWMSCapabilitiesOptions = {
   /** Add inherited layer information to sub layers */
   inheritedLayerProps?: boolean;
   /** Include the "raw" JSON (parsed but untyped, unprocessed XML). May contain additional fields */
@@ -125,7 +152,6 @@ export type parseWMSCapabilitiesOptions = {
   includeXMLText?: boolean;
   /** @deprecated Use includeRawData` */
   raw?: boolean;
-
   // xml options are passed through to xml loader
 };
 
@@ -135,7 +161,7 @@ export type parseWMSCapabilitiesOptions = {
  */
 export function parseWMSCapabilities(
   xmlText: string,
-  options?: parseWMSCapabilitiesOptions
+  options?: ParseWMSCapabilitiesOptions
 ): WMSCapabilities {
   const parsedXML = XMLLoader.parseTextSync?.(xmlText, options);
   const xmlCapabilities: any =
@@ -227,8 +253,8 @@ function extractLayer(xmlLayer: any): WMSLayer {
     // All layers must have a title
     title: String(xmlLayer?.Title || ''),
     // Name is required only if renderable
-    name: String(xmlLayer?.Name),
-    abstract: String(xmlLayer?.Abstract),
+    name: xmlLayer?.Name && String(xmlLayer?.Name),
+    abstract: xmlLayer?.Name && String(xmlLayer?.Abstract),
     keywords: getXMLStringArray(xmlLayer.KeywordList?.Keyword)
   };
 
@@ -258,6 +284,13 @@ function extractLayer(xmlLayer: any): WMSLayer {
     layer.boundingBoxes = boundingBoxes;
   }
 
+  // Extract dimensions
+  const xmlDimensions = getXMLArray(xmlLayer?.Dimension);
+  const dimensions = xmlDimensions.map((xml) => extractDimension(xml));
+  if (dimensions.length) {
+    layer.dimensions = dimensions;
+  }
+
   if (xmlLayer?.opaque) {
     layer.opaque = getXMLBoolean(xmlLayer?.opaque);
   }
@@ -339,22 +372,54 @@ function extractWMSBoundingBox(xmlBoundingBox: any): WMSBoundingBox {
   return boundingBox;
 }
 
+/**
+ * Extracts optional WMS Dimension layer field
+ * @param xmlDimension
+ * @example <Dimension name="time" units="ISO8601" default="2018-01-01" nearestValue="0">2001-01-01/2018-01-01/P1Y</Dimension>
+ * @see https://mapserver.org/ogc/wms_dimension.html
+ */
+function extractDimension(xmlDimension: any): WMSDimension {
+  const {name, units, value: extent} = xmlDimension;
+
+  const dimension: WMSDimension = {name, units, extent};
+
+  if (xmlDimension.unitSymbol) {
+    dimension.unitSymbol = xmlDimension.unitSymbol;
+  }
+  if (xmlDimension.default) {
+    dimension.defaultValue = xmlDimension.default;
+  }
+  if (xmlDimension.multipleValues) {
+    dimension.multipleValues = getXMLBoolean(xmlDimension.multipleValues);
+  }
+  if (xmlDimension.nearestValue) {
+    dimension.nearestValue = getXMLBoolean(xmlDimension.nearestValue);
+  }
+  if (xmlDimension.current) {
+    dimension.current = getXMLBoolean(xmlDimension.current);
+  }
+
+  return dimension;
+}
+
 /** Traverse layers and inject missing props from parents */
 // eslint-disable-next-line complexity
 function addInheritedLayerProps(layer: WMSLayer, parent: WMSLayer | null): void {
-  if (parent && parent.geographicBoundingBox && !layer.geographicBoundingBox) {
+  if (parent?.geographicBoundingBox && !layer.geographicBoundingBox) {
     layer.geographicBoundingBox = [...parent.geographicBoundingBox];
   }
 
-  if (parent && parent.crs && !layer.crs) {
+  if (parent?.crs && !layer.crs) {
     layer.crs = [...parent.crs];
   }
 
-  if (parent && parent.boundingBoxes && !layer.boundingBoxes) {
+  if (parent?.boundingBoxes && !layer.boundingBoxes) {
     layer.boundingBoxes = [...parent.boundingBoxes];
   }
 
-  // TODO inherit other elements
+  if (parent?.dimensions && !layer.dimensions) {
+    layer.dimensions = [...parent.dimensions];
+  }
 
   for (const subLayer of layer.layers || []) {
     addInheritedLayerProps(subLayer, layer);

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

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

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

@@ -20,7 +20,7 @@ type CSWCommonParameters = {
   /** In case the endpoint supports multiple services */
   service?: 'CSW';
   /** In case the endpoint supports multiple CSW versions */
-  version?: '1.1.1' | '2.0.0' | '2.0.1' | '3.0.0' | '3.0.0';
+  version?: '1.1.1' | '2.0.0' | '2.0.1' | '3.0.0';
 };
 
 export type CSWGetCapabilitiesParameters = CSWCommonParameters & {
@@ -41,17 +41,25 @@ export type CSWGetDomainParameters = CSWCommonParameters & {
   // TBA
 };
 
-export type Service = {name: string; type: string; url: string; params?: string; scheme?: string};
+/** Describes a service or resource exposed by the catalog */
+export type Service = {
+  /** name of service or resource */
+  name: string;
+  /** type of service or resource */
+  type: string;
+  url: string;
+  params?: string;
+  scheme?: string;
+};
 
 export type CSWServiceProps = DataSourceProps & {
   url: string;
 };
 
 /**
- * The CSWService class provides
+ * The CSWService class
  * - provides type safe methods to form URLs to a CSW service
  * - provides type safe methods to query and parse results (and errors) from a CSW service
- * - implements the ImageService interface
  * @note Only the URL parameter conversion is supported. XML posts are not supported.
  */
 export class CSWService extends DataSource<CSWServiceProps> {

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

@@ -42,6 +42,10 @@ export type WMSParameters = {
   styles?: unknown;
   /** Any additional parameters specific to this WMSService (GetMap) */
   transparent?: boolean;
+  /** If layer supports time dimension */
+  time?: string;
+  /** If layer supports elevation dimension */
+  elevation?: string;
 };
 
 /** Parameters for GetCapabilities */
@@ -60,6 +64,8 @@ export type WMSGetMapParameters = {
   width: number;
   /** pixels */
   height: number;
+  /** requested format for the return image. can be provided in service constructor */
+  format?: 'image/png';
   /** 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. */
@@ -68,8 +74,10 @@ export type WMSGetMapParameters = {
   styles?: unknown;
   /** Don't render background when no data. can be provided in service constructor */
   transparent?: boolean;
-  /** requested format for the return image. can be provided in service constructor */
-  format?: 'image/png';
+  /** If layer supports time dimension */
+  time?: string;
+  /** If layer supports elevation dimension */
+  elevation?: string;
 };
 
 /** GetMap parameters that are specific to the current view */
@@ -213,6 +221,8 @@ export class WMSService extends ImageSource<WMSServiceProps> {
       format: 'image/png',
       info_format: 'text/plain',
       transparent: undefined!,
+      time: undefined!,
+      elevation: undefined!,
       ...props.wmsParameters
     };
 
@@ -342,6 +352,8 @@ export class WMSService extends ImageSource<WMSServiceProps> {
       version: this.wmsParameters.version,
       format: this.wmsParameters.format,
       transparent: this.wmsParameters.transparent,
+      time: this.wmsParameters.time,
+      elevation: this.wmsParameters.elevation,
       layers: this.wmsParameters.layers,
       styles: this.wmsParameters.styles,
       crs: this.wmsParameters.crs,
@@ -440,9 +452,10 @@ export class WMSService extends ImageSource<WMSServiceProps> {
     };
 
     // Encode the keys
+    const IGNORE_EMPTY_KEYS = ['transparent', 'time', 'elevation'];
     for (const [key, value] of Object.entries(allParameters)) {
       // hack to preserve test cases. Not super clear if keys should be included when values are undefined
-      if (key !== 'transparent' || value) {
+      if (!IGNORE_EMPTY_KEYS.includes(key) || value) {
         url += first ? '?' : '&';
         first = false;
         url += this._getURLParameter(key, value, wmsParameters);

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

@@ -7,8 +7,8 @@ import {DataSource} from './data-source';
 /**
  * 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.
+ *  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;
@@ -18,14 +18,24 @@ export type ImageSourceMetadata = {
   layers: ImageSourceLayer[];
 };
 
+/** Description of one data layer in the image source */
 export type ImageSourceLayer = {
+  /** Name of this layer */
   name?: string;
+  /** Human readable title of this layer */
   title?: string;
+  /** Coordinate systems supported by this layer */
   crs?: string[];
-  boundingBox?: [number, number, number, number];
+  /** layer limits in unspecified CRS:84-like lng/lat, for quick access w/o CRS calculations. */
+  geographicBoundingBox?: [min: [x: number, y: number], max: [x: number, y: number]];
+  /** Sub layers of this layer */
   layers?: ImageSourceLayer[];
+
+  /** @deprecated from v3.4: non-vis.gl style bounding box. Use `.geographicBoundingBox` instead */
+  boundingBox?: [number, number, number, number];
 };
 
+/** Generic parameters for requesting an image from an image source */
 export type GetImageParameters = {
   /** Layers to render */
   layers: string | string[];
@@ -74,7 +84,9 @@ export type ImageSourceProps = DataSourceProps;
  * @note
  * - If geospatial, bounding box is expected to be in web mercator coordinates
  */
-export abstract class ImageSource<PropsT extends ImageSourceProps> extends DataSource<PropsT> {
+export abstract class ImageSource<
+  PropsT extends ImageSourceProps = ImageSourceProps
+> extends DataSource<PropsT> {
   abstract getMetadata(): Promise<ImageSourceMetadata>;
   abstract getImage(parameters: GetImageParameters): Promise<ImageType>;
 }

package/src/wip/wms-feature-info-loader.ts

@@ -1,7 +1,8 @@
 // loaders.gl, MIT license
 
 import type {LoaderWithParser} from '@loaders.gl/loader-utils';
-import {WMSCapabilitiesLoader, WMSLoaderOptions} from '../wms-capabilities-loader';
+import type {XMLLoaderOptions} from '@loaders.gl/xml';
+import {WMSCapabilitiesLoader} from '../wms-capabilities-loader';
 
 import type {WMSFeatureInfo} from '../lib/parsers/wms/parse-wms-features';
 import {parseWMSFeatureInfo} from '../lib/parsers/wms/parse-wms-features';
@@ -17,9 +18,9 @@ export const WMSFeatureInfoLoader = {
   id: 'wms-feature-info',
   name: 'WMS FeatureInfo',
 
-  parse: async (arrayBuffer: ArrayBuffer, options?: WMSLoaderOptions) =>
+  parse: async (arrayBuffer: ArrayBuffer, options?: XMLLoaderOptions) =>
     parseWMSFeatureInfo(new TextDecoder().decode(arrayBuffer), options),
-  parseTextSync: (text: string, options?: WMSLoaderOptions) => parseWMSFeatureInfo(text, options)
+  parseTextSync: (text: string, options?: XMLLoaderOptions) => parseWMSFeatureInfo(text, options)
 };
 
 export const _typecheckWMSFeatureInfoLoader: LoaderWithParser = WMSFeatureInfoLoader;

package/src/wip/wms-layer-description-loader.ts

@@ -1,7 +1,7 @@
 // loaders.gl, MIT license
 
 import type {LoaderWithParser} from '@loaders.gl/loader-utils';
-import type{WMSLoaderOptions} from '../wms-capabilities-loader';
+import type {XMLLoaderOptions} from '@loaders.gl/xml';
 import {WMSCapabilitiesLoader} from '../wms-capabilities-loader';
 
 import type {WMSLayerDescription} from '../lib/parsers/wms/parse-wms-layer-description';
@@ -18,9 +18,9 @@ export const WMSLayerDescriptionLoader = {
   id: 'wms-layer-description',
   name: 'WMS DescribeLayer',
 
-  parse: async (arrayBuffer: ArrayBuffer, options?: WMSLoaderOptions) =>
+  parse: async (arrayBuffer: ArrayBuffer, options?: XMLLoaderOptions) =>
     parseWMSLayerDescription(new TextDecoder().decode(arrayBuffer), options),
-  parseTextSync: (text: string, options?: WMSLoaderOptions) => parseWMSLayerDescription(text, options)
+  parseTextSync: (text: string, options?: XMLLoaderOptions) => parseWMSLayerDescription(text, options)
 };
 
 export const _typecheckWMSFeatureInfoLoader: LoaderWithParser = WMSLayerDescriptionLoader;

package/src/wip/wmts-capabilities-loader.ts

@@ -1,6 +1,7 @@
 // loaders.gl, MIT license
 
-import type {LoaderWithParser, LoaderOptions} from '@loaders.gl/loader-utils';
+import type {LoaderWithParser} from '@loaders.gl/loader-utils';
+import type {XMLLoaderOptions} from '@loaders.gl/xml';
 // import type {WMTSCapabilities} from './lib/wmts/parse-wmts-capabilities';
 import {parseWMTSCapabilities} from './lib/wmts/parse-wmts-capabilities';
 
@@ -10,7 +11,7 @@ const VERSION = typeof __VERSION__ !== 'undefined' ? __VERSION__ : 'latest';
 
 // export type {WMTSCapabilities};
 
-export type WMTSLoaderOptions = LoaderOptions & {
+export type WMTSLoaderOptions = XMLLoaderOptions & {
   wmts?: {};
 };
 

package/src/wms-capabilities-loader.ts

@@ -1,21 +1,32 @@
 // loaders.gl, MIT license
 
-import type {LoaderWithParser, LoaderOptions} from '@loaders.gl/loader-utils';
-import type {WMSCapabilities} from './lib/parsers/wms/parse-wms-capabilities';
+import type {LoaderWithParser} from '@loaders.gl/loader-utils';
+import type {XMLLoaderOptions} from '@loaders.gl/xml';
 import {parseWMSCapabilities} from './lib/parsers/wms/parse-wms-capabilities';
 
 // __VERSION__ is injected by babel-plugin-version-inline
 // @ts-ignore TS2304: Cannot find name '__VERSION__'.
 const VERSION = typeof __VERSION__ !== 'undefined' ? __VERSION__ : 'latest';
 
-// Parsed data type
-export type {WMSCapabilities};
-
-export type WMSLoaderOptions = LoaderOptions & {
+// Parsed data types
+export type {
+  WMSCapabilities,
+  WMSLayer,
+  WMSBoundingBox,
+  WMSDimension,
+  WMSRequest,
+  WMSExceptions
+} from './lib/parsers/wms/parse-wms-capabilities';
+
+export type WMSCapabilitiesLoaderOptions = XMLLoaderOptions & {
   wms?: {
     /** Add inherited layer information to sub layers */
     inheritedLayerProps?: boolean;
-    /** Whether to include "raw" XML-derived JSON */
+    /** Include the "raw" JSON (parsed but untyped, unprocessed XML). May contain additional fields */
+    includeRawData?: boolean;
+    /** Include the original XML document text. May contain additional information. */
+    includeXMLText?: boolean;
+    /** @deprecated Use options.includeRawData` */
     raw?: boolean;
   };
 };
@@ -36,9 +47,11 @@ export const WMSCapabilitiesLoader = {
   options: {
     wms: {}
   },
-  parse: async (arrayBuffer: ArrayBuffer, options?: WMSLoaderOptions) =>
+  parse: async (arrayBuffer: ArrayBuffer, options?: WMSCapabilitiesLoaderOptions) =>
+    // TODO pass in XML options
     parseWMSCapabilities(new TextDecoder().decode(arrayBuffer), options?.wms),
-  parseTextSync: (text: string, options?: WMSLoaderOptions) =>
+  parseTextSync: (text: string, options?: WMSCapabilitiesLoaderOptions) =>
+    // TODO pass in XML options
     parseWMSCapabilities(text, options?.wms)
 };