Bands¶

Classes

descarteslabs.catalog.Band

descarteslabs.catalog.SpectralBand

descarteslabs.catalog.MicrowaveBand

descarteslabs.catalog.MaskBand

descarteslabs.catalog.ClassBand

descarteslabs.catalog.GenericBand

descarteslabs.catalog.DerivedBand

Data Types

class Band(**kwargs)[source]¶

A data band in images of a specific product.

This is an abstract class that cannot be instantiated, but can be used for searching across all types of bands. The concrete bands are represented by the derived classes. To create a new band instantiate one of those specialized classes:

SpectralBand: A band that lies somewhere on the visible/NIR/SWIR electro-optical wavelength spectrum. Specific attributes: wavelength_nm_center, wavelength_nm_min, wavelength_nm_max, wavelength_nm_fwhm
MicrowaveBand: A band that lies in the microwave spectrum, often from SAR or passive radar sensors. Specific attributes: frequency, bandwidth
MaskBand: A binary band where by convention a 0 means masked and 1 means non-masked. The data_range and display_range for masks is implicitly [0, 1]. Specific attributes:is_alpha
ClassBand: A band that maps a finite set of values that may not be continuous to classification categories (e.g. a land use classification). A visualization with straight pixel values is typically not useful, so commonly a colormap is used. Specific attributes: colormap, colormap_name, class_labels
GenericBand: A generic type for bands that are not represented by the other band types, e.g., mapping physical values like temperature or angles. Specific attributes: colormap, colormap_name, physical_range, physical_range_unit

Methods

search([client])

A search query for all bands.

Parameters: kwargs (dict) – With the exception of readonly attributes (created, modified), any (inherited) attribute listed below can also be used as a keyword argument.

Inheritance

For inherited parameters, methods, attributes, and properties, please refer to the base classes:

The attributes documented below are shared by all band objects, namely SpectralBand, MicrowaveBand, MaskBand, ClassBand, and GenericBand.

description¶

A description with further details on the band

Type: str

type¶

The type of this band, directly corresponding to a Band subclass (SpectralBand, MicrowaveBand, MaskBand, ClassBand, GenericBand). Never needs to be set explicitly, this attribute is implied by the subclass used. The type of a band does not necessarily affect how it is rastered, it mainly conveys useful information about the data it contains. Filterable.

Type: str, BandType

sort_order¶

A number defining the default sort order for bands within a product. If not set for newly created bands, this will default to the current maximum sort order + 1 in the product. Sortable.

Type: int

data_type¶

Required: The data type for pixel values in this band

Type: DataType

nodata¶

A value representing missing data in a pixel in this band

Type: float

data_range¶

Required: The minimum and maximum pixel values stored in this band

Type: tuple(float, float)

display_range¶

Required: A reasonable default range of pixel values when rastering this band for display purposes

Type: tuple(float, float)

resolution¶

The spatial resolution of this band. Filterable, sortable.

Type: Resolution

band_index¶

Required: The 0-based index into the source data to access this band

Type: int

file_index¶

The 0-based index into the list of source files, if there are multiple ones. Defaults to 0 (first file).

Type: int

jpx_layer_index¶

The 0-based layer index if the source data is JPEG2000 with layers. Defaults to 0.

Type: int

classmethod search(client=None)[source]¶

A search query for all bands.

Returns an instance of the Search class configured for searching bands. Call this on the Band base class to search all types of bands or classes SpectralBand, MicrowaveBand, MaskBand, ClassBand and GenericBand to search only a specific type of band.

Parameters: client (CatalogClient) – A CatalogClient instance to use for requests to the Descartes Labs catalog.
Returns: An instance of the Search class
Return type: Search

class SpectralBand(**kwargs)[source]¶

A band that lies somewhere on the visible/NIR/SWIR electro-optical wavelength spectrum.

Parameters: kwargs (dict) – With the exception of readonly attributes (created, modified), any (inherited) attribute listed below can also be used as a keyword argument.

Inheritance

For inherited parameters, methods, attributes, and properties, please refer to the base classes:

wavelength_nm_center¶

Weighted center of min/max responsiveness of the band, in nm. Filterable, sortable.

Type: float

wavelength_nm_min¶

Minimum wavelength this band is sensitive to, in nm. Filterable, sortable.

Type: float

wavelength_nm_max¶

Maximum wavelength this band is sensitive to, in nm. Filterable, sortable.

Type: float

wavelength_nm_fwhm¶

