Types

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

---

class AggregateDateField(value)

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 AuthCatalogObject(*args, **kwargs)

A base class for all representations of objects in the Descartes Labs catalog that support ACLs.

Note

The readers and writers IDs must be prefixed with email:, user:, group: or org:. The owners IDs must be prefixed with org: or user:. Using org: as an owner will assign those privileges only to administrators for that organization; using org: as a reader or writer assigns those privileges to everyone in that organization. The readers and writers attributes are only visible in full to an owner. If you are a reader or a writer those attributes will only display the elements of those lists by which you are gaining read or write access.

Any user with owner privileges is able to read the object attributes and data, modify the object attributes, and delete the object, including reading and modifying the owners, writers, and readers attributes.

Any user with writer privileges is able to read the object attributes and data, modify the object attributes except for owners, writers, and readers. A writer cannot delete the object. A writer can read the owners attribute but can only read the elements of writers and readers by which they gain access to the object.

Any user with reader privileges is able to read the objects attributes and data. A reader can read the owners attribute but can only read the elements of writers and readers by which they gain access to the object.

Also see Sharing Resources.

user_can_read(auth=None)

Check if the authenticated user is an owner, a writer, or a reader and has permissions to read this object.

Note it is kind of silly to call this method unless a non-default auth object is provided, because the default authorized user must have read permission in order to even retrieve this object.

Parameters:

auth (Auth, optional) – The auth object to use for the check. If not provided, the default auth object will be used.

Returns:

True if the user can read the object, False otherwise.

Return type:

bool

user_can_write(auth=None)

Check if the authenticated user is an owner or a writer and has permissions to modify this object.

Parameters:

auth (Auth, optional) – The auth object to use for the check. If not provided, the default auth object will be used.

Returns:

True if the user can modify the object, False otherwise.

Return type:

bool

user_is_owner(auth=None)

Check if the authenticated user is an owner, and can perform actions such as changing ACLs or deleting this object.

Parameters:

auth (Auth, optional) – The auth object to use for the check. If not provided, the default auth object will be used.

Returns:

True if the user is an owner of the object, False otherwise.

Return type:

bool

created

The point in time this object was created.

Filterable, sortable.

Type:

datetime, readonly

extra_properties

A dictionary of up to 50 key/value pairs.

The keys of this dictionary must be strings, and the values of this dictionary can be strings or numbers. This allows for more structured custom metadata to be associated with objects.

Type:

dict, optional

id

A unique identifier for this object.

Note that if you pass a string that does not begin with your Descartes Labs user organization ID, it will be prepended to your id with a : as separator. If you are not part of an organization, your user ID is used. Once set, it cannot be changed.

Type:

str, immutable

modified

The point in time this object was last modified.

Filterable, sortable.

Type:

datetime, readonly

owners

User, group, or organization IDs that own this object.

Defaults to [user:current_user, org:current_org]. The owner can edit, delete, and change access to this object. See this note.

Filterable.

Type:

list(str), optional

readers

User, email, group, or organization IDs that can read this object.

Will be empty by default. This attribute is only available in full to the owners of the object. See this note.

Type:

list(str), optional

tags

A list of up to 32 tags, each up to 1000 bytes long.

The tags may support the classification and custom filtering of objects.

Filterable.

Type:

list, optional

writers

User, group, or organization IDs that can edit this object.

Writers will also have read permission. Writers will be empty by default. See note below. This attribute is only available in full to the owners of the object. See this note.

Type:

list(str), optional

class BandType(value)

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 CatalogObject(*args, **kwargs)

A base class for all representations of objects in the Descartes Labs catalog.

class Colormap(value)

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 DataType(value)

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 DerivedParamsAttribute(**kwargs)

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 DocumentState(value)

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 EventConnectionParameter(**kwargs)

Parameter value for a connection.

Key

The key for this parameter.

Type:

str

Value

The value for this parameter.

Type:

str

IsValueSecret

True if the value should be stored as a secret.

Type:

bool

class EventRuleTarget(**kwargs)

Target for an EventRule.

name

The name of this event target.

Type:

str

arn

The ARN of the event target. For example, the ARN of the API Destination.

Type:

str

role_arn

The ARN of the role to assume when invoking the target.

Type:

str, optional

input

The input to the target.

Type:

str, optional

input_path

The path into the event to be mapped to the input to the target.

Type:

str, optional

input_paths_map

Dictionary mapping named substition variables for the input template to their path in the event.

Type:

dict, optional

input_template

The template for the input to the target. Substitutions are defined by the input_paths_map. See the AWS EventBridge documentation for more information.

Type:

str, optional

ttl

The time to live for the target.

Type:

int, optional

retries

The number of times to retry the target.

Type:

int, optional

dead_letter_arn

The ARN of the dead letter queue for the target.

Type:

str, optional

path_parameter_values

The path parameter values for the target URL.

Type:

list(str), optional

header_parameters

Dictionary of headers and values to be sent to the target.

Type:

dict, optional

query_string_parameters

Dictionary of query parameters and values to be sent to the target.

Type:

