OGC Testbed-15: Open Portrayal Framework Engineering Report

All questions regarding this document should be directed to the editor or the contributors:

Contacts

Attention is drawn to the possibility that some of the elements of this document may be the subject of patent rights. The Open Geospatial Consortium shall not be held responsible for identifying any or all such patent rights.

Recipients of this document are requested to submit, with their comments, notification of any relevant patent claims or other intellectual property rights of which they may be aware that might be infringed by any implementation of the standard set forth in this document, and to provide supporting documentation.

The following paragraphs show the various implementations that have been created by participants in Technology Integration Experiments (TIEs) conducted in Testbed-15 and provide additional information.

Step 1 The user discovers API endpoints that provide vector, raster, or tiled vector or tiled raster data, maps, or coverages. The user loads the data and finds references to corresponding styles to render the data correctly (or retrieves pre-rendered tiles that apply the stylesheets).

Step 2 The references to the applicable styles point to a server that provides access to the styles via the Styles API. The user loads the style and applies the stylesheet to the data. Not happy with the result, the user decides to modify the style.

Three clients have been produced in Testbed-15 that interact with the various service endpoints as illustrated below.

Step 3 A user can modify any style using a Visual Style Editor. These tools allow modifying styles and ideally transform styles from one media type to another (e.g. from OGC SLD to Mapbox Style or vice versa).

Two Visual Style Editors were implemented in Testbed-15. Both are described and illustrated in Annex A: OPF Implementations and illustrated in the videos listed in the section Videos and Outreach Material. Both editors are capable of retrieving a style from a style server, updating the style locally, and re-distributing the style by uploading it to the style server.

Step 4 Once the stylesheet has been adapted to the user’s needs, the user may decide to make the modified style available via the Style API. The Style API provides transactional capabilities for that purpose.

Step 5 In Step 5, another User-2 discovers the same data as User-1. The references in the data to the applicable styles have not changed, since the data server is not aware of any modifications to styles. User-2 retrieves the data via the various API endpoints (API Maps or Tiles) similar to User-1.

Step 6 User-2 discovers references to the applicable styles and loads these similar to User-1 before. Except, that the loaded stylesheets now also contain the styling instructions which User-1 defined before, using the Visual Style Editor.

Step 7 & 8 Other users or systems make new satellite imagery available to an image archive. This process triggers the re-building of individual tiles as served by tile service endpoints.

The steps involve an implementation of the new OGC API - Images draft specification that allows uploading images to an image archive. The API basically functions like a catalog API and is further described in the section API Images. Three implementations of this API have been developed in the Testbed-15 activities.

Step 9 User-1 needs to have the latest data for a given region. To avoid loading the entire data set again, User-1 requests all changed data since the last checkpoint (here: since the last request). Because new imagery data is now available, the data server provides a set of updated tiles.

The step makes use of the draft OGC API - Change Set specification as documented in the section API Changesets.

Step 10 & 11 The Open Portrayal Framework is envisioned to provide full support for online/offline mixed environments. For the offline situation, GeoPackages are used as a data container that supports a draft extension for styles and symbols. The necessary extensions are described in the section GeoPackage.

GeoPackage builders ideally load all data using the same API endpoints as the users before.

The Styles API is a Web API that enables map servers and clients as well as visual style editors to manage and fetch styles. This draft API is documented in OGC Testbed-15: Styles API Engineering Report (OGC 19-010). The Styles API is consistent with the emerging OGC API family of standards. The Styles API implements the draft conceptual model for style encodings and style metadata as documented in the OGC Testbed-15: Concept Model for Style Encoding & Metadata Model Engineering Report (OGC 19-023). The draft conceptual model provides information for understanding styles intended usage, availability, compatibility with existing layers, as well as supporting style search. The conceptual model defines three main concepts:

