/ogc_api_coverages

[WIP] OpenAPI for Coverages

Primary LanguageCSSApache License 2.0Apache-2.0

OGC API - Coverages

This GitHub repository contains OGC's standard for querying geospatial information on the web, "OGC API - Coverages".

OGC API standards define modular API building blocks to spatially enable Web APIs in a consistent way. OpenAPI is used to define the reusable API building blocks with responses in JSON and HTML.

The OGC API family of standards is organized by resource type. OGC API - Coverages specifies the fundamental API building blocks for interacting with coverages. The spatial data community uses the term 'coverage' for homogeneous collections of values located in space/time, such as spatio-temporal sensor, image, simulation, and statistics data.

If you are unfamiliar with the term 'coverage', the explanations on the Coverages DWG Wiki provide more detail and links to educational material. Additionally, Coverages: describing properties that vary with location (and time) in the W3C/OGC Spatial Data on the Web Best Practice document may be considered.

Overview

General

This OGC API - Coverages specification establishes how to access coverages as defined by the Coverage Implementation Schema (CIS) 1.1 through OpenAPI.

Current scope:

  • Only gridded coverages are addressed, not MultiPoint/Curve/Surface/SolidCoverages. Reason is that gridded coverages receive most attention today.
  • Only CIS 1.1 GeneralGridCoverage is addressed, other coverage types will follow later. Reason is to have a first version early which shows and allows to evaluate the principles.
  • Only coverage extraction functionality is considered, not general processing (as is provided with Web Coverage Service (WCS) extensions such as the Processing Extension). Exceptions from this rule are subsetting including band subsetting, scaling, and CRS conversion and data format encoding, given their practical relevance.
  • Subsetting is considered in the query component only for now. As typically all dimensions in a coverage are of same importance subsetting might not fit perfectly in the hierarchical nature of the path component. Further, subsetting may reference any axis and leave out any other, which makes positional parameters unsuitable. Nevertheless subsetting in the path component particularly limited to fixed subsets might be considered in a future version. The principles of the /tiles path defined in OGC API - Maps & Tiles might be a good fit and shall be explored.

As such, the functionality provided below resembles OGC Web Coverage Service (WCS) 2.1 Interface Standard - Core.

Background Information: WCS Service Model

