MS RFC 43: Direct tile generation for Google Maps and Virtual Earth API¶

Date:: 2008/04/08
Author:: Paul Ramsey
Contact:: pramsey at cleverelephant.ca
Last Edited:: 2008/05/02
Status:: Adopted on 2008/04/29 - Completed
Version:: MapServer 5.2

Overview¶

Providing a simple access API in the mapserv CGI can make using MapServer with the Google Maps and Virtual Earth user interfaces dramatically easier for new users.

Technical Solution¶

The GMaps API defines a GTileLayer which can be used as an overlay or base map. The GTileLayer supports a GTileLayerOption, tileUrlTemplate, which allows the TileLayer to be accessed using a simple URL pattern that substitutes Google’s x/y/z coordinates into the request:

http://host/tile?x={X}&y={Y}&z={Z}.png

See https://developers.google.com/maps/documentation/javascript/overview

For MapServer, the simple URL pattern will be:

http://host/cgi-bin/mapserv?map=/the.map&layers=foo,bar&mode=tile&tilemode=gmap&tile={X}+{Y}+{Z}

The change will add in new handling in the loadForm function for the mode, interface, version, x, y and z parameters. Like the WMS interface, GMaps API will require PROJ to be specified, and the existence of PROJECTION defines for all layers being accessed. Google X/Y/Z coordinates will be converted to «spherical mercator» coordinates and fed into the extent.

The result will make a Google-with-MapServer map as easy as:

var url = "http://host/cgi-bin/mapserv?";
    url += "map=/the.map&";
    url += "layers=parcels&";
    url += "mode=tile&";
    url += "tilemode=gmap&";
    url += "tile={X}+{Y}+{Z}";
var myLayer = new GTileLayer(null,null,null,
                             {
                              tileUrlTemplate:url,
                              isPng:true,
                              opacity:0.5
                             }
                            );
var map = new GMap2(document.getElementById("map"));
map.addOverlay(new GTileLayerOverlay(myLayer));

A Virtual Earth with MapServer map would look like:

var url = "http://host/cgi-bin/mapserv?";
    url += "map=/the.map&";
    url += "layers=parcels&";
    url += "mode=tile&";
    url += "tilemode=ve&";
    url += "tile=%4";
map = new VEMap("map");
map.LoadMap();
var tileSourceSpec = new VETileSourceSpecification( "myLayer", url );
tileSourceSpec.Opacity = 0.3;
map.AddTileLayer(tileSourceSpec, true);

A request with tilemode of «gmap» implies the following:

The «tile» parameter will be of the form: x y zoom
The output CRS will be set to «spherical mercator» (EPSG:900913)
The service bounds be global in extent. The top «zoom» level (0) will have 1 tile.
The «zoom» levels will run from 0 upwards
The «y» axis of the tile coordinates will run from top to bottom
The «x» axis of the tile coordinates will run from left to right
The output tiles will be 256x256 in size
Each zoom level will be related to parent and children by powers of two

A request with tilemode of «ve» implies the following:

The «tile» parameter will use the VE tile numbering scheme, for example «0312». See http://msdn.microsoft.com/en-us/library/bb545006.aspx for more details.
The output CRS will be set to «spherical mercator» (EPSG:900913)
The service bounds be global in extent. The top level will have 4 tiles (0, 1, 2, 3).
The output tiles will be 256x256 in size
Each zoom level will be related to parent and children by powers of two

The MapServer tile mode API will not explicitly attempt to address issues of meta-tiling or cross-tile labeling. However, the following steps will be taken to try to minimize these issues:

Future phases will render into a target slightly larger than the tile and then clip off the extra border pixels.

MapScript Implications¶

None. This affects only the CGI interface and mapserv CGI.

Files Affected¶

mapserv.c
maptile.c <new>
maptile.h <new>

Documentation will be updated to reflect the new feature
- MapServer CGI Reference
- MapServer Tile HOWTO <new>
Test suite will be updated to exercise the new features
- Frank Warmerdam has volunteered to do this

Backwards Compatibility Issues¶

None. This functionality is net new and requires no changes to existing behavior.

Bug ID¶

https://github.com/MapServer/MapServer/issues/2581

Voting History¶

Adopted on 2008/04/29 with +1 from SteveL, DanielM, JeffM, SteveW, TomK, PericlesN and AssefaY.