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:

ADAPTER

CONNECT_TIMEOUT

READ_TIMEOUT

RETRY_CONFIG(*args, **kwargs)

Retry configuration.

TIMEOUT

session

The session instance used by this service.

token

The bearer token used in the requests.

Methods:

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 Metadata identifiers, retrieve a translated and warped mosaic as an image file.

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_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=None, 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 Metadata 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. Not specifying bands returns all bands in the product.

  • 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=None, 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 Metadata identifiers, retrieve a translated and warped mosaic as an image file.

Parameters
  • inputs – List of Metadata 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. Not specifying bands returns all bands in the product.

  • 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_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=None, 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 – List, or list of lists, of Metadata 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. Not specifying bands returns all bands in the product.

  • 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.

ADAPTER = <descarteslabs.common.threading.local.ThreadLocalWrapper object>
CONNECT_TIMEOUT = 9.5
READ_TIMEOUT = 300
RETRY_CONFIG(*args, **kwargs)

Retry configuration.

Each retry attempt will create a new Retry object with updated values, so they can be safely reused.

Retries can be defined as a default for a pool:

retries = Retry(connect=5, read=2, redirect=5)
http = PoolManager(retries=retries)
response = http.request('GET', 'http://example.com/')

Or per-request (which overrides the default for the pool):

response = http.request('GET', 'http://example.com/', retries=Retry(10))

Retries can be disabled by passing False:

response = http.request('GET', 'http://example.com/', retries=False)

Errors will be wrapped in MaxRetryError unless retries are disabled, in which case the causing exception will be raised.

Parameters
  • total (int) –

    Total number of retries to allow. Takes precedence over other counts.

    Set to None to remove this constraint and fall back on other counts.

    Set to 0 to fail on the first retry.

    Set to False to disable and imply raise_on_redirect=False.

  • connect (int) –

    How many connection-related errors to retry on.

    These are errors raised before the request is sent to the remote server, which we assume has not triggered the server to process the request.

    Set to 0 to fail on the first retry of this type.

  • read (int) –

    How many times to retry on read errors.

    These errors are raised after the request was sent to the server, so the request may have side-effects.

    Set to 0 to fail on the first retry of this type.

  • redirect (int) –

    How many redirects to perform. Limit this to avoid infinite redirect loops.

    A redirect is a HTTP response with a status code 301, 302, 303, 307 or 308.

    Set to 0 to fail on the first retry of this type.

    Set to False to disable and imply raise_on_redirect=False.

  • status (int) –

    How many times to retry on bad status codes.

    These are retries made on responses, where status code matches status_forcelist.

    Set to 0 to fail on the first retry of this type.

  • other (int) –

    How many times to retry on other errors.

    Other errors are errors that are not connect, read, redirect or status errors. These errors might be raised after the request was sent to the server, so the request might have side-effects.

    Set to 0 to fail on the first retry of this type.

    If total is not set, it’s a good idea to set this to 0 to account for unexpected edge cases and avoid infinite retry loops.

  • allowed_methods (iterable) –

    Set of uppercased HTTP method verbs that we should retry on.

    By default, we only retry on methods which are considered to be idempotent (multiple requests with the same parameters end with the same state). See Retry.DEFAULT_ALLOWED_METHODS.

    Set to a False value to retry on any verb.

    Warning

    Previously this parameter was named method_whitelist, that usage is deprecated in v1.26.0 and will be removed in v2.0.

  • status_forcelist (iterable) –

    A set of integer HTTP status codes that we should force a retry on. A retry is initiated if the request method is in allowed_methods and the response status code is in status_forcelist.

    By default, this is disabled with None.

  • backoff_factor (float) –

    A backoff factor to apply between attempts after the second try (most errors are resolved immediately by a second try without a delay). urllib3 will sleep for:

    {backoff factor} * (2 ** ({number of total retries} - 1))
    

    seconds. If the backoff_factor is 0.1, then sleep() will sleep for [0.0s, 0.2s, 0.4s, …] between retries. It will never be longer than Retry.DEFAULT_BACKOFF_MAX.

    By default, backoff is disabled (set to 0).

  • raise_on_redirect (bool) – Whether, if the number of redirects is exhausted, to raise a MaxRetryError, or to return a response with a response code in the 3xx range.

  • raise_on_status (bool) – Similar meaning to raise_on_redirect: whether we should raise an exception, or return a response, if status falls in status_forcelist range and retries have been exhausted.

  • history (tuple) – The history of the request encountered during each call to increment(). The list is in the order the requests occurred. Each list item is of class RequestHistory.

  • respect_retry_after_header (bool) – Whether to respect Retry-After header on status codes defined as Retry.RETRY_AFTER_STATUS_CODES or not.

  • remove_headers_on_redirect (iterable) – Sequence of headers to remove from the request when a response indicating a redirect is returned before firing off the redirected request.

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