The conceptual model was developed taking into account the knowledge gained in the draft OGC Symbology Conceptual Model: Core part and the Vector Tiles Pilot (VTP) activities. The VTP, conducted just before Testbed-15 started, produced a first prototype of a Styles API independent of the style encoding

Testbed-15 developed the Styles API to allow management, sharing, and usage of styles independently from concrete API endpoints. With the new API, datasets that are shared by other Web APIs implementing the OGC API - Features - Part 1: Core standard or the draft OGC API - Coverages or draft OGC API - Tiles specifications can reference applicable styles served by dedicated Style Web API endpoints.

The Styles Web API proof-of-concept supports full CRUD (create, read, update, delete) and thus features reusability of styles in an unprecedented way. In combination with Visual Style Editors, commonly used styles can be adapted, transformed from one serialization format to another (Testbed-15 experimented with OGC SLD/SE, MapBox GL, CSS, and CNOSIS internal style format) and shared again after modification.

Web APIs implementing the draft OGC API - Maps specification fetch styles and render spatial data (features or coverages) on the server. Map clients fetch styles and render spatial data (features or coverages) on the client.

In order to support styles, data APIs (for example, supporting the OGC API-Features standard and/or the draft OGC API Tiles) require additional capabilities, too. These are:

The Styles API specification uses OpenAPI 3.0 to specify the building blocks of the API.

The OGC Web Map Tile Service (WMTS) implementation standard provides a standard based solution to serve digital maps using predefined image tiles. The standard builds on the Capabilities model, which is common to all OGC Web Service standards from the Key-Value-Pair (KVP) and Simple Object Access Protocol (SOAP) era, to advertise the tiles the service has available through a standardized declaration in the ServiceMetadata (aka Capabilities) document. This declaration defines the tiles available in each layer (i.e. each type of content), in each graphical representation style, in each format, in each coordinate reference system, at each scale, and over each geographic fragment of the total covered area. The ServiceMetadata document also declares the communication protocols and encodings through which clients can interact with the server. Clients can interpret the ServiceMetadata document to request specific tiles.

The new version of WMTS should be better aligned with the emerging OGC API family of standards. These APIs

This new family of (emerging) standards reflects the design change from existing Web service standards (W*S) towards Web APIs in order to serve geospatial data more natively on the Web. The Web API OGC API - Maps and Tiles draft specifications were further developed in Testbed-15 in response to these design changes.

As documented in the beginning of this chapter, Testbed-15 participants developed a series of APIs to cover functionality offered by a revised, transactional WMTS. The draft Maps and Tiles APIs, documented in detail in OGC document 19-069 adopt an approach similar to that of the OGC API - Features - Part 1: Core standard. The OGC API - Tiles draft specification describes a service that retrieves data representations as tiles. Tiles are organized into Tile Matrix Sets consisting of regular tile matrices available at different scales or resolutions. The OGC API – Tiles draft specification is described as a building block that can be plugged into an OGC API - Features service to retrieve tiled feature data (sometimes called vector tiles or tiled vector data) or to an OGC API – Maps implementation to retrieve rendered tiles (sometimes called map tiles). Thus, depending on the source data and the behavior of the corresponding service, a client may receive tiled vector data (e.g. as Mapbox, GeoJSON, etc.), or raster data (e.g. TIFF, NetCDF, etc.). In the future, tiles could even support multiple data formats in a single tile container, i.e. raster data and vector data in a single tile. The same concept is applicable to layers. A tile container could contain multiple layers (that can be of different types as well).

The maps part of the draft OGC API - Maps and Tiles specification describes an API that presents some data as maps by applying a style. These maps can be retrieved as tiles (if OGC API - Tiles is also adopted by the implementation) or as maps of any size generated on the fly.

