Types

`CatalogObject`	A base class for all representations of objects in the Descartes Labs catalog.
`DocumentState`	The state of the catalog object.
`TaskState`	The state of a task.
`DataType`	Valid data types for bands.
`BandType`	Types of bands with different data interpretation.
`Colormap`	Predefined colormaps available to assign to bands.
`ProcessingStepAttribute`	Processing Levels Step.
`ProcessingLevelsAttribute`	An attribute that contains properties (key/value pairs).
`DerivedParamsAttribute`	Derived Band Parameters Attribute.
`Resolution`	A spatial pixel resolution with a unit.
`ResolutionUnit`	Valid units of measure for Resolution.
`File`	File definition for an Image.
`StorageState`	The storage state for an image or blob.
`AggregateDateField`	A date field to use for aggragation for the `ImageSearch.summary_interval()` method.
`Interval`	An interval for the `ImageSearch.summary_interval()` method.
`ImageUploadOptions`	Control of the upload process.
`ImageUploadType`	The type of upload data.
`OverviewResampler`	Allowed overview resampler algorithms.
`ImageUploadStatus`	The status of the image upload operation.
`ImageUploadEvent`	Image upload event data.

class CatalogObject(*args, **kwargs)[source]

A base class for all representations of objects in the Descartes Labs catalog. .. method:: delete()

Delete this catalog object from the Descartes Labs catalog.

Once deleted, you cannot use the catalog object and should release any references.

raises DeletedObjectError:

If this catalog object was already deleted.

raises UnsavedObjectError:

If this catalog object is being deleted without having been saved.

raises ~descarteslabs.exceptions.ClientError or ~descarteslabs.exceptions.ServerError:

Spurious exception that can occur during a network request.

class DocumentState(value)[source]

The state of the catalog object.

UNSAVED

The catalog object was never synchronized with the Descartes Labs catalog. All values are considered modified and saving the catalog object will create the corresponding object in the Descartes Labs catalog.

Type:: enum

MODIFIED

The catalog object was synchronized with the Descartes Labs catalog (using get() or save()), but at least one attribute value has since been changed. You can save() a modified catalog object to update the object in the Descartes Labs catalog.

Note that assigning an identical value does not change the state.

Type:: enum

SAVED

The catalog object has been fully synchronized with the Descartes Labs catalog (using get() or save()).

Type:: enum

DELETED

The catalog object has been deleted from the Descartes Labs catalog. Many operations cannot be performed on DELETED objects.

Type:: enum

Note

A SAVED catalog object can still be out-of-date with respect to the Descartes Labs catalog if there was an update from another client since the last sycnronization. To re-synchronize a SAVED catalog object you can use reload().

class TaskState(value)[source]

The state of a task.

NEVERRAN

The operation was never invoked.

Type:: enum

RUNNING

The operation is in progress.

Type:: enum

SUCCEEDED

The operation was successfully completed.

Type:: enum

FAILED

The operation resulted in a failure and may not have been completed.

Type:: enum

