OGC Testbed-15: Quebec Model MapML Engineering Report

The integration of map definition and linking to separate data and styles with the OGC API was done at the level of the collection description resource. An attempt was made at providing a MapML representation of the collection resource. Instead of the default JSON representation, this representation is returned by specifying the f=mapml parameter when requesting the collection description (/collections/{collectionId}?f=mapml).

Due to the nature and purpose of the collection resource not corresponding directly with the concept of a MapML document this approach posed challenges as to exactly what could be featured within this MapML representation. On one hand, a MapML document is expected to contain a single reference to a particular dataset. On the other, an OGC API collection can be retrieved in different manners, such as tiles or as whole features (potentially together with an intersection or clipping bounding box).

Similarly, the same problem presents itself for linking to multiple encodings of the data, such as offering features or tiles as GeoJSON, MapML, GNOSIS Map Tiles and Mapbox Vector Tiles.

The collection description resource for the OGC API is typically not parameterized, as its purpose is only to describe the particular resource being offered. A MapML representation should therefore also avoid introducing parameters to alter the response of retrieving a collection description resource. This ensures the possibility of an OGC API simply directly serving data from a static file system structure. Instead, it would be best to make it possible for a higher-level geospatial content management system to reference a single generic MapML collection resource, while selecting specific capabilities.

In order for a MapML representation of the collection description resource to integrate well with the OGC API, it would be ideal if it could be harmonized as much as possible with its typical JSON equivalent. This harmonization would cover aspects such as:

It was noted that a client could consider the type attribute of a link to recognize and select the best supported encoding, and ignore alternate contents.

The MapML community would need to assess whether it is still possible and desirable to achieve this harmonization based on the current evolutionary stage of the MapML specification.

Alternatively, the OGC API integration could focus solely on the encoding, and a geospatial content management system could instead directly refer to the tiles or items being served by the OGC API, avoiding the integration challenges of the collection description resource altogether.

Because no consensus could be reached during the testbed, it was decided to only provide a link to the tiled data within the collection description (rel=tile). MapML is the encoding specified for those vector tiles, and marks the first attempt at using MapML to encode vector tiles or integrating vector tiles within a MapML document. The links to the features (rel=features) were still included in the document, but commented out. A link to the items was still included together with a bbox parameter for the purpose of querying (rel=query). Links to other supported encodings were also provided within the document, but commented out.

The testbed examined the question of providing links to styles applicable to a collection.

One viewpoint posited that an OGC API collection is strictly data, facilitating its presentation in different ways. Under this view, the collection description would remain neutral of the style, but could list the styles which the client could separately decide to apply (e.g., in a higher-level MapML document including or linking to this collection). A collection might have defined for it one or more styles. The collection description resource, which itself would be style-agnostic, would provide information about the availability of these styles. A style parameter could potentially be used within a style sheet link to name the different styles, and the higher-level document could pick a style, by also specifying a style parameter when defining a <layer>.

It was also noted that the specialized requirements of cartographic styling such as scale-dependent styles, complex expressions, etc. can be more complex than what Web CSS was intended to address. To address these more advanced needs, MapML-enabled clients could consider supporting Web-CSS inspired specifications such as CartoCSS, GeoCSS, and GNOSIS CMSS.

An alternative viewpoint was that HTML/MapML combines data and affordances, but does separate presentation (style) from content. Styles (CSS) are separated from (and linked to) the content. Under this view, a named style could be included in a parameter. A MapML client could interpret multiple style sheets linked from a single collection description as styles which should all be applied in cascade.

The question of selecting alternative styles for MapML was examined in Testbed-14, with findings presented in the Testbed-14 MapML Engineering Report. Since the styling aspect was not a core requirement for this component, a resolution was not pursued. It is recommended that these considerations be investigated in future work that takes into consideration the growing OGC API family of standards.

Sample code appears below as an illustration.

Some issues with the MapML encoding specification were encountered, reported and resolved during this initiative:

In order to facilitate re-combining tiled polygonal geometry and avoiding rendering a stroke at tile edges resulting from polygons that cross tile boundaries, a time-proven approach has been to mark the artificial segments introduced by the tiling. See Testbed 13 - Vector Tiles ER for a detailed discussion of the topic. Two opposite approaches were proposed and implemented for specifying those artificial segments in the MapML encoding.

Example direct paths to collections listing and description:

http://maps.ecere.com/geoapi/collections/ (List of all collections served)

http://maps.ecere.com/geoapi/collections/GRHQ (Québec hydrography network)

http://maps.ecere.com/geoapi/collections/GRHQ?f=mapml (MapML representation, listing commented out sub-collections)

http://maps.ecere.com/geoapi/collections/GRHQ/RH_S (hydrographic network surfaces)

http://maps.ecere.com/geoapi/collections/GRHQ/RH_S?f=mapml (MapML representation)

http://maps.ecere.com/geoapi/collections/NaturalEarth/cultural/ne_10m_admin_0_countries (Natural Earth Countries)

http://maps.ecere.com/geoapi/collections/NaturalEarth/cultural/ne_10m_admin_0_countries?f=mapml (as MapML)

http://maps.ecere.com/geoapi/collections/osm/ottawa/roads (Ottawa Roads from OpenStreetMap)

http://maps.ecere.com/geoapi/collections/osm/ottawa/roads?f=mapml (as MapML)

Example direct paths to vector features:

http://maps.ecere.com/geoapi/collections/GRHQ/RH_S/items (default GeoJSON encoding of the hydrographic network) http://maps.ecere.com/geoapi/collections/GRHQ/RH_S/items.mapml (MapML encoding of the hydrographic network)

The features end-point supports a number of parameters:

