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, http url or s3 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.

Specifying an Url as Source

The raster file can be uploaded directly using the raster file field, or passed as a url either to a public http(s) address, or a url like string, pointing directly to an s3 bucket. The http(s) urls are regular web urls.

For the s3 links, the boto3 library is used to directly access an s3 bucket and download it from there. In this way, private or requester-pays buckets can be used as source. The credentials for accessing the buckets need to be configured so that boto3 can see them.

The url should have the following structure


for instance,


gets the same file as the following regular http url


but instead of making a regular web request, it accesses the file using boto3.

Note that for requester pays bucket this might incur charges even if the requester is not the owner of the bucket.

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.