The requirement for a Web API to handle new imagery came up in the context of updated tile caches. Basically, a new image becomes available and needs to be added to an image archive. The provisioning of that image then triggers the re-generation of tiles in an adjacent tile store for the area affected by the new image (or even the entire area, depending on tiling concepts and methodologies). So far, a direct connection between the image archive and the tile store is assumed. In a future initiative, this connection can be further analyzed and further decoupled. The Images API is described in full detail in OGC Testbed-15:Images and ChangesSet API Draft Specification Engineering Report (OGC 19-070).

The initial discussion focused on an image specific solution. However, it quickly became clear that the image archive case is nothing more than an asset catalog. An image catalog has just one main difference to most other catalogs: An image catalogue stores the images themselves and not just references, as most other catalogs do. This resulted in the Spatial Temporal Asset Catalog (STAC) being considered for use in the Testbed.

STAC is a Web API-enabled generic catalog solutions for spatio-temporal assets. "The Spatio Temporal Asset Catalog (STAC) specification aims to standardize the way geospatial assets are exposed online and queried. A 'spatiotemporal asset' is any file that represents information about the earth captured in a certain space and time. The initial focus is primarily on remotely-sensed imagery (from satellites, but also planes, drones, balloons, etc), but the core is designed to be extensible to SAR (Synthetic Aperture Radar), full motion video, point clouds, hyperspectral, LiDAR (Light Detection and Ranging) and derived data like NDVI (Normalized Difference Vegetation Index), Digital Elevation Models, mosaics, etc." (STAC).

The Changeset building block describes a mechanism for partial data updates to maintain synchronization between a server and a client cache that could be applied to any data service. Each retrieval of data from the server has associated a checkpoint identifier that is used in further communications. The Testbed-15 Open Portrayal Framework thread concentrated on updates to imagery stores. The filter mechanisms use checkpoint identifiers to constrain the response to tiles updated for a given target area since a provided checkpoint.

This work on changesets is closely related to the work on Delta Updates as performed in the Testbed-15 "Delta Updates" thread. In that thread, the goal was to develop a general solution to reduce the volume of transferred feature data in Denied, Degraded, Intermittent and Limited (DDIL) Bandwidth environments. Delta Updates explored how servers can decide to further reduce the amount of update data by leveraging classification schemes. Depending on the applied classification schema, the server may only send top priority updates in DDIL conditions and further lower priority updates, once conditions improve. The OGC Testbed-15: Delta Updates Engineering Report describes the delta updates solution and describes how prioritized delta updates can be served using a transactional extension for the OGC API – Features and the WPS standard/OGC API – Processes in front of WFS instances.

Within the OPF thread, the participants decided to keep the classification scheme available, since this approach might prove beneficial in future work. For Testbed-15, all tiles have been part of the same class, i.e. the schema has been ignored at implementation stage.

The Changeset API is described in full detail in OGC Testbed-15:Images and ChangesSet API Draft Specification Engineering Report.

The Open Geospatial Consortium (OGC) GeoPackage Encoding Standard was developed for the purpose of providing an open, standards-based, platform-independent, portable, self-describing, compact format for transferring geospatial information. GeoPackage has proven to be an effective "container" mechanism for bundling and sharing geospatial data for a variety of operational use cases. However, GeoPackage stakeholders have observed persistent interoperability issues, particularly with regards to metadata, extensions, and portrayal.

While OGC 19-047 discusses a series of enhancements, this chapter focuses on enhancements directly relevant for portrayal, including enhancements to deal with change sets that are part of the Testbed-15 Open Portrayal Framework scenario.

Section 6.1.2 of OGC 19-047 introduces a concept for building metadata profiles. Metadata profiles are an optional agreement on how metadata is to be used in a GeoPackage to meet a particular purpose. Through the GeoPackage extension mechanism, a community of interest may define one or more metadata profiles that specify the encoding, scope, and purpose of a particular type of metadata. Without this mechanism, a GeoPackage client would be forced to inspect all metadata content to respect an out-of-band (non-machine-encoded) agreement to determine how metadata is being used in that file.

