search

stac-extensions / web-map-links

Allows to provide links to web maps for visualization purposes
Apache License 2.0
18 stars 3 forks source link

Add more types of Services to this extension #8

Open boeckMt opened 2 years ago

boeckMt commented 2 years ago

I wanted to ask if this extension is intended to add more types of services or should this be done in a separate extension? If not, please close this issue, if yes, you can continue reading :)

My use case is to query/search/filter through Collections/Items (which a User should do in a custom User Interface), then select one or multiple of the items and dynamically create an application to show the data through the "services" (WMS, WMTS, TMS, XYZ, Vector Tiles, WFS (KML, GeoJSON) ) in a map. Clients could be e.g. OpenLayers, Leaflet, Mapbox or QGIS... (in our case OpenLayers and the STAC API is provided via GeoServers STAC extension).

What I need is some sort of merge/link between searchability of STAC and metadata to create services for the visualisation of the items e.g. like in parts of the OGC OWS Context GeoJSON Encoding Standard. Unfortunately this standard is not being further developed and the documentation is sometimes not clear either, we tried to create interfaces for missing parts

which were only in their documentation but not completely in the OWS Context JSON schema. We also tried to create a new json-schema for it https://github.com/dlr-eoc/ukis-frontend-libraries/blob/main/projects/services-ogc/src/lib/owc/types/ukis-owc.schema.json with a few custom extensions.

Perhaps it is possible to include some of these ideas in this extension?

Maybe related issues

m-mohr commented 1 year ago

Happy to accept PRs for additional services.

ycespb commented 1 year ago

It would be nice to be able to use OGC type "offerings" and "operations" from OGC 14-055r2 and the underlying model OGC 12-080r2 in combination with STAC and include these in the links section.

The current OGC API-Records draft has the notion of "templated links with variables". The combination of this with OGC "offering code" and "operation code" (encoded in the "rel") may make it possible to include service bindings (in this case WCS) as shown below... Would this be suitable to extend the current extension ?

"links": [  {
            "rel": "http://www.opengis.net/spec/owc-geojson/1.0/req/wcs#GetCoverage",
            "type": "application/netcdf",
            "title": "Access via DataCube",
            "href": "http://server.com/wcs?request=GetCoverage&service=WCS&version=2.1&coverageid=ALT_L2_NRT&format={format}&subset=Lat({min_lat}},{max_lat})&subset=Long({min_long}},{max_long})&subset=time(‘{min_date}’,’{max-date}’)",
            "templated": true,
            "variables": {
                "min_long": {
                    "description": "...",
                    "type": "number",
                    "minimum": -180,
                    "maximum": 180
                },
                "max_long": {
                    "description": "...",
                    "type": "number",
                    "minimum": -180,
                    "maximum": 180
                },
                "min_lat": {
                    "description": "...",
                    "type": "number",
                    "minimum": -90,
                    "maximum": 90
                },
                "max_lat": {
                    "description": "...",
                    "type": "number",
                    "minimum": -90,
                    "maximum": 90
                },
                "max_date": {
                    "description": "...",
                    "type": "string",
                    "format": "date-time"
                },
                "min_date": {
                    "description": "...",
                    "type": "string",
                    "format": "date-time"
                },
                "format": {
                    "description": "...",
                    "type": "string",
                    "enum": [
                        "application/netcdf",
                        "image/tiff;application=geotiff""
                    ]
                }
            }
        }
  ]
boeckMt commented 1 year ago

@ycespb I also thought in the beginning to include "offerings" and "operations" from OWS Context GeoJSON but I think this is to complicated and as discussed here https://github.com/stac-extensions/web-map-links/pull/7#issuecomment-1035242349 only using the link-object would be preferred.

I think it should be implemented for each rel separately like:

WMS

Links to a OGC WMS.

Field Name Type Description
rel string REQUIRED. Must be set to wms.
href string REQUIRED. Link to the WMS Service, without or whith specific query parameters.
type string Recommended to be set to the media type the WMS Service Request returns for GetMap usually image/png or image/jpeg
wms:operation string Can be set to e.g. GetCapabilities, GetMap, GetFeatureInfo...