dict, optional

event_api_destination_id

The id of the EventApiDestination for the target.

Type:

str

Note that `input`, `input_path`, and `input_template` are mutually exclusive, and `input_paths_map`

may only be used together with `input_template`.

class EventSubscriptionComputeTarget(_: str, *args, **kwargs)

An EventSubscriptionTarget tailored for a compute function.

Supports the use of placeholders in the detail template to be substituted from the matching event and subscription.

Create an EventSubscriptionTarget tailored for a compute function.

Placeholder values can be used for any parameter value, which allows for passing through Jinja2 template substitutions into the resulting detail template which are otherwise not themselves JSON serializable.

Parameters:

• _ (str) – The compute function id to be invoked.

• args (Any, optional) – Positional arguments to pass to the compute function.

• kwargs (Any, optional) – Keyword arguments to pass to the compute function. This includes the special parameters tags and environment as used by the compute function.

class EventSubscriptionSqsTarget(_: str, *args, **kwargs)

An EventSubscriptionTarget tailored for an SQS queue.

Supports the use of placeholders in the detail template to be substituted from the matching event and subscription.

Create an EventSubscriptionTarget tailored for an SQS queue.

Placeholder values can be used for any parameter value, which allows for passing through Jinja2 template substitutions into the resulting detail template which are otherwise not themselves JSON serializable.

If no positional or keyword arguments are provided, then the message defaults to being the event detail.

Parameters:

• _ (str) – The SQS queue URL.

• args (Placeholder or mapping type, optional) – At most one positional argument which is either a Placeholder object which will be rendered as a JSON object, or a mapping type which will yield the same. If a value is provided, then no kwargs are permitted.

• kwargs (Any, optional) – Keyword parameters to pass in the message to the SQS queue. They may include placeholders for Jinja2 templating.

class EventSubscriptionTarget(**kwargs)

Target for an EventSubscription.

rule_id

The id of the EventRule for the target.

Type:

str

detail_template

A Jinja2 template for the detail JSON for the target event. If not provided, the detail will be the same as the event which the subscription matches. The context for rendering the template will include the event object and the subscription to which this target belongs. Note that this template must render to a valid JSON string: no trailing commas anywhere.

Type:

str, optional

class EventType(value)

The event type for a subscription.

Also refered to as the detail type for an event.

NEW_IMAGE

A new image that has been uploaded to the Catalog.

Type:

enum

UPDATE_IMAGE

An existing image in the Catalog has been updated.

Type:

enum

NEW_STORAGE

A new storage blob that has been uploaded to the Catalog.

Type:

enum

UPDATE_STORAGE

An existing blob in the Catalog has been updated.

Type:

enum

NEW_VECTOR

A new vector feature that has been uploaded to the Vector service.

Type:

enum

UPDATE_VECTOR

An existing vector feature in the Vector service has been updated.

Type:

enum

SCHEDULED

A scheduled event.

Type:

enum

COMPUTE_FUNCTION_COMPLETED

A compute function has completed all jobs.

Type:

enum

class File(**kwargs)

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 ImageUploadEvent(**kwargs)

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 ImageUploadEventSeverity(value)

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

class ImageUploadEventType(value)

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 ImageUploadOptions(**kwargs)

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 ImageUploadStatus(value)

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 ImageUploadType(value)

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 Interval(value)

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 OverviewResampler(value)

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 Placeholder(text: str, unquoted=False, raw=False)

Placeholder class for EventSubscriptionComputeTarget.

Can be used in an EventSubscriptionComputeTarget for any value element, as a mechanism to pass Jinja2 template substitutions through to the resulting detail template.

Create a Placeholder object.

By default when unquoted and raw are both False, the text will be rendered as a string value with the text substituted from the event context. For example, Placeholder("event.detail.id") will render as "some-id".

If unquoted is True, the text will be rendered without enclosing quotes (typically for a numeric value, JSON object or array). For example, Placeholder("event.detail.geometry", unquoted=True) will render as {"type": "Polygon", "coordinates": [[[0, 0,], [1, 0], [1, 1], [0, 1], [0, 0]]]}.

If raw is True, then the text will be rendered by Jinja2 as is, without introducing any additional quotes or substitutions. Generally this is used when you must explicitly pass through a Jinja2 template expression with substitutions.

In all cases, the final result after all substitions must be a fragment of a valid JSON string.

Parameters:

• text (str) – The text to be rendered into the resulting JSON detail template. How it is handled depends on the unquoted and raw parameters.

• unquoted (bool, optional) – If False, the text will be rendered as a string value. If False, then the text will be rendered without enclosing quotes. Defaults to False. Ignored if raw is True.

• raw (bool, optional) – If True, the text will be rendered as is, without wrapping as a substitution or a string. Defaults to False.

class ProcessingStepAttribute(**kwargs)

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)

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 Resolution(values=None, **kwargs)

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)

Valid units of measure for Resolution.

METERS

The resolution in meters.

Type:

enum

DEGREES

The resolution in degrees.

Type:

enum

class StorageState(value)

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 TaskState(value)

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