RasterColorizer

New in 0.8

(Note: This document has been copied and translated from https://github.com/BenMoores/mapnik-trunk/wiki/RasterColorizer

The Raster Colorizer allows the palette of rasters to be modified, for example, colorizing a height map.

To use the colorizer, create a style with a raster symbolizer and add a raster colorizer to it.

The DataSource making use of the style must be a single band raster file opened with the GDAL input plugin. It will not work with other input plugins; and it will not work if more than one band is loaded. It will not work unless you explicitly request the band to be loaded (the default band=-1 does not work even if the input has a single band). It will not work with the PostGIS Raster gdal driver (as of GDAL-0.11).

The colorizer works in the following way:

It has an ordered list of ''stop_s that describe how to translate an input value to an output color.
A stop has a value, which marks the stop as being applied to input values from its value, up until the next stops value.
A stop has a mode, which says how the input value will be converted to a colour.
A stop has a color
The colorizer also has default color, which input values will be converted to if they don't match any stops.
The colorizer also has a default mode, which can be inherited by the stops.
The colorizer also has an epsilon value, which is used in the exact mode.

Modes

The available modes are inherit, discrete, linear, and exact. Inherit is only valid for stops, and not the default colorizer mode. It means that the stop will inherit the mode of the containing colorizer.

Discrete causes all input values from the stops value, up until the next stops value (or forever if this is the last stop) to be translated to the stops color.

Linear causes all input values from the stops value, up until the next stops value to be translated to a color which is linearly interpolated between the two stops colors. If there is no next stop, then the discrete mode will be used.

Exact causes an input value which matches the stops value to be translated to the stops color. The colorizers epsilon value can be used to make the match a bit fuzzy (in the 'greater than' direction).

XML

RasterColorizer element

Required attributes: none

Optional attributes:

default-mode This can be either "discrete", "linear" or "exact". If it is not specified then the default is "linear".
default-color This can be any color. If it is not specified then the default is "transparent".
epsilon This can be any positive floating point value. The default is a very small number (e.g. 1.1920928955078125e-07 )

Optional sub-elements:

stop The list of stops ordered by their value attribute.

stop element

Required attributes:

value The value at which the stop begins to be applied

Optional attributes:

color The color of the stop. If not specified, the colorizers default_color will be used.
mode The mode of the stop. If not specified, "inherit" will be used.

Example XML

In this example XML, the following value to color translation is performed:

-inf <= x < -1000 white
-1000 <= x < -500 blue
-500 <= x < 0 red
0 <= x < 5 yellow blending to white
5 <= x < 10 white blending to red
10 <= x < 15 red blending to green
15 <= x < 17 green blending to black
17 == x black
17 <= x < 18 white
18 <= x < 100 green blending to indigo

<?xml version="1.0" encoding="utf-8"?>
<Map srs="+proj=latlong +datum=WGS84">
<Style name="elevation">
  <Rule>
    <RasterSymbolizer>
      <RasterColorizer default-mode="linear" default-color="white" epsilon="0.001">
        <stop color="blue"        value = "-1000"  />
        <stop color="red"         value = "-500"   mode = "discrete" />
        <stop color="yellow"      value = "0"      />
        <stop                     value = "5"      />
        <stop color="red"         value = "10"     />
        <stop color="green"       value = "15"     />
        <stop color="black"       value = "17"     mode = "exact"    />
        <stop color="indigo"      value = "100"    />
      </RasterColorizer>
    </RasterSymbolizer>
  </Rule>
</Style>

<Layer name="dataraster">
    <StyleName>elevation</StyleName>
    <Datasource>
        <Parameter name="file">../mapnik2/tests/data/raster/dataraster.tif</Parameter>
        <Parameter name="type">gdal</Parameter>
        <Parameter name="band">1</Parameter>
    </Datasource>
</Layer>
</Map>

Python Bindings

Python bindings are available. The objects are as follows:

RasterColorizer

_mapnik2.RasterColorizer()

It has the properties default_color, default_mode, epsilon, and stops (read only).

It has the functions add_stop, and get_color.

ColorizerStops

This is an array of ColorizerStop objects. It is the type of the RasterColorizer stops property.

ColorizerStop

It has the properties color, value, and mode.

ColorizerMode

This is the enumeration of the stop modes. The values are mapnik2.COLORIZER_LINEAR, mapnik2.COLORIZER_DISCRETE, mapnik2.COLORIZER_EXACT, and mapnik2.COLORIZER_INHERIT.

Example Python

import mapnik2
c = mapnik2.RasterColorizer( mapnik2.COLORIZER_DISCRETE , mapnik2.Color(0,0,0,255) )
c.epsilon = 0.001
c.add_stop(-10)
c.add_stop(15.83, mapnik2.COLORIZER_EXACT)
c.add_stop(20, mapnik2.Color("red"))
c.add_stop(30.25, mapnik2.COLORIZER_LINEAR, mapnik2.Color("green"))
c.get_color(23.124)
c.stops[1].color