Improve and clarify WMS support

stac-extensions · Oct 19, 2023 · 5854ad1 · 5854ad1
1 parent 2f2643b
commit 5854ad1
Show file tree

Hide file tree

Showing 5 changed files with 44 additions and 2 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -9,17 +9,21 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Added
 
 - PMTiles
+- New property `wms:transparent` for WMS
 
 ### Changed
 
 - The `type` for WMS and WMTS links should be set to the image media type that the client should request for tiles.
+- WMS supports only v1.3.0 of the specification
 
 ### Deprecated
 
 ### Removed
 
 ### Fixed
 
+- WMS: Clarified the behavior of `wms:layers` and `wms:styles`
+
 ## [1.2.0]
 
 ### Added

diff --git a/README.md b/README.md
@@ -48,7 +48,7 @@ Links to a [3D Tiles](https://docs.ogc.org/cs/18-053r2/18-053r2.html) implementa
 
 ### OGC WMS
 
-Links to a [OGC Web Map Service](https://www.ogc.org/standards/wms) (WMS) implementation (versions 1.x).
+Links to a [OGC Web Map Service](https://www.ogc.org/standards/wms) (WMS) implementation (versions 1.3.0).
 Only (tiled) "Basic WMS" is supported at this time.
 
 | Field Name      | Type                 | Description |
@@ -59,6 +59,14 @@ Only (tiled) "Basic WMS" is supported at this time.
 | wms:layers      | \[string]            | **REQUIRED**. The layers to show on the map by default. Can't be empty. |
 | wms:styles      | \[string]            | The styles to show on the map by default. If not provided or empty, an empty string will be used for the query parameter. |
 | wms:dimensions  | Map\<string, string> | Any additional dimension parameters to add to the request as query parameters (e.g. the dimensions `TIME` or `ELEVATION`). |
+| wms:transparent | boolean              | Sets whether the layers should be rendered transparent or not. Default: `false` |
+
+If you provide multiple array elements in `wms:layers` (e.g. `["layerA", "layerB"]`),
+each should occur in a separate layer in the mapping library so that requests for the layers are sent.
+If you want to send multiple layers in a single request, provide them as a string with comma-separated values: `["layerA,layerB"]`.
+`wms:layers` and `wms:styles` work in parallel, so the first style in the array will be used for the first layer, etc.
+
+- [More details on the mapping between WMS query parameters and the STAC fields](./wms.md)
 
 ### OGC WMTS
 
@@ -73,6 +81,9 @@ Links to a [OGC Web Map Tile Service](https://www.ogc.org/standards/wmts) (WMTS)
 | wmts:layer      | string\|\[string]    | **REQUIRED**. The layers to show on the map by default, either a list of layer names or a single layer name. |
 | wmts:dimensions | Map\<string, string> | Any additional dimension parameters to add to the request as key-value-pairs, usually added as query parameters. |
 
+If you provide multiple array elements in `wmts:layer` (e.g. `["layerA", "layerB"]`),
+each should occur in a separate layer in the mapping library so that individual requests for the layers are sent.
+
 #### href
 
 For WMTS, the `href` is pointing to the URL of the Capabilities document, but without the query parameters for the Capabilities request.

diff --git a/examples/item.json b/examples/item.json
@@ -64,7 +64,8 @@
       "title": "RGB composite visualized through a WMS",
       "wms:layers": [
         "rgb"
-      ]
+      ],
+      "wms:transparent": true
     },
     {
       "href": "https://maps.example.com/xyz/{z}/{x}/{y}.jpg",

diff --git a/json-schema/schema.json b/json-schema/schema.json
@@ -138,6 +138,9 @@
                   "additionalProperties": {
                     "type": "string"
                   }
+                },
+                "wms:transparent": {
+                  "type": "boolean"
                 }
               }
             }

diff --git a/wms.md b/wms.md
@@ -0,0 +1,23 @@
+# OGC WMS
+
+## Mapping between STAC and the WMS GetMap parameters
+
+| Request Parameter           | Mandatory | Description                                                  | Mapping / Implementation guide                               |
+| --------------------------- | --------- | ------------------------------------------------------------ | ------------------------------------------------------------ |
+| VERSION=1.3.0               | Yes       | Request version.                                             | Always `1.3.0` - We assume everyone supports 1.3.0 today.    |
+| REQUEST=GetMap              | Yes       | Request name.                                                | Always `GetMap`.                                             |
+| LAYERS=layer_list           | Yes       | Comma-separated list of one or more map layers.              | via `wms:layers`, one layer in the mapping library per array element |
+| STYLES=style_list           | Yes       | Comma-separated list of one rendering style per requested layer. | via `wms:styles`, 1:1 mapping to `wms:layers`                |
+| CRS=namespace:identifier    | Yes       | Coordinate reference system.                                 | determined by mapping library, usually EPSG:3857             |
+| BBOX=minx,miny,maxx,maxy    | Yes       | Bounding box corners (lower left, upper right) in CRS units. | determined by mapping library                                |
+| WIDTH=output_width          | Yes       | Width in pixels of map picture.                              | determined by mapping library                                |
+| HEIGHT=output_height        | Yes       | Height in pixels of map picture.                             | determined by mapping library                                |
+| FORMAT=output_format        | Yes       | Output format of map.                                        | via `type`                                                   |
+| TRANSPARENT=TRUE\|FALSE     | No        | Background transparency of map (default=FALSE).              | via `wms:transparent`                                        |
+| BGCOLOR=color_value         | No        | Hexadecimal red-green-blue colour value for the background color (default=0xFFFFFF). | not supported, some libraries may support setting it via `wms:dimensions` |
+| EXCEPTIONS=exception_format | No        | The format in which exceptions are to be reported by the WMS (default=XML). | determined by mapping library                                |
+| TIME=time                   | No        | Time value of layer desired.                                 | via `wms:dimensions`                                         |
+| ELEVATION=elevation         | No        | Elevation of layer desired.                                  | via `wms:dimensions`                                         |
+| Other sample dimension(s)   | No        | Value of other dimensions as appropriate.                    | via `wms:dimensions`                                         |
+
+Columns 1-3 are coming from the [OGC WMS specification, version 1.3.0](https://portal.ogc.org/files/?artifact_id=14416), chapter 7.3.2.