Raster

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

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

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

Example:

>>> from descarteslabs.client.services import Raster
>>> Raster().dltile("1024:16:15.0:41:-16:324")
{
  'geometry': {
    'coordinates': [
      [
        [59.88428127486419, 44.89851158847289],
        [60.08463455818353, 44.90380671613201],
        [60.077403974563175, 45.046212550598135],
        [59.87655568675822, 45.040891215906676],
        ...
      ]
    ],
    'type': 'Polygon'
  },
  'properties': {
    'cs_code': 'EPSG:32641',
    'key': '1024:16:15.0:41:-16:324',
    'outputBounds': [254000.0, 4976400.0, 269840.0, 4992240.0],
    'pad': 16,
    'resolution': 15.0,
    'ti': -16,
    'tilesize': 1024,
    'tj': 324,
    '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

Example:

>>> from descarteslabs.client.services import Raster
>>> Raster().dltile_from_latlon(45, 60, 15.0, 1024, 16)
{
  'geometry': {
    'coordinates': [
      [
        [59.88428127486419, 44.89851158847289],
        [60.08463455818353, 44.90380671613201],
        [60.077403974563175, 45.046212550598135],
        [59.87655568675822, 45.040891215906676],
        ...
      ]
    ],
    'type': 'Polygon'
  },
  'properties': {
    'cs_code': 'EPSG:32641',
    'key': '1024:16:15.0:41:-16:324',
    'outputBounds': [254000.0, 4976400.0, 269840.0, 4992240.0],
    'pad': 16,
    'resolution': 15.0,
    'ti': -16,
    'tilesize': 1024,
    'tj': 324,
    '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.

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.

Example:

>>> from descarteslabs.client.services import Raster, Places
>>> iowa = Places().shape("north-america_united-states_iowa")
>>> tiles = Raster().dltiles_from_shape(30.0, 2048, 16, iowa)
>>> tiles['features'][0]
{
  'geometry': {
    'coordinates': [
      [
        [-96.81264975325402, 41.045203319986356],
        [-96.07101667769108, 41.02873098016475],
        [-96.04576296033223, 41.59007261142797],
        [-96.79377566762066, 41.60687154946031],
        ...
      ]
    ],
    'type': 'Polygon'
  },
  'properties': {
    'cs_code': 'EPSG:32614',
    'key': '2048:16:30.0:14:3:74',
    'outputBounds': [683840.0, 4546080.0, 746240.0, 4608480.0],
    'pad': 16,
    'resolution': 30.0,
    'ti': 3,
    'tilesize': 2048,
    'tj': 74,
    '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, **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 [0, 1, 0, 1]. 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.
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, save=False, outfile_basename=None, **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 [0, 1, 0, 1]. 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.
  • 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. The value for files is 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). The value for 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).

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, 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, 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 [0, 1, 0, 1]. 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.
  • 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.
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.