Multidimensional WMTS domain discovery

By GeoSolutions, 2016-05-24 draft.

Contact: Andrea Aime, andrea.aime@geo-solutions.it

Warning

This document is not an OGC specification

Objective

This document describes a WMTS 1.0.0 extension adding multidimensional domain discovery operations/resources. The use cases under consideration are:

  • Datasets with large and irregular dimension domains which cannot be described by a simple start/end/interval syntax

  • Datasets with multiple dimensions, such as time, run-time, elevation, some dimensions being related to each other (e.g. for a given time there is a small set of corresponding run-times)

  • Datasets scattered over both space and time (e.g., typical satellite collections) where not all possible combinations of space and time locate an actual data sample

While the current WMTS dimension support can report multiple dimensions, there is no way to discover the relationships between dimensions, moreover, large domains cannot be practically reported due to the requirement to enumerate all possible values in the capabilities document.

Note

While this document focuses on WMTS, the need to drill down into a N-dimensional domain to locate pockets of data is felt also while using WMS and WMTS, thus this extension tries to have limited WMTS dependencies to allow easy integration with the other two protocols as well.

Existing OWS dimension support

Explicit multiple dimension support exists in both WMTS and WMS interfaces, based on slightly different semantics, while the EO-WCS extension supports a single time dimension as part of the coverage descriptions metadata.

None of the above protocols however provides a way to discover the structure of the dimension domain, nor provides good support for large scattered ones, but all would benefit from such support.

While this document focuses on WMTS, similar concepts and operations should be applicable to the other two protocols as well, with little conceptual and practical adaptations.

Existing WMTS dimension support

The latest official version of WMTS (Web Map Tile Service) is 1.0.0 [WMTS 1.0.0]. It includes a limited mechanism for dimension based queries, with

<Dimension>
  <ows:Identifier>dimension1</ows:Identifier>
  <ows:UOM>theUnit</ows:UOM>
  <ows:Title>...</ows:Title>
  <ows:Abstract>...</ows:Abstract>
  <Default>d1Default</Default>
  <Value>d1v1</Value>
  <Value>d1v2</Value>
  <Value>d1v3</Value>
</Dimension>
<Dimension>
  <ows:Identifier>dimension2</ows:Identifier>
  <ows:UOM>theUnit</ows:UOM>
  <ows:Title>...</ows:Title>
  <ows:Abstract>...</ows:Abstract>
  <Default>d2Default</Default>
  <Value>d2v1</Value>
  <Value>d2v2</Value>
  <Value>d2v3</Value>
</Dimension>

Specific values must be explicitly enumerated, implying the practical usage is limited to small domains, and the dimension is opaque to the client, which is going to use the dimension values as-is in requests, without any understanding of them.

Existing WMS dimension support

The latest official version of WMS (Web Map Service) is 1.3.0 [WMS 1.3.0]. It has a more-sophisticated dimension support than WMTS. An example declaration section might describe regular domains in a compact way by providing a start, end, and resolution:

<Dimension name="time" units="ISO8601" default="current">2008-01-15T00:00:00.000Z/2008-11-01T00:00:00.000Z/PT1H</Dimension>
<Dimension name="run-time" units="ISO8601" default="current">2008-01-12T00:00:00.000Z/2008-10-28T00:00:00.000Z/PT1H</Dimension>
<Dimension name="elevation" units="EPSG:5030" default="0">0/2000/100</Dimension>

This allows regular domains to be described in a compact notation, however one that still fails to address discovery of the relationships between the domains. For example, in the above example a 3 days weather forecast is run periodically to generate temperature values at various heights in the atmosphere: it’s thus clear to the reader there is a tight relationship between time and run-time, while a single time is related to multiple run-times, the run-time values related to a time T are to be found in the interval [T - 3d,T].

A client unaware of such relationship will thus generate requests that match no actual data in the dataset.

Capabilities document changes

The starting point for a client trying to explore the structure of the multidimensional domain is the capabilities document. Services supporting this extension declare dimensions using either:

  • The full domain as usual, if the domain is small enough to practically be included in the capabilities document

  • A single value representing the full domain as "minValue--maxValue", if the domain is too large to be represented as a sequence of values in the capabilities document.

For example:

