Using KML SuperOverlays from TileCache

TileCache has support for KML superoverlays. For any TileCache layer for which the source data is EPSG:4326, the KML Service provides GroundOverlay data with LevelOfDetail NetworkLinks to deeper levels of data.

How to Use

In order to display the KML data, there are two options:

• Create a link to a single tile which contains your tile of interest. The tiling scheme for your data determines what the tile identifiers are. Tiles match those used by TMS.
• Create a service that assembles multiple KML tile links into a single KML document. This service should use NetworkLinks to point to other KML files to include. This service does not need to be comple: it simply needs to create small KML documents which include only a small number of networklinks, needed to link the user to an area.

A simple document which does this – for a given layername – is included in doc/examples/overlay.kml.

This sample document is designed to make available an entire worldwide set of tiles via TileCache: typically, one would create a more complex KML generator that would, for example, specify a LookAt tag as well, so that a user could open the data in Google Earth based on where they were looking. Also, this KML file will let them zoom out – but it means that the server does need to generate (possibly many) KML documents to get the viewer to where they want to be, because the KML Client will need to trawl its way through the entire Pyramid down to where the user is viewing. However, the image data is not included with the KML document, so this should be a lightweight server side operation: it’s just somewhat slow to do many round trips, in general, so specifying (as a top level) some reasonaable compromise between the whole world and the targeted viewing plane might make sense.

Finding KML/Tile URLS

TileCache KML documents are based around the TMS URL scheme. This means that for a TMS tile:

http://tile.openaerialmap.org/tiles/1.0.0/openaerialmap/0/0/0.png

the corresponding KML document is

http://tile.openaerialmap.org/tiles/1.0.0/openaerialmap/0/0/0.kml

By default, TileCache uses a ‘whole world’ extent, split into two tiles: western hemisphere and eastern. This means that to get the whole world into Google Earth, you would need to include links to 0/0/0.kml and 0/0/1.kml.

TileCache can calculate a tile z/x/y from a bounding box using the getCell function on a layer. To use this:

>>> import TileCache.Service
>>> s = TileCache.Service.load("tilecache.cfg")
>>> s.layers 
{'basic': <TileCache.Layers.WMS.WMS object at ...>}
>>> s.layers['basic'] 
<TileCache.Layers.WMS.WMS object at ...>
>>> basic = s.layers['basic']
>>> basic.getCell((-180,-90,0,90))
(0, 0, 0)
>>> cell = basic.getCell((-10,-90,12,-80), exact=False)
>>> cell
(8, 0, 3)

Once you’ve done this, you can then use Python to construct a KML doc for the tile:

>>> from TileCache.Layer import Tile
>>> tile = Tile(basic, cell[0], cell[1], cell[2])
>>> from TileCache.Services.KML import KML
>>> kml = KML(s)
>>> doc = kml.generate_kml_doc(tile, base_path="http://example.com/tilecache.cgi", include_wrapper=False)
>>> len(doc)
2546
>>> doc[550:600]
'\n    </GroundOverlay>\n    <NetworkLink>\n      <nam'