Raster Layers

A RasterLayer is django-raster’s representation of raster files. It can be used to input raster data into your application. In most cases there is one RasterLayer for each raster file.

Storing a Raster File

Raster files can be uploaded through the admin interface and are stored in the RasterLayer model. Like for any other model, raster layers can also be created using the Django shell. Each raster file corresponds to one RasterLayer object. When adding a new raster file, the following properties are required:

  • Layer name
  • Raster file (either as file or url)
  • Data type

The datatype tells django-raster how to interpret the pixel values. The choices are “continuous”, “categorical”, “mask”, or “rank ordered”. By default, django-raster extracts all other raster metadata from the input file. The optional input parameters are the following

  • Description
  • SRID
  • Nodata value
  • Max zoom value
  • Legend

The srid, the nodata value and the maximum zoom value are all determined automatically from the raster properties if left blank. The max zoom value specifies the highest z-x-y zoom level to create tiles for (see below).

The legend attribute is a foreign key to a raster Legend object. If the raster legend is specified, it is used as default style when rendering tiles from that raster. How raster tiles are rendered is described in detail in the Rendering tiles section.

There are also three boolean flags that allow finer grained control over the raster layer parse process.

  • Next higher zoom level
  • Build pyramids
  • Store reprojected

The raster layer is “snapped” to the next higher zoom level by default. To snap the raster to the next lower zoom level when compared to the true resolution of the data, the “next higher” flag has to be disactivated.

There is a “build pyramids” flag that controls whether the tiles should be created also for the lower zoom levels. This is enabled by default and is recommended in most cases as the tile renderer will expect those tiles to be present.

During parsing, the raster is reprojected to the web mercator projection. This operation is costly and is only done once by default. Django-raster stores a reprojected version in a separate model. To prevent the storage of the reprojected file, the “store reprojected” flag can be disactivated. Note that this will result in less use of storage, but an overhead when parsing, especially for asynchronous parsing where the file will be reprojected by each worker.

Raster Tile Creation

Upon uploading a file, django-raster automatically parses the raster file. The parser extracts metadata from the raster and its bands, and creates tiles. The progress or possible errors in parsing is written to a parse log object, which is exposed on the RasterLayer admin interface.

The parser automatically creates a tile pyramid in the z-x-y scheme of a TMS. By default, the highest zoom level for which to create tiles is calculated automatically from the resolution of the raster. The zoom level is set such that the resolution of the highest zoom is at least the original resolution. This behavior can be changed by manually setting the highest zoom level, using the max_zoom_value field.

The tiles are stored as RasterTile objects. The raster data itself is stored as PostGIS rasters through a RasterField. The tiles are managed automatically through their parent RasterLayer object, and do normally not require any manual user manipulation.

Asynchronous Parsing

It is highly recommended to configure the Django application with Celery, to parse the rasters asynchronously. For most raster files, the creation of tiles takes several minutes or even hours to complete. Since the parsing is triggered automatically upon upload, the html requests in the admin will often time out. For more information about how to configure Celery, consult the Installation section.