operation

The operation could give a hint what exactly is in the query parameters and how to parse them.

href

If no query parameters are appended on the href then the REQUIRED parameters must be set like rel:parameter e.g. wms:layers, wms:styles, wms:time... .

@m-mohr what are your opinions on this?

I don't had time for

https://github.com/stac-extensions/web-map-links/issues/8#issuecomment-1406468565 Happy to accept PRs for additional services.

but I am working on it :)

m-mohr commented 1 year ago

Thanks for the proposal. I don't understand yet what you need the wms:operation for? Wouldn't you just define the "baseUrl" and then handle it like for wmts? Having in mind that this extension is primarily for "powering" web maps using OL, Leaflet etc...

wms:layers, wms:styles etc would also need a definition.

ycespb commented 1 year ago

@boeckMt, thank for the feedback. My intention was indeed to simplify and make these just 'links' to fit the current STAC model. However, I would not reinvent the wheel and reuse part of the offerings, such as the identification of the service/operation by the "rel", using what before were the code attributes of offering and operation (this allows to use OGC 14-055r2 as kind of a codelist). In my example above, what was an operation in OGC 14-055r2 would correspond to a link. As this may not have been clear, I added "links" in the example (it was only in the text). BTW: there are other approaches online as well for these offerings, such as the DLR GeoService that uses an ogc property...

ycespb commented 1 year ago

Simpler examples would look like this:

    "links": [
        {
            "rel": "http://www.opengis.net/spec/owc-geojson/1.0/req/wcs#GetCapabilities",
            "type": "application/xml",
            "title": "DataCube GetCapabilities",
            "href": "https://server.com/wcs?service=WCS&Request=GetCapabilities"
        },
        {
            "rel": "http://www.opengis.net/spec/owc-geojson/1.0/req/wcs#DescribeCoverage",
            "type": "application/xml",
            "title": "DataCube DescribeCoverage",
            "href": "https://server.com/wcs?service=WCS&Request=DescribeCoverage&version=2.0.0&CoverageId=ALT_L2_NRT"
        }
]
boeckMt commented 1 year ago

Thanks for the proposal. I don't understand yet what you need the wms:operation for? Wouldn't you just define the "baseUrl" and then handle it like for wmts?

@m-mohr thanks for the response!

The wms:operation is not really needed, I thought this would be a helpful hint for the client what to expect in the href. It would also be an option to parse all parameters from the query.

...Having in mind that this extension is primarily for "powering" web maps using OL, Leaflet etc...

wms:layers, wms:styles etc would also need a definition.

Sometimes a client need further information from other operations like GetCapabilities, GetFeatureInfo, GetLegendGraphic e.g. to know what time range is allowed for the layer, existing styles and so forth. The wms:operation was my intention to make this more clear like @ycespb proposed with rel in https://github.com/stac-extensions/web-map-links/issues/8#issuecomment-1469588593.

m-mohr commented 1 year ago

Yes, but in general the clients make this for you as the parameters are pre-defined in the spec. Looking at Leaflet and OpenLayers:

So I'd propose to follow the route that we also defined for WMTS so you'd create just the following link for the Leaflet example:

        {
            "rel": "wms",
            "type": "application/xml",
            "title": "OWM Topographic as WMS",
            "href": "http://ows.mundialis.de/services/service",
                        "wms:layers": "TOPO-OSM-WMS"
        }

You can then just use this link for Leaflet, OpenLayers etc. This should at least be the baseline for what the main purpose of the extension is, visualizing automatically on a web map. Additional use cases than just visualizing layers on a map should be discussed separately, I think.

My focus was WMS here, but WCS should work similarly, I guess?

boeckMt commented 1 year ago

@ycespb as far as I know the ogc property in DLR GeoService was only a workaround, because of a missing extension in the STAC standard.

I agree that reusing things from OGC 14-055r2 would be good but I don't know if rel is the best thing to substitute code from OWC:Operation

@m-mohr I understand, then the best thing would be make or separate extension for our use case?

