Raster

class Raster(url=None, auth=None)[source]

The Raster API retrieves data from the Descartes Labs Catalog. Direct use of the Raster API is not recommended. Consider using the Descartes Labs Scenes API instead.

The parent Service class implements authentication and exponential backoff/retry. Override the url parameter to use a different instance of the backing service.

Attributes:

CONNECT_TIMEOUT
READ_TIMEOUT
RETRY_CONFIG(*args, **kwargs) Retry configuration that extends urllib3.util.retry to support retry-after.
TIMEOUT
session The session instance used by this service.
token The bearer token used in the requests.

Methods:

get_default_client() Retrieve the default client.
get_default_session_class() Get the default session class for Service.
ndarray(inputs, bands[, scales, data_type, …]) Retrieve a raster as a NumPy array.
raster(inputs, bands[, scales, data_type, …]) Given a list of image identifiers, retrieve a translated and warped mosaic as an image file.
set_default_client(client) Change the default client to the given client.
set_default_session_class(session_class) Set the default session class for Service.
stack(inputs, bands[, scales, data_type, …]) Retrieve a stack of rasters as a 4-D NumPy array.
classmethod get_default_client()

Retrieve the default client.

This client is used whenever you don’t explicitly set the client.

classmethod get_default_session_class()

Get the default session class for Service.

Returns:The default session class, which is Session itself or a derived class from Session.
Return type:Session
ndarray(inputs, bands, scales=None, data_type=None, srs=None, resolution=None, dimensions=None, cutline=None, place=None, bounds=None, bounds_srs=None, align_pixels=False, resampler=None, order='image', dltile=None, processing_level=None, output_window=None, headers=None, progress=None, masked=True, _retry=<function _retry>, **pass_through_params)[source]

Retrieve a raster as a NumPy array.

Parameters:
  • inputs – List of image identifiers.
  • bands – List of requested bands. If the last item in the list is an alpha band (with data range [0, 1]) it affects rastering of all other bands: When rastering multiple images, they are combined image-by-image only where each respective image’s alpha band is 1 (pixels where the alpha band is not 1 are “transparent” in the overlap between images). If a pixel is fully masked considering all combined alpha bands it will be 0 in all non-alpha bands.
  • scales – List of tuples specifying the scaling to be applied to each band. A tuple has 4 elements in the order (src_min, src_max, out_min, out_max), meaning values in the source range src_min to src_max will be scaled to the output range out_min to out_max. A tuple with 2 elements (src_min, src_max) is also allowed, in which case the output range defaults to (0, 255) (a useful default for the common output type Byte). If no scaling is desired for a band, use None. This tuple format and behaviour is identical to GDAL’s scales during translation. Example argument: [(0, 10000, 0, 127), (0, 1, 0, 1), (0, 10000)] - the first band will have source values 0-10000 scaled to 0-127, the second band will not be scaled, the third band will have 0-10000 scaled to 0-255.
  • data_type (str) – Output data type (one of Byte, UInt16, Int16, UInt32, Int32, Float32, Float64).
  • srs (str) – Output spatial reference system definition understood by GDAL.
  • resolution (float) – Desired resolution in output SRS units. Incompatible with dimensions
  • dimensions (tuple) – Desired output (width, height) in pixels within which the raster should fit; i.e. the longer side of the raster will be min(dimensions). Incompatible with resolution.
  • cutline (str) – A GeoJSON object to be used as a cutline, or WKT string. GeoJSON coordinates must be in WGS84 lat-lon.
  • place (str) – A slug identifier to be used as a cutline.
  • bounds (tuple) – (min_x, min_y, max_x, max_y) in target SRS.
  • bounds_srs (str) – Override the coordinate system in which bounds are expressed. If not given, bounds are assumed to be expressed in the output SRS.
  • align_pixels (bool) – Align pixels to the target coordinate system.
  • resampler (str) – Resampling algorithm to be used during warping (near, bilinear, cubic, cubicsplice, lanczos, average, mode, max, min, med, q1, q3).
  • order (str) – Order of the returned array. image returns arrays as (row, column, band) while gdal returns arrays as (band, row, column).
  • dltile (str) – a dltile key used to specify the resolution, bounds, and srs.
  • processing_level (str) – How the processing level of the underlying data should be adjusted, one of toa (top of atmosphere) and surface. For products that support it, surface applies Descartes Labs’ general surface reflectance algorithm to the output.
  • masked (bool) – Whether to return a masked array or a regular Numpy array.
  • progress (bool) – Display a progress bar.
