TileStache.Goodies.Providers.Composite module¶
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 be limited to appear at certain zoom levels, given either as a range or as a single number:
{“src”: “layer-name”, “zoom”: “12”} {“src”: “layer-name”, “zoom”: “12-18”}
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.
Layers can be combined through the use of opacity and blend modes. Opacity is specified as a value from 0.0-1.0, and blend mode is specified as a string. This example layer is blended using the “hard light” mode at 50% opacity:
{“src”: “hillshading”, “mode”: “hard light”, “opacity”: 0.5}
Currently-supported blend modes include “screen”, “multiply”, “linear light”, and “hard light”.
Layers can also be affected by adjustments. Adjustments are specified as an array of names and parameters. This example layer has been slightly darkened using the “curves” adjustment, moving the input value of 181 (light gray) to 50% gray while leaving black and white alone:
{“src”: “hillshading”, “adjustments”: [ [“curves”, [0, 181, 255]] ]}
- Available adjustments:
- “threshold” - apply_threshold_adjustment() “curves” - apply_curves_adjustment() “curves2” - apply_curves2_adjustment()
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.
-
class
TileStache.Goodies.Providers.Composite.Composite(layer, stack=None, stackfile=None)¶ Bases:
TileStache.Goodies.Providers.Composite.ProviderAn old name for the Provider class, deprecated for the next version.
-
class
TileStache.Goodies.Providers.Composite.Layer(layername=None, colorname=None, maskname=None, opacity=1.0, blendmode=None, adjustments=None, zoom='')¶ 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.
-
in_zoom(zoom)¶ Return true if the requested zoom level is valid for this layer.
-
render(config, input_rgba, 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
TileStache.Goodies.Providers.Composite.Provider(layer, stack=None, stackfile=None)¶ 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.
-
renderTile(width, height, srs, coord)¶
-
-
class
TileStache.Goodies.Providers.Composite.Stack(layers)¶ A stack of image layers.
-
in_zoom(level)¶
-
render(config, input_rgba, 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.
-
-
TileStache.Goodies.Providers.Composite.apply_adjustments(rgba, adjustments)¶ Apply image adjustments one by one and return a modified image.
Working adjustments:
- threshold:
- Calls apply_threshold_adjustment()
- curves:
- Calls apply_curves_adjustment()
- curves2:
- Calls apply_curves2_adjustment()
-
TileStache.Goodies.Providers.Composite.apply_curves2_adjustment(rgba, map_red, map_green=None, map_blue=None)¶ Adjustment inspired by Photoshop “Curves” feature.
Arguments are given in the form of three value mappings, typically mapping black, grey and white input and output values. One argument indicates an effect applicable to all channels, three arguments apply effects to each channel separately.
Simple monochrome inversion:
- [
- “curves2”, [[0, 255], [128, 128], [255, 0]]
]
Darken a light image by pushing light grey down by 50%, 0x99 to 0x66:
- [
- “curves2”, [[0, 255], [153, 102], [255, 0]]
]
Shaded hills, with Imhof-style purple-blue shadows and warm highlights:
- [
- “curves2”, [[0, 22], [128, 128], [255, 255]], [[0, 29], [128, 128], [255, 255]], [[0, 65], [128, 128], [255, 228]]
]
-
TileStache.Goodies.Providers.Composite.apply_curves_adjustment(rgba, black_grey_white)¶ Adjustment inspired by Photoshop “Curves” feature.
Arguments are three integers that are intended to be mapped to black, grey, and white outputs. Curves2 offers more flexibility, see apply_curves2_adjustment().
Darken a light image by pushing light grey to 50% grey, 0xCC to 0x80:
- [
- “curves”, [0, 204, 255]
]
-
TileStache.Goodies.Providers.Composite.apply_threshold_adjustment(rgba, red_value, green_value=None, blue_value=None)¶
-
TileStache.Goodies.Providers.Composite.blend_channels_hard_light(bottom_chan, top_chan)¶ Return combination of bottom and top channels.
Math from http://illusions.hu/effectwiki/doku.php?id=hard_light_blending
-
TileStache.Goodies.Providers.Composite.blend_channels_linear_light(bottom_chan, top_chan)¶ Return combination of bottom and top channels.
Math from http://illusions.hu/effectwiki/doku.php?id=linear_light_blending
-
TileStache.Goodies.Providers.Composite.blend_channels_multiply(bottom_chan, top_chan)¶ Return combination of bottom and top channels.
Math from http://illusions.hu/effectwiki/doku.php?id=multiply_blending
-
TileStache.Goodies.Providers.Composite.blend_channels_screen(bottom_chan, top_chan)¶ Return combination of bottom and top channels.
Math from http://illusions.hu/effectwiki/doku.php?id=screen_blending
-
TileStache.Goodies.Providers.Composite.blend_images(bottom_rgba, top_rgb, mask_chan, opacity, blendmode)¶ Blend images using a given mask, opacity, and blend mode.
Working blend modes: None for plain pass-through, “screen”, “multiply”, “linear light”, and “hard light”.
-
TileStache.Goodies.Providers.Composite.build_stack(obj)¶ 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.
-
TileStache.Goodies.Providers.Composite.makeColor(color)¶ An old name for the make_color function, deprecated for the next version.
-
TileStache.Goodies.Providers.Composite.makeLayer(element)¶ Build a Layer object from an XML element, deprecated for the next version.
-
TileStache.Goodies.Providers.Composite.makeStack(element)¶ Build a Stack object from an XML element, deprecated for the next version.
-
TileStache.Goodies.Providers.Composite.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”