Building Your Own Tile Server

Although Bing Maps provides good map and aerial coverage of most areas, you are still the best authority on data availability and data quality for your own needs. Whether you have advanced imagery, engineering plans, or transportation maps, serving this information to users is often a challenging problem. Fortunately, you can take advantage of Bing Maps tile layers to create an imagery server that integrates fully with the navigation methods, data and tools built into Bing Maps.

The Bing Maps AJAX Control 6.3 SDK is built on a foundation of tiles. Each tile represents a particular view of a rectangular piece of information. Bing Maps tile sets can be used immediately for regular map views, aerial views bird's eye views, and hybrid map views. However, the tiling system can also be used to serve up custom geospatially-oriented information. In other words, you can build your own tiles and "roll your own tile server" so that your users can see not only the built in maps, but your specific information.

This article examines the techniques needed to serve up custom image data using Bing Maps technology.

Note

Microsoft neither recommends nor supports accessing the Bing Maps tile servers directly. The tile server paths are subject to change at any time.

Generating Tiles

The most difficult challenge in building a custom tile server is matching up custom data with the Bing Maps map data. This process is challenging due to the related problems of projection and registration. That is, images must be stretched to fit a Bing Maps Mercator projection, and the latitude and longitude boundaries of images must be determined.

Understanding Bing Maps Tiles

Bing Maps divides up each map and map style into a set of 256 pixel x 256 pixel tiles. The tiles are stitched together according to a naming scheme that is based on the images position and relative degree of resolution. Each tile is numbered according to where it is with respect to a 4 square quadrant system.

The Naming Scheme

You can easily find the name of specific tiles by going to bing.com and using either the Internet Explorer DevToolBar, or FireFox's Firebug tool, and turning on image paths. If you look at a Bing Maps map at the highest level, you will see four images representing the 4 256x256 tiles that make up the projection of the Earth.

Bb545006.64c1036f-fb24-4f93-8310-4b7ec9536c3f(en-us,MSDN.10).jpg

Figure 1 Tile Numbering Scheme

As you zoom in, each of these top level tiles is further divided into 4 tiles. The tile naming scheme is therefore as follows:

  • A letter code indicating style (r - road, a - aerial, h - hybrid, o - bird's eye, b - bird's eye hybrid)

  • A series of "quadrant" numbers. The numbers will always be between 0 and 3 (inclusive) and represent the relative position of the tile. The more numbers in the sequence, the greater the zoom level.

For example, a "max zoom" hybrid image of Qwest Field (where the Seattle Seahawks play) is numbered h0212300302202032001. This would indicate that the image is 19 layers deep, in the upper right corner of its quadrant.

Bounding Tiles

Finding the latitude and longitude boundaries of a tile is a bit more difficult. The process consists of breaking apart the quadrant key naming scheme and recursively calculating the latitude and longitude. This process is beyond the scope of this article.

Preparing Your Own Tiles

To prepare custom tiles, convert an image into 256x256 pixel chunks and create a meaningful naming scheme. You will also have to decide how you want to host your images. To follow Microsoft's naming scheme, register your images in relation to to the Bing Maps tiles. Custom tiles must share bounding boxes with Bing Maps tiles.

MapCruncher - A Short Cut

If the image is large, consider using MapCruncher. MapCruncher is a desktop application that maps registration points on an image to Bing Maps locations. Once enough registration points have been made from an image to a Bing Maps location, MapCruncher automatically reshapes the image and divides it into tiles that match the Bing Maps tiles. MapCruncher even builds a Web page showing the custom tiles on top of Bing Maps.

Adding a Custom Tile Layer to Bing Maps

Once custom tiles have been created, using them in a Bing Maps map is straightforward. If the custom tiles are named according to the Bing Maps naming scheme, specify the source of the custom tiles by , and then add the source to the map by . If the custom tiles are not named according to the Bing Maps naming scheme, create a custom naming scheme by before creating the VETileSourceSpecification object.

Specifying a Custom Tile Source

To specify a custom tile source, creating a new VETileSourceSpecification object containing the tile source information, as follows.

var bounds = [
   new VELatLongRectangle(new VELatLong(49,-123),
                          new VELatLong(47,-121))];
var layerID = "lidar";
var tileSource = 
   "https://www.microsoft.com/maps/isdk/ajax/layers/lidar/%4.png";
var tileSourceSpec = 
   new VETileSourceSpecification(layerID, tileSource);