We use OpenLayers a lot but most of the time it is not enough to only display the layer in the webclient. A user wants to interact with this layers, query information for features, set different styles and so forth. We need all this information from the Item. Originally we tried to use the OWS Context GeoJSON but this is not provided like STAC.

The use case we need is: Query STAC for some Items you are interested in, then get all Information to add data (as web services) to an interactive web map and e.g. use a Time Slider or some other User Inputs to interact with the map.

m-mohr commented 1 year ago

Not sure, could maybe also go in here as it seems like a valid use case, but I think it should start with what we do for the other service types and build on top of that.

Originally we tried to use the OWS Context GeoJSON but this is not provided like STAC.

Whatr do you mean with this?

boeckMt commented 1 year ago

Not sure, could maybe also go in here as it seems like a valid use case, but I think it should start with what we do for the other service types and build on top of that.

That would be fine from my side. So starting with the basics like wmts, XYZ and tilejson and then add more things to the shema?

I want to include links for Layers like WMS, Vector Tiles and WFS (KML, GeoJSON)

Originally we tried to use the OWS Context GeoJSON but this is not provided like STAC.

Whatr do you mean with this?

The OWS Context GeoJSON standard provides most of the things we need to specify Items from which we can create layers in our web clients, but as far as I know there are no interfaces/API to search and query these documents like with STAC. GeoServer e.g. has the The STAC extension so it is possible to provide Data (searchable) which is managed with GeoServer in STAC format. There is no such thing for OWS Context GeoJSON and STAC Items already provide a subset from the OWS Context GeoJSON so my intention was to include missing parts so we have all the data we need on one interface.

m-mohr commented 1 year ago

That would be fine from my side. So starting with the basics like wmts, XYZ and tilejson and then add more things to the shema?

I meant more that we always have a link such as https://github.com/stac-extensions/web-map-links/issues/8?notification_referrer_id=NT_kwDOAH4SFrI0NjQwNDU3NjY0OjgyNjIxNjY#issuecomment-1469774373 at the beginning for "simple" use cases and then build the more advanced use-cases on top.

I want to include links for Layers like WMS, Vector Tiles and WFS (KML, GeoJSON)

Sounds good.

The OWS Context GeoJSON standard provides most of the things we need to specify Items from which we can create layers in our web clients, but as far as I know there are no interfaces/API to search and query these documents like with STAC. GeoServer e.g. has the The STAC extension so it is possible to provide Data (searchable) which is managed with GeoServer in STAC format. There is no such thing for OWS Context GeoJSON and STAC Items already provide a subset from the OWS Context GeoJSON so my intention was to include missing parts so we have all the data we need on one interface.

Thanks. I'm wondering whether that can be merged somehow? Can we use this for advanced use cases on top of what I proposed above for simple use cases?

boeckMt commented 1 year ago

I meant more that we always have a link such as https://github.com/stac-extensions/web-map-links/issues/8 at the beginning for "simple" use cases and then build the more advanced use-cases on top.

I forked the repo and will make some examples, then we can discuss what makes sense and how to structure it.

Thanks. I'm wondering whether that can be merged somehow? Can we use this for advanced use cases on top of what I proposed above for simple use cases?

I do not know exactly, the OWS Context GeoJSON would duplicate some things which are already in STAC.

Basically there is the OWS Context which is similar to a STAC Collection (which groups multiple items). The Context inherits from GeoJSON FeatureCollection so it has all properties of it. In the features Array are OWS Resources (GeoJSON Features with special properties) which are similar to STAC Items. The Resources can have Offerings. This Offerings are different views for the resource, e.g. WMS, WFS and XYZ for world country borders. But the can also include things like WCS, GetCapabilities, GetFeatureInfo... The Offerings have an array of Operations also mentioned by https://github.com/stac-extensions/web-map-links/issues/8#issuecomment-1469579898 which have similar properties like a STAC Link.

There is a useful description in the OWS Context User Guide which describes the standard more in real world cases.

ycespb commented 1 year ago