class DataType(value)[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(value)[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(value)[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 ProcessingStepAttribute(**kwargs)[source]

Processing Levels Step.

function

Name of the processing function to apply. Required.

Type:: str

parameter

Name of the parameter in the image metadata containing the coefficients for the processing function. Required.

Type:: str

index

Optional index into the named parameter (an array) for the band.

Type:: int

data_type

Optional data type for pixel values in this band.

Type:: str or DataType

data_range

Optional normal range of pixel values stored in the band.

Type:: tuple(float, float)

display_range

Optional normal range of pixel values stored in the band for display purposes.

Type:: tuple(float, float)

physical_range

Optional normal range of physical values stored in the band.

Type:: tuple(float, float)

physical_range_unit

Optional unit of the physical range.

Type:: str

class ProcessingLevelsAttribute(value=None, validate=True, **kwargs)[source]

An attribute that contains properties (key/value pairs).

Can be set using a dictionary of items or any Mapping, or an instance of this attribute. All keys must be string and values can be string or an iterable of ProcessingStepAttribute items (or compatible mapping). ProcessingLevelsAttribute behaves similar to dictionaries.

class DerivedParamsAttribute(**kwargs)[source]

Derived Band Parameters Attribute.

function

Name of the function to apply. Required.

Type:: str

bands

Names of the bands used as input to the function. Required.

Type:: list(str)

source_type

Optional index into the named parameter (an array) for the band.

Type:: int

class Resolution(values=None, **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. You can also use a string with a value and unit, for example 60m or 1.2 deg.. The available unit designations are:

m, meter, meters, metre, metres
°, deg, degree, degrees

Spaces between the value and unit are optional, as is a trailing period.

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) 

Parameters:

values (Mapping or str) – A mapping that either contains the value and unit key/value pairs, or is a string that can be parsed to a value and a unit.
**kwargs (optional) – See Attribute.

value

The value of the resolution.

Type:: float

unit

The unit the resolution is measured in.

Type:: str or ResolutionUnit

class ResolutionUnit(value)[source]

Valid units of measure for Resolution.

METERS

The resolution in meters.

Type:: enum

DEGREES

The resolution in degrees.

Type:: enum

class File(**kwargs)[source]

File definition for an Image.

href

If the StorageState is AVAILABLE, this field is required and it must be a valid reference to either a JP2 or a GeoTiff file using the gs scheme. If the StorageState is REMOTE, this field is optional and you can use one of the schemes gs, http, https, ftp, or ftps; if the scheme is gs, it must be a valid reference but can be any format.

Type:: str

size_bytes

Size of the file in bytes. Required when the StorageState is AVAILABLE.

Type:: int

hash

The md5 hash for the given file. Required when the StorageState is AVAILABLE.

Type:: str

provider_id

Optional ID for the external provider when the StorageState is REMOTE.

Type:: str

provider_href

A URI to describe the remote image in more detail. Either the provider_href or the href must be specified when the StorageState is REMOTE.

Type:: str

class StorageState(value)[source]

The storage state for an image or blob.

AVAILABLE

The data has been uploaded and can be retrieved or rastered.

Type:: enum

REMOTE

The data is has not been uploaded, but its location is known.

Type:: enum

class AggregateDateField(value)[source]

A date field to use for aggragation for the ImageSearch.summary_interval() method.

ACQUIRED

Aggregate on the Image.acquired field.

Type:: enum

CREATED

Aggregate on the Image.created field.

Type:: enum

MODIFIED

Aggregate on the Image.modified field.

Type:: enum

PUBLISHED

Aggregate on the Image.published field.

Type:: enum

class Interval(value)[source]

An interval for the ImageSearch.summary_interval() method.

YEAR

Aggregate on a yearly basis

Type:: enum

QUARTER

Aggregate on a quarterly basis

Type:: enum

MONTH

Aggregate on a monthly basis

Type:: enum

WEEK

Aggregate on a weekly basis

Type:: enum

DAY

Aggregate on a daily basis

Type:: enum

HOUR

Aggregate on a hourly basis

Type:: enum

MINUTE

Aggregate per minute

Type:: enum

class ImageUploadOptions(**kwargs)[source]

Control of the upload process.

upload_type

Type of upload job, see ImageUploadType.

Type:: str or ImageUploadType

image_files

File basenames of the uploaded files.

Type:: list(str)

overviews

Overview generation control, only used when upload_type is ImageUploadType.NDARRAY.

Type:: list(int)

overview_resampler

Overview resampler method, only used when upload_type is ImageUploadType.NDARRAY.

Type:: str or OverviewResampler

upload_size

When upload_type is ImageUploadType.NDARRAY, the total size of the array in bytes.

Type:: int

class ImageUploadType(value)[source]

The type of upload data.

NDARRAY

An multidimensional, homogeneous array of fixed-size items representing one or more images.

Type:: enum

FILE

A file on disk containing one or more images.

Type:: enum

class OverviewResampler(value)[source]

Allowed overview resampler algorithms.

NEAREST

Applies a nearest neighbour (simple sampling) resampler

Type:: enum

AVERAGE

Computes the average of all non-NODATA contributing pixels.

Type:: enum

GAUSS

Applies a Gaussian kernel before computing the overview, which can lead to better results than simple averaging in e.g case of sharp edges with high contrast or noisy patterns.

Type:: enum

CUBIC

Applies a cubic convolution kernel.

Type:: enum

CUBICSPLINE

Applies a B-Spline convolution kernel.

Type:: enum

LANCZOS

Applies a Lanczos windowed sinc convolution kernel.

Type:: enum

AVERAGE_MP

Averages complex data in mag/phase space.

Type:: enum

AVERAGE_MAGPHASE

average_magphase

Type:: enum

MODE

Selects the value which appears most often of all the sampled points.

Type:: enum

class ImageUploadStatus(value)[source]

The status of the image upload operation.

TRANSFERRING

Upload has been initiated and file(s) are being transfered from the client to the platform.

Type:: enum

PENDING

The files were transfered to the platform, and are waiting for processing to begin.

Type:: enum

RUNNING

The processing step is currently running.

Type:: enum

SUCCESS

The upload processing completed successfully and the new image is available.

Type:: enum

FAILURE

The upload failed; error information is available.

Type:: enum

CANCELED

The upload was canceled by the user prior to completion.

Type:: enum

class ImageUploadEvent(**kwargs)[source]

Image upload event data.

During the sequence of steps in the life-cycle of an upload, events are recorded at each change in upload status and as responsibility for the upload passes between different subsystems (referred to here as “components”). While the ImageUpload object provides the current status of the upload and the time at which that status was reached, the events associated with an upload record the circumstances for each of the changes in the upload status as they occurred.

A typical upload, once complete, will have four events with the following event_type:

ImageUploadEventType.QUEUE
ImageUploadEventType.RUN
ImageUploadEventType.USAGE
ImageUploadEventType.COMPLETE

component

The component which generated the event.

The value of this field depends on the internal details of how images are uploaded, but is useful to support personnel for understanding where a failure may have occurred.

Type:: str

component_id

The unique identifier for the component instance which generated the event.

This identifier is useful to support personnel for tracking down any errors which may have occurred.

Type:: str

event_datetime

The time at which the event occurred.

Type:: datetime

event_type

The type of the event.

Type:: ImageUploadEventType

id

Unique id for the event.

Type:: str

message

Any message associated with the event.

Type:: str

severity

The severity of the event.

Type:: ImageUploadEventSeverity

class ImageUploadEventType(value)[source]

The type of the image upload event.

QUEUE

The transfer of the file(s) was completed, and the upload processing request has been issued.

Type:: enum

CANCEL

The user has requested that the upload be canceled. If processing is already underway, it will continue.

Type:: enum

RUN

The processing step is starting.

Type:: enum

COMPLETE

All processing has completed. The upload status will reflect success, failure, or cancellation.

Type:: enum

ERROR

An error has been detected, but the operation may continue or be retried.

Type:: enum

TIMEOUT

The upload operation has timed out, and will be retried.

Type:: enum

LOG

The event contains logging output.

Type:: enum

USAGE

The event contains process resource usage information.

Type:: enum

class ImageUploadEventSeverity(value)[source]

The severity of an image upload event.

The severity values duplicate the standard python logging package level names and have the same meaning.

CRITICAL

Critical (error) event.

Type:: enum

ERROR

Error event.

Type:: enum

WARNING

Warning event.

Type:: enum

INFO

Informational event.

Type:: enum

DEBUG

Debug event.

Type:: enum