search

opengeospatial / ogcapi-coverages

OGC API - Coverages draft specification
https://ogcapi.ogc.org/coverages
Apache License 2.0
22 stars 13 forks source link

Scenes requirements class #171

Closed jerstlouis closed 1 year ago

jerstlouis commented 1 year ago

As proposed in Testbed 17 GeoDataCube API Engineering Report (5.2.6 Scenes API), it would make a lot of sense to define an optional requirements class for listing the individual component scenes of a coverage (e.g., LANDSAT scenes), retrieving metadata for each of the scenes, filtering them based on metadata such as a maximum cloud coverage, time and area of interest, (similar to STAC and ideally based on the OGC API - Records Local Resource Catalog concept where in this case the resource is the scenes) retrieving a coverage for each of them as well as the description of their domains.

By making the ../coverage resource not tied specifically to /collections/{collectionId}, we could easily support /collections/{collectionId}/scenes/{sceneId}/coverage for retrieving the coverage of an individual scene. The JSON schema for /collections/{collectionId}/scenes/{sceneId} would include an extent property just like the one at /collections/{collectionId}, plus additional scene-specific record fields such as those defined by STAC / Records.

Both /collections/{collectionId}/scenes and /collections/{collectionId}/scenes/{sceneId} would be modeled after the Records Local Resource Catalog concept.

All scenes of a coverage would share the same RangeType / Schema of observed/measured fields/properties.

The individual scenes of a coverage may have a different native CRS than the overall coverage e.g., each scene may be in a particular UTM grid whereas the overall coverage is available in WGS84. This requirements class would enable some of the use cases that the more complex multi-part CIS coverages addressed.

This requirements class could be either included in Part 1 or in a Part X extension.

The /collections/{collectionId}/scenes/ could also be where a CRUD extension for Coverages allows adding/updating/deleting individual scenes as explored in the Testbed 15 "Images API".

This extension could also be supported as a building blocks for other specifications such as Maps and Tiles (of a particular scene), and even potentially extended to feature collections organized in separate component parts.

chris-little commented 1 year ago

@jerstlouis Isn't the ../collections/{collectionId}/scenes/{sceneId}/.. approach outlined in the Testbed 17 Engineering Report similar to, or even the same as, the API-EDR ../collections/{collectionId}/instances/{insanceId}/.. ?

"The instance query type allows this data to be described as different views of the same collection"

The terminology scenes implies specific to a visual representation.

jerstlouis commented 1 year ago

@chris-little I have not fully understood the concept of instances yet in EDR (despite really trying to), but according to that definition you just quoted, definitely not.

Different scenes are not different views on the same collection, but different components of the collection.

That is the coverage consists of the function that provides values for a direct position for any position within each of the component scenes.

Scenes does not imply anything specific to a visual representation. Scenes is the term used for example by the Landsat data products.

In this sense, the concept of a scene is more akin to an individual part of the MultiPart coverage of CIS, but at a more abstract level not implying any particular physical encoding or object (not necessarily linking directly to the files from which the coverage function sources its data for example, the data could be in an arbitrary data store or still purely a mathematical function).

chris-little commented 1 year ago

@jerstlouis Think of instances as versions, which are usually different components but with some common metadata. E.g. draft, 2nd draft, final versions of some data,;or uncalibrated or calibrated; or test, development or production.

The bbox of the collection instances/components would be the same, andthe instances metadata could be queried just like the collection metadata.

Is that the same as scenes?

jerstlouis commented 1 year ago

@chris-little Not exactly the same as scenes.

The bbox and/or the datetime of each scene is different.

There is this similar concept that the metadata of each scene could be queried -- even as part of a coverage request filter, even together with the individual cell ("pixel") values.

The most important distinction I believe is that with scenes it is meaningful to put all of those scenes together to return a coverage such as by doing a mosaic and filtering out clouds.

With your concept of instance, if I understand correctly you would never want to mix and merge multiple "versions" to return all of the data together. They are like the different experiment runs, or the different forecasts started from different observation times or for a different time period.

However, I agree that we could have shared concepts that apply to both. For sure the Local Resource Catalog requirements class of Records would cover a lot of that:

Something else that might be shared is the data access point for a specific instance or scene:

In this sense, I am considering that the ../coverage resource may not necessarily be tied to the /collections/{collectionId} resource (like the ../map and ../tiles resources in Maps & Tiles).

When you have instances for a particular collection in EDR, what does /collections/{collectionId}/cube return? a default instance, or composite of all instances together?

chris-little commented 1 year ago

@jerstlouis Thanks for the explanation of the differences. If there are instances in a collection, it is up to the service provider to decide what is returned: nothing/error condition, a default instance or possibly all instances (but the latter is not really recommended, as we are trying to reduce data volumes!) We are considering an OGC API-EDR Part 3 which could do summary stats and/or aggregation which might be a standardised way of addressing the latter use case.

jerstlouis commented 1 year ago

@chris-little I hope we can consider alignment for aggregation, at least the aggregation functions and their meaning. We are also looking at the aggregation functions defined by WCPS and openEO.

cnreediii commented 1 year ago

@jerstlouis Not to be picky, but is scene defined somewhere? Not in the TB 17 ER. I ask because QGIS, GDAL, Esri, etc all use 'scene' in reference to a "symbolized geospatial content that allows you to visualize and analyze geographic information in an intuitive and interactive 3D environment". This is different than a Landsat scene. Should have a definition to avoid confusion.

jerstlouis commented 1 year ago

@cnreediii For sure we need to clarify the meaning, and add scene to the terms and definition in this particular context. Thanks for pointing this out!

EDIT: added a draft definition of Scene

https://github.com/opengeospatial/ogcapi-coverages/blob/2023edits/standard/clause_4_terms_and_definitions.adoc#scene

jerstlouis commented 1 year ago

A first draft of the Scenes requirement class has been merged with #172.

chris-little commented 1 year ago

@jerstlouis Further to my comment last week, as API-EDR Instances are like Collections, they can have the full gamut of extents, values/parameters, CRSs, etc exactly like a Collection, so I still think there is a strong overlap with Scenes. In particular, we envisaged a specific query, or whatever type and extent, time, parameters may be repeated against a different Collection or Instance, and therefore could be stored as an Item (it is an abstract potential feature of interest) This seems to have commonalaity with 'Scene' too.

jerstlouis commented 1 year ago

@chris-little A specific requirement of Scenes here is that they share the same fields (that you call value/parameters in EDR) as the collection. But yes there is commonality.