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 or dict – The region the scene’s data covers, in WGS84 (lat-lon) coordinates. If the Shapely package is installed, it will be a shapely Polygon, otherwise a dict of a GeoJSON 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.

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