<Dimension>
  <ows:Identifier>dimension1</ows:Identifier>
  <ows:UOM>theUnit</ows:UOM>
  <ows:Title>...</ows:Title>
  <ows:Abstract>...</ows:Abstract>
  <Default>d1Min--d1Max</Default>
  <Value>d1Min--d1Max</Value>
</Dimension>
<Dimension>
  <ows:Identifier>dimension2</ows:Identifier>
  <ows:UOM>theUnit</ows:UOM>
  <ows:Title>...</ows:Title>
  <ows:Abstract>...</ows:Abstract>
  <Default>d2v1</Default>
  <Value>d2v1</Value>
  <Value>d2v2</Value>
  <Value>d2v3</Value>
</Dimension>

This approach will allow clients unaware of the dimension drilling extension to get their usual dimension support. When the range syntax is used in WMTS requests, the server is free to decide on a reasonable behavior, including:

  • Stack all data in the range to compose the output

  • Using a single default value contained in the range depending on the nature of the dimension (e.g., min, max, or current)

  • Evaluate the specified dimension values, considering those that are explicit and those that are implicit ranges, and locate a suitable list of dimension values actually matching an available dataset

Note

The full range of values has been used, as opposed to a static key as null or all to reduce the likeliness that HTTP caching headers won’t disallow clients to get fresh data when fresher data gets added to the set.

The range separator proposed is not / due to its incompatibility with rest oriented architectures. It is to be noted however that the usage of -- will make ranges using negative values (e.g., elevation) unintuitive to read (e.g., -100---10 to represent the range between -100 and -10).

The capabilities document of services implementing this extension will also declare two extra operations to discover the details of multiple dimensions domain (detailed description available in the following sections):

  • DescribeDomains, allowing to drill into the dimensions structure with a compact output representation

  • GetFeature, allowing to locate all the available dimension values combinations

A WMTS implementation using the procedure oriented architectural style declares the two new operations in the operations section of the capabilities document, a restful one will instead provide two extra url templates at the layer level.

Space as an element of dimension domain discovery

It is to be noted that, while the two dimensional space does not appear as an explicit Dimension element in the capabilities document, it is nevertheless and important element of discovery, especially for scattered domains populated by satellite or aerial sources (as opposed to models, which instead tend to always consider the same area).

Each domain resource/operation will then accept a target range of values for each dimension (space included), and will return the restricted domain/values of the others as described below.

Specifically for WMTS, the representation of space is normally provided as a TopLeftCorner in the tile matrix set CRS, a resolution and number of tiles. For the sake of simplicity the extension will use a bounding box using the same syntax and semantics as the BBOX parameter in WMS 1.3 [WMS 1.3] instead. This won’t make WMTS clients and servers more complex, as on both sides there is already a need to convert between tile coordinates and world coordinates.

Note

The usage of BBOX also simplifies to integration of the extension with WMS, and to a more limited extent, with WCS (WCS 2.0 uses trims on single axis to limit the area of interest instead of a bounding box).

Compact domain inspection

A new operation/resource is added to the WMTS protocol describing all the dimension domains in a compact document, along with the restricted bounding box of the two dimensional space intercepted by the request.

The domain description is delivered by a new DescribeDomains operation in procedure oriented architectural style, and a Domains resource in resource oriented architectural style.

The DescribeDomains operation accepts the following parameters:

Table 1. DescribeDomains operation request URL parameters
Name Optionality and use Definition and format

"Service=WMTS"

Mandatory

Service type identifier

"Request=DescribeDomains"

Mandatory

Operation name

"Version=1.0.0"

Mandatory

Standard and schema version for this operation

"Layer"

Mandatory

Layer identifier

"TileMatrixSet"

Mandatory

Tile matrix set identifier

"BBOX=minx,miny,maxx,maxy"

Optional

Bounding box corners (lower left, upper right) in CRS units.

"DimensionIdentifier"

Optional, at most one per dimension

A range described as min/max, restricting the domain of this dimension

"Format"

Optional, the default being text/xml

The desired output format

The following is a sample request assuming a Dimension definition with an ows:Identifier value of time:

http://server.com/ows?Service=WMTS&Request=DescribeDomains&Version=1.0.0&Layer=Imagery&TileMatrixSet=CRS84&BBOX=0,0,90,180&time=2008-01-15T00:00:00.000Z/2008-11-01T00:00:00.000Z

