TileStache.Goodies.Providers.Composite
index
/home/migurski/public_html/TileStache/TileStache/Goodies/Providers/Composite.py

Layered, composite rendering for TileStache.
 
NOTE: This code is currently in heavy progress. I'm finishing the addition
of the new JSON style of layer configuration, while the original XML form
is *deprecated* and will be removed in the future TileStache 2.0.
 
The Composite Provider provides 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. Composite is modeled on Lars Ahlzen's TopOSM.
 
The "stack" configuration parameter describes a layer or stack of layers that
can be combined to create output. A simple stack that merely outputs a single
color orange tile looks like this:
 
    {"color" "#ff9900"}
 
Other layers in the current TileStache configuration can be reference by name,
as in this example stack that simply echoes another layer:
 
    {"src": "layer-name"}
 
Layers can also be used as masks, as in this example that uses one layer
to mask another layer:
 
    {"mask": "layer-name", "src": "other-layer"}
 
Many combinations of "src", "mask", and "color" can be used together, but it's
an error to provide all three.
 
Finally, the stacking feature allows layers to combined in more complex ways.
This example stack combines a background color and foreground layer:
 
    [
      {"color": "#ff9900"},
      {"src": "layer-name"}
    ]
 
Stacks can be nested as well, such as this combination of two background layers
and two foreground layers:
 
    [
      [
        {"color"" "#0066ff"},
        {"src": "continents"}
      ],
      [
        {"src": "streets"},
        {"src": "labels"}
      ]
    ]
 
A complete example configuration might look like this:
 
    {
      "cache":
      {
        "name": "Test"
      },
      "layers": 
      {
        "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}
        },
        "composite":
        {
          "provider":
          {
            "class": "TileStache.Goodies.Providers.Composite.Provider",
            "kwargs":
            {
              "stack":
              [
                {"src": "base"},
                [
                  {"src": "outlines", "mask": "halos"},
                  {"src": "streets"}
                ]
              ]
            }
          }
        }
      }
    }
 
It's also possible to provide an equivalent "stackfile" argument that refers to
an XML file, but this feature is *deprecated* and will be removed in the future
release of TileStache 2.0.
 
Corresponding example stackfile XML:
 
  <?xml version="1.0"?>
  <stack>
    <layer src="base" />
  
    <stack>
      <layer src="outlines">
        <mask src="halos" />
      </layer>
      <layer src="streets" />
    </stack>
  </stack>
 
Note that each layer in this file refers to a TileStache layer by name.
This complete example can be found in the included examples directory.

 
Modules
       
PIL
TileStache
sys

 
Classes
       
Layer
Provider
Composite
Stack

 
class Composite(Provider)
    An old name for the Provider class, deprecated for the next version.
 
  Methods inherited from Provider:
__init__(self, layer, stack=None, stackfile=None)
Make a new Composite.Provider.
 
Arguments:
 
  layer:
    The current TileStache.Core.Layer
    
  stack:
    A list or dictionary with configuration for the image stack, parsed
    by build_stack(). Also acceptable is a URL to a JSON file.
  
  stackfile:
    *Deprecated* filename for an XML representation of the image stack.
renderTile(self, width, height, srs, coord)

 
class Layer
    A single image layer in a stack.
 
Can include a reference to another layer for the source image, a second
reference to another layer for the mask, and a color name for the fill.
 
  Methods defined here:
__init__(self, layername=None, colorname=None, maskname=None)
A new image layer.
 
Arguments:
 
  layername:
    Name of the primary source image layer.
  
  colorname:
    Fill color, passed to make_color().
  
  maskname:
    Name of the mask image layer.
render(self, config, input_img, coord)
Render this image layer.
 
Given a configuration object, starting image, and coordinate,
return an output image with the contents of this image layer.

 
class Provider
    Provides 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.
 
  Methods defined here:
__init__(self, layer, stack=None, stackfile=None)
Make a new Composite.Provider.
 
Arguments:
 
  layer:
    The current TileStache.Core.Layer
    
  stack:
    A list or dictionary with configuration for the image stack, parsed
    by build_stack(). Also acceptable is a URL to a JSON file.
  
  stackfile:
    *Deprecated* filename for an XML representation of the image stack.
renderTile(self, width, height, srs, coord)

 
class Stack
    A stack of image layers.
 
  Methods defined here:
__init__(self, layers)
A new image stack.
 
Argument:
 
  layers:
    List of Layer instances.
render(self, config, input_img, coord)
Render this image stack.
 
Given a configuration object, starting image, and coordinate,
return an output image with the results of all the layers in
this stack pasted on in turn.

 
Functions
       
build_stack(object)
Build up a data structure of Stack and Layer objects from lists of dictionaries.
 
Normally, this is applied to the "stack" parameter to Composite.Provider.
makeColor(color)
An old name for the make_color function, deprecated for the next version.
makeLayer(element)
Build a Layer object from an XML element, deprecated for the next version.
makeStack(element)
Build a Stack object from an XML element, deprecated for the next version.
make_color(color)
Convert colors expressed as HTML-style RGB(A) strings to tuples.
 
Returns four-element RGBA tuple, e.g. (0xFF, 0x99, 0x00, 0xFF).
 
Examples:
  white: "#ffffff", "#fff", "#ffff", "#ffffffff"
  black: "#000000", "#000", "#000f", "#000000ff"
  null: "#0000", "#00000000"
  orange: "#f90", "#ff9900", "#ff9900ff"
  transparent orange: "#f908", "#ff990088"