MapGuide tidbits: Updating coordinate system dictionaries

DISCLAIMER: This procedure is unsupported. Use at your own risk.

The coordinate system dictionaries that ship with a MapGuide installation are effectively coupled with that particular version of MapGuide. Should support for new coordinate systems, datums, etc be introduced into CS-Map, ideally you should upgrade your version of MapGuide to one that uses a version of CS-Map that incorporates these new definitions.

However, since the next major of version of MapGuide will still be some time away and the next immediate release (3.1.2) is a minor release, which we're being conservative with regards to updates to upstream libraries, it means there's a potential long wait to be able to use some coordinate systems, datums, etc if they were added to CS-Map since our last major release of MapGuide.

So if you can't afford to wait, you can try this method of updating your coordinate system dictionaries. We assume you are using the current latest version of MapGuide (3.1.1).

Firstly, use a subversion client to check out the current CS-Map source code from trunk.

svn co http://svn.osgeo.org/metacrs/csmap/trunk

Once checked out, you will need to build the CS_Comp.exe dictionary compiler. To build this dictionary compiler, open the OpenSource.sln file (under any VC* folder) in Visual Studio and build. If you do not have Visual Studio to build this executable, you can download this pre-compiled binary.

Either way, make sure the CS_Comp.exe is in your Dictionaries folder.

Then open a command prompt, navigate to this folder and run the following command:

CS_Comp.exe /b /c . .

You should see output like this

This produces a whole series of files with a .csd extension

Now locate the Dictionaries folder of your MapGuide installation and copy all the .csd files and NameMapper.csv into it, overwriting all existing files. In case things go wrong, you should make a backup of the existing files first.

Some new definitions may require new supporting grid files (eg. These files are required for the new Australian GDA2020 datum). Such files have to be copied across as well.

Once you have copied these files over, (re)start your MapGuide Server.

Now there's 2 ways to verify the new coordinate systems, datums, etc are in place.

Firstly, in MapGuide Maestro, when bringing up the coordinate system picker. You should see newer definitions for your particular country.

Secondly, as a sanity test you write a simple PHP script that verifies you can transform coordinates into these new coordinate systems. Here's an example script:

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21

<?php MgInitializeWebTier(dirname(__FILE__)."./webconfig.ini"); $csFactory = new MgCoordinateSystemFactory(); $srcCs = $csFactory->CreateFromCode("LL84"); //Map Grid Australia, Zone 55, with new GDA2020 datum $dstCs = $csFactory->CreateFromCode("MGA/20-55"); $xform = $csFactory->GetTransform($srcCs, $dstCs); $srcX = 144.9674853; $srcY = -37.808262; $txCoord = $xform->Transform($srcX, $srcY); echo "Lng: $srcX, Lat: $srcY"; echo "<br />"; echo "X: " . $txCoord->GetX() . ", Y: " . $txCoord->GetY(); ?>

Save this and when you run it, if it prints out the transformed coordinates then your new coordinate systems should be working.

Some caveats

The key thing to watch out for here is whether a new coordinate system, datum, etc requires only a data file update or it requires both a data file update and an engine update

A new definition that only requires a data file update, will only touch one or more of the following files:

• Any file with an .asc extension
• NameMapper.csv

For example, this commit to CS-Map that introduces some new coordinate systems only touches the aforementioned data files.

New definitions that require engine updates are indicated by commits that also involve modifications to one or more *.c source files.

Such definitions would require building MapGuide against a newer version of CS-Map with these engine changes, which only happens with every new major release.

Based on my cursory testing, definitions that only require a data file update can be incorporated into your current MapGuide install with this approach. Otherwise, such a definition is unlikely to be usable until we release the next major version of MapGuide.

How would you know if a given coordinate system, datum, etc only requires a data file update or both? The only thing I can suggest is to hit up the CS-Map trac instance and search for commits involving your coordinate system, datum, etc and see if they change the above aforementioned files.