@boeckMt , if you are looking for Earth Observation related use cases of OWS Context and offerings, then OGC17-003r2 defines a GeoJSON representation of an EO product/granule very similar to a STAC Item (a comparison can be found here) and it uses the OWS Context "offerings". Similarly, OGC17-084r1 defines a GeoJSON representation of an EO collection (equivalent to a STAC collection or ISO19139-2 "series"). Also that one uses "offerings". Both specs have a number of examples. The FedEO STAC endpoint gives access to additional examples of the above metadata formats as "STAC assets" (for collections and items).

boeckMt commented 1 year ago

@ycespb I couldn't find how the following

... a comparison can be found here ...

uses the OWS Context "offerings". Is this not only a Mapping from Earth Observation Class to STAC Item? I only see the use of links and some things of links for STAC assets.

STAC Property   OGC 17-003r2 Property
... ... ...
links [Link Object] $.properties.links
assets.*.updated string $.properties.availabilityTime (data)
assets.* (role="data") Asset Object $.properties.links.data
assets.* (role="thumbnail") Asset Object $.properties.links.previews
assets.* (role="metadata") Asset Object $.properties.links.alternates
... ... ...

So what is your proposal, completely reuse all things from Offering (Earth Observation) and Offering (OWS Context)?

I think then a new Extension would make more sense, where the STAC Item gets a property offerings. But that's a bit of duplication with links and assets then.

@m-mohr here are some examples https://github.com/stac-extensions/web-map-links/compare/main...boeckMt:web-map-links:issues-8 for Links of type Vector Tiles, WMS, WFS and Data (KML, GeoJSON...). What do you think about them could they be integrated?

ycespb commented 1 year ago

@boeckMt , indeed, the "walkthrough" focussed on what existed already in STAC and how the same thing could be done with the OGC specifications. What I propose is to encode offerings as STAC links with a number of properties which match what already is defined in OWS context (thus not reuse all, just this small part). I would not introduce a property offerings as links will do. I added the mapping in the walkthrough at the bottom and include it here as well.

So, someone knowing how an OGC 14-055r2 offering/operation would look like, can encode the same information (much simplified) as a STAC link as below. The values of both operation code and offering code remain the same as in OGC 14-055r2 and is the only remaining "dependency". The operation code is a bookmark added to the offering code and becomes the rel, e.g. http://www.opengis.net/spec/owc-geojson/1.0/req/wcs#GetCoverage.

STAC Property OGC 14-055r2 Property
TBD Offering Extension
$.links[*].rel string (uri) $..offerings[*].code
$.links[*].rel string $..offerings[*].operations[*].code
$.links[*].method string $..offerings[*].operations[*].method
$.links[*].type string $..offerings[*].operations[*].type
$.links[*].href string (uri) $..offerings[*].operations[*].href
boeckMt commented 1 year ago

@ycespb I don't really know what things are all allowed for link rel. The STAC spec says the the following should be used or this one or IANA Link Relation Types.

I also found these issues regarding rel Link

@m-mohr Can you tell more about that and what exactly is allowed?

E.g. the OWS Context GeoJSON describes the following offering codes

Operation codes are then

Code identifying the type of Operation... Typically the OGC Service request type, e.g. “GetCapabilities” or “GetMap”.

So e.g. there could be an item with the following links:

"links": [
   ...
  {
      "href": "https://maps.example.com/wmts?...",
      "rel": "TBD",
      "type": "image/jpeg",
      "title": "Web Map Tile Service with same data as in a wms"
    },
   {
      "href": "https://maps.example.com/wms?...",
      "rel": "TBD",
      "type": "image/jpeg",
      "title": "GetLegendGraphic so the user can have a legend for the wmts"
    },
   {
      "href": "https://maps.example.com/wfs?...",
      "rel": "TBD",
      "type": "application/json",
      "title": "GetFeature for the same data as in wms and wmts but the client can work with geometriess"
    },
    ...
]

Then the client could display wmts tiles and a legend for the tiles via wms and maybe use the geometry so the tile canvas can be clipped or intersected with other things.