TileStache.Core | index

`The core class bits of TileStache.
Two important classes can be found here.
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. Layers are represented in the
configuration file as a dictionary:
{
"cache": ...,
"layers":
{
"example-name":
{
"provider": { ... },
"metatile": { ... },
"preview": { ... },
"projection": ...,
"stale lock timeout": ...,
"cache lifespan": ...,
"write cache": ...,
"bounds": { ... },
"allowed origin": ...,
"maximum cache age": ...,
"redirects": ...,
"tile height": ...,
"jpeg options": ...,
"png options": ...
}
}
}
- "provider" refers to a Provider, explained in detail in TileStache.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 the Mapnik provider. See below for more information on metatiles.
- "preview" optionally overrides the starting point for the built-in per-layer
slippy map preview, useful for image-based layers where appropriate.
See below for more information on the preview.
- "projection" names a geographic projection, explained in TileStache.Geography.
If omitted, defaults to spherical mercator.
- "stale lock timeout" is 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" is 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" is an optional boolean value to allow skipping cache write
altogether. This is defined on a per-layer basis. Defaults to true if omitted.
- "bounds" is 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).
- "allowed origin" is 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 (http://www.w3.org/TR/cors/).
- "maximum cache age" is 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" is 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.
- "tile height" 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" is an optional dictionary of JPEG creation options, passed
through to PIL: http://www.pythonware.com/library/pil/handbook/format-jpeg.htm.
- "png options" is an optional dictionary of PNG creation options, passed
through to PIL: http://www.pythonware.com/library/pil/handbook/format-png.htm.
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
Sample JPEG creation options:
{
"quality": 90,
"progressive": true,
"optimize": true
}
Sample PNG creation options:
{
"optimize": true,
"palette": "filename.act"
}
Sample bounds:
{
"low": 9, "high": 15,
"south": 37.749, "west": -122.358,
"north": 37.860, "east": -122.113
}
Metatile represents a larger area to be rendered at one time. Metatiles are
represented in the configuration file as a dictionary:
{
"rows": 4,
"columns": 4,
"buffer": 64
}
- "rows" and "columns" are the height and width of the metatile measured in
tiles. This example metatile is four rows tall and four columns wide, so it
will render sixteen tiles simultaneously.
- "buffer" is a 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. This example
metatile has a buffer of 64 pixels, so the resulting metatile will be 1152
pixels square: 4 rows x 256 pixels + 2 x 64 pixel buffer.
The preview can be accessed through a URL like /<layer name>/preview.html:
{
"lat": 33.9901,
"lon": -116.1637,
"zoom": 16,
"ext": "jpg"
}
- "lat" and "lon" are the starting latitude and longitude in degrees.
- "zoom" is the starting zoom level.
- "ext" is the filename extension, e.g. "png".`

Modules

``

PIL.Image | logging |  |

Classes

``

Layer
Metatile
exceptions.Exception(exceptions.BaseException)
  KnownUnknown
  NoTileLeftBehind
  TheTileLeftANote

class KnownUnknown(exceptions.Exception)
`` | `There are known unknowns. That is to say, there are things that we now know we don't know. This exception gets thrown in a couple places where common mistakes are made.`

Method resolution order:
  KnownUnknown
  exceptions.Exception
  exceptions.BaseException
  __builtin__.object

Data descriptors defined here:

__weakref__
  `list of weak references to the object (if defined)`

Methods inherited from exceptions.Exception:

__init__(...)
  `x.__init__(...) initializes x; see x.__class__.__doc__ for signature`

Data and other attributes inherited from exceptions.Exception:

__new__ = <built-in method __new__ of type object at 0x100119f80>
  `T.__new__(S, ...) -> a new object with type S, a subtype of T`

Methods inherited from exceptions.BaseException:

__delattr__(...)
  `x.__delattr__('name') <==> del x.name`

__getattribute__(...)
  `x.__getattribute__('name') <==> x.name`

__getitem__(...)
  `x.__getitem__(y) <==> x[y]`

__getslice__(...)
  `x.__getslice__(i, j) <==> x[i:j]
  Use of negative indices is not supported.`

__reduce__(...)

__repr__(...)
  `x.__repr__() <==> repr(x)`

__setattr__(...)
  `x.__setattr__('name', value) <==> x.name = value`

__setstate__(...)

__str__(...)
  `x.__str__() <==> str(x)`

__unicode__(...)

Data descriptors inherited from exceptions.BaseException:

__dict__

args

message

class Layer

``

`A Layer.
Required attributes:
provider:
Render provider, see Providers module.
config:
Configuration instance, see Config module.
projection:
Geographic projection, see Geography module.
metatile:
Some information for drawing many tiles at once.
Optional attributes:
stale_lock_timeout:
Number of seconds until a cache lock is forced, default 15.
cache_lifespan:
Number of seconds that cached tiles should be stored, default 15.
write_cache:
Allow skipping cache write altogether, default true.
bounds:
Instance of Config.Bounds for limiting rendered tiles.
allowed_origin:
Value for the Access-Control-Allow-Origin HTTP response header.
max_cache_age:
Number of seconds that tiles from this layer may be cached by downstream clients.
redirects:
Dictionary of per-extension HTTP redirects, treated as lowercase.
preview_lat:
Starting latitude for slippy map layer preview, default 37.80.
preview_lon:
Starting longitude for slippy map layer preview, default -122.26.
preview_zoom:
Starting zoom for slippy map layer preview, default 10.
preview_ext:
Tile name extension for slippy map layer preview, default "png".
tile_height:
Height of tile in pixels, as a single integer. Tiles are generally
assumed to be square, and Layer.render() will respond with an error
if the rendered image is not this height.
`

Methods defined here:

__init__(self, config, projection, metatile, stale_lock_timeout=15, cache_lifespan=None, write_cache=True, allowed_origin=None, max_cache_age=None, redirects=None, preview_lat=37.799999999999997, preview_lon=-122.26000000000001, preview_zoom=10, preview_ext='png', bounds=None, tile_height=256)

doMetatile(self)
  `Return True if we have a real metatile and the provider is OK with it.`

envelope(self, coord)
  `Projected rendering envelope (xmin, ymin, xmax, ymax) for a Coordinate.`

getTileResponse(self, coord, extension, ignore_cached=False)
  `Get status code, headers, and a tile binary for a given request layer tile.
  Arguments:
  - coord: one ModestMaps.Core.Coordinate corresponding to a single tile.
  - extension: filename extension to choose response type, e.g. "png" or "jpg".
  - ignore_cached: always re-render the tile, whether it's in the cache or not.
  This is the main entry point, after site configuration has been loaded
  and individual tiles need to be rendered.`

getTypeByExtension(self, extension)
  `Get mime-type and PIL format by file extension.`

metaEnvelope(self, coord)
  `Projected rendering envelope (xmin, ymin, xmax, ymax) for a metatile.`

metaSize(self, coord)
  `Pixel width and height of full rendered image for a metatile.`

metaSubtiles(self, coord)
  `List of all coords in a metatile and their x, y offsets in a parent image.`

name(self)
  `Figure out what I'm called, return a name if there is one.
  Layer names are stored in the Configuration object, so
  config.layers must be inspected to find a matching name.`

render(self, coord, format)
  `Render a tile for a coordinate, return PIL Image-like object.
  Perform metatile slicing here as well, if required, writing the
  full set of rendered tiles to cache as we go.
  Note that metatiling and pass-through mode of a Provider
  are mutually exclusive options`

setSaveOptionsJPEG(self, quality=None, optimize=None, progressive=None)
  `Optional arguments are added to self.jpeg_options for pickup when saving.
  More information about options:
  http://www.pythonware.com/library/pil/handbook/format-jpeg.htm`

setSaveOptionsPNG(self, optimize=None, palette=None)
  `Optional arguments are added to self.png_options for pickup when saving.
  Palette argument is a URL relative to the configuration file,
  and it implies bits and optional transparency options.
  More information about options:
  http://www.pythonware.com/library/pil/handbook/format-png.htm`

class Metatile
`` | `Some basic characteristics of a metatile. Properties: - rows: number of tile rows this metatile covers vertically. - columns: number of tile columns this metatile covers horizontally. - buffer: pixel width of outer edge.`

Methods defined here:

__init__(self, buffer=0, rows=1, columns=1)

allCoords(self, coord)
  `Return a list of coordinates for a complete metatile.
  Results are guaranteed to be ordered left-to-right, top-to-bottom.`

firstCoord(self, coord)
  `Return a new coordinate for the upper-left corner of a metatile.
  This is useful as a predictable way to refer to an entire metatile
  by one of its sub-tiles, currently needed to do locking correctly.`

isForReal(self)
  `Return True if this is really a metatile with a buffer or multiple tiles.
  A default 1x1 metatile with buffer=0 is not for real.`

class NoTileLeftBehind(exceptions.Exception)

``

`Leave no tile in the cache.
This exception can be thrown in a provider to signal to
TileStache.getTile() that the result tile should be returned,
but not saved in a cache. Useful in cases where a full tileset
is being rendered for static hosting, and you don't want millions
of identical ocean tiles.
The one constructor argument is an instance of PIL.Image or
some other object with a save() method, as would be returned
by provider renderArea() or renderTile() methods.
`

Method resolution order:
  NoTileLeftBehind
  exceptions.Exception
  exceptions.BaseException
  __builtin__.object

Methods defined here:

__init__(self, tile)

Data descriptors defined here:

__weakref__
  `list of weak references to the object (if defined)`

Data and other attributes inherited from exceptions.Exception:

__new__ = <built-in method __new__ of type object at 0x100119f80>
  `T.__new__(S, ...) -> a new object with type S, a subtype of T`

Methods inherited from exceptions.BaseException:

__delattr__(...)
  `x.__delattr__('name') <==> del x.name`

__getattribute__(...)
  `x.__getattribute__('name') <==> x.name`

__getitem__(...)
  `x.__getitem__(y) <==> x[y]`

__getslice__(...)
  `x.__getslice__(i, j) <==> x[i:j]
  Use of negative indices is not supported.`

__reduce__(...)

__repr__(...)
  `x.__repr__() <==> repr(x)`

__setattr__(...)
  `x.__setattr__('name', value) <==> x.name = value`

__setstate__(...)

__str__(...)
  `x.__str__() <==> str(x)`

__unicode__(...)

Data descriptors inherited from exceptions.BaseException:

__dict__

args

message

class TheTileLeftANote(exceptions.Exception)
`` | `A tile exists, but it shouldn't be returned to the client. Headers and/or a status code are provided in its stead. This exception can be thrown in a provider or a cache to signal to upstream servers where a tile can be found or to clients that a tile is empty (or solid).`

Method resolution order:
  TheTileLeftANote
  exceptions.Exception
  exceptions.BaseException
  __builtin__.object

Methods defined here:

__init__(self, headers=None, status_code=200, content='', emit_content_type=True)

Data descriptors defined here:

__weakref__
  `list of weak references to the object (if defined)`

Data and other attributes inherited from exceptions.Exception:

__new__ = <built-in method __new__ of type object at 0x100119f80>
  `T.__new__(S, ...) -> a new object with type S, a subtype of T`

Methods inherited from exceptions.BaseException:

__delattr__(...)
  `x.__delattr__('name') <==> del x.name`

__getattribute__(...)
  `x.__getattribute__('name') <==> x.name`

__getitem__(...)
  `x.__getitem__(y) <==> x[y]`

__getslice__(...)
  `x.__getslice__(i, j) <==> x[i:j]
  Use of negative indices is not supported.`

__reduce__(...)

__repr__(...)
  `x.__repr__() <==> repr(x)`

__setattr__(...)
  `x.__setattr__('name', value) <==> x.name = value`

__setstate__(...)

__str__(...)
  `x.__str__() <==> str(x)`

__unicode__(...)

Data descriptors inherited from exceptions.BaseException:

__dict__

args

message

Functions

``

time(...)
  `time() -> floating point number
  Return the current time in seconds since the Epoch.
  Fractions of a second may be present if the system clock provides them.`