Raster

The Raster API gives you access to the catalog of data processed and stored by Descartes Labs.

Raster has two fundamental capabilities. First, the ndarray and raster methods retrieve raster data, returning them either in a Numpy array or image file. These methods accept a list of Metadata identifiers from the Metadata API which identify the image(s) to retrieve. Both of these methods enable you to rescale, resample, reproject, clip, resize, select bands of interest, and convert data type of the imagery in a single call.

The ndarray and raster methods also enable you to mosaic adjacent images by passing a list of Metadata identifiers for the imagery you wish to mosaic. The mosaic ordering follows the ordering of the list of inputs. Thus, if there is any area of overlap between images, the mosaic image will contain the data from the last image.

Secondly, the Raster API provides a mechanism to tile imagery over a your area of interest (AOI). Using the dltile_from_latlon and dltiles_from_shape methods, you can generate uniformly sized tile(s) over point or polygon AOIs (respectively). These tile geometries can be passed to the Metadata API, and the ndarray or raster methods to search for and access data for each tile. The concept of DLTiles is further explained in the next section.

DLTiles

A common method for scaling up analysis over large geographic areas is to iterate over a tiling of the Earth. DLTiles is the Descartes Labs implementation of a customizable, global image tiling. By specifying the pixel size and tile dimensions, DLTiles generates tile grids over which any imagery source can be served. After defining a tiling, you can obtain tiles intersecting a region of interest by providing a latitude/longitude pair or GeoJSON geometry to one of the DLTile methods.

A tiling is defined by three user-specified parameters: the spatial resolution, tile dimension, and overlap between tiles (padding). The optimal tiling parameters will depend on your application.

Spatial resolution The spatial resolution will determine the pixel size of any imagery returned over the tiles. Higher or lower resolution versions of the same tile grid can be easily created by adjusting the spatial resolution and tile dimensions such that they cover the same ground distance. For example, a 1048x1048 pixel tile at 30m resolution will yield the same tile boundaries as a 524x524 pixel tile at 60m. DLTiles use UTM zones as a base projection, thus the spatial resolution is always specified in meters.

Tile dimension The choice of tile dimension is fairly arbitrary for most applications. Generally, it is most efficient to choose the largest tile dimension possible given your application. Depending on the computation you are running over the image tiles, it may be necessary to reduce the tile size as a means of reducing memory usage. Typical tile dimensions that cover a majority of use cases are 1024x1024 to 2048x2048.

Padding For some applications, a padding around the pixels defined by the tile dimension is necessary. This is typically in cases where the computation being performed involves a spatial operation over a stencil or kernel, such as a taking a derivative or doing a convolution, or where edge effects may otherwise be introduced. Specifying an appropriate padding will add pixels to the edge of the tile, such that the operation can yield a valid region the size of the specified tile dimension. It is up to the user to remove any unwanted padding after performing a spatial operation.

Here’s an example of a tiling over the state of New Mexico.

import descarteslabs as dl
>>> new_mexico = dl.places.shape('north-america_united-states_new-mexico')
>>> tile_size = 2048
>>> resolution = 60
>>> pad = 0
>>> tiles = dl.raster.dltiles_from_shape(resolution, tile_size, pad, new_mexico['geometry'])
>>> print("Total number of tiles over NM: {}".format(len(tiles['features'])))
Total number of tiles over NM: 42
https://cdn.descarteslabs.com/docs/dltile_new_mexico.png

Here, we can see that tiles do not generally overlap, since we have specified a padding of 0. The area where the tiles do overlap is in the western part of the state, at the boundary of two UTM zones. Because DLTiles always use UTM zones as the base projection, there will always be overlapping tiles at UTM boundaries.

If we were to add a padding, all tiles will overlap. For illustration purposes, we created a new tiling with the same parameters above, but set a very large padding (pad = 100). Overlaying this tiling on the above tiling, we can see the overlap between tiles related to padding as well as the overlap due to the UTM projection.

https://cdn.descarteslabs.com/docs/dltile_padding.png