The Domains resource is described by a URL template at the Layer level and works in a similar fashion, using -- as the interval separator in requests

Table 2. URL template variables and possible values for Domains
URL template variable Meaning Possible values Multiplicity

"TileMatrixSet"

Tile matrix set identifier

Identifier found at ./ TileMatrixSetLink/TileMatrixSet

One (mandatory)

"BBOX"

Space restriction

minx,miny,maxx,maxy expressed in the TileMatrixSet CRS, or all for no restriction

One (Mandatory)

"./Dimension/ows:Identifier"

Restriction for the given dowmain

Min--Max or all for no restriction

One for each dimension available (mandatory)

The following are a sample template and a request assuming a Dimension definition with an ows:Identifier value of time:

<ResourceURL format="text/xml" resourceType="Domains" template="http://server.com/ows/wmts/1.0.0/layer/default/{TileMatrixSet}/{BBOX}/{time}.xml"/> http://server.com/ows/wmts/1.0.0/layer/default/CRS84/-30,10,20,40/2008-01-15T00:00:00.000Z--2008-11-01T00:00:00.000Z.xml

The response contains the residual space and domain of various dimensions. To accommodate competing needs of clarity and compactness, the residual domain can be expressed as a comma separate list of:

  • Regular distributions expressed as Min/Max/Interval, using the same syntax as WMS 1.3

  • Compact scattered domains represented as Min/Max, indicating that there is no regular structure betwen the two extremes

  • Single values

A few examples:

  • A large scattered elevation domain too large to be represented by a full list can be described as 1.5/2436

  • An almost regular domain cut on missing data points can be represented as 1/100/1,110/200/1,215/500/1

  • When restrictions on the various domain axis make the domain small enough a scattered domain can be represented as a simple list, e.g., 1,10,13,25,32

  • If the restrictions cause a domain to be completely void of data, an empty list will be returned .

Note
 The document is presented with XML bindings, for consistency with the other WMTS protocol requests. A namespace needs to be chosen, while a potential JSON presentation should be considered as well.

A compact dimension domain description contains the following elements:

Table 3. URL DimensionDomain elements
Element Meaning Possible values Multiplicity

"ows:Identifier"

The dimension name

time,elevation,run-time,…​

One (mandatory)

"Size"

Number of elements left in the domain with the current restriction

Non negative number

One or zero (mandatory for Scattered only)

"Domain"

A description of residual dimension domain under the current restrictions

A comma separate list of point values, regular ranges, and scattered ranges, or an empty value if no data is available under the current restrictions

Mandatory

The following document declares the dimension domains for an unrestricted request:

http://server.com/ows?Service=WMTS&Request=DescribeDomains&Version=1.0.0&Layer=Imagery&TileMatrixSet=CRS84
<Domains>
  <SpaceDomain>
    <BoundingBox CRS="urn:ogc:def:crs:OGC:1.3:CRS84" minx="-180" miny="-90" maxx="180" maxy="90"/>
  </SpaceDomain>
  <DimensionDomain>
    <ows:Identifier>time</ows:Identifier>
    <Domain>2008-01-15T00:00:00.000Z/2008-11-01T00:00:00.000Z/PT1H</Domain>
  </DimensionDomain>
  <DimensionDomain>
    <ows:Identifier>elevation</ows:Identifier>
    <Domain>0/5000</Domain>
    <Size>238</Sizez>
  </DimensionDomain>
  <DimensionDomain>
    <ows:Identifier>band</ows:Identifier>
    <Domain>COAST,B,G,R,NIR,SWIR1,SWIR2,PAN,CIRRUS,TIR1,TIR2</Domain>
  </DimensionDomain>
</Domains>

A request restricting on the -30,10,20,40 bounding box might result in an elevation domain compact enough to be expressed in enumerated mode:

http://server.com/ows?Service=WMTS&Request=DescribeDomains&Version=1.0.0&Layer=Imagery&TileMatrixSet=CRS84&BBOX=-30,10,20,40
<Domains>
  <SpaceDomain>
    <BoundingBox CRS="urn:ogc:def:crs:OGC:1.3:CRS84" minx="-30" miny="10" maxx="20" maxy="40"/>
  </SpaceDomain>
  <DimensionDomain>
    <ows:Identifier>time</ows:Identifier>
    <Domain>2008-05-00T10:30:00.000Z/2008-07-20T23:00:00.000Z/PT1H</Domain>
  </DimensionDomain>
  <DimensionDomain>
    <ows:Identifier>elevation</ows:Identifier>
    <Domain>1200,1300,1400,1500,1600,1700</Domain>
  </DimensionDomain>
  <DimensionDomain>
    <ows:Identifier>band</ows:Identifier>
    <Domain>COAST,B,G,R,NIR,SWIR1,SWIR2,PAN,CIRRUS,TIR1,TIR2</Domain>
  </DimensionDomain>
</Domains>

A further restriction on the same bbox and an elevation value outside of the previous list would result in:

http://server.com/ows?Service=WMTS&Request=DescribeDomains&Version=1.0.0&Layer=Imagery&TileMatrixSet=CRS84&BBOX=-30,10,20,40&elevation=100
<Domains>
  <SpaceDomain>
    <BoundingBox CRS="urn:ogc:def:crs:OGC:1.3:CRS84" minx="-30" miny="10" maxx="20" maxy="40"/>
  </SpaceDomain>
  <DimensionDomain>
    <ows:Identifier>time</ows:Identifier>
    <Domain></Domain>
  </DimensionDomain>
  <DimensionDomain>
    <ows:Identifier>elevation</ows:Identifier>
    <Domain></Domain>
  </DimensionDomain>
  <DimensionDomain>
    <ows:Identifier>band</ows:Identifier>
    <Domain></Domain>
  </DimensionDomain>
</Domains>
Note

As an alternative the space domain portion could be represented as a GML polygon in the tilematrixset CRS, allowing smart clients to avoid requesting tiles in empty areas. The extension may require the server to provide the bounding box and allow it to also provide a more precise polygon, clients can decide to use it or ignore it based on their sophistication. e.g.:

<Domains>
  <SpaceDomain>
    <BoundingBox CRS="urn:ogc:def:crs:OGC:1.3:CRS84" minx="-30" miny="10" maxx="20" maxy="40"/>
    <DomainGeometry>
      <gml:MultiSurface srsName="urn:ogc:def:crs:OGC:1.3:CRS84" srsDimension="2">
         <gml:surfaceMember>
            <gml:Polygon>
               <gml:exterior>
                  <gml:LinearRing>
                     <gml:posList>-30 20 10 40 20 10 -30 -20</gml:posList>
                  </gml:LinearRing>
               </gml:exterior>
            </gml:Polygon>
         </gml:surfaceMember>
      </gml:MultiSurface>
    </DomainGeometry>
  </SpaceDomain>
  <DimensionDomain>
    <ows:Identifier>time</ows:Identifier>
    <Domain></Domain>
  </DimensionDomain>
  <DimensionDomain>
    <ows:Identifier>elevation</ows:Identifier>
    <Domain></Domain>f
  </DimensionDomain>
  <DimensionDomain>
    <ows:Identifier>band</ows:Identifier>
    <Domain>COAST,B,G,R,NIR,SWIR1,SWIR2,PAN,CIRRUS,TIR1,TIR2</Domain>
  </DimensionDomain>
</Domains>

Given the Domains document is a summary one, servers are advised to return a suitably simplified representation of the domain, to avoid bloating the document with a large GML geometry.

Histogram generation

Given a scattered domain description, a client might want to provide users a notion of the data distribution between the minimum and maximum value. The histogram divides the interval in regular buckets, and provides an item count for each bucket.

The distribution histogram is delivered by a new GetHistogram operation in procedure oriented architectural style, and a Histogram resource in resource oriented architectural style. The client is allowed to suggest a desired resolution for the buckets, the server can accept and use the suggested value, or return an histogram with a lower resolution in the suggested value would result in an exceedingly large response.

The GetHistogram operation builds on top of the DescribeDomain structure, adding parameters to identify the histogram dimension, and the desired histogram resolution:

Table 4. Histogram operation request URL parameters
Name Optionality and use Definition and format

"Service=WMTS"

Mandatory

Service type identifier

