Scene

Back to Scenes

The Scene class holds metadata about a single scene in the Descartes Labs catalog.

Example

>>> import descarteslabs as dl
>>> scene, ctx = dl.scenes.Scene.from_id("landsat:LC08:PRE:TOAR:meta_LC80270312016188_v1")
>>> ctx  # a default GeoContext to use when loading raster data from this Scene
AOI(geometry=None,
    resolution=15.0,
    crs='EPSG:32615',
    align_pixels=False,
    bounds=(258292.5, 4503907.5, 493732.5, 4743307.5),
    bounds_crs='EPSG:32615',
    shape=None)
>>> scene.properties.id
'landsat:LC08:PRE:TOAR:meta_LC80270312016188_v1'
>>> scene.properties.date
datetime.datetime(2016, 7, 6, 16, 59, 42, 753476)
>>> scene.properties.bands.red.resolution
15
>>> arr = scene.ndarray("red green blue", ctx)
>>> type(arr)
<class 'numpy.ma.core.MaskedArray'>
>>> arr.shape
(3, 15960, 15696)
class Scene(scene_dict, bands_dict)[source]

Object holding metadata about a single scene in the Descartes Labs catalog.

A Scene is structured like a GeoJSON Feature, with geometry and properties.

geometry

The region the scene’s data covers, in WGS84 (lat-lon) coordinates, represented as a Shapely polygon.

Type:shapely.geometry.Polygon
properties

Metadata about the scene. Some fields will vary between products, but these will be present:

  • id : str

    Descartes Labs ID of this scene

  • crs : str

    Native coordinate reference system of the scene, as an EPSG code or PROJ.4 definition

  • date : datetime.datetime

    'acquired' date parsed as a Python datetime if set, otherwise None

  • bands : DotDict[str, DotDict]

    Metadata about the bands available in the scene, as the mapping {band name: band metadata}.

    Band names are either the band’s name field (like “red”), or for derived bands, the band’s id (like “derived:ndvi”).

    Each band metadata dict should contain these fields:

    • id : str
      Descartes Labs ID of the band; unique to every band of every product
    • name : str
      Human-readable name of the band
    • dtype : str
      Native type in which the band’s data is stored
    • data_range : list
      List of [min, max] values the band’s data can have

    These fields are useful and available in most products, but may not always be available:

    • resolution : float
      Native resolution of the band, in resolution_unit, that the edge of each pixel represents on the ground
    • resolution_unit : str
      Units of resolution field, such as "m"
    • physical_range : list
      [min, max] range of values the band’s data represents. Values of data have physical meaning (such as a reflectance fraction from 0-1), but often those values are remapped to a different numerical range for more efficient storage (since fixed-point integers require less space than floats). To return data to numbers with physical meaning, they should be mapped from data_range to physical_range.
    • wavelength_min
      Minimum wavelength captured by the sensor in this band
    • wavelength_center
      Central wavelength captured by the sensor in this band
    • wavelength_max
      Maximum wavelength captured by the sensor in this band
    • wavelength_unit
      Units of the wavelength fields, such as "nm"
Type:DotDict

__init__ instantiates a Scene from a dict returned by Metadata.search and Metadata.get_bands_by_id.

It’s preferred to use Scene.from_id or scenes.search <scenes._search.search> instead.

coverage(geom)[source]

The fraction of a geometry-like object covered by this Scene’s geometry.

Parameters:geom (GeoJSON-like dict, GeoContext, or object with __geo_interface__) – Geometry to which to compare this Scene’s geometry
Returns:coverage – The fraction of geom’s area that overlaps with this Scene, between 0 and 1.
Return type:float

Example

>>> import descarteslabs as dl
>>> scene, ctx = dl.scenes.Scene.from_id("landsat:LC08:PRE:TOAR:meta_LC80270312016188_v1")
>>> scene.coverage(scene.geometry.buffer(1))  # doctest: +SKIP
0.8
default_ctx()[source]

Return an AOI GeoContext for loading this Scene’s original, unwarped data.

These defaults are used:

  • resolution: resolution determined from the Scene’s geotrans
  • crs: native CRS of the Scene (often, a UTM CRS)
  • bounds: bounds determined from the Scene’s geotrans and raster_size
  • bounds_crs: native CRS of the Scene
  • align_pixels: False, to prevent interpolation snapping pixels to a new grid
  • geometry: None

