TileStache is a Python-based server application that can serve up map tiles based on rendered geographic data. You might be familiar with TileCache the venerable open source WMS server from MetaCarta. TileStache is similar, but we hope simpler and better-suited to the needs of designers and cartographers.
This document covers TileStache version 1.32.0.
See also detailed module and class reference.
TileStache URLs are based on a simplified TMS scheme:
/{layer name}/{zoom}/{column}/{row}.{extension}
An example tile URL might look like this:
http://example.org/path/tile.cgi/streets/12/656/1582.png
For JSON responses such as those from the Vector provider, URLs can include an optional callback for JSONP support:
http://example.org/path/tile.cgi/streets/12/656/1582.json?callback=funcname
Interactive, slippy-map previews of tiles are also available:
/{layer name}/preview.html
TileStache.getTileGet a type string and tile binary for a given request layer tile.
Arguments to getTile:
Core.Layer to render.
ModestMaps.Core.Coordinate corresponding to a single tile.
Return value of getTile is a tuple containing a mime-type string
such as "image/png" and a complete byte string representing the
rendered tile.
See TileStache.getTile documentation for more information.
TileStache.requestHandlerGenerate a mime-type and response body for a given request. This is the function to use when creating new HTTP interfaces to TileStache.
Arguments to requestHandler:
TileStache.Config.Configuration.
Return value of requestHandler is a tuple containing a mime-type string
such as "image/png" and a complete byte string representing the
rendered tile.
See TileStache.requestHandler documentation for more information.
We currently provide three scripts for serving tiles: one for a WSGI-based
webserver, one for a CGI-based webserver, and one for Apache mod_python.
TileStache comes with a WSGI application and a Werkzeug web server. To use the built-in server, run tilestache-server.py, which (by default) looks for a config file named tilestache.cfg in the current directory and then serves tiles on http://127.0.0.1:8080/. Check tilestache-server.py --help to change these defaults.
Alternatively, any WSGI server can be pointed at an instance of TileStache.WSGITileServer. Here’s how to use it with gunicorn:
$ gunicorn "TileStache:WSGITileServer('/path/to/tilestache.cfg')"
See
TileStache.WSGITileServer
documentation for more information.
Using TileStache through CGI supports basic tile serving, and is useful for simple testing and low-to-medium traffic websites. This is a complete, working CGI script that looks for configuration in a local file called tilestache.cfg:
#!/usr/bin/python import os, TileStache TileStache.cgiHandler(os.environ, 'tilestache.cfg', debug=True)
See
TileStache.cgiHandler
documentation for more information.
Using TileStache through mod_python improves performance by
caching imported modules, but must be configured via the Apache webserver
config. This is a complete example configuration for a webserver publishing
tiles configured by a file in /etc:
<Directory /var/www/tiles> AddHandler mod_python .py PythonHandler TileStache::modpythonHandler PythonOption config /etc/tilestache.cfg </Directory>
See
TileStache.modPythonHandler
documentation for more information.
TileStache configuration is stored in JSON files, and is composed of two main top-level sections: "cache" and "layers". There are examples of both in this minimal sample configuration:
{
"cache": {"name": "Test"},
"layers": {
"ex": {
"provider": {"name": "mapnik", "mapfile": "style.xml"},
"projection": "spherical mercator"
}
}
}
A Cache is the part of TileStache that stores static files to speed up future
requests. A few default caches are shown here, with additional cache classes
defined in
TileStache.Goodies.Caches
Simple cache that doesn’t actually cache anything.
Activity is optionally logged, though.
Example configuration:
{ "cache": { "name": "Test", "verbose": True }, "layers": { … } }
Test cache parameters:
See TileStache.Caches.Test documentation for more information.
Caches files to disk.
Example configuration:
{ "cache": { "name": "Disk", "path": "/tmp/stache", "umask": "0000", "dirs": "portable", "gzip": ["xml", "json"] }, "layers": { … } }
Disk cache parameters:
If your configuration file is loaded from a remote location, e.g. http://example.com/tilestache.cfg, the path must be an unambiguous filesystem path, e.g. "file:///tmp/cache".
See TileStache.Caches.Disk documentation for more information.
Caches tiles to multiple, ordered caches.
Multi cache is well-suited for a speed-to-capacity gradient, for example a combination of Memcache and S3 to take advantage of the high speed of memcache and the high capacity of S3. Each tier of caching is checked sequentially when reading from the cache, while all tiers are used together for writing. Locks are only used with the first cache.
Example configuration:
{ "cache": { "name": "Multi", "tiers": [ { "name": "Memcache", "servers": ["127.0.0.1:11211"] }, { "name": "Disk", "path": "/tmp/stache" } ] }, "layers": { … } }
Multi cache parameters:
See TileStache.Caches.Multi documentation for more information.
Caches tiles to Memcache, requires python-memcached.
Example configuration:
{ "cache": { "name": "Memcache", "servers": ["127.0.0.1:11211"], "revision": 0 }, "layers": { … } }
Memcache cache parameters:
See TileStache.Memcache.Cache documentation for more information.
Caches tiles to Amazon S3, requires boto (2.0+).
Example configuration:
{ "cache": { "name": "S3", "bucket": "<bucket name>", "access": "<access key>", "secret": "<secret key>" }, "layers": { … } }
S3 cache parameters:
See TileStache.S3.Cache documentation for more information.
New caches with functionality that’s not strictly core to TileStache first appear in TileStache.Goodies.Caches.
Cache that stores a limited amount of data. This is an example cache that uses a SQLite database to track sizes and last-read times for cached tiles, and removes least-recently-used tiles whenever the total size of the cache exceeds a set limit. See TileStache.Goodies.Caches.LimitedDisk for more information.
A Layer represents a set of tiles in TileStache. It keeps references to providers, projections, a Configuration instance, and other details required for to the storage and rendering of a tile set.
Example layer configuration:
{ "cache": …, "layers": { "example-name": { "provider": { … }, "metatile": { … }, "preview": { … }, "stale lock timeout": …, "cache lifespan": …, "projection": …, "write cache": …, "bounds": { … }, "allowed origin": …, "maximum cache age": …, "redirects": …, "jpeg options": …, "png options": … } } }
The public-facing URL of a single tile for this layer might look like this:
http://example.com/tilestache.cgi/example-name/0/0/0.png
Shared layer parameters:
A Provider is the part of TileStache that stores static files to speed up
future requests. A few default providers are shown here, with additional
provider classes defined in
TileStache.Goodies.Providers
Built-in Mapnik provider, renders map images from Mapnik XML files.
Example Mapnik provider configuration:
{ "cache": { … }. "layers": { "roads": { "provider": { "name": "mapnik", "mapfile": "style.xml" } } } }
Mapnik provider parameters:
See TileStache.Mapnik.ImageProvider for more information.
Proxy provider, to pass through and cache tiles from other places.
Example Proxy provider configuration:
{ "cache": { … }. "layers": { "roads": { "provider": { "name": "proxy", "url": "http://tile.openstreetmap.org/{Z}/{X}/{Y}.png" } } } }
Proxy provider parameters:
ModestMaps.builtinProviders.keys() for a list. Example:
"OPENSTREETMAP".
See TileStache.Providers.Proxy for more information.
Provider that returns vector representation of features in a data source.
Currently two serializations and three encodings are supported for a total of six possible kinds of output with these tile name extensions:
Example Vector provider configurations:
{ "cache": { … }. "layers": { "vector-postgis-points": { "provider": {"name": "vector", "driver": "PostgreSQL", "parameters": {"dbname": "geodata", "user": "geodata", "table": "planet_osm_point"}} }, "vector-shapefile-lines": { "provider": {"name": "vector", "driver": "shapefile", "parameters": {"file": "oakland-uptown-line.latlon.shp"}, "properties": {"NAME": "name", "HIGHWAY": "highway"}} }, "vector-sf-streets": { "provider": {"name": "vector", "driver": "GeoJSON", "parameters": {"file": "stclines.json"}, "properties": ["STREETNAME"]} } } }
Vector provider parameters:
See TileStache.Vector for more information.
Templated URL provider, to pass through and cache tiles from WMS servers.
Example UrlTemplate provider configuration:
{ "cache": { … }. "layers": { "roads": { "provider": { "name": "url template", "template": "http://example.com/?bbox=$xmin,$ymin,$xmax,$ymax" } } } }
UrlTemplate provider parameters:
See TileStache.Providers.UrlTemplate for more information.
Provider that reads stored images from MBTiles tilesets.
Example MBTiles provider configuration:
{ "cache": { … }. "layers": { "roads": { "provider": { "name": "mbtiles", "tileset": "collection.mbtiles" } } } }
MBTiles provider parameters:
See TileStache.MBTiles.Provider for more information.
Built-in Mapnik UTF Grid provider, renders JSON raster objects from Mapnik 2.0+.
Example Mapnik Grid provider configurations:
{ "cache": { … }. "layers": { "one-grid": { "provider": { "name": "mapnik grid", "mapfile": "style.xml", "layer index": 1 }, } "two-grids": { "provider": { "name": "mapnik grid", "mapfile": "style.xml", "layers": [ [2, ["population"]], [0, ["name", "population"]] ] } } } }
Mapnik Grid provider parameters:
See TileStache.Mapnik.GridProvider for more information.
New providers with functionality that’s not strictly core to TileStache first appear in TileStache.Goodies.Providers.
Grid rendering for TileStache. UTM provider draws gridlines in tiles, in transparent images suitable for use as map overlays. See TileStache.Goodies.Providers.Grid for more information.
Provider that returns GeoJSON data responses from PostGIS queries. This is an example of a provider that does not return an image, but rather queries a database for raw data and replies with a string of GeoJSON. For example, it’s possible to retrieve data for locations of OpenStreetMap points of interest based on a query with a bounding box intersection. See TileStache.Goodies.Providers.PostGeoJSON for more information.
Provider that returns GeoJSON data responses from Solr spatial queries. This is an example of a provider that does not return an image, but rather queries a Solr instance for raw data and replies with a string of GeoJSON. See TileStache.Goodies.Providers.SolrGeoJSON for more information.
Layered, composite rendering for TileStache. See TileStache.Goodies.Providers.Composite for more information.
Requests for tiles have the side effect of running
osm2pgsql to populate
a PostGIS database of OpenStreetMap data from a remote API source. It would be
normal to use this provider outside the regular confines of a web server,
perhaps with a call to tilestache-seed.py governed by a cron job or
some other out-of-band process. See
TileStache.Goodies.Providers.MirrorOSM
for more information.
A Projection defines the relationship between the rendered tiles and the underlying geographic data. Generally, just one popular projection is used for most web maps, "spherical mercator".
Provided projections:
EPSG:900913. The simplified projection used here is described
in greater detail at
openlayers.org.
EPSG:4326.
You can define your own projection, with a module and object name as arguments:
"layer-name": { ... "projection": "Module:Object", }
The object must include methods that convert between coordinates, points, and locations. See the included mercator and WGS84 implementations for example. You can also instantiate a projection class using this syntax:
"layer-name": { ... "projection": "Module:Object()" }
See TileStache.Geography for more information.
Metatiles are larger areas to be rendered at one time, often used because it’s more efficient to render a large number of contiguous tiles at once than each one separately.
Example metatile configuration:
{ "cache": …, "layers": { "example-name": { "provider": { … }, "metatile": { "rows": 4, "columns": 4, "buffer": 64 } } } }
This example metatile is four rows tall and four columns wide with a buffer of 64 pixels, for a total bitmap size of 4 × 256 + 64 × 2 = 1152.
Metatile parameters:
TileStache includes a built-in slippy map preview, that can be viewed in a browser using the URL /{layer name}/preview.html, e.g. http://example.org/example-name/preview.html. The settings for this preview are completely optional, but can be set on a per-layer basis for control over starting location and file extension.
Example preview configuration:
{ "cache": …, "layers": { "example-name": { "provider": { … }, "preview": { "lat": 37.80439, "lon": -122.27127, "zoom": 15, "ext": "jpg" } } } }
This example preview displays JPG tiles, and is centered on 37.80439, -122.27127 at zoom 15.
Preview parameters:
TileStache supports configurable index pages for the front page of an instance. A custom index can be specified as a filename relative to the configuration location. Typically an HTML document would be given here, but other kinds of files such as images can be used, with MIME content-type headers determined by mimetypes.guess_type. A simple text greeting is displayed if no index is provided.
Example index page configuration:
{ "cache": …, "layers": …, "index": "filename.html" } }
Example index page configuration using a remote image:
{ "cache": …, "layers": …, "index": "http://tilestache.org/mustaches.jpg" } }
TileStache includes basic support for Python’s built-in logging system, with a logging level settable in the main configuration file. Possible logging levels include "debug", "info", "warning", "error" and "critical", described in the basic logging tutorial.
Example logging configuration:
{ "cache": …, "layers": …, "logging": "debug" } }
TileStache relies on duck typing rather than inheritance for extensibility, so all guidelines for customization below explain what methods and properties must be defined on objects for them to be valid as providers, caches, and configurations.
Example external provider configuration:
{ "cache": …, "layers": { "example-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 at least one of two methods for rendering map areas:
renderTile or renderArea. A provider must also accept
an instance of Layer as the first argument to its constructor.
Return value of both renderTile and renderArea is an
object with a save method that can accept a file-like object and
a format name, typically an instance of the PIL.Image object but
allowing for creation of providers that save text, raw data or other non-image
response.
A minimal provider stub class:
class ProviderStub:
def __init__(self, layer):
# create a new provider for a layer
raise NotImplementedError
def renderTile(self, width, height, srs, coord):
# return an object with a PIL-like save() method for a tile
raise NotImplementedError
def renderArea(self, width, height, srs, xmin, ymin, xmax, ymax, zoom):
# return an object with a PIL-like save() method for an area
raise NotImplementedError
In cases where a provider generates a response that should not be cached,
renderTile and renderArea may raise the
Core.NoTileLeftBehind
exception in lieu of a normal response. The exception is constructed using the
intended response object, but nothing will be written to cache. This feature
might useful in cases where a full tileset is being rendered for static
hosting, and you don’t want millions of identical ocean tiles.
See TileStache.Providers for more information on custom providers and TileStache.Goodies.Providers for examples of custom providers.
provider.renderTileDraws a single tile at a time.
Arguments to renderTile:
Return value of renderTile is a
PIL.Image
or other saveable object, used like this:
provider.renderTile(…).save(file, "XML")
provider.renderAreaDraws a variably-sized area, and is used when drawing metatiles.
Non-image providers and metatiles do not mix. If your provider returns JSON,
plaintext, XML, or some other non-PIL format, implement only the
renderTile method.
Arguments to renderArea:
Return value of renderArea is a
PIL.Image
or other saveable object, used like this:
provider.renderArea(…).save(file, "PNG")
provider.getTypeByExtension
A provider may offer a method for custom response types,
getTypeByExtension. This method returns a tuple with two strings:
a mime-type and a format.
Arguments to getTypeByExtension:
Example external provider configuration:
{ "cache": { "class": "Module:Classname", "kwargs": {"frob": "yes"} }, "layers": { … } }
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 cache must provide all of these five methods: lock,
unlock, remove, read, and save.
Each method requires three arguments:
The save method accepts an additional argument before the others:
A minimal cache stub class:
class CacheStub:
def lock(self, layer, coord, format):
# lock a tile
raise NotImplementedError
def unlock(self, layer, coord, format):
# unlock a tile
raise NotImplementedError
def remove(self, layer, coord, format):
# remove a tile
raise NotImplementedError
def read(self, layer, coord, format):
# return raw tile content from cache
raise NotImplementedError
def save(self, body, layer, coord, format):
# save raw tile content to cache
raise NotImplementedError
See TileStache.Caches for more information on custom caches and TileStache.Goodies.Caches for examples of custom caches.
A complete configuration object includes cache, layers, and dirpath properties and optional index property:
TileStache.Caches.Disk
etc. See
TileStache.Caches
for details on what makes a usable cache.
When creating a custom layers dictionary, e.g. for dynamic layer collections backed by some external configuration, these dictionary methods must be provided for a complete collection of layers:
KeyError.
A minimal layers dictionary stub class:
class LayersStub:
def keys(self):
# return a list of key strings
raise NotImplementedError
def items(self):
# return a list of (key, layer) tuples
raise NotImplementedError
def __contains__(self, key):
# return True if the key is here
raise NotImplementedError
def __getitem__(self, key):
# return the layer named by the key
raise NotImplementedError