Rendering tiles

After creating and parsing a RasterLayer, the tiles for that layer can be accessed through the tiles url. The raster urls have to be added to the application’s url patterns. Here we assume that the /raster/ base url is used as proposed in the Installation section.

The tiles url is structured as follows,

/raster/tiles/layer_id/{z}/{x}/{y}.png

where the layer_id is the primary key of a raster layer. This structure can be used directly in online mapping software such as OpenLayers or Leaflet. An example request could look like this: /raster/tiles/23/8/536/143.png, returning a tile in png format of the layer with ID pk=23 at zoom level z=8 and indexes x=536 and y=143.

By default, the tiles are rendered using simple grayscale. To apply a custom colormap, a Legend needs to be assigned to the layer. Raster layers have an optional foreign key to a Legend object, which can be set through the admin interface.

Legends

Legends are objects that are used to interpret raster data. This includes the cartographic information (colors), but also the semantics of the data (such as names). Legends be created through the admin interface.

A legend is stored as in the Legend model, which is a collection of LegendEntry objects. Each of the entries have an expression for classifying the data and a semantic meaning of the expression. The semantics of the expression are stored in the LegendSemantics model. Here is an example for a legend representing two temperatures:

>>> from raster.models import Legend, LegendEntry, LegendEntryOrder, LegendSemantics
>>> hot_semantics = LegendSemantics.objects.create(name='Hot')
>>> cold_semantics = LegendSemantics.objects.create(name='Cold')
>>> hot_entry = LegendEntry.objects.create(semantics=cold, expression='0', color='#0000FF')
>>> cold_entry = LegendEntry.objects.create(semantics=hot, expression='1', color='#FF0000')
>>> legend = Legend.objects.create(title='Temperatures')
>>> LegendEntryOrder.objects.create(legend=legend, legendentry=entry, code='1')
>>> legend.json
... '[{"color": "#FFFFFF", "expression": "1", "name": "Earth"}]'

Legend Entries

LegendEntry entries relate semantics and a color value with a range of pixel values. One entry has a foreign key to a LegendSemantics object, a color in hex format and an expression.

The expression is a classification of pixels. It describes a range of pixel values in the data. It is either an exact number for discrete rasters, or a formula for continuous rasters:

expression = "3"  # Matches all pixels with an exact value of 3

For more complicated expressions, a logical expression can be specified through a formula. The variable x represents the pixel value in the formula. Here are two examples of valid formula expressions:

# Match pixel values bigger than -3 and smaller or equal than 1
expression = "(-3.0 < x) & (x <= 1)"
# Match all pixels with values smaller or equal to one
expression = "x <= 1"

Formula expressions are currently not validated on input. Wrongly specified formulas might lead to errors when rendering raster tiles. Check your formulas if unexpected errors happen on the TMS endpoints.

Continuous Color Schemes

The examples above show how to assign discrete pixel value ranges to individual colors. This allows applying discrete color schemes with a limited number of breaks to continuous rasters.

Django-raster also supports applying continuous color scales. Colormaps are interpreted as continuous color schemes if the keyword continuous is provided as a key in the colormap dictionary.

The continuous color scheme requires at least two colors, which are interpolated over the range of pixel values. These colors can be specified using the from and to keywords. A third color can be specified to force interpolation through another color in the middle of the range. This intermediate color can be specified using the over key.

The range over which the colors are interpolated is determined automatically from the raster layer metadata if possible, and falls back to the range of the individual tile data. The fallback might result in a visually confusing color scheme, as the range of pixel values in a single tile may vary substantially and are not representative of the raster. The range can therefore also be specified manually using the range parameter.

An example for a continuous color scheme, which will interpolate all values from 0 to 100 into colors ranging from red to blue over green is the following:

{
    "continuous": "True",
    "from": [255, 0, 0],
    "to": [0, 0, 255],
    "over": [0, 255, 0],
    "range": [0, 100]
}

The keys continuous, from and to are required. The over key is an optional intermediate color for the interpolation. The range key specifies the pixel values over which to interpolate. This parameter is estimated from metadata if not provided in the legend. All other keys are ignored in the continuous color mode, which is triggered if the continuous key is found in the legend.

Overriding the colormap and the legend

While a legend and a colormap can be associated with a raster layer objects in the database it is nonetheless possible to overwrite the legend or colormap used to render the tiling. Overriding is done via the following url parameters:

Parameter Description
legend Use given legend to render the tiles
store One of database, session. Fetch legend from database or session, default is database
colormap Overrides the raster layer’s legend colormap.

Examples

If you want to overrides the legend to use MyOtherLegend stored in database you can use the following url for the tiling (assuming 23 is your rasterlayer_id):

/raster/tiles/23/{z}/{x}/{y}.png?legend=MyOtherLegend

If you want to use the legend from the session with the same name as above you can use following one:

/raster/tiles/23/{z}/{x}/{y}.png?legend=MyOtherLegend&store=session

Note

You can set and get a session colormap with the help of shortcuts functions set_session_colormap() and get_session_colormap().

And finally if you want to provide this custom colormap

{
    "1": "#FF0000",
    "2": "#00FF00",
    "3": "#0000FF"
}

you can do so by using this url:

/raster/tiles/{z}/{x}/{y}.png?colormap=%22%7B1%3A%20'%23FF0000'%2C%202%3A%20'%2300FF00'%2C%203%3A%20'%230000FF'%7D%22

The colormap value is the URIEncoded version of the json stringified colormap object.

Image formats

All endpoints (regular tiles, algebra and RGB) support three formats: PNG, JPEG and TIFF. The different formats can be requested by changing the file extension in the url. The extensions to use are .png, .jpg, and .tif.

The PNG and JPEG endpoints behave the same way, except that JPEG images do not support an alpha channel. Nodata pixels are rendered in black.

The TIFF endpoint will return the raw data produced from the request in a georeferenced GeoTIFF file. It therefore ignores any of the rendering parameters and simply returns the raw values of the result of the request. This might be useful for analysis purposes, where raster algebra results can be obtained in raw form for further downstream processing.