Returns:

A tuple of (np_array, metadata). The first element (np_array) is the rastered scene as a NumPy array. The second element (metadata) is a dictionary containing details about the raster operation that happened. These details can be useful for debugging but shouldn’t otherwise be relied on (there are no guarantees that certain keys will be present).
raster(inputs, bands, scales=None, data_type=None, output_format='GTiff', srs=None, dimensions=None, resolution=None, bounds=None, bounds_srs=None, cutline=None, place=None, align_pixels=False, resampler=None, dltile=None, processing_level=None, outfile_basename=None, headers=None, progress=None, nodata=None, _retry=<function _retry>, **pass_through_params)[source]

Given a list of image identifiers, retrieve a translated and warped mosaic as an image file.

Parameters:
  • inputs – Iterable of image identifiers.
  • bands – List of requested bands. If the last item in the list is an alpha band (with data range [0, 1]) it affects rastering of all other bands: When rastering multiple images, they are combined image-by-image only where each respective image’s alpha band is 1 (pixels where the alpha band is not 1 are “transparent” in the overlap between images). If a pixel is fully masked considering all combined alpha bands it will be 0 in all non-alpha bands.
  • scales – List of tuples specifying the scaling to be applied to each band. A tuple has 4 elements in the order (src_min, src_max, out_min, out_max), meaning values in the source range src_min to src_max will be scaled to the output range out_min to out_max. A tuple with 2 elements (src_min, src_max) is also allowed, in which case the output range defaults to (0, 255) (a useful default for the common output type Byte). If no scaling is desired for a band, use None. This tuple format and behaviour is identical to GDAL’s scales during translation. Example argument: [(0, 10000, 0, 127), (0, 1, 0, 1), (0, 10000)] - the first band will have source values 0-10000 scaled to 0-127, the second band will not be scaled, the third band will have 0-10000 scaled to 0-255.
  • output_format (str) – Output format (one of GTiff, PNG, JPEG). The default is GTiff.
  • data_type (str) – Output data type (one of Byte, UInt16, Int16, UInt32, Int32, Float32, Float64).
  • srs (str) – Output spatial reference system definition understood by GDAL.
  • resolution (float) – Desired resolution in output SRS units. Incompatible with dimensions
  • dimensions (tuple) – Desired output (width, height) in pixels within which the raster should fit; i.e. the longer side of the raster will be min(dimensions). Incompatible with resolution.
  • cutline (str) – A GeoJSON object to be used as a cutline, or WKT string. GeoJSON coordinates must be in WGS84 lat-lon.
  • place (str) – A slug identifier to be used as a cutline.
  • bounds (tuple) – (min_x, min_y, max_x, max_y) in target SRS.
  • bounds_srs (str) – Override the coordinate system in which bounds are expressed. If not given, bounds are assumed to be expressed in the output SRS.
  • align_pixels (bool) – Align pixels to the target coordinate system.
  • resampler (str) – Resampling algorithm to be used during warping (near, bilinear, cubic, cubicsplice, lanczos, average, mode, max, min, med, q1, q3).
  • dltile (str) – a dltile key used to specify the resolution, bounds, and srs.
  • processing_level (str) – How the processing level of the underlying data should be adjusted, one of toa (top of atmosphere) and surface. For products that support it, surface applies Descartes Labs’ general surface reflectance algorithm to the output.
  • outfile_basename (str) – Overrides default filename using this string as a base.
  • progress (bool) – Display a progress bar.
  • or number (None) – A nodata value to use in the file where pixels are masked. Only used for non-JPEG geotiff files.
Returns:

A tuple of (filename, metadata dictionary). The dictionary contains details about the raster operation that happened. These details can be useful for debugging but shouldn’t otherwise be relied on (there are no guarantees that certain keys will be present).
classmethod set_default_client(client)

Change the default client to the given client.

This is the client that will be used whenever you don’t explicitly set the client

classmethod set_default_session_class(session_class)

Set the default session class for Service.

The default session is used for any Service that is instantiated without specifying the session class.

Parameters:session_class (class) – The session class to use when instantiating the session. This must be the class Session itself or a derived class from Session.
stack(inputs, bands, scales=None, data_type='UInt16', srs=None, resolution=None, dimensions=None, cutline=None, place=None, bounds=None, bounds_srs=None, align_pixels=False, resampler=None, order='image', dltile=None, processing_level=None, max_workers=None, masked=True, progress=None, **pass_through_params)[source]

