Rendering a map using a custom style, or using a process execution document with standardized inputs

[jerstlouis]

In #40 (comment) we discussed the capability to POST a custom SLD/SE style to /map, and be able to get either a map back right away, or a URL to which you could still add parameters for a specific format, bbox, width and height.

Other than the media type being SLD/SE, this capability is actually identical to functionality we are implementing in our Modular OGC API Workflows (MOAW) project, where we POST a process execution schema (instead of a style) to a RenderMap process (which you could picture as powering the OGC API - Maps capability).

I would suggest this be a separate extension/part, OGC API - Maps - Part 4: Custom maps. It would have optional conformance classes for advanced capabilities. Not for everyone ;)
It could work with both /processes/RenderMap and /map, or alternatively only for /processes/RenderMap (but Maps - Part 4 would standardize the inputs and result of such a RenderMap process).

Three flavors:

• POST your style or execution document to /map with all query parameters, get your map image back right away
• POST your style or execution document to /map?mode=deferred to get back a number of ways how you can query different AOIs/resolution (e.g. BBOX+width+height, tilesets...).
• POST your style or execution document to /map/tiles/{tileMatrixSetId} to get back an OGC API - Tiles tileset right away

The server would advertise what media types are valid to POST to it, e.g. SLD/SE, MapboxGL style, GNOSIS CMSS style, or process execution document...

You can accept a POST directly to /map without conflicting with GET which returns some metadata about styles available etc. And you could even optionally POST to /map without a payload to return the default map.

To render a very large print-quality map which will be gigabytes in size, an asynchronous mode may also make sense with ?mode=async and e.g. an e-mail address to let you know when it's ready (following OGC API - Processes asynchronous mechanics).

Practical examples:

Immediate mode

POST my SLD/SE to http://maps.ecere.com/ogcapi/datasets/vtp:daraa/map?f=png&width=1024&height=1024&bbox=35.898213,32.4633913,36.5614696,32.8370158

returns me a PNG map right away based on that style and its layers (already existing on that API).

Deferred mode
POSTing the same thing to http://maps.ecere.com/ogcapi/datasets/vtp:daraa/map?mode=deferred returns me:

{
   "links" : [
      {
         "rel" : "ogc:common:bbox-resolution-data",
         "href" : "http://maps.ecere.com/ogcapi/deferred/ABCD1234",
      },
   ],
   "tilesets" : [
      {
         "dataType" : "image",
         "tileMatrixSet" : "http://maps.ecere.com/ogcapi/tileMatrixSets/WebMercatorQuad",
         "links" : [
            {
               "rel" : "ogc:tiles:tileset",
               "type" : "application/json",
               "href" : "http://maps.ecere.com/ogcapi/deferred/ABCD1234/tiles/WebMercatorQuad"
            },
            {
               "rel" : "ogc:tiles:tileset",
               "type" : "application/json+tilejson",
               "href" : "http://maps.ecere.com/ogcapi/deferred/ABCD1234/tiles/WebMercatorQuad?f=tilejson"
            }
         ]
      }
   ]
}

NOTES:

• The /deferred URLs are completely arbitrary...
• You can add f (or use Accept-content header), bbox, width & height query parameters to the bbox-resolution-data deferred URL.
• See this OGC API - Tiles comment tilesets resource only contains links to tileset resources. May we remove the thing completely? ogcapi-tiles#43 (comment) about that new suggested approach to list tilesets, and the new suggested default JSON response for requesting a tileset

Deferred, tiled, "I know what TMS I want" mode
You could also potentially support POSTing to http://maps.ecere.com/ogcapi/datasets/vtp:daraa/map/tiles/WebMercatorQuad to directly receive the tileset (same result as following that deferred request with a GET to http://maps.ecere.com/ogcapi/deferred/ABCD1234/tiles/WebMercatorQuad).

Process execution document example
Now an example with a process execution document, instead of a style...
WARNING! Now we're talking about very advanced and powerful capabilities, acknowledging that rendering a map is a process...
Not for the faint of heart ;)

Now I can POST this directly to the http://maps.ecere.com/ogcapi/map* or /processes/RenderMap* end-points, at the top-level service API level (outside of any dataset), because the execution document explicitly references datasets collections.

{
   "inputs" : [
      {
         "id" : "layers",
         "list" : [
            { "collection" : "http://maps.ecere.com/ogcapi/datasets/vtp-Daraa2/collections/AgricultureSrf" },
            { "collection" : "http://maps.ecere.com/ogcapi/datasets/vtp-Daraa2/collections/SettlementSrf" },
            {
               "collection" : "http://maps.ecere.com/ogcapi/datasets/vtp-Daraa2/collections/TransportationGroundCrv",
               "useWith" : { "style" : "http://maps.ecere.com/ogcapi/datasets/vtp-Daraa2/styles/overlay" }
            },
         ]
      },
      {
         "id" : " style",
         "value" : "http://maps.ecere.com/ogcapi/datasets/vtp-Daraa2/styles/night"
      }
   ]
}

NOTE: The omitted id for each collection input inside the layers list would default to the {collectionID}, so that we have the option not to have to explicitly supply it separately.

And this would return you the same types of resources as with the styles scenarios, depending on which flavor of the map resource you POST to (i.e. a map image in immediate mode, links and tilesets for deferred mode, and a tileset in deferred/one TMS mode).

/processes/RenderMap would only differ in that a GET on that resource returns you the process description, whereas a GET on the /map resource returns you availables styles etc., but in that case the process execution is standardized (e.g. it expects layers and style inputs).

In our MOAW project, those collection inputs could actually be complex nested workflows specified directly as a nested object, which may involve multiple data sources and computing resources, which when using the deferred mode are all executed in a parallel manners and only for the visualization Area of Interest, e.g. using BBOX, Tiles or DGGS (extensions we are proposing to OGC API - Processes).

[jerstlouis]

I propose the following conformance classes for OGC API - Maps - Part 4: Custom maps:

• Maps-Custom -- Support for POSTing something to define a custom map
• CustomMap-SLDSE -- Support for POSTing SLD/SE style
• CustomMap-Processing -- Support for POSTing process execution document
• CustomMap-External -- External collections (as opposed to only those on servers)

And some related conformance classes for Processing which would describe the available processing capabilities (would need to compare this with what Processing currently defines):

• Processing-Core -- Processing capabilities
• Processing-Sync -- Synchronous processing
• Processing-Async -- Asynchronous processing

With CustomMap-Processing, but without Processing-Core, the service only supports the specialized maps rendering process, without generic support for processes (e.g. no support for querying available processes, or what the inputs of the process /processes/RenderMap should be).

Capabilities defined in Modular OGC API Workflows approach:

• Processing-Nested -- Support for nested processes in execution document
• Processing-Deferred -- Support for deferred approach (passing AOI+resolution or asking for tiles later)
• Processing-Tiled -- Support for deferred tilesets approach (including directly asking for a specific TMS)

With CustomMap-Processing, but without Processing-Nested, custom maps could be rendered from submitting process execution document, but it could only reference collections, not processes.

[ghobona]

Discussed during the 2020-07 Sprint. It should be possible for an implementation of OGC API - Maps to pull styles from an implementation of OGC API - Styles.