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,
    crs='EPSG:32615',
    align_pixels=True,
    bounds=(-95.8364984, 40.703737, -93.1167728, 42.7999878),
    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, 15259, 15340)
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

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

properties

DotDict – 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"

__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 instead.

coverage(ctx)[source]

Returns the fraction of the GeoContext geometry covered by the scene geometry.

Parameters:ctx (GeoContext) – A GeoContext to use when computing coverage
Returns:
Return type:float

Example

>>> import descarteslabs as dl
>>> scene, ctx = dl.scenes.Scene.from_id("landsat:LC08:PRE:TOAR:meta_LC80270312016188_v1")
>>> coverage = scene.coverage(ctx)  
>>> coverage  
1.0
download(bands, ctx, dest=None, format='tif', 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”).

  • 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)  
"landsat:LC08:PRE:TOAR:meta_LC80270312016188_v1_red-green-blue.tif"
>>> import os
>>> os.listdir(".")  
["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)
... )  
"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")  
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 with reasonable defaults to use when loading the Scene’s ndarray.

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 default GeoContext useful for loading this Scene. These defaults are used:
    • bounds: bounds of the Scene’s geometry
    • resolution: the finest resolution of any band in the scene
    • crs: native CRS of the Scene (generally, a UTM CRS)
    • align_pixels: True

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,
    crs='EPSG:32615',
    align_pixels=True,
    bounds=(-94.724166, 39.2784859, -92.0686956, 41.3717716),
    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', 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 SRS. Possible values are near (nearest-neighbor), bilinear, cubic, cubicsplice, lanczos, average, mode, max, min, med, q1, q3.
  • 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, 15259, 15340)
>>> 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