"Request=GetHistogram"

Mandatory

Operation name

"Version=1.0.0"

Mandatory

Standard and schema version for this operation

"Layer"

Mandatory

Layer identifier

"TileMatrixSet"

Mandatory

Tile matrix set identifier

"BBOX=minx,miny,maxx,maxy"

Optional

Bounding box corners (lower left, upper right) in CRS units.

"DimensionIdentifier"

Optional, at most one per dimension

A range described as min/max, restricting the domain of this dimension

"Histogram"

Required, one value

Name of the dimension for which the histogram will be computed

"Resolution"

Optional

Suggsted size of the histogram bucket. Cannot be provided for enumerated dimensions, will use the period sytanx for time (e.g. PT1H), a number for numeric dimensions, or auto to leave the decision to the server.

"Format"

Optional, the default being text/xml

The desired output format

The following is a sample request assuming the Capabililites document contains a Dimension definition with an ows:Identifier value of time:

http://server.com/ows?Service=WMTS&Request=GetHistogram&Version=1.0.0&Layer=Imagery&TileMatrixSet=CRS84&BBOX=0,0,90,180&time=2008-01-15T00:00:00.000Z/2008-11-01T00:00:00.000Z&histogram=time&resolution=P1D

The Histogram resource is described by a URL template at the Layer level and works in a similar fashion, using -- as the interval separator in requests

Table 5. URL template variables and possible values for Histogram
URL template variable Meaning Possible values Multiplicity

"TileMatrixSet"

Tile matrix set identifier

Identifier found at ./ TileMatrixSetLink/TileMatrixSet

One (mandatory)

"BBOX"

Space restriction

minx,miny,maxx,maxy expressed in the TileMatrixSet CRS, or all for no restriction

One (Mandatory)

"./Dimension/ows:Identifier"

Restriction for the given dowmain

Min--Max or all for no restriction

One for each dimension available (mandatory)

"Histogram"

Name of the dimension for which the histogram will be computed

A dimension name as found in the capabilities document

One (mandatory)

"Resolution"

Suggested size for the histogram bucket

A period for time dimensions (e.g. PT1H), a number for numeric dimensions, or auto to leave the decision to the server.

One (mandatory)

The following are a sample template and request assuming a Dimension definition with an ows:Identifier value of time:

<ResourceURL format="text/xml" resourceType="Histogram" template="http://server.com/ows/wmts/1.0.0/layer/default/{TileMatrixSet}/{BBOX}/{time}/{dimension}/{resolution}/histogram.xml"/> http://server.com/ows/wmts/1.0.0/layer/default/CRS84/-30,10,20,40/2008-01-15T00:00:00.000Z--2008-11-01T00:00:00.000Z/time/auto/histogram.xml

The response contains the distribution histogram for the specified dimension, under the specified restrictions.

Note
 The document is presented with XML bindings, for consistency with the other WMTS protocol requests. A namespace needs to be chosen, while a potential JSON presentation should be considered as well.

A histogram description contains the following elements:

Table 6. URL DimensionDomain elements
Element Meaning Possible values Multiplicity

"ows:Identifier"

The dimension name

time,elevation,run-time,…​

One (mandatory)

"Domain"

Describes the histogram domain as start, end and resolution.

Start/End/Resolution

Mandatory

"Values"

Lists the number of values found in each bucket

A comma separate list of integer numbers, one count per bucket

Mandatory

In the following request the client requires a hourly histogram over a space of 11 months, the server considers the request excessive and returns a monthly histogram instead:

http://server.com/ows?Service=WMTS&Request=GetHistogram&Version=1.0.0&Layer=Imagery&TileMatrixSet=CRS84&histogram=time&resolution=PT1H
<Histogram>
   <ows:Identifier>time</ows:Identifier>
   <Domain>2008-01-01T00:00:00.000Z/2008-12-01T00:00:00.000Z/P1M</Domain>
   <Values>1,15,0,2,5,7,1,0,3,9,23</Value>
</Histogram>

Detailed value combination inspection and description

Once the range of possible values has been suitably restricted, the client might need to to enumerate the actual possible value combinations using a GetFeature operation, which in a similar way to WFS [WFS 2.0] GetFeature returns a list of features along with dimension values using the same formats as the feature info operation. For this profile GML 3.1 shall be provided as a feature info format ("application/gml+xml; version=3.1") a similar GeoJSON output should be considered as an option.