Note

Using this GeoContext will only return original, unwarped data if the Scene is axis-aligned (“north-up”) within the CRS. If its geotrans applies a rotation, a warning will be raised. In that case, use Raster.ndarray or Raster.raster to retrieve original data. (The GeoContext paradigm requires bounds for consistentcy, which are inherently axis-aligned.)

Returns:ctx
Return type:AOI
download(bands, ctx, dest=None, format='tif', resampler='near', processing_level=None, raster_client=None)[source]

Save bands from this scene as a GeoTIFF, PNG, or JPEG, writing to a path or file-like object.

Parameters:
  • bands (str or Sequence[str]) – Band names to load. Can be a single string of band names separated by spaces ("red green blue derived:ndvi"), or a sequence of band names (["red", "green", "blue", "derived:ndvi"]). Names must be keys in self.properties.bands.
  • ctx (GeoContext) – A GeoContext to use when loading this Scene
  • dest (str, path-like object, or file-like object, default None) –

    Where to write the image file.

    • If None (default), it’s written to an image file of the given format in the current directory, named by the Scene’s ID and requested bands, like "sentinel-2:L1C:2018-08-10_10TGK_68_S2A_v1-red-green-blue.tif"
    • If a string or path-like object, it’s written to that path.

      Any file already existing at that path will be overwritten.

      Any intermediate directories will be created if they don’t exist.

      Note that path-like objects (such as pathlib.Path) are only supported in Python 3.6 or later.

    • If a file-like object, it’s written into that file.
  • format (str, default "tif") –

    If a file-like object or None is given as dest: one of “tif”, “png”, or “jpg”.

    If a str or path-like object is given as dest, format is ignored and determined from the extension on the path (one of “.tif”, “.png”, or “.jpg”).

  • resampler (str, default "near") – Algorithm used to interpolate pixel values when scaling and transforming the image to its new resolution or SRS. Possible values are near (nearest-neighbor), bilinear, cubic, cubicsplice, lanczos, average, mode, max, min, med, q1, q3.
  • processing_level (str, optional) – How the processing level of the underlying data should be adjusted. Possible values are toa (top of atmosphere) and surface. For products that support it, surface applies Descartes Labs’ general surface reflectance algorithm to the output.
  • raster_client (Raster, optional) – Unneeded in general use; lets you use a specific client instance with non-default auth and parameters.
Returns:

path – If dest is None or a path, the path where the image file was written is returned. If dest is file-like, nothing is returned.

Return type:

str or None

Example

>>> import descarteslabs as dl
>>> scene, ctx = dl.scenes.Scene.from_id("landsat:LC08:PRE:TOAR:meta_LC80270312016188_v1")
>>> scene.download("red green blue", ctx)  # doctest: +SKIP
"landsat:LC08:PRE:TOAR:meta_LC80270312016188_v1_red-green-blue.tif"
>>> import os
>>> os.listdir(".")  # doctest: +SKIP
["landsat:LC08:PRE:TOAR:meta_LC80270312016188_v1_red-green-blue.tif"]
>>> scene.download(
...     "nir swir1",
...     ctx,
...     "rasters/{ctx.resolution}-{scene.properties.id}.jpg".format(ctx=ctx, scene=scene)
... )  # doctest: +SKIP
"rasters/15-landsat:LC08:PRE:TOAR:meta_LC80270312016188_v1.tif"
>>> with open("another_raster.jpg", "wb") as f:
...     scene.download("swir2", ctx, dest=f, format="jpg")  # doctest: +SKIP
Raises:
  • ValueError – If requested bands are unavailable. If band names are not given or are invalid. If the requested bands have different dtypes. If format is invalid, or the path has an invalid extension.
  • NotFoundError – If a Scene’s ID cannot be found in the Descartes Labs catalog
  • BadRequestError – If the Descartes Labs platform is given invalid parameters
classmethod from_id(scene_id, metadata_client=None)[source]

Return the metadata for a Descartes Labs scene ID as a Scene object.

Also returns a GeoContext for loading the Scene’s original, unwarped data.

