Publication Date: YYYY-MM-DD

Approval Date: YYYY-MM-DD

Submission Date: YYYY-MM-DD

Reference number of this document: OGC 19-046

Reference URL for this document: http://www.opengis.net/doc/PER/t14-ID

Category: OGC Public Engineering Report

Editor: Scott Serich

Title: OGC Testbed-15: Quebec Model MapML Engineering Report


OGC Public Engineering Report

COPYRIGHT

Copyright © 2018 Open Geospatial Consortium. To obtain additional rights of use, visit http://www.opengeospatial.org/

WARNING

This document is not an OGC Standard. This document is an OGC Public Engineering Report created as a deliverable in an OGC Interoperability Initiative and is not an official position of the OGC membership. It is distributed for review and comment. It is subject to change without notice and may not be referred to as an OGC Standard. Further, any OGC Public Engineering Report should not be referenced as required or mandatory technology in procurements. However, the discussions in this document could very well lead to the definition of an OGC Standard.

LICENSE AGREEMENT

Permission is hereby granted by the Open Geospatial Consortium, ("Licensor"), free of charge and subject to the terms set forth below, to any person obtaining a copy of this Intellectual Property and any associated documentation, to deal in the Intellectual Property without restriction (except as set forth below), including without limitation the rights to implement, use, copy, modify, merge, publish, distribute, and/or sublicense copies of the Intellectual Property, and to permit persons to whom the Intellectual Property is furnished to do so, provided that all copyright notices on the intellectual property are retained intact and that each person to whom the Intellectual Property is furnished agrees to the terms of this Agreement.

If you modify the Intellectual Property, all copies of the modified Intellectual Property must include, in addition to the above copyright notice, a notice that the Intellectual Property includes modifications that have not been approved or adopted by LICENSOR.

THIS LICENSE IS A COPYRIGHT LICENSE ONLY, AND DOES NOT CONVEY ANY RIGHTS UNDER ANY PATENTS THAT MAY BE IN FORCE ANYWHERE IN THE WORLD. THE INTELLECTUAL PROPERTY IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT OF THIRD PARTY RIGHTS. THE COPYRIGHT HOLDER OR HOLDERS INCLUDED IN THIS NOTICE DO NOT WARRANT THAT THE FUNCTIONS CONTAINED IN THE INTELLECTUAL PROPERTY WILL MEET YOUR REQUIREMENTS OR THAT THE OPERATION OF THE INTELLECTUAL PROPERTY WILL BE UNINTERRUPTED OR ERROR FREE. ANY USE OF THE INTELLECTUAL PROPERTY SHALL BE MADE ENTIRELY AT THE USER’S OWN RISK. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR ANY CONTRIBUTOR OF INTELLECTUAL PROPERTY RIGHTS TO THE INTELLECTUAL PROPERTY BE LIABLE FOR ANY CLAIM, OR ANY DIRECT, SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES, OR ANY DAMAGES WHATSOEVER RESULTING FROM ANY ALLEGED INFRINGEMENT OR ANY LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR UNDER ANY OTHER LEGAL THEORY, ARISING OUT OF OR IN CONNECTION WITH THE IMPLEMENTATION, USE, COMMERCIALIZATION OR PERFORMANCE OF THIS INTELLECTUAL PROPERTY.

This license is effective until terminated. You may terminate it at any time by destroying the Intellectual Property together with all copies in any form. The license will also terminate if you fail to comply with any term or condition of this Agreement. Except as provided in the following sentence, no such termination of this license shall require the termination of any third party end-user sublicense to the Intellectual Property which is in force as of the date of notice of such termination. In addition, should the Intellectual Property, or the operation of the Intellectual Property, infringe, or in LICENSOR’s sole opinion be likely to infringe, any patent, copyright, trademark or other right of a third party, you agree that LICENSOR, in its sole discretion, may terminate this license without any compensation or liability to you, your licensees or any other party. You agree upon termination of any kind to destroy or cause to be destroyed the Intellectual Property together with all copies in any form, whether held by you or by any third party.

Except as contained in this notice, the name of LICENSOR or of any other holder of a copyright in all or part of the Intellectual Property shall not be used in advertising or otherwise to promote the sale, use or other dealings in this Intellectual Property without prior written authorization of LICENSOR or such copyright holder. LICENSOR is and shall at all times be the sole entity that may authorize you or any third party to use certification marks, trademarks or other special designations to indicate compliance with any LICENSOR standards or specifications.