Note
 Supporting this operation could be made optional, but it’s strongly recommended for domains that are scattered and/or having inter-dimension dependencies (e.g., even having enumerated values for all dimensions, not all possible combinations will select existing data).

Each dimension shall be represented as an attribute of the feature, while the space component is encoded as a polygon/multipolygon, which can be as simple as a bounding box, or a full fledged footprint of an EO feature.

The GetFeature operation accepts the following parameters:

Table 7. GetFeature operation request URL parameters
Name Optionality and use Definition and format

"Service=WMTS"

Mandatory

Service type identifier

"Request=GetFeature"

Mandatory

Operation name

"Layer"

Mandatory

Layer identifier

"BBOX=minx,miny,maxx,maxy"

Optional

Bounding box corners (lower left, upper right) in CRS units.

"TileMatrixSet=tileMatrixSetId"

Mandatory

Tile matrix set identifiier

"DimensionIdentifier=dimension"

Optional, at most one per dimension

A range described as min/max, restricting the domain of this dimension

"Format=application/gml+xml; version=3.1"

Mandatory

One of the formats declared as supported in the capabilities document

The Features resource is described by a URL template at the Layer level and works in a similar fashion, using -- as the interval separator in requests

Table 8. URL template variables and possible values for Features
URL template variable Meaning Possible values Multiplicity

"TileMatrixSet"

Tile matrix set identifier

Identifier found at ./ TileMatrixSetLink/TileMatrixSet

One (mandatory)

"BBOX"

Space restriction

Bottom,Left,Top,Right expressed in the TileMatrixSet identifier, or all for no restriction

One (Mandatory)

"./Dimension/ows:Identifier"

Restriction for the given dimension

Min--Max or all for no restriction

One for each dimension available (mandatory)

The encoded GML result contains an indication of the footprints and other dimension values

<?xml version="1.0" encoding="UTF-8"?>
<wmts:FeatureCollection xmlns:xs="http://www.w3.org/2001/XMLSchema"
    xmlns:gml="http://www.opengis.net/gml" xmlns:ogc="http://www.opengis.net/ogc"
    xmlns:wmts="http://www.opengis.net/wmts/1.0"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" numberOfFeatures="1">
    <gml:featureMembers>
        <wmts:feature gml:id="sample.1">
            <wmts:footprint>
                <gml:MultiSurface srsName="urn:ogc:def:crs:OGC:1.3:CRS84" srsDimension="2">
                    <gml:surfaceMember>
                        <gml:Polygon>
                            <gml:exterior>
                                <gml:LinearRing>
                                    <gml:posList>-10 0 -10 10 10 10 10 0 -10 0</gml:posList>
                                </gml:LinearRing>
                            </gml:exterior>
                        </gml:Polygon>
                    </gml:surfaceMember>
                </gml:MultiSurface>
            </wmts:footprint>
            <wmts:dimension name="time">2008-05-00T10:30:00.000Z</wmts:dimension>
            <wmts:dimension name="run-time">2008-02-00T10:30:00.000Z</wmts:dimension>
            <wmts:dimension name="elevation">1200</wmts:dimension>
        </wmts:feature>
    </gml:featureMembers>
    ...
</wmts:FeatureCollection>
Note

The XML above places dimension names as attribute in order to allow usage of a simple, static XML schema to describe the GML collection, while at the same time avoiding the extra requirement of dimension names being valid QName.

References

[WMS 1.3.0] OpenGIS Web Map Service (WMS) Implementation Specification, version 1.3.0, OGC document 06-042, 2006-03-15, http://portal.opengeospatial.org/files/?artifact_id=14416

[WMTS 1.0.0] OpenGIS Web Map Tile Service Implementation Standard, version 1.0.0, OGC document 07-057r7, 2010-04-06, http://portal.opengeospatial.org/files/?artifact_id=35326

[WFS 2.0.0] OGC® Web Feature Service 2.0 Interface Standard, version 2.0.2, OGC document 09-025r2, 20104-07-10, http://docs.opengeospatial.org/is/09-025r2/09-025r2.html