GetMap with format=text/mapml returns <map-extent> with rel=features for vector data

[prushforth]

Background

The set of requirements surrounding GetMap in this document, taken together, will reconstitute the GeoServer MapML Extension as part of the standard WMS request/response protocol, so that MapML clients can interact with the richness of the OGC WMS implementation provided by the GeoServer geospatial CMS, while simultaneously benefiting from the (proposed) standardized client map and location semantics.

Requirement

Related to #50 and #48 , there should be a checkable option for "Use Features" (default un-checked) in the MapML Settings panel for a layer (not for layer groups) that changes the serialized <map-link rel="image" ...> to <map-link rel="features">, as described below.

For a raster data source, the "Use Features" option must be disabled / uncheckable. For vector data, the default should be unchecked, but it should be enabled and checkable if "Use Tiles" is unchecked.

When "Use Features" is checked for a layer based on a vector-capable data source, the response from GetMap for the layer should be a MapML document in which the <map-extent> contains a link URL template with rel="features" and in which the GetMap format_options parameter is set, as described below.

When a GetMap for multiple layers and styles happens, a question of how to handle differently set "Use Vectors" layers in the request layers list arises.

There are two proposed ways of representing individual layers in a multi-layer GetMap.

1. A multi-layer, multi-style GetMap MapML format response embodied by one <map-extent>
2. A multi-layer, multi-style GetMap MapML format response with one <map-extent> per layer

For 1. above, if there is a heterogeneity of "Use Features" states (some checked, some unchecked) among the different layers in the request, "Use Features" must be ignored for the request and a single link URL template emitted with rel="image":

<map-link rel="image" tref="https://example.org/geoserver/wms?request=GetMap&layers=a,b,c&format=image/png..."><map-link>

For 1. above, on the other hand, if all of the layers in the request have "Use Features" checked i.e., the set of requested layers has a homogeneous collection of "Use Features" (state = checked) among the different layers in the request, then the response link template, which would otherwise have a rel="image" value, will be serialized with a rel="features" and type="text/mapml" state and with a GetMap URL (template) whose format_options value is set to mapmlfeatures:true. See GetMap format_options MapML requirement

<map-link rel="features" type="text/mapml" tref="https://example.org/geoserver/wms?request=GetMap&layers=a,b,c&format=text/mapml&format_options=mapmlfeatures:true..."><map-link>

For 2. above, since each layer is serialized as its own <map-extent> with associated link URL template, those layers which have "Use Features" checked must be serialized with a link URL template <map-link rel="features" and type="text/mapml" ...> state, and a URL template whose format_options value is set to mapmlfeatures:true.

Maintain "Use Tiles"

In the current MapML extension, the "Use Tiles" checkbox governs how requests for the current layer is interpreted for the purpose of serializing a <map-extent>. Without vector support (which clearly continues to be the case for a raster data source, and ignoring for the moment the existing WFS MapML integration), "Use Tiles" is interpreted according to the what is possible for the layer or layer group, given the existence or not of a compatible tile cache, established in the "Tile Caching" tab interface.

The current logic is:

if ("Use Tiles") {
  if ("Tile Caching") {
    <map-link rel="tile" tref="...GetTile..."></map-link>
  else { /* tile-shaped GetMap request template */
    <map-link rel="tile" tref="...GetMap...">
  }
else { /* entire map view generated by "traditional" GetMap, which is good for e.g. labels */
  <map-link rel="image" tref="...GetMap..."></map-link>
}

if ("Queryable")
  if ("Use Tiles" && "Tile Caching") { /* generate WMTS GetFeatureInfo request template */
    <map-link rel="query" tref="...&service=WMTS&request=GetFeatureInfo..."></map-link>
  else { /* generate WMS GetFeatureInfo request template */
    <map-link rel="query" tref="...&service=WMS&request=GetFeatureInfo..."></map-link>
  }
}

In future, because of the possibility of serializing feature content directly with a GetMap request and because that feature content may ALSO be used to create vector tiles in "text/mapml" format, it will be necessary to significantly update this logic to reflect how the "Use Tiles" and "Use Features" settings will be processed together, should they both be selected, and given the fact that a layer or layer group can be one of many layers and/or layer groups present in a GetMap layers parameter list.