Retrieve a stack of rasters as a 4-D NumPy array.

To ensure every raster in the stack has the same shape and covers the same spatial extent, you must either:

  • set dltile, or
  • set [resolution or dimensions], srs, and bounds
Parameters:
  • inputs – Iterable, or Iterable of Iterables, of image identifiers. The stack will follow the same order as this list. Each element in the list is treated as a separate input to raster.ndarray, so if a list of lists is given, each sublist’s identifiers will be mosaiced together to become a single level in the stack.
  • bands – List of requested bands. If the last item in the list is an alpha band (with data range [0, 1]) it affects rastering of all other bands: When rastering multiple images, they are combined image-by-image only where each respective image’s alpha band is 1 (pixels where the alpha band is not 1 are “transparent” in the overlap between images). If a pixel is fully masked considering all combined alpha bands it will be 0 in all non-alpha bands.
  • scales – List of tuples specifying the scaling to be applied to each band. A tuple has 4 elements in the order (src_min, src_max, out_min, out_max), meaning values in the source range src_min to src_max will be scaled to the output range out_min to out_max. A tuple with 2 elements (src_min, src_max) is also allowed, in which case the output range defaults to (0, 255) (a useful default for the common output type Byte). If no scaling is desired for a band, use None. This tuple format and behaviour is identical to GDAL’s scales during translation. Example argument: [(0, 10000, 0, 127), (0, 1, 0, 1), (0, 10000)] - the first band will have source values 0-10000 scaled to 0-127, the second band will not be scaled, the third band will have 0-10000 scaled to 0-255.
  • data_type (str) – Output data type (one of Byte, UInt16, Int16, UInt32, Int32, Float32, Float64).
  • srs (str) – Output spatial reference system definition understood by GDAL.
  • resolution (float) – Desired resolution in output SRS units. Incompatible with dimensions
  • dimensions (tuple) – Desired output (width, height) in pixels within which the raster should fit; i.e. the longer side of the raster will be min(dimensions). Incompatible with resolution.
  • cutline (str) – A GeoJSON object to be used as a cutline, or WKT string. GeoJSON coordinates must be in WGS84 lat-lon.
  • place (str) – A slug identifier to be used as a cutline.
  • bounds (tuple) – (min_x, min_y, max_x, max_y) in target SRS.
  • bounds_srs (str) – Override the coordinate system in which bounds are expressed. If not given, bounds are assumed to be expressed in the output SRS.
  • align_pixels (bool) – Align pixels to the target coordinate system.
  • resampler (str) – Resampling algorithm to be used during warping (near, bilinear, cubic, cubicsplice, lanczos, average, mode, max, min, med, q1, q3).
  • order (str) – Order of the returned array. image returns arrays as (scene, row, column, band) while gdal returns arrays as (scene, band, row, column).
  • dltile (str) – a dltile key used to specify the resolution, bounds, and srs.
  • processing_level (str) – How the processing level of the underlying data should be adjusted, one of toa (top of atmosphere) and surface. For products that support it, surface applies Descartes Labs’ general surface reflectance algorithm to the output.
  • max_workers (int) – Maximum number of threads over which to parallelize individual ndarray calls. If None, will be set to the minimum of the number of inputs and DEFAULT_MAX_WORKERS.
  • masked (bool) – Whether to return a masked array or a regular Numpy array.
  • progress (bool) – Display a progress bar.
Returns:

A tuple of (stack, metadata).

  • stack: 4D ndarray. The axes are ordered (scene, band, y, x) (or (scene, y, x, band) if order="gdal"). The scenes in the outermost axis are in the same order as the list of identifiers given as inputs.
  • metadata: List[dict] of the rasterization metadata for each element in inputs. As with the metadata returned by ndarray() and raster(), these dictionaries contain useful information about the raster, such as its geotransform matrix and WKT of its coordinate system, but there are no guarantees that certain keys will be present.
CONNECT_TIMEOUT = 9.5
READ_TIMEOUT = 300
RETRY_CONFIG(*args, **kwargs)

Retry configuration that extends urllib3.util.retry to support retry-after.

This retry configuration class derives from urllib3.util.retry.Retry.

Parameters:retry_after_status_codes (list) – The http status codes that should support the Retry-After header.
TIMEOUT = (9.5, 300)
property session

The session instance used by this service.

Type:Session
property token

The bearer token used in the requests.

Type:str