By specifying a zero-area box for the location (equal lower left and upper right coordinates, the intersecting bounding box has notably been found useful in a MapML client to query the feature properties:

http://maps.ecere.com/geoapi/collections/NaturalEarth/cultural/ne_10m_admin_0_countries/items?bbox=-75,45,-75,45

The geometry and only query specific attributes can also be omitted:

http://maps.ecere.com/geoapi/collections/NaturalEarth/cultural/ne_10m_admin_0_countries/items.mapml?bbox=-75,45,-75,45&properties=name,pop_est

On the other hand, the clipping bounding box is preferable for requesting only a portion of a high resolution very large single feature, such as a single polygon for the whole of Canada with highly detailed coastline.

The zoom level parameter offers a generalized version of the data without requiring the use of tiles.

The following parameters are supported:

Example direct paths to imagery:

http://maps.ecere.com/geoapi/collections/BMNG%202004/items (NASA Blue Marble Next Generation imagery mosaic)

The following parameters are supported:

Example direct paths to coverage (elevation data):

http://maps.ecere.com/geoapi/collections/SRTM_ViewFinderPanorama/items (SRTM ViewFinderPanorama elevation data)

Tiled data are available for either individual layers or as multi-layer Mapbox Vector Tiles for a group of vector collections.

The Tiles API supports the Tile Matrix Set extension to describe the tiling scheme.

Most of the tiling schemes supported are defined in the OGC Web Map Tile Service (WMTS) standard. The tiling schemes supported include:

The support for CRS84Quad2L0Tiles was added during the initiative to support the MapML needs, as currently only the EPSG:4326 tiling scheme is officially supported by MapML.

Example direct paths to tiles:

http://maps.ecere.com/geoapi/collections/

osm/ottawa/tiles/CRS84Quad2L0Tiles/14/4053/9493.mvt (multi-layer Mapbox Vector Tile, OSM Ottawa) GRHQ/RH_S/tiles/CRS84Quad2L0Tiles/6/16/37.mapml (hydrographic network surfaces tiled vectors, as MapML)

SRTM_ViewFinderPanorama/tiles/CRS84Quad2L0Tiles/6/16/37 (elevation data tile)

BMNG%202004/tiles/CRS84Quad2L0Tiles/6/16/37 (imagery tile)

The style sheets are available in GNOSIS CMSS, SLD/SE and Mapbox GL JSON styles. The server can either serve the different encodings (one or more) directly if available for each style, or generate the missing ones on-the-fly. This functionality is experimental as numerous challenges are posed by major differences in styling approach from one styling language and renderer to another. This workflow is being improved to produce better conversion results.

The association between the styles and the data layers is done by storing style sheets with the source data store itself, or through the concept of a stylable layer set. This is a unique resource identifier which both the layers and styles can be associated with. One or more stylable layer set can be specified within the styles and layers metadata.

Example direct paths to styles:

http://maps.ecere.com/geoapi/collections/

NaturalEarth/styles (list of all styles for Natural Earth)

NaturalEarth/styles/default (Default Natural Earth style, default CMSS encoding)

NaturalEarth/styles/default.sld (Default Natural Earth style, SLD/SE encoding)

NaturalEarth/styles/default.json (Default Natural Earth style, Mapbox GL encoding)

osm/styles (list of all styles for OpenStreetMap)

osm/styles/default (Default style for OpenStreetMap, default CMSS encoding)

osm/styles/default.sld (Default style for OpenStreetMap, SLD/SE encoding)

osm/styles/default.json (Default style for OpenStreetMap, Mapbox GL encoding)

An end-user interaction triggers a request to fetch a Collection from an OGC API - Features service endpoint. The WFS Client sends the request via Ajax to a local web server, which uses the Proxy Server to bypass the CORS restriction. (As described above, it is recommended that a longer-term approach should use CORS headers instead of a proxy.) The Collection information asynchronously returns the result to the WFS Client.

The WFS Client has a user interface for setting OGC API - Features parameters, such as selecting a collection, appending spatial and temporal constraints, setting zoom level or output format, and so on. The end-user can request features information by clicking the AddLayer button in the user interface. The WFS Client sends a request for acquiring item features, and the WFS Client receives a MapML document containing the desired item features.

Now the WFS Client has the desired MapML document containing multiple <feature> elements. The WFS Client component sends this MapML content to the Layers component for adding the layer into the map area. The Layers component parses the MapML text content to a MapML Document Object model by using the MapML Parser. The view of D106 is based on an OpenLayers map library, so the MapML Document Object is converted using the MapML OpenLayers Front-end. After conversion, the generated layer object is appended as a layer of the OpenLayers map view.

A raw MapML document is text content, and the MapML Parser converts the plain text of MapML documents to a MapML Document Object. Figure 18 shows how each statement in a MapML document becomes a part of a MapML Document Object. The <head> element becomes a head key, which is a top key of the object. The <extent> element becomes an extent key, which is a sibling of the head key. Each <feature> element becomes an element of a features array in a FeatureCollection type of geojson key. The parser packs all <feature> elements into a single FeatureCollection of a GeoJSON object.

Unlike the GeoJSON specification, the <properties> element of MapML is a free HTML format, so the parser converts it as a single property named "CDATA".

An alternative view was posited that the idea of MapML is to be compatible with the HTML parser, so that MapML becomes part of HTML (obviating any need to convert to JSON first). For now, MapML services can be relied upon to be mostly compatible with MicroXML rules, which enables use of the browser’s built-in XML parser. The HTML parser could also be used if its heuristics are known, enabling manipulation of the output DOM directly using browser-provided DOM APIs. Under this view, MapML is an HTML encoding of geospatial information, which is where the semantics of geospatial information are currently absent. MapML fills this need.

A MapML Document Object has an extent array and a GeoJSON object. In most cases, the item features served by OGC API - Features are described in the <feature> elements in the MapML response. Therefore, the most important part of the D106 deliverable as an OGC API - Features Client is converting from <feature> elements of MapML to a single GeoJSON object.

To become a MapML viewer beyond being simply an OGC API - Features client, the D106 component had to support <extent> elements as describing how a layer of map area is retrieved. Each <link> in the <extent> element can describe raster or vector layers, and each of them will become an (internal) layer. Figure 19 shows not only how a GeoJSON object becomes a vector layer in OpenLayers, and also how each <link> in an extent will become a proper layer in OpenLayers in its own right.

The name OlMapML is a Node.js package name that supports APIs for getting a layers array of OpenLayers. The following example shows how to use the OlMapML Node.js package.

Figure 20 shows the top-level screen view on a modern web browser.

There are six sections in the main view. Two Client (WPS, WFS) sections and one Layers section are in the left area, one console section is in the bottom area, one toolbar section is in the top right side, and one map view section is in center area.

Figure 21 shows how to add a new OGC API - Features service endpoint.

Figure 22 shows an OGC API - Features item parameter setting dialog box for fetching feature items.

Figure 23 shows that vector features described in a MapML document display on the map area as a vector layer. An end-user can select any feature in the map area, and its property information is shown in a dialog box.

Although the Quebec model MapML Client D016 deliverable design was based on using vector features described in a MapML document, MapML has potential benefits as a metadata document in describing an OGC API - Features implementation and a selection of features from a data source. The following are advantages of MapML as a service or client implementation of the OGC API - Features - Part 1: Core standard.