Using MapGuide Overlays with Commercial Map Service Layers
Commercial tiled map layers can be used as base layers within MapGuide flexible layouts, provided you make some modifications to your application and map projection. Please note that the commercial mapping API providers referenced in this document have terms and conditions attached to the use of their services. Please review those terms before proceeding, especially if your intended application will not be both publicly accessible and free.
What you will need
- a commercial service api key
- A MapGuide Open Source 2.1 or AutoDesk MapGuide Enterprise 2010 Server.
- Fusion svn checkout in place of the bundled fusion installation.
- MapGuide Maestro or familiarity with MapGuide's MapAgent utility.
- Sheboygan Sample data set
optional:
Getting Started
You will need to get a free key from a commercial mapping api provider. For Google maps, you can obtain one here:
http://code.google.com/apis/maps/signup.html
After submitting the request, you should get a sample script tag like this:
<script src="http://maps.google.com/maps?file=api&v=2&sensor=false&key=<your key here>" type="text/javascript"></script>
Note that the sensor argument has been set to false.
Microsoft's Virtual Earth service can be used by including this script tag:
<script src='http://dev.virtualearth.net/mapcontrol/mapcontrol.ashx?v=6.1'></script>
Finally, Yahoo's service requires you to obtain a key from:
http://developer.yahoo.com/maps
You should get a script tag that looks like
<script src="http://api.maps.yahoo.com/ajaxymap?v=3.0&appid=<your key here>"></script>
If you haven't already done so, use the MapGuide MapAdmin page to load the Sheboygan sample data which will be used as an example overlay.
Step 1: Modify the application html
You can add a commercial base layer to any fusion application, but as an example we will modify the sample template that comes with MapGuide Open Source.
You can find the template's index.html file in
<MapGuide Install Directory>/WebServerExtensions/www/fusion/templates/mapguide/standard/
- Use a text editor to open the file and insert the script tag from the previous step right before the fusion tag:
<script type="text/javascript" src="../../../lib/fusion.js"></script>
Step 2: Update the projection information in the MapDefinition
Since the Google, Microsoft and Yahoo mapping systems all use the same modified Mercator projection, any overlaid MapGuide data needs to be transformed into that coordinate system. MapGuide can reproject vector data on the fly, meaning the original sample set can be used provided that we modify the MapDefinition to use the Mercator output projection.
- Using MapGuide Maestro, connect to the MapGuide server and make a duplicate of the /Samples/Sheboygan/Maps/Sheboygan MapDefinition resource using the Edit menu copy and paste commands. Rename the copy to Sheboygan-m.
- Double click on the new file to open it and then click on the button next to 'Coordinate System' to bring up the Select Coordinate System dialog. Click the 'Type WKT code' radio button and then paste in the following definition:
PROJCS["Popular Visualisation CRS / Mercator",GEOGCS["Popular Visualisation CRS",DATUM["Popular_Visualisation_Datum",SPHEROID["Popular Visualisation Sphere",6378137,0,AUTHORITY["EPSG","7059"]],TOWGS84[0,0,0,0,0,0,0],AUTHORITY["EPSG","6055"]],PRIMEM["Greenwich",0,AUTHORITY["EPSG","8901"]],UNIT["degree",0.01745329251994328,AUTHORITY["EPSG","9122"]],AUTHORITY["EPSG","4055"]],UNIT["metre",1,AUTHORITY["EPSG","9001"]],PROJECTION["Mercator_1SP"],PARAMETER["central_meridian",0],PARAMETER["scale_factor",1],PARAMETER["false_easting",0],PARAMETER["false_northing",0],AUTHORITY["EPSG","3785"],AXIS["X",EAST],AXIS["Y",NORTH]]
- Close the dialog box and then modify the Initial Map View coordinates so they make sense in the new projection:
Lower left X: -9774168, Y: 5415995 Upper right X: -9754637, Y: 5434757
If you need to determine coordinates for your own data sets, you can convert them online using Proj4js. Pick the 'GOOGLE' CRS from the 'dest' list, enter your coordinates and click transform.
You can use AutoDesk MapGuide Studio for the above steps by duplicating the MapDefinition as above but picking 'Save as XML' from the file menu instead. The saved file can be edited in a text editor but you will then need to use the MapAgent interface to perform a SetResource operation with the modified xml file. Studio does not have the correct projection built in and there is no way to add it to the MapDefinition from application's user interface. MapAgent can also be used to issue a GetResource request to retrieve the initial xml file.
Step 3: Add a Google layer to the ApplicationDefinition
- In the same folder as the index.html file, locate the ApplicationDefinition.xml file and open it in your text editor. You may want to make a backup copy of the file with a different name. In the original file, replace the MapSet tag contents with the following block:
<MapGroup id="googleBase"> <Map> <Type>Google</Type> <Extension> <ResourceId>google</ResourceId> </Extension> </Map> </MapGroup>
- If you don't like the default Google map type, you can add an <Options> tag to the Google layer to change it:
G_NORMAL_MAP (default) : street map G_PHYSICAL_MAP : terrain map G_HYBRID_MAP : combined satellite and streets G_SATELLITE_MAP : satellite map
i.e.
<Map> <Type>Google</Type> <Extension> <ResourceId>google</ResourceId> <Options> <type>G_PHYSICAL_MAP</type> </Options> </Extension> </Map>
- You can use the same approach with Virtual Earth (be careful - these are case sensitive):
Road (default) : street map Shaded : terrain map Hybrid : combined satellite and streets Aerial : satellite map
- Or Yahoo Maps:
YAHOO_MAP_REG (default) : street map YAHOO_MAP_SAT : satellite map YAHOO_MAP_HYB : combined satellite and streets
- Add a second <Map> tag to your map group after the google <Map>. Take care that it remains within the <MapGroup> tags. The useOverlay tag makes the layer's background transparent so the base layer can be seen.
<Map> <Type>MapGuide</Type> <SingleTile>true</SingleTile> <Extension> <Options> <isBaseLayer>false</isBaseLayer> <useOverlay>true</useOverlay> <projection>EPSG:900913</projection> </Options> <ResourceId>Library://Samples/Sheboygan/Maps/Sheboygan-m.MapDefinition</ResourceId> </Extension> </Map>
Note that the commercial layer must be the base layer so any overlays must have the isBaseLayer: false option set. The projection tag is needed so that OpenLayers will initialize the layer in the same projection as the base map. You can also pass other OpenLayers layer options in the Options tag. For example, <opacity>0.8</opacity> creates a semi-transparent appearance.
- Load the template in a browser: http://localhost:8008/mapguide/fusion/templates/mapguide/standard/
To use the Microsoft Virtual Earth or Yahoo mapping services as base maps, remove the google <Map> block from your ApplicationDefinition and replace it with
<Map xsi:type="WMSLayerType">
<Type>VirtualEarth</Type>
<Extension>
<ResourceId>ve</ResourceId>
</Extension>
</Map>
for Virtual Earth or
<Map xsi:type="WMSLayerType">
<Type>Yahoo</Type>
<Extension>
<ResourceId>yahoo</ResourceId>
</Extension>
</Map>
for Yahoo.
- By default, the map will load with global extent (showing the entire world) because the commercial layer is the base layer. To specify a desired initial view, add an additional xml block to the MapGroup alongside the individual Map tags:
<InitialView>
<MinX>-9774168</MinX>
<MinY>5415995</MinY>
<MaxX>-9754637</MaxX>
<MaxY>5434757</MaxY>
</InitialView>
Support for these layer types is a new addition to Fusion 2.0 so you may encounter compatibility issues. Please help the project by reporting them to the fusion-dev mailing list or filing a bug in the fusion trac instance.
