= !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||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 [wiki:MapGuideRfc158] || The response matches the new {{{TransformedCoordinateCollection-3.3.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 {{{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=}}} 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