TileStache.Providers
index

The provider bits of TileStache.
 
A Provider is the part of TileStache that actually renders imagery. A few default
providers are found here, but it's possible to define your own and pull them into
TileStache dynamically by class name.
 
Built-in providers:
- mapnik (Mapnik.ImageProvider)
- proxy (Proxy)
- vector (TileStache.Vector.Provider)
- url template (UrlTemplate)
- mbtiles (TileStache.MBTiles.Provider)
- mapnik grid (Mapnik.GridProvider)
 
Example built-in provider, for JSON configuration file:
 
    "layer-name": {
        "provider": {"name": "mapnik", "mapfile": "style.xml"},
        ...
    }
 
Example external provider, for JSON configuration file:
 
    "layer-name": {
        "provider": {"class": "Module:Classname", "kwargs": {"frob": "yes"}},
        ...
    }
 
- The "class" value is split up into module and classname, and dynamically
  included. If this doesn't work for some reason, TileStache will fail loudly
  to let you know.
- The "kwargs" value is fed to the class constructor as a dictionary of keyword
  args. If your defined class doesn't accept any of these keyword arguments,
  TileStache will throw an exception.
 
A provider must offer one of two methods for rendering map areas.
 
The renderTile() method draws a single tile at a time, and has these arguments:
 
- width, height: in pixels
- srs: projection as Proj4 string.
  "+proj=longlat +ellps=WGS84 +datum=WGS84" is an example, 
  see http://spatialreference.org for more.
- coord: Coordinate object representing a single tile.
 
The renderArea() method draws a variably-sized area, and is used when drawing
metatiles. It has these arguments:
 
- width, height: in pixels
- srs: projection as Proj4 string.
  "+proj=longlat +ellps=WGS84 +datum=WGS84" is an example, 
  see http://spatialreference.org for more.
- xmin, ymin, xmax, ymax: coordinates of bounding box in projected coordinates.
- zoom: zoom level of final map. Technically this can be derived from the other
  arguments, but that's a hassle so we'll pass it in explicitly.
  
A provider may offer a method for custom response type, getTypeByExtension().
This method accepts a single argument, a filename extension string (e.g. "png",
"json", etc.) and returns a tuple with twon strings: a mime-type and a format.
Note that for image and non-image tiles alike, renderArea() and renderTile()
methods on a provider class must return a object with a save() method that
can accept a file-like object and a format name, e.g. this should word:
    
    provder.renderArea(...).save(fp, "TEXT")
 
... if "TEXT" is a valid response format according to getTypeByExtension().
 
Non-image providers and metatiles do not mix.
 
For an example of a non-image provider, see TileStache.Vector.Provider.

 
Modules
       
TileStache.Geography
PIL.Image
ModestMaps
TileStache.Vector
logging
os
urllib
urllib2

 
Classes
       
Proxy
UrlTemplate
Verbatim

 
class Proxy
    Proxy provider, to pass through and cache tiles from other places.
 
This provider is identified by the name "proxy" in the TileStache config.
 
Additional arguments:
 
- url (optional)
    URL template for remote tiles, for example:
    "http://tile.openstreetmap.org/{Z}/{X}/{Y}.png"
- provider (optional)
    Provider name string from Modest Maps built-ins.
    See ModestMaps.builtinProviders.keys() for a list.
    Example: "OPENSTREETMAP".
- timeout (optional)
    Defines a timeout in seconds for the request.
    If not defined, the global default timeout setting will be used.
 
 
Either url or provider is required. When both are present, url wins.
 
Example configuration:
 
{
    "name": "proxy",
    "url": "http://tile.openstreetmap.org/{Z}/{X}/{Y}.png"
}
 
  Methods defined here:
__init__(self, layer, url=None, provider_name=None, timeout=None)
Initialize Proxy provider with layer and url.
renderTile(self, width, height, srs, coord)

Static methods defined here:
prepareKeywordArgs(config_dict)
Convert configured parameters to keyword args for __init__().

 
class UrlTemplate
    Built-in URL Template provider. Proxies map images from WMS servers.
 
This provider is identified by the name "url template" in the TileStache config.
 
Additional arguments:
 
- template (required)
    String with substitutions suitable for use in string.Template.
 
- referer (optional)
    String to use in the "Referer" header when making HTTP requests.
 
- source projection (optional)
    Projection to transform coordinates into before making request
- timeout (optional)
    Defines a timeout in seconds for the request.
    If not defined, the global default timeout setting will be used.
 
More on string substitutions:
http://docs.python.org/library/string.html#template-strings
 
  Methods defined here:
__init__(self, layer, template, referer=None, source_projection=None, timeout=None)
Initialize a UrlTemplate provider with layer and template string.
 
http://docs.python.org/library/string.html#template-strings
renderArea(self, width, height, srs, xmin, ymin, xmax, ymax, zoom)
Return an image for an area.
 
Each argument (width, height, etc.) is substituted into the template.

Static methods defined here:
prepareKeywordArgs(config_dict)
Convert configured parameters to keyword args for __init__().

 
class Verbatim
    Wrapper for PIL.Image that saves raw input bytes if modes and formats match.
 
  Methods defined here:
__init__(self, bytes)
convert(self, mode)
crop(self, bbox)
image(self)
Return a guaranteed instance of PIL.Image.
save(self, output, format)

 
Functions
       
getProviderByName(name)
Retrieve a provider object by name.
 
Raise an exception if the name doesn't work out.