The GeoPackage Style Metadata Profile satisfies the need for metadata for styles. The second profile introduces data governance aspects to GeoPackages. The GeoPackage Delta Update Profile allows tracking local updates to a GeoPackage, so that they can be applied to another repository. GeoPackage is a single-user database with no built-in security, so any management of updates beyond version and checksum will rely on the trustworthiness of software and users. With that understanding, the GeoPackage Metadata Extension supports the elements needed to track updates made locally. Please note: The name Delta Update was used in early stages of Testbed-15 development and was only superseded by Change Set towards the end of the initiative.

An important GeoPackage mechanism produced during Testbed-15 was Semantic Annotations. This activity addressed interoperability issues caused by lack of formal semantics in data descriptions. There is an unbounded set of ancillary information that may be operationally relevant to GeoPackage users. Members of the GeoPackage community have periodically proposed adding additional columns to existing GeoPackage tables to address one-off operational needs. This approach does not scale, and adding additional columns to existing tables introduces interoperability risks and does not necessarily meet operational needs due to unclear semantics.

The proposed Semantic Annotations extension allows such information to be placed on any GeoPackage business objects. The schema for a Semantic Annotation is straight-forward, including resolvable URIs and types along with a human-readable name and description. Semantic Annotations are linked to business objects via the Related Tables Extension. Section 6.3.1 explains how the mechanism can be applied to link layers to styles, which is essential to identify appropriate styling rules, symbols, and fonts for data layers. Since the styles that will work for a particular layer are independent of the data (and may be produced by one or more completely different organizations), a loose coupling between layers and styles is preferred. By annotating layers (either conventional or tiled vector data) with known valid styles, a GeoPackage client may provide a user a reasonable set of style options to choose from. Whether the styles are stored directly in the GeoPackage or are accessible through a separate style service, the client will be able to retrieve the styles and apply them to the data in the layer.

The following figure illustrates the Semantic Annotation concept. Based on GeoPackage’s Related Tables Extension, the data content and its organization in a layer is linked to the stylesheets by leveraging the Semantic Annotation concept.

The same approach can be applied to Stylable Layer Sets. The stylable layer set concept was introduced to group multiple styles that apply to the same data set or schema. For example, a stylable layer set could apply to a theater of operations and could group a set of styles (e.g., "topographic", "satellite overlay", and "night"). The original proposal called for a column to be added to a pair of tables, but the semantic annotation approach would be more flexible and could be applied to both conventional and tiled vector layers. In this latter case, both the layers and the styles could be annotated with one or more stylable layer sets.

A third practical example for Semantic Annotation is Layer-to-Layer Linking. When a GeoPackage contains a relatively large volume of vector data (either in conventional feature or tiled vector layers), a recommended practice is to pre-render raster tiles that cover a large geographic area. This reduces the need to render extreme numbers of features at run-time. In scenarios where a full OWS Context document is considered to be over-kill for the scenario, a simple semantic annotation can be used to link vector and raster layers that represent the same underlying data.

The longterm goal of the Open Portrayal Framework is to realize smooth online/offline experiences when dealing with high quality maps based on heterogeneous source data. Pre-rendered and raw vector- and raster data needs to be visualized using externally provided and governed styles. Updates in image archives causing re-generation of tile sets are made transferrable to tile caches using tile change-sets in both, online and offline scenarios. These requirements lead to the aforementioned extensions and Semantic Annotation concepts and have been implemented as documented below. In principle, three major challenges had to be addressed:

The following section provides an overview of the various participant implementations. The overview is complemented with important lessons learned during implementation and technical interoperability testing exercises. The following figure provides an overview of Testbed-15 Open Portrayal Framework GeoPackage components.

