Via Virtual Earth

Roll Your Own Tile Server RSS

Microsoft Virtual Earth brings a whole new dimension to browser-based mapping, but it's possible to go well beyond the supplied API and get the same rich interaction with other kinds of maps, charts and graphical data.

This article explains how the tile server protocol works and how to re-point the Virtual Earth control at your own tile server. We've used this technique for a number of applications which I describe below.

Reverse Engineering

The Virtual Earth control is implemented using JavaScript. To understand how it works, we installed the Microsoft Internet Explorer Developer Toolbar. We visited http://local.live.com/ and turned on the "Show Image Paths" option. As we zoomed and panned the control, it was clear that the map is made up from separate bitmaps, each 256x256, which are tiled together. Each bitmap has a URL something like:

http://r2.ortho.tiles.virtualearth.net/tiles/r120202001322.png?g=22

There's nothing special about these URLs, they are just image references, but we needed to work out how the URL was constructed. Casey Chesnut's article "Creating a Virtual Earth plugin for NASA's WorldWind" proved to be very helpful.

At zoom level 1, the Earth is divided into 4 tiles numbered 0 to 3 thus:

These tiles are delivered from 4 separate servers, using the following URLs

http://r0.ortho.tiles.virtualearth.net/tiles/r0.png?g=1 
http://r1.ortho.tiles.virtualearth.net/tiles/r1.png?g=1 
http://r2.ortho.tiles.virtualearth.net/tiles/r2.png?g=1 
http://r3.ortho.tiles.virtualearth.net/tiles/r3.png?g=1

As you zoom in, the tiles are further subdivided, so when you move to zoom level 2, the upper right quarter divides into four tiles 10, 11, 12 and 13.

This indexing system continues recursively, allowing the earth's surface to be broken up into a grid, with each square represented by a number which we'll refer to as its quad key.

As you can see, server r0 always delivers top left squares, server r1 top right and so on. The significance of the "r" is road – other designators include "a" for aerial and "h" for hybrid. Aerial and hybrid images are delivered from a different set of tile servers.

Once you know the quad key, it's fairly straightforward to determine a bounding box that represents the grid square in units of longitude and latitude. Armed with this information, we set out to build a custom tile server and modify the JavaScript control to make use of it.

Example Code

Download and unzip the sample code associated with this article. Start Visual Studio 2005 and select File, Open, Web Site and load the project.

Now I'll walk you through some of the key functionality.

At zoom level 1 there are four tiles 1, 2, 3 and 4. At zoom level 19 there are 274,877,906,944 tiles. In theory we could create each tile and save it as an image using its quad key as the name, but we'd need a massive amount of disk space.

The solution is to build an HttpHandler that intercepts web requests for PNG files and builds the tiles on the fly.

VeHttpHandler.cs implements IHttpHandler. The ProcessRequest method calculates the bounding box and creates a tile bitmap which is then streamed back to the browser. This code is just a template example, so we just generate tiles that display their quad key number and the latitude and longitude of the northeast and southwest corners.

The HTTP Handler is installed using a simple addition to Web.config

<httpHandlers>
  <add verb="*" path="*.png" type="VeHttpHandler"/>
</httpHandlers>

This configures all requests for PNG files within this site to be directed to the VeHttpHandler class.

Changing the JavaScript Control

Having built a new tile server we need to modify the JavaScript to point to the new tile server in preference to the Microsoft servers.

We inspected the JavaScript code in MapControl.js

function ____downloadMapControl()
{ 
document.write("<script type='text/javascript' src='http://local.live.com/veapi.ashx'></script>");
};____downloadMapControl();

As you can see, all the clever JavaScript is being loaded from 'http://local.live.com/veapi.ashx'. This server page generates very compact JavaScript code – we downloaded it and set to work trying to understand it. With a little time and a pretty printer we began to understand where the tile server was being called.

if (wl==0) return "http://"+currentView.mapStyle+cell+".ortho.tiles.virtualearth.net/tiles/"
+currentView.mapStyle+key+(currentView.mapStyle==roadStyle?".png":".jpeg")
+"?g="+generations[currentView.mapStyle];

By changing this one line and using the revised JavaScript, we managed to redirect the Virtual Earth control to access our own server rather than the virtualearth.net tile servers.

if (wl==0) return "http://myserver.mycompany.com/tiles/"
+currentView.mapStyle+key+(currentView.mapStyle==roadStyle?".png":".jpeg")
+"?g="+generations[currentView.mapStyle];

Beware - changing the JavaScript is difficult – Visual Studio doesn't cope well with long lines, so we found it quicker and easier to use Emacs.

We saved this file as veapi.js and then modified mapcontrol.js to use this local copy.

function ____downloadMapControl()
{ 
  document.write("<script type='text/javascript' src='veapi.js'></script>");
};____downloadMapControl();

When you run the code, it should look something like this:

Quad keys are shown in red and the corners are marked with their calculated longitude and latitude.

This article assumes that you are running the web site from within Visual Studio. If you host the site within Internet Information Server (IIS) you must also configure PNG files to be handled by the aspnet_isapi.dll. Click on the Virtual Directory properties and under configuration, mappings add a new extension mapping like this.

Applications

The code supplied with this article is just a demonstrator to encourage developers to build new tile server applications. We've used this technique with great effect in some customer applications.

Active Web Solutions is a United Kingdom Hydrographic Office OEM for Admiralty ARCS charts. We hooked up our ARCS implementation to the tile server and we're using it with vessel tracking applications.

This same technique can also be used to access Open Geospatial Consortium (OGC) compliant map servers. It's also possible to do some limited image processing within the tile server. The following screenshot shows cloud cover satellite imagery overlaid on Virtual Earth.

Conclusions

By understanding and manipulating the Virtual Earth Tile Server protocol, it's possible to extend Virtual Earth functionality in new ways, outside the scope of the supplied SDK.

Obviously, Microsoft could choose to change the protocol and its implementation at any time, and this could break your application.

We hope that the Microsoft Virtual Earth team will consider extending the control to allow custom tile servers to be specified through the API.

*** UPDATE ***

Since this article was written, the Virtual Earth control has improved dramatically, and it now supports the ability to point to a tile server using map.AddLayer.

It’s no longer necessary to hack the JavaScript in the control, everything can be done via the API.

In fact the bulk of this article has now been subsumed into the MSDN documentation

Download

You can download the source code providing a basic tile server here.

Thanks

I'd like to thank Peter Williams at Microsoft - this work grew out of a discussion with him whilst we manned the Virtual Earth stand on the Microsoft Pavilion at MEDC Europe 2006.

Richard Prodger and Lewis Harvey both worked with me on the implementation and provided significant input, help and advice.

Article contributed by Rob Blackwell. Have you got something to contribute?