From e240ce7287cb0f3ed4260b99a26d369decee4494 Mon Sep 17 00:00:00 2001 From: pcampalani Date: Thu, 22 Jun 2023 20:02:24 +0200 Subject: [PATCH 1/8] Initialize openEO/OGC-Coverages crosswalk document. --- crosswalks/ogcapi-coverages.md | 177 +++++++++++++++++++++++++++++++++ 1 file changed, 177 insertions(+) create mode 100644 crosswalks/ogcapi-coverages.md diff --git a/crosswalks/ogcapi-coverages.md b/crosswalks/ogcapi-coverages.md new file mode 100644 index 00000000..542dc1a8 --- /dev/null +++ b/crosswalks/ogcapi-coverages.md @@ -0,0 +1,177 @@ +# Crosswalk between openEO API and OGC API - Coverages + +This document gives a brief overview over similarities and differences between +- [**openEO API, v1.2.0**](https://api.openeo.org/1.2.0/) +- [**OGC API - Coverages - Part 1: Core, v0.0.6**](https://docs.ogc.org/DRAFTS/19-087.html) + + +This *OGC API - Coverages* draft specification establishes how to access coverages as defined by the +[OGC Abstract Specification Topic 6](https://portal.ogc.org/files/?artifact_id=19820) / +[ISO 19123](https://www.iso.org/standard/40121.html) *Schema for coverage geometry and functions*, +and it thus represents an alternative to the established OGC +[Web Coverage Service (WCS)](http://docs.opengeospatial.org/is/17-089r1/17-089r1.html) +interface standard (v2.1). + +The strategy behind the development of the *OGC API - Coverages* specification is to +develop a minimal, relatively simple API standard first, with new capabilities being incrementally +added based on the community demands. Also, while defining how to access (portions of) +coverages from a catalog, the standard does not specify the encoding of the coverage +itself given in response, not limiting it to "internal" OGC encodings like the +[CIS 1.1](http://www.opengis.net/doc/IS/cis/1.1.1), or +[CF-netCDF](https://www.ogc.org/standard/netcdf/)), but also to e.g. +[CoverageJSON](https://covjson.org/), [COPC](https://copc.io/), etc. + +This crosswalk will proceed by comparing such standard with the openEO API, touching +all the functionalities that are declared in the OGC standard, i.e.: + +- (meta)data retrieval +- subsetting through dimension(s) +- range (bands) subsetting +- up/down-scaling +- data retrieval as tiles + +## Abbreviations + +- **openEO** : *openEO API, v1.2.0* +- **OAC1** : *OGC API - Coverages - Part 1* + +## Nomenclature + +Despite stemming from the [OGC API - Features](http://docs.opengeospatial.org/is/17-069r3/17-069r3.html) standards, +openEO/STAC and OGC have both a different terminology and data models, so here +we put the definitions of the most relevant terms of both "worlds". + +Most notably, an OGC [*coverage*](http://myogc.org/go/coveragesDWG) — +even though formally defined as a *feature* +(and not a *collection* thereof) — is frequently an abstraction for a +*collection* of (generally, but not limited to, gridded) datasets/items +(like time-series of satellite images for instance), +so we can generally compare it with STAC [collections](https://github.com/radiantearth/stac-spec/blob/master/collection-spec/collection-spec.md), +especially [datacubes](https://openeo.org/documentation/1.0/datacubes.html). + +### OGC + +**`collection`** +A set of **features** from a dataset. + +**`coverage`** +A **feature** that acts as a function to return values from its **range** for any direct +position within its spatial, temporal or spatiotemporal **domain**; +this can be equivalent to either a [STAC Item](https://github.com/radiantearth/stac-spec/tree/master/item-spec) +or [Collection](https://github.com/radiantearth/stac-spec/blob/master/collection-spec/collection-spec.md). + +**`domain`** +A set of direct positions along some *axis* in space and time (or other dimensions) that define the +"location" of a coverage, associated with a (compounding of) spatio(-temporal)(-other) coordinates +reference system, and for each of which a set of 1+ values (**range**) are associated. + +**`feature`** +An abstraction of real world phenomena. + +**`range`** +Set of **feature** attribute values associated by a function with the elements of the **domain** of a +coverage, that means the stored values of a coverage like for instance the spectral bands; +In the STAC [`datacube`](https://github.com/stac-extensions/datacube) extension, **range** and **domain** +are condensed into the same **cube:dimensions** container. + +### STAC + +**`catalog`** +A logical group of other **catalog**, **collection**, and **item** objects. + +**`collection`** +A set of common fields to describe a group of **items** that share properties and metadata + +**`item`** +A GeoJSON Feature augmented with foreign members relevant to a STAC object. + +**`cube:dimensions`** +A set of dimensions that can be of different types: spatial, temporal, "other", etc. + + +## Crosswalk + +*Executive summary (tl;dr)* : ... + + +### Meta / API capabilities + +In this section we go through the available information on the API capabilities, +very relevant for interoperability and "machine-actionable" services. + +#### Well-known URIs + +- openEO: [`GET /.well-known/openeo`](https://api.openeo.org/1.2.0/#tag/Capabilities/operation/connect) (optional) + +- OAC1: `n/a` + +Site-wide metadata information, in **openEO** this is a list of versions of the API that the server supports, +and it is meant to help a client choose the most suitable endpoint (eg. production/develpment). + +Not available in **OAC1**. + + +#### Landing page + +- openEO: [`GET /`](https://api.openeo.org/1.2.0/#tag/Capabilities/operation/capabilities) (required) + +- OAC1: `GET /` (required) + +Both landing pages stem from the [OGC API - Common](https://ogcapi.ogc.org/common/) standard, +and they only have minor differences in the returned schemas. + +#### Conformance + +- openEO: [`GET /conformance`](https://api.openeo.org/1.2.0/#tag/Capabilities/operation/conformance) (optional) (only from v1.2.0) + +- OAC1: `GET /conformance` (required) + +Both endpoints are 100% equivalent (**openEO** additionally allows to list the conformance classes in the landing page, +following the STAC API). + + +#### API description + +- openEO: `n/a` (?) + +- OAC1: `GET /api` (required) + +In **OAC1** this is contains the description of the API (eg. OpenAPI), and optionally some +documentation (eg. HTML). + +In **openEO** this is missing. + + +### (Meta)data retrieval + +... + + +### Domain subsetting + +... + +### Range subsetting + +... + + +### Scaling + +... + +### Tiles + +... + + +## References + +- **openEO API, v1.2.0** — https://api.openeo.org/1.2.0/ + +- **OGC API - Coverages - Part 1: Core, v0.0.6** — https://docs.ogc.org/DRAFTS/19-087.html + +- **OGC Abstract Specification Topic 6** - *Schema for coverage geometry and functions* — https://portal.ogc.org/files/?artifact_id=19820 + +- **OGC Web Coverage Service (WCS) 2.1 Interface Standard** — http://docs.opengeospatial.org/is/17-089r1/17-089r1.html +interface standard (v2.1). From 775db9f7a3a8a93e074f0d184a0c3bdc6eb99ded Mon Sep 17 00:00:00 2001 From: pcampalani Date: Fri, 23 Jun 2023 13:15:33 +0200 Subject: [PATCH 2/8] Drafting coverages crosswalk. --- crosswalks/ogcapi-coverages.md | 104 +++++++++++++++++++++++++++++---- 1 file changed, 93 insertions(+), 11 deletions(-) diff --git a/crosswalks/ogcapi-coverages.md b/crosswalks/ogcapi-coverages.md index 542dc1a8..3de6158f 100644 --- a/crosswalks/ogcapi-coverages.md +++ b/crosswalks/ogcapi-coverages.md @@ -71,7 +71,7 @@ An abstraction of real world phenomena. **`range`** Set of **feature** attribute values associated by a function with the elements of the **domain** of a coverage, that means the stored values of a coverage like for instance the spectral bands; -In the STAC [`datacube`](https://github.com/stac-extensions/datacube) extension, **range** and **domain** +in the STAC [`datacube`](https://github.com/stac-extensions/datacube) extension, **range** and **domain** are condensed into the same **cube:dimensions** container. ### STAC @@ -99,7 +99,7 @@ A set of dimensions that can be of different types: spatial, temporal, "other", In this section we go through the available information on the API capabilities, very relevant for interoperability and "machine-actionable" services. -#### Well-known URIs +### Well-known URIs - openEO: [`GET /.well-known/openeo`](https://api.openeo.org/1.2.0/#tag/Capabilities/operation/connect) (optional) @@ -111,7 +111,7 @@ and it is meant to help a client choose the most suitable endpoint (eg. producti Not available in **OAC1**. -#### Landing page +### Landing page - openEO: [`GET /`](https://api.openeo.org/1.2.0/#tag/Capabilities/operation/capabilities) (required) @@ -120,7 +120,7 @@ Not available in **OAC1**. Both landing pages stem from the [OGC API - Common](https://ogcapi.ogc.org/common/) standard, and they only have minor differences in the returned schemas. -#### Conformance +### Conformance - openEO: [`GET /conformance`](https://api.openeo.org/1.2.0/#tag/Capabilities/operation/conformance) (optional) (only from v1.2.0) @@ -130,40 +130,121 @@ Both endpoints are 100% equivalent (**openEO** additionally allows to list the c following the STAC API). -#### API description +### API description - openEO: `n/a` (?) - OAC1: `GET /api` (required) -In **OAC1** this is contains the description of the API (eg. OpenAPI), and optionally some +In **OAC1** this contains the description of the API (eg. OpenAPI), and optionally some documentation (eg. HTML). In **openEO** this is missing. -### (Meta)data retrieval +### Authentication +- openEO: [GET /credentials/basic](https://api.openeo.org/1.2.0/#section/Authentication) + and/or [GET /credentials/oidc](https://api.openeo.org/1.2.0/#section/Authentication) + +- OAP1: `n/a` + +**openEO** defines two authentication mechanisms: +[OpenID Connect](https://developers.google.com/identity/openid-connect/openid-connect) (primary) +and HTTP Basic (for development/testing). **OAC1** does not define any authentication mechanisms, +and while both mechanisms could be implemented, **OAC1** clients will likely not support them. + +The availability of the authentication mechanisms is detected through the endpoints in the +[landing page](#landing-page) in **openEO**, while in **OAC1** you need to parse the +OpenAPI document for it (which implicitly requires a link to an OpenAPI 3.0 file with +relation type `service-desc` in the landing page). + + +### Data discovery + +{datasetAPI}/collections +-> abbreviated copy of Collection Resource (OGC API-Common Part 2 Standard.) ... +### Data description + +{datasetAPI}/collections/{collectionId} +{datasetAPI}/collections/{collectionId}/coverage/rangetype +{datasetAPI}/collections/{collectionId}/coverage/domainset +{datasetAPI}/collections/{collectionId}/coverage/metadata +--> All of the collections described on a Coverages API will be be CIS covaerages -### Domain subsetting +Due to the multi-dimensional nature of coverages, it is desireable for an +API to describe the extent of a coverage along those additional dimensions. +OAC1 addresses this need through an extension of the Collection Resource which supports additional dimensions. +This is accomplished by replacing the Extent module with the `Extent-UAD` module. + +coverage's metadata (may be empty) (wg. domain-specific) ... -### Range subsetting +### Data access ... +{datasetAPI}/collections/{collectionId}/coverage +{datasetAPI}/collections/{collectionId}/coverage/rangeset +Values can be represented in-line or by reference to an external file which may have any suitable encoding. + +### Data subsetting + +#### Domain +-> multi-dimensional coverage, thus: +bbox: Bounding Box +datetime: Date and Time +subset: Subset -### Scaling +BBOX: default WGS84 (alternative CRS can be specified) lat/lon + ellipsoidal height. +Data that INTERSECTS with the bbox is returned + all resources in the collection that +are not associated with a spatial geometry. +"Intersects" means that a coordinate that is part of the spatial geometry of the resource falls within the area specified in the parameter bbox. This includes the boundaries of the geometries. + +DATETIME: [ABNF](https://datatracker.ietf.org/doc/html/rfc5234) syntax is used to specify the intervals, +or "temporal geometries", with double-dots '..' to specify open ranges. +INTERSECTION as specified for the bbox, mutatis mutandis. + +SUBSET: general low:high either numeric or text-based interval definition (also single point slicing is allowed) +with asterisks '*' used for open ranges. + +Also planned: Consider returing a URI instead of the content if the content is too large. +Or - return a reduced resolution coverage with a URI to the full resolution response +... + +#### Range +`properties` parameter for selecting a subset of the DataRecord fields (defined in the Range Type, e.g. individual imagery bands) . +filtering can be done via band names, or using numeric indexes (order of the band in the range set) + + +### Data scaling + + += retrieving data from n-dimensional Range Sets at a resolution different than the original + + parameters: scale-size or scale-factor or scale-axes ... ### Tiles +.../{collectionId}/coverage/tiles -> list of tiles ("tileset") +.../{collectionId}/coverage/tiles/{tileMatrixSetId} -> tileset description +.../{collectionId}/coverage/tiles/{tileMatrixSetId}/{tileMatrix}/{tileRow}/{tileCol} -> data tile +combine the OGC API - Tiles Part1:Core building blocks with the Coverages API to request coverage tiles + +RESULT = subset of the coverage trimmed on the axes defined by the 2D Tile Matrix Set to cover the exact geospatial extent of the tile. ... +### Media encoding + +A description of the media types is mandatory for any OGC standard which involves data encodings. + +OGC standard does not mandate any particular encoding or format (CIS JSON recommended), +also binary formats (CIS RDF, NetCDF, GeoTIFF, PNG, JPEG, JPEG-2000, etc) ## References @@ -173,5 +254,6 @@ In **openEO** this is missing. - **OGC Abstract Specification Topic 6** - *Schema for coverage geometry and functions* — https://portal.ogc.org/files/?artifact_id=19820 +- **OGC API - Tiles - Part 1: Core Standard 1.0.0** — https://docs.ogc.org/is/20-057/20-057.html + - **OGC Web Coverage Service (WCS) 2.1 Interface Standard** — http://docs.opengeospatial.org/is/17-089r1/17-089r1.html -interface standard (v2.1). From 85172d73590cca190a462d76c32e06bd7d1e6c47 Mon Sep 17 00:00:00 2001 From: pcampalani Date: Fri, 23 Jun 2023 18:34:31 +0200 Subject: [PATCH 3/8] First openEO/OGC-Coverages crosswalk draft. --- crosswalks/ogcapi-coverages.md | 254 +++++++++++++++++++++++++-------- 1 file changed, 198 insertions(+), 56 deletions(-) diff --git a/crosswalks/ogcapi-coverages.md b/crosswalks/ogcapi-coverages.md index 3de6158f..0ac30510 100644 --- a/crosswalks/ogcapi-coverages.md +++ b/crosswalks/ogcapi-coverages.md @@ -4,6 +4,9 @@ This document gives a brief overview over similarities and differences between - [**openEO API, v1.2.0**](https://api.openeo.org/1.2.0/) - [**OGC API - Coverages - Part 1: Core, v0.0.6**](https://docs.ogc.org/DRAFTS/19-087.html) +[TOC] + +## Introduction This *OGC API - Coverages* draft specification establishes how to access coverages as defined by the [OGC Abstract Specification Topic 6](https://portal.ogc.org/files/?artifact_id=19820) / @@ -30,7 +33,7 @@ all the functionalities that are declared in the OGC standard, i.e.: - up/down-scaling - data retrieval as tiles -## Abbreviations +NOTE: the following abbreviations will be used throughout the document: - **openEO** : *openEO API, v1.2.0* - **OAC1** : *OGC API - Coverages - Part 1* @@ -56,14 +59,14 @@ A set of **features** from a dataset. **`coverage`** A **feature** that acts as a function to return values from its **range** for any direct -position within its spatial, temporal or spatiotemporal **domain**; +position within its spatial, temporal or spatio-temporal **domain**; this can be equivalent to either a [STAC Item](https://github.com/radiantearth/stac-spec/tree/master/item-spec) or [Collection](https://github.com/radiantearth/stac-spec/blob/master/collection-spec/collection-spec.md). **`domain`** A set of direct positions along some *axis* in space and time (or other dimensions) that define the "location" of a coverage, associated with a (compounding of) spatio(-temporal)(-other) coordinates -reference system, and for each of which a set of 1+ values (**range**) are associated. +reference system (CRS), and for each of which a set of 1+ values (**range**) are associated. **`feature`** An abstraction of real world phenomena. @@ -91,7 +94,27 @@ A set of dimensions that can be of different types: spatial, temporal, "other", ## Crosswalk -*Executive summary (tl;dr)* : ... +*Executive summary (tl;dr)* + +The capabilities of **openEO** and **OAC1** largely overlap, +though, as also declared in the standard draft's preface, **OAC1** is a simpler +service, with limited functionality in its core specification +(eg. no authentication/authorization management, processes, +batch jobs, logs, processing budgets, etc). + +**OAC1** usually provide simpler ways to request basic operations on +datasets (like filtering or resampling), by using the query parameters of +the URLs. **openEO** on the other hand allows for a much powerful service +with processing graphs and asynchronous jobs management, at the cost of a +slightly more laborious way to execute the most basic "processing" operations. + +The data model of the "coverage" is generally a bit more flexible with regards +to the "arbitrary" non-spatial non-temporal dimensions, while the processes +in **openEO** generally do not include such dimensions. + +The only **OAC1** capability that **openEO** does not directly provide (if not +via cascade with a secondary tiles service) is to attach tilesets to coverages, and hence +enable tiled access to the data. ### Meta / API capabilities @@ -106,7 +129,7 @@ very relevant for interoperability and "machine-actionable" services. - OAC1: `n/a` Site-wide metadata information, in **openEO** this is a list of versions of the API that the server supports, -and it is meant to help a client choose the most suitable endpoint (eg. production/develpment). +and it is meant to help a client choose the most suitable endpoint (eg. production/development). Not available in **OAC1**. @@ -162,89 +185,205 @@ relation type `service-desc` in the landing page). ### Data discovery -{datasetAPI}/collections --> abbreviated copy of Collection Resource (OGC API-Common Part 2 Standard.) -... +- openEO: + - [`GET /collections`](https://api.openeo.org/1.2.0/#tag/EO-Data-Discovery/operation/list-collections) (required) + - [`GET/POST /search`] + +- OAC1: + - `GET /collections` (required) + +**openEO** and **OAC1** both provide a resource for accessing the +whole catalog of datacubes/coverages offered by the server, +with basic/abbreviated metadata for each of the assets in order +to try to keep the response size small. +Full metadata details are instead available as per [data description](#data-description). + +CIS coverages will be returned by **OAC1**, STAC Collections by **openEO**. + +Optionally, **openEO** allows for searching for individual STAC items "hidden" +inside the collections, as per [STAC API repository](https://github.com/radiantearth/stac-spec/tree/v0.9.0/api-spec). + ### Data description -{datasetAPI}/collections/{collectionId} -{datasetAPI}/collections/{collectionId}/coverage/rangetype -{datasetAPI}/collections/{collectionId}/coverage/domainset -{datasetAPI}/collections/{collectionId}/coverage/metadata ---> All of the collections described on a Coverages API will be be CIS covaerages +- openEO: + - [`GET /collections/{collectionId}`](https://api.openeo.org/1.2.0/#tag/EO-Data-Discovery/operation/describe-collection) (required) + - [`GET /collections/{collectionId}/queryables`](https://api.openeo.org/1.2.0/#tag/EO-Data-Discovery/operation/list-collection-queryables) + +- OAC1: + - `GET /collections/{collectionId}` (required) + - `GET /collections/{collectionId}/coverage/rangetype` (required) + - `GET /collections/{collectionId}/coverage/domainset` (required) + - `GET /collections/{collectionId}/coverage/metadata` (optional) + +Full metadata descriptions of collections are available in both **openEO** and **OAC1**, +encoded as STAC Collections or CIS Coverages, respectively. -Due to the multi-dimensional nature of coverages, it is desireable for an -API to describe the extent of a coverage along those additional dimensions. -OAC1 addresses this need through an extension of the Collection Resource which supports additional dimensions. -This is accomplished by replacing the Extent module with the `Extent-UAD` module. +Additional links are provided (required) for coverages in **OAC1** with respect to the +basic "Collection Resources" defined in the OGC API - Common: one for +the description of the sole "range" of the coverage, and one for +the sole "domain", which are anyway just a subset of the full +metadata description. Also available, tough optional, is the +link to the sole coverage's "metadata", meaning supplementary/domain-specific +extra metadata fields that might be attached to a coverage. -coverage's metadata (may be empty) (wg. domain-specific) +**openEO** offers a more flexible and machine-actionable solution for +filtering the description of a collection, by means of the "queryables": +a listing of all metadata filters available for each collection. +This is in line with both [`filter`](https://github.com/stac-api-extensions/filter#queryables) STAC API extension +and [OGC API - Features - Part 3: Filtering](https://github.com/opengeospatial/ogcapi-features/tree/master/extensions/filtering). -... ### Data access -... +- openEO: + - [`POST /result`](https://api.openeo.org/1.2.0/#tag/Data-Processing/operation/compute-result)@ +[load_collection](https://processes.openeo.org/#load_collection) process + - [`POST /jobs`](https://api.openeo.org/1.2.0/#tag/Batch-Jobs/operation/create-job)@ +[resample_spatial](https://processes.openeo.org/#load_collection) process + +[`POST /jobs/{jobId}/results`](https://api.openeo.org/1.2.0/#tag/Batch-Jobs/operation/start-job) + +- OAC1: + - `GET /collections/{collectionId}/coverage` (required) + - `GET /collections/{collectionId}/coverage/rangeset` (optional) + +**OAC1** : encoding as negotiated in the HTTP protocol, with proper fallback media type +otherwise. The actual coverage values (the range set) can be represented either in-line +or by reference to an external file which may have any suitable encoding. + +**openEO** provides access to the actual data by means of the +[load_collection](https://processes.openeo.org/#load_collection) process, which can +be submitted either synchronously or asynchronously as a batch job. + +For pre-filtering / data subsetting options, see next section. -{datasetAPI}/collections/{collectionId}/coverage -{datasetAPI}/collections/{collectionId}/coverage/rangeset -Values can be represented in-line or by reference to an external file which may have any suitable encoding. ### Data subsetting -#### Domain --> multi-dimensional coverage, thus: -bbox: Bounding Box -datetime: Date and Time -subset: Subset +- openEO: + - [`POST /result`](https://api.openeo.org/1.2.0/#tag/Data-Processing/operation/compute-result)@ +[load_collection](https://processes.openeo.org/#load_collection) process + - [`POST /jobs`](https://api.openeo.org/1.2.0/#tag/Batch-Jobs/operation/create-job)@ +[resample_spatial](https://processes.openeo.org/#load_collection) process + +[`POST /jobs/{jobId}/results`](https://api.openeo.org/1.2.0/#tag/Batch-Jobs/operation/start-job) -BBOX: default WGS84 (alternative CRS can be specified) lat/lon + ellipsoidal height. -Data that INTERSECTS with the bbox is returned + all resources in the collection that -are not associated with a spatial geometry. -"Intersects" means that a coordinate that is part of the spatial geometry of the resource falls within the area specified in the parameter bbox. This includes the boundaries of the geometries. +- OAC1: + - `bbox` / `datetime` / `subset` query params (domain subsetting) + - `properties` query param (range subsetting) -DATETIME: [ABNF](https://datatracker.ietf.org/doc/html/rfc5234) syntax is used to specify the intervals, -or "temporal geometries", with double-dots '..' to specify open ranges. -INTERSECTION as specified for the bbox, mutatis mutandis. -SUBSET: general low:high either numeric or text-based interval definition (also single point slicing is allowed) -with asterisks '*' used for open ranges. +The parameters offered by the [load_collection](https://processes.openeo.org/#load_collection) **openEO** process +allows for subsetting the requested collection along a cube's dimensions, which +includes also what **OAC1** calls the range set, hence the "bands" of the dataset. +There is no option for lo:hi subsetting of an arbitrary dimension which might +not be classified as neither spatial nor temporal, like the `subset` query +parameter offers in **OAC1**. -Also planned: Consider returing a URI instead of the content if the content is too large. -Or - return a reduced resolution coverage with a URI to the full resolution response -... +Spatial subsetting in **openEO** is more powerful as not only bounding-boxes but +also GeoJSON geometries can be specified for a more accurate clipping of the data. +On the other hand **OAC1** accepts open/unbounded spatial intervals. +Open/unbounded time intervals are supported in both APIs (via `null` or double-dots `..`, +respectively). -#### Range -`properties` parameter for selecting a subset of the DataRecord fields (defined in the Range Type, e.g. individual imagery bands) . -filtering can be done via band names, or using numeric indexes (order of the band in the range set) +Spatial filtering with coordinates specified with an arbitrary CRS is available +in both APIs. In both cases, all data values that spatially *intersect* +with the provided spatial extent/range (boundaries included) will be in the response. +Subsetting of an arbitrary dimension — not classified as spatial not temporal, nor band +in the openEO datacube model — is not possible in **openEO**, while available +in **OAC1** via `subset` parameters. -### Data scaling +In case the response is too large, **OAC1** plans to consider returning a URI +instead of the content, or a reduced-resolution coverage with a URI to the full resolution response. + +Filtering/cherry-picking of bands is available in both **OAC1** and **openEO**, via +`properties` parameter and [load_collection](https://processes.openeo.org/#load_collection) +process respectively. Both band names and band indices can be used in **OAC1**, +while **openEO** accepts band names exclusively. + +An **openEO** server can optionally provide a rough estimate of the time/cost +of a stored job via [`/jobs/{jobId}/estimate`](https://api.openeo.org/1.2.0/#tag/Data-Processing/operation/estimate-job). +Server logs are also available in **openEO** either directly in the synchronous processing +response (as a link), or via the API resources dedicated to the batch jobs +(eg. `josb/{jobId}/logs`). -= retrieving data from n-dimensional Range Sets at a resolution different than the original +### Data scaling - parameters: scale-size or scale-factor or scale-axes +- openEO: + - [`POST /result`](https://api.openeo.org/1.2.0/#tag/Data-Processing/operation/compute-result)@ +[resample_spatial](https://processes.openeo.org/#resample_spatial) process + - [`POST /jobs`](https://api.openeo.org/1.2.0/#tag/Batch-Jobs/operation/create-job)@ +[resample_spatial](https://processes.openeo.org/#resample_spatial) process + +[`POST /jobs/{jobId}/results`](https://api.openeo.org/1.2.0/#tag/Batch-Jobs/operation/start-job) + +- OAC1: + - `GET /collections/{collectionId}/coverage?scale-size=axisName({number})[,axisName({number})]*` + - `GET /collections/{collectionId}/coverage?scale-axes=axisName({number})[,axisName({number})]*` + - `GET /collections/{collectionId}/coverage?scale-factor={number}` + +Rescaling a dataset in **openEO** requires the same procedure as for any other kind +of processing, thus preparing a process graph that executes the desired operation, then +fetch the results, either synchronously or asynchronously through the creation of a +[batch job](https://api.openeo.org/1.2.0/#tag/Data-Processing/operation/create-job). + +At the time of writing, the available **openEO** processes for data resampling are +[`resample_spatial`](https://processes.openeo.org/#resample_spatial) — +that rescales the spatial dimensions to a target resolution, or to +a target spatial coordinate reference system — and +[resample_cube_spatial](https://processes.openeo.org/#resample_spatial)/ +[resample_cube_temporal](https://processes.openeo.org/#resample_cube_temporal), that +rescale the spatial/temporal dimensions to match the resolutions of a +provided target datacube. + +While **OAC1** does not let a user specify +a resolution, it lets a client specify the target number of samples +along a dimension, or the scaling factor. While the capabilities +of a user-defined process with asynchronous job management +go well beyond data the resampling of a dataset and provide +a wide range of benefits, **OAC1** provides a somewhat simpler shortcut +for via query parameters of the URL. + +**OAC1** also allows for scaling on *any* coverage's dimension, while +**openEO** only along the spatial plane/dimensions. -... ### Tiles -.../{collectionId}/coverage/tiles -> list of tiles ("tileset") -.../{collectionId}/coverage/tiles/{tileMatrixSetId} -> tileset description -.../{collectionId}/coverage/tiles/{tileMatrixSetId}/{tileMatrix}/{tileRow}/{tileCol} -> data tile -combine the OGC API - Tiles Part1:Core building blocks with the Coverages API to request coverage tiles +- openEO: `n/a` (?) + +- OAC1: + - `GET /collections/{collectionId}/coverage/tiles` : list the available tilesets + - `GET /collections/{collectionId}/coverage/tiles/{tileMatrixSetId}` : tileset description + - `GET /collections/{collectionId}/coverage/tiles/{tileMatrixSetId}/{tileMatrix}/{tileRow}/{tileCol}` : retrieve tile + +**OAC1**, in alignment with the requirements defined in the +[OGC API - Tiles](http://docs.ogc.org/DRAFTS/20-057.html) standard, allows the retrieval of +coverage data in form of tiles, hence trimmed and resampled to match the +boundaries and resolution of a given tile. More than one tilesets can be attached to a coverage. + +**openEO** does not provide tiled access directly, but can be easily cascaded to +a dedicated secondary tile service (like [XYZ tiles](https://wiki.openstreetmap.org/wiki/Slippy_map_tilenames)) +thanks to the [`/service_types`](https://api.openeo.org/1.2.0/#tag/Capabilities/operation/list-service-types) resource. (?) -RESULT = subset of the coverage trimmed on the axes defined by the 2D Tile Matrix Set to cover the exact geospatial extent of the tile. -... ### Media encoding -A description of the media types is mandatory for any OGC standard which involves data encodings. +- openEO: [`GET /file_formats`](https://api.openeo.org/1.2.0/#tag/Capabilities/operation/list-file-types) + +- OAC1: `GET /` (?) + +While not exposed as a dedicated API resource, **OAC1** requires a server to provide information about +the supported media types (probably in the landing page). + +**OAC1** does not mandate any particular output encoding or format, although CIS JSON is recommended. +Binary formats of course are also alllowed (CIS RDF, NetCDF, GeoTIFF, PNG, JPEG, JPEG-2000, etc.) + +**openEO** returns a list of data formats the server supports, with the additional +information of the data formats the server can also read from (input), and not just +write to (output). Format names and parameters are aligned with the GDAL/OGR formats although +custom file formats are also permitted. -OGC standard does not mandate any particular encoding or format (CIS JSON recommended), -also binary formats (CIS RDF, NetCDF, GeoTIFF, PNG, JPEG, JPEG-2000, etc) ## References @@ -252,8 +391,11 @@ also binary formats (CIS RDF, NetCDF, GeoTIFF, PNG, JPEG, JPEG-2000, etc) - **OGC API - Coverages - Part 1: Core, v0.0.6** — https://docs.ogc.org/DRAFTS/19-087.html +- **OGC API - Common** — https://ogcapi.ogc.org/common/ + - **OGC Abstract Specification Topic 6** - *Schema for coverage geometry and functions* — https://portal.ogc.org/files/?artifact_id=19820 - **OGC API - Tiles - Part 1: Core Standard 1.0.0** — https://docs.ogc.org/is/20-057/20-057.html - **OGC Web Coverage Service (WCS) 2.1 Interface Standard** — http://docs.opengeospatial.org/is/17-089r1/17-089r1.html + From 67904e59e572c8a113c6eeccd11d8cc95089e365 Mon Sep 17 00:00:00 2001 From: pcampalani Date: Fri, 23 Jun 2023 18:42:35 +0200 Subject: [PATCH 4/8] Minor editorial changes in crosswalk. --- crosswalks/ogcapi-coverages.md | 48 ++++++++++++++++++---------------- 1 file changed, 26 insertions(+), 22 deletions(-) diff --git a/crosswalks/ogcapi-coverages.md b/crosswalks/ogcapi-coverages.md index 0ac30510..48c667b4 100644 --- a/crosswalks/ogcapi-coverages.md +++ b/crosswalks/ogcapi-coverages.md @@ -4,6 +4,10 @@ This document gives a brief overview over similarities and differences between - [**openEO API, v1.2.0**](https://api.openeo.org/1.2.0/) - [**OGC API - Coverages - Part 1: Core, v0.0.6**](https://docs.ogc.org/DRAFTS/19-087.html) +---- + +**TABLE OF CONTENTS** + [TOC] ## Introduction @@ -167,8 +171,8 @@ In **openEO** this is missing. ### Authentication -- openEO: [GET /credentials/basic](https://api.openeo.org/1.2.0/#section/Authentication) - and/or [GET /credentials/oidc](https://api.openeo.org/1.2.0/#section/Authentication) +- openEO: [`GET /credentials/basic`](https://api.openeo.org/1.2.0/#section/Authentication) + and/or [`GET /credentials/oidc`](https://api.openeo.org/1.2.0/#section/Authentication) - OAP1: `n/a` @@ -187,7 +191,7 @@ relation type `service-desc` in the landing page). - openEO: - [`GET /collections`](https://api.openeo.org/1.2.0/#tag/EO-Data-Discovery/operation/list-collections) (required) - - [`GET/POST /search`] + - [`GET/POST /search`](https://api.openeo.org/1.2.0/#tag/EO-Data-Discovery/STAC) (optional) - OAC1: - `GET /collections` (required) @@ -208,7 +212,7 @@ inside the collections, as per [STAC API repository](https://github.com/radiante - openEO: - [`GET /collections/{collectionId}`](https://api.openeo.org/1.2.0/#tag/EO-Data-Discovery/operation/describe-collection) (required) - - [`GET /collections/{collectionId}/queryables`](https://api.openeo.org/1.2.0/#tag/EO-Data-Discovery/operation/list-collection-queryables) + - [`GET /collections/{collectionId}/queryables`](https://api.openeo.org/1.2.0/#tag/EO-Data-Discovery/operation/list-collection-queryables) (required?) - OAC1: - `GET /collections/{collectionId}` (required) @@ -237,11 +241,11 @@ and [OGC API - Features - Part 3: Filtering](https://github.com/opengeospatial/o ### Data access - openEO: - - [`POST /result`](https://api.openeo.org/1.2.0/#tag/Data-Processing/operation/compute-result)@ -[load_collection](https://processes.openeo.org/#load_collection) process - - [`POST /jobs`](https://api.openeo.org/1.2.0/#tag/Batch-Jobs/operation/create-job)@ -[resample_spatial](https://processes.openeo.org/#load_collection) process + -[`POST /jobs/{jobId}/results`](https://api.openeo.org/1.2.0/#tag/Batch-Jobs/operation/start-job) + - [`POST /result`](https://api.openeo.org/1.2.0/#tag/Data-Processing/operation/compute-result) @ +[`load_collection`](https://processes.openeo.org/#load_collection) process (sync) + - [`POST /jobs`](https://api.openeo.org/1.2.0/#tag/Batch-Jobs/operation/create-job) @ +[`load_collection`](https://processes.openeo.org/#load_collection) process + +[`POST /jobs/{jobId}/results`](https://api.openeo.org/1.2.0/#tag/Batch-Jobs/operation/start-job) (async) - OAC1: - `GET /collections/{collectionId}/coverage` (required) @@ -261,11 +265,11 @@ For pre-filtering / data subsetting options, see next section. ### Data subsetting - openEO: - - [`POST /result`](https://api.openeo.org/1.2.0/#tag/Data-Processing/operation/compute-result)@ -[load_collection](https://processes.openeo.org/#load_collection) process - - [`POST /jobs`](https://api.openeo.org/1.2.0/#tag/Batch-Jobs/operation/create-job)@ -[resample_spatial](https://processes.openeo.org/#load_collection) process + -[`POST /jobs/{jobId}/results`](https://api.openeo.org/1.2.0/#tag/Batch-Jobs/operation/start-job) + - [`POST /result`](https://api.openeo.org/1.2.0/#tag/Data-Processing/operation/compute-result) @ +[`load_collection`](https://processes.openeo.org/#load_collection) process (sync) + - [`POST /jobs`](https://api.openeo.org/1.2.0/#tag/Batch-Jobs/operation/create-job) @ +[`load_collection`](https://processes.openeo.org/#load_collection) process + +[`POST /jobs/{jobId}/results`](https://api.openeo.org/1.2.0/#tag/Batch-Jobs/operation/start-job) (async) - OAC1: - `bbox` / `datetime` / `subset` query params (domain subsetting) @@ -305,17 +309,17 @@ An **openEO** server can optionally provide a rough estimate of the time/cost of a stored job via [`/jobs/{jobId}/estimate`](https://api.openeo.org/1.2.0/#tag/Data-Processing/operation/estimate-job). Server logs are also available in **openEO** either directly in the synchronous processing response (as a link), or via the API resources dedicated to the batch jobs -(eg. `josb/{jobId}/logs`). +(eg. [`jobs/{jobId}/logs`](https://api.openeo.org/1.2.0/#tag/Batch-Jobs/operation/debug-job)). ### Data scaling - openEO: - - [`POST /result`](https://api.openeo.org/1.2.0/#tag/Data-Processing/operation/compute-result)@ -[resample_spatial](https://processes.openeo.org/#resample_spatial) process - - [`POST /jobs`](https://api.openeo.org/1.2.0/#tag/Batch-Jobs/operation/create-job)@ -[resample_spatial](https://processes.openeo.org/#resample_spatial) process + -[`POST /jobs/{jobId}/results`](https://api.openeo.org/1.2.0/#tag/Batch-Jobs/operation/start-job) + - [`POST /result`](https://api.openeo.org/1.2.0/#tag/Data-Processing/operation/compute-result) @ +[`resample_spatial`](https://processes.openeo.org/#resample_spatial) process (sync) + - [`POST /jobs`](https://api.openeo.org/1.2.0/#tag/Batch-Jobs/operation/create-job) @ +[`resample_spatial`](https://processes.openeo.org/#resample_spatial) process + +[`POST /jobs/{jobId}/results`](https://api.openeo.org/1.2.0/#tag/Batch-Jobs/operation/start-job) (async) - OAC1: - `GET /collections/{collectionId}/coverage?scale-size=axisName({number})[,axisName({number})]*` @@ -331,8 +335,8 @@ At the time of writing, the available **openEO** processes for data resampling a [`resample_spatial`](https://processes.openeo.org/#resample_spatial) — that rescales the spatial dimensions to a target resolution, or to a target spatial coordinate reference system — and -[resample_cube_spatial](https://processes.openeo.org/#resample_spatial)/ -[resample_cube_temporal](https://processes.openeo.org/#resample_cube_temporal), that +[`resample_cube_spatial`](https://processes.openeo.org/#resample_spatial)/ +[`resample_cube_temporal`](https://processes.openeo.org/#resample_cube_temporal), that rescale the spatial/temporal dimensions to match the resolutions of a provided target datacube. From 70368164cccdfefd296855a09a902d2dba4f614b Mon Sep 17 00:00:00 2001 From: Piero Campalani Date: Wed, 28 Jun 2023 16:28:32 +0200 Subject: [PATCH 5/8] OGC API - Coverages: a few more details from after testbed-19 call. --- crosswalks/ogcapi-coverages.md | 25 +++++++++++++------------ 1 file changed, 13 insertions(+), 12 deletions(-) diff --git a/crosswalks/ogcapi-coverages.md b/crosswalks/ogcapi-coverages.md index 48c667b4..758859e9 100644 --- a/crosswalks/ogcapi-coverages.md +++ b/crosswalks/ogcapi-coverages.md @@ -8,7 +8,7 @@ This document gives a brief overview over similarities and differences between **TABLE OF CONTENTS** -[TOC] +[TOC_] ## Introduction @@ -257,7 +257,9 @@ or by reference to an external file which may have any suitable encoding. **openEO** provides access to the actual data by means of the [load_collection](https://processes.openeo.org/#load_collection) process, which can -be submitted either synchronously or asynchronously as a batch job. +be submitted either synchronously, or asynchronously as a batch job. +The format of the resulting data shall always be specified by chaining a +[save_result](https://processes.openeo.org/#save_result) process. For pre-filtering / data subsetting options, see next section. @@ -354,7 +356,7 @@ for via query parameters of the URL. ### Tiles -- openEO: `n/a` (?) +- openEO: `n/a` - OAC1: - `GET /collections/{collectionId}/coverage/tiles` : list the available tilesets @@ -367,25 +369,24 @@ coverage data in form of tiles, hence trimmed and resampled to match the boundaries and resolution of a given tile. More than one tilesets can be attached to a coverage. **openEO** does not provide tiled access directly, but can be easily cascaded to -a dedicated secondary tile service (like [XYZ tiles](https://wiki.openstreetmap.org/wiki/Slippy_map_tilenames)) -thanks to the [`/service_types`](https://api.openeo.org/1.2.0/#tag/Capabilities/operation/list-service-types) resource. (?) +a dedicated secondary tiles service (like [XYZ tiles](https://wiki.openstreetmap.org/wiki/Slippy_map_tilenames)) +thanks to the [`/service_types`](https://api.openeo.org/1.2.0/#tag/Capabilities/operation/list-service-types) resource. ### Media encoding - openEO: [`GET /file_formats`](https://api.openeo.org/1.2.0/#tag/Capabilities/operation/list-file-types) -- OAC1: `GET /` (?) +- OAC1: `GET /api` -While not exposed as a dedicated API resource, **OAC1** requires a server to provide information about -the supported media types (probably in the landing page). +Both **OAC1** and **openEO** provide a list of data formats the server supports, both +the data formats the server can read from (input), and write to (output). -**OAC1** does not mandate any particular output encoding or format, although CIS JSON is recommended. +**OAC1** embeds the information in the API description available in the `/api` endpoint. +It does not mandate any particular output encoding or format, although CIS JSON is recommended. Binary formats of course are also alllowed (CIS RDF, NetCDF, GeoTIFF, PNG, JPEG, JPEG-2000, etc.) -**openEO** returns a list of data formats the server supports, with the additional -information of the data formats the server can also read from (input), and not just -write to (output). Format names and parameters are aligned with the GDAL/OGR formats although +In **openEO** format names and parameters are aligned with the GDAL/OGR formats although custom file formats are also permitted. From 1bbf9ac3bb603ddff3ba8807b6f89121a274245d Mon Sep 17 00:00:00 2001 From: Piero Campalani Date: Wed, 28 Jun 2023 16:32:55 +0200 Subject: [PATCH 6/8] ogcapi-coverages.md : add TOC. --- crosswalks/ogcapi-coverages.md | 26 ++++++++++++++++++++++++-- 1 file changed, 24 insertions(+), 2 deletions(-) diff --git a/crosswalks/ogcapi-coverages.md b/crosswalks/ogcapi-coverages.md index 758859e9..cb888794 100644 --- a/crosswalks/ogcapi-coverages.md +++ b/crosswalks/ogcapi-coverages.md @@ -1,6 +1,7 @@ # Crosswalk between openEO API and OGC API - Coverages -This document gives a brief overview over similarities and differences between +This document gives a brief overview over similarities and differences between: + - [**openEO API, v1.2.0**](https://api.openeo.org/1.2.0/) - [**OGC API - Coverages - Part 1: Core, v0.0.6**](https://docs.ogc.org/DRAFTS/19-087.html) @@ -8,7 +9,26 @@ This document gives a brief overview over similarities and differences between **TABLE OF CONTENTS** -[TOC_] + * [Introduction](#introduction) + * [Nomenclature](#nomenclature) + + [OGC](#ogc) + + [STAC](#stac) + * [Crosswalk](#crosswalk) + + [Meta / API capabilities](#meta-api-capabilities) + + [Well-known URIs](#well-known-uris) + + [Landing page](#landing-page) + + [Conformance](#conformance) + + [API description](#api-description) + + [Authentication](#authentication) + + [Data discovery](#data-discovery) + + [Data description](#data-description) + + [Data access](#data-access) + + [Data subsetting](#data-subsetting) + + [Data scaling](#data-scaling) + + [Tiles](#tiles) + + [Media encoding](#media-encoding) + * [References](#references) + ## Introduction @@ -121,6 +141,8 @@ via cascade with a secondary tiles service) is to attach tilesets to coverages, enable tiled access to the data. + + ### Meta / API capabilities In this section we go through the available information on the API capabilities, From 0e591aec3daba5a1081a3edf5d387dcd5b3905fb Mon Sep 17 00:00:00 2001 From: Piero Campalani Date: Mon, 3 Jul 2023 15:20:14 +0200 Subject: [PATCH 7/8] Update ogcapi-coverages.md --- crosswalks/ogcapi-coverages.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/crosswalks/ogcapi-coverages.md b/crosswalks/ogcapi-coverages.md index cb888794..afef71a0 100644 --- a/crosswalks/ogcapi-coverages.md +++ b/crosswalks/ogcapi-coverages.md @@ -234,7 +234,7 @@ inside the collections, as per [STAC API repository](https://github.com/radiante - openEO: - [`GET /collections/{collectionId}`](https://api.openeo.org/1.2.0/#tag/EO-Data-Discovery/operation/describe-collection) (required) - - [`GET /collections/{collectionId}/queryables`](https://api.openeo.org/1.2.0/#tag/EO-Data-Discovery/operation/list-collection-queryables) (required?) + - [`GET /collections/{collectionId}/queryables`](https://api.openeo.org/1.2.0/#tag/EO-Data-Discovery/operation/list-collection-queryables) (optional) - OAC1: - `GET /collections/{collectionId}` (required) @@ -378,7 +378,7 @@ for via query parameters of the URL. ### Tiles -- openEO: `n/a` +- openEO: -> secondary web services - OAC1: - `GET /collections/{collectionId}/coverage/tiles` : list the available tilesets @@ -390,7 +390,7 @@ for via query parameters of the URL. coverage data in form of tiles, hence trimmed and resampled to match the boundaries and resolution of a given tile. More than one tilesets can be attached to a coverage. -**openEO** does not provide tiled access directly, but can be easily cascaded to +**openEO** does not provide tiled access directly, but can be easily cascaded by a dedicated secondary tiles service (like [XYZ tiles](https://wiki.openstreetmap.org/wiki/Slippy_map_tilenames)) thanks to the [`/service_types`](https://api.openeo.org/1.2.0/#tag/Capabilities/operation/list-service-types) resource. From eb531a059287a1a13d457a60ef35836fb3515a2e Mon Sep 17 00:00:00 2001 From: Piero Campalani Date: Wed, 5 Jul 2023 10:15:02 +0200 Subject: [PATCH 8/8] Update ogcapi-coverages.md. Edited API/service description comments. --- crosswalks/ogcapi-coverages.md | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/crosswalks/ogcapi-coverages.md b/crosswalks/ogcapi-coverages.md index afef71a0..82bbcfd1 100644 --- a/crosswalks/ogcapi-coverages.md +++ b/crosswalks/ogcapi-coverages.md @@ -181,14 +181,13 @@ following the STAC API). ### API description -- openEO: `n/a` (?) +- openEO: as per `service-desc` / `service-doc` relation types - OAC1: `GET /api` (required) -In **OAC1** this contains the description of the API (eg. OpenAPI), and optionally some -documentation (eg. HTML). - -In **openEO** this is missing. +Both **openEO** and **OAC1** can provide service descriptions (eg. OpenAPI documents) and +human-readable documentation in the resources pointed by the standard `service-desc` and `service-doc` relation types. +In **OAC1** such resources shall (both) point to the `/api` endpoint. ### Authentication