tileSourceSpec.NumServers = 1;
tileSourceSpec.Bounds     = bounds;
tileSourceSpec.MinZoom    = 10;
tileSourceSpec.MaxZoom    = 18;
tileSourceSpec.Opacity    = 0.5
tileSourceSpec.ZIndex     = 100

Listing 1 Defining a Tile Layer

The VETileSourceSpecification has several important properties.

  • ID - The ID field simply identifies a layer, and can be any string value. Pass this value in to the constructor as the constructor verifies that the ID value is unique.

  • TileSource - The tile source contains a URL that points to the servers that are going to host the tiles. There are three place holder variables within this URL.

    • %1 - This parameter is a place holder for map style. If the tile images start with 'a', 'r', or 'h', and the source URL contains %1, the map only displays tiles if the view style matches the image names. If this parameter is omitted, then tiles are displayed on every view type.

    • %2 - This parameter is a place holder for the server number if there is more than one server. Use this place holder if the tiles are hosted on multiple severs (numbered sequentially). Bing Maps will make requests to each server in a round-robin fashion.

    • %4 - The last parameter is a place holder for the default Bing Maps numbering scheme. Use this if the custom tiles follow the Bing Maps numbering scheme.

    • As with the ID parameter, pass the Tile Source into the constructor as the constructor ensures that the source is properly formed and accessible. If the source is invalid, the constructor throws an exception.

  • NumServers - Set this parameter to 1 unless the %2 place holder is in the source path. This number represents the number of server paths used to host the custom tiles. The servers must be named sequentially starting from 0 (eg. TileServer0, TileServer1, TileServer2).

  • Bounds - Bounds represents a VELatLongRectangle defining the borders of the area where the custom tiles exist. If a user pans into this area, the custom tiles appear. If the user moves out of the area, no custom tiles are requested.

  • MinZoom, MaxZoom - These parameters define the minimum and maximum zoom levels for displaying custom tiles. If the user moves outside the zoom range, no custom tiles appear. The zoom range is from 1 (least zoomed in) to 19 (most zoomed in).

  • Opacity - Opacity determines whether or not a layer completely obscures the underlying map (1.0) or is completely transparent (0.0). Adjust this value depending on the relative contrast of a tile compared to the underlying map style.

  • ZIndex - The ZIndex is a relative indicator of the "height" of a custom layer compared to other layers. To overlay multiple layers, set the ZIndex values so that the layers appear in the desired order. This is usually only an issue when opacity is specified dynamically. If all layers are opaque, the one with the largest ZIndex appears and all other layers are obscured.

Creating a Custom Naming Scheme

To use a custom naming scheme, specify a different set of parameters, as the NumServers and TileSource parameters are ignored. Instead, set the GetTilePath() property to point to a JavaScript function. This JavaScript function receives a VETileContext parameter which provides the x and y position of the center of the tile and the zoom level. The function must convert these values into a fully-qualified path.

Note that this system only works for 2D tile layers. To see layers in 3D, use the Bing Maps naming scheme.

Adding the Tile Layer to a Bing Maps Map

To add a tile layer to a Bing Maps map, use the VEMap.AddTileLayer method to add a The VETileSourceSpecification object to the map, as follows.

map.AddTileLayer(tileSourceSpec, true);

Listing 2 Adding the Layer

The second parameter indicates that the tile layer should be visible as soon as it is loaded. If the parameter is false, the layer is not be visible until the ShowTileLayer method is called.

A third parameter can be included to specify a callback function. The callback function is invoked when the layer has successfully loaded. Use this mechanism if the tile layers are large, complex, or slow to load.

Manipulating Layers

Once a layer is in place, manipulate it by calling the ShowTileLayer, HideTileLayer and DeleteTileLayer methods. Each of these methods takes the Layer ID as a parameter. For instance, to hide the layer defined in Listing 1, use the following code:

map.HideTileLayer('lidar');

Listing 3 Hiding a Layer

Conclusion

Although Bing Maps provides an extensive set of maps, there is often a need to add custom imagery. Using this article as a starting point, you should be able to work through the challenges of registering your image to Bing Maps, dividing up an image into tiles, deciding on an appropriate naming scheme, and adding a custom tile source to a Bing Maps map.

This article was written by Robert McGovern MVP (Bing Maps/MapPoint) from Infusion Development. Some of the content was drawn directly from a Bing Maps article by Rob Blackwell.