MapGuide RFC 55 - Switch from PROJ4 to CS-Map coordinate system library

This page contains an 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	August 07, 2008
Last Modified	Bruce Dechant Timestamp
Author	Hugues Wisniewski
RFC Status	adopted
Implementation Status	completed
Proposed Milestone	2.1
Assigned PSC guide(s)	Bruce Dechant
Voting History
+1	Andy, Bruce, Haris, Jason, Paul, Tom
+0
-0
-1
no vote	Bob

Overview

For the coordinate system work, MapGuide uses the PROJ4 library which is wrapped into the MgGeometry.dll binary module. The coordinate system functionality is exposed through all the API interfaces prefixed with MgCoodinateSystem This proposal aims at replacing the PROJ4 implementation with the CS-Map implementation. CS-Map was recently open sourced and posted on at:
​http://svn.osgeo.org/metacrs/csmap/

Motivation

The CS-Map code has a broader range of functionality than what PROJ4 can offer.

CS-Map can address things that are not well addressed by PROJ4 like:

• vertical datum shifting
  
• WKT transformations in multiple flavors like Oracle
  
• greater coverage in terms of coordinate system definitions, right now more than 4000 systems, roughly 700 datums and 100 ellipsoids
  
• CS-Map can provide an implementation to all the MgCoordinateSystem API methods that currently throw MgNotImplementedException
  

Proposed Solution

The current MgCoordinateSystem API implementation code is a wrapper around PROJ4
This implementation code is located here:
​http://svn.osgeo.org/mapguide/trunk/MgDev/Common/CoordinateSystem/
The new API implementation would wrap the CS-Map code hosted at:
​http://svn.osgeo.org/metacrs/csmap/trunk/CsMapDev/

This API is part of the module MgGeometry.dll generated from the project:
​http://svn.osgeo.org/mapguide/trunk/MgDev/Common/Geometry/Geometry.vcproj

This project is used in the solutions:

​http://svn.osgeo.org/mapguide/trunk/MgDev/Server/Server.sln
​http://svn.osgeo.org/mapguide/trunk/MgDev/Web/src/WebTier.sln

The current PROJ4 implementation would not be supported anymore. Only CS-Map would remain in the place where the PROJ4 currently resides:
​http://svn.osgeo.org/mapguide/trunk/MgDev/Common/CoordinateSystem/

Implications

PROJ4 would not be supported anymore.
The coordinate system definitions will come from the CS-Map coordinate system dictionaries.
All the MgCoordinateSystem API methods that currently throw MgNotImplementedException would have a fully functional implementation.
The build process documentation will have to be updated to explain how to get and build CS-Map and then build MapGuide using CS-Map instead of PROJ4.

Concerning the possible risk that users would see differences from one application to the next when moving from PROJ4 to CS-Map, this may indeed impact MapGuide because of the differences between Proj4 and CSMap. Ie: supported projections, the way transformations are calculated, or slightly different coefficient precision in the coordinate system definitions, etc...
Any of the well known and highly used systems in CS-Map is unit tested with a list of test points that should be transformed to an expected target point within a certain tolerance. This test points in this list typically come from official sources. We can expect slightly different results between the two libraries depending on the reasons listed above but if there is a large difference between the two products, and we have valid test points for a given transformation to test what is expected, the resulting defect we would be facing in that case in the algorithm or in the system definition will have to be fixed.

Some coordinate systems may not work with the new CSMAP. Though the number should be very low. Resources would need to be updated to use the CS-MAP equivalent CS if there is failing CS.
If a definition is missing, the creation of a custom system is possible via the fully implemented MgCoodinateSystem API that will be provided.
If a projection or datum technique is missing, a source code update would be needed inside CS-Map. This would be of course possible after approval of the corresponding RFC that would need to be written against that OSGEO project.

Test Plan

CS-Map has its own standalone unit tests so it can be tested separately.
The existing unit MapGuide unit tests would remain the same.
More can be added, especially for the new functionality that CS-Map provides, like the WKT conversions.

Funding/Resources

Provided by Autodesk.

Additional Notes

The code is ready to be distributed.
If this request is accepted, the implementation would be trivial as it has already been intensively tested and is fully functional.

Mapping coordinate systems from PROJ4 to CS-Map

PROJ4 to CS-Map

Addendum - New datum transformation technique in CsMap will need to be exposed in the API

There is a new ticket logged against Cs-Map that fixes the 3Parameter conversion technique by introducing a new technique named "Geocentric" ​http://trac.osgeo.org/csmap/ticket/4

When this defect is fixed, the switch to the Cs-Map implementation will need to have the MgCoordinateSystem API expose it via a new entry inside the MgCoordinateSystemGeodeticTransformationMethod enum That is the only change in the API that is expected from the move to CsMap