Parameters:
  • scene_id (str) – Descartes Labs scene ID, e.g. “landsat:LC08:PRE:TOAR:meta_LC80270312016188_v1”
  • metadata_client (Metadata, optional) – Unneeded in general use; lets you use a specific client instance with non-default auth and parameters.
Returns:

  • scene (Scene) – Scene instance with metadata loaded from the Descartes Labs catalog
  • ctx (AOI) – A GeoContext for loading this Scene’s original data. The defaults used are described in Scene.default_ctx.

Example

>>> import descarteslabs as dl
>>> scene, ctx = dl.scenes.Scene.from_id("landsat:LC08:PRE:TOAR:meta_LC80260322016197_v1")
>>> ctx
AOI(geometry=None,
    resolution=15.0,
    crs='EPSG:32615',
    align_pixels=False,
    bounds=(348592.5, 4345567.5, 581632.5, 4582807.5),
    bounds_crs='EPSG:32615',
    shape=None)
>>> scene.properties.date
datetime.datetime(2016, 7, 15, 16, 53, 59, 495435)
Raises:NotFoundError – If the scene_id cannot be found in the Descartes Labs catalog
ndarray(bands, ctx, mask_nodata=True, mask_alpha=True, bands_axis=0, raster_info=False, resampler='near', processing_level=None, raster_client=None)[source]

Load bands from this scene as an ndarray, optionally masking invalid data.

Parameters:
  • bands (str or Sequence[str]) – Band names to load. Can be a single string of band names separated by spaces ("red green blue derived:ndvi"), or a sequence of band names (["red", "green", "blue", "derived:ndvi"]). Names must be keys in self.properties.bands. If the alpha band is requested, it must be last in the list to reduce rasterization errors.
  • ctx (GeoContext) – A GeoContext to use when loading this Scene
  • mask_nodata (bool, default True) – Whether to mask out values in each band that equal that band’s nodata sentinel value.
  • mask_alpha (bool, default True) – Whether to mask pixels in all bands where the alpha band is 0.
  • bands_axis (int, default 0) –

    Axis along which bands should be located in the returned array. If 0, the array will have shape (band, y, x), if -1, it will have shape (y, x, band).

    It’s usually easier to work with bands as the outermost axis, but when working with large arrays, or with many arrays concatenated together, NumPy operations aggregating each xy point across bands can be slightly faster with bands as the innermost axis.

  • raster_info (bool, default False) – Whether to also return a dict of information about the rasterization of the scene, including the coordinate system WKT and geotransform matrix. Generally only useful if you plan to upload data derived from this scene back to the Descartes catalog, or use it with GDAL.
  • resampler (str, default "near") – Algorithm used to interpolate pixel values when scaling and transforming the image to its new resolution or CRS. Possible values are near (nearest-neighbor), bilinear, cubic, cubicsplice, lanczos, average, mode, max, min, med, q1, q3.
  • processing_level (str, optional) – How the processing level of the underlying data should be adjusted. Possible values are toa (top of atmosphere) and surface. For products that support it, surface applies Descartes Labs’ general surface reflectance algorithm to the output.
  • raster_client (Raster, optional) – Unneeded in general use; lets you use a specific client instance with non-default auth and parameters.
Returns:

  • arr (ndarray) – Returned array’s shape will be (band, y, x) if bands_axis is 0, (y, x, band) if bands_axis is -1 If mask_nodata or mask_alpha is True, arr will be a masked array.
  • raster_info (dict) – If raster_info=True, a raster information dict is also returned.

Example

>>> import descarteslabs as dl
>>> scene, ctx = dl.scenes.Scene.from_id("landsat:LC08:PRE:TOAR:meta_LC80270312016188_v1")
>>> arr = scene.ndarray("red green blue", ctx)
>>> type(arr)
<class 'numpy.ma.core.MaskedArray'>
>>> arr.shape
(3, 15960, 15696)
>>> red_band = arr[0]
Raises:
  • ValueError – If requested bands are unavailable. If band names are not given or are invalid. If the requested bands have different dtypes.
  • NotFoundError – If a Scene’s ID cannot be found in the Descartes Labs catalog
  • BadRequestError – If the Descartes Labs platform is given invalid parameters