TileStache API

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.49.11.

Requesting Tiles ¶

Over HTTP ¶

TileStache URLs are based on a Google Maps-like 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

In Code ¶

`TileStache.getTile` ¶

Get a type string and tile binary for a given request layer tile.

Arguments to getTile:

layer: Instance of Core.Layer to render.
coord: One ModestMaps.Core.Coordinate corresponding to a single tile.
extension: Filename extension to choose response type, e.g. "png" or "jpg".
ignore_cached: Optional boolean: always re-render the tile, whether it's in the cache or not. Default False.

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.requestHandler` ¶

Generate 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:

config: Required file path string for a JSON configuration file or a configuration object with cache, layers, and dirpath properties, such as TileStache.Config.Configuration.
path_info: Required end portion of a request URL including the layer name and tile coordinate, e.g. "/roads/12/656/1582.png".
query_string: Optional query string. Currently used only for JSONP callbacks.
script_name: Optional script name corresponds to CGI environment variable SCRIPT_NAME, used to calculate correct 302 redirects.

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.

Serving Tiles ¶

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.

WSGI ¶

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')"

The same configuration can be served with uWSGI like so. Note the usage of the --eval option over --module as this latter option does not support argument passing:

$ uwsgi --http :8080 --eval 'import TileStache; \
application = TileStache.WSGITileServer("/path/to/tilestache.cfg")'

See TileStache.WSGITileServer documentation for more information.

CGI ¶

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.

mod_python ¶

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.

Configuring TileStache ¶

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"
    } 
  }
}

Caches ¶

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.

Jump to Test, Disk, Multi, Memcache, Redis, or S3 cache.

Test ¶

Simple cache that doesn’t actually cache anything.

Activity is optionally logged, though.

Example configuration:

{
  "cache": {
    "name": "Test",
    "verbose": true
  },
  "layers": { … }
}

Test cache parameters:

verbose: Optional boolean flag to write cache activities to a logging function, defaults to False if omitted.

See TileStache.Caches.Test documentation for more information.

Disk ¶

Caches files to disk.

Example configuration:

{
  "cache": {
    "name": "Disk",
    "path": "/tmp/stache",
    "umask": "0000",
    "dirs": "portable",
    "gzip": ["xml", "json"]
  },
  "layers": { … }
}

Disk cache parameters:

path: Required local directory path where files should be stored.
umask: Optional string representation of octal permission mask for stored files. Defaults to "0022".
dirs: Optional string saying whether to create cache directories that are safe or portable. For an example tile 12/656/1582.png, "portable" creates matching directory trees while "safe" guarantees directories with fewer files, e.g. 12/000/656/001/582.png. Defaults to "safe".
gzip: Optional list of file formats that should be stored in a compressed form. Defaults to ["txt", "text", "json", "xml"]. Provide an empty list in the configuration for no compression.

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.

Multi ¶

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:

tiers: Required list of cache configurations. The fastest, most local cache should be at the beginning of the list while the slowest or most remote cache should be at the end. Memcache and S3 together make a great pair.

See TileStache.Caches.Multi documentation for more information.

Memcache ¶

Caches tiles to Memcache, requires python-memcached.

Example configuration:

{
  "cache": {
    "name": "Memcache",
    "servers": ["127.0.0.1:11211"],
    "revision": 0,
    "key prefix": "unique-id"
  },
  "layers": { … }
}

Memcache cache parameters:

servers: Optional array of servers, list of "{host}:{port}" pairs. Defaults to ["127.0.0.1:11211"] if omitted.
revision: Optional revision number for mass-expiry of cached tiles regardless of lifespan. Defaults to 0.
key prefix: Optional string to prepend to Memcache generated key. Useful when running multiple instances of TileStache that share the same Memcache instance to avoid key collisions. The key prefix will be prepended to the key name. Defaults to "".

See TileStache.Memcache.Cache documentation for more information.

Redis ¶

Caches tiles to Redis, requires redis-py and redis server.

Example configuration:


{
  "cache": {
    "name": "Redis",
    "host": "localhost",
    "port": 6379,
    "db": 0,
    "key prefix": "unique-id"
  },
  "layers": { … }
}

Redis cache parameters:

host: Defaults to "localhost" if omitted.
port: Integer; Defaults to 6379 if omitted.
db: Integer; Redis database number, defaults to 0 if omitted.
key prefix: Optional string to prepend to generated key. Useful when running multiple instances of TileStache that share the same Redis database to avoid key collisions (though the prefered solution is to use a different db number). The key prefix will be prepended to the key name. Defaults to "".

See TileStache.Redis.Cache documentation for more information.

S3 ¶

Caches tiles to Amazon S3, requires boto (2.0+).

Example configuration:

{
  "cache": {
    "name": "S3",
    "bucket": "<bucket name>",
    "access": "<access key>",
    "secret": "<secret key>"
    "reduced_redundancy": False
  },
  "layers": { … }
}

S3 cache parameters:

bucket: Required bucket name for S3. If it doesn’t exist, it will be created.
access: Optional access key ID for your S3 account. You can find this under “Security Credentials” at your AWS account page.
secret: Optional secret access key for your S3 account. You can find this under “Security Credentials” at your AWS account page.
use_locks: Optional boolean flag for whether to use the locking feature on S3. True by default. A good reason to set this to false would be the additional price and time required for each lock set in S3.
path: Optional path under bucket to use as the cache directory. ex. 'path': 'cache' will put tiles under {bucket}/cache/
reduced_redundancy: Optional boolean specifying whether to use Reduced Redundancy Storage mode in S3. Files stored with RRS incur less cost but have reduced redundancy in Amazon's storage system.

When access or secret are not provided, the environment variables AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY will be used. See Boto documentation for more information.

See TileStache.S3.Cache documentation for more information.

Additional Caches ¶

New caches with functionality that’s not strictly core to TileStache first appear in TileStache.Goodies.Caches.

LimitedDisk

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.

Layers ¶

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": …,
      "tile height": …,
      "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:

provider: Refers to a Provider, explained in detail under Providers.
metatile: Optionally makes it possible for multiple individual tiles to be rendered at one time, for greater speed and efficiency. This is commonly used for bitmap providers such as Mapnik. See Metatiles for more information.
preview: Optionally overrides the starting point for the built-in per-layer slippy map preview, useful for image-based layers where appropriate. See Preview for more information.
projection: Names a geographic projection, explained in Projections. If omitted, defaults to "spherical mercator".
stale lock timeout: An optional number of seconds to wait before forcing a lock that might be stuck. This is defined on a per-layer basis, rather than for an entire cache at one time, because you may have different expectations for the rendering speeds of different layer configurations. Defaults to 15.
cache lifespan: An optional number of seconds that cached tiles should be stored. This is defined on a per-layer basis. Defaults to forever if None, 0 or omitted.
write cache: An optional boolean value to allow skipping cache write altogether. This is defined on a per-layer basis. Defaults to true if omitted.
bounds: An optional dictionary of six tile boundaries to limit the rendered area: low (lowest zoom level), high (highest zoom level), north, west, south, and east (all in degrees). When any of these are omitted, default values are north=89, west=-180, south=-89, east=180, low=0, and high=31. A list of dictionaries will also be accepted, indicating a set of possible bounding boxes any one of which includes possible tiles.
allowed origin: An optional string that shows up in the response HTTP header Access-Control-Allow-Origin, useful for when you need to provide javascript direct access to response data such as GeoJSON or pixel values. The header is part of a W3C working draft. Pro-tip: if you want to allow maximum permissions and minimal security headache, use a value of "*" for this.
maximum cache age: An optional number of seconds used to control behavior of downstream caches. Causes TileStache responses to include Cache-Control and Expires HTTP response headers. Useful when TileStache is itself hosted behind an HTTP cache such as Squid, Cloudfront, or Akamai.
redirects: An optional dictionary of per-extension HTTP redirects, treated as lowercase. Useful in cases where your tile provider can support many formats but you want to enforce limits to save on cache usage. If a request is made for a tile with an extension in the dictionary keys, a response can be generated that redirects the client to the same tile with another extension. For example, use the setting {"jpg": "png"} to force all requests for JPEG tiles to be redirected to PNG tiles.
tile height: An optional integer gives the height of the image tile in pixels. You almost always want to leave this at the default value of 256, but you can use a value of 512 to create double-size, double-resolution tiles for high-density phone screens.
jpeg options: An optional dictionary of JPEG creation options, passed through to PIL. Valid options include quality (integer), progressive (boolean), and optimize (boolean).
png options: An optional dictionary of PNG creation options, passed through to PIL. Valid options include palette (URL or filename), palette256 (boolean) and optimize (boolean).

Providers ¶

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

Jump to Mapnik (image), Proxy, Vector, URL Template, MBTiles, Mapnik (grid), or Pixel Sandwich provider.

Mapnik ¶

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:

mapfile: Required local file path to Mapnik XML file.
fonts: Optional relative directory path to *.ttf font files

See TileStache.Mapnik.ImageProvider for more information.

Proxy ¶

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:

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

See TileStache.Providers.Proxy for more information.

Vector ¶

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:

GeoJSON (.geojson): Conforms to the GeoJSON specification.
Arc GeoServices JSON (.arcjson): Conforms to ESRI’s GeoServices REST specification.
GeoBSON (.geobson) and Arc GeoServices BSON (.arcbson): BSON-encoded GeoJSON and Arc JSON.
GeoAMF (.geoamf) and Arc GeoServices AMF (.arcamf): AMF0-encoded GeoJSON and Arc JSON.

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"]}
    },
    {
      "provider": {"name": "vector", "driver": "MySQL",
                   "parameters": {"dbname": "geodata", "port": "3306", 
                                   "user": "geotest", "table": "test"},
                   "properties": ["name"], "id_property": "oid"}
    },
    {
      "provider": {"name": "vector", "driver": "Oracle",
                   "parameters": {"dbname": "ORCL", "port": "3306", 
                                  "user": "scott", "password": "tiger", 
                                  "table": "test"}}
    },
    {
      "provider": {"name": "vector", "driver": "Spatialite",
                   "parameters": {"file": "test.sqlite", "layer": "test"}}
    }
  }
}

Vector provider parameters:

driver

String used to identify an OGR driver. Currently, only "ESRI Shapefile", "PostgreSQL", and "GeoJSON" are supported as data source drivers, with "postgis" and "shapefile" accepted as synonyms. Not case-sensitive.

parameters

Dictionary of parameters for each driver.

PostgreSQL, MySQL and Oracle: "dbname" parameter is required, with name of database. "host", "user", and "password" are optional connection parameters. One of "table" or "query" is required, with a table name in the first case and a complete SQL query in the second.
Shapefile and GeoJSON: "file" parameter is required, with filesystem path to data file.
Spatialite: "file" parameter is required, with filesystem path to data file. "layer" parameter is required, and is the name of the SQLite table.

properties

Optional list or dictionary of case-sensitive output property names.
If omitted, all fields from the data source will be included in response. If a list, treated as a whitelist of field names to include in response. If a dictionary, treated as a whitelist and re-mapping of field names.

clipped

Default is true.
Boolean flag for optionally clipping the output geometries to the bounds of the enclosing tile, or the string value "padded" for clipping to the bounds of the tile plus 5%. This results in incomplete geometries, dramatically smaller file sizes, and improves performance and compatibility with Polymaps.

projected

Default is false.
Boolean flag for optionally returning geometries in projected rather than geographic coordinates. Typically this means EPSG:900913 a.k.a. spherical mercator projection. Stylistically a poor fit for GeoJSON, but useful when returning Arc GeoServices responses.

precision

Default is 6.
Optional number of decimal places to use for floating point values.

spacing

Optional number of tile pixels for spacing geometries in responses. Used to cut down on the number of returned features by ensuring that only those features at least this many pixels apart are returned. Order of features in the data source matters: early features beat out later features.

verbose

Default is false.
Boolean flag for optionally expanding output with additional whitespace for readability. Results in larger but more readable GeoJSON responses.

See TileStache.Vector for more information.

URL Template ¶

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:

template: String with substitutions suitable for use in string.Template. The variables available for substitution are width, height (in pixels), srs (in PROJ.4 format), xmin, ymin, xmax, ymax (in projected map units), and zoom. Example: "http://example.com/?bbox=$xmin,$ymin,$xmax,$ymax&bboxSR=102113&size=$width,$height&imageSR=102113&format=jpg&f=image".
referer: Optional string with HTTP Referer URL to send to WMS server. Some WMS servers use the Referer request header to authenticate requests; this parameter provides one.
source projection
timeout

See TileStache.Providers.UrlTemplate for more information.

MBTiles ¶

Provider that reads stored images from MBTiles tilesets.

Example MBTiles provider configuration:

{
  "cache": { … }.
  "layers":
  {
    "roads":
    {
      "provider":
      {
        "name": "mbtiles", 
        "tileset": "collection.mbtiles"
      }
    }
  }
}

MBTiles provider parameters:

tileset: Required local file path to MBTiles tileset file, a SQLite 3 database file.

See TileStache.MBTiles.Provider for more information.

Mapnik Grid ¶

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:

mapfile: Required local file path to Mapnik XML file.
fields: Optional array of field names to return in the response, defaults to all. An empty list will return no field names, while a value of null is equivalent to all.
layer index: Optional layer from the mapfile to render, defaults to 0 (first layer).
layers: Optional ordered list of (layer index, fields) to combine; if provided layers overrides both layer index and fields arguments.
scale: Optional scale factor of output raster, defaults to 4 (64×64).
layer id key: Optional. If set, each item in the "data" property will have its source mapnik layer name added, keyed by this value. Useful for distingushing between data items.

See TileStache.Mapnik.GridProvider for more information.

Pixel Sandwich ¶

The Sandwich Provider supplies a Photoshop-like rendering pipeline, making it possible to use the output of other configured tile layers as layers or masks to create a combined output. Sandwich is modeled on Lars Ahlzen’s TopOSM.

Sandwich require the external Blit library to function.

Example Sandwich provider configurations:

{
  "cache": { … }.
  "layers": 
  {
    "sandwiches":
    {
      "provider":
      {
        "name": "Sandwich",
        "stack":
        [
          {"src": "base"},
          {"src": "outlines", "mask": "halos"},
          {"src": "streets"}
        ]
      }
    },
    "base":
    {
      "provider": {"name": "mapnik", "mapfile": "mapnik-base.xml"}
    },
    "halos":
    {
      "provider": {"name": "mapnik", "mapfile": "mapnik-halos.xml"},
      "metatile": {"buffer": 128}
    },
    "outlines":
    {
      "provider": {"name": "mapnik", "mapfile": "mapnik-outlines.xml"},
      "metatile": {"buffer": 16}
    },
    "streets":
    {
      "provider": {"name": "mapnik", "mapfile": "mapnik-streets.xml"},
      "metatile": {"buffer": 128}
    }
  }
}

Sandwich provider parameters:

stack: Required layer or stack of layers that can be combined to create output. The stack is a list, with solid color or raster layers from elsewhere in the configuration, and is described in detail in the dedicated Sandwich documentation.

See TileStache.Sandwich for more information.

Additional Providers ¶

New providers with functionality that’s not strictly core to TileStache first appear in TileStache.Goodies.Providers.

Grid

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.

PostGeoJSON

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.

SolrGeoJSON

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.

Composite

Layered, composite rendering for TileStache. See TileStache.Goodies.Providers.Composite for more information.

MirrorOSM

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.

Projections ¶

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:

spherical mercator: Projection for most commonly-used web map tile scheme, equivalent to EPSG:900913. The simplified projection used here is described in greater detail at openlayers.org.
WGS84: Unprojected projection for the other commonly-used web map tile scheme, equivalent to 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 ¶

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:

rows: Height of the metatile measured in tiles.
columns: Width of the metatile measured in tiles.
buffer: Buffer area around the metatile, measured in pixels. This is useful for providers with labels or icons, where it’s necessary to draw a bit extra around the edges to ensure that text is not cut off.

Preview ¶

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:

lat: Starting latitude in degrees.
lon: Starting longitude in degrees.
zoom: Starting zoom level.
ext: Filename extension, e.g. "png".

Index Page ¶

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"
  }
}

Logging ¶

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"
  }
}

Extending TileStache ¶

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.

Providers ¶

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.renderTile` ¶

Draws a single tile at a time.

Arguments to renderTile:

width: Pixel width of tile, typically 256.
height: Pixel height of tile, typically 256.
srs: Projection as Proj4 string. "+proj=longlat +ellps=WGS84 +datum=WGS84" is an example, see TileStache.Geography for actual values.
coord: Coordinate object representing a single tile.

Return value of renderTile is a PIL.Image or other saveable object, used like this:

provider.renderTile(…).save(file, "XML")

`provider.renderArea` ¶

Draws 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:

width: Pixel width of tile, typically 256.
height: Pixel height of tile, typically 256.
srs: Projection as Proj4 string. "+proj=longlat +ellps=WGS84 +datum=WGS84" is an example, see TileStache.Geography for actual values.
xmin: Minimum x boundary of rendered area in projected coordinates.
ymin: Minimum y boundary of rendered area in projected coordinates.
xmax: Maximum x boundary of rendered area in projected coordinates.
ymax: Maximum y boundary of rendered area 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.

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:

extension: Filename extension string, e.g. "png", "json", etc.

Caches ¶

Example external provider configuration:

{
  "cache":
  {
    "class": "Module:Classname",
    "kwargs": {"frob": "yes"}
  },
  "layers": { … }
}

A cache must provide all of these five methods: lock, unlock, remove, read, and save.

Each method requires three arguments:

layer: Instance of a layer.
coord: Single Coordinate that represents a tile.
format: String like "png" or "jpg" that is used as a filename extension.

The save method accepts an additional argument before the others:

body: Raw content to save to the cache.

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.

Configuration ¶

A complete configuration object includes cache, layers, and dirpath properties and optional index property:

cache: Cache instance, e.g. TileStache.Caches.Disk etc. See TileStache.Caches for details on what makes a usable cache.
layers: Dictionary of layers keyed by name.
dirpath: Local filesystem path for this configuration, useful for expanding relative paths.
index: Two-element tuple with mime-type and content for installation index page.

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:

keys: Return list of layer name strings.
items: Return list of (name, layer) pairs.
__contains__: Return boolean true if given key is an existing layer.
__getitem__: Return existing layer object for given key or raise 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