This Agreement is governed by the laws of the Commonwealth of Massachusetts. The application to this Agreement of the United Nations Convention on Contracts for the International Sale of Goods is hereby expressly excluded. In the event any provision of this Agreement shall be deemed unenforceable, void or invalid, such provision shall be modified so as to make it valid and enforceable, and as so modified the entire Agreement shall remain in full force and effect. No decision, action or inaction by LICENSOR shall be construed to be a waiver of any rights or remedies available to it.

None of the Intellectual Property or underlying information or technology may be downloaded or otherwise exported or reexported in violation of U.S. export laws and regulations. In addition, you are responsible for complying with any local laws in your jurisdiction which may impact your right to import, export or use the Intellectual Property, and you represent that you have complied with any regulations or registration procedures required by applicable law to make this license enforceable.

1. Subject

This Engineering Report (ER) describes the Map Markup Language (MapML) enabled client component implementation for the Quebec Lake-River Differentiation Model in the Machine Learning (ML) task of Open Geospatial Consortium (OGC) Testbed-15. It presents the MapML parsing capabilities that were developed to illustrate the outputs of a ML model to delineate lake and river features from an undifferentiated waterbody vector dataset in Québec, Canada. Client data was accessed through an OGC Web Processing Service (WPS) interface in coordination with an OGC Web Feature Service (WFS) API implementation.

2. Executive Summary

Add content here.

2.1. Document contributor contact points

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

Contacts

Name Organization Role

Scott Serich

OGC Staff

Editor

Gil Heo

George Mason University

Contributor

Jérôme Jacovella-St-Louis

Ecere Corporation

Contributor

Peter Rushforth

Natural Resources Canada

Contributor

2.2. Foreword

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.

3. References

The following normative documents are referenced in this ER.

NOTE: Only normative standards are referenced here, e.g. OGC, International Organization for Standardization (ISO) or other standards development organization standards. All other references are listed in the bibliography. Example:

4. Terms and definitions

For the purpose of this report, the definitions specified in Clause 4 of the OGC Web Services (OWS) Common Implementation Standard OGC 06-121r9 shall apply. In addition, the following terms and definitions apply.

● map

portrayal of geographic information as a digital image file suitable for display on a computer screen

● portrayal

presentation of information to humans (source: ISO 19117)

4.1. Abbreviated terms

NOTE: The abbreviated terms clause gives a list of the abbreviated terms and the symbols necessary for understanding this document. All symbols should be listed in alphabetical order. Some more frequently used abbreviated terms are provided below as examples.
  • API - Application Programming Interface

  • CORS - Cross-Origin Resource Sharing

  • CSS - Cascading Style Sheets

  • DOM - Document Object Model

  • EC2 - Elastic Compute Cloud

  • GML - Geography Markup Language

  • HTML - Hypertext Markup Language

  • IANA - Internet Assigned Numbers Authority

  • ISO - International Organization for Standardization

  • JPEG - Joint Photographic Experts Group

  • JSON - JavaScript Object Notation

  • KML - Keyhole Markup Language

  • MapML - Map Markup Language

  • ML - Machine Learning

  • MVC - Model-View-Controller

  • OGC - Open Geospatial Consortium

  • OWS - OGC Web Services

  • PNG - Portable Network Graphics

  • SVG - Scalable Vector Graphics

  • URL - Uniform Resource Locator

  • WFS - Web Feature Service

  • WMS - Web Map Service

  • WMTS - Web Map Tile Service

  • WPS - Web Processing Service

5. Overview

Note

The following content has been paraphrased from the Testbed-14 engineering report. It will be updated during Testbed-15.

Much of the work in implementing this client was based on the foundational work of the MapML W3C Community Group.

Section 5 introduces the coordinate reference systems that are used by MapML and suggests some alignment with the OGC WMTS Tile Matrix Set specifications.

[tentative] Section 6 discusses the introduction of URL templates in the MapML specification and how the introduction of the URL templates has changed the interaction between clients and services.

[tentative] Section 7 continues the discussions about the encodings for features.

[tentative] Section 8 presents several discussions about the use of CSS for styling features.

[tentative] Section 9 suggests the introduction of event handling in Maps4html.

