Raster

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

The Raster API has two purposes: retrieving data from the Descartes Labs Catalog, and providing a consistent way of splitting that data into smaller tiles.

Parameters
  • url (str) – A HTTP URL pointing to a version of the storage service (defaults to current version)

  • auth (Auth) – A custom user authentication (defaults to the user authenticated locally by token information on disk or by environment variables)

  • retries (urllib3.util.retry.Retry) – A custom retry configuration used for all API requests (defaults to a reasonable amount of retries)

dltile(key)[source]

Given a DLTile key, return a DLTile GeoJSON Feature

Parameters

key (str) – A DLTile key that identifies a DLTile

Returns

A DLTile GeoJSON Feature

Return type

DotDict

Raises

descarteslabs.client.exceptions.BadRequestError – if the given key is not a valid DLTile key

Example:

>>> from descarteslabs.client.services import Raster
>>> Raster().dltile("1024:16:15.0:41:-16:324")
{
  'geometry': {
    'coordinates': [
      [
        [59.88428127486419, 44.8985115884728...],
        [60.08463455818353, 44.90380671613201],
        [60.077403974563175, 45.046212550598135],
        [59.87655568675822, 45.040891215906676],
        ...
      ]
    ],
    'type': 'Polygon'
  },
  'properties': {
    'cs_code': 'EPSG:32641',
    'geotrans': [
      254000.0,
      15.0,
      0,
      4992240.0,
      ...
    ],
    'key': '1024:16:15.0:41:-16:324',
    'outputBounds': [254000.0, 4976400.0, 269840.0, 4992240.0],
    'pad': 16,
    'proj4': '+proj=utm +zone=41 +datum=WGS84 +units=m +no_defs ',
    'resolution': 15.0,
    'ti': -16,
    'tilesize': 1024,
    'tj': 324,
    'wkt': 'PROJCS["WGS 84 / UTM zone 41N",GEOGCS["WGS...Northing",NORTH],AUTHORITY["EPSG","32641"]]',
    'zone': 41
  },
  'type': 'Feature'
}
dltile_from_latlon(lat, lon, resolution, tilesize, pad)[source]

Return a DLTile GeoJSON Feature that covers a latitude/longitude

Parameters
  • lat (float) – Requested latitude

  • lon (float) – Requested longitude

  • resolution (float) – Resolution of DLTile

  • tilesize (int) – Number of valid pixels per DLTile

  • pad (int) – Number of ghost pixels per DLTile (overlap among tiles)

Returns

A DLTile GeoJSON Feature

Return type

DotDict

Example:

>>> from descarteslabs.client.services import Raster
>>> Raster().dltile_from_latlon(45, 60, 15.0, 1024, 16)
{
  'geometry': {
    'coordinates': [
      [
        [59.88428127486419, 44.8985115884728...],
        [60.08463455818353, 44.90380671613201],
        [60.077403974563175, 45.046212550598135],
        [59.87655568675822, 45.040891215906676],
        ...
      ]
    ],
    'type': 'Polygon'
  },
  'properties': {
    'cs_code': 'EPSG:32641',
    'geotrans': [
      254000.0,
      15.0,
      0,
      4992240.0,
      ...
    ],
    'key': '1024:16:15.0:41:-16:324',
    'outputBounds': [254000.0, 4976400.0, 269840.0, 4992240.0],
    'pad': 16,
    'proj4': '+proj=utm +zone=41 +datum=WGS84 +units=m +no_defs ',
    'resolution': 15.0,
    'ti': -16,
    'tilesize': 1024,
    'tj': 324,
    'wkt': 'PROJCS["WGS 84 / UTM zone 41N",GEOGCS["WGS...Northing",NORTH],AUTHORITY["EPSG","32641"]]',
    'zone': 41
  },
  'type': 'Feature'
}
dltiles_from_shape(resolution, tilesize, pad, shape)[source]

Return a feature collection of DLTile GeoJSONs that intersect a GeoJSON geometry shape or a Shapely shape object.

Parameters
  • resolution (float) – Resolution of DLTile

  • tilesize (int) – Number of valid pixels per DLTile

  • pad (int) – Number of ghost pixels per DLTile (overlap among tiles)

  • shape (str) – A GeoJSON geometry specifying a shape over which to intersect DLTiles

Returns

GeoJSON FeatureCollection of intersecting DLTile geometries.

Return type

DotDict

Raises

descarteslabs.client.exceptions.BadRequestError – if the given parameters would generate too many tiles - use Raster.iter_dltiles_from_shape() to iterate over more

Example:

>>> from descarteslabs.client.services import Raster
>>> iowa_geom = {
...     "coordinates": [[
...         [-96.498997, 42.560832],
...         [-95.765645, 40.585208],
...         [-91.729115, 40.61364],
...         [-91.391613, 40.384038],
...         [-90.952233, 40.954047],
...         [-91.04589, 41.414085],
...         [-90.343228, 41.587833],
...         [-90.140613, 41.995999],
...         [-91.065059, 42.751338],
...         [-91.217706, 43.50055],
...         [-96.599191, 43.500456],
...         [-96.498997, 42.560832]
...     ]],
...     "type": "Polygon"
... }
>>> tiles = Raster().dltiles_from_shape(30.0, 2048, 16, iowa_geom)
>>> tiles['features'][0]
{
  'geometry': {
    'coordinates': [
      [
        [-96.81264975325402, 41.045203319986356],
        [-96.07101667769108, 41.02873098016475],
        [-96.04576296033223, 41.59007261142797],
        [-96.79377566762066, 41.6068715494603...],
        ...
      ]
    ],
    'type': 'Polygon'
  },
  'properties': {
    'cs_code': 'EPSG:32614',
    'geotrans': [
      683840.0,
      30.0,
      0,
      4608480.0,
      ...
    ],
    'key': '2048:16:30.0:14:3:74',
    'outputBounds': [683840.0, 4546080.0, 746240.0, 4608480.0],
    'pad': 16,
    'proj4': '+proj=utm +zone=14 +datum=WGS84 +units=m +no_defs ',
    'resolution': 30.0,
    'ti': 3,
    'tilesize': 2048,
    'tj': 74,
    'wkt': 'PROJCS["WGS 84 / UTM zone 14N",GEOGCS["WGS...Northing",NORTH],AUTHORITY["EPSG","32614"]]',
    'zone': 14
  },
  'type': 'Feature'
}
iter_dltiles_from_shape(resolution, tilesize, pad, shape, maxtiles=5000)[source]

Iterates over all DLTiles as GeoJSONs features that intersect the GeoJSON geometry shape or Shapely shape object.

Parameters
  • resolution (float) – Resolution of DLTile

  • tilesize (int) – Number of valid pixels per DLTile

  • pad (int) – Number of ghost pixels per DLTile (overlap among tiles)

  • shape (str) – A GeoJSON geometry or Shapely shape specifying a shape over which to intersect DLTiles.

  • maxtiles (int) – Maximum number of tiles per paged request

Returns

An iterator over GeoJSON features representing intersecting DLTiles

Return type

generator(DotDict)

Example:

>>> iowa_geom = {
...     "coordinates": [[
...         [-96.498997, 42.560832],
...         [-95.765645, 40.585208],
...         [-91.729115, 40.61364],
...         [-91.391613, 40.384038],
...         [-90.952233, 40.954047],
...         [-91.04589, 41.414085],
...         [-90.343228, 41.587833],
...         [-90.140613, 41.995999],
...         [-91.065059, 42.751338],
...         [-91.217706, 43.50055],
...         [-96.599191, 43.500456],
...         [-96.498997, 42.560832]
...     ]],
...     "type": "Polygon"
... }
>>> next(Raster().iter_dltiles_from_shape(30.0, 2048, 16, iowa_geom))
{
  'geometry': {
    'coordinates': [
      [
        [-96.81264975325402, 41.045203319986356],
        [-96.07101667769108, 41.02873098016475],
        [-96.04576296033223, 41.59007261142797],
        [-96.79377566762066, 41.6068715494603...],
        ...
      ]
    ],
    'type': 'Polygon'
  },
  'properties': {
    'cs_code': 'EPSG:32614',
    'geotrans': [
      683840.0,
      30.0,
      0,
      4608480.0,
      ...
    ],
    'key': '2048:16:30.0:14:3:74',
    'outputBounds': [683840.0, 4546080.0, 746240.0, 4608480.0],
    'pad': 16,
    'proj4': '+proj=utm +zone=14 +datum=WGS84 +units=m +no_defs ',
    'resolution': 30.0,
    'ti': 3,
    'tilesize': 2048,
    'tj': 74,
    'wkt': 'PROJCS["WGS 84 / UTM zone 14N",GEOGCS["WGS...Northing",NORTH],AUTHORITY["EPSG","32614"]]',
    'zone': 14
  },
  'type': 'Feature'
}
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, **pass_through_params)[source]

Retrieve a raster as a NumPy array.

Parameters
  • inputs (list(str)) – List of catalog image identifiers.

  • bands (list(str)) – 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(tuple())) – 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.

Returns

A tuple of (np_array, metadata).

  • np_array: the rastered scene as a NumPy array

  • metadata: 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).

Return type

tuple(numpy.ndarray, DotDict)

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, save=False, outfile_basename=None, **pass_through_params)[source]

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

Parameters
  • inputs (list(str)) – List of catalog image identifiers.

  • bands (list(str)) – 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(tuple())) – 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).

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

  • save (bool) – Write resulting files to disk. Default: False

  • outfile_basename (str) – If save is True, override default filename using this string as a base.

Returns

A dictionary with two keys, files and metadata.

  • files: a dictionary mapping file names to binary data for files (at the moment there will always be only a single file with the appropriate file extension based on the output_format requested)

  • metadata: 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).

Return type

DotDict

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, **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|list(list)) – List, or list of lists, of catalog image identifiers. The stack will follow the same order as this list. Each element in the list is treated as a separate input to ndarray(), so if a list of lists is given, each sublist’s identifiers will be mosaicked together to become a single level in the stack.

  • bands (list(str)) – 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(tuple())) – 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. Maximum number of workers allowed is 25.

Returns

A tuple of (stack, metadata).

  • stack: 4D ndarray. The axes are ordered (scene, y, x, band) (or (scene, band, y, x) if order="gdal"). The scenes in the outermost axis are in the same order as the list of identifiers given as inputs.

  • metadata: list 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.

Return type

tuple(numpy.ndarray, list(DotDict))