Image Matters has developed a GeoPackage Provisioner that receives a JSON-formatted REST request and creates and populates a GeoPackage to meet that request. The Provisioner was originally written to support tile formats such as WMTS, but has been extended to support tiled vector data. The Provisioner supports other GeoPackage extensions in certain cases, but these are not currently handled in the case of vector tiles. Currently, the provisioner supports only the Coordinate Reference Systems (CRS) EPSG:3857 (Web Mercator) and EPSG:4326 (WGS84).

For example, a request could specify a CRS, a bounding box, a service, a layer, and a list of included zoom levels, and the provisioner would fetch all tiles with those specifications that fit within the bounding box, and put them into a GPKG. Optimistically, styling information is also gathered and included, according to the Style extension.

The Testbed-15 scenario required the usage of specific background color: gray. Whereas the MapBox styles technology allows setting background color values, OGC SLD does not. Testbed-15 developed a proposal as to how a background-color parameter should go in an SLD document and how this approach should work. After some discussions, the following solution emerged:

The SLD <UserStyle> element should be augmented to include an optional <BackgroundColor> element, whose value is a hexadecimal RGB color value. Colors in SLD and SE are expressed in the #RRGGBB form. The default value of this element should be "#FFFFFF" (white). This element declares the preferred background color of the style. Change request #620 was submitted against the Styled Layer Descriptor Profile of the Web Map Service Implementation Specification version 1.1.0 (OGC 05-078r4) to add this element.

Further discussion focused on whether the BackgroundColor could also be sensibly placed inside StyledLayerDescriptor for styles that have a list of NamedLayer/UserStyle (which is possible, and GeoServer’s preferred way of handling multi-layer styles, even outside the confines of tiled vector data). At the end, the idea was discarded because the preferred background color is as style-specific as the foreground colors and line thicknesses, etc.

If a tile is requested in a format that does not support transparency (such as JPEG), or if the request is made with TRANSPARENT=FALSE, the server should return the tile with a solid background of the color specified by the <BackgroundColor> element of the style. Change request #621 was submitted against the Web Map Tile Service Implementation Standard version 1.0.0 (OGC 07-057r7) to add this optional TRANSPARENT parameter.

If tiles are cached in an opaque format such as JPEG, clients cannot expect that the server changes the background color on the fly. A server could still conceivably cache PNG and return JPEG, but not all users will want to do this. Still, any server should not be expected to handle the "transparent" parameter (or any query parameter for that matter). A client application can always add parameters to a request, if the client desires the behaviors the parameters are intended to invoke. Services that don’t support or recognize these additional parameters will simply ignore them.

When a client application that is aware of this new mechanism is displaying a map and the bottom-most layer is a WMTS-tile layer, the client should request the tiles of that layer with TRANSPARENT=FALSE (or as a JPEG). This allows the map to be displayed with the background color that is appropriate for the selected style, without the client application having to know anything about the style (other than its ID). This can be done even for WMTS servers that do not declare this profile. This is because earlier WMTS servers will simply ignore the TRANSPARENT parameter and return transparent tiles, which will be displayed on the (presumably white) background of the client application, as it is currently done.

Even if the tile is returned with a transparent background (which is the normal case), the server should - if possible - endeavor to have the background be a fully transparent version of the color specified by the <Background> element of the style. This allows client applications to infer this information out of its cached tiles, if the client decides at a later time to provide an appropriate background color for them.

When a client application that is aware of this proposed mechanism is requesting tiled data and rendering the map, it will presumably have retrieved the style definition by making a GetStyle(s) request. From this, the client will be able to determine the correct background color by looking up the style’s <Background> element in the SLD. Then, the client can simply set the canvas to that background color.

This mechanism alleviates the need for a WMTS server to accept an arbitrary background color in a GetTile request, increasing cache use. The WMTS server could still potentially pre-render all tiles: pre-render a transparent and an opaque version of each.

As an example, the "Night" style in a previous initiative required a blue background. This information was communicated by the MapBox style definitions, but not the SLD style definitions. As a result, any SLD-based client application showing this style