[tentative] Section 10 presents some discussions and topics that could be extended in further interoperability experiments.

[tentative] Section 11 records the lessons learned and experiences coming from the components implementing MapML experimented or developed in this testbed.

[tentative] Section 12 discusses a possible way forward, beyond HTML, to share maps in social media.

[tentative] Section 13 discusses a web service that combines WMS and WMTS and provides MapML documents as an output.

5.1. MapML in relation to other encodings

MapML is unique relative to other encodings but there is some level of duplication. What makes MapML unique is that it takes Spatial Data on the Web Best Practices (Tandy2017) and applies them directly to HTML users instead of favoring web developers.

As described by the MapML use cases and requirements, MapML is an extension to HTML, which if implemented, implies that the browser understands map/layer semantics (however those elements are eventually named), as well as feature, property, or geometry semantics. MapML is intended to be user-oriented. It aims at enabling users to create web pages in all manner of styles, but having the common denominator being HTML and Cascading Style Sheets (CSS), as well as JavaScript for progressive enhancement. Today, there is no built-in map/layer behavior in web browsers, nor is there feature/property/geometry semantics. MapML provides the ability to encode map/layer and feature/property/geometry semantics in one (simple) format that will be read and interpreted by web browsers directly. MapML brings geographic knowledge to the web browser, thereby making the web browser the user agent.

