MapGuide RFC 94 - Dtaum 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 Timestamp
Author	Norm Olsen
RFC Status	draft
Implementation Status	pending
Proposed Milestone	2.3
Assigned PSC guide(s)
Voting History
+1
+0
-0
-1
no vote

Overview

Incorporate within the MgCoordinateSystem interface the new features of MetaCRS/CS-MAP RFC 2. The referenced CS-MAP RFC proposes a major rework of how datum transformations are defined and is intended to vastly improve the generality of geodetic transformations (i.e. datum shifts).

There will be few changes to any existing interface, although several interface methods are recommended for deprecation. Numerical results produced by the suggested changes will not change. These changes will increase the number of parameters supported for a geodetic transformation, thus enabling the implementation of additional tranformation 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 or any other pivot datum) 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 geodetiv transformation dictionary will provide anincrease 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 prposed to enable the above defined benefits to be added to the MgCoordinateSysteme API of MapGuide.

Proposed Solution

• The referenced CS-MAP RFC 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.

• The constructor for the MgCoordinateSystemCatalog object will be overloaded with a constructor which accepts a parameter which indicates the dictionary folder path, thus enabling applications to specify the location in a platform independent manner. This would not alter any existing interface, simply add an additional interface more conistent with a multi-pltform product environment.

• The major thrust of this effort is the redesign of the underlying CS-MAP datum transformation model. In sympathy with this effort, it is recommended that the following portions of the MgCoordinateSystem interface be deprecated (i.e. continued to be supported, but documented as will be removed in future releases). As currently implemented, these functions accomplish very little. They will not be replaced with anything. You can retrieve and set the indicated values, but in the current implementation doing so has no effect on the calculations of the underlying object. Nor can the modifed values be written at any dictionary (a geodetic transformation dictionary does not exist, YET!)

• 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);
• double MgCoordinateSystemGeodeticTransformation::GetMaxOffset();
• bool MgCoordinateSystemGeodeticTransformation::IsLegalOffset(double dOffset);
• double MgCoordinateSystemGeodeticTransformation::GetMaxRotation();
• bool MgCoordinateSystemGeodeticTransformation::IsLegalRotation(double dRotation);
• double MgCoordinateSystemGeodeticTransformation::GetBwScaleMin();
• double MgCoordinateSystemGeodeticTransformation::GetBwScaleMax();
• bool MgCoordinateSystemGeodeticTransformation::IsLegalBwScale(double dBwScale);

• Three new functions will be added to the API
  • INT32 MgCoordinateSystem::GetEpsgCode()
  • INT32 MgCoordinateSystem::GetEpsgQuadrant()
  • INT32 MgCoordinateSystem::GetSrid ()

GetEpsgCode will return the EPSG Code of the CRS definition, returns 0 if such is not known GetEpsgCode will return the EpsgQuadrantCode which may be different from the CS-MAP quadrant code:

0 X increases to the East, Y increases to the North 1 X increases to the East, Y increases to the North 2 X increases to the West, Y increases to the North 3 X increases to the West, Y increases to the South 4 X increases to the East, Y increases to the South

-1 X increases to the North, Y increases to the East -2 X increases to the North, Y increases to the West -3 X increases to the South, Y increases to the West -4 X increases to the South, Y increases to the East

GetEpsgCode will return the SRID code of the CRS definition, returns 0 if such is not known

• An overload to the MgCoordinateSystemCatalog constructor will be added which will accept as its only parameter a string value which specifies the location of the dictionary folder.

Implications

Several MgCoordinateSystem interface methods will be deprecated. It is unlikely that they are used by any application as they do not really accomplish much. The deprecation is recommended as their function is incompatible with geodetic transformations as they will be implemented by CS-MAP RFC #2.

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, but no effect on the actual perfromance of the conversion process is expected.

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 produce 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.