| Home | Products | Issue Tracker | Service Providers | FAQ | Twitter | Download

# 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 http://code.google.com/apis/maps/documentation/reference.html#GTileLayer

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.

## References

- http://msdn.microsoft.com/en-us/library/bb545006.aspx

- http://code.google.com/apis/maps/documentation/reference.html#GTileLayer

- http://www.worldwindcentral.com/wiki/TileService