Full width at half maximum value of the wavelength spread, in nm. Filterable, sortable.

Type: float

class MicrowaveBand(**kwargs)[source]¶

A band that lies in the microwave spectrum, often from SAR or passive radar sensors.

Parameters: kwargs (dict) – With the exception of readonly attributes (created, modified), any (inherited) attribute listed below can also be used as a keyword argument.

Inheritance

For inherited parameters, methods, attributes, and properties, please refer to the base classes:

frequency¶

Center frequency of the observed microwave in GHz. Filterable, sortable.

Type: float

bandwidth¶

Chirp bandwidth of the sensor in MHz. Filterable, sortable.

Type: float

class MaskBand(**kwargs)[source]¶

A binary band where by convention a 0 means masked and 1 means non-masked.

The data_range and display_range for masks is implicitly (0, 1).

Parameters: kwargs (dict) – With the exception of readonly attributes (created, modified), and the computed attributes (data_range, display_range) any (inherited) attribute listed below can also be used as a keyword argument.

Inheritance

For inherited parameters, methods, attributes, and properties, please refer to the base classes:

is_alpha¶

Whether this band should be useable as an alpha band during rastering. This enables special behavior for this band during rastering. If this is True and the band appears as the last band in a raster operation (such as descarteslabs.scenes.scenecollection.SceneCollection.mosaic() or descarteslabs.scenes.scenecollection.SceneCollection.stack()) pixels with a value of 0 in this band will be treated as transparent.

Type: bool

data_range¶

Readonly: [0, 1].

Type: tuple(float, float)

display_range¶

Readonly: [0, 1].

Type: tuple(float, float)

class ClassBand(**kwargs)[source]¶

A band that maps a finite set of values that may not be continuous.

For example land use classification. A visualization with straight pixel values is typically not useful, so commonly a colormap is used.

Parameters: kwargs (dict) – With the exception of readonly attributes (created, modified), any (inherited) attribute listed below can also be used as a keyword argument.

Inheritance

For inherited parameters, methods, attributes, and properties, please refer to the base classes:

colormap_name¶

Name of a predefined colormap for display purposes. The colormap is applied when this band is rastered by itself in PNG or TIFF format, including in UIs where imagery is visualized.

Type: str, Colormap

colormap¶

A custom colormap for this band. A list of lists, where each nested list is a 4-tuple of RGBA values to map pixels whose value is the index of the tuple. E.g. the colormap [[100, 20, 200, 255]] would map pixels whose value is 0 in the original band to the RGBA color defined by [100, 20, 200, 255]. The number of 4-tuples provided can be up to the maximum of this band’s data range. Omitted values will map to black by default.

Type: list(tuple)

class_labels¶

A list of labels where each element is a name for the class with the value at that index. Elements can be null if there is no label at that value.

Type: list(str or None)

class GenericBand(**kwargs)[source]¶

A generic kind of band not fitting any other type.

For example mapping physical values like temperature or angles.

Parameters: kwargs (dict) – With the exception of readonly attributes (created, modified), any (inherited) attribute listed below can also be used as a keyword argument.

Inheritance

For inherited parameters, methods, attributes, and properties, please refer to the base classes:

physical_range¶

A physical range that pixel values map to

Type: tuple(float, float)

physical_range_unit¶

Unit of the physical range

Type: str

colormap_name¶

Name of a predefined colormap for display purposes. The colormap is applied when this band is rastered by itself in PNG or TIFF format, including in UIs where imagery is visualized.

Type: str, Colormap

colormap¶

A custom colormap for this band. A list of lists, where each nested list is a 4-tuple of RGBA values to map pixels whose value is the index of the tuple. E.g. the colormap [[100, 20, 200, 255]] would map pixels whose value is 0 in the original band to the RGBA color defined by [100, 20, 200, 255]. The number of 4-tuples provided can be up to the maximum of this band’s data range. Omitted values will map to black by default.

Type: list(tuple)

class DerivedBand(**kwargs)[source]¶

A type of band that is the result of a pixel function applied to one or more existing bands. This object type only supports read operations; they cannot be created, updated, or deleted using this client.

Parameters: kwargs (dict) – This is a readonly object.

Methods

`delete`(id[, client, ignore_missing])	You cannot delete a derived band.
`save`()	You cannot save a derived band.

Inheritance

For inherited parameters, methods, attributes, and properties, please refer to the base class:

descarteslabs.catalog.CatalogObject

name¶

Required, immutable: The name of the derived band, globally unique. Filterable, sortable.

