GetMap with format=text/mapml AND format_options=mapmlfeatures:true returns styled vector MapML content

[prushforth]

Background

The WFS GetFeature operation can return vector geospatial data in a wide variety of formats. This operation is suitable for simple use cases in which the scale of the features is fixed for use in simple data processing scenarios. GetFeature in GeoServer WFS already has the ability to serve MapML documents.

On the other hand, styled and scale-appropriate vector information cannot be obtained from WFS; for this reason the WMS GetMap operation is useful for obtaining underlying vector information that can be styled by the client, potentially reducing the processing burden on the server while providing the separation of concerns that good data management requires. Further, the GetMap operation is scale-specific, allowing not only scale-dependent styling of features, but even different geometric representations of features at different scales e.g. looking at Paris on a very small scale map, it could reasonably be represented by a point marker, while looking at the same location on a large scale map might stop representing "Paris" as such and replace that representation with street-level information.

GeoServer WMS has the ability to represent geospatial data in a scale-appropriate way, by applying symbology encoding scale-dependent rules via Styled Layer Descriptor documents. Sophisticated symbology rules enable the server to process and to even render different layer data at different scales when requested via GetMap. Typically this results in the rendering of a map image on the server side which is returned to the client via HTTP response as an image encoding of the map. Processing (including clipping, buffering and so on) and styling (applying symbology encoding rules to control rendering) of vector information is fundamental to the map creation process. An example of vector output of this processing is currently given by the ability of GeoServer to render maps in the SVG vector image format that are clipped to the bounding box of the request an decorated with CSS style rules that are derived from the applicable SLD/SE.

Requirement

This requirement enables GeoServer to respond to GetMap requests for text/mapml document representations of layers with CSS-styled MapML response documents containing appropriate-scale vector feature data.

mapmlfeatures: true | false

See format_options for GeoServer.

A suggested mechanism to distinguish what MapML content is expected for the text/mapml format GetMap response is to enable a format_options parameter value applicable to the text/mapml format when it is requested via GetMap. The state of this parameter value could indicate (a preference for) how a (vector-capable) layer is expected to be represented in the text/mapml MapML document body generated by GeoServer: either as a <map-extent> hypermedia control (mapmlfeatures:false / not present) that itself contains a URL template (in a <map-link tref> element attribute) to a GetMap that returns features (the generated URL template would contain mapmlfeatures:true), or as one or more <map-feature> elements (which would presumably be the response to the aforementioned GetMap that returns features).

This GetMap requirement is to recognize a text/mapml-specific, boolean format_options value named (subject to discussion) mapmlfeatures. Legal values: true and false. Default value (when not present) is false. When the user selects "Use Features" from the layer configuration GUI, a <map-extent> containing a URL template is created in a response to a GetMap for a text/mapml MapML document (with no / false format_options=mapmlfeatures:___ parameter value), the format_options parameter will be set in the URL template with the true value.

The logic to implement this requirement should take into account what is a "reasonable" serialization for the layer or layer group given the nature of the GetMap request and the "Use Features" and "Use Tiles" settings. If the request is for multiple layers, with associated named styles, it may be necessary to override or ignore the layer or layer group "Use Features" and "Use Tiles" settings so that the resulting map image or MapML document is coherent and useful. The detailed implementation logic will be developed and refined in the context of the other GetMap-related requirements.

GetMap response snippet for (single) layer with format=text/mapml with "Use Features" checked (note format_options):

...
    <map-extent units="OSMTILE">
      ...
      <map-link rel="features" tref="http://example.org/mapserver/wms?request=GetMap&amp;format=text/mapml&amp;format_options="mapmlfeatures:true" />
     ...
    </map-extent>

GetMap response snippet for (single) layer response from the above GetMap URL template:

<mapml- xmlns="http://www.w3.org/1999/xhtml">
  <map-head>...</map-head>
  <map-body>
        <map-feature id="restaurant_polygon.20" class="restaurant_polygon">
          <map-featurecaption>The Prescott</map-featurecaption>
            <map-geometry>
              <map-point>
                  <map-coordinates>-75.7093517 45.4005727</map-coordinates>
              </map-point>
            </map-geometry>
            <map-properties>
                  ....
            </map-properties>
          </map-feature>
         ...
  </map-body>
</mapml->

mapmltile: true | false

If the layer is associated to a style, either by default or by an associated named style in the styles parameter list of style names, the <map-feature> elements' descendants must be attributed with classes which have CSS style rules based on the associated named style. If the format_options mapmltile value is not present in the request or is set to false (the default), a <map-style> element must be embedded in the the root <mapml-><map-head> element and contain the CSS style rules of the associated named style. When generating MapML vector tiles (for caching, or dynamically), it is not desirable to generate a <map-style> element in each tile's MapML document.

Where the GetMap request lists multiple layers, with every layer in the request having "Use Features" enabled, the vector content and associated styles should be appended/merged into a single well-formed MapML response document, following the same order in which layers are listed in the request layers parameter.

The returned vector data must be clipped to the supplied bbox, per GetMap semantics (clip behaviour can be seen with SVG response vector format).