However, with the extension suggested above, the SLD encoding of the "Night" style could include this information as shown in the following example. This example assumes that a separate WMTS Layer is provided for each feature set:

or like this (if a single WMTS Layer contains all feature sets):

The following demo provided by CubeWerx demonstrates the concepts described above. Note that some links may not work any longer at the time of reading, but the URL structure and corresponding figures should still provide valuable information.

Look at the SLD at this link or in this annex.

Notice that the "Topographic" style has a <sld:BackgroundColor>#CCCCCC</sld:BackgroundColor> element (look, gray!) and the "Night" style has a <sld:BackgroundColor>#1E193E</sld:BackgroundColor> element. This specifies the preferred background color for these styles. The "Overlay" style does not have a BackgroundColor element, so the preferred background color defaults to white.

Make a tile request to https://tb15.cubewerx.com/cubewerx/cubeserv/op/wmts/1.0.0/tiles/Daraa_vectors/Topographic/smerc/14/6621/9838.png. Notice that the standard tile still has a transparent background.

If one executes the following endpoint https://tb15.cubewerx.com/cubewerx/cubeserv/op/wmts/1.0.0/tiles/Daraa_vectors/Topographic/smerc/14/6621/9838.png?transparent=false. the client will display an opaque tile, where the background color is not the default white, but the color specified by the BackgroundColor element in the style! If a client application always requests the bottommost layer with transparent=false, the client will automatically get the background color that is the most appropriate for that layer.

The application can also accomplish this same capability by specifying a format that does not support transparency. Try https://tb15.cubewerx.com/cubewerx/cubeserv/op/wmts/1.0.0/tiles/Daraa_vectors/Topographic/smerc/14/6621/9838.jpg.

As an experimental extension (not proposed as part of the API Tile specification), the Cubewerx tile requests also accept a BackgroundColor parameter that can be used to specify an arbitrary background color. Executing the following endpoint service https://tb15.cubewerx.com/cubewerx/cubeserv/op/wmts/1.0.0/tiles/Daraa_vectors/Topographic/smerc/14/6621/9838.jpg?BackgroundColor=red allows various color syntaxes to be accepted.

This mechanism is also supported by our WMS. By default you will get the background color specified by the style, rather than white. Try https://tb15.cubewerx.com/cubewerx/cubeserv/op?SERVICE=WMS&VERSION=1.3.0&REQUEST=GetMap&FORMAT=image%2Fx-jpegorpng&LAYERS=Daraa_vectors&STYLES=Topographic&CRS=EPSG%3A3857&WIDTH=640&HEIGHT=325&BBOX=4024937,3840638,4028353,3842372

Cubewerx created a short demonstration, available at https://tb15.cubewerx.com/cubewerx/demos/BackgroundColorDemo.html to illustrate the final effect. In addition to the gray background of the Topographic style, check out the blue background of the Night style! Also note that when the "Daraa Mosaic 2019" imagery is selected, the imagery becomes the background. The following figures show the client in action:

The Styleable Layer Sets concept was introduced to group multiple styles that apply to the same data set or schema. For example, a styleable layer set could apply to a theater of operations and could group a set of styles (e.g., "topographic", "satellite overlay", and "night"). The concept was originally developed as part of the Vector Tiles Pilot and is described in detail in the OGC Engineering Report 18-101 with the concept’s definition and a corresponding UML diagram.

Styleable layer sets allow defining bi-directional data layer to style and style to data layer associations. In this context, please note that a styleable layer set is necessarily constrained to vector data.

GeoPackage has support for styleable layer sets as well. This capability is described in section GeoPackage: Coupling Styles and Layers. The recommended approach uses the semantic annotation model. Here, the original proposal called for a column to be added to a pair of tables. However, the semantic annotation approach would be more flexible and could be applied to both conventional and tiled vector layers. In this case, both the layers and the styles could be annotated with one or more styleable layer sets.