How to handle feature-coverages?

[dblodgett-usgs]

It is common practice in hydrology to treat a collection of watershed features that cover the landscape as a coverage. This is also common with spatial units in various domains that can be thought of as a coverage.

There is also a very common practice where a grid (rectilinear or otherwise) can be accessed via index position. In this arrangement, the i,j position of a cell can be thought of as a feature identifier.

In both cases, an individual entity can be identified uniquely as a feature, but it can be equally valid to access the "layer" as a coverage. From the perspective of OGC API, it would seem that we shouldn't actually make a distinction between coverages and features as unique kinds of data, but rather, support various operations on a given "layer".

So say we had a feature collection that could also be treated as a coverage, we might do:
https://acme.com/collections/foo_collection/items
as well as:
https://acme.com/collections/foo_collection/rangeset

Using this kind of arrangement, if a provider didn't want to allow access to the collection items, they wouldn't have to. Conversely, if a set of features really shouldn't be treated as a coverage of features, then the coverage functionality wouldn't be supported. But at the end of the day, functions/subsetting capabilities that operate on coverages and features could be applicable to either, right?

[joanma747]

I think we are closer that it looks.

First, I do not think that items is equivalent to rangeset. In items you have properties with names and geographic objects with coordinates. In rangset you only have an array of numbers with no semantics whatsoever. To me you need to receive the full coverage description (domainset, rangeset and rangetype) to be at the same level of semantics as in items.

Lets imagine that we have network of weather station that provides temperature and rain and the interpolation system to create a temperature coverage and a rain coverage.

By doing
https://acme.com/collections/foo_collection/items
you are going to get the weather stations with temperature and rain

https://acme.com/collections/foo_collection/coverages/temperature
you are going to get a complete coverage with temperature
https://acme.com/collections/foo_collection/coverages/rain
you are going to get a complete coverage with rain

At the moment,
https://acme.com/collections/foo_collection/coverages
will give you the list of coverageIds
I wonder if (at least in some cases) we could have a
https://acme.com/collections/foo_collection/coverages?content=full
that will get us a coverage that will give us both temperature and rain.

[dblodgett-usgs]

Ahhh. I think I follow now. Thank you.

In essence, the rain in ../coverages/rain/ is declaring the feature attribute you would like to access as a coverage.

So we might have a cell-coverage that could be accessed
via: https://acme.com/collections/weather/items?row=1&col=1 which would return tmin, tmax, and rain for row=1, col=1.
or: https://acme.com/collections/weather/coverages/rain?bbox=160.6,-55.95,-170,-25.89

The prospect of a coverage encoding that contains multiple variables is very real... NetCDF. In the case above, I may want to request specific variables from the coverage. That may be an argument to do:
https://acme.com/collections/weather/coverages?vars=rain,tmin,tmax

???

[pebau]

yes, that's what the WCS Range Subsetting extension does; in GET/KVP notation (can also be POST/XML or SOAP):

http://www.acme.com/ows?SERVICE=WCS&VERSION=2.0&REQUEST=GetCoverage&SUBSET=...&RANGESUBSET=rain,tmin,tmax

In practice, we are using this all over the place for band subsetting in hyperspectral image datacubes or variable selection in climate datacubes.

[joanma747]

So we might need another URL in the API:

https://acme.com/collections/foo_collection/coverages?RANGESUBSET=rain,tmin,tmax

to get a coverage in a format that allows more than one "range" (variable) as a response (netCDF, multipart...).

This could be added to the current:
https://acme.com/collections/foo_collection/coverages/rain?SUBSET=...

If we go this route, then it might be good to use "coverage" instead of "coverages" and us the "collections" to separate coverages: I mean
https://acme.com/collections/weather/coverage/rangetype --> lists the "variables"
https://acme.com/collections/weather/coverage?RANGESUBSET=rain,tmin,tmax --> Gets some of them
https://acme.com/collections/weather/coverage/rain?SUBSET=... -->Gets one of them

this will allow for
https://acme.com/collections/weather/items?point=45,3 --> Gives us rain,tmin,tmax values on a weather station as geojson
or even:
https://acme.com/collections/weather/items?bbox --> Gives us the values of the centers of the "cells" in the coverage as a geojson with geometry point. Useful it there are not so many of them.

I believe it opens the field for a nice integration between features and grid coverages.

[pebau]

just a little addition:

• "This could be added to the current:
  https://acme.com/collections/foo_collection/coverages/rain?SUBSET=..." --- just as the other WCS extensions which remain to be discovered :)
• " https://acme.com/collections/weather/coverage/rain?SUBSET=... -->Gets one of them" --- actually, it gets all variables, but only for the spatio-temporal SUBSET
• "https://acme.com/collections/weather/coverage/rangetype --> lists the "variables"" --- but not only their names, rather the full description as per SWE

good discussion!

[joanma747]

Please note that recently WFS 3.0 has include a "itemType" that might prevent the possibility discussed here (except if it is re-defined as an array). I would like to reconsider the decision. I hope it is not too late for that.

[cmheazel]

API-Common defines a path up to /collections/{collectionid}/items. This path returns the content of the collection, but imposes no requirements on what that content must be. This is a job for the resource API (aka coverages). It seems to me that in the case of Coverages, /items could be an additional access path to RangeSet. The difference is that /items would inherit its behavior from API-Features while RangeSet would be based on WCS. Granted, not all coverages can be treated as a collection of Features. But as long as it fails gracefully I believe that use case can be addressed.

[pebau]

there seems to be a tendency of "coverage is rangeset, plus something not really important". But coverage = { domainset, rangeset, rangetype, metadata }. Ignoring this means ignoring 15 years of discussion about importance of metadata and painstaking work to integrate them more seamlessly, in the WCS group and elsewhere.

A rangeset is really just a sequence of values, such as

1.456693,6.141732,12.20472,19.09449,22.40158,21.29921,24.6063,23.50394,21.85039,16.33858,9.448819,2.834646

...no width/height information, no # dimensions, no spatial or temporal extent, no CRS, no range type (float, int, ...?), nothing. Think of the range set as a CSV or PNG (and even this is more than the rangeset in that it knows about x*y pixel numbers), but NOT as a TIFF.

If we want to deliver a coverage then we must deliver /.../all (which is the compromise syntax we chose), all else is not a coverage.

Maybe we devote some discussion in Bethesda to it to inspect this; the coverage tutorials also provide helpful information on coverage encoding (which is what we discuss here). Among others, I'd be curious what a "coverage from a feature perspective" concretely looks like, ie: a concrete example file. That might be helpful for discussion.

[jerstlouis]

I think this issue is solved / overcome by events, specifically:

opengeospatial/ogcapi-common#140

#64

A collection can now be potentially accessible as both a coverage and features.

itemType is strictly for OGC APIs making use of /collections/{collectionId}/items (e.g. Features and Records).
What determines that a collection is accessible as a coverage is the presence of a link with the http://www.opengis.net/def/rel/ogc/1.0/coverage relation type (normally pointing to a /coverage resource).

Opened issue #99 to discuss subsetting by range type to address ?rangesubset= aspect.

The /coverage end-point is what used to be /coverage/all, and will have all CIS coverage components, to the extent that the netogiated media type supports describing them.
The server can optionally also provide a /coverage/rangeset with only the range set (sample values) for media types that do support this.

[Schpidi]

Coverages SWG call: Agreed to close.