= !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
{{{
A collection of transformed coordinates
Information about the coordinate system
Mentor (CS-Map) coordinate system code
EPSG code
The well-known text of the coordinate system
Represents a transformed coordinate
x-coordinate
y-coordinate
The string token that failed to parse into a coordinate pair
}}}
The {{{}}} 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 {{{}}} elements do not have any {{{}}} 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=}}} outputs GeoJSON with transformed coordinates in {{{output_cs}}}
* Verify {{{CS.TRANSFORMCOORDINATES}}} with malformed {{{COORDINATE}}} strings, properly puts un-parseable tokens into the {{{}}} element of their respective {{{}}} element in the operation response.
== Funding/Resources ==
Community