CS-Map RFC 2 - Redesign Datum Transformation Engine

This page contains an change request (RFC) for the CS-Map Open Source project. More CS-Map RFCs can be found on the RFCs page.

Status

RFC Template Version	(1.0)
Submission Date	Wed Jun 9 12:57:21 2010
Last Modified	Norm Olsen Timestamp
Author	Norm Olsen
RFC Status	draft
Implementation Status	pending
Proposed Milestone	13.1
Assigned PSC guide(s)
Voting History	(vote date)
+1
+0
-0
-1
no vote

Overview

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 I call 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.

Motivation

The "pivot datum" model has many limitations. This is especially true given the manner in which transformations driven by grid data files has been kludged into the model. Additionally, those geodetic transformations which required multiple geodetic transformation operations were hard coded, making it impossible for end users to add (for example) new grid file transformations. Further, we want to do away with the concept of Geodetic Data Catalogs which were kludged in 12 years ago to address what is now a non-existent problem.

Proposed Solution

The proposed solution requires the implementation of two new dictionaries and the modification of the use of an existing dictionary. To keep development costs within reason, there will be no changes in the format or interfaces provided for the four existing dictionaries. Obviously, changing the basic model upon which a major chunk of code is based requires some hefty changes. These are briefly described below:

• A datum definition becomes a simple definition of the existence of the datum and attaches some meta data to that definition. The "transformation to WGS84" portion of the existing datum definitions will be left unchanged and used for limited purposes such as WKT production.

• A new Geodetic Transformation dictionary will be implemented. The significant properties of a definition in this new dictionary will be:
  • identified by a unique 57 character name
  • defines a transformation method and associated parameters to convert from a specific source datum to a specific target datum
  • there may be several definitions which convert between the same datums
  • the number of supported parameters will be dramatically increased
  • the parameters in the definition will include references to grid data files as necessary
  • it is expected that a one to one correspondence between entries in this dictionary and EPSG "coordinate operations" shall exist

• A new Geodetic Path Dictionary will be implemented. An entry in this dictionary shall establish an ordered list and the direction (i.e. forward/inverse) of Geodetic Transformations necessary to accomplish a geodetic transformation from any datum to any other datum. The principle purposes of an entry in this dictionary shall be:
  • enables a means by which distributions and/or end users can specify a specific set of geodetic transformations where ambiguity exists
  • enables chaining of geodetic transformations where necessary (ATS77 -> NAD27 -> CSRS)

• All geodetic transformation code related to a grid data file (e.g. NTv2) will be refactored so as to be organized along file format lines as opposed to specific datums.

• The actual transformation code will be refactored into a system of protocol consistent functions similar to that used for projections. Thus, a geodetic equivalent of CS-MAP's projection table will be used to drive the redesigned system.

• Should funding and resources be sufficient, the redesign should enable the addition of some new geodetic transformation methods which were previously unsupportable.

• It is intended that the current CS_dtcsu (datum conversion setup) function operate as follows (given the source and target datums):
  • examine the Geodetic Path dictionary, and use any entry without further consideration
  • locate a unique geodetic transformation which converts from the source to target and use it if such exists
  • using a user definable pivot datum (or list thereof)(defaults to WGS84), locate a unique path from source to target and use if such exists
  • starting at the source and target, walk back to a common pivot datum providing there is no ambiguity
  • should any or all of these methods fail to produce a unique geodetic transformation path from source to target, the setup fails.

Implications

The proposed changes will not change the numeric results, nor will they change the performance of actual conversions. The intent of these changes is to remove the dependence upon the WGS84 "pivot datum" model thus enabling more flexibility in defining datum conversions without having to change library code. The performance of setting up a datum tranformation (CS_dtcsu) will be negatively impacted, but the actual calulation of a datum shift will remain about the same.

The proposed modifications do not include any changes to existing interfaces, and all existing dictionaries will remain intact. All foreseen interface changes are additions to the existing API. What does change, however, is the use of the Datum dictionary. The transformation information contained in the datum dictionary will now be pretty much ignored; used only in special cases such as producing the "TOWGS84" WKT element. Thus, existing applications which twiddle the datum dictionary entry and then perform transformations using such changes will be adversely affected; such a technique will no longer work.

Products using CS-MAP will need to distribute the two new dictionaries, and quite likely devise user interfaces to edit same. Also, existing user interfaces which examine, modify, and/or create entries in the Datums dictionary will need to be reworked.

User documentation of applications using CS-MAP will require substantial rewrites as the functionality of the Datum dictionary changes, and there are two completely new dictionaries which have been created expressly for the purpose of enabling users to edit them.

Test Plan

Substantial opportunities for regression are inherent in this effort. To insure against the development plan calls for the production of a data file of thousands of test data points to be generated using the existing library. It is necessary for this data file to exercise most all datum conversion techniques and all currently supported variations. A test module (such as the currently existing Console Test mdoule, Test #4, or something similar) will then be used to verify that there are no regressions in the actual calculations produced by the new and refactored code.

Other aspects of this redesign will be tested through normal quality assurance methods.

Funding/Resources

Funding, development, and initial quality assurance resources to be provided by Autodesk.