MapML maintains a different focus as compared to other encodings such as GeoJSON, Geography Markup Language (GML), and Keyhole Markup Language (KML), which require JavaScript interpretation and are not native in web browsers. MapML should not be constrained by other encodings should the need for user-oriented features arise (e.g. markup in coordinate strings and possibly other requirements). A major objective of MapML is to make the browser understand not only where the user is (that is already standardized by the GeoLocation API, https://www.w3schools.com/html/html5_geolocation.asp), but also to understand where features are in relation to the user.

5.2. MapML as a media type

A MapML document is a new media type for maps on the web. It looks very similar to and it is inspired by HTML, but it is not HTML. Even if it could look like HTML, it is actually written under the rules of MicroXML.

This document uses text/mapml as the media type for MapML documents.

Note

This type has not yet been negotiated with Internet Assigned Numbers Authority (IANA).

A MapML document can be included in an HTML document in two ways:

  • by a link (src attribute) in the <layer> element in the <map> division:

<map zoom="15" lat="45.398043" lon="-75.70683" width="640" height="300" projection="CBMTILE">
  <layer label="Canada Base Map" src="http://example.com/mapml/cbmt/" checked></layer>
  <layer label="CanVec+ 031G" src="http://example2.com/mapml/canvec/50k/features/"></layer>
</map>
  • embedded directly in the HTML page, in the same way a Scalable Vector Graphics (SVG) document can also be included.

<html>
  <body>
    <map projection="CBMTILE" zoom="17" lat="45.4624905" lon="-74.9787676" width="900" height="400" controls>
      <layer label="CanVec+ Features" checked>
        <extent units="WGS84" method="GET">
          <input ...>
          <...>
          <link rel="features" ...>
        </extent>
      </layer->
    </map>
  </body>
</html>
Note

The second option is not yet part of the Maps4HTML draft specification.

There is a fundamental difference between the first and the second approach. If the MapML document is linked to the HTML page, the MapML becomes opaque to the HTML page. In practice this means that the internal content of a MapML document is not part of the Document Object Model (DOM) structure of HTML and it will not be accessible for scripting (e.g. it will not be accessible to the JavaScript code associated with the HTML page). When the MapML encoding is embedded in the HTML page, it is part of the HTML DOM and it can be read and altered by scripts.

The fact that linked MapML documents are opaque to the scripts suggests the need to have events associated with MapML linked documents, in order to notify scripts about some changes in the map produced by user interactions. This will be discussed later in this document.

6. Background

This engineering report describes the MapML-enabled client component implementation for the Quebec Lake-River Differentiation Model in the ML task of OGC Testbed-15. It presents the MapML parsing capabilities that were developed to illustrate the outputs of an ML model to delineate lake and river features from an undifferentiated waterbody vector dataset in Québec, Canada. Client data was accessed through an OGC WPS interface in coordination with an OGC WFS API implementation.

The most recent prior MapML work in the OGC is described in the OGC Testbed-14 engineering report.

6.1. Overview of the ML Architecture

The overall architecture of the Testbed-15 ML Task was based on a broad set of scenarios ranging from image classification to dataset discovery.

The objective of the Quebec Lake-River Differentiation Model subtask was to create and deploy an ML model to differentiate between rivers and lakes from otherwise unlabeled bodies of water. The main focus of the work was to provide a service to determine whether a body of water should be split into a lake and a river, and to provide identified and labeled outputs when such splits occur. When no split was required, each body of water was labeled as either lake or river. The procedure for applying the model was to:

  1. Recommend whether a water body should be split into a lake and river features.

  2. Evaluate the confidence level of a recommendation.

  3. Apply the recommendation to the dataset.

  4. Test and correct the resultant dataset for topological and cartographical issues.

  5. Serve the data on a WFS 3.0 interface using a MapML encoding.

Each service component was fronted by the relevant OGC interface, a WPS for workflow management and a WFS 3.0 data interface for features.

7. Quebec Model MapML Service

Note
Overall

This section is designed to describe the implementation of your component along with the experiences of developing for the use cases from the CFP. These sections will be compared with the Architecture section at the beginning to see how the implementations differ from the original purpose of the thread. Each of the sections below are top-level, please feel free to add subsections as required.

7.1. Component Summary

Note
Introduction

Briefly introduce your component summary here. The entire component section should focus on the implementation, as the questions from the CFP are discussed in the architecture section.

7.2. Component Design

Note
Design

The design section should outline the overall architecture of the implementation. This could differ from what was in the CFP as it is your answer to the requirements. It should include diagrams, preferably UML. The editor is happy to help with creating UML diagrams (sequence for execution, potentially class for data model, a use case diagram is also good). If you want to do something like Archimate to show your system level architecture that could work.

7.3. Implementation Approach

Note
Approach

what approach did you take and why? This is the main section for capturing experiences and decisions made throughout the course of your implementation efforts.

7.3.1. Machine Learning Model

Note
ml

If relevant, please include information about the ML model that you produced. This should include information about the model building process, predictive power and other statistics related to the quality of the model.

7.4. Component Implementation

Example 1. implementations

What did you produce? Endpoints, screen shots, all of work that you did in development should be captured here. You should also include a sub-section on how the components talk to other components and also what clients have been implemented to exercise your components. Include lots of screenshots and diagrams to illustrate the work you have done.

8. Quebec model MapML Client

The Quebec model MapML Client (D106) displays MapML documents served by OGC API - Features. The final geospatial results of the ML model are provided in vector format. The data at its different stages are displayed using MapML served by OGC API - Features.

A scenario includes a single WPS instance that serves as an interface to the vectorization model. The service/model needs to connect to various OWS instances at the backend. The WFS instance serves the results of the vectorization process as MapML. A dedicated client application interacts with the service instances and displays the MapML data.

Scenario
Figure 1. Quebec scenario work items

The scenario begins that a client receives a notification from a WPS instance which is informing ready to service. After that, the client requests features to a OGC API - Features instance, and receives a MapML document which is describing a final geospatial result of the ML model as a vector format.

8.1. Component Summary

The Quebec model MapML Client (D106) is a web application which is executable on a web browser. The D106 application logic is in the client-side of the deliverable, and the logic is running on browser engine in a web browser.

The D106 client supports the following features:

  • showing vector features (MapML and GeoJSON format) served by OGC API - Features

  • supporting spatial and temporal constraints

  • executing generic operations served by WPS 2.0

  • showing single and tile images served by WMS/WMTS, ArcGIS REST, XYZ

  • supporting a pixel picker tool

The following Figure 2 is showing the top-level software architecture of the D106 client.

Overview
Figure 2. Top-level Software Structure

The server-side components consist of a web server, a proxy server, and application resources like HTML files, scripts, images, etc. A web browser loads all the D106 application relative resources, and then a browser engine (e.g. WebKit in Google Chrome) in the web browser executes them as client-side components.

The client-side components do not need any server-side backend processing, but because of the Cross-origin resource sharing (CORS) mechanism, certain cross-origin requests on modern web browsers are forbidden by the same-origin security policy. The D106 client sometimes need to fetch cross-origin XML or JSON contents, such as a response of GetCapabilities of WPS or WMS/WMTS, Collections list of OGC API - Features, MapML documents, etc., which are not allowed by the mechanism on web browser. To avoid this restriction, any cross-origin URL is encapsulated in a new same-origin URL, and then sends it to the proxy server. The proxy server is a small, simple bypass server programmed in Python. and it is called by web server. A client-side component requests a prohibited cross-origin URL to a predefined path, the web server bypasses the request to the proxy server.

8.2. Component Design

The D106 deliverable is a web application, and its software structure is based on Model-view-controller (MVC). Each client-side component has its own model, view, and controller, and the components are sharing only a few variables and methods each other.

In the D106 client has 5 user interface components and 1 MapML component:

  • Map Area: Manipulating map area supported by OpenLayers

  • WFS Client: Fetching collections and their items served by OGC API - Features

  • Layers: Managing vector and image layers

  • WPS Client: Fetching and executing operations served by WPS 2.0

  • Toolbar: supporting spatial and temporal constraints, additional tools, and settings menu

  • MapML: Manipulating MapML document

    • Parser: parsing MapML document, and then producing a MapML document object model

    • Document Object: MapML document object model

    • OpenLayers Front-end: creating a layer objects array of OpenLayers from MapML document object model

The following Figure 3 is a sequence diagram which is from fetching a collections list served by OGC API - Features to acquiring an item written by MapML document.

Overview
Figure 3. Fetching MapML document from OGC API - Features

8.2.1. Step 1. Acquiring a Collections List

An end-user interaction about an input of OGC API - Features service endpoint is a view part of WFS Client component. The WFS Client sends a request of end-user via Ajax to local web server, instead of sending OGC API - Features service endpoint directly, because of avoiding cross-origin restriction. The service-endpoint URL is encapsulating with a proxy requesting format, so the local web server recognizes what this request is, and then bypasses the URL to local proxy server. The proxy server requests desired content with the URL, receives it, and returns it to the web server. Finally, WFS Client receives desired content from the web server without any problem with cross-origin restriction.

8.2.2. Step 2. Acquiring a MapML document

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, etc., An end-user can request features information by clicking AddLayer button in the user interface. The WFS Client sends a request for acquiring item features to local web server as the same way as the Step 1, and finally, the WFS Client gets a MapML document which contains desired item features.

8.2.3. Step 3. Showing features from the MapML document

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

8.3. Implementation Approach

To show a MapML document on map area, the D106 parses the MapML document by using MapML Parser, and then converts it to an OpenLayers layer object by using MapML OpenLayers Front-end. Especially, the parser converts all <feature> elements to a single GeoJSON object for showing on map area easily.

8.3.1. MapML Parser

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

Overview
Figure 4. MapML document parsing

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

8.3.2. OpenLayers Front-end

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

To become a MapML viewer, beyond a OGC API - Features client, the D106 must support <extent> elements as a layer of map area. Each <link> in <extent> element can describe raster and vector layers, and each of them will become a layer. The following Figure 5 is showing not only a GeoJSON object becomes a vector layer of OpenLayers, but also how each <link> will become a proper layer of OpenLayers.

Overview
Figure 5. OpenLayers front-end for MapML

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

import MapML from './MapML.js';
import OlMapML from './OlMapML.js';
...
let content = "<mapml> ... </mapml>";

let mapml = new MapML();
let mapmlDoc = mapml.parse( content );   // returns MapMLDoc
let geojson = mapmlDoc.getGeoJSON();     // GeoJSON object
// or
let olMapML = new OlMapML( mapmlDoc, { projection: 'EPSG:3857' } );   // OpenLayers front-end
let layers = olMapML.getLayers();        // OpenLayers Layer array (both <extent> and <feature>s)
...

8.4. Component Implementation

The deliverable D106 is a web application based on React web framework. The deliverable is deployed on a Linux virtual machine supported by Amazon Elastic Compute Cloud (Amazon EC2) web service. The final deliverable D106 can be accessible at the following URL:

8.4.1. Runtime Environments (for the D106 web application)

  • Processor: Intel Xeon CPU E5-2676 v3 @ 2.40GHz

  • Memory: 1GB

  • Storage: 10GB SSD

  • OS: Linux Ubuntu 16.04 LTS

  • Web Server: Apache HTTP Server 2.4.18

  • Proxy Runtime: Python 2.7.12

8.4.2. User Interface

The following Figure 6 is showing the top-level screen view on a modern web browser.