---

MapGuide RFC 127 - Change Coordinate System API (MgGeometry) to adopt changes proposed by CS-Map RFC6

This page contains a 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	(Date / Time submitted)
Last Modified	Andre Barth 09/25/2012
Author	Andre Barth
RFC Status	adopted
Implementation Status	pending
Proposed Milestone	2.5
Assigned PSC guide(s)	(when determined)
Voting History
+1	Bruce, Jackie, Haris, Trevor, Zac
+0
-0
-1
no vote

Overview

The CS-Map team (MapGuide's geospatial coordinate system engine) recently approved the RFC6. It proposes to split the geospatial coordinate system dictionary (*.CSD) files it is using into "system" (read-only) and "user-defined" (read/write) files. In order to be able to benefit from these enhancements, the MgCoordinateSystem API will have to be updated.

Motivation

The rationale behind changing the MgCoordinateSystem API is the same as for CS-Map's RFC6. Adding user-defined coordinate systems to CS-Map - which is possible through the MgCoordinateSystem API already today - would no longer delete and then rewrite entire *.CSD files. The installed CSD files could thus remain read-only. Also, having any custom geospatial coordinate system information separated from the default system files allows for much easier sharing, distribution and "installing" of these.

See ​http://trac.osgeo.org/csmap/wiki/CsMapRfc6's 'Motivation' section for additional details.

Proposed Solution

This RFC proposes to implement the following changes to the MgCoordinateSystem API in principle and initialization routines in general:

• Modify the initialization sequence of the MgCoordinateSystemCatalog class so it by default initializes the system dictionary path and also the user's coordinate system path. The latter defaults to [CLSID_LOCAL_APPDATA\Autodesk\User Geospatial Coordinate Systems] which is analog to the default dictionary path already implemented in the CCoordinateSystemCatalog class. This can be dynamically overridden by the MENTOR_USER_DICTIONARY_PATH variable. In either case, if the targeted directory doesn't exist or is invalid in any way, the entire MgCoordinateSystem API would behave as it does today. That is, any dictionary updates initiated through MapGuide's Coordinate System API will directly modify the root CSD files.
• Adapt the changes made due the implementation of RFC122 (​http://trac.osgeo.org/mapguide/wiki/MapGuideRfc122) so that the user's dictionary path can be configured through the serverconfig.ini file. The new, optional, parameter will be MentorUserDictionaryPath which can be configured in co-existence with the MentorDictionaryPath key.

New API to be added:

• CoordinateSystemCatalog::GetDefaultUserDictionaryDir(): Returns the default dictionary directory where user-defined geospatial coordinate system information is stored.
• CoordinateSystemCatalog::GetUserDictionaryDir(): Returns the current, if so configured or initialized, dictionary directory where user-defined geospatial coordinate system information is stored
• CoordinateSystemCatalog::SetUserDictionaryDir(): Sets the current dictionary directory where user-defined geospatial coordinate system information will be stored

Additional modifications:

• With RFC6 being implemented in CS-Map, the category API will be finalized, too. Currently, MapGuide uses its own code to access, i.e. read and write, the Category.CSD file. That should be changed so it uses - like all other CS-Map dictionary related implementation in MapGuide - the API provided by CS-Map directly.
• The various MgCoordinateSystem...Dictionary classes have to be changed, where appropriate, so they call into new CS-Map API. Note, that all these changes are internal only.

Implications

None. The additional directory where user-defined geospatial coordinate system information is to be stored is not created by default in any form. Instead, this feature has to be explicitly turned on by providing a valid target directory where custom geospatial coordinate system information can be stored. If that does not happen to be [CLSID_LOCAL_APPDATA\Autodesk\User Geospatial Coordinate Systems], MapGuide has to be configured in one of the following ways:

• setting the MENTOR_USER_DICTIONARY_PATH variable - OR -
• setting up the correct configuration in the serverconfig.ini file - OR -
• call the new SetUserDictionaryDir() API in an appropriate way

where none of the aforementioned is proposed to be implemented by this RFC. In particular, updating the installer is not covered by the changes proposed by this RFC.

Test Plan

The proposed changes will be tested at unit level, i.e. by enhancing existing (CPPUnit)tests or new tests where appropriate. Existing unit tests, specifically those related to the coordinate system, should naturally not be negatively affected by the changes implemented by this RFC.

In addition, the tests that have been run for RFC122 will have to be re-executed. See the Test Plan section for RFC 122.

Funding / Resources

Supplied by Autodesk.