MapGuide RFC 162 - Enhanced coordinate system capabilities in mapagent

This page contains a change request (RFC) for the MapGuide Open Source project. More MapGuide RFCs can be found on the RFCs page.

Status

RFC Template Version	(1.0)
Submission Date	12 July 2017
Last Modified	10 Dec 2017
Author	Jackie Ng
RFC Status	adopted
Implementation Status	implemented
Proposed Milestone	3.3
Assigned PSC guide(s)
Voting History
+1
+0
-0
-1
Abstained

Overview

This RFC proposes to enhance the coordinate system capabilities of the mapagent

Motivation

MapGuide has one of the most powerful coordinate system transformation libraries (CS-Map) with support for several thousand different coordinate systems out of the box.

Yet, as a MapGuide HTTP client application none of these transformation capabilities are ever exposed to the mapagent. To tap into coordinate transformation requires using the MapGuide Web API and thus custom server-side code that a HTTP client application would have to call into.

Proposed Solution

This RFC will add the following enhancements to the mapagent

Batch Coordinate Transformation

We'll add a new mapagent operation for batch transformation of coordinates from one coordinate system to another

Name	Value	Required	Description
OPERATION	CS.TRANSFORMCOORDINATES	Yes	Operation to execute
VERSION	3.3.0	Yes	Operation version
CLIENTAGENT	text	Optional	Descriptive text for client
SOURCE	string	Yes	The CS-Map code describing the coordinate system of the input coordinates
TARGET	string	Yes	The CS-Map code of the coordinate system to transform the input coordinates to
COORDINATES	string	Yes	A comma-separated list of space-separated coordinate pairs (in the source coordinate system)
FORMAT	string	Yes	text/xml for XML, application/json for JSON
CLEAN	1/0	Optional	If requested format is application/json, returns a clean JSON structure per MapGuideRfc158

The response matches the new TransformedCoordinateCollection-3.3.0.xsd schema

<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified" attributeFormDefault="unqualified">
  <xs:element name="TransformedCoordinateCollection">
    <xs:annotation>
      <xs:documentation>A collection of transformed coordinates</xs:documentation>
    </xs:annotation>
    <xs:complexType>
      <xs:sequence>
        <xs:element name="CoordinateSystem" type="CoordinateSystemInfo" />
        <xs:element name="TransformedCoordinate" type="TransformedCoordinate" minOccurs="0" maxOccurs="unbounded" />
      </xs:sequence>
    </xs:complexType>
  </xs:element>
  <xs:complexType name="CoordinateSystemInfo">
    <xs:annotation>
      <xs:documentation>Information about the coordinate system</xs:documentation>
    </xs:annotation>
    <xs:sequence>
      <xs:element name="MentorCode" type="xs:string">
        <xs:annotation>
          <xs:documentation>Mentor (CS-Map) coordinate system code</xs:documentation>
        </xs:annotation>
      </xs:element>
      <xs:element name="EpsgCode" type="xs:integer">
        <xs:annotation>
          <xs:documentation>EPSG code</xs:documentation>
        </xs:annotation>
      </xs:element>
      <xs:element name="Wkt" type="xs:string">
        <xs:annotation>
          <xs:documentation>The well-known text of the coordinate system</xs:documentation>
        </xs:annotation>
      </xs:element>
    </xs:sequence>
  </xs:complexType>
  <xs:complexType name="TransformedCoordinate">
    <xs:annotation>
      <xs:documentation>Represents a transformed coordinate</xs:documentation>
    </xs:annotation>
    <xs:sequence>
      <xs:element name="X" type="xs:double" minOccurs="0" maxOccurs="1">
        <xs:annotation>
          <xs:documentation>x-coordinate</xs:documentation>
        </xs:annotation>
      </xs:element>
      <xs:element name="Y" type="xs:double" minOccurs="0" maxOccurs="1">
        <xs:annotation>
          <xs:documentation>y-coordinate</xs:documentation>
        </xs:annotation>
      </xs:element>
      <xs:element name="Error" type="xs:string" minOccurs="0" maxOccurs="1">
        <xs:annotation>
          <xs:documentation>The string token that failed to parse into a coordinate pair</xs:documentation>
        </xs:annotation>
      </xs:element>
    </xs:sequence>
  </xs:complexType>
</xs:schema>

The <Error> element in the schema is used to capture any string tokens in the COORDINATES operation parameter that does not parse out to a space-separated coordinate pair. Thus a successful batch transformation operation is one whose list of <TransformedCoordinate> elements do not have any <Error> elements set.

This mapagent operation supports both GET and POST methods. Bigger coordinate lists can be specified via POST to overcome natural (client-and-server-imposed) limits in query string size.

Transformation support for any mapagent operation that returns geometry

Any operation that returns geometry data will now have an optional TRANSFORMTO parameter, which if set (to an appropriate Mentor CS code) will instruct the supporting operation to transform the geometry result to the specified coordinate system.

The following operations will have a new 3.3.0 version that supports the optional TRANSFORMTO parameter:

• SELECTFEATURES
• SELECTAGGREGATES (if a geometric aggregate expression is found. eg. SpatialExtents, otherwise TRANSFORMTO has no effect)

Implications

These are new API additions

Test Plan

• Verify SELECTFEATURES and SELECTAGGREGATES behave as before without the TRANSFORMTO parameter
  • Verify SELECTFEATURES and SELECTAGGREGATES (with SpatialExtent aggregate) output transformed coordinates according to the TRANSFORMTO parameter
  • Verify that SELECTFEATURES and SELECTAGGREGATES (with SpatialExtent aggregate) with CLEAN=1 TRANSFORMTO=<output_cs> outputs GeoJSON with transformed coordinates in output_cs
• Verify CS.TRANSFORMCOORDINATES with malformed COORDINATE strings, properly puts un-parseable tokens into the <Error> element of their respective <TransformedCoordinate> element in the operation response.

Funding/Resources

Community