MapGuide RFC 94 - Datum Transformation Upgrade
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 | Wed Jun 9 16:57:56 2010 |
| Last Modified | Norm Olsen 21 June 2010 |
| Author | Norm Olsen |
| RFC Status | adopted |
| Implementation Status | pending |
| Proposed Milestone | 2.3 |
| Assigned PSC guide(s) | Bruce Dechant |
| Voting History | |
| +1 | Bruce, Tom, Trevor, Jason, Zac, Jackie, Haris |
| +0 | |
| -0 | |
| -1 | |
| no vote | Bob, Paul |
Overview
It is proposed to incorporate within the MgCoordinateSystem interface the new features of MetaCRS/CS-MAP RFC 2. The referenced CS-MAP RFC 2 proposes a major rework of how datum transformations are defined and is intended to improve the generality of geodetic transformations (i.e. datum shifts).
There may be few changes to existing interfaces as described below, but mostly the effort will augment (rather than change) the existing interfaces. Numerical results produced by the proposed changes will not change, nor will the performance of the package change in either direction. Among other things, the proposed changes will increase the number of parameters supported for a geodetic transformation, thus enabling the implementation of additional transformation methods which could not be supported previously.
Motivation
CS-MAP's existing datum transformation model is an anachronism dating back to DMA TR-8350.2-B, December 1987 (TR == Technical Report). It is based on the concept of using WGS84 as what is referred to as a "pivot datum". All geodetic transformations are defined as part of a datum definition, where the datum definition carries the method and parameters necessary to convert from the datum being defined to WGS84. A complete geodetic transformation is currently accomplished (usually) by using the forward method of the source datum to convert to WGS84 and the inverse method of the target datum to produce the desired result.
It is proposed that this "pivot datum" model be replaced with a model which closely resembles that used by EPSG. In this new model a geodetic transformation definition will associate a geodetic method with the appropriate parameters which will convert from a source datum to a target datum (without the implication of using WGS84 for either the source or target) and the concept of a geodetic transformation path which enable the specification of an ordered list of geodetic transformations as the means to convert from any datum to any other. The new geodetic transformation dictionary will provide an increase in the number of transformation parameters thus enabling implementation of new transformation methods which the lack of additional parameters prohibited.
The above motivations are the motivations of the referenced CS-MAP RFC 2 project. This MapGuide RFC is proposed to enable the above defined benefits to be added to the MgCoordinateSystem API of MapGuide.
Proposed Solution
- The reference CS-MAP RFC #2 proposes to introduce two new objects to the CS-MAP repetoire: a Geodetic Transformation object and a Geodetic Path object.
- The existing MgCoordinateSystemGeodeticTransform object will be reworked to interface with this new CS-MAP equivalent and be associated with a new Geodetic Transformation Dictionary object as described below. It is expected that the reworked interface will support all existing members of this interface; possible exceptions are listed in the Implications section of this RFC. As far as numeric results are concerned, the interface will not change. There will be several additions to this interface enabling support of all transformation techniques (such as the grid file techniques).
- A new MapGuide object will be implemented to interface with the new CS-MAP Geodetic Path object. This new object will be connected to a new dictionary object as detailed below. The interface for this object will enable the specification of an ordered list of one or more geodetic transformations as the means by which a complete datum shift from any defined datum to any other defined datum is to be accomplished.
- The referenced CS-MAP RFC 2 proposes the implementation of two entirely new dictionaries: a Geodetic Transformation Dictionary and a Geodetic Path Dictionary. Interfaces to these new dictionaries which mimic the existing four dictionary objects would to be added to the MgCoordinateSystem interface.
Implications
- The intent is to leave all existing interfaces and functionality undisturbed. However, note that the two new objects will be provided as a means to access and maintain the underlying CS-MAP dictionary files. All datum shift calculations will continue to be accomplished within the CS-MAP library.
- Two additional dictionary files will need to be included in the MapGuide distribution, in the same folder as the current four dictionaries are distributed.
- The performance of the "setup" portion of a geodetic transformation may be reduced (i.e. MgCoordinateSystemTransform constructor), but no effect on the actual performance of the conversion process is expected.
- It is safe to say that existing applications which use the basic coordinate conversion interface will not see any change.
- Applications which use the current API to manipulate dictionary entries may experience some small changes. This will be due to the fact that the definition of a datum transformation will no longer reside in the Datum Dictionary and that a single geodetic transformation object may be only one of a series of transformations necessary to calculate the shift from source to target datums. Such differences will not be apparent for geodetic transformations which are consistent with the current datum transformation model (i.e. using a pivot datum of WGS84). A new and different behavior might be observed for new geodetic transformations which do not fit within this model. The specific API's which might be affected are:
double MgCoordinateSystemGeodeticTransformation::GetOffsetX(); double MgCoordinateSystemGeodeticTransformation::GetOffsetY(); double MgCoordinateSystemGeodeticTransformation::GetOffsetZ(); void MgCoordinateSystemGeodeticTransformation::SetOffset(double x, double y, double z); double MgCoordinateSystemGeodeticTransformation::GetBursaWolfeTransformRotationX(); double MgCoordinateSystemGeodeticTransformation::GetBursaWolfeTransformRotationY(); double MgCoordinateSystemGeodeticTransformation::GetBursaWolfeTransformRotationZ(); double MgCoordinateSystemGeodeticTransformation::GetBursaWolfeTransformBwScale(); void MgCoordinateSystemGeodeticTransformation::SetBursaWolfeTransform(double dRotationX, double dRotationY, double dRotationZ, double dBwScale); INT32 MgCoordinateSystemGeodeticTransformation::GetGeodeticTransformationMethod(); void MgCoordinateSystemGeodeticTransformation::SetGeodeticTransformationMethod(INT32 nGeodeticTransformationMethod);
- Since CS-MAP is now Open Source, it is possible (certainly not recommended) that there exist applications which access the CS-MAP library directly. While the primary CS-MAP API will not change, certian lower level functions will necessarily change; thus such applications may be negatively affected.
Test Plan
The referenced CS-MAP RFC proposes a rigorous regression test feature to insure that numerical results produced after implementation of the RFC are identical to the results produced prior to implementation of the RFC. This same test data and algorithm will be implemented on top of the MgCoordinateSystem interface to assure that there are no regressions in the MgCoordinateSystem interface.
Funding/Resources
Funded by, and development and quality assurance resources provided by, Autodesk.
Addendum
The implementation of the CCoordinateSystemMathComparator::SameDatum(MgCoordinateSystemDatum *pDefinition1, MgCoordinateSystemDatum *pDefinition2) has to be adjusted so it does (optionally, i.e. no change in default behavior) no longer considers the transformation information that might be attached to a datum object. Due to the CSMAP RFC2, such geodetic transformation information is no longer an inherent part of a datum definition but is now available in a separate dictionary.
New API in MgCoordinateSystemMathComparator:
void SetCompareInternalDatumOldParameters(bool); //on by default; i.e. no change in default behavior bool GetCompareInternalDatumOldParameters();
The implementation in CCoordinateSystemMathComparator has be changed accordingly. That is, if
CCoordinateSystemMathComparator::GetCompareInternalDatumOldParameters()
is true, the code will no longer try to match the transformation parameters of the cs_dtDef_ struct.