Type: str

description¶

Immutable: A description with further details on the derived band

Type: str

data_type¶

Required, immutable: The data type for pixel values in this derived band

Type: str

data_range¶

Required, immutable: The minimum and maximum pixel values stored in this derived band

Type: tuple(float, float)

physical_range¶

Immutable: A physical range that pixel values map to

Type: tuple(float, float)

bands¶

Required, immutable: List of bands used in the derived band pixel function Filterable

Type: list(str)

function_name¶

Required, immutable: Name of the function applied to create this derived band

Type: str

delete(ignore_missing=False)[source]¶

You cannot delete a derived band.

Raises: NotImplementedError – This method is not supported for DerivedBands.

classmethod delete(id, client=None, ignore_missing=False)[source]

You cannot delete a derived band.

Raises: NotImplementedError – This method is not supported for DerivedBands.

save()[source]¶

You cannot save a derived band.

Raises: NotImplementedError – This method is not supported for DerivedBands.

class DataType[source]¶

Valid data types for bands.

BYTE¶

An 8 bit unsigned integer value.

Type: enum

UINT16¶

A 16 bit unsigned integer value.

Type: enum

INT16¶

A 16 bit signed integer value.

Type: enum

UINT32¶

A 32 bit unsigned integer value.

Type: enum

INT32¶

A 32 bit signed integer value.

Type: enum

FLOAT32¶

A 32 bit single-precision floating-point format value.

Type: enum

FLOAT64¶

A 64 bit double-precision floating-point format value.

Type: enum

class BandType[source]¶

Types of bands with different data interpretation.

The type of band is represented in the specific Band class being used and is only for informative purposes.

CLASS¶

A band that maps a finite set of values that may not be continuous.

Type: enum

SPECTRAL¶

A band that lies somewhere on the visible/NIR/SWIR electro-optical wavelength spectrum.

Type: enum

MASK¶

A binary band where by convention a 0 means masked and 1 means non-masked.

Type: enum

MICROWAVE¶

A band that lies in the microwave spectrum, often from SAR or passive radar sensors.

Type: enum

GENERIC¶

An unspecified kind of band not fitting any other type.

Type: enum

class Colormap[source]¶

Predefined colormaps available to assign to bands.

Most of these colormaps correspond directly to the built-in colormaps of the same name in matplotlib. See https://matplotlib.org/3.1.0/tutorials/colors/colormaps.html for an overview and visual examples.

MAGMA¶

A perceptually uniform sequential colormap, equivalent to matplotlib’s built-in “magma”

Type: enum

INFERNO¶

A perceptually uniform sequential colormap, equivalent to matplotlib’s built-in “inferno”

Type: enum

PLASMA¶

A perceptually uniform sequential colormap, equivalent to matplotlib’s built-in “plasma”

Type: enum

VIRIDIS¶

A perceptually uniform sequential colormap, equivalent to matplotlib’s built-in “viridis”

Type: enum

COOL¶

A sequential colormap, equivalent to matplotlib’s built-in “cool”

Type: enum

HOT¶

A sequential colormap, equivalent to matplotlib’s built-in “hot”

Type: enum

COOLWARM¶

A diverging colormap, equivalent to matplotlib’s built-in “coolwarm”

Type: enum

BWR¶

A diverging colormap (blue-white-red), equivalent to matplotlib’s built-in “bwr”

Type: enum

GIST_EARTH¶

A colormap designed to represent topography and water depths together, equivalent to matplotlib’s built-in “gist_earth”

Type: enum

TERRAIN¶

A colormap designed to represent topography and water depths together, equivalent to matplotlib’s built-in “terrain”

Type: enum

CDL¶

A standard colormap used in Cropland Data Layer (CDL) products, with a distinct color for each class in such products

Type: enum

class Resolution(**kwargs)[source]¶

A spatial pixel resolution with a unit. For example, Resolution(value=60, unit=ResolutionUnit.METERS) represents a resolution of 60 meters per pixel.

Objects with resolution values can be filtered by a unitless number in which case the value is always in meters. For example, retrieving all bands with a resolution of 60 meters per pixel:

>>> Band.search().filter(p.resolution == 60)

value¶

Required: The value of the resolution.

Type: float

unit¶

Required: The unit the resolution is measured in.

Type: str

class ResolutionUnit[source]¶

Valid units of measure for Resolution.

METERS¶

The resolution in meters.

Type: enum

DEGREES¶

The resolution in degrees.

Type: enum