.. _rfc43:

=======================================================================
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
:Id: $Id$

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 :ref:`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
------

* http://trac.osgeo.org/mapserver/ticket/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