OGC WCS 2 has an internal model of its storage organization based on which the classic operations GetCapabilities, DescribeCoverage, and GetCoverage can be explained naturally. This model consists of a single CoverageOffering resembling the complete WCS data store. It holds some service metadata describing service qualities (such as WCS extensions, encodings, CRSs, and interpolations supported, etc.). At its heart, this offering holds any number of OfferedCoverages. These contain the coverage payload to be served, but in addition can hold coverage-specific service-related metadata (such as the coverage's Native CRS).

WCS 2 internal storage model

Discussion has shown that the OpenAPI functionality also assumes underlying service and object descriptions, so a convergence seems possible. In any case, it will be advantageous to have a similar "mental model" of the server store organization on hand to explain the various functionalities introduced below.

Principles

OpenAPI establishes URL-based access patterns, as defined by RFC 3986 "Uniform Resource Identifier (URI): Generic Syntax", RFC 3987 "Internationalized Resource Identifiers (IRIs)", and RFC 6570 "URI Template" following a syntax like http://www.acme.com/path/to/resource/{id}{?query,parameters} whereby

  • /path/to/resource/{id} defines the local path to the resource to be retrieved on the node identified by the head part, http://www.acme.com.
  • the {?query,parameters} represent key/value pairs with further parameters passed to the request.

As a general rule,

  • accessing a coverage component is done in the path section,
  • subsetting is done in the query parameter section
  • format encoding is controlled via HTTP headers

As the coverage model normatively is given by the corresponding XML schema (JSON and RDF are built in sync with XML) specification of the OpenAPI access paths follows this schema. Note, though, that OWS Common, while normatively referenced in CIS, is not followed by OpenAPI, so here deviations will occur.

For path expressions abbreviations (i.e., aliases) may be defined for convenience.

OGC API - Coverages Requests

This clause defines the basics of accessing OGC coverages via OpenAPI.

General

Requirement: A service offering OGC API - Coverages access shall be accessible via an URL as service endpoint (subsequently referred to as Base URL).

Example: http://acme.com/oapi

Requirement: Coverage access paths, as defined in the next clause, are concatenated to the Base URL via a "/" character, followed (optionally) by a query part.

Example: http://acme.com/oapi/collections/{collectionid}/coverage/rangeset

A request may be denied for server-specific reasons, such as quota.

Coverage Access Paths

In this clause, the path component of OGC API - Coverages access is established.

Access paths follow the XML Schema of CIS in their structure.

To access coverage service constituents, such as formats supported, OGC 14-121 Web Query Service provides guidance, see https://github.com/opengeospatial/ogc_api_coverages/blob/master/CIS%2BWCS-standards/14-121_Web-Query-Service_2016-06-19.pdf .

Coverage Query Parameters

In this clause, the query component of OGC API - Coverages access is established.

Subsetting parameters may be mixed in a query part, in no particular order.

Coverage Subsetting

Without any subsetting parameter the whole coverage extent is the target resource addressed. If a subsetting operation is provided then the coverage subset indicated is the target resource addressed.

Coverage subsetting is indicated through the SUBSET parameter name. The value following the "=" symbol is built as follows:

SubsetSpec:            SUBSET = axisName ( intervalOrPoint )
axisName:              {NCName}
intervalOrPoint:       interval | point
interval:              low ,  high
low:                   point | *
high:                  point | *
point:                 {number} | " {text} "    //" = double quote = ASCII code 0x42

where {NCName} is an XML-style identifier not containing ":" (colon) characters, {number} is an integer or floating-point number, and {text} is some general ASCII text (such as a time and date notation in ISO 8601). A coverage access request may have any number of SUBSET parameters, however for each axis of the coverage at most one SUBSET parameter may be provided.

In case of an interval a trim operation is specified, with lower and upper bound. In case of a point a slicing operation is specified. For the detailed semantics of subsetting, trimming, and slicing see OGC WCS.

Coverage Encoding

If no format encoding is specified in the request then a representation of the coverage shall be returned in its Native Format.

In general, file formats are not always capable of representing all coverage information. This is one reason why applications may prefer receiving a coverage in some different format.

Note:

  • The notion of Native Format refers to the range set only. Returning a coverage in this format may mean that some coverage constituents cannot be represented appropriately, and consequently will be missing from the coverage result.

An application may request a particular format encoding through one of the following two options:

If both options are present simultaneously in the request then the f parameter shall have preference.

If the format chosen is not capable of representing the coverage data requested this shall lead to a request error.

Note:

  • Extensions may provide further options, such as full content negotiation as per the HTTP standard.

For the detailed semantics of format encoding see OGC WCS.

Examples

This section contains examples for coverage access, subsetting, and encoding. It assumes a service endpoint of http://acme.com/oapi/ .

Service Metadata

The first part is about service metadata. Currently this is wild speculation as it will mainly be defined through OGC API - Common.

Coverage Finding

Notes:

  • all list results include links (cf. OGC API - Common)
  • "coverage" is a specialization of "items"; further names could be defined in future (RectifiedGridCoverage, features, ...)
  • "description of collection" to be clarified (defined in OGC API - Common?)
  • bbox is OGC API - Common syntax
    • in OGC API - Coverages Core, no subsetting on vertical and time coordinates
    • horizontal coordinates: all filtering is evaluated in WGS84 (may require bounding box translation before intersecting)
    • if filtering dimension is not present in coverage to be tested (due to above restriction not an issue currently): coverage will be discarded from result

Coverage Access

The second part is about coverage access, which (as described earlier) is driven by the coverage structure and, hence, given:

Coverage Subsetting

The third part is about query parameters:

Metadata and Coverage encoding

When not specified otherwise, the metadata will be returned in CIS XML format where applicable. Alternatively when the Accept header includes application/json at a higher relevance than text/xml then the CIS JSON encoding will be applied.

Similarly, coverages are always returned in their native format (even when subsetted) unless the Accept header is to set and another acceptable format is in the list. Additionally, encoding specific parameters can be passed as-well using mime type parameters.

For example, the following request expresses the intent to download the rangeset in a tiled and LZW-compressed TIFF file, but allows a fallback to a simple image/tiff and NetCDF encoding.

Accept: image/tiff; tiling=yes; tilewidth=128; tileheight=256; compress=LZW, image/tiff, application/netcdf

When using the TIFF encoding format the available parameters are documented in the WCS 2.0 Specification - GeoTIFF Coverage Encoding Profile. It is not required to use the GEOTIFF: prefix for each parameter.

When the full coverage access (metadata + data) is accessed, the encoding of the parts can be controlled by mime type parameters too. Each part of the coverage (domainset, rangetype, metadata, rangeset, etc.) is controllable by a mime type parameter of the same name. Each parameter can contain a list of formats, just as using the Accept header value directly. The acceptable format description of the part must be properly quoted if necessary to not interfere with the root Accept header description.

The following example shows the usage of format description for parts of the coverage. Note that not all parts are described, those parts are encoded in the default format. As can be seen, multiple formats can be specified to allow for encoding negotiation.

Accept: multipart/related; domainset="application/json,text/xml" rangetype=text/xml; rangeset="image/tiff;interleave=Pixel"

The resulting multipart document must provide the overall Content-Type of multipart/mixed and the negotiated Content-Type for each part.

E.g:

server: gunicorn/19.9.0
date: Tue, 18 Jun 2019 14:14:14 GMT
connection: close
content-length: 496897
content-type: multipart/related; boundary=9db765ef886544b8928b0a9902dca366
x-frame-options: SAMEORIGIN

--9db765ef886544b8928b0a9902dca366
Content-Type: text/xml
Content-Length: 6354

...

--9db765ef886544b8928b0a9902dca366
Content-Type: text/xml
Content-Length: 1253

...

--9db765ef886544b8928b0a9902dca366
Content-Type: text/xml
Content-Length: 1993

...

--9db765ef886544b8928b0a9902dca366
Content-Type: image/tiff
Content-Disposition: attachment; filename="mosaic_MER_FRS_1PNPDE20060816_090929_000001972050_00222_23322_0058_RGB_reduced_20190618141413.tif"
Content-Length: 486768

...

Open Issues

  • Establish service parameter access, based on OGC API - Common
  • What is the output format of items typically returned as XML or JSON, such as DomainSet and RangeType? Should maybe FORMAT be applicable here as well? If so, should it be listed as a possible output format (which might be confusing)?
  • OGC 14-121 Web Query Service provides a definition of path syntax, but adds more functionality (such as selection predicates), all based on the XPath standard. Such extra functionality might come handy.