Scene¶
-
class
Scene
(image: descarteslabs.catalog.image.Image)[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
strDescartes Labs ID of this scene
crs
strNative 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’sid
(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
tophysical_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-like
__init__
instantiates a Scene by wrapping adescarteslabs.catalog.Image
instead.It’s preferred to use
Scene.from_id
orscenes.search
instead.Methods:
coverage
(geom)The fraction of a geometry-like object covered by this Scene’s geometry. default_ctx
()Return an AOI GeoContext
for loading this Scene’s original, unwarped data.download
(bands, ctx[, dest, format, …])Save bands from this scene as a GeoTIFF, PNG, or JPEG, writing to a path. from_id
(scene_id)Return the metadata for a Descartes Labs scene ID as a Scene object. ndarray
(bands, ctx[, mask_nodata, …])Load bands from this scene as an ndarray, optionally masking invalid data. scaling_parameters
(bands[, …])Computes fully defaulted scaling parameters and output data_type from provided specifications. -
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__ # noqa: E501) – Geometry to which to compare this Scene’s geometryReturns: 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)) 0.258370644415335
-
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
andraster_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 itsgeotrans
applies a rotation, a warning will be raised. In that case, useRaster.ndarray
orRaster.raster
to retrieve original data. (TheGeoContext
paradigm requires bounds for consistentcy, which are inherently axis-aligned.)Returns: ctx Return type: AOI - resolution: resolution determined from the Scene’s
-
download
(bands, ctx, dest=None, format='tif', resampler='near', processing_level=None, scaling=None, data_type=None, nodata=None, progress=None)[source]¶ Save bands from this scene as a GeoTIFF, PNG, or JPEG, writing to a path.
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 inself.properties.bands
. - ctx (
GeoContext
) – AGeoContext
to use when loading this Scene - dest (str or path-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 None (default), it’s written to an image file of the given
- format (str, default "tif") –
If 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 depend on the product and bands in use. Legacy products support
toa
(top of atmosphere) and in some casessurface
. Consult the availableprocessing_levels
in the product bands to understand what is available. - scaling (None, str, list, dict) – Band scaling specification. Please see
scaling_parameters()
for a full description of this parameter. - data_type (None, str) – Output data type. Please see
scaling_parameters()
for a full description of this parameter. - nodata (None, number) – NODATA value for a geotiff file. Will be assigned to any masked pixels.
- progress (None, bool) – Controls display of a progress bar.
Returns: path – If
dest
is None or a path, the path where the image file was written is returned. Ifdest
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.assign(resolution=120.)) "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( ... "red green blue", ... ctx, ... "rasters/{ctx.resolution}-{scene.properties.id}.jpg".format(ctx=ctx, scene=scene) ... ) "rasters/15-landsat:LC08:PRE:TOAR:meta_LC80270312016188_v1.tif"
Raises: - ValueError – If requested bands are unavailable.
If band names are not given or are invalid.
If the requested bands have incompatible 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
- bands (str or Sequence[str]) – Band names to load. Can be a single string of band names
separated by spaces (
-
classmethod
from_id
(scene_id)[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 inScene.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. all_touched=True) >>> scene.properties.date datetime.datetime(2016, 7, 15, 16, 53, 59, 495435, tzinfo=<UTC>)
Raises: NotFoundError – If the scene_id
cannot be found in the Descartes Labs catalog
-
ndarray
(bands, ctx, mask_nodata=True, mask_alpha=None, bands_axis=0, raster_info=False, resampler='near', processing_level=None, scaling=None, data_type=None, progress=None)[source]¶ Load bands from this scene as an ndarray, optionally masking invalid data.
If the selected bands have different data types the resulting ndarray has the most general of those data types. This table defines which data types can be cast to which more general data types:
Byte
to:UInt16
,UInt32
,Int16
,Int32
,Float32
,Float64
UInt16
to:UInt32
,Int32
,Float32
,Float64
UInt32
to:Float64
Int16
to:Int32
,Float32
,Float64
Int32
to:Float32
,Float64
Float32
to:Float64
Float64
to: No possible casts
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 inself.properties.bands
. If the alpha band is requested, it must be last in the list to reduce rasterization errors. - ctx (
GeoContext
) – AGeoContext
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 or str or None, default None) – Whether to mask pixels in all bands where the alpha band of the scene is 0.
Provide a string to use an alternate band name for masking.
If the alpha band is available and
mask_alpha
is None,mask_alpha
is set to True. If not, mask_alpha is set to False. - 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 depend on the product and bands in use. Legacy products support
toa
(top of atmosphere) and in some casessurface
. Consult the availableprocessing_levels
in the product bands to understand what is available. - scaling (None, str, list, dict) – Band scaling specification. Please see
scaling_parameters()
for a full description of this parameter. - data_type (None, str) – Output data type. Please see
scaling_parameters()
for a full description of this parameter. - progress (None, bool) – Controls display of a progress bar.
- 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. Ifmask_nodata
ormask_alpha
is True, arr will be a masked array. The data type (“dtype”) of the array is the most general of the data types among the bands being rastered. - 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.assign(resolution=120.)) >>> type(arr) <class 'numpy.ma.core.MaskedArray'> >>> arr.shape (3, 1995, 1962) >>> 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 incompatible 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
-
scaling_parameters
(bands, processing_level=None, scaling=None, data_type=None)[source]¶ Computes fully defaulted scaling parameters and output data_type from provided specifications.
This method makes accessible the scales and data_type parameters which will be generated and passed to the Raster API by methods such as
ndarray()
anddownload()
. It is provided as a convenience to the user to aid in understanding how thescaling
anddata_type
parameters will be handled by those methods. It would not usually be used in a normal workflow.Parameters: - bands (list) – List of bands to be scaled.
- processing_level (str, optional) – How the processing level of the underlying data should be adjusted. Possible
values depend on the product and bands in use. Legacy products support
toa
(top of atmosphere) and in some casessurface
. Consult the availableprocessing_levels
in the product bands to understand what is available. - scaling (None or str or list or dict, default None) – Supplied scaling specification, see below.
- data_type (None or str, default None) – Result data type desired, as a standard data type string (e.g.
"Byte"
,"Uint16"
, or"Float64"
). If not specified, will be deduced from thescaling
specification. Typically this is left unset and the appropriate type will be determined automatically.
Returns: - scales (list(tuple)) – The fully specified scaling parameter, compatible with the
Raster
API and the output data type. - data_type (str) – The result data type as a standard GDAL type string.
Raises: ValueError – If any invalid or incompatible value is passed to any of the three parameters.
Scaling is determined on a band-by-band basis, incorporating the user provided specification, the output data_type, and properties for the band, such as the band type, the band data type, and the
default_range
,data_range
, andphysical_range
properties. Ultimately the scaling for each band will be resolved to eitherNone
or a tuple of numeric values of length 0, 2, or 4, as accepted by the Raster API. The result is a list (with length equal to the number of bands) of one of these values, or may be a None value which is just a shorthand equivalent for a list of None values.A
None
indicates that no scaling should be performed.A 0-tuple
()
indicates that the band data should be automatically scaled from the minimum and maximum values present in the image data to the display range 0-255.A 2-tuple
(input-min, input-max)
indicates that the band data should be scaled from the specified input range to the display range of 0-255.A 4-tuple
(input-min, input-max, output-min, output-max)
indicates that the band data should be scaled from the input range to the output range.In all cases, the scaling will be performed as a multiply and add, and the resulting values are only clipped as necessary to fit in the output data type. As such, if the input and output ranges are the same, it is effectively a no-op equivalent to
None
.The support for scaling parameters in the
Scenes
API includes the concept of an automated scaling mode. The four supported modes are as follows."raw"
:- Equivalent to a
None
, the data should not be scaled. "auto"
:- Equivalent to a 0-tuple, the data should be scaled by the Raster service so that the actual range of data in the input is scaled up to the full display range (0-255). It is not possible to determine the bounds of this input range in the Scenes API as the actual band data is not accessible.
"display"
:- The data should be scaled from any specified input bounds,
defaulting to the
default_range
property for the band, to the output range, defaulting to 0-255. "physical"
:- The data should be scaled from the input range, defaulting
to the
data_range
property for the band, to the output range, defaulting to thephysical_range
property for the band.
The mode may be explicitly specified, or it may be determined implicitly from other characteristics such as the length and contents of the tuples for each band, or from the output data_type if this is explicitly specified (e.g.
"Byte"
implies display mode,"Float64"
implies physical mode).If it is not possible to infer the mode, and a mode is required in order to fully determine the results of this method, an error will be raised. It is also an error to explicitly specify more than one mode, with several exceptions: auto and display mode are compatible, while a raw display mode for a band which is of type “mask” or type “class” does not conflict with any other mode specification.
Normally the
data_type
parameter is not provided by the user, and is instead determined from the mode as follows."raw"
:- The data type that best matches the data types of all the bands, preserving the precision and range of the original data.
"auto"
and"display"
:"Byte"
"physical"
:"Float64"
The
scaling
parameter passed to this method can be any of the following:- None:
- No scaling for all bands. Equivalent to
[None, ...]
. - str:
- Any of the four supported automatic modes as described above.
- list or Iterable:
- A list or similar iterable must contain a number of
elements equal to the number of bands specified. Each
element must either be a None, a 0-, 2-, or 4-tuple, or
one of the above four automatic mode strings. The
elements of each tuple must either be a numeric value
or a string containing a valid numerical string followed
by a “%” character. The latter will be interpreted as a
percentage of the appropriate range (e.g.
default_range
,data_range
, orphysical_range
) according to the mode. For example, a tuple of("25%", "75%")
with adefault_range
of[0, 4000]
will yield(1000, 3000)
. - dict or Mapping:
- A dictionary or similar mapping with keys corresponding to
band names and values as accepted as elements for each band
as with a list described above. Each band name is used to
lookup a value in the mapping. If none is found, and the
band is not of type “mask” or “class”, then the special
key
"default_"
is looked up in the mapping if it exists. Otherwise a value ofNone
will be used for the band. This is strictly a convenience for constructing a list of scale values, one for each band, but can be useful if a single general-purpose mapping is defined for all possible or relevant bands and then reused across many calls to the different methods in the Scenes API which accept ascaling
parameter.
See also
Scenes Guide : This contains many examples of the use of the
scaling
anddata_type
parameters.
-