= !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 [wiki:MapGuideRfcs 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||4.0||
||Assigned PSC guide(s)||||
||'''Voting History'''||||
||+1||Crispin,Jackie,Haris||
||+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 || 4.0.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 [wiki:MapGuideRfc158] ||

The response matches the new {{{TransformedCoordinateCollection-4.0.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 {{{4.0.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