TileStache.Vector package

Module contents

Provider that returns vector representation of features in a data source.

This is a provider that does not return an image, but rather queries a data source for raw features and replies with a vector representation such as GeoJSON. For example, it’s possible to retrieve data for locations of OpenStreetMap points of interest or street centerlines contained within a tile’s boundary.

Many Polymaps (http://polymaps.org) examples use GeoJSON vector data tiles, which can be effectively created using this provider.

Vector functionality is provided by OGR (http://www.gdal.org/ogr/). Thank you, Frank Warmerdam.

Currently two serializations and three encodings are supported for a total of six possible kinds of output with these tile name extensions:

GeoJSON (.geojson):
See http://geojson.org/geojson-spec.html
Arc GeoServices JSON (.arcjson):
See http://www.esri.com/library/whitepapers/pdfs/geoservices-rest-spec.pdf
GeoBSON (.geobson) and Arc GeoServices BSON (.arcbson):
BSON-encoded GeoJSON and Arc JSON, see http://bsonspec.org/#/specification
GeoAMF (.geoamf) and Arc GeoServices AMF (.arcamf):
AMF0-encoded GeoJSON and Arc JSON, see: http://opensource.adobe.com/wiki/download/attachments/1114283/amf0_spec_121207.pdf

Possible future supported formats might include KML and others. Get in touch via Github to suggest other formats: http://github.com/migurski/TileStache.

Common parameters:

driver:

String used to identify an OGR driver. Currently, “ESRI Shapefile”, “PostgreSQL”, “MySQL”, Oracle, Spatialite and “GeoJSON” are supported as

data source drivers, with “postgis” and “shapefile” accepted as synonyms. Not case-sensitive.

OGR’s complete list of potential formats can be found here: http://www.gdal.org/ogr/ogr_formats.html. Feel free to get in touch via Github to suggest new formats: http://github.com/migurski/TileStache.

parameters:

Dictionary of parameters for each driver.

PostgreSQL: “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.

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 (http://polymaps.org).
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.
id_property:
Default is None. Sets the id of the geojson feature to the specified field of the data source. This can be used, for example, to identify a unique key field for the feature.

Example TileStache provider configuration:

“vector-postgis-points”: {

“provider”: {“name”: “vector”, “driver”: “PostgreSQL”,
“parameters”: {“dbname”: “geodata”, “user”: “geodata”,
“table”: “planet_osm_point”}}

}

“vector-postgis-lines”: {

“provider”: {“name”: “vector”, “driver”: “postgis”,
“parameters”: {“dbname”: “geodata”, “user”: “geodata”,
“table”: “planet_osm_line”}}

}

“vector-shapefile-points”: {

“provider”: {“name”: “vector”, “driver”: “ESRI Shapefile”,
“parameters”: {“file”: “oakland-uptown-point.shp”}, “properties”: [“NAME”, “HIGHWAY”]}

}

“vector-shapefile-lines”: {

“provider”: {“name”: “vector”, “driver”: “shapefile”,
“parameters”: {“file”: “oakland-uptown-line.shp”}, “properties”: {“NAME”: “name”, “HIGHWAY”: “highway”}}

}

“vector-postgis-query”: {

“provider”: {“name”: “vector”, “driver”: “PostgreSQL”,
“parameters”: {“dbname”: “geodata”, “user”: “geodata”,
“query”: “SELECT osm_id, name, highway, way FROM planet_osm_line WHERE SUBSTR(name, 1, 1) = ‘1’”}}

}

“vector-sf-streets”: {

“provider”: {“name”: “vector”, “driver”: “GeoJSON”,
“parameters”: {“file”: “stclines.json”}, “properties”: [“STREETNAME”]}

}

Caveats:

Your data source must have a valid defined projection, or OGR will not know how to correctly filter and reproject it. Although response tiles are typically in web (spherical) mercator projection, the actual vector content of responses is unprojected back to plain WGS84 latitude and longitude.

If you are using PostGIS and spherical mercator a.k.a. SRID 900913, you can save yourself a world of trouble by using this definition:

class TileStache.Vector.Provider(layer, driver, parameters, clipped, verbose, projected, spacing, properties, precision, id_property, skip_empty_fields=False)

Vector Provider for OGR datasources.

See module documentation for explanation of constructor arguments.

getTypeByExtension(extension)

Get mime-type and format by file extension.

This only accepts “geojson” for the time being.

static prepareKeywordArgs(config_dict)

Convert configured parameters to keyword args for __init__().

renderTile(width, height, srs, coord)

Render a single tile, return a VectorResponse instance.

class TileStache.Vector.VectorResponse(content, verbose, precision=6)

Wrapper class for Vector response that makes it behave like a PIL.Image object.

TileStache.getTile() expects to be able to save one of these to a buffer.

Constructor arguments: - content: Vector data to be serialized, typically a dictionary. - verbose: Boolean